Debug Common Operations - nxp-mcuxpresso/vscode-for-mcux GitHub Wiki
Where possible, MCUXpresso for VS Code extension attempts to provide a common debug experience regardless of the used debug solution. In this section, we discuss some common debug operations and, where applicable, the particularities for each debug solution.
DEBUG PROBES view displays all available probes, grouped by their provider (i.e. SEGGER, LinkServer, PEmicro). Initially, if software for them is not installed, the DEBUG PROBES view will visually indicate this information. Follow dependencies installation chapter to find how to get MCUXpresso Installer and install the debug probes software.
Once installed, a tooltip on each debug probe type will indicate installation path. If multiple installations are found, the newest version will be considered.
Each installed debug probe will display a documentation icon, linking to the available documentation for each type.
The projects currently being debugged are shown under the corresponding probe. A refresh button will force re-reading the list of available probes.
Once a debug probe is selected for a project, that probe will be used by default for subsequent debug sessions. If you need to select another debug probe, a "Reset Probe Selection" option is available for each project. If selected, then the probe selection dialog will be displayed again, once a new debug session is initiated.
Quick access links to program the flash or to fully erase the flash are available in the project's context menu.
In case of flash operation, a dialog will ask to confirm (or to select, in case of multiple binary files are found) the image file you want to program.
In case only attach to running target is needed (in other words, no download, no reset or other "intrusive" debug operations needed to be performed), simply right-click the project node inside the PROJECTS view and select "Attach" instead. This is directly linked to the isAttach
attribute, that is configurable inside the debug configuration.
Note: The "Attach" action under the project's context menu does not persist the change to the
isAttach
attribute configured inside a debug configuration. If attach debug mode is required even when using the "Debug" action, make sure you updatelaunch.json
(accessible via PROJECTS view -> Settings) accordingly. Debug sessions initiated on secondary cores in a multicore debug use case, will always have theisAttach
property set totrue
.
Serial Monitor from Microsoft, added by default by MCUXpresso extension, can be used to monitor UART or Semihosting traffic.
During a debug session, the DEBUG CONSOLE view gets activated and allows GDB commands to be executed inside the console. Moreover, each connection to a GDB server has a terminal associated to it. Messages logged by the GDB servers are printed in such a terminal. To inspect the logs, open the TERMINAL view and then select the terminal entry associated to the debug session.
Projects can be configured to support semihosting (I/O operations using the debug probe). In order to achieve this, the first step is to build the project with semihosting support, the default being UART:
- Identify the active build configuration of the project, select the "Edit" icon, select "Semihost" for Debug Console type. Finish by pressing the "Save" button to save your changes.
or
- Directly modify DEBUG_CONSOLE property in the
CMakePresets.json
file of the project. Keep in mind that each build configuration can have its own settings. When modifying theCMakePresets.json
file make sure you modify the build configuration you are using.
For an MCUXpresso SDK project, Serial Monitor will automatically connect to the semihosting port when the debug session is launched.
The semihosting port can be configured for each individual probe type using semihostPort
field from the mcuxpresso-tools.json
file. If the field is not provided, a suitable port will be chosen automatically before starting the debug session.
In a multicore debug scenario, a debug session must be started for each core individually. The primary core should be debugged first. The active debug session can be switched using the drop-down next to the debug bar, or directly from the CALL STACK view.
For more details see Multicore-Examples-on-LPC55S6x-and-MCUXPresso-SDK.
Note: For PEmicro, all the debug sessions on the same probe depend on the first debug session started on that probe. As a consequence, when the first debug session closes, all the dependant sessions also get closed.
By default, a new GDB server is automatically started for each debug session. The debugger can be configured instead, to connect to a manually started GDB server. This can be achieved by using the gdbServerTargetRemote
attribute inside launch.json
.
Steps:
- Start the GDB server. For details regarding manually starting the GDB server, check the documentation specific for each debug probe type.
- In
launch.json
, fill ingdbServerTargetRemote
the address and port where the server is listening on. The address needs to be formatted as<host>:<port>
. - Debug.
- Select the probe type you are debugging with. The selection is saved in
probeType
attribute insidelaunch.json
and is reused for future remote debug sessions.
In a typical debug scenario, a project is built, programmed into flash and debugged. However, a common requirement may be to debug via a bootloader, or debug additional code preloaded (into flash) generated by other project(s). For a good debug experience, symbolic information (and source) for additional code must be made available to GDB. The list of files containing additional symbolic information can be added through the extraSymbolFiles
attribute inside launch.json
file, as shown below:
"extraSymbolFiles": [
"C:/NXP/symbols/app1.elf",
"C:/NXP/symbols/app2.elf"
],
A complex debug use case might also involve several ELF files that need to be loaded on the target along with the main executable associated to the project being debugged. To accomplish this, you can use the extraLoadFiles
attribute, that is available for debug configuration, inside launch.json
file. An example that instructs the debugger to also load some additional ELF files is shown below:
"extraLoadFiles": [
"C:/NXP/symbols/app1.elf",
"C:/NXP/symbols/app2.elf"
],
Sometimes the project that will be debugged does not have an associated repository or, even if it has, the necessary information is not present in that repository.
In this the case the extension allows starting the debug session, but will ask the user to provide the necessary information.
For example, on LinkServer extension will first present a list of all the devices supported.
Additionally, if you select a multicore device, a new list with the available cores will be displayed.
Sometimes you might need to debug without building the application. In this case you need to change the skipBuildBeforeDebug
attribute value from the default false
value to true
inside the launch.json
file of your project.
If the project was built before, then a incremental build will not be performed, and the existing executable will be used to debug. Otherwise, the debug session will fail since in this case a build is required.