External control client¶

Renode exposes an API server that can be used to control the emulation programatically using the External control client library. Latest building instructions and example descriptions can be found in the README file in Renode’s repository.

Macros¶

NO_ERROR¶

NO_ERROR()

All the functions return a pointer to the renode_error_t structure in case of an error. Its memory has to be freed in case it’s handled. NULL returned indicates success.

Enumerations¶

renode_error_code_t¶

enum renode_error_code_t

Error codes

renode_time_unit_t¶

enum renode_time_unit_t

Supported time units

renode_access_width_t¶

enum renode_access_width_t

Supported access width options

Typedefs¶

renode_t¶

using renode_t = struct renode

Renode connection API handle.

Renode handles are pointers to structs implemented internally which must be prepared by calling renode_get_X functions (renode_connect() for renode_t) so that they can be later used in their related functions.

Struct internals aren’t part of the API.

renode_machine_t¶

using renode_machine_t = struct renode_machine

Renode machine API handle.

Renode handles are pointers to structs implemented internally which must be prepared by calling renode_get_X functions (renode_connect() for renode_t) so that they can be later used in their related functions.

Struct internals aren’t part of the API.

renode_adc_t¶

using renode_adc_t = struct renode_adc

Renode ADC peripheral API handle.

Renode handles are pointers to structs implemented internally which must be prepared by calling renode_get_X functions (renode_connect() for renode_t) so that they can be later used in their related functions.

Struct internals aren’t part of the API.

renode_gpio_t¶

using renode_gpio_t = struct renode_gpio

Renode GPIO controller API handle.

Renode handles are pointers to structs implemented internally which must be prepared by calling renode_get_X functions (renode_connect() for renode_t) so that they can be later used in their related functions.

Struct internals aren’t part of the API.

renode_bus_context_t¶

using renode_bus_context_t = struct renode_bus_context

Renode bus manager API handle.

Renode handles are pointers to structs implemented internally which must be prepared by calling renode_get_X functions (renode_connect() for renode_t) so that they can be later used in their related functions.

Struct internals aren’t part of the API.

Functions¶

renode_connect¶

renode_error_t * renode_connect(const char * port, renode_t ** renode)

Function initializing Renode connection.

Parameters¶

• port TCP port

• renode Renode connection handle pointer

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_disconnect¶

renode_error_t * renode_disconnect(renode_t ** renode)

Function closing Renode connection and freeing internal handle memory.

Parameters¶

• renode Renode connection handle pointer

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_machine¶

renode_error_t * renode_get_machine(renode_t * renode, const char * name, renode_machine_t ** machine)

Function preparing machine handle.

Parameters¶

• renode Renode connection handle

• name name of the machine to fetch

• machine Renode machine handle

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_free_error¶

void renode_free_error(renode_error_t * error)

Function deallocating error structure’s memory.

The function should be run every time any of the functions return a valid error structure pointer. By default, those functions return NULL.

Parameters¶

• error error structure

renode_run_for¶

renode_error_t * renode_run_for(renode_t * renode, renode_time_unit_t unit, uint64_t value)

Function ordering emulation to run for a specified time.

Parameters¶

• renode Renode connection handle

• unit value argument’s time unit

• value virtual time the emulation should run for (in the specified unit)

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_current_time¶

renode_error_t * renode_get_current_time(renode_t * renode, renode_time_unit_t unit, uint64_t * current_time)

Function getting current emulation virtual time.

Parameters¶

• renode Renode connection handle

• unit requested time unit of the output value

• current_time current emulation virtual time (in the requested unit)

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_adc¶

renode_error_t * renode_get_adc(renode_machine_t * machine, const char * name, renode_adc_t ** adc)

Function preparing ADC handle.

Parameters¶

• machine machine handle

• name ADC peripheral’s name

• adc handle associated with the requested ADC peripheral

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_adc_channel_count¶

renode_error_t * renode_get_adc_channel_count(renode_adc_t * adc, int32_t * count)

Function getting a number of channels ADC has.

Parameters¶

• adc ADC handle

• count number of channels

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_adc_channel_value¶

renode_error_t * renode_get_adc_channel_value(renode_adc_t * adc, int32_t channel, uint32_t * value)

Function getting ADC channel’s value.

Parameters¶

