How to Debug in Visual Studio Code#

This guide explains how to debug Zephyr applications using Visual Studio Code on Linux or macOS. You can also use other GDB-compatible environments. To enable debugging, install the Segger J-Link software pack, compile the jlink-zephyr library, enable debug information in your Zephyr project, and start the GDB server manually or through your debugger.

Install Segger J-Link Software Pack#

Download the package from: J-Link / J-Trace Downloads

Install jlink-zephyr library for J-Link Zephyr support#

Fetch the jlink-zephyr repository and compile the library:

    git clone https://github.com/zephyrproject-rtos/jlink-zephyr.git
    cd jlink-zephyr
    mkdir build && cd build
    cmake ..
    cmake --build .

Enable Debug Information in Your Zephyr Project#

Edit your project's prj.conf to include CONFIG_DEBUG_THREAD_INFO=y

Another configuration option, CONFIG_DEBUG_OPTIMIZATIONS=y, provides better visibility of variable values during debugging. However, this option should be used with caution because it disables compiler optimizations, which can lead to performance degradation and different runtime behavior.

Debug Configuration in Visual Studio Code#

To debug using Visual Studio Code and the Cortex-Debug plugin, create a debug configuration in the launch.json file.

The following example shows a Cortex-Debug configuration:

    {
        "version": "0.2.0",
        "configurations": [
        {
            "cwd": "${workspaceRoot}",
            "executable": "build/zephyr/zephyr.elf",
            "name": "Debug Microcontroller",
            "request": "launch",
            "type": "cortex-debug",
            "servertype": "jlink",
            "device": "EFR32MG29BxxxF1024",
            "armToolchainPath": "${env:HOME}/zephyr-sdk-0.17.0/armzephyr-eabi/bin",
            "toolchainPrefix": "arm-zephyr-eabi",
            "svdFile": "${workspaceRoot}/resources/EFR32MG29B140F1024IM40.svd",
            "serverArgs": ["-rtos", "${workspaceRoot}/jlinkzephyr/build/libzephyr_rtos.so"],
            "liveWatch": { "enabled": true, "samplesPerSecond": 4 }
        }
      ]
    }

Notes:

  • You can also remove or disable liveWatch if not used.

  • Using the System View Description (.svd) file is not mandatory but enables viewing MCU register contents.

  • The Zephyr SDK is frequently updated with new versions. You may need to adjust the path to the arm-zephyr-eabi toolchain in the configuration to match your installed SDK version (e.g., from zephyr-sdk-0.17.0 to a newer version).

Start the GDB Server Manually#

To start the GDB Server for command line debugging, use:

west debug --tool-opt="-rtos GDBServer/RTOSPlugin_Zephyr"

Note: Your debugger might start the server automatically.