Arm CMSIS Debugger

The Arm® CMSIS Debugger extension is an extension pack for Visual Studio Code® that demonstrates how to combine technologies from various open source projects to create a comprehensive debug platform for Arm-based IoT solutions.

Related open source projects are

• Open-CMSIS-Pack of which this extension is part of.
• Eclipse® CDT.cloud™, an open-source project that hosts a number of components and best practices for building customizable web-based C/C++ tools.
• pyOCD, a Python based tool and API for debugging, programming, and exploring Arm Cortex® microcontrollers.
• GDB, the debugger of the GNU Project.

The Arm CMSIS Debugger Extension Pack

The Arm CMSIS Debugger extension is an extension pack. It allows to install multiple separate extensions together.

Included Extensions

The following extensions are included in this extension pack:

• CDT™ GDB Debug Adapter Extension, an Eclipse CDT.cloud extension that supports debugging using GDB and any other debuggers that supports the MI protocol.
• Memory Inspector, an Eclipse CDT.cloud extension that provides a powerful and configurable memory viewer that works with debug adapters.
• Peripheral Inspector, an Eclipse CDT.cloud extension that provides a CMSIS SVD viewer and works with debug adapters.

Recommended Extensions

We recommend to install the following extensions to simplify the user experience:

• Arm Tools Environment Manager, an extension that allows to download, install, and manage software development tools using Microsoft® Vcpkg artifacts. Use this extension to for example install the GCC compiler for ARM CPUs which comes with a GDB variant for Arm CPUs.
• Arm CMSIS Solution, an extension that is a graphical user interface for csolution projects that use the CMSIS-Toolbox. Use this extension to build your csolution projects, to generate *.cbuild-run.yml debug configuration files, and to make use of contributed commands in your debug launch configurations.

pyOCD Debug Setup

• Install GCC compiler for ARM CPUs with the Arm Tools Environment Manager extension to get access to a GDB (arm-none-eabi-gdb).
• Temporary - should become obsolete with full *.cbuild-run.yml support in pyOCD:
  Make sure to set up your CMSIS Pack installation root folder by one of the following methods:

  • Set your system environment variable CMSIS_PACK_ROOT.

  • Add the following to your debug launch configuration

    "environment": {
      "CMSIS_PACK_ROOT": "</path/to/your/pack/cache>"
    }
    

SEGGER® J-LINK® Debug Setup

• Install the latest J-LINK Software and Documentation Pack from SEGGER. Ensure all required drivers and host platform specific settings are done.
• Ensure the installation folder is added to your system's PATH environment variable. Alternatively, you can add an absolute path to your installation in the debug launch configuration.

Additional Extension Functionality

This extension contributes additional functionality to more seamlessly integrate the included extensions:

• The pseudo debugger types cmsis-debug-pyocd and cmsis-debug-jlink. These types allow a more seamless integration into your IDE. However, these are not full debug adapters but generate debug configurations of type gdbtarget which comes with the CDT GDB Debug Adapter Extension.
• A debug configuration provider for the type gdbtarget which comes with the CDT GDB Debug Adapter Extension. This provider automatically fills in default values for known remote GDB servers when launching a debug session.
• CMSIS specific launch configuration items for the * debugger type, i.e. visible for all debugger types. It depends on the actually used debug adapter type if this information is known and utilized.

Pseudo Debugger Types

This section describes the contributed pseudo debugger types and their support through the contributed debug configuration provider for type gdbtarget.

CMSIS Debugger (pyOCD) - cmsis-debug-pyocd

The cmsis-debug-pyocd debugger type allows to add default debug configurations to the workspace's launch.json file to debug via GDB and pyOCD. The actually used debugger type is gdbtarget.

In addition this extension contributes a debug configuration resolver which automatically fills the following gaps during debug launch:

• If option target.server is set to pyocd, then it expands this option to the absolute path of the built-in pyOCD distribution.
• Adds/extends the target.serverParameters list of pyocd command line arguments:
  • Prepends gdbserver if not present.
  • Appends --port and the corresponding port value if target.port is set.
  • Appends --cbuild-run and the corresponding cbuildRunFile path if cmsis.cbuildRunFile is set.

Note: The built-in version of pyOCD supports the command line option --cbuild-run. However, this is a new option which isn't contained yet in releases outside this extension.

CMSIS Debugger (J-LINK) - cmsis-debug-jlink

The cmsis-debug-jlink debugger type allows to add default debug configurations to the workspace's launch.json file to debug via GDB and the SEGGER J-LINK GDB server. The actually used debugger type is gdbtarget.

Note: The generated default debug configuration uses JLinkGDBServer as target.server setting. The executable with this name has slightly differing behavior depending on your host platform. It launches a GUI-less server on Linux and macOS. Whereas a GDB server with GUI is launched on Windows®. Please change the value to JLinkGDBServerCL to suppress the GUI on Windows.

In addition this extension contributes a debug configuration resolver which automatically fills the following gaps during debug launch:

• Adds/extends the target.serverParameters list of JLinkGDBServer/JLinkGDBServerCL command line arguments:
  • Appends --port and the corresponding port value if target.port is set.

Known Limitations

• Requires ELF files built with GCC and DWARF5 debug information to operate seamlessly.
• The shipped pyOCD version accepts the new command line option --cbuild-run. But only extracts device and DFP names.

Trademarks

Arm and Cortex are registered trademarks of Arm Limited (or its subsidiaries or affiliates) in the US and/or elsewhere.
Windows, Visual Studio Code, VS Code, and the Visual Studio Code icon are trademarks of Microsoft Corporation. All rights reserved.
Mac and macOS are trademarks of Apple Inc., registered in the U.S. and other countries and regions.
Eclipse, CDT, and CDT.cloud are trademarks of Eclipse Foundation, Inc.
SEGGER and J-LINK are registered trademarks of SEGGER Microcontroller GmbH.
Node.js is a registered trademark of the OpenJS Foundation.
GDB and GCC are part of the GNU Project and are maintained by the Free Software Foundation.