I2C Master RTOS Driver

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

I2C Master Initialization API

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

typedef struct rtos_i2c_master_struct rtos_i2c_master_t

Typedef to the RTOS I2C master driver instance struct.

void rtos_i2c_master_start(rtos_i2c_master_t *i2c_master_ctx)

Starts an RTOS I2C master driver instance. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before any of the core I2C master driver functions are called with this instance.

rtos_i2c_master_init() must be called on this I2C master driver instance prior to calling this.

Parameters

i2c_master_ctx – A pointer to the I2C master driver instance to start.

void rtos_i2c_master_init(rtos_i2c_master_t *i2c_master_ctx, const port_t p_scl, const uint32_t scl_bit_position, const uint32_t scl_other_bits_mask, const port_t p_sda, const uint32_t sda_bit_position, const uint32_t sda_other_bits_mask, hwtimer_t tmr, const unsigned kbits_per_second)

Initializes an RTOS I2C master driver instance. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before calling rtos_i2c_master_start() or any of the core I2C master driver functions with this instance.

Parameters

  • i2c_master_ctx – A pointer to the I2C master driver instance to initialize.

  • p_scl – The port containing SCL. This may be either the same as or different than p_sda.

  • scl_bit_position – The bit number of the SCL line on the port p_scl.

  • scl_other_bits_mask – A value that is ORed into the port value driven to p_scl both when SCL is high and low. The bit representing SCL (as well as SDA if they share the same port) must be set to 0.

  • p_sda – The port containing SDA. This may be either the same as or different than p_scl.

  • sda_bit_position – The bit number of the SDA line on the port p_sda.

  • sda_other_bits_mask – A value that is ORed into the port value driven to p_sda both when SDA is high and low. The bit representing SDA (as well as SCL if they share the same port) must be set to 0.

  • tmr – This is unused and should be set to 0. This will be removed.

  • kbits_per_second – The speed of the I2C bus. The maximum value allowed is 400.

struct rtos_i2c_master_struct
#include <rtos_i2c_master.h>

Struct representing an RTOS I2C master driver instance.

The members in this struct should not be accessed directly.

I2C Master Core API

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

inline i2c_res_t rtos_i2c_master_write(rtos_i2c_master_t *ctx, uint8_t device_addr, uint8_t buf[], size_t n, size_t *num_bytes_sent, int send_stop_bit)

Writes data to an I2C bus as a master.

Parameters

  • ctx – A pointer to the I2C master driver instance to use.

  • device_addr – The address of the device to write to.

  • buf – The buffer containing data to write.

  • n – The number of bytes to write.

  • num_bytes_sent – The function will set this value to the number of bytes actually sent. On success, this will be equal to n but it will be less if the slave sends an early NACK on the bus and the transaction fails.

  • send_stop_bit – If this is non-zero then a stop bit will be sent on the bus after the transaction. This is usually required for normal operation. If this parameter is zero then no stop bit will be omitted. In this case, no other task can use the component until a stop bit has been sent.

Returns

  • <tt>I2C_ACK</tt> – if the write was acknowledged by the device.

  • <tt>I2C_NACK</tt>otherwise. –

inline i2c_res_t rtos_i2c_master_read(rtos_i2c_master_t *ctx, uint8_t device_addr, uint8_t buf[], size_t n, int send_stop_bit)

Reads data from an I2C bus as a master.

Parameters

  • ctx – A pointer to the I2C master driver instance to use.

  • device_addr – The address of the device to read from.

  • buf – The buffer to fill with data.

  • n – The number of bytes to read.

  • send_stop_bit – If this is non-zero then a stop bit. will be sent on the bus after the transaction. This is usually required for normal operation. If this parameter is zero then no stop bit will be omitted. In this case, no other task can use the component until a stop bit has been sent.

Returns

  • <tt>I2C_ACK</tt> – if the read was acknowledged by the device.

  • <tt>I2C_NACK</tt>otherwise. –

inline void rtos_i2c_master_stop_bit_send(rtos_i2c_master_t *ctx)

Send a stop bit to an I2C bus as a master.

This function will cause a stop bit to be sent on the bus. It should be used to complete/abort a transaction if the send_stop_bit argument was not set when calling the rtos_i2c_master_read() or rtos_i2c_master_write() functions.

Parameters

