Debug - nxp-mcuxpresso/vscode-for-mcux GitHub Wiki
Debug solutions overview
MCUXpresso for VS Code installs with built-in support for 3 debug (hardware) solutions, comprising the native LinkServer (including CMSIS-DAP), plus support for PEmicro and SEGGER J-Link. This support includes the installation of all necessary drivers and supporting software using MCUXpresso Installer.
Starting a debug session
With a suitable board and debug probe connected (usually via USB), to start a debug session:
- Select a project to debug within the PROJECTS view;
- Click Debug button from the project toolbar options. A debug probe discovery operation is automatically performed to display (in a Quick Pick) the available debug connections (that is, the detected debug probes), including LinkServer, PEmicro, and J-Link compatible probes;
- Select the required debug probe
- At this stage, the launch configuration complete with debug-specific configurations;
- If the debug connection is successful, a Debug view appears typically showing the project has stopped on main()
Note: After debugging a project, the launch configuration contains details of the debug probe used. Subsequent debug sessions automatically select this probe if it is available.
From this point onwards, one of the debug solutions mentioned above controls the low-level debug operations. However, from the user's point of view, most of the common debug operations within the IDE appear the same (or broadly similar), for example:
- Automatic inheritance of part knowledge.
- Automatic downloading (programming) of generated image to target Flash memory.
- Automatic halt on
main(). - Setting breakpoints and watchpoints.
- Stepping (single, step in, step out, and so on).
- Viewing and editing local variables, registers, peripherals, memory.
- Viewing and editing global variables.
- Live global and static variables.
- Viewing disassembly.
- Semihosted I/O.
- GUI Flash Programmer.
Note: In addition, MCUXpresso for VS Code dynamically manages each debug solution's connection requirements allowing multiple sessions to be started without conflict. For debug of multicore MCUs, refer to the section Debugging a multicore application. It is important to note that certain operations such as the handling of features via Launch configurations may be different for each debug solution. Furthermore, advanced debug features and capabilities may vary between solutions and even similar features may appear different within the MCUXpresso for VS Code extension. PEmicro and SEGGER debug solutions also provide several advanced features. Find details at their respective web sites.
An introduction to launch configuration files
Each project in MCUXpresso for VS Code stores its debug properties locally in launch.json file (in Settings, or phisically, in .vscode directory in the project root folder) known as launch configuration files.
Debug probe options are specified via gdbServerConfigs property in the launch configuration (also in Settings, or physically, in .vscode directory in the project root folder).
Debug probe settings are different for each debug solution (LinkServer, PEmicro, SEGGER) and contain the properties of the debug connection (for example SWD/JTAG, RTOS thread awareness enablement and various other configurations) and can also include a
debug probe identifier for automatic debug probe matching and selection.
If a project has not yet been debugged, for example, a newly imported or created project, then the project has no debug probe associated with it. When you try to debug a project, MCUXpresso for VS Code performs a Debug Probe Discovery operation and presents the list of debug probes found. If only one debug probe is identified then this is automatically associated to the project, and it also used for starting the actual debug session.
Note: The extension creates a launch configuration only for the currently selected build configuration. For many debug operations, these files do not require any attention and can essentially be ignored. However, if changes are required, you can edit the launch connection settings. The simplest way to do this is to click to expand the project within the PROJECTS view, then open and edit the
launch.jsonconfiguration file.
Note: For details about managing current debug probe selection, please check DEBUG PROBES view.
Debug solutions support advanced operations. In the next sections, details about general debug settings and each debug probe options will be presented.
Debug launch configuration
Debugger options are available in .vscode/launch.json file located in project's root folder.
| Attribute | Type | Description |
|---|---|---|
| cwd | string | Current working directory for commands executed during launch. |
| debugServerLogFile | string | Path to log file used by the GDB server. |
| executable | object | string | Path to executable (and associated BIN/HEX files), used for debug symbols and program information. See also "executableLoadTypePriority", "extraLoadFiles" and "extraSymbolFiles". |
| executable.binary | object | Details about the BIN file associated to the ELF file. |
| executable.binary.address | number | Base address used for loading the BIN file into target memory. |
| executable.binary.path | string | Path to the BIN file. |
| executable.elf | string | Path to the ELF file. |
| executable.hex | string | Path to the HEX file. |
| executableLoadTypePriority | string | Load on target the build artifact type based on the priority specified by this property. Depending on the project type, debugger can choose between ELF, HEX or BIN files. Valid values: "auto" prioritizes HEX > BIN > ELF but only when HEX/BIN are assumed to be post build processed (i.e. file names - excluding file extensions - and/or parent folders are different), "elf" uses the ELF file, "hex" loads any available HEX file, "bin" loads any available BIN file. Note that MCUXpresso for VS Code also uses the information (i.e. "runners") generated by "west"-based build systems in order to perform flash programming and debugging. |
| extraLoadFiles | object[] | List of additional files (ELF/BIN/HEX) to load/program. Symbols are not loaded (see "extraSymbolFiles"). |
| extraSymbolFiles | object[] | List of additional files to load symbols from. Each item in the array can be a string or an object. |
| gdbClientExtraArgs | array | Additional arguments to passed to GDB command line client. |
| gdbClientPath | string | Property used to override the GDB client path for a particular launch configuration. It must be the full path to the executable (or name of the executable if it is in your "PATH" environment variable). Note that other toolchain executables with the configured prefix must still be available. |
| gdbInitCommands | string[] | Additional GDB commands to be executed at the start of the main launch sequence (right before attaching to target). |
| gdbServerArgs | string[] | Initial arguments to pass to the GDB server. |
| gdbServerConfigs | object | Debug probe specific configurations. See Debug probe specific configurations section below for all options. |
| gdbServerCwd | string | Current working directory for GDB server. |
| gdbServerExtraArgs | string[] | Additional arguments to pass to the GDB server. |
| gdbServerLaunchTimeout | number | Launch timeout to be used by the GDB client when connecting to the GDB server. |
| gdbServerPath | string | Property used to override the GDB server path for a particular launch configuration. It is the full path to the executable or name of executable if it is in your "PATH" environment variable. |
| gdbServerTargetRemote | string | This can either be a "hostname:port" combination or path to a serial port. The appropriate GDB server type is not started in this case and the GDB client will connect to the remote target pointed by this attribute. |
| isAttach | boolean | Whether to attach to target, instead of launch. |
| liveWatch | object | Parameters for LIVE WATCH view configuration. It is currently supported only with J-Link debug probes. |
| liveWatch.enabled | boolean | Enable/disable LIVE WATCH view functionality. |
| liveWatch.samplesPerSecond | number | Maximum number of samples per second. Different from GUI refresh-rate, which is a user/workspace setting. |
| name | string | Name of launch configuration. |
| objdumpPath | string | Property used to override the "objdump" (used to find globals/statics) path for a particular launch configuration. It must be the full path to the executable (or name of the executable if it is in your "PATH" environment variable). Note that other toolchain executables with the configured prefix must still be available. The program "nm" is also expected alongside. |
| overrideLaunchCommands | string[] | Property used to override the commands that are normally executed as part of flashing and launching the target. In most cases it is preferable to use "preLaunchCommands" and "postLaunchCommands" to customize the GDB launch sequence. |
| overrideResetCommands | string[] | Property used to override the commands that are normally executed as part of the target reset sequence. |
| postLaunchCommands | string[] | Additional GDB commands to be executed after the main launch sequence has finished. |
| postResetCommands | string[] | Additional GDB commands to be executed at the end of the reset sequence. |
| postResetSessionCommands | string[] | Additional GDB commands to be executed at the end of a reset/restart sequence, after a debug session has already started and "stopAtSymbol" is not specified. |
| postStartSessionCommands | string[] | Additional GDB commands to be executed at the end of the start debug sequence, after a debug session has already started and "stopAtSymbol" is not specified. |
| preLaunchCommands | string[] | Additional GDB commands to be executed at the start of the main launch sequence (immediately after attaching to target). |
| preResetCommands | string[] | Additional GDB commands to be executed at the beginning of the reset sequence (after interrupt execution). |
| probeSerialNumber | string | Probe serial number. |
| probeType | string | Probe type. |
| registerUseNaturalFormat | boolean | If true, display registers in their natural format as specified by ARM. Hex otherwise. |
| request | string | Launch type. |
| showDevDebugOutput | string | Used to debug MCUXpresso debug adapter and also activate logging associated to active debug sessions. Prints all GDB responses to the DEBUG CONSOLE. "raw" prints GDB responses, "parsed" prints results after parsing, "both" prints both. "vscode" shows raw and VS Code interactions. |
| showDevDebugTimestamps | boolean | Show timestamps when "showDevDebugOutput" is enabled. |
| skipBuildBeforeDebug | boolean | Whether to skip automatic build before initiating a debug session. |
| skipPreFlashActions | boolean | Whether pre-flash actions should be skipped. |
| stopAfterReset | boolean | Applies to launch/restart/reset, halt debugger after a reset. Ignored if "stopAtSymbol" is used. |
| stopAtSymbol | string | Applies to launch/restart/reset. If enabled, the debugger will run until the start of the given symbol. |
| svdPath | string | Path to SVD file containing registers/peripherals definition. |
| toolchainPath | string | Property used to override the toolchain path for a particular launch configuration. It must be the path where "arm-none-eabi-gdb", "arm-none-eabi-objdump" and "arm-none-eabi-nm" are located. |
| toolchainPrefix | string | Property used to override the toolchain prefix for a particular launch configuration. Default is "arm-none-eabi-" |
| type | string | MCUXpresso debug type. |
| variableUseNaturalFormat | boolean | If true, display variables in their natural format as specified by ARM. Hex otherwise. |
Debug probe specific configurations
On top of common debugger settings, debug probe specific properties are available via the gdbServerConfigs property in the launch configuration. Properties for each probe type can be customized by using the dedicated node, under gdbServerConfigs.
The options currently available are as follows:
linkserver:device: Device name.core: Core name.overrides: Override device config properties. See LinkServer--overrideoption.cachelib: Cachelib to use for the current core.gdbPort: GDB server port.semihostPort: Semihosting telnet port.
pemicro:device: Device name.core: Core index.speed: Shift frequency in KHz. Defaults to 5000.usejtag: Sets the communication style to JTAG. Defaults to false.gdbPort: GDB server port.semihostPort: Semihosting telnet port.
segger:device: Device name.interface: Target interface. Defaults to SWD.speed: Interface speed. Decimal value (kHz), 'adaptive' or 'auto'. Defaults to 4000.rtos: RTOS plugin passed to-rtosoption. If the file extension is missing, it is automatically added based on the current OS.scriptfile: Selects a specific J-Link script file to use.resetAfterLoad: Issue a reset command after load. If given a number, it indicates the J-Link reset strategy to be used. Ignored in attach mode.gdbPort: GDB server port.semihostPort: Semihosting telnet port.swoPort: SWO port.
Debug a project
PROJECTS view provides a debug button for each project. This will trigger a debug session considering the executable built for current selected build configuration.
While having an active debug session, the "Run and Debug" perspective offers various debug-specific views to help interact with the underlying target and effectively run and debug the application. For more information, see the dedicated Debug views section.
If selected first time for that particular project, the user will be asked to select from available debug probes.
After starting a debug session, the "Terminate Debug" button can be used to terminate all debug sessions associated with that project.
While actively debugging, the use of "Run and Debug" perspective provides access to various views, debug actions and resources, making it suitable for this type of activity. Once the debug session is terminated, the switch to MCUXpresso for VS Code is automatically performed because of the various features offered that support the development process. This behavior can be configured through the Settings page from VS Code.
Configuring application type to be loaded during debug
Depending on the debug session type, the application might also be loaded on target. It is important to emphasize that during an "attach" debug session, the main build artifact is not loaded on target.
MCUXpresso for VS Code uses a custom heuristic to decide what build artifact is automatically loaded on target when a debug session is started. This depends on the project type and on the availability of information needed by the extension. Extra information used for debug can be extracted from projects that are west-based (e.g. Zephyr, and SDK v24.12 or newer). Build outputs are taken into account by the extension in order to decide what is going to be loaded on target. This behavior can also be controlled by the "executableLoadTypePriority" attribute, configurable inside launch.json.
By default, the extension attempts to prioritize HEX/BIN files over ELF files, but only if they are assumed to be a post-processed (e.g. signed) version of the ELF file. More specifically, two build artifacts are assumed to be different if their file names (excluding file extensions) and/or parent folders are different. This behavior is associated to the "auto" value for "executableLoadTypePriority". If this behavior proves to be incorrect for debugging a particular project, please make sure you change the value of "executableLoadTypePriority" inside launch.json.
Automatic device detection and check
When using CMSIS-DAP probes with target information available, launching a debug session causes the probe selection dialog to order with higher position the entry that matches the board and device description of your project. When available, target information is added for discovered probes in DEBUG PROBES view.
As a safety mechanism, if you select a probe that is configured for a different board or device than the ones your project is configured for, the extension warns you of the mismatch before proceeding with the debug operation.
