Difference between revisions of "Hardware And Software Setup"

VSCode - Workspace and Project(s)

Similar to other IDEs, Visual Studio Code is using the concept of a ‘workspace’. In simple words, a workspace is a collection of Folders open in the IDE. See workspaces for more details. In the most simple case a workspace just contains a folder which is the folder for the project. So all what we need is to add a folder.

Use menu File > Add Folder to Workspace …

Browse to an existing new (empty) folder or simply create one from the dialog:

Add a new file: main.c

Implement the main function, then save it (CTRL+S)

Sample Project

You can download sample project from here

References

• workspaces
• User and Workspace Settings

VSCode – Include Paths

This article will describe how to set up the Include Paths for C/C++ in Visual Studio Code to support ARM development. Visual Studio Code with the C/C++ plugin has many useful features while we are writing our code:

• syntax highlighting,
• error checking while we type, and
• automatic code completion, where it guesses while we type.

This can help us reduce errors and write faster. However, if the plugin is not correctly set up, these features will not work correctly or at all.

In order for Visual Studio Code and the C/C++ language plugin to understand our code, it needs to be able to find all of the header files referenced in our program. A header can further reference other headers, so they may be needed even if you didn’t explicitly call them yourself.

In main.c, VSCode is complaining that it cannot open tm4c123gh6pm.h' file'. The message is a little obscure, but it’s basically saying that it will interpret the file based on keywords and syntax, but can’t tell if things like function or variable names are correct.

So, how do we fix this? If the cursor is on the error, you will see the lightbulb to the left. Click that, and then Update “includePath” setting. VSCode will create and open a file called “c_cpp_properties.json”, in our project under a “.vscode” folder. By default this will contain configurations for Mac, Linux, and Win32. These include default includePaths suitable for desktop applications, but are not correct for ARM.

There are two sections with paths. The first, “includePath”, is where VSCode will look for headers for the purpose of checking our code. Unlike GCC, this is not recursive; we need to explicitly list each folder that contains headers that are referenced, directly or indirectly.

The second section with just “path” is used by IntelliSense to suggest things for us.

This is the initial c_cpp_properties.json file:

{
    "configurations": [
        {
            "name": "WIN32",
            "includePath": [
                "${workspaceFolder}/**",
                "E:\\ti\\TivaWare_C_Series-2.2.0.295"
            ],
            "defines": [
                "_DEBUG",
                "PART_TM4C123GH6PM"
            ],
            "compilerPath": "C:\\ProgramData\\chocolatey\\bin\\arm-none-eabi-gcc",
            "cStandard": "c99",
            "cppStandard": "gnu++17",
            "intelliSenseMode": "gcc-arm",
            "configurationProvider": "ms-vscode.cmake-tools"
        },
        {
            "name": "LINUX",
            "includePath": [
                "${workspaceFolder}/**",
                "/home/jshankar/ti/TivaWare_C_Series-2.2.0.295"
            ],
            "defines": [
                "_DEBUG",
                "PART_TM4C123GH6PM"
            ],
            "compilerPath": "/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc",
            "cStandard": "c99",
            "cppStandard": "gnu++17",
            "intelliSenseMode": "gcc-arm",
            "configurationProvider": "ms-vscode.cmake-tools"
        }        
    ],
    "version": 4
}

• name: arbitrary name for the configuration
• includePath: list here all locations where IntelliSense shall search for header files. It automatically will use the ones located in the toolchain (compiler) installation. The ‘**’ notation means it will search recursively that folder
• defines: list all the extra defines which shall be considered.
• forcedInclude: if using the -include compiler option, make sure you list that file here
• compilerPath: path to the compiler executable.
• cStandard and cppStandard: the C and C++ standard to be used
• intelliSenseMode: mode to be used. ‘gcc-arm’ is considered legacy, but not sure what to use otherwise for ARM?

But where is stdint.h? GCC has built-in include paths that are used even if compiler flags don’t specify them. GCC will list the defaults by running “arm-none-eabi-gcc -xc -E -v -“, and add those paths as well. Be sure to list all sub folders with headers for the includePath section.

References

• Customizing default settings
• IntelliSense for cross-compiling

VSCode – Defines

It is common to pass defines to the compiler using flags at compile time.

-D_DEBUG
-DPART_TM4C123GH6PM

Setting these for VSCode is simple: just add them to the “defines” section of c_cpp_properties.json, without the -D flag prefix:

    "defines": [
        "_DEBUG",
        "PART_TM4C123GH6PM"
    ],

If the include paths and defines are properly set up in Visual Studio Code, the C/C++ plugin should be able to properly parse our code, identify syntax errors, and will provide Intellisense code completion to improve the speed and accuracy of writing!

