CLion 2019.3 Help

Embedded GDB Server

To debug on-chip with GDB server, use the dedicated Embedded GDB Server run/debug configuration which covers the following use cases:

  • ST-Link GDB servers (you can find the open-source version of the tools on GitHub).

  • Segger J-Link GDB server.

  • Qemu as a GDB server.

  • OpenOCD as a standalone GDB server, as an alternative to OpenOCD Download & Run configuration.

  • Any other boards or specific GDB stubs that comply with the GDB server protocol.

Currently, this configuration works with CMake-based projects only.

Required tools

  1. Toolchain

    The Embedded GDB Server configuration requires the cross-compiler toolchain to be configured in advance.

    For ARM Cortex-M and Cortex-R MCUs, install GNU ARM toolchain. After the installation, make sure the toolchain is presented in the system PATH: run arm-none-eabi-gcc from the command line, and your system should recognize this command.

    For all other platforms, install the platform-specific toolchain and set up the tools in Settings/Preferences | Build, Execution, Deployment | Toolchain or in your CMake script (take a look at the template CMakeLists.txt).

    Also, you need to provide the linker file: obtain it from your chip vendor or create it manually, and specify through CMake settings.

    If you are working with an STM32CubeMX project, installing the GNU ARM toolchain is a part of the project set up, and CubeMX generates the linker file automatically.

  2. GDB client

    GDB client is the debugger that runs on CLion's side and connects to the remote GDB server. You can use either the bundled GDB or your toolchain's debugger as a GDB client.

    By default, the configuration employs the debugger selected in the toolchain of the current CMake profile. You can check or change it in the Debugger field of the toolchain that is chosen in Settings/Preferences | Build, Execution, Deployment | CMake.

  3. GDB server

    The chosen GDB server should be installed on your machine. There is no need to launch it manually - the configuration will run the GDB server automatically when you start a debug session.

Create an Embedded GDB Server configuration

Go to Run | Edit Configurations, click icons general add and select Embedded GDB Server.

Embedded GDB Server configuration

Configure the following settings:

  • 'target remote' args

    Provide the medium to carry debugging packets (serial line or an IP network using TCP or UDP). See gdb documentation for more details on connecting to a remote target.

  • GDB Server

    Specify the binary to be used as GDB server.

  • GDB Server args

    Provide the GDB server-specific arguments (for example, port number or board config file).

  • Advanced options: reset command

    The command to be sent when you press MCU reset during a debug session.

  • Advanced options: startup delay

    The amount of time CLion will wait after starting the GDB server before attempting to connect.

Debug an Embedded GDB Server configuration

When you Debugicons actions startDebugger this configuration, CLion performs a sequence of steps:

  1. Start GDB server with the specified environment.

  2. Wait until the configured startup delay time passes.

  3. Start GDB client and connect to the GDB server.

  4. Upload the binary as specified by the Download option in the configuration settings.

  5. Start the debug session.

    At this point, you can use all the CLion debugging features for your firmware running on-chip:

    Notice the MCU reset button on the left-hand bar of the Debugger tool window. When pressed, it sends the chip reset command specified in the Reset command field of the configuration settings.

Last modified: 20 February 2020