Cortex-Debug Launch Configurations

Jan. 2, 2018

Introduction

Cortex-Debug is an extension for Visual Studio Code to streamline your debug process when working with ARM Cortex-M microcontrollers. This document covers writing launch configurations (launch.json). It is divided into 3 sections:

  • Basic shared configuration options
  • GDB server specific options
  • Customizing the launch, attach and restart processes

Shared Configuration Options

  • type: To utilize the Cortex-Debug extension your launch type should be set to "cortex-debug"
  • request: This is the debug request type. This can have one of the two following values:
    • launch - In this mode at debug start the firmware executable will automatically be flashed to the target microcontroller and the microcontroller will be restarted.
    • attach - In this mode the target microcontroller will be halted - but the core is not reset and firmware is not flashed. It is up to the user to ensure that the elf firmware file corresponds to the current version of the firmware flashed on the microcontroller.
  • servertype: This is the type of GDB server to use for the debug process. The following servertype values are supported:
    • jlink - This uses the JLinkGDBServer (JLinkGDBServerCL.exe on Windows) executable. If this is not located on your system PATH the path to the executable can be set in the "cortex-debug.JLinkGDBServerPath" user/workspace setting. All Cortex-Debug features are supported when using the J-Link mode.
    • openocd - This mode uses the OpenOCD server. If the openocd executable is not located on your system PATH then the complete path to the openocd executable can be set in the "cortex-debug.openocdPath" user/workspace setting. All Cortex-Debug features are support when using the OpenOCD mode.
    • stutil - This mode uses the st-util gdb server from texane/stlink (https://github.com/texane/stlink). If the st-util executable is not located on your system PATH then the complete path to the executable can be set in the "cortex-debug.stutilPath". In this mode SWO data cannot be collected via your debug probe (collecting SWO data via a separate serial port is supported).
    • pyocd - This mode uses the MBed pyOCD GDB server (https://github.com/mbedmicro/pyOCD). If the pyocd-gdbserver executable is not located on your system PATH then the complete path to the executable can be set in the "cortex-debug.pyocdPath" user/workspace setting. In this mode SWO data cannot be collected via your debug probe (collecting SWO data via a separate serial port is supported).
    • bmp - This mode uses the Black Magic Probe with its built-in GDB server. In this mode SWO data cannot currently be collected via your debug probe (support for this is under development; you can currently collect SWO data via a separate serial port).
  • executable: This is the path to the firmware executable to debug (ELF format); symbols will be loaded from this executable, and in launch
  • cwd: This should contain a path to be used for the current working directory when debugging - this will default to the workspace root
  • device: This configuration parameter is the name of the device being targeted for debug. When using the J-Link GDB server this parameter is required (See https://www.segger.com/downloads/supported-devices.php for devices - only Cortex-M devices are supported by Cortex-Debug). When using other GDB servers this parameter is optional, but may be used to help automatically determine the SVD file to use if it is not manually supplied.
  • svdFile: You can specify a specific SVD file that defines the peripherals of the device being debugged - this is used to build the peripheral registers view. For some members of the STM32 family the SVD file will be automatically determined based upon the device parameter if supplied and svdFile is omitted.
  • swoConfig: This configuration section controls the SWO/ITM decoding support present in Cortex-Debug. This is discussed in more depth on the Cortex-Debug SWO Decoding and Graphing page.
  • graphConfig: This configuration section controls the Graphing of SWO/ITM decoded data. This is discussed in more depth on the Cortex-Debug SWO Decoding and Graphing page.
  • showDevDebugOutput: This will output additional output in the debugging stream for debugging the Cortex-Debug extension. It is generally not needed in normal operation, but can be useful to enable if you want to make a bug report for Cortex-Debug.

GDB Server Specific Options

J-Link GDB Server ("servertype": "jlink")

To the right is an example of a basic launch configuration using the J-Link GDB server.

As mentioned in the Shared Configuration Options section - the device parameter is required for J-Link sessions. Please find the appropriate device identifier here.

The following three parameters are optional, but may be needed depending on your setup:

  • interface - This allows you to select the debug connection type to your microcontroller. This can be either "swd" (the default) or "jtag".
  • ipAddress - If your J-Link probe is connected via Ethernet instead of USB you need to supply the IP Address for the probe in this configuration parameter.
  • serialNumber - If you have multiple J-Link probes connected via USB then you can supply the serial number for the J-Link probe to use. If only one J-Link probe is connected this option can be omitted.

Note: Only one of ipAddress or serialNumber should be supplied. If both are supplied then ipAddress is ignored and a USB connection is attempted with the supplied serial number.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "jlink",
            "cwd": "${workspaceRoot}",
            "executable": "./firmware.elf",
            "name": "Debug (J-Link)",
            "device": "STM32F103RB",
            "interface": "swd",
            "ipAddress": null,
            "serialNumber": null,
        }
    ]
}

