Why We Are Discussing ItTo put it bluntly, the most frustrating aspects of embedded debugging are connection issues, visibility problems, inaccurate breakpoints, and chaotic logs. cortex-debug acts like a tool that collects these fragmented issues and assembles them into a smooth workflow. It’s not magic, but it truly transforms VSCode into a powerful debugging platform for Cortex-M, making it much easier to use.
What is cortex-debug?In simple terms: it is an extension for VSCode used to debug ARM Cortex-M series MCUs. It interfaces with common GDB servers (J-Link, OpenOCD, ST-LINK, pyOCD, Black Magic Probe, etc.) and gdb, providing functionalities such as register access, memory inspection, disassembly, SWO/RTT output, graphical ITM data representation, and RTOS thread views. It supports multi-core and multi-session debugging and allows for custom ITM decoders, making it quite flexible.
What Pain Points Does It Address?
- • Unified debugging experience: No need to switch IDEs; VSCode handles everything in one place.
- • Support for various probes: Whether you have J-Link, ST-Link, or CMSIS-DAP, you can connect them all.
- • Visual SWO/RTT: ITM/RTT outputs that previously required old tools for parsing can now be viewed directly as text and graphs.
- • Combined register and disassembly view: You can directly see instructions where the source code is not visible, allowing for finer granularity in breakpoints and stepping.
- • RTOS support: Threads are visible in the CALL STACK, making scheduling analysis more convenient (Note: Avoid stepping arbitrarily before the scheduler when debugging RTOS, as it may crash the gdb-server).
Installation and Usage (Key Points)First, let’s discuss dependencies (don’t rush to install the extension yet):
- • ARM GCC Toolchain (arm-none-eabi-gdb)
- • At least one GDB Server must be installed: J-Link, OpenOCD, ST-LINK GDB server, pyOCD, Black Magic Probe, or texane/stlink (st-util, limited functionality)
- • VSCode + cortex-debug extension
Quick Installation Steps (Concise Version)
| Step | Command / Action |
| 1 | Install ARM GCC (arm-none-eabi) |
| 2 | Install the corresponding GDB server (e.g., SEGGER J-Link, OpenOCD) |
| 3 | Install the cortex-debug extension in VSCode |
| 4 | Create .vscode/launch.json in your project, select the Cortex Debug configuration, and fill in properties like serverType, device, executable, armToolchainPath, etc. |
| 5 | Connect the debugger and start Debug (F5) |
Common Key Fields in launch.json (Informal Tips):
- • serverType: “jlink”, “openocd”, “stlink”, “pyocd”, “blackmagic”
- • device: MCU model, e.g., “STM32F407VG”
- • executable: path to the elf file
- • svdFile: peripheral SVD (optional, makes the peripheral viewer more user-friendly)
- • showDevDebugOutput: true (allows you to see gdb-server output)
If you want to compile the source code or debug the extension locally, you can git clone the source code, run npm install, and then run npm watch in VSCode.
Pros / Cons (Clear Overview)
| Pros | Cons |
| Supports various probes and gdb-servers, good compatibility | Some gdb-servers (like older versions of OpenOCD / st-util) may report incomplete registers, limiting functionality |
| SWO/RTT text and graphical display, customizable ITM decoding | ETM (trace via SWO) decoding is not supported |
| Multi-core, multi-session, RTOS thread view | Debugging RTOS can be tricky initially (stepping may cause gdb-server to crash) |
| Highly configurable (many properties in launch.json) | Initial configuration requires familiarity with various servers and paths, slightly higher barrier to entry |
| Integrated into VSCode, unified workflow | Some edge features depend on other mcu-debug organization extensions |
Conclusioncortex-debug has transformed VSCode into a very user-friendly debugging environment for Cortex-M developers: supporting multiple probes, various output formats, RTOS capabilities, and rich visualization tools. The main challenge lies in environment configuration (GCC, OpenOCD/J-Link, etc.), but once set up, daily debugging becomes much smoother. For engineers who prefer VSCode and seek a unified toolchain, I highly recommend giving it a try.
Project Address: https://github.com/Marus/cortex-debug