Home - Marus/cortex-debug GitHub Wiki

Cortex-Debug is an extension to add debugging capabilities for ARM Cortex-M devices to Visual Studio Code.

Please read the Overview page to understand this extension and the debugging process better. Especially important for advanced/custom use cases.

VSCode Settings for Cortex-Debug

There are dozens of options that are global or workspace settings. While most of them can be overridden in your launch.json, please don't jump to configuring your launch.json with hard coded path-names, etc., before reviewing these settings. They are settings for this extension and some are inherited/overridable by your launch.json configurations. There are two key settings we need for this extension to even function

  • cortex-debug.armToolchainPath - there are many versions of this for customization for each OS. This is the directory that contains all the GNU toolchain executables. There are many, and currently, we rely on gdb, objdump, and nm. Maybe different in the future.
    • You don't need this setting if all the GNU executables are already in your PATH and have the default prefix. If they are not in your path, then ABSOLUTE Paths maybe required.
    • Note: This doesn't have to be ARM specific, it can be anything but we are historically built for a 32-bit ARM embedded device` Naming of the setting is historical
  • cortex-debug.armToolchainPrefix - Historically, the prefix was just arm-none-eabi for our use case is the default. But that has been changing and there are far too many distributions with custom builds/prefixes, so you may have to customize this. We foresee a suffix coming as well. If you are familiar with Linux Kernel Builds this is effectively the value of $(CROSS_COMPILE). As a simple test: Open a command prompt, and type: arm-none-eabi-gdb - if that works, then the gdb debugger is in your $PATH, if not - you will need to use the absolute path

If we cannot find the required GNU tools, then debugging is not possible.

There are a LOT of customizations possible but following the above will simplify your getting started. There is no one-size-fits-all for how to configure all your dependent tools. Consider using symlinks on platforms that allow them.

There are other settings (both VSCode and launch.json) that you can carefully tailor to your needs. But the above two are what we recommend.

Please review all of the other settings and this list will evolve. It is a place to look to see if you have a setting that is a bit more global than one launch configuration. launch.json may not always be your friend, especially in a team environment. Workspace or User settings are generally more appropriate.

** For "workspace" settings, a handy trick is to use a small shell script or batch file or your Makefile to create or customize your launch.json file via your Makefile.

Supported Debug Servers/Probes/gdb-servers

See very custom example

Most people don't have to do this if they are using standard ARM tools, but you can debug many types of MCUs by customizing your launch.json

// FILE:  ${workspaceRoot}/.vscode/launch.json
{
   // The cwd for debug sessions is the top of my source tree.
   "cwd" : "${workspaceRoot}"
   // Path from {workspaceRoot} to your ELF file it might be placed elsewhere.
   "executable": "Build/debug.d/app_riscv_test.debug.elf",
   // For humans in the VSCODE selection window give this a human friendly name
   "name": "debug with OpenOCD",
   // in this example: tools are not in the path, so absolute paths are required.
   // in this example: debugging RiscV on a MicroSemi PolarfireFPGA using a tool chain from Microsemi.
   "gdbPath" : "/tools/Microchip/SoftConsole-v2021.1/riscv-unknown-elf-gcc/bin/riscv64-unknown-elf-gdb",
   // cortex-debug requires a few more tools then just GDB.
   // This is the prefix for those tools, ie: Like Linux kernel: NM=$(CROSS_COMPILE)nm 
   "toolchainPrefix" : "/tools/Microchip/SoftConsole-v2021.1/riscv-unknown-elf-gcc/bin/riscv64-unknown-elf-",
   // I this example the author develops on a Linux machine (Linux Server in a data center not locally on a laptop)
   // The physical target (a Polarfire FPGA development board) is local to the laptop via USB
   // And - OpenOCD is launched locally on the laptop via a batch file specific to the board & laptop or lab-computer
   // Thus VS CODE does not launch OpenOCD, and the servertype is "external", not "openocd"
   "servertype" : "external",  
   // Need to tell GDB how to talk to openocd, often it is: "localhost:3333" or an IP address, ie: "10.23.42.220:3333" 
   // GDB sees this as: "target remote HOSTNAME:PORT" - this needs to match your OpenOCD invocation.
   // Change "mylaptop.mycompany.local" to a name that works for you (or hard code the IP address yuck but it works)
   "gdbTarget": "mylaptop.mycompany.local:3333",
   // attach to a running target and halt (Handy if your code has hung)
   // Hint: In the gdb prompt/console, type 3 commands: 
   //   "load" to load your application, program counter will be at the reset vector.
   //   "tbreak main" - sets a temporary breakpoint at main.
   //   "continue" - target runs/executes-opcodes and should break at main.
   //    Or - if you can step through (and debug) faulty startup code.
   "request" : "attach"
}

Publications with configuration examples you may find useful (HELP NEEDED)

Sorry to say, many links below are outdated and/or need new references/updates

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️