ctx – A pointer to the I2C master driver instance to use.

inline i2c_regop_res_t rtos_i2c_master_reg_write(rtos_i2c_master_t *ctx, uint8_t device_addr, uint8_t reg_addr, uint8_t data)

Write to an 8-bit register on an I2C device.

This function writes to an 8-bit addressed, 8-bit register in an I2C device. The function writes the data by sending the register address followed by the register data to the device at the specified device address.

Parameters

  • ctx – A pointer to the I2C master driver instance to use.

  • device_addr – The address of the device to write to.

  • reg_addr – The address of the register to write to.

  • data – The 8-bit value to write.

Returns

  • <tt>I2C_REGOP_DEVICE_NACK</tt> – if the address is NACKed.

  • <tt>I2C_REGOP_INCOMPLETE</tt> – if not all data was ACKed.

  • <tt>I2C_REGOP_SUCCESS</tt> – on successful completion of the write.

inline i2c_regop_res_t rtos_i2c_master_reg_read(rtos_i2c_master_t *ctx, uint8_t device_addr, uint8_t reg_addr, uint8_t *data)

Reads from an 8-bit register on an I2C device.

This function reads from an 8-bit addressed, 8-bit register in an I2C device. The function reads the data by sending the register address followed reading the register data from the device at the specified device address.

Note that no stop bit is transmitted between the write and the read. The operation is performed as one transaction using a repeated start.

Parameters

  • ctx – A pointer to the I2C master driver instance to use.

  • device_addr – The address of the device to read from.

  • reg_addr – The address of the register to read from.

  • data – A pointer to the byte to fill with data read from the register.

Returns

  • <tt>I2C_REGOP_DEVICE_NACK</tt> – if the device NACKed.

  • <tt>I2C_REGOP_SUCCESS</tt> – on successful completion of the read.

I2C Master RPC Initialization API

The following functions may be used to share a I2C driver instance with other xcore tiles. Tiles that the driver instance is shared with may call any of the core functions listed above.

void rtos_i2c_master_rpc_client_init(rtos_i2c_master_t *i2c_master_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *host_intertile_ctx)

Initializes an RTOS I2C master driver instance on a client tile. This allows a tile that does not own the actual driver instance to use a driver instance on another tile. This will be called instead of rtos_i2c_master_init(). The host tile that owns the actual instance must simultaneously call rtos_i2c_master_rpc_host_init().

Parameters

  • i2c_master_ctx – A pointer to the I2C master driver instance to initialize.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as i2c_master_ctx.

  • host_intertile_ctx – A pointer to the intertile driver instance to use for performing the communication between the client and host tiles. This must have the same scope as i2c_master_ctx.

void rtos_i2c_master_rpc_host_init(rtos_i2c_master_t *i2c_master_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *client_intertile_ctx[], size_t remote_client_count)

Performs additional initialization on an I2C master driver instance to allow client tiles to use the I2C master driver instance. Each client tile that will use this instance must simultaneously call rtos_i2c_master_rpc_client_init().

Parameters

  • i2c_master_ctx – A pointer to the I2C master driver instance to share with clients.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as i2c_master_ctx.

  • client_intertile_ctx – An array of pointers to the intertile driver instances to use for performing the communication between the host tile and each client tile. This must have the same scope as i2c_master_ctx.

  • remote_client_count – The number of client tiles to share this driver instance with.

void rtos_i2c_master_rpc_config(rtos_i2c_master_t *i2c_master_ctx, unsigned intertile_port, unsigned host_task_priority)

Configures the RPC for an I2C master driver instance. This must be called by both the host tile and all client tiles.

On the client tiles this must be called after calling rtos_i2c_master_rpc_client_init(). After calling this, the client tile may immediately begin to call the core I2C master functions on this driver instance. It does not need to wait for the host to call rtos_i2c_master_start().

On the host tile this must be called both after calling rtos_i2c_master_rpc_host_init() and before calling rtos_i2c_master_start().

Parameters

  • i2c_master_ctx – A pointer to the I2C master driver instance to configure the RPC for.

  • intertile_port – The port number on the intertile channel to use for transferring the RPC requests and responses for this driver instance. This port must not be shared by any other functions. The port must be the same for the host and all its clients.

  • host_task_priority – The priority to use for the task on the host tile that handles RPC requests from the clients.