OpenOCD GDB Server ("servertype": "openocd")

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

In this configuration the device paramter 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "openocd",
            "cwd": "${workspaceRoot}",
            "executable": "./firmware.elf",
            "name": "Debug (OpenOCD)",
            "device": "STM32F103RB",
            "configFiles": [
                "board/st_nucleo_f103rb.cfg"
            ]
        }
    ]
}

ST-Util GDB Server ("servertype": "stutil")

To the right is an example configuration for the texane's st-util GDB server.

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

There is only one ST-Util specific configuration option, which is generally not needed. If you are using an older ST-Link V2 (for example the ST-Link that is embedded in the STM32 Value Line Discovery board , you need to specify "v1": true in the launch configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "stutil",
            "cwd": "${workspaceRoot}",
            "executable": "./firmware.elf",
            "name": "Debug (ST-Util)",
            "device": "STM32F103RB",
            "v1": false
        }
    ]
}

pyOCD GDB Server ("servertype": "pyocd")

To the right is an example configuration for the pyOCD GDB Server.

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

There are two pyocd specific configuration parameters, that are needed for two different situations, but in most cases can be omitted:

  • boardId - If you have multiple pyOCD compatible boards connected at the same time you need to specify the board to use using this parameter. You can get a list of all available board ids by executing pyocd-gdbserver -l in a terminal window.
  • targetId (string value) - If you are using a pyOCD powered probe to debug custom hardware (not an on-board target) then you need to specify a supported target. You can find a list of supported targets by executing pyocd-gdbserver --help in a terminal window.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "pyocd",
            "cwd": "${workspaceRoot}",
            "executable": "./firmware.elf",
            "name": "Debug (pyOCD)",
            "device": "STM32F103RB",
            "targetId": "",
            "boardId": ""
        }
    ]
}

Black Magic Probe GDB Server ("servertype": "bmp")

To the right is an example configuration for the pyOCD GDB Server.

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

There are three Black Magic Probe specific configuration parameters:

  • BMPGDBSerialPort (required)- This configuration parameter is the serial device for the Black Magic Probe's GDB server. On Linux or macOS this will be a path to the serial device, for example "/dev/cu.usbmodemB6F1D7E3" in the example. On Windows this will be a COM port (e.g. COM1). The exact value will vary depending on your computer setup. Note: On macOS there will be two versions of the device available - one that starts with cu and one that starts with tty - You must use the version of the device that starts with cu for the probe to function properly.
  • interface - This allows you to select the debug connection type to your microcontroller. This can be either "swd" (the default) or "jtag".
  • targetId (integer value; default 1) - If the probe has multiple targets attached then this parameter is used to determine with target to attach to, this is passed to the attach command. In most cases with only one target connected then the default value of 1 is suitable.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "cortex-debug",
            "request": "launch",
            "servertype": "bmp",
            "cwd": "${workspaceRoot}",
            "executable": "./firmware.elf",
            "name": "Debug (Black Magic Probe)",
            "device": "STM32F103RB",
            "BMPGDBSerialPort": "/dev/cu.usbmodemB6F1D7E3",
            "targetId": 1
        }
    ]
}

Customizing the launch, attach and restart processes

Coming Soon