Developing Renode

Renode has many built-in features to enable debugging of embedded software, e.g. debugging with GDB, but sometimes you might be interested in debugging Renode itself, especially if you are involved in its development

Debugging with GDB

To start debugging Renode and its components using GDB, follow these steps:

  1. Build Renode in debug configuration.

    ./ -d
  2. Launch Renode using Mono with the debugger enabled.

    ./renode -d
  3. Connect to Renode via the Mono debugger, e.g. using VS Code

  4. Attach GDB to a running Renode process to also debug implementation of cores (in C via GDB). GDB requires specific commands due to Mono using signals for flow control. The most important command is:

    handle SIGXCPU SIG33 SIG35 SIG36 SIG37 SIGPWR nostop noprint

VS Code configurations

Visual Studio Code’s extensive plugin ecosystem provides a good developer experience for working with the Renode codebase. You may decide to use either the official VS Code app from Microsoft or use one of the OSS binary releases VSCodium or code-server. The main difference between the official and OSS releases is that they use different extensions gallery, so some extensions may be unavailable for each version.

When launching Renode in VS Code, you can use several ready-to-use configurations (as defined in the launch.json file):

  • Launch - Release - equivalent to running ./ and ./renode from the console.

  • Launch - Debug - builds Renode in the Debug configuration (./ -d) and launches it under the Mono debugger.

  • (gdb) Tlib Attach - required to connect to a previously launched instance of Renode via GDB to debug translation libraries (implementation of emulated cores).

These configurations require the following VS Code extensions:

Launching Renode and debugging

By following the steps below, you will be able to add regular breakpoints in Renode, both in C# and C code.

  1. Use the Launch - Debug configuration. It may take a while, as it builds Renode in the debug configuration.

  2. When Renode starts, load the platform with a CPU whose code you wish to debug.

  3. Use the (gdb) Tlib Attach configuration to connect with GDB.

  4. Once started, a popup will appear. In the popup, type in mono.

  5. From the drop-down list, select the option beginning with /usr/bin/mono --debug --debuger-agent=..., as highlighted in the screenshot below.

VSCode Mono drop-down list

Figure 1 VSCode Mono drop-down list

Useful VS Code extensions

Below, you can find a list of VS Code extensions that may prove useful when working with Renode:


Some of these extensions may require additional configuration depending on your machine’s setup. Tlib should be first built with CMake to generate the compile_commands.json file for clangd language services.

Last update: 2023-12-01