blob: 7817bd81008ee8f77b03e6d5c299516f4ed984c3 [file] [log] [blame] [view]
# 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:
```bash
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:
```bash
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:
```bash
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)
```