CMake: Configure

We are going to use CMake with Make to build the project. CMake needs some information where to find the tools. How does CMake know which compiler to use? It checks the CC and CXX environment variables. They define what is the default compiler in the system. If we manually set CC or CXX to different values, then CMake will use these new settings as default compilers. After successful detection, CMake stores info about the current toolchain in the following variables:

CMAKE_C_COMPILER,
CMAKE_CXX_COMPILER

They contain paths to the C and C++ compilers respectively.

When we cross-compile to another platform, we have to specify completely different toolchain both in terms of name and location of the binaries. This can be done in two ways:

1. pass values for the toolchain variables from the command line,
2. specify toolchain file.

First option is very explicit thus easy to understand, but big number of arguments makes it harder to use CMake in terminal:

cmake .. -DCMAKE_C_COMPILER=<path_to_c_compiler> -DCMAKE_CXX_COMPILER=<path_to_cxx_compiler> -DCMAKE_AR=<path_to_ar> -DCMAKE_LINKER=<path_to_linker> etc...

Second option is more elegant and is the preferred way of choosing the toolchain. All we need to do is to put toolchain variables into a separate file (e.g. <toolchain_name>.cmake) and set CMAKE_TOOLCHAIN_FILE variable to the path of that file. This can be done both in the command line or in CMakeLists.txt before project() command:

cmake .. -DCMAKE_TOOLCHAIN_FILE=<path_to_toolchain_file>

OR

cmake_minimum_required(VERSION 3.15)
set(CMAKE_TOOLCHAIN_FILE <path_to_toolchain_file>)
project(<project_name> LANGUAGES C CXX)

Note: It is crucial to set the value of CMAKE_TOOLCHAIN_FILE before project() is invoked, because project() triggers toolchain detection and verification.

A simple and easy way is to to add the following file to the project. I have named it arm-toolchain.cmake and placed it in the project root folder.

CMake: Toolchain File

ARM_TOOLCHAIN_DIR specifies the compiler to be used. Additionally it defines extra tools as size and objcopy.

CMake: CMakeLists.txt

To tell CMake what to do, create a file named CMakeList.txt in the project root.

The most important sections/entries are:

• project(<your project name here>): Give your project a name
• set(LINKER_FILE <your linker file here>): specify the linker file name
• set(SRC_FILES <your source files here>): list of source files to compile
• target_compile_definitions(${EXECUTABLE} PRIVATE <compiler defines here>): list of compiler #defines
• target_include_directories(${EXECUTABLE} PRIVATE <list of include dir>): list of include directories
• target_compile_options(${EXECUTABLE} PRIVATE <compiler options>): list of compiler options
• target_link_options(${EXECUTABLE} PRIVATE <linker options>): list of linker options

This completes setting up the configuration for the build.

Configure

Next we are going to build it. Actually we need to ‘configure’ it first. With CMake it is a two stage process: running CMake to create (or configure) the make files and then we use ‘make’ to build it.

• Close VSCode and Restart again
• Open Command Palette ... (CTL+SHIFT+P)
• Select CMake:Delete cache and Reconfigure

CMake: Config Output

[variant] Loaded new set of variants
[kit] Successfully loaded 3 kits from /home/jshankar/.local/share/CMakeTools/cmake-tools-kits.json
[proc] Executing command: /opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -v
[cmakefileapi-driver] This version of CMake does not support the "toolchains" object kind. Compiler paths will be determined by reading CMakeCache.txt.
[main] Configuring folder: blinky 
[proc] Executing command: /usr/bin/cmake --no-warn-unused-cli -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE -DCMAKE_BUILD_TYPE:STRING=Debug -DCMAKE_C_COMPILER:FILEPATH=/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -DCMAKE_CXX_COMPILER:FILEPATH=/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-g++ -S/home/jshankar/codeprojects/tm4c123gxl/blinky -B/home/jshankar/codeprojects/tm4c123gxl/blinky/build -G "Unix Makefiles"
[cmake] Not searching for unused variables given on the command line.
[cmake] -- CMAKE_TOOLCHAIN_FILE is: /home/jshankar/codeprojects/tm4c123gxl/blinky/arm-toolchain.cmake
[cmake] -- Configuring done
[cmake] -- Generating done
[cmake] -- Build files have been written to: /home/jshankar/codeprojects/tm4c123gxl/blinky/build

Build it with make

Open a terminal in the build output folder:
View-->Terminal

cd build 
make

Instead of calling ‘make’ inside the build folder, following can be used which does the one or the other:

cmake --build .

