Intertile RTOS Driver

This driver allows for communication between AMP RTOS instances running on different xcore tiles.

Initialization API

The following structures and functions are used to initialize and start an intertile driver instance.

void rtos_intertile_start(rtos_intertile_t *intertile_ctx)

Starts an RTOS intertile driver instance. It may be called either before or after starting the RTOS, but must be called before any of the core intertile driver functions are called with this instance.

rtos_intertile_init() must be called on this intertile driver instance prior to calling this.

Parameters

intertile_ctx – A pointer to the intertile driver instance to start.

void rtos_intertile_init(rtos_intertile_t *intertile_ctx, chanend_t c)

Initializes an RTOS intertile driver instance. This must be called simultaneously on the two tiles establishing an intertile link. It may be called either before or after starting the RTOS, but must be called before calling rtos_intertile_start() or any of the core RTOS intertile functions with this instance.

This establishes a new streaming channel between the two tiles, using the provided non-streaming channel to bootstrap this.

Parameters

  • intertile_ctx – A pointer to the intertile driver instance to initialize.

  • c – A channel end that is already allocated and connected to channel end on the tile with which to establish an intertile link. After this function returns, this channel end is no longer needed and may be deallocated or used for other purposes.

struct rtos_intertile_t
#include <rtos_intertile.h>

Struct representing an RTOS intertile driver instance.

The members in this struct should not be accessed directly.

struct rtos_intertile_address_t
#include <rtos_intertile.h>

Struct to hold an address to a remote function, consisting of both an intertile instance and a port number. Primarily used by the RPC mechanism in the RTOS drivers.

Core API

The following functions are the core intertile driver functions that are used after it has been initialized and started.

void rtos_intertile_tx_len(rtos_intertile_t *ctx, uint8_t port, size_t len)
size_t rtos_intertile_tx_data(rtos_intertile_t *ctx, void *data, size_t len)
void rtos_intertile_tx(rtos_intertile_t *ctx, uint8_t port, void *msg, size_t len)

Transmits data to an intertile link.

Parameters

  • ctx – A pointer to the intertile driver instance to use.

  • port – The number of the port to send the data to. Only the thread listening on this particular port on the remote tile will receive this data.

  • msg – A pointer to the data buffer to transmit.

  • len – The number of bytes from the buffer to transmit.

size_t rtos_intertile_rx_len(rtos_intertile_t *ctx, uint8_t port, unsigned timeout)
size_t rtos_intertile_rx_data(rtos_intertile_t *ctx, void *data, size_t len)
size_t rtos_intertile_rx(rtos_intertile_t *ctx, uint8_t port, void **msg, unsigned timeout)

Receives data from an intertile link.

Note

the buffer returned via msg must be freed by the application using rtos_osal_free().

Note

It is important that no other thread listen on this port simultaneously. If this happens, it is undefined which one will receive the data, and it is possible for a resource exception to occur.

Parameters

  • ctx – A pointer to the intertile driver instance to use.

  • port – The number of the port to listen for data on. Only data sent to this port by the remote tile will be received.

  • msg – A pointer to the received data is written to this pointer variable. This buffer is obtained from the heap and must be freed by the application using rtos_osal_free().

  • timeout – The amount of time to wait before data become available.

Returns

the number of bytes received.