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

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.

Debug probes software not installed

Once installed, a tooltip on each debug probe type will indicate installation path. If multiple installations are found, the newest version will be considered.

Debug probes software installed

Each installed debug probe will display a documentation icon, linking to the available documentation for each type.

Software debug probes doc

The projects currently being debugged are shown under the corresponding probe. A refresh button will force re-reading the list of available probes.

Debug refresh probes list

Reset debug probe selection

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.

Debug refresh probes list

Flash operations

Quick access links to program the flash or to fully erase the flash are available in the project's context menu.

Flash erase quick access options

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.

Flash options

Attach to target

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.

Attach

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 update launch.json (accessible via PROJECTS view -> Settings) accordingly. Debug sessions initiated on secondary cores in a multicore debug use case, will always have the isAttach property set to true.

Serial console

Serial Monitor from Microsoft, added by default by MCUXpresso extension, can be used to monitor UART or Semihosting traffic.

Serial Monitor

GDB server terminal

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.

GDB server terminal

Semihosting support

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.

Semihosting enablement through UI

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 the CMakePresets.json file make sure you modify the build configuration you are using.

Semihosting enablement through configuration file

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.

Semihosting Flow

Multicore debugging

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.

Debug Sessions in Callstack

Debug Sessions in Callstack

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.

Remote GDB server

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:

  1. Start the GDB server. For details regarding manually starting the GDB server, check the documentation specific for each debug probe type.
  2. In launch.json, fill in gdbServerTargetRemote the address and port where the server is listening on. The address needs to be formatted as <host>:<port>.
  3. Debug.
  4. Select the probe type you are debugging with. The selection is saved in probeType attribute inside launch.json and is reused for future remote debug sessions.

Remote GDB server Flow

Additional symbol files

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"
],

Additional load files

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"
],

Debug without repository information

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.

LinkServer devices

Additionally, if you select a multicore device, a new list with the available cores will be displayed.

LinkServer cores

Debug without building the project

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.

skip build when debuggging

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.

home

⚠️ **GitHub.com Fallback** ⚠️