Cortex-Debug is a Visual Studio Code extension that simplifies the debugging process for ARM Cortex-M microcontrollers. This guide will walk you through the process of creating launch settings (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”
Launch configurations
To launch or debug a simple app in VS Code, go to the Debug start view and pick Run and Debug, or press F5 and VS Code will attempt to run the currently active file.
It is advantageous to create a launch configuration file since it allows us to customize and save debugging setup parameters. VSCode saves debugging configuration information in a launch.json file in the workspace’s.vscode folder (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 the 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.
A basic launch configuration using the OpenOCD GDB server is shown below.
The device argument is not necessary in this configuration, although it can be included to facilitate auto-selection of an appropriate SVD file if possible.
A single OpenOCD-specific argument must be provided. The configFiles field accepts a list of strings to load openocd configuration files. These can be files from the openocd search path (as in this example) or the complete path to your own configuration file. If you’re utilising OpenOCD’s files, you’ll usually have one file from the board area, one from the interface part, and one 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.
