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.

MAX_CAN_FRAME_SIZE¶

MAX_CAN_FRAME_SIZE()

Maximum size of the CAN Frame in bytes, that the client can handle.

Enumerations¶

renode_error_code_t¶

enum renode_error_code_t

Possible error codes.

renode_time_unit_t¶

enum renode_time_unit_t

The supported time units.

renode_access_width_t¶

enum renode_access_width_t

The supported access width options.

renode_access_type_t¶

enum renode_access_type_t

The supported accesses to the Renode system bus.

Typedefs¶

renode_t¶

using renode_t = struct renode

The API handle for the Renode connection.

Renode handles are pointers to structs that are 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.

The internal structs are not a part of the API.

renode_machine_t¶

using renode_machine_t = struct renode_machine

The API handle for the Renode machine.

Renode handles are pointers to structs that are 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.

The internal structs are not a part of the API.

renode_adc_t¶

using renode_adc_t = struct renode_adc

The API handle for a Renode ADC peripheral.

Renode handles are pointers to structs that are 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.

The internal structs are not a part of the API.

renode_gpio_t¶

using renode_gpio_t = struct renode_gpio

The API handle for a Renode GPIO controller.

Renode handles are pointers to structs that are 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.

The internal structs are not a part of the API.

renode_can_t¶

using renode_can_t = struct renode_can

The API handle for a Renode CAN bus.

Renode handles are pointers to structs that are 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.

The internal structs are not a part of the API.

renode_bus_context_t¶

using renode_bus_context_t = struct renode_bus_context

The API handle for a Renode bus manager.

Renode handles are pointers to structs that are 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.

The internal structs are not a part of the API.

renode_fatal_error_callback_t¶

using renode_fatal_error_callback_t = void(*

A type of the Renode fatal error callback.

renode_spi_t¶

using renode_spi_t = struct renode_spi

The API handle for a Renode SPI peripheral.

Renode handles are pointers to structs that are 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.

The internal structs are not a part of the API.

renode_bus_peripheral_t¶

using renode_bus_peripheral_t = struct renode_bus_peripheral

The API handle for a Renode External Bus peripheral.

Renode handles are pointers to structs that are 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.

The internal structs are not a part of the API.

renode_time_t¶

using renode_time_t = uint64_t

Renode’s virtual time.

The virtual time is represented by an unsigned integer in an unspecified time unit. It is safe to perform comparision (<, >, <=, >=, !=, ==), addition (+, +=) and subtraction (-, -=) operations between two instances of renode_time_t.

Use renode_create_time(), renode_time_to_time_unit() or renode_time_to_seconds() to create or convert the virtual time.

renode_time_elapsed_callback_t¶

using renode_time_elapsed_callback_t =
    void (*)(void *ud, renode_time_t *timestamp);

The type of the Renode time-elapsed callback.

renode_custom_command_callback_t¶

using renode_custom_command_callback_t =
    renode_custom_command_response_data_t * (*)(
        void *ud, renode_custom_command_event_data_t *event_data);

renode_can_event_callback_t¶

using renode_can_event_callback_t = 
    void (*)(void *user_data, renode_can_event_data_t *event_data);

renode_sysbus_event_callback_t¶

using renode_sysbus_event_callback_t =
    void (*)(void *user_data, renode_sysbus_event_data_t *event_data);

renode_spi_transmit_callback_t¶

using renode_spi_transmit_callback_t =
    uint8_t (*)(void *user_data, uint8_t mosi);

The SPI transmit callback is invoked for every byte the master sends to the slave (MOSI). It returns the byte that the slave transmits on the bus in exchange (MISO).

Parameters¶

• user_data - the pointer passed at registration

• mosi - the byte received from the master

Returns¶

• the MISO byte to return to the master

renode_spi_finish_callback_t¶

using renode_spi_finish_callback_t =
    void (*)(void *user_data);

The SPI finish-transmission callback is invoked when the master ends the transfer (CS deasserted).

Parameters¶

• user_data - the pointer passed at registration

Functions¶

renode_connect¶

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

The function initializing the Renode connection.

Parameters¶

• port - the TCP port

• renode - the Renode connection handle pointer

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_disconnect¶

renode_error_t * renode_disconnect(renode_t ** renode)

The function closing the Renode connection and freeing the internal handle memory.

Parameters¶

• renode - the Renode connection handle pointer

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_disconnect_ex¶

renode_error_t * renode_disconnect_ex(renode_t ** renode, bool blocking)

The extended variant of the function to close the Renode connection and free the internal handle memory.

Parameters¶

• renode - the Renode connection handle pointer

• blocking - if false, the function may return an error with the code ERR_CONNECTION_BUSY to indicate that the connection cannot be closed at this momment due to the command handlers currently running. If true, this function will block in case of ERR_CONNECTION_BUSY being returned.

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_machine¶

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

The function preparing the machine handle.

Parameters¶

• renode - the Renode connection handle

• name - the name of the machine to fetch

• machine - the Renode machine handle

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_free_error¶

void renode_free_error(renode_error_t * error)

The function deallocating an 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 - the error structure

renode_set_fatal_error_callback¶

void renode_set_fatal_error_callback(renode_t * renode, void * user_data, renode_fatal_error_callback_t callback)

The function setting a callback to be called when the library encounters an unrecoverable error.

The callback can be used to perform any application-specific cleanup routines before the application terminates.

Parameters¶

• renode - the Renode connection handle

• user_data - the pointer to the data passed to the callback when invoked

• callback - the callback to be invoked when an unrecoverable error occurs

renode_create_time¶

renode_error_t * renode_create_time(uint64_t value, renode_time_unit_t unit, renode_time_t * time)

The function creating Renode’s virtual time value.

Parameters¶

• value - the time, expressed in the given unit

• unit - the unit in which the given time is expressed

• time - the Renode time instance

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_time_to_time_unit¶

uint64_t renode_time_to_time_unit(renode_time_t time, renode_time_unit_t unit)

The function converting Renode’s virtual time to an integer time value expressed in a specified unit.

Parameters¶

• time - the Renode time instance

• unit - the unit in which the given time is expressed (see renode_time_unit_t); the caller is responsible for ensuring that the passed unit is valid

Returns¶

A time value in a given unit.

renode_time_to_seconds¶

double renode_time_to_seconds(renode_time_t time)

The function converting Renode’s timestamp into seconds.

Parameters¶

• time - the Renode time instance

Returns¶

A floating-point timestamp equivalent in seconds.

renode_run_for¶

renode_error_t * renode_run_for(renode_t * renode, renode_time_t time)

The function specifying that the emulation should run for a given amount of time.

Parameters¶

• renode - the Renode connection handle

• time - the duration of virtual time that the emulation should execute for

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_current_time¶

renode_error_t * renode_get_current_time(renode_t * renode, renode_time_t * current_time)

The function fetching the current virtual time of the emulation.

Parameters¶

• renode - the Renode connection handle

• current_time - the current virtual time of the emulation

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_register_time_elapsed_callback¶

renode_error_t * renode_register_time_elapsed_callback(renode_t * renode, void * user_data, renode_time_elapsed_callback_t callback)

The function registering a callback that will be called after a quantum of time elapses in Renode.

Parameters¶

• renode - the Renode connection handle

• user_data - the pointer to the data passed to the callback when invoked

• callback - the callback to be invoked when a quantum of time elapses in Renode

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_adc¶

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

The function preparing the ADC handle.

Parameters¶

• machine - the machine handle

• name - the ADC peripheral’s name

• adc - the handle associated with the requested ADC peripheral

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_adc_channel_count¶

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

The function fetching the number of channels of the ADC.

Parameters¶

• adc - the ADC handle

• count - the number of the ADC channels

Returns¶

A pointer to the error structure if an 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)

The function fetching an ADC channel’s value.

Parameters¶

• adc - the ADC handle

• channel - the ADC channel index

• value - the current ADC channel value

Returns¶

A pointer to the error structure if an 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)

The function setting an ADC channel’s value.

Parameters¶

• adc - the ADC handle

• channel - the ADC channel index

• value - the requested ADC channel value

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_gpio¶

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

The function preparing the GPIO controller handle.

Parameters¶

• machine - the machine handle

• name - the name of the GPIO controller

• gpio - the handle associated with the requested GPIO controller

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_gpio_state¶

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