• The advantage of doing it this way is that if there has been a change in the CMakeList.txt it will run a configuration step first too.
• If doing changes in the structure: make sure you do a configure to make sure things are correctly set up.

Cleaning

A ‘clean’ is to delete all the files inside the build folder. But CMake has a ‘clean’ command too:

cd build
cmake --build . --target clean
make

To do a ‘clean followed by a build’ use the following:

cd build

cmake --build . --clean-first

Make: Build Output

/usr/bin/cmake -S/home/jshankar/codeprojects/tm4c123gxl/blinky -B/home/jshankar/codeprojects/tm4c123gxl/blinky/build --check-build-system CMakeFiles/Makefile.cmake 0
/usr/bin/cmake -E cmake_progress_start /home/jshankar/codeprojects/tm4c123gxl/blinky/build/CMakeFiles /home/jshankar/codeprojects/tm4c123gxl/blinky/build/CMakeFiles/progress.marks
make -f CMakeFiles/Makefile2 all
make[1]: Entering directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
make -f CMakeFiles/blinky.elf.dir/build.make CMakeFiles/blinky.elf.dir/depend
make[2]: Entering directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
cd /home/jshankar/codeprojects/tm4c123gxl/blinky/build && /usr/bin/cmake -E cmake_depends "Unix Makefiles" /home/jshankar/codeprojects/tm4c123gxl/blinky /home/jshankar/codeprojects/tm4c123gxl/blinky /home/jshankar/codeprojects/tm4c123gxl/blinky/build /home/jshankar/codeprojects/tm4c123gxl/blinky/build /home/jshankar/codeprojects/tm4c123gxl/blinky/build/CMakeFiles/blinky.elf.dir/DependInfo.cmake --color=
make[2]: Leaving directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
make -f CMakeFiles/blinky.elf.dir/build.make CMakeFiles/blinky.elf.dir/build
make[2]: Entering directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
[ 33%] Building C object CMakeFiles/blinky.elf.dir/src/main.c.obj
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -DPART_TM4C123GH6PM -I/home/jshankar/codeprojects/tm4c123gxl/blinky/src -I/home/jshankar/codeprojects/tm4c123gxl/blinky/inc -I/home/jshankar/codeprojects/tm4c123gxl/blinky/if -I"/home/jshankar/codeprojects/tm4c123gxl/blinky/(" -I/home/jshankar/codeprojects/tm4c123gxl/blinky/WIN32 -I"/home/jshankar/codeprojects/tm4c123gxl/blinky/)" -I/home/jshankar/codeprojects/tm4c123gxl/blinky/E:/ti/TivaWare_C_Series-2.2.0.295 -I/home/jshankar/codeprojects/tm4c123gxl/blinky/else -I/home/jshankar/ti/TivaWare_C_Series-2.1.4.178 -I/home/jshankar/codeprojects/tm4c123gxl/blinky/endif  -g   -mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard -fdata-sections -ffunction-sections -Wall -O0 -g3 -std=c99 -o CMakeFiles/blinky.elf.dir/src/main.c.obj   -c /home/jshankar/codeprojects/tm4c123gxl/blinky/src/main.c
[ 66%] Building C object CMakeFiles/blinky.elf.dir/src/tm4c_startup.c.obj
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -DPART_TM4C123GH6PM -I/home/jshankar/codeprojects/tm4c123gxl/blinky/src -I/home/jshankar/codeprojects/tm4c123gxl/blinky/inc -I/home/jshankar/codeprojects/tm4c123gxl/blinky/if -I"/home/jshankar/codeprojects/tm4c123gxl/blinky/(" -I/home/jshankar/codeprojects/tm4c123gxl/blinky/WIN32 -I"/home/jshankar/codeprojects/tm4c123gxl/blinky/)" -I/home/jshankar/codeprojects/tm4c123gxl/blinky/E:/ti/TivaWare_C_Series-2.2.0.295 -I/home/jshankar/codeprojects/tm4c123gxl/blinky/else -I/home/jshankar/ti/TivaWare_C_Series-2.1.4.178 -I/home/jshankar/codeprojects/tm4c123gxl/blinky/endif  -g   -mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard -fdata-sections -ffunction-sections -Wall -O0 -g3 -std=c99 -o CMakeFiles/blinky.elf.dir/src/tm4c_startup.c.obj   -c /home/jshankar/codeprojects/tm4c123gxl/blinky/src/tm4c_startup.c
[100%] Linking C executable blinky.elf
/usr/bin/cmake -E cmake_link_script CMakeFiles/blinky.elf.dir/link.txt --verbose=1
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -g  -T/home/jshankar/codeprojects/tm4c123gxl/blinky/ld/tm4c123gh6pm.ld -mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard -specs=nano.specs -specs=nosys.specs -lc -lm -Wl,-Map=blinky.map,--cref -Wl,--gc-sections -Xlinker -print-memory-usage CMakeFiles/blinky.elf.dir/src/main.c.obj CMakeFiles/blinky.elf.dir/src/tm4c_startup.c.obj  -o blinky.elf 
Memory region         Used Size  Region Size  %age Used
           FLASH:         980 B       256 KB      0.37%
            SRAM:         540 B        32 KB      1.65%
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-size blinky.elf
   text    data     bss     dec     hex filename
    980       0     540    1520     5f0 blinky.elf
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-objcopy -O srec --srec-len=64 blinky.elf blinky.s19
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-objcopy -O ihex blinky.elf blinky.hex
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-objcopy -O binary blinky.elf blinky.bin
make[2]: Leaving directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
[100%] Built target blinky.elf
make[1]: Leaving directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
/usr/bin/cmake -E cmake_progress_start /home/jshankar/codeprojects/tm4c123gxl/blinky/build/CMakeFiles 0

