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.