The function fetching the GPIO state.

Parameters¶

• gpio - the GPIO controller handle

• id - the GPIO’s index in the given GPIO controller

• state - the current GPIO state

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_set_gpio_state¶

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

The function setting the GPIO state.

Parameters¶

• gpio - the GPIO controller handle

• id - the GPIO’s index in the given GPIO controller

• state - the requested GPIO state

Returns¶

A pointer to the error structure if an 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)

The function registering the callback when the GPIO state changes.

Parameters¶

• gpio - the GPIO controller handle

• id - the GPIO’s index in the given GPIO controller

• user_data - the pointer to the data passed to the callback when invoked

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

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_register_custom_command_callback¶

renode_error_t * renode_register_custom_command_callback(renode_t * renode, void * user_data, renode_custom_command_callback_t callback)

The function registering callback on custom command. The callback function returns a pointer to the renode_custom_command_callback_t struct which it allocates. This pointer is freed in the invoke_callback function.

Parameters¶

• renode - the Renode handle

• user_data - the pointer to the data passed to the callback when invoked

• callback - the callback to be invoked when a custom command is issued

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_can¶

renode_error_t * renode_get_can(renode_machine_t * machine, const char * name, renode_can_t ** can)

The function preparing the CAN handle.

Parameters¶

• machine - the machine handle

• name - the CAN Bus peripheral name

• can - the handle associated with the requested CAN instance

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_register_can_callback¶

renode_error_t * renode_register_can_callback(renode_can_t * can, void * user_data, renode_can_event_callback_t callback)

The function registering the callback when a CAN message is received.

Parameters¶

• can - the CAN instance handle

• user_data - the pointer to the data passed to the callback when invoked

• callback - the callback to be invoked when a message is received

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_send_can_message¶

renode_error_t * renode_send_can_message(renode_can_t * can, void * packet, int packet_length, uint32_t packet_id)

The function sending a CAN message.

Parameters¶

• can - the CAN instance handle

• packet - the pointer to the CAN packet payload

• packet_length - the length of the packet to be sent

• packet_id - the packet ID

Returns¶

A pointer to the error structure if an 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)

The function preparing the bus handle with the emulation element context.

The context is used to imitate bus access 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 access made using a handle with the emulation element context still needs to use absolute addresses so they are equivalent to Renode’s sysbus Read<width> <address> context=<name> rather than <name> Read<width> <address>, which treats addresses as relative to <name> peripheral’s registration base address.

Parameters¶

• machine - the machine handle

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

• ctx - the handle for performing the bus access with the context of the specified emulation element

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_bus_context_name¶

renode_error_t * renode_get_bus_context_name(renode_bus_context_t * ctx, char ** name)

The function fetching the name of the bus context.

Parameters¶

• ctx - the bus context

• name - fully qualified name of the bus context in the format “.”, must be freed

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_sysbus¶

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

The function preparing the bus handle with global context.

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

Parameters¶

• machine - the machine handle

• sysbus - the handle for performing bus access with global context

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_byte_count¶

renode_error_t * renode_get_byte_count(renode_access_width_t width, uint32_t count, uint32_t * byte_count)

The function calculating the byte count from the given access width and transfer count.

Parameters¶

• width - the width of the transfer

• count - the count of the transfers

• byte_count - the count of accessed bytes

Returns¶

A pointer to the error structure if an 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)

The function reading data from the system bus.

Parameters¶

• ctx - the bus handle

• address - the absolute address of the read

• width - the width of the read

• buffer - the buffer for the read data

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

Returns¶

A pointer to the error structure if an 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)

The function writing data to the system bus.

Parameters¶

• ctx - the bus handle

• address - the absolute address of the access

• width - the access width

• buffer - the buffer with the data to write to the bus

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

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_get_bus_peripheral¶

renode_error_t * renode_get_bus_peripheral(renode_machine_t * machine, const char * name, renode_bus_peripheral_t ** bus_peripheral)

The function preparing the Bus peripheral handle.

The peripheral must be a Bus.ExternalControlBusPeripheral.

Parameters¶

• machine - the machine handle

• name - the Bus peripheral’s name

• bus_peripheral - the handle associated with the requested External Bus peripheral

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_register_sysbus_access_callback¶

renode_error_t * renode_register_sysbus_access_callback(renode_bus_peripheral_t * bus_peripheral, renode_access_type_t access_type, renode_access_width_t width, void * user_data, renode_sysbus_event_callback_t callback)

The function registering a callback when Renode’s system bus is accessed.

Parameters¶

• bus_peripheral - the platform peripheral handle

• access_type - the access types for which the callback will be invoked

• width - the widths for which the callback will be invoked

• user_data - the pointer to the data passed to the callback when invoked

• callback - the callback to be invoked when Renode’s system bus is accessed for the given access types and widths.

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

All callbacks should set renode_sysbus_event_data_t::access_succeeded to true. By default, it is false. If renode_sysbus_event_data_t::access_type is ::SYSBUS_READ, then the callback should set renode_sysbus_event_data_t::data to true. By default, it is all zeros, and can be ommited if the access doesn’t succeed.

renode_get_spi¶

renode_error_t * renode_get_spi(renode_machine_t * machine, const char * name, renode_spi_t ** spi)

The function preparing the SPI peripheral handle.

The peripheral must be a SPI.ExternalControlSPIPeripheral

Parameters¶

• machine -the machine handle

• name - the SPI peripheral name

• spi - the handle associated with the requested SPI peripheral

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

renode_spi_register_callbacks¶

renode_error_t * renode_spi_register_callbacks(renode_spi_t * spi, void * user_data, renode_spi_transmit_callback_t on_transmit, renode_spi_finish_callback_t on_finish)

The function registering live callbacks for an ExternalControlSPIPeripheral slave.

After registration, the callbacks fire, while the emulation advances (i.e. during renode_run_for()). on_transmit supplies the MISO byte for each master beat, and on_finish is notified at the end of a transfer.

Parameters¶

• spi - the SPI handle

• user_data - the pointer passed to both callbacks when invoked

• on_transmit - the callback returning the MISO byte for each received MOSI byte

• on_finish - the callback invoked when the transfer finishes (may be NULL)

Returns¶

A pointer to the error structure if an error occurred, otherwise NULL.

Structures¶

renode_error_t¶

#include <renode_api.h>

struct renode_error_t

The structure describing the 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_can_event_data_t¶

#include <renode_api.h>

struct renode_can_event_data_t

The CAN bus event data.

Public Attributes¶

time¶

renode_time_t time

The timestamp of when the packet was sent

packet_length¶

int32_t packet_length

The length of the CAN frame in bytes

packet_id¶

uint32_t packet_id

The ID of the CAN frame

packet¶

uint8_t packet

The payload of the CAN frame

renode_gpio_event_data_t¶

#include <renode_api.h>

struct renode_gpio_event_data_t

The GPIO state-change event data.

Public Attributes¶

time¶

renode_time_t time

The virtual time at which the event occured

state¶

bool state

The new GPIO state

renode_sysbus_event_data_t¶

#include <renode_api.h>

struct renode_sysbus_event_data_t

The structure storing information about an access event to Renode’s system bus.

Public Attributes¶

timestamp¶

renode_time_t timestamp

The timestamp of when the event occured

access_type¶

renode_access_type_t access_type

The read or write transaction

address¶

uint64_t address

The access address

width¶

renode_access_width_t width

The access width of a transfer

transfer_count¶

uint32_t transfer_count

The count of transfers of the width specified by renode_sysbus_event_data_t::width.

Use renode_get_byte_count() to calculate byte count.

access_succeeded¶

bool access_succeeded

The flag indicating that the access was successful

Public Methods¶

_Alignas¶

_Alignas(uint64_t)

The bytes that are written or will be read, allocated and freed by the library

renode_custom_command_event_data_t¶

#include <renode_api.h>

struct renode_custom_command_event_data_t

The custom command event data.

Public Attributes¶

time¶

renode_time_t time

The virtual time at which the event occured

command¶

char command

The command string

renode_custom_command_response_data_t¶

#include <renode_api.h>

struct renode_custom_command_response_data_t

The custom command user data

Public Attributes¶

command_valid¶

bool command_valid

The command valid flag

response_string¶

char response_string

The pointer to response string