• adc ADC handle

• channel ADC channel index

• value current ADC channel value

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_set_adc_channel_value¶

renode_error_t * renode_set_adc_channel_value(renode_adc_t * adc, int32_t channel, uint32_t value)

Function setting ADC channel’s value.

Parameters¶

• adc ADC handle

• channel ADC channel index

• value requested ADC channel value

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_gpio¶

renode_error_t * renode_get_gpio(renode_machine_t * machine, const char * name, renode_gpio_t ** gpio)

Function preparing GPIO controller handle.

Parameters¶

• machine machine handle

• name GPIO controller’s name

• gpio handle associated with the requested GPIO controller

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_gpio_state¶

renode_error_t * renode_get_gpio_state(renode_gpio_t * gpio, int32_t id, bool * state)

Function getting state of GPIO.

Parameters¶

• gpio GPIO controller handle

• id GPIO’s index in the given GPIO controller

• state current GPIO state

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_set_gpio_state¶

renode_error_t * renode_set_gpio_state(renode_gpio_t * gpio, int32_t id, bool state)

Function setting state of GPIO.

Parameters¶

• gpio GPIO controller handle

• id GPIO’s index in the given GPIO controller

• state requested GPIO state

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_register_gpio_state_change_callback¶

renode_error_t * renode_register_gpio_state_change_callback(renode_gpio_t * gpio, int32_t id, void * user_data, void(*)(void *, renode_gpio_event_data_t *) callback)

Function registering callback when GPIO state changes.

Parameters¶

• gpio GPIO controller handle

• id GPIO’s index in the given GPIO controller

• user_data pointer to data passed to the callback when it’s invoked

• callback callback to be invoked when state of GPIO with the given index changes

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_bus_context¶

renode_error_t * renode_get_bus_context(renode_machine_t * machine, const char * name, renode_bus_context_t ** ctx)

Function preparing bus handle with emulation element context.

The context is used to imitate bus accesses made by specific bus managers like CPU, DMA, etc. "sysbus" can be passed as name if bus accesses should be made with global context.

Please note that accesses made using a handle with emulation element context still need to use absolute addresses so they’re equivalent to Renode’s sysbus Read<width> <address> context=<name> rather than <name> Read<width> <address> which treates addresses as relative to <name> peripheral’s registration base address.

Parameters¶

• machine machine handle

• name emulation element’s name in which context bus accesses should be made

• ctx handle for making bus accesses with context of the specified emulation element

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_get_sysbus¶

renode_error_t * renode_get_sysbus(renode_machine_t * machine, renode_bus_context_t ** sysbus)

Function preparing bus handle with global context.

This is just a convenience wrapper equivalent to renode_get_bus_context() with name="sysbus".

Parameters¶

• machine machine handle

• sysbus handle for making bus accesses with global context

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_sysbus_read¶

renode_error_t * renode_sysbus_read(renode_bus_context_t * ctx, uint64_t address, renode_access_width_t width, void * buffer, uint32_t count)

Function reading data from bus.

Parameters¶

• ctx bus handle

• address read’s absolute address

• width read’s width

• buffer buffer for the read data

• count number of requested reads (total data size will be width * count)

Returns¶

a pointer to error structure if error occurred, otherwise NULL

renode_sysbus_write¶

renode_error_t * renode_sysbus_write(renode_bus_context_t * ctx, uint64_t address, renode_access_width_t width, const void * buffer, uint32_t count)

Function writing data to bus.

Parameters¶

• ctx bus handle

• address access absolute address

• width access width

• buffer buffer with data to write to bus

• count number of requested writes (total data size is width * count)

Returns¶

a pointer to error structure if error occurred, otherwise NULL

Structures¶

renode_error_t¶

#include <renode_api.h>

struct renode_error_t

Structure describing status of a finished operation

Public Attributes¶

code¶

renode_error_code_t code

Error code

flags¶

int flags

Error flags, currently only used internally

message¶

char * message

Error message

data¶

void * data

Error data, currently unused

renode_gpio_event_data_t¶

#include <renode_api.h>

struct renode_gpio_event_data_t

GPIO state changed event data

Public Attributes¶

timestamp_us¶

uint64_t timestamp_us

Virtual time in microseconds

state¶

bool state

New GPIO state