Arm Debugger
Quality
| Badge |
Status |
| Maintainability |
 |
| Code Coverage |
 |
Overview
The Arm® Debugger extension allows you to debug and optimize software running on Arm-based processors. You can use the extension as a standalone tool or integrate it into your existing toolchain. It is also compatible with other extensions included in the Arm® Keil® Studio Pack.
The extension provides access to the Arm Debugger engine (armdbg) by implementing the Microsoft Debug Adapter Protocol (DAP).
The Arm Debugger engine supports connections to the following targets:
Physical targets: Either through external hardware, for example, Arm® Keil® ULINK™ or DSTREAM debug probes, or through low-cost on-board hardware, for example, ST-Link or CMSIS-DAP
Virtual targets: Using Fixed Virtual Platform (FVP) models
See the Arm Debugger Release Note for an overview of each Arm Debugger engine release.
Supported features
The Arm Debugger extension allows you to:
Load images like .elf, .axf, or .bin files and debug information according to the DWARF Debugging Information Format Standard, up to and including version 5
Run images
Set breakpoints
Do source and instruction stepping
Access variables and registers
View the contents of memory
Access the CLI using the Debug Console
Inspect OS threads, their call stacks, and execution context during a debug session with OS awareness
Supported debug connections
The Arm Debugger engine supports debug connections based on the following information:
The debug setup included in the CMSIS-Packs of your project
The integrated configuration database (configdb). The configuration database is where Arm Debugger stores information about the processors, devices, and boards that it can connect to.
Supported technologies
For a complete list of supported architectures, processors, Fixed Virtual Platform (FVP) models, and debug probes see the Arm Debugger Release Note.
Prerequisites
You must install the Arm Debugger extension pack (identifier: arm.arm-debugger).
The Arm Debugger extension automatically installs the following extensions:
Arm Tools Environment Manager (identifier: arm.environment-manager)
Arm Device Manager (identifier: arm.device-manager)
Arm Virtual Hardware (identifier: arm.virtual-hardware)
Peripheral Inspector (identifier: eclipse-cdt.peripheral-inspector)
Memory Inspector (identifier: eclipse-cdt.memory-inspector)
To work with CMSIS projects, you must install the Arm CMSIS Solution extension (identifier: arm.cmsis-csolution) separately.
To debug a program running on an FVP model, you must have FVPs installed locally. See Work with a virtual target for more details.
You must have an example project ready to use. You can create an example from scratch. Alternatively, if you are working with CMSIS, you can start from one of the official examples available on Arm Examples or keil.arm.com. These examples contain pre-configured vcpkg-configuration.json, tasks.json, and launch.json files.
Install the Arm Debugger extension pack
Open Visual Studio Code Desktop and click the Extensions icon  in the Activity Bar to open the Extensions view.
Search for Arm Debugger and click the Install button.
The Arm Debugger extension installs all extensions in the extension pack at the same time.
The Arm Tools Environment Manager extension downloads, installs, and manages software development tools, including the Arm Debugger engine, using Microsoft vcpkg artifacts. Arm Tools Environment Manager adds a vcpkg-configuration.json manifest file to your project and uses this file to acquire and activate the tools needed to set up your development environment.
Some tools, like the Arm Debugger engine, require a User-based Licensing (UBL) license. You must activate the license with the Arm License Management Utility available with Arm Tools Environment Manager.
See the Arm Tools Environment Manager README for more details.
To install the Arm Debugger engine and other tools:
Open the project that you want to work on.
Click the Arm Tools status bar indicator and select Add Arm Tools Configuration to Workspace in the drop-down list at the top of the window.
A visual editor opens where you can select the tools you need.
Select the latest version available for Arm Debugger and select the other tools you require.
The extension adds a vcpkg-configuration.json file to your project and includes the tools that you selected in the file. You can also update the file manually. Click the vcpkg-configuration.json tab to display the file contents.
For example, the following file activates the Arm Debugger engine. In this configuration, vcpkg resolves * to the latest Arm Debugger version available.
{
"registries": [
{
"name": "arm",
"kind": "artifact",
"location": "https://artifacts.tools.arm.com/vcpkg-registry"
}
],
"requires": {
"arm:debuggers/arm/armdbg": "*"
}
}
Save your changes.
The Arm Tools Environment Manager extension activates the workspace and downloads the tools specified in the vcpkg-configuration.json file. After installation, tools are available on the PATH for the activated workspace in Visual Studio Code.
The status bar shows No Arm License if no valid user-based license is active. In this case, click No Arm License and select Activate or manage Arm licenses in the drop-down list at the top of the window.
Manage your license with the Arm License Management Utility.
Define a run configuration and run a project on your board
To flash a program onto your hardware, you must first configure a task. Visual Studio Code uses a tasks.json configuration file to run projects. Use the Run Configuration visual editor to select options. Alternatively, you can add the configuration manually in the tasks.json file.
Note: This procedure assumes that you already built either a PDSC file or an AXF or ELF file using your toolchain.
To define a run configuration and run a project on your board:
Open the Command Palette. Search for Tasks: Configure Task and then select it.
Select the arm-debugger.flash: Flash Device task (or Flash Device).
Visual Studio Code creates a tasks.json file in the .vscode folder of your project with the following default configuration:
{
"version": "2.0.0",
"tasks": [
{
"type": "arm-debugger.flash",
"connectionAddress": "${command:device-manager.getSerialNumber}",
"programs": ["${command:arm-debugger.getApplicationFile}"],
"cmsisPack": "${command:cmsis-csolution.getDfpName}",
"deviceName": "${command:cmsis-csolution.getDeviceName}",
"processorName": "${command:cmsis-csolution.getProcessorName}",
"label": "arm-debugger.flash: Flash Device"
}
]
}
To open the Run Configuration visual editor, either:
Click the Open in editor code lens above the configuration. The Enable Code Lens Arm Debugger setting enables code lenses by default.
Click the Open Arm Run Configuration button  in the top right-hand corner of the text editor.
Use the visual editor to enter the following details:
Save your changes.
The editor adds the options that you select to the tasks.json file.
To run the project on your board:
Note: When you run a task for the first time, Visual Studio Code asks you to select a scanning option for the task output. Select the Continue without scanning the task output option in the drop-down list.
- If you are using a multicore device and you did not specify a
"processorName" in the tasks.json file, select the appropriate processor for your device in the Select a processor drop-down list at the top of the window.
Visual Studio Code downloads the project to the board and starts it.
Check the download progress in the Terminal tab.
Define and start a debug connection
Visual Studio Code uses a launch.json configuration file to define debugger settings. You can use the Debug Configuration visual editor to choose configuration options, or manually edit the launch.json file.
For more information about inspecting OS threads during a debug session, see OS awareness.
Arm Debugger Launch
With the Arm Debugger Launch option, you can start your program in debug mode using various configurations that support both physical and virtual targets.
Physical targets
Select the Hardware debug connection option, then select:
Built-in platform option: Connect to an off-the-shelf development board or a platform defined in the Arm Debugger configuration database. This option provides a pre-defined, integrated debug setup, and adds an "arm-debugger.configdb" configuration with a "launch" request to the launch.json file.
CMSIS-Pack device option: Connect using a CMSIS-Pack, specifically a Device Family Pack (DFP) provided by silicon vendors. This method requires a *.csolution.yml file specifying the target device, compiler, and debug settings. It adds an "arm-debugger" configuration with a "launch" request to the launch.json file.
Virtual targets
Select the Model debug connection option to use Fixed Virtual Platform (FVP) models to debug virtual targets. This adds an "arm-debugger.configdb" configuration with a "launch" request to the launch.json file.
Arm Debugger Attach
With the Arm Debugger Attach option, you can attach to an existing debug connection. This adds an "arm-debugger" configuration with an "attach" request to the launch.json file. Unlike launch configurations, you must configure this type manually and cannot use the visual editor.
Work with a physical target
To define and start a debug connection:
Open the Command Palette. Search for Debug: Add Configuration... and then select it.
Select Arm Debugger in the drop-down list that displays.
Select Arm Debugger Launch > Hardware debug connection > Built-in platform option.
Check the name of the configuration and press the Enter key.
Visual Studio Code creates a launch.json file in the .vscode folder of your project with the following default configuration:
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Arm Debugger Built-in Platform",
"type": "arm-debugger.configdb",
"request": "launch",
"cdbEntry": "<Select platform>",
"connectionAddress": "<Enter address>"
}
]
}
To open the Debug Configuration visual editor, either:
Click the Open in editor code lens above the configuration. The Enable Code Lens Arm Debugger setting enables code lenses by default.
Click the Open Arm Debug Configuration button in the top right-hand corner of the text editor.
Use the visual editor to enter the following details:
Save your changes.
The editor adds the options that you select to the launch.json file.
To start a debug session, click the Start debugging button in the top right-hand corner of the Debug Configuration visual editor.
The debug session starts. The debugger stops at the location that you specified in Run Control.
To see the debugger log output and use advanced debugger functionality with command-line interface commands, check the Debug Console tab.
CMSIS-Pack device option
To define and start a debug connection:
Open the Command Palette. Search for Debug: Add Configuration... and then select it.
Select Arm Debugger in the drop-down list that displays.
Select Arm Debugger Launch > Hardware debug connection > CMSIS-Pack device option.
Check the name of the configuration and press the Enter key.
Visual Studio Code creates a launch.json file in the .vscode folder of your project with the following default configuration:
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Arm Debugger",
"type": "arm-debugger",
"request": "launch",
"connectionAddress": "${command:device-manager.getSerialNumber}",
"programs": [
"${command:arm-debugger.getApplicationFile}"
],
"cmsisPack": "${command:cmsis-csolution.getDfpName}",
"deviceName": "${command:cmsis-csolution.getDeviceName}",
"processorName": "${command:cmsis-csolution.getProcessorName}"
}
]
}
To open the Debug Configuration visual editor, either:
Click the Open in editor code lens above the configuration. The Enable Code Lens Arm Debugger setting enables code lenses by default.
Click the Open Arm Debug Configuration button in the top right-hand corner of the text editor.
Use the visual editor to enter the following details:
Save your changes.
The editor adds the options that you select to the launch.json file.
To start a debug session, click the Start debugging button in the top right-hand corner of the Debug Configuration visual editor.
The debug session starts. The debugger stops at the location that you specified in Run Control.
To see the debugger log output and use advanced debugger functionality with command-line interface commands, check the Debug Console tab.
Work with a virtual target
Note: FVPs are natively available on Windows and Linux only. If you are on a Mac, you can run FVPs in a Linux container with Docker. To install Docker and clone the https://github.com/Arm-Examples/FVPs-on-Mac repository, follow this Arm Developer Learning Path.
To define and start a debug connection:
To debug a virtual target using FVPs, you must install the models locally. The list of available FVPs depends on the version of Arm Debugger specified in the vcpkg-configuration.json file for your project. Arm Debugger includes a configuration database that provides access to these FVPs.
Note: For Arm® Cortex®-M based on Fast Models, add "arm:models/arm/avh-fvp": "<version>" in the "requires": section of the vcpkg-configuration.json file for your project.
Open the Command Palette. Search for Debug: Add Configuration... and then select it.
Select Arm Debugger in the drop-down list that displays.
Select Arm Debugger Launch > Model debug connection option.
Check the name of the configuration and press the Enter key.
Visual Studio Code creates a launch.json file in the .vscode folder of your project with the following default configuration:
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Connect to Model",
"type": "arm-debugger.configdb",
"request": "launch",
"cdbEntry": "<Configuration database string of model to connect>"
}
]
}
To open the Debug Configuration visual editor, either:
Click the Open in editor code lens above the configuration. The Enable Code Lens Arm Debugger setting enables code lenses by default.
Click the Open Arm Debug Configuration button in the top right-hand corner of the text editor.
Use the visual editor to enter the following details:
Save your changes.
The editor adds the options you select to the launch.json file.
To start a debug session:
If you are on a Mac, make sure Docker is running.
Click the Start debugging button in the top right-hand corner of the Debug Configuration visual editor.
The debug session starts. The debugger stops at the location that you specified in Run Control.
To see the debugger log output and use advanced debugger functionality with command-line interface commands, check the Debug Console tab.
Attach to an existing connection
To attach to an existing connection:
Open the Command Palette. Search for Debug: Add Configuration... and then select it.
Select Arm Debugger in the drop-down list that displays.
Select the Arm Debugger Attach option.
Check the name of the configuration and press the Enter key.
Visual Studio Code creates a launch.json file in the .vscode folder of your project with the following default configuration:
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Arm Debugger (Attach)",
"type": "arm-debugger",
"request": "attach",
"debuggerAddress": "Websocket (ws://<host>:<port>) or socket (<host>:<port>) to connect to"
}
]
}
In the launch.json file, specify the address of the Arm Debugger process that you want to connect to. Use ws://<host>:<port> for a WebSocket connection or <host>:<port> for a plain socket connection.
Save your changes.
To attach to the debug connection:
The extension attaches to the running debug connection.
OS awareness
OS awareness enables Arm Debugger to interpret operating system (OS) information during a debug session. This feature is useful when you debug software running on an RTOS or an embedded Linux system.
When you enable OS awareness, Arm Debugger can identify the threads that the OS creates and display them in the Call Stack view. Each thread displays with its own call stack, allowing you to understand what each thread is doing when the target stops.
Depending on the OS and debugger support, you can:
- View OS threads and their call stacks in the Call Stack view
- Identify which thread is currently executing
- See what other threads are doing (for example, running, waiting, or delayed) based on their call stacks
- Recognize OS activity such as delays, waits, or queue operations through RTOS functions that display in the stack (for example,
osDelay, osThreadFlagsWait, or message queue APIs)
You can select a thread in the Call Stack view to change the debugging context. When you select a thread, views such as Variables and Registers update to reflect the execution state of that thread.
OS awareness enables you to debug multitasking software at the OS level rather than only at the processor level, without manually inspecting raw memory.
Supported operating systems
OS awareness is available for the following operating systems:
- FreeRTOS
- Keil® CMSIS-RTOS RTX
- NXP MQX
- Nucleus
- PikeOS
- RTXC
- ThreadX
- Wind River VxWorks
- eForce µC3 Compact
- eForce µC3 Standard
- embOS
- μC/OS-II
- μC/OS-III
Note: OS awareness depends on the target processor architecture. Some operating systems are not supported on all architectures.
Limitations
Arm® CoreSight™ trace is a capability of the Arm Debugger engine that is not yet exposed in Visual Studio Code.
Submit feedback or report issues
To submit feedback or report issues on the Arm Debugger extension, please use GitHub issues in the extension repository.
| |
