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.
Additionally, debug probe specific options are located in the mcuxpresso-tools.json file (also in Settings, or phisically, 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 simply open and edit
launch.jsonconfiguration file or themcuxpresso-tools.jsonsettings 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 | string | Path to executable, used for debug symbols and program information. See also 'extraLoadFiles' 'extraSymbolFiles' |
| extraLoadFiles | string[] | List of additional files (hex/bin/elf) 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). 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. |
| 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. |
| 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 configuration of LIVE WATCH view. It is currently supported only with J-Link debug probes. |
| liveWatch.enabled | boolean | Enable/disable continuous variables update in LIVE WATCH view. |
| 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). 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 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. Hard-coded. |
| variableUseNaturalFormat | boolean | If 'true', display variables in their natural format as specified by ARM. Hex otherwise. |
Debug probe settings
On top of common debugger settings, debug probe specific properties are available in .vscode/mcuxpresso-tools.json file, located in project's root folder. Properties for each probe type can be customized by using the dedicated node, under debug.
The options currently available are as follows:
linkserver:device: Device name.core: Core name.gdbPort: GDB server port.semihostPort: Semihosting telnet port.overrides: Override device config properties. See LinkServer--overrideoption.
pemicro:device: Device name.core: Core index.speed: Shift frequency in KHz. Default 5000.usejtag: Sets the communication style to JTAG. Default false.gdbPort: GDB server port.semihostPort: Semihosting telnet port.
segger:device: Device name.interface: Target interface. Default "SWD".speed: Interface speed. Decimal value (kHz), 'adaptive' or 'auto'. Default 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.
