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_get_current_time
  • 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 to progress emulation time multiple times with an ability to run it again and connect to the same server.

Following every executed set it will ask whether to continue with the current configuration, defaults to No. This prompt also has an option (c for change) to provide a new time value, using the same format as the CLI argument, with an optional new number of times to run, defaults to 1.

The usage is:

Usage:
  ./test_run_for <PORT> <VALUE_WITH_UNIT> [<REPEAT>]
  where:
  * <VALUE_WITH_UNIT> is an integer with a time unit, e.g.: '100ms'
  * accepted time units are 's', 'ms' and 'us' (for microseconds)
  * <REPEAT> is an optional number of times (default: 1) to run
  * the simulation for

adc example

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

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

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

After starting the server in Renode, the adc application can be used multiple times to set ADC channel 0 value.

The usage is:

Usage:
  ./adc <PORT> <MACHINE_NAME> <ADC_NAME> <VALUE_WITH_UNIT>
  where:
  * <VALUE_WITH_UNIT> is an unsigned integer with a voltage unit, e.g.: '100mV'
  * accepted voltage units are 'V', 'mV' and 'uV' (for microvolts)