I2C API Calls

i2c Config Struct

typedef struct{
       //Master/Slave mode
       //Number of cycle - 1 between each SDA/SCL sample
   u32 samplingClockDivider; 
       //Number of cycle - 1 after which an inactive frame is considered dropped.
   u32 timeout;              
       //Number of cycle - 1 SCL should be keept low (clock stretching) 
       //after having feed the data to the SDA to ensure a correct 
       //propagation to other devices
   u32 tsuDat;               
       //Master mode
       //SCL low (cycle count -1)
   u32 tLow;  
       //SCL high (cycle count -1)
   u32 tHigh; 
       //Minimum time between the Stop/Drop -> Start transition
   u32 tBuf;  
   } I2c_Config;

i2c_getFilteringHit()

Usage I2c_getFilteringHit(reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Returns [OUT] 2-bit output:
[0] indicates address hit for address setting 0.
[1] indicates address hit for address setting 1.
Description Read the 32-bit I2C register filter hit to register filter hit with a call back function.
Return 1 on a specific bit if the filter address is enabled and the address received from the master is tallied with the target address settings for target address 0 (0 x 88) and target address 1 (0 x 8C). Used for slave mode.
Example
if(i2c_getFilteringHit(I2C_CTRL) == 1); 
// Check if address 0 received is the expected address from master.

i2c_getFilteringStatus()

Usage I2c_getFilteringStatus(reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Returns [OUT] 1-bit output indicates the operation requested from master:
Return 1 indicates read operation requested.
Return 0 indicates write operation requested.
Description Read the operation requested from master. Used in slave mode.
Example
if(i2c_getFilteringStatus(I2C_CTRL) == 1); 
// Check filter hit value, bit [7] from slave address, 
// read =’1’ write =’0’

i2c_getInterruptFlag()

Usage I2c_getInterruptFlag(reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Returns [OUT] 32-bit interrupt flags:
[4] Start flag
[5] Restart flag
[6] End flag
[7] Drop flag
[15] Clock generation exit flag
[16] Clock generation enter flag
[17] Filter generation flag
Description Read the 32-bit I2C register interrupt flag.
Example
Int flag = i2c_getInterruptFlag(I2C_CTRL) & I2C_INTERRUPT_DROP;
// Get Drop interrupt flag from Interrupt register 

i2c_getMasterStatus()

Usage I2c_getMasterStatus(reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Returns [OUT] 32-bit current master status:
[0] I2C controller busy
[4] Start sequence in progress/requested
[5] Stop sequence in progress/requested
[6] Drop sequence in progress/requested
[7] Recover sequence in progress/requested
[9] Sequence dropped when executing start sequence
[10] Sequence dropped when executing stop sequence
[11] Sequence dropped when executing recover sequence
Description Read the 32-bit I2C register current master status.
Example
int status = i2c_getMasterStatus(I2C_CTRL) & I2C_MASTER_BUSY; 
// Get master busy status from status register 

i2c_getSlaveStatus()

Usage I2c_getSlaveStatus(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Returns [OUT] 32-bit current slave status:
[0] Indicates the slave is in frame. Start sequence executed. Required stop or drop sequence to exit from frame.
[1] Current state of SDA bus
[2] Current state of SCL bus
Description Read the I2C bus status. This function allows the software to obtain the current state of the SDA and SCL bus.

i2c_getSlaveOverride()

Usage I2c_getSlaveOverride(u32 reg, u32 value)
Parameters [IN] reg base address of specific I2C
[IN] value I2C slave override value
Include driver/i2c.h
Returns [OUT] 32-bit slave override setting:
[1] SDA bus override setting
[2] SCL bus override setting
Description Manually controls the state of SDA and SCL. Setting of zero will forcefully pull the bus low while setting of one will release the bus as the I2C bus is always in pull-up condition.

i2c_applyConfig()

Usage void i2c_applyConfig(u32 reg, I2c_Config *config)
Parameters [IN] reg base address of specific I2C
[IN] config struct of I2C configuration
Include driver/i2c.h
Description Apply I2C configuration to register or for initial configuration.

i2c_clearInterruptFlag()

Usage void i2c_clearInterruptFlag(u32 reg, u32 value)
Parameters [IN] reg base address of specific I2C
[IN] value I2C interrupt flag to reset
Note: Refer to "Interrupt Clears Register: 0x0000_0024" in the Sapphire RISC-V SoC Data Sheet and Sapphire High-Performance RISC-V SoC Data Sheet.
Include driver/i2c.h
Description Clear the I2C interrupt flag by setting the interrupt bit to 1.

i2c_disableInterrupt()

Usage void i2c_disableInterrupt(u32 reg, u32 value)
Parameters [IN] reg base address of specific I2C
[IN] value I2C interrupt register:
[0] I2C_INTERRUPT_RX_DATA
[1] I2C_INTERRUPT_RX_ACK
[2] I2C_INTERRUPT_TX_DATA
[3] I2C_INTERRUPT_TX_ACK
[4] I2C_INTERRUPT_START
[5] I2C_INTERRUPT_RESTART
[6] I2C_INTERRUPT_END
[7] I2C_INTERRUPT_DROP
[15] I2C_INTERRUPT_CLOCK_GEN_EXIT
[16] I2C_INTERRUPT_CLOCK_GEN_ENTER
[17] I2C_INTERRUPT_FILTER
Include driver/i2c.h
Description Disable I2C interrupt.
Example
i2c_disableInterrupt(I2C_CTRL, I2C_INTERRUPT_TX_ACK);
// Enable I2C interrupt  with interrupt TX Ack

i2c_enableInterrupt()

Usage void i2c_enableInterrupt(u32 reg, u32 value)
Parameters [IN] reg base address of specific I2C
[IN] value I2C interrupt register:
[0] I2C_INTERRUPT_RX_DATA
[1] I2C_INTERRUPT_RX_ACK
[2] I2C_INTERRUPT_TX_DATA
[3] I2C_INTERRUPT_TX_ACK
[4] I2C_INTERRUPT_START
[5] I2C_INTERRUPT_RESTART
[6] I2C_INTERRUPT_END
[7] I2C_INTERRUPT_DROP
[15] I2C_INTERRUPT_CLOCK_GEN_EXIT
[16] I2C_INTERRUPT_CLOCK_GEN_ENTER
[17] I2C_INTERRUPT_FILTER
Include driver/i2c.h
Description Enable I2C interrupt.
Example
i2c_enableInterrupt(I2C_CTRL, I2C_INTERRUPT_FILTER | I2C_INTERRUPT_DROP);
// Enable I2C interrupt with interrupt filter and drop

i2c_filterEnable()

Usage void i2c_filterEnable(u32 reg, u32 filterId, u32 config)
Parameters [IN] reg base address of specific I2C
[IN] filterID filter configuration ID number
[IN] config struct of I2C configuration:
  • [0] Filter address 0
  • [1] Filter address 1
Include driver/i2c.h
Description Enable the filter configuration.

i2c_listenAck()

Usage void i2c_listenAck(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Listen acknowledge from the slave.

i2c_masterBusy()

Usage int i2c_masterBusy(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Returns [OUT] Integer master busy status (1-bit):
Returns 0 indicates Master is available
Returns 1 indicates Master is busy/in progress
Description Get the I2C busy status.

i2c_masterStatus()

Usage int i2c_masterStatus(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Returns [OUT] 32-bit current master status:
[0] I2C controller busy
[4] Start sequence in progress/requested
[5] Stop sequence in progress/requested
[6] Drop sequence in progress/requested
[7] Recover sequence in progress/requested
[9] Sequence dropped when executing start sequence
[10] Sequence dropped when executing stop sequence
[11] Sequence dropped when executing recover sequence
Description Get the I2C status.

i2c_masterDrop()

Usage void i2c_masterDrop(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Change the I2C master to the drop state.
Example i2c_masterDrop(I2C_CTRL);

i2c_masterStart()

Usage void i2c_masterStart(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Assert start condition.

i2c_masterRestart()

Usage void i2c_masterRestart(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Restart the I2C master by sending a start condition.

i2c_masterStartBlocking()

Usage void i2c_masterStartBlocking(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Asserts a start condition and wait for the master to start the process.

i2c_masterRestartBlocking()

Usage void i2c_masterRestartBlocking(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Restart the I2C master by sending a start condition. Wait for the master to start the process.

i2c_masterStop()

Usage void i2c_masterStop(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Asserts a stop condition.

i2c_masterStopBlocking()

Usage void i2c_masterStartBlocking(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Asserts a stop condition and waits for the master to start the process.

i2c_masterStopWait()

Usage void i2c_masterStopWait(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Waits for the master to be available.

i2c_masterRecoverBlocking()

Usage void i2c_masterRecoverBlocking(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description To recover the slave, toggle the SCL bus until the slave releases the SDA bus,except for a timeout. This function will retry 3 times. This function may be used as a backup plan to ensure that the slave can be recovered if a transaction fails in between.

i2c_setFilterConfig()

Usage void i2c_setFilterConfig(u32 reg, u32 filterId, u32 value)
Parameters [IN] reg base address of specific I2C
[IN] filterID filter configuration ID number
[IN] value filter configuration register:
  • [0] Filter address 0
  • [1] Filter address 1
  • [9:0] I2C slave address
  • [14] I2C_FILTER_10BITS
  • [15] I2C_FILTER_ENABLE
Include driver/i2c.h
Description Set the filter configuration for selected filter ID.
Example
i2c_setFilterConfig(I2C_CTRL, 0, 0x30 | I2C_FILTER_ENABLE);
// Enable filter with ID=0 slave addr = 0x30 default 7 bit filter

i2c_txAck()

Usage void i2c_txAck(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Transmit acknowledge.

i2c_txAckBlocking()

Usage void i2c_txAckBlocking(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Transmit knowledge and wait for it to complete.

i2c_txAckWait()

Usage void i2c_txAckWait(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Wait for an acknowledge to transmit.

i2c_txByte()

Usage void i2c_txByte(u32 reg, u8 byte)
Parameters [IN] reg base address of specific I2C
[IN] byte 8 bits data to send out
Include driver/i2c.h
Description Transfers one byte to the I2C slave.

i2c_txByteRepeat()

Usage void i2c_txByteRepeat(u32 reg, u8 byte)
Parameters [IN] reg base address of specific I2C
[IN] byte 8 bits data to send out
Include driver/i2c.h
Description Send a byte in repeat mode.

i2c_txNack()

Usage void i2c_txNack(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Transfers a NACK.

i2c_txNackRepeat()

Usage void i2c_txNackRepeat(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Send a NACK in repeat mode.

i2c_txNackBlocking()

Usage void i2c_ txNackBlocking(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Transfer a NACK and wait for the completion.

i2c_rxAck()

Usage void i2c_rxAck(u32 reg)
Parameters [IN] reg base address of specific I2C
Returns [OUT] 1 bit acknowledge
Include driver/i2c.h
Description Receive an acknowledge from the I2C slave.

i2c_rxAckWait()

Usage void i2c_rxAck(u32 reg)
Parameters [IN] reg base address of specific I2C
Include driver/i2c.h
Description Waits for ACK signal from I2C slave.

i2c_rxData()

Usage u32 i2c_rxData(u32 reg)
Parameters [IN] reg base address of specific I2C
Returns [OUT] 1 byte data from I2C slave
Include driver/i2c.h
Description Receive one byte data from I2C slave.

i2c_rxNack()

Usage int i2c_rxNack(u32 reg)
Parameters [IN] reg base address of specific I2C
Returns [OUT] 1 bit no acknowledge. Return 1 if NACK is received.
Include driver/i2c.h
Description Receive no acknowledge from the I2C slave.

i2c_writeData_b()

Usage void i2c_writeData_b(u32 reg, u8 slaveAddr, u8 regAddr, u8 *data, u32 length)
Parameters [IN] reg base address of specific I2C
[IN] slaveAddr 8-bit slave address (left shift 1-bit)
[IN] regAddr 8-bit register address
[IN] data 8-bit write data pointer
[IN] length number of byte of data to be transmitted
Include driver/i2c.h
Description Write a number of data with 8-bit register address.

i2c_writeData_w()

Usage void i2c_writeData_w(u32 reg, u8 slaveAddr, u16 regAddr, u8 *data, u32 length)
Parameters [IN] reg base address of specific I2C
[IN] slaveAddr 8-bit slave address (left shift 1-bit)
[IN] regAddr 16-bit register address
[IN] data 8-bit write data pointer
[IN] length number of byte of data to be transmitted
Include driver/i2c.h
Description Write a number of data with 16-bit register address.

i2c_readData_b()

Usage void i2c_readData_b(u32 reg, u8 slaveAddr, u8 regAddr, u8 *data, u32 length)
Parameters [IN] reg base address of specific I2C
[IN] slaveAddr 8-bit slave address (left shift 1-bit)
[IN] regAddr 8-bit register address
[IN] data 8-bit read data pointer
[IN] length number of byte of data to be transmitted
Include driver/i2c.h
Description Read a number of data with 8-bit register address.

i2c_readData_w()

Usage void i2c_readData_w(u32 reg, u8 slaveAddr, u16 regAddr, u8 *data, u32 length)
Parameters [IN] reg base address of specific I2C
[IN] slaveAddr 8-bit slave address (left shift 1-bit)
[IN] regAddr 16-bit register address
[IN] data 8-bit read data pointer
[IN] length number of byte of data to be transmitted
Include driver/i2c.h
Description Read a number of data with 16-bit register address.

i2c_writeData_b_ack()

Usage void i2c_writeData_b_ack(u32 reg, u8 slaveAddr, u8 regAddr, u8 *data, u32 length)
Parameters [IN] reg base address of specific I2C
[IN] slaveAddr 8-bit slave address (left shift 1-bit)
[IN] regAddr 8-bit register address
[IN] data 8-bit write data pointer
[IN] length number of byte of data to be transmitted
Include driver/i2c.h
Description Write multiple data bytes using an 8-bit register address, with acknowledgment checking on receive (RX).

i2c_writeData_w_ack()

Usage void i2c_writeData_w_ack(u32 reg, u8 slaveAddr, u16 regAddr, u8 *data, u32 length)
Parameters [IN] reg base address of specific I2C
[IN] slaveAddr 8-bit slave address (left shift 1-bit)
[IN] regAddr 16-bit register address
[IN] data 8-bit write data pointer
[IN] length number of byte of data to be transmitted
Include driver/i2c.h
Description Write multiple data bytes using an 16-bit register address, with acknowledgment checking on receive (RX).

i2c_readData_b_ack()

Usage void i2c_readData_b_ack(u32 reg, u8 slaveAddr, u8 regAddr, u8 *data, u32 length)
Parameters [IN] reg base address of specific I2C
[IN] slaveAddr 8-bit slave address (left shift 1-bit)
[IN] regAddr 8-bit register address
[IN] data 8-bit read data pointer
[IN] length number of byte of data to be transmitted
Include driver/i2c.h
Description Read multiple data with 8-bit register address.

i2c_readData_w_ack()

Usage void i2c_readData_w_ack(u32 reg, u8 slaveAddr, u16 regAddr, u8 *data, u32 length)
Parameters [IN] reg base address of specific I2C
[IN] slaveAddr 8-bit slave address (left shift 1-bit)
[IN] regAddr 16-bit register address
[IN] data 8-bit read data pointer
[IN] length number of byte of data to be transmitted
Include driver/i2c.h
Description Read multiple data with 16-bit register address.