GNU source level debugger for Visual Studio Code

This extension for Visual Studo Code enables debugging of bare metal C/C++ programs for microcontrollers. The extension implements the Visual Studio Code debug adaptor for Arm embedded processors. This extension is suited for macOS, Linux and Window.

The adaptor uses the GNU source level debugger (GDB) that enables examination of your running program. You can find background documentation about the GNU source level debugger here.

Dependencies

• GDB client from GNU toolchain for you operating system (one of the following)
  • GNU Arm embedded toolchain for macOS
  • GNU Arm embedded toolchain for Linux (64-bit)
  • GNU Arm embedded toolchain for Windows
• GDB server for your debug probe (one of the following)
  • SEGGER J-Link probe
  • ST-Link debug probe upgraded to J-Link probe

If you have a development board with an onboard ST-Link debug probe you can upgrade the firmware to J-Link. More information for upgrading to J-Link may be found here.

Features

• source level debugging of C and C+++
• set / clear breakpoints
• pause / continue, step over, step into, step out, restart
• change variables
• watch expressions

Output format

Visual Studio Code has no standard way to set the format of variables. In this extension you can change the output format with a number prefix.

Use the following number prefixes:

• 0b = binary
• 0o = octal
• 0d = decimal
• 0x = hexadecimal
• 0n = natural (back to GDB default output format)

Custom variables

To view/change global variables on every debug session add a customVariables list to the launch.json.

Here is an example launch.json for the Infineon XMC 2Go a low cost board with an Arm Cortex-M0 processor.

{
  // Visual Studio Code launch.json for XMC 2Go development board 
  "version": "0.2.0",
  "configurations": [
    {
      "type": "gnu-debugger",
      "request": "launch",
      "name": "GNU debugger",
      "program": "${workspaceFolder}/build.nosync/firmware.elf",
      "toolchain": "${config:arm-none-eabi.bin}",
      "client": "arm-none-eabi-gdb",
      "server": "JLinkGDBServer",
      "windows": {
        "server": "C:/Program Files/SEGGER/JLink_V632g/JLinkGDBServerCL.exe",
      },
      "serverArgs": [
        "-device", "XMC1100-0064",
        "-if", "SWD",
        "-speed", "4000"
      ],
      "serverPort": 2331,
      "customVariables": [
        "port0",
        "port1",
        "port2",
      ],
      "autoRun": false,
      "debugOutput": false,
      "preLaunchTask": "build firmware"
    }
  ]
}

Principle of operation

The extension uses the machine oriented text interface of the GNU source level debugger (GDB/MI). The adaptor translates workbench.action.debug commands to GDB/MI commands and translate GDB/MI outputs to graphical representation inside Visual Studio Code.

For Arm embedded platforms the GNU source level debugger consists of two parts:

• GDB client
• GDB server

Both programs must be installed on your development system.

GDB client

The GDB client is supplied by Arm free of charge as part of the Arm embedded toolchain. For convience I have packaged the latest toolchain for different operating systems as Visual Studio Code extension as mentioned in the dependencies section.

You can find GDB client for Arm embedded processors under the bin directory of the toolchain. The name of the GDB client program is:

• arm-none-eabi-gdb (macOS, Linux)
• arm-none-eabi-gdb.exe (Windows)

The GDB client communicates with a GDB server through a network connection (TCP/IP socket).

GDB server

The GDB server is supplied by the manufacterer of the debug probe. The most widely used lines of debug probes are the J-Link and ST-Link debug probes. The name of the SEGGER J-Link GDB server program is:

• JLinkGDBServer (macOS, Linux) (symbolic link, the actual command line program is JLinkGDBServerCLExe)
• JLinkGDBServerCL.exe (Windows)

If you have a development board with an onboard ST-Link debug probe you can upgrade the firmware to J-Link. More information for upgrading to J-Link may be found here.

OpenOCD

The Open On-Chip Debugger supports a large amount of debug probes. Starting from Version 0.0.5 you can use OpenOCD as GDB server.

Release Notes

Version 1.0.2

Updated several dependencies to the latest version.

Version 1.0.1

Removed depences on vscode and changed it to @types/vscode.

Version 1.0.0

Updated several dependencies.

Version 0.0.7

Added gdbCommands to support PSoC 6.

Version 0.0.5

OpenOCD support.

Version 0.0.4

Some of the dependencies required an update because they contained vulnerabilities. Changed several devDependencies.

Version 0.0.3

Changes in visual studio code 1.28.1 caused a problem. Updated all vscode dependencies to the latest version.

Version 0.0.2

Fixed a bug causing a error message "resource is not available". This problems shows when you have a source file compiled without debug information. Visual Studio code now shows "Unknown Source" if the debug information is missing.

Version 0.0.1

First version tested on macOS, Linux and Windows.