Sample Project

You can download sample project from here

References

• Get started with CMake Tools on Linux
• CMake Tools for Visual Studio Code

VSCode Cortex-Debug Launch Configurations

Cortex-Debug is an extension for Visual Studio Code to streamline the debug process when working with ARM Cortex-M microcontrollers. This document covers writing launch configurations (launch.json).

• Open the VSCode user settings file settings.json: File → Preferences → Settings
• Select User settings:

  Enter "json" in the search bar (with or without double quotes). Locate a link "Edit in settings.json" and click on it. This will open the file ~/.config/Code/User/settings.json

• Add the following lines to the settings.json file, between the curly braces {}:
  
  

    "cortex-debug.openocdPath": "/usr/bin/openocd",
    "cortex-debug.armToolchainPath.linux": "/opt/toolchains/gcc-arm- none-eabi-10.3-2021.10/bin",
    "cortex-debug.armToolchainPath.windows": "C:\\ProgramData\\chocolatey\\bin",
    "cortex-debug.gdbPath.linux": "/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin//arm-none-eabi-gdb",
    "cortex-debug.gdbPath.windows": "C:\\ProgramData\\chocolatey\\bin\\arm-none-eabi-gdb.exe"

Please note: The paths on your system might be different. Make sure the path matches your actual file locations.

• Save the file settings.json

Launch configurations

To run or debug a simple app in VS Code, we can select Run and Debug on the Debug start view or we can press F5 and VS Code will try to run the currently active file.

Creating a launch configuration file is beneficial because it allows us to configure and save debugging setup details. VSCode keeps debugging configuration information in a launch.json file located in a .vscode folder in the workspace (project root folder).

The launch.json file is used to configure the debugger in Visual Studio Code.

Parameters

Here is a list of parameters in launch.json. Configure them for your specific device and environment.

• cwd: Path of project
• configFiles: OpenOCD configuration file(s) to load
• device: Target Device Identifier
• interface: Debug Interface type to use for connections (defaults to SWD) - Used for J-Link and BMP probes.
• name: Name of configuration; appears in the launch configuration dropdown menu.
• preLaunchTask: Task to run before debug session starts. Specify a task defined in tasks.json.
• request: Request type of configuration. Can be “launch” or “attach”.
• runToEntryPoint: If enabled the debugger will run until start of the main function.
• serialNumber: J-Link specific parameter. J-Link Serial Number - only needed if multiple J-Links are connected to the computer
• servertype: GDB Server type - supported types are jlink, openocd, pyocd, pe and stutil
• svdFile: Path to an SVD file describing the peripherals of the microcontroller; if not supplied then one may be selected based upon the ‘device’ entered. This may be automatically loaded depending on the "device".
• swoConfig: SWO/ITM configuration.
• enabled: Enable SWO decoding.
• cpuFrequency: Target CPU frequency in Hz.
• swoFrequency: SWO frequency in Hz.
• source: Source for SWO data. Can either be “probe” to get directly from debug probe, or a serial port device to use a serial port external to the debug probe.
• decoders: SWO Decoder Configuration
• label: A label for the output window.
• port: ITM Port Number

OpenOCD Specific Configuration

• configFiles

  OpenOCD configuration files to use when debugging. Exactly equivalent to the OpenOCD command line argument -f.

• searchDir

  Directories to search for configuration files in. Exactly equivalent to the OpenOCD command line argument -s. If no search directories are specified, it defaults to the configured cwd.

• openOCDPreConfigLaunchCommands

  OpenOCD commands to run prior to loading configuration files.

• openOCDLaunchCommands

  OpenOCD commands to run in order to launch target.

OpenOCD GDB Server

We modify launch.json to configure debug features.

Below is an example of a basic launch configuration using the OpenOCD GDB server.

In this configuration the device parameter is not required - but can be supplied to allow auto-selecting an appropriate SVD file if possible.

There is one OpenOCD specific parameter that must be supplied. The configFiles property takes an arrays of strings that are used to load openocd configuration files. These can either be a files in the openocd search path (like in this example), or a full path to your own configuration file. If you are using OpenOCD supplied files you typically will have either one file from the board section, or a file from the interface section and a file from the target section.

• Open the VSCode launch configuration file launch.json: Run → Add Configuration...
• Copy the following code

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug (OpenOCD)",
            "cwd": "${workspaceRoot}",
            "executable": "${workspaceRoot}/build/blinky.elf",
            "request": "launch",
            "type": "cortex-debug",
            "servertype": "openocd",
            "interface": "swd",
            "device": "TM4C123GH6PM",
            "runToEntryPoint": "main",
            "svdFile": "${workspaceRoot}/svd/TM4C123GH6PM.svd",
            "configFiles": [
                "board/ek-tm4c123gxl.cfg"
            ],
            "preLaunchCommands": [
                "set mem inaccessible-by-default off",
                "monitor reset"
            ],
            "postLaunchCommands": [
                "monitor reset init",
                "monitor sleep 200"
            ]
        }
    ]
}

• Change "executable", "svdFile", and "device" parameter as appropriate and save it
• SVD Files: The “svdFile” entry in the launch.json file is optional, but crucial to embedded system debugging because it describes the device peripheral registers.

References

Coretex-Debug

• marus25.cortex-debug
• Configuring C/C++ debugging

OpenOCD

• OpenOCD Config Files
• OpenOCD Config File Paths
• Accessing Devices without sudo

VSCode Cortex Debugging

Use F5 or the menu Run > Start Debugging to start a debug session:

This starts debug session. In case of troubles, check the Debug Console:

Debug Console Output

Launching GDB: /opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin//arm-none-eabi-gdb -q --interpreter=mi2 /home/jshankar/codeprojects/tm4c123gxl/blinky/build/blinky.elf
Set "showDevDebugOutput": true in your "launch.json" to see verbose GDB transactions here. Helpful to debug issues or report problems
Reading symbols from /home/jshankar/codeprojects/tm4c123gxl/blinky/build/blinky.elf...
Launching gdb-server: /usr/bin/openocd -c "gdb_port 50000" -c "tcl_port 50001" -c "telnet_port 50002" -s /home/jshankar/codeprojects/tm4c123gxl/blinky -f /home/jshankar/.vscode/extensions/marus25.cortex-debug-1.2.0/support/openocd-helpers.tcl -f board/ek-tm4c123gxl.cfg
Please check TERMINAL tab (gdb-server) for output from /usr/bin/openocd
0x00000000 in g_pfnVectors ()
Program stopped, probably due to a reset and/or halt issued by debugger
2
adapter speed: RCLK - adaptive
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x00000354 msp: 0x2000021c
adapter speed: RCLK - adaptive
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x00000354 msp: 0x2000021c
adapter speed: RCLK - adaptive
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x00000354 msp: 0x2000021c
Note: automatically using hardware breakpoints for read-only addresses.

Temporary breakpoint 1, main () at /home/jshankar/codeprojects/tm4c123gxl/blinky/src/main.c:16
16	    SYSCTL_RCGC2_R |= 0x00000020;

By default there are several debug views available. With the .svd file, we have access to the peripheral register too:

Debug Commands

There are the usual debug commands (continue, stepping, restart) plus a run and debug toolbar

• Continue / Pause F5
• Step Over F10
• Step Into F11
• Step Out Shift+F11
• Restart Ctrl+Shift+F5
• Stop Shift+F5

Assembly Stepping

Press CTRL+SHIFT+P to invoke command palette. Then Select Cortex-Debug:View Disassembly(Functon), type the function name you want to disassemble.

It is possible to set breakpoints in the assembly code, but one cannot see high level (C/C++) side-by-side with the assembly code. And the disassembly view does not show any more information or symbolic as the Eclipse CDT disassembly view does.

Memory

To view memory, use the Command Palette (CTRL+SHIFT+P) with Cortex-Debug:View Memory.

Then specify the expression for the memory location and a length.

References

• marus25.cortex-debug
• How to Use
• Debugging