Renode API

Server

The server's implementation can be found in this repository in src/Renode/Network/ExternalControl/ExternalControlServer.cs.

Besides building Renode from source, the server can be also dynamically compiled into Renode from the Monitor with i @ExternalControlServer.cs assuming the current directory contains the source file.

From the Monitor, the server can be started with:

emulation CreateExternalControlServer "<NAME>" <PORT>

Client

The client's header, library and examples can be found under tools/external_control_client and all further paths starting with ./ will be relative to this directory.

Header

The Renode API header file is ./include/renode_api.h.

Library

The Renode API library sources can be found in the ./lib directory.

The currently implemented functions from the header file are:

  • renode_connect
  • renode_disconnect
  • renode_run_for
  • renode_error_free

The library itself can be built with CMake using the ./lib/CMakeLists.txt. librenode_api.a can be built in the build directory from the Renode repository's root directory with:

renode$ mkdir build && cmake -S tools/external_control_client/lib -B build && cmake --build build

Building

Besides building a library and linking a client to the library, a client can be built with CMake using ./CMakeLists.txt. CMake variables can be used to set:

  • application name (APP_NAME)
  • path to the directory containing sources (APP_SOURCES_DIR)
  • compile flags (optional APP_COMPILE_FLAGS; the default is -Wall;-Wextra;-Werror)

For example, example_client application with sources in ~/example_client/src directory can be built in the build directory from the Renode repository's root directory with:

renode$ mkdir build && cmake -DAPP_NAME=example_client -DAPP_SOURCES_DIR=~/example_client/src -S tools/external_control_client -B build && cmake --build build

run_for example

The example application using Renode API can be found in examples/run_for.

It can be built in the build directory from the Renode repository's root directory with:

renode$ mkdir build && cmake -DAPP_NAME=run_for -DAPP_SOURCES_DIR=tools/external_control_client/examples/run_for -S tools/external_control_client -B build && cmake --build build

After starting the server in Renode, the run_for application can be used multiple times to progress emulation time.

The usage is:

Usage:
  ./test_run_for <PORT> <VALUE_WITH_UNIT>
  where:
  * <VALUE_WITH_UNIT> is an integer with a time unit, e.g.: '100ms'
  * accepted time units are 's', 'ms' and 'us' (for microseconds)