I2C Slave RTOS Driver

This driver can be used to instantiate and control an I2C slave I/O interface on xcore in an RTOS application.

I2C Slave API

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

typedef struct rtos_i2c_slave_struct rtos_i2c_slave_t

Typedef to the RTOS I2C slave driver instance struct.

typedef void (*rtos_i2c_slave_start_cb_t)(rtos_i2c_slave_t *ctx, void *app_data)

Function pointer type for application provided RTOS I2C slave start callback functions.

These callback functions are optionally called by an I2C slave driver’s thread when it is first started. This gives the application a chance to perform startup initialization from within the driver’s thread.

Parameters

  • ctx – A pointer to the associated I2C slave driver instance.

  • app_data – A pointer to application specific data provided by the application. Used to share data between this callback function and the application.

typedef void (*rtos_i2c_slave_rx_cb_t)(rtos_i2c_slave_t *ctx, void *app_data, uint8_t *data, size_t len)

Function pointer type for application provided RTOS I2C slave receive callback functions.

These callback functions are called when an I2C slave driver instance has received data from a master device.

Parameters

  • ctx – A pointer to the associated I2C slave driver instance.

  • app_data – A pointer to application specific data provided by the application. Used to share data between this callback function and the application.

  • data – A pointer to the data received from the master.

  • len – The number of valid bytes in data.

typedef size_t (*rtos_i2c_slave_tx_start_cb_t)(rtos_i2c_slave_t *ctx, void *app_data, uint8_t **data)

Function pointer type for application provided RTOS I2C slave transmit start callback functions.

These callback functions are called when an I2C slave driver instance needs to transmit data to a master device. This callback must provide the data to transmit and the length.

Parameters

  • ctx – A pointer to the associated I2C slave driver instance.

  • app_data – A pointer to application specific data provided by the application. Used to share data between this callback function and the application.

  • data – A pointer to the data buffer to transmit to the master. The driver sets this to its internal data buffer, which has a size of RTOS_I2C_SLAVE_BUF_LEN, prior to calling this callback. This may be set to a different buffer by the callback. The callback must fill this buffer with the data to send to the master.

Returns

The number of bytes to transmit to the master from data. If the master reads more bytes than this, the driver will wrap around to the start of the buffer and send it again.

typedef void (*rtos_i2c_slave_tx_done_cb_t)(rtos_i2c_slave_t *ctx, void *app_data, uint8_t *data, size_t len)

Function pointer type for application provided RTOS I2C slave transmit done callback functions.

These callback functions are optionally called when an I2C slave driver instance is done transmitting data to a master device. A buffer to the data sent and the actual number of bytes sent are provided to the callback.

The application may want to use this, for example, if the buffer that was sent was malloc’d. This callback can be used to free the buffer.

Parameters

  • ctx – A pointer to the associated I2C slave driver instance.

  • app_data – A pointer to application specific data provided by the application. Used to share data between this callback function and the application.

  • data – A pointer to the data transmitted to the master.

  • len – The number of bytes transmitted to the master from data.

void rtos_i2c_slave_start(rtos_i2c_slave_t *i2c_slave_ctx, void *app_data, rtos_i2c_slave_start_cb_t start, rtos_i2c_slave_rx_cb_t rx, rtos_i2c_slave_tx_start_cb_t tx_start, rtos_i2c_slave_tx_done_cb_t tx_done, unsigned interrupt_core_id, unsigned priority)

Starts an RTOS I2C slave driver instance. This must only be called by the tile that owns the driver instance. It must be called after starting the RTOS from an RTOS thread.

rtos_i2c_slave_init() must be called on this I2C slave driver instance prior to calling this.

Parameters

  • i2c_slave_ctx – A pointer to the I2C slave driver instance to start.

  • app_data – A pointer to application specific data to pass to the callback functions.

  • start – The callback function that is called when the driver’s thread starts. This is optional and may be NULL.

  • rx – The callback function to receive data from the bus master.

  • tx_start – The callback function to transmit data to the bus master.

  • tx_done – The callback function that is notified when transmits are complete. This is optional and may be NULL.

  • interrupt_core_id – The ID of the core on which to enable the I2C interrupt.

  • priority – The priority of the task that gets created by the driver to call the callback functions.

void rtos_i2c_slave_init(rtos_i2c_slave_t *i2c_slave_ctx, uint32_t io_core_mask, const port_t p_scl, const port_t p_sda, uint8_t device_addr)

Initializes an RTOS I2C slave driver instance. This must only be called by the tile that owns the driver instance. It should be called before starting the RTOS, and must be called before calling rtos_i2c_slave_start().

Parameters

  • i2c_slave_ctx – A pointer to the I2C slave driver instance to initialize.

  • io_core_mask – A bitmask representing the cores on which the low level I2C I/O thread created by the driver is allowed to run. Bit 0 is core 0, bit 1 is core 1, etc.

  • p_scl – The port containing SCL. This must be a 1-bit port and different than p_sda.

  • p_sda – The port containing SDA. This must be a 1-bit port and different than p_scl.

  • device_addr – The 7-bit address of the slave device.

RTOS_I2C_SLAVE_BUF_LEN

The maximum number of bytes that a the RTOS I2C slave driver can receive from a master in a single write transaction.

RTOS_I2C_SLAVE_CALLBACK_ATTR

This attribute must be specified on all RTOS I2C slave callback functions provided by the application.

struct rtos_i2c_slave_struct
#include <rtos_i2c_slave.h>

Struct representing an RTOS I2C slave driver instance.

The members in this struct should not be accessed directly.