Home

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. Note: This does not have to be ARM specific, it can be anything but we are historically built for a 32-bit ARM embedded device`
• cortex-debug.armToolchainPrefix - Historically, the prefix was just arm-none-eabi for our use case and this is our 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 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.

Supported Debug Servers/Probes

• Segger J-Link GDB Server (https://www.segger.com/) (https://wiki.segger.com/J-Link_Visual_Studio_Code). Make sure you use the JLinkGDBServerCL.exe or JLinkGDBServerCLexe and not the GUI versions
• STMicroelectronic's ST-LINK GDB server supplied as part of the STM32CubeIDE (https://www.st.com/resource/en/user_manual/dm00613038-stm32cubeide-stlink-gdb-server-stmicroelectronics.pdf)
• PE-Micro GDB Server (http://www.pemicro.com)
• Texane's St-Link Utils (https://github.com/stlink-org/stlink)
• Black Magic Probe Embedded GDB server (https://github.com/blacksphere/blackmagic/wiki)
• PyOCD (https://github.com/mbedmicro/pyOCD)
• OpenOCD (Note: Please use the latest version, 0.11.0 when writing this, prebuilt binaries for Windows)
  • Many vendors (ST, Cypress/Infineon) ship their own modified versions of OpenOCD. You must use their version to be fully compatible with their devices
• QEMU Emulated Environment
• Renode Emulated Environment (https://renode.io)

Publications with configuration examples you may find useful

• VSCode ARM Cortex-M debugging
• Cortex-Debug for Visual Studio Code
• Cortex-debug debugger introduction
• A Deep Dive into ARM Cortex-M Debug Interfaces
• How to use VSCode to build a SIG MESH development environment