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. The extension can be used independently and is also compatible with other extensions included in the Keil Studio Pack.
The extension provides access to the Arm Debugger engine by implementing the Microsoft Debug Adapter Protocol (DAP).
The Arm Debugger engine supports connections to the following targets:
Physical targets: Either through external debugging, for example, Arm ULINK™ or DSTREAM debug probes, or through on-board low-cost debugging, for example, ST-Link or CMSIS-DAP based debug probes.
Virtual targets: Using Fixed Virtual Platform models (FVPs).
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
Debug virtual targets (FVPs)
Access the CLI using the Debug Console
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 models (FVPs), and debug probes see the Arm Debugger Release Note.
Prerequisites
You must install the Arm Debugger extension (identifier: arm.arm-debugger).
The following extensions are installed automatically alongside Arm Debugger:
Arm Tools Environment Manager (identifier: arm.environment-manager)
Arm Device Manager (identifier: arm.device-manager)
Arm CMSIS Solution (identifier: arm.cmsis-csolution)
Peripheral Inspector (identifier: eclipse-cdt.peripheral-inspector)
Memory Inspector (identifier: eclipse-cdt.memory-inspector)
To debug a virtual target using FVPs, you must have the models 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 extension
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 Install.
Arm Debugger and all the extensions contained in the Arm Debugger extension pack are installed 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 item 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.
A vcpkg-configuration.json file is added to your project and the tools that you selected are included 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.
{
"registries": [
{
"name": "arm",
"kind": "artifact",
"location": "https://artifacts.tools.arm.com/vcpkg-registry"
}
],
"requires": {
"arm:debuggers/arm/armdbg": "6.5.0"
}
}
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.
The status bar shows No Arm License if no valid UBL 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 download your code and run it on 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: In this procedure, it is assumed that you have 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}",
"program": "${command:arm-debugger.getApplicationFile}",
"cmsisPack": "${command:cmsis-csolution.getTargetPack}",
"deviceName": "${command:cmsis-csolution.getDeviceName}",
"processorName": "${command:cmsis-csolution.getProcessorName}",
"problemMatcher": [],
"label": "arm-debugger.flash: Flash Device"
}
]
}
To open the Run Configuration visual editor, either:
Click the Open in editor code lens above the configuration. Code lenses are enabled by default with the Enable Code Lens Arm Debugger setting.
Click Open Arm Run Configuration  in the top right-hand corner of the text editor.
Use the visual editor to enter the following details:
Save your changes.
The options that you select in the editor are added in 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.
The project is downloaded to the board and starts running.
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.
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 Hardware debug connection, then select:
Built-in platform: 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: 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 Model debug connection to use Fixed Virtual Platform models (FVPs) 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 a debug connection that is already established. 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.
Validate the name of the configuration and press Enter.
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. Code lenses are enabled by default with the Enable Code Lens Arm Debugger setting.
Click Open Arm Debug Configuration in the top right-hand corner of the text editor.
Use the visual editor to enter the following details:
Save your changes.
The options that you select in the editor are added in the launch.json file.
To start a debug session, click Start debugging 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.
Validate the name of the configuration and press Enter.
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}",
"program": "${command:arm-debugger.getApplicationFile}",
"cmsisPack": "${command:cmsis-csolution.getTargetPack}",
"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. Code lenses are enabled by default with the Enable Code Lens Arm Debugger setting.
Click Open Arm Debug Configuration in the top right-hand corner of the text editor.
Use the visual editor to enter the following details:
Save your changes.
The options that you select in the editor are added in the launch.json file.
To start a debug session, click Start debugging 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 have the models installed 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 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.
Validate the name of the configuration and press Enter.
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. Code lenses are enabled by default with the Enable Code Lens Arm Debugger setting.
Click Open Arm Debug Configuration in the top right-hand corner of the text editor.
Use the visual editor to enter the following details:
Save your changes.
The options you select in the editor are added in the launch.json file.
To start a debug session:
If you are on a Mac, make sure Docker is running.
Click Start debugging 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 Arm Debugger Attach.
Validate the name of the configuration and press Enter.
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",
"address": "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.
Limitations
Some capabilities of the Arm Debugger engine that are not yet exposed in Visual Studio Code include:
Submit feedback or report issues
To submit feedback or report issues on the Arm Debugger extension, please use GitHub issues in the extension repository.
| |
