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.

Param ctx:

A pointer to the associated I2C slave driver instance.

Param 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.

Param ctx:

A pointer to the associated I2C slave driver instance.

Param app_data:

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

Param data:

A pointer to the data received from the master.

Param 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.

Param ctx:

A pointer to the associated I2C slave driver instance.

Param app_data:

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

Param 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.

Return:

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.

Param ctx:

A pointer to the associated I2C slave driver instance.

Param app_data:

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

Param data:

A pointer to the data transmitted to the master.

Param len:

The number of bytes transmitted to the master from data.

typedef void (*rtos_i2c_slave_rx_byte_check_cb_t)(rtos_i2c_slave_t *ctx, void *app_data, uint8_t data, i2c_slave_ack_t *cur_status)#

Function pointer type for application provided function to check bytes received from master individually.

This callback function is called once per byte received from the master device.

The application may want to use this, for example, to check byte by byte and force a NACK for an unexpected payload.

The user provided functions must be marked with RTOS_I2C_SLAVE_MASTER_SENT_BYTE_CHECK_CALLBACK_ATTR.

Param ctx:

A pointer to the associated I2C slave driver instance.

Param app_data:

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

Param data:

A copy of the most recent byte of data transmitted from the master.

Param cur_status:

A pointer to the current ACK/NACK response for this byte. The application may change this to I2C_SLAVE_ACK or I2C_SLAVE_NACK. If cur_status is returned as an invalid value, the driver will implicitly NACK.

typedef void (*rtos_i2c_slave_write_addr_request_cb_t)(rtos_i2c_slave_t *ctx, void *app_data, i2c_slave_ack_t *cur_status)#

Function pointer type for application provided function to alert application that there is a write transaction incoming from master

This allows an application to NACK if it is not ready for handling write requests.

The user provided functions must be marked with RTOS_I2C_SLAVE_WRITE_ADDR_REQUEST_CALLBACK_ATTR.

Param ctx:

A pointer to the associated I2C slave driver instance.

Param app_data:

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

Param cur_status:

A pointer to the current ACK/NACK response for this byte. The application may change this to I2C_SLAVE_ACK or I2C_SLAVE_NACK. If cur_status is returned as an invalid value, the driver will implicitly NACK. By default the driver will implicitly ACK.

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, rtos_i2c_slave_rx_byte_check_cb_t rx_byte_check, rtos_i2c_slave_write_addr_request_cb_t write_addr_req, 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.

  • rx_byte_check – The callback function to check received bytes individually.

  • write_addr_req – The callback function to alert an incoming write request

  • 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.

RTOS_I2C_SLAVE_RX_BYTE_CHECK_CALLBACK_ATTR#

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

RTOS_I2C_SLAVE_WRITE_ADDR_REQUEST_CALLBACK_ATTR#

This attribute must be specified on all RTOS I2C slave rtos_i2c_slave_write_addr_request_cb_t 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.