Inter-Integrated Circuit (I2C)

Overview

Ameba series products support Philips I2C interface, which is a two-wire, low-speed, synchronous serial communication bus, supporting multi-master/multi-slave.

Features

  • Two-wire I2C serial interface: a serial data line (SDA) and a serial clock (SCL)

  • Master or Slave I2C operation

  • Transmitter or Receiver

  • Transmit and receive FIFOs with depth of 16 and width of 12-bit

  • Multi-master ability including bus arbitration scheme

  • 7-bit or 10-bit addressing mode

  • Clock stretch in master/slave mode

  • Supports General Call, NULL DATA, START BYTE transfer protocol

  • Component parameters for configurable software driver support (programmable SDA hold time, slave address, SCL duty cycle, etc.)

  • Filter to eliminate the glitches on the signal of SDA and SCL, programmable digital noise filter

  • Operation mode:

    • Polling

    • Interrupt

    • DMA mode

Speed Modes

Support three speed modes:

  • Standard Speed (SS), up to 100kbps

  • Fast Speed (FS), up to 400kbps

  • High Speed (HS), up to 3.4Mbps

Note

For more information about I2C IP clock and speed mode, please reference User Manual .

Operating Modes

I2C Configurable Operating Modes

Polling Mode

This is the most basic operating mode. The CPU polls the I2C status registers and reads or writes the FIFO buffer as needed to send and receive data.

Suited for small-scale data transfers with low real-time requirements.

Interrupt Mode

When configured trigger conditions are met, the I2C hardware sends an interrupt signal to notify the CPU to handle the relevant tasks.

This method reduces the need for frequent polling, lowering CPU usage and improving response speed.

DMA Mode

RTL8721Dx:

Through an I2C and DMA handshake mechanism, the DMA controller handles data transfers, reducing the CPU’s processing load.

Suitable for applications that require handling large amounts of data.

Note

For considerations when using DMA mode for transfers, please refer to the DMA and Cache section.

Application Examples

The SDK provides two types of functional examples to help developers understand and use I2C functionality:

  • Mbed Examples

    • Path: {SDK}\example\peripheral\mbed\I2C\{demo}

    • Demonstrates how to implement I2C control in the mbed environment.

  • Raw Examples

    • Path: {SDK}\example\peripheral\raw\I2C\{demo}

    • Illustrates how to directly control I2C without abstraction layers.

Below is a brief description of the features of the raw examples:

Note

To see which chips are supported by the examples, refer to the README.md file in the example’s path.

Raw API

I2C Exported Types

struct I2C_IntModeCtrl

I2C IntMode Structure Definition.

Public Members

void (*I2CSendSem)(u32 IsWrite)

Interface for releasing semaphores

void (*I2CWaitSem)(u32 IsWrite)

Interface for acquiring semaphores

I2C_TypeDef *I2Cx

Pointer to I2C peripheral registers

RTL8721Dx:
struct I2C_DevTable

I2C dev Table Definition.

Public Members

I2C_TypeDef *I2Cx

Pointer to I2C peripheral registers

IRQn_Type IrqNum

I2C interrupt request number

u32 Tx_HandshakeInterface

GDMA handshake interface for TX DMA

u32 Rx_HandshakeInterface

GDMA handshake interface for RX DMA

struct I2C_InitTypeDef

I2C Init Structure Definition.

Public Members

u32 I2CIdx

Specifies the I2C Device Index. This parameter should be 0

u32 I2CMaster

Specifies the I2C Role. This parameter can be a value of I2C Role Mode

u32 I2CAddrMod

Specifies the I2C Addressing Mode. This parameter can be a value of I2C Address Mode

u32 I2CSpdMod

Specifies the I2C Speed Mode. Now the circuit don’t support High Speed Mode. This parameter can be a value of I2C Speed Mode

u32 I2CRXTL

Specifies the I2C RX FIFO Threshold. It controls the level of entries(or above) that triggers the RX_FULL interrupt. This parameter must be set to a value in the 0-255 range. A value of 0 sets the threshold for 1 entry, and a value of 255 sets the threshold for 256 entry

u32 I2CTXTL

Specifies the I2C TX FIFO Threshold. It controls the level of entries(or below) that triggers the TX_EMPTY interrupt. This parameter must be set to a value in the 0-255 range. A value of 0 sets the threshold for 0 entry, and a value of 255 sets the threshold for 255 entry

u32 I2CMstReSTR

Specifies the I2C Restart Support of Master.

u32 I2CMstGC

Specifies the I2C General Call Support of Master.

u32 I2CMstStartB

Specifies the I2C Start Byte Support of Master.

u32 I2CSlvNoAck

Specifies the I2C Slave No Ack Support.

u32 I2CSlvAckGC

Specifies the I2C Slave Acks to General Call.

u32 I2CAckAddr

Specifies the I2C Target Address in I2C Master Mode or Ack Address in I2C Slave0 Mode. This parameter must be set to a value in the 0-127 range if the I2C_ADDR_7BIT is selected or 0-1023 range if the I2C_ADDR_10BIT is selected.

u32 I2CSlvSetup

Specifies the I2C SDA Setup Time. It controls the amount of time delay introduced in the rising edge of SCL relative to SDA changing by holding SCL low when I2C Device operating as a slave transmitter, in units of ic_clk period. This parameter must be set to a value in the 0-255 range. It must be set larger than I2CSdaHd

u32 I2CSdaHd

Specifies the I2C SDA Hold Time. It controls the amount of hold time on the SDA signal after a negative edge of SCL in both master and slave mode, in units of ic_clk period. This parameter must be set to a value in the 0-0xFFFF range.

u32 I2CClk

Specifies the I2C Bus Clock (in kHz). It is closely related to I2CSpdMod

u32 I2CIPClk

Specifies the I2C IP Clock (in Hz).

u32 I2CFilter

Specifies the I2C SCL/SDA Spike Filter.

u32 I2CTxDMARqLv

Specifies the I2C TX DMA Empty Level. dma_tx_req signal is generated when the number of valid data entries in the transmit FIFO is equal to or below the DMA Transmit Data Level Register. The value of DMA Transmit Data Level Register is equal to this value. This parameter must be set to a value in the 0-31 range.

u32 I2CRxDMARqLv

Specifies the I2C RX DMA Full Level. dma_rx_req signal is generated when the number of valid data entries in the transmit FIFO is equal to or above the DMA Receive Data Level Register. The value of DMA Receive Data Level Register is equal to this value+1. This parameter must be set to a value in the 0-31 range.

u32 I2CDMAMod

Specifies the I2C DMA Mode. This parameter can be a value of I2C DMA Mode

u32 I2CAckAddr1

Specifies the I2C Ack Address in I2C Slave1 Mode. I2C Slave1 only support I2C_ADDR_7BIT mode. This parameter must be set to a value in the 0-127 range.

I2C Exported Constants

I2C Address Mode

/* 7-bit addressing mode. */
#define I2C_ADDR_7BIT ((u32)0x00000000)

/* 10-bit addressing mode. */
#define I2C_ADDR_10BIT ((u32)0x00000001)

/* Check if I2C address mode value is valid. */
#define IS_I2C_ADDR_MODE (((MODE) == I2C_ADDR_7BIT) || \
    ((MODE) == I2C_ADDR_10BIT))

I2C Buffer Depth Mode

/* I2C TX/RX FIFO buffer depth in entries. */
#define I2C_TRX_BUFFER_DEPTH 16

I2C Role Mode

/* I2C operates in slave mode. */
#define I2C_SLAVE_MODE ((u32)0x00000000)

/* I2C operates in master mode. */
#define I2C_MASTER_MODE ((u32)0x00000001)

I2C Speed Mode

/* Standard speed mode (up to 100 kHz). */
#define I2C_SS_MODE ((u32)0x00000001)

/* Fast speed mode (up to 400 kHz). */
#define I2C_FS_MODE ((u32)0x00000002)

/* High speed mode (up to 3.4 Mbps). */
#define I2C_HS_MODE ((u32)0x00000003)

/* Check if I2C speed mode value is valid. */
#define IS_I2C_SPEED_MODE (((MODE) == I2C_SS_MODE) || \
    ((MODE) == I2C_FS_MODE) || \
    ((MODE) == I2C_HS_MODE))

I2C Timing Mode

/* Standard speed minimum SCL high time in ns. */
#define I2C_SS_MIN_SCL_HTIME 4600

/* Standard speed minimum SCL low time in ns. */
#define I2C_SS_MIN_SCL_LTIME 5400

/* Fast speed minimum SCL high time in ns. */
#define I2C_FS_MIN_SCL_HTIME 800

/* Fast speed minimum SCL low time in ns. */
#define I2C_FS_MIN_SCL_LTIME 1700

/* High speed minimum SCL high time, 100pF loading, in ns. Maximum supported speed: 3.4 MHz. */
#define I2C_HS_MIN_SCL_HTIME_100 100

/* High speed minimum SCL low time, 100pF loading, in ns. Maximum supported speed: 3.4 MHz. */
#define I2C_HS_MIN_SCL_LTIME_100 194

/* High speed minimum SCL high time, 400pF loading, in ns. Maximum supported speed: 1.7 MHz. */
#define I2C_HS_MIN_SCL_HTIME_400 200

/* High speed minimum SCL low time, 400pF loading, in ns. Maximum supported speed: 1.7 MHz. */
#define I2C_HS_MIN_SCL_LTIME_400 388

I2C Clock

RTL8721Dx: 
/* I2C0/I2C1 IP clock frequency in Hz. */
#define I2C0_1_IPCLK XTAL_ClkGet()

I2C DMA Mode

RTL8721Dx: 
/* DWC DMA legacy mode. */
#define I2C_DMA_LEGACY ((u32)0x00000000)

/* DMA mode with control register. */
#define I2C_DMA_REGISTER ((u32)0x00000001)

/* DMA mode with transfer descriptor. */
#define I2C_DMA_DESCRIPTOR ((u32)0x00000002)

/* Check if I2C DMA mode value is valid. */
#define IS_I2C_DMA_MODE (((MODE) == I2C_DMA_LEGACY) || \
    ((MODE) == I2C_DMA_REGISTER) || \
    ((MODE) == I2C_DMA_DESCRIPTOR))

I2C DMA Data Length

RTL8721Dx: 
/* Check if I2C DMA data length is valid. */
#define IS_I2C_DMA_DATA_LEN ((LENGTH) <= 0xFFFF)

I2C Exported Functions

u8 I2C_CheckFlagState(I2C_TypeDef *I2Cx, u32 I2C_FLAG)

Check whether the specified I2C flag is set or not.

Parameters:

  • I2Cx – I2Cx device.

  • I2C_FLAG –

    Specifies the flag to check. This parameter can be one of the following values:

    • I2C_BIT_SLV_ACTIVITY:

    • I2C_BIT_MST_ACTIVITY:

    • I2C_BIT_RFF:

    • I2C_BIT_RFNE:

    • I2C_BIT_TFE:

    • I2C_BIT_TFNF:

    • I2C_BIT_ACTIVITY:

Returns:

The new state of I2C_FLAG:

  • 1: the specified I2C flag is set

  • 0: the specified I2C flag is not set

u32 I2C_ClearAllINT(I2C_TypeDef *I2Cx)

Clear all of the I2C interrupt pending bit.

Parameters:

  • I2Cx – I2Cx device.

Returns:

Cleared interrupt status

u32 I2C_ClearINT(I2C_TypeDef *I2Cx, u32 INTrBit)

Clear the specified I2C interrupt pending bit.

Parameters:

  • I2Cx – I2Cx device.

  • INTrBit –

    Specifies the interrupt to be cleared. This parameter can be one of the following values:

    • I2C_BIT_R_LP_WAKE_2: I2C slave1 Address Match Interrupt

    • I2C_BIT_R_LP_WAKE_1: I2C slave0 Address Match Interrupt

    • I2C_BIT_R_GEN_CALL: General Call Interrupt

    • I2C_BIT_R_START_DET: Start or Restart Condition Interrupt

    • I2C_BIT_R_STOP_DET: Stop Condition Interrupt

    • I2C_BIT_R_ACTIVITY: I2C Activity Interrupt

    • I2C_BIT_R_RX_DONE: Slave Transmitter RX Done Interrupt

    • I2C_BIT_R_TX_ABRT: Transmit Abort Interrupt

    • I2C_BIT_R_RD_REQ: Read Request Interrupt

    • I2C_BIT_R_TX_EMPTY: Transmit FIFO Empty Interrupt

    • I2C_BIT_R_TX_OVER: Transmit FIFO Over Interrupt

    • I2C_BIT_R_RX_FULL: Receive FIFO Full Interrupt

    • I2C_BIT_R_RX_OVER: Receive FIFO Over Interrupt

    • I2C_BIT_R_RX_UNDER: Receive FIFO Under Interrupt

Returns:

Cleared interrupt status

Note

  • I2C_BIT_R_TX_EMPTY is automatically cleared by hardware when the buffer level goes above the I2CTXTL threshold.

  • I2C_BIT_R_RX_FULL is automatically cleared by hardware when the buffer level goes below the I2CRXTL threshold.

void I2C_Cmd(I2C_TypeDef *I2Cx, u8 NewState)

Enable or disable the specified I2C peripheral, this is one bit register.

Parameters:

  • I2Cx – I2Cx device.

  • NewState – New state of the I2Cx peripheral. This parameter can be: ENABLE or DISABLE.

u32 I2C_GetINT(I2C_TypeDef *I2Cx)

Get I2C interrupt status.

Parameters:

  • I2Cx – I2Cx device.

Returns:

Interrupt status

u32 I2C_GetRawINT(I2C_TypeDef *I2Cx)

Get I2C Raw Interrupt Status.

Parameters:

  • I2Cx – I2Cx device.

Returns:

Raw interrupt status

void I2C_INTConfig(I2C_TypeDef *I2Cx, u32 I2C_IT, u32 NewState)

ENABLE/DISABLE the I2C’s interrupt bits..

Parameters:

  • I2Cx – I2Cx device.

  • I2C_IT –

    Specifies the I2Cx interrupt sources to be enabled or disabled. This parameter can be one or combinations of the following values:

    • I2C_BIT_M_LP_WAKE_2: I2C slave1 Address Match Interrupt

    • I2C_BIT_M_LP_WAKE_1: I2C slave0 Address Match Interrupt

    • I2C_BIT_M_GEN_CALL: General Call Interrupt

    • I2C_BIT_M_START_DET: Start or Restart Condition Interrupt

    • I2C_BIT_M_STOP_DET: Stop Condition Interrupt

    • I2C_BIT_M_ACTIVITY: I2C Activity Interrupt

    • I2C_BIT_M_RX_DONE: Slave Transmitter RX Done Interrupt

    • I2C_BIT_M_TX_ABRT: Transmit Abort Interrupt

    • I2C_BIT_M_RD_REQ: Read Request Interrupt

    • I2C_BIT_M_TX_EMPTY: Transmit FIFO Empty Interrupt

    • I2C_BIT_M_TX_OVER: Transmit FIFO Over Interrupt

    • I2C_BIT_M_RX_FULL: Receive FIFO Full Interrupt

    • I2C_BIT_M_RX_OVER: Receive FIFO Over Interrupt

    • I2C_BIT_M_RX_UNDER: Receive FIFO Under Interrupt

  • NewState – Specifies the state of the interrupt. This parameter can be: ENABLE or DISABLE.

u32 I2C_ISRHandle(I2C_IntModeCtrl *I2C_SemStruct)

I2C TX/RX interrupt handler.

Parameters:

  • I2C_SemStruct – Pointer to an I2C_IntModeCtrl structure containing the function of acquiring and releasing semaphores.

Returns:

Status value (0 in this implementation).

Note

This function has been defined as weak in the SDK, and users can redefine it according to their needs.

void I2C_Init(I2C_TypeDef *I2Cx, I2C_InitTypeDef *I2C_InitStruct)

Initialize the I2Cx peripheral according to the specified parameters in the I2C_InitStruct.

Parameters:

  • I2Cx – I2Cx device.

  • I2C_InitStruct – Pointer to an I2C_InitTypeDef structure that contains the configuration information for the specified I2C peripheral.

u32 I2C_MasterRead(I2C_TypeDef *I2Cx, u8 *pBuf, u32 len)

Read data with special length in master mode through the I2Cx peripheral under in-house IP.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the buffer to hold the received data.

  • len – The length of data that to be received.

Returns:

The length of data that have received from rx fifo.

u32 I2C_MasterReadDW(I2C_TypeDef *I2Cx, u8 *pBuf, u32 len)

Read data with special length in master mode through the I2Cx peripheral under DW IP.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the buffer to hold the received data.

  • len – The length of data that to be received.

Returns:

The length of data that have received from rx fifo.

Note

Under DW IP, master must send two times read cmd, flow is:

  1. Master requests first data entry.

  2. Slave sends first data entry.

  3. Master sends second read cmd to ack first data and request second data.

  4. Slave sends second data.

  5. Master RX full interrupt receives first data, acks second data and requests third data.

Repeat steps 4 and 5. The last slave data has no ACK, which is permitted by the spec.

u32 I2C_MasterReadInt(I2C_TypeDef *I2Cx, I2C_IntModeCtrl *I2C_SemStruct, u8 *pBuf, u32 len)

Master receives data in interrupt mode.

Parameters:

  • I2Cx – I2Cx device.

  • I2C_SemStruct – Pointer to an I2C_IntModeCtrl structure containing the function of acquiring and releasing semaphores.

  • pBuf – Point to the buffer to hold the received data.

  • len – The length of data that to be received.

Returns:

Received count.

u32 I2C_MasterRead_TimeOut(I2C_TypeDef *I2Cx, u8 *pBuf, u32 len, u32 ms)

Read data with special length in master mode through the I2Cx peripheral under in-house IP.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the buffer to hold the received data.

  • len – The length of data that to be received.

  • ms – Specifies timeout time, unit is ms.

Returns:

The length of data that have received from rx fifo.

u32 I2C_MasterRepeatRead(I2C_TypeDef *I2Cx, u8 *pWriteBuf, u32 Writelen, u8 *pReadBuf, u32 Readlen)

Send data and read data in master mode through the I2Cx peripheral.

Parameters:

  • I2Cx – I2Cx device.

  • pWriteBuf – Byte to be transmitted.

  • Writelen – Byte number to be transmitted.

  • pReadBuf – Byte to be received.

  • Readlen – Byte number to be received.

Returns:

The length of data that have received from rx fifo.

void I2C_MasterSend(I2C_TypeDef *I2Cx, u8 *pBuf, u8 I2CCmd, u8 I2CStop, u8 I2CReSTR)

Master sends single byte through the I2Cx peripheral according to the set of the upper layer.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the data that to be write.

  • I2CCmd – Specifies whether a read from FIFO or a write to FIFO is performed.

  • I2CStop – Specifies whether a STOP is issued after the byte is sent or received.

  • I2CReSTR – Specifies whether a RESTART is issued after the byte is sent or received.

void I2C_MasterSendNullData(I2C_TypeDef *I2Cx, u8 *pBuf, u8 I2CCmd, u8 I2CStop, u8 I2CReSTR)

Master sends single byte through the I2Cx peripheral according to the set of the upper layer.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the data that to be write.

  • I2CCmd – Specifies whether a read from FIFO or a write to FIFO is performed.

  • I2CStop – Specifies whether a STOP is issued after the byte is sent or received.

  • I2CReSTR – Specifies whether a RESTART is issued after the byte is sent or received.

s32 I2C_MasterSendNullData_TimeOut(I2C_TypeDef *I2Cx, int address, u32 timeout_ms)

Master sends single byte through the I2Cx peripheral to detect slave device.

Parameters:

  • I2Cx – I2Cx device.

  • address – The address of slave that to be detected.

  • timeout_ms – Specifies timeout time, unit is ms.

Returns:

Slave ack condition:

  • 0: Slave available

  • 1: Slave not available

u32 I2C_MasterWrite(I2C_TypeDef *I2Cx, u8 *pBuf, u32 len)

Send data with special length in master mode through the I2Cx peripheral.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the data to be transmitted.

  • len – The length of data that to be transmitted.

Returns:

The length of data that have sent to the bus.

u32 I2C_MasterWriteInt(I2C_TypeDef *I2Cx, I2C_IntModeCtrl *I2C_SemStruct, u8 *pBuf, u32 len)

Master sends data in interrupt mode.

Parameters:

  • I2Cx – I2Cx device.

  • I2C_SemStruct – Pointer to an I2C_IntModeCtrl structure containing the function of acquiring and releasing semaphores.

  • pBuf – Point to the data to be transmitted.

  • len – The length of data that to be transmitted.

Returns:

Remaining to be transferred count.

u32 I2C_MasterWrite_TimeOut(I2C_TypeDef *I2Cx, u8 *pBuf, u32 len, u32 ms)

Write data with special length in master mode through the I2Cx peripheral under in-house IP.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the data to be transmitted.

  • len – The length of data that to be transmitted.

  • ms – Specifies timeout time, unit is ms.

Returns:

The length of data that have sent to the bus.

s32 I2C_PollFlagRawINT(I2C_TypeDef *I2Cx, u32 I2C_FLAG, u32 I2C_RawINT, u32 timeout_ms, u32 *txflr_out)

Poll the specified I2C flag and/or RawINT to be set.

Parameters:

  • I2Cx – I2Cx device.

  • I2C_FLAG – Specifies the status flag to check.

  • I2C_RawINT – Specifies the raw interrupt status to check.

  • timeout_ms – Specifies timeout time, unit is ms.

  • txflr_out – Points to a backup of IC_TXFLR in case TXFIFO flush.

Returns:

Operation status:

  • RTK_SUCCESS: pass

  • RTK_ERR_TIMEOUT: timeout

  • RTK_FAIL: TX_ABRT

u8 I2C_ReceiveData(I2C_TypeDef *I2Cx)

Return the most recent received data by the I2Cx peripheral.

Parameters:

  • I2Cx – I2Cx device.

Returns:

The value of the received data.

void I2C_SetSlaveAddress(I2C_TypeDef *I2Cx, u16 Address)

Master transmits the address byte to select the slave device.

Parameters:

  • I2Cx – I2Cx device.

  • Address – Specifies the slave address which will be transmitted

void I2C_SetSpeed(I2C_TypeDef *I2Cx, u32 SpdMd, u32 I2Clk, u32 I2CIPClk)

Master sets I2C Speed Mode.

Parameters:

  • I2Cx – I2Cx device.

  • SpdMd –

    I2C Speed Mode. This parameter can be one of the following values:

    • I2C_SS_MODE:

    • I2C_FS_MODE:

    • I2C_HS_MODE:(not support for I2C0)

  • I2Clk –

    I2C Bus Clock, unit is KHz. This parameter can be one of the following values:

    • 50:

    • 100:

    • 400:

    • 1000:

    • 3000: or others

  • I2CIPClk – I2C IP Clock, unit is Hz.

u32 I2C_SlaveRead(I2C_TypeDef *I2Cx, u8 *pBuf, u32 len)

Read data with special length in slave mode through the I2Cx peripheral.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the buffer to hold the received data.

  • len – The length of data that to be received.

Returns:

The length of data that have received from rx fifo.

void I2C_SlaveSend(I2C_TypeDef *I2Cx, u8 Data)

Slave sends single byte through the I2Cx peripheral after receiving read request of Master.

Parameters:

  • I2Cx – I2Cx device.

  • Data – Data to be transmitted.

u32 I2C_SlaveWrite(I2C_TypeDef *I2Cx, u8 *pBuf, u32 len)

Send data with special length in slave mode through the I2Cx peripheral.

Parameters:

  • I2Cx – I2Cx device.

  • pBuf – Point to the data to be transmitted.

  • len – The length of data that to be transmitted.

Returns:

The length of data that have sent to the bus.

void I2C_StructInit(I2C_InitTypeDef *I2C_InitStruct)

Fill each I2C_InitStruct member with its default value.

Parameters:

  • I2C_InitStruct – Pointer to an I2C_InitTypeDef structure which will be initialized.

RTL8721Dx:
void I2C_DMAControl(I2C_TypeDef *I2Cx, u32 DmaCtrl, u8 NewState)

Enable I2C Tx or Rx DMA.

Parameters:

  • I2Cx – I2Cx device.

  • DmaCtrl –

    Control Transmit DMA Enable or Receive DMA Enable This parameter can be one of the following values:

    • I2C_BIT_TDMAE:

    • I2C_BIT_RDMAE:

  • NewState – The new state of the DMA function. This parameter can be: ENABLE or DISABLE.

void I2C_DmaMode1Config(I2C_TypeDef *I2Cx, u32 I2C_DmaCmd, u32 I2C_DmaBLen)

Initialize the I2Cx Control Register DMA mode.

Parameters:

  • I2Cx – I2Cx device.

  • I2C_DmaCmd –

    Command to control the read or write operation and the action after the last data transferred. This parameter can be one or combinations of the following values:

    • I2C_BIT_DMODE_RESTART

    • I2C_BIT_DMODE_STOP

    • I2C_BIT_DMODE_CMD

    • I2C_BIT_DMODE_ENABLE

  • I2C_DmaBLen – Length of data. This parameter must be set to a value in the 0-0xFFFF range.

void I2C_DmaMode2Config(I2C_TypeDef *I2Cx, u32 I2C_DmaCmd, u32 I2C_DmaBLen)

Initialize the I2C Descriptor DMA mode.

Parameters:

  • I2Cx – I2Cx device.

  • I2C_DmaCmd – Set BIT[0] of IC_DMA_CMD to enable DMA mode.

  • I2C_DmaBLen – Length of data. This parameter must be set to a value in the 0-0xFF range.

bool I2C_RXGDMA_Init(u8 Index, GDMA_InitTypeDef *GDMA_InitStruct, void *CallbackData, IRQ_FUN CallbackFunc, u8 *pRxBuf, int RxCount)

Init and Enable I2C RX GDMA.

Parameters:

  • Index – I2C index.

  • GDMA_InitStruct – Pointer to a GDMA_InitTypeDef structure that contains the configuration information for the GDMA peripheral.

  • CallbackData – GDMA callback data.

  • CallbackFunc – GDMA callback function.

  • pRxBuf – Rx Buffer.

  • RxCount – Rx Count.

Returns:

Operation status:

  • TRUE: initialization successful

  • FALSE: initialization failed (no available DMA channel)

Note

Support Master or Slave RXDMA

bool I2C_TXGDMA_Init(u8 Index, GDMA_InitTypeDef *GDMA_InitStruct, void *CallbackData, IRQ_FUN CallbackFunc, u8 *pTxBuf, int TxCount)

Init and Enable I2C TX GDMA.

Parameters:

  • Index – I2C index.

  • GDMA_InitStruct – Pointer to a GDMA_InitTypeDef structure that contains the configuration information for the GDMA peripheral.

  • CallbackData – GDMA callback data.

  • CallbackFunc – GDMA callback function.

  • pTxBuf – Tx Buffer.

  • TxCount – Tx Count.

Returns:

Operation status:

  • TRUE: initialization successful

  • FALSE: initialization failed (no available DMA channel)

Note

Can not support legacy DMA mode

Mbed API

MBED_I2C Exported Types

Enumeration Type

enum I2CCallback

I2C callback event type.

Values:

/* Transmission complete event. */
I2C_TX_COMPLETE = 0

/* Reception complete event. */
I2C_RX_COMPLETE = 1

/* Slave read request event. */
I2C_RD_REQ_COMMAND = 2

/* Error occurred event. */
I2C_ERR_OCCURRED = 3
enum I2C_ERR_REASON

I2C error reason code.

Values:

/* No slave device found. */
I2C_ERROR_NO_SLAVE = -1

/* I2C bus is busy. */
I2C_ERROR_BUS_BUSY = -2

Structure Type

typedef struct i2c_s i2c_t

I2C object type, defined as struct i2c_s.

MBED_I2C Exported Functions

int i2c_byte_read(i2c_t *obj, int last)

I2C master receive single byte.

Parameters:

  • obj – I2C object defined in application software.

  • last – Reserved.

Returns:

Received data.

int i2c_byte_write(i2c_t *obj, int data)

I2C master send single byte.

Parameters:

  • obj – I2C object defined in application software.

  • data – Data to be sent.

Returns:

Write result.

int i2c_enable_control(i2c_t *obj, int enable)

Enable or Disable I2C Device.

Parameters:

  • obj – I2C object defined in application software.

  • enable –

    This parameter can be one of the following values:

    • 0: Disable I2C Device.

    • 1: Enable I2C Device.

Returns:

0

void i2c_frequency(i2c_t *obj, int hz)

Set I2C frequency.

Parameters:

  • obj – I2C object defined in application software.

  • hz – I2C clock frequency in units of Hz.

void i2c_init(i2c_t *obj, PinName sda, PinName scl)

Initialize the I2C device, including clock, function and I2C registers.

Parameters:

  • obj – I2C object defined in application software.

  • sda – SDA PinName according to pinmux spec.

  • scl – SCL PinName according to pinmux spec.

int i2c_read(i2c_t *obj, int address, char *data, int length, int stop)

I2C master read in poll mode.

Parameters:

  • obj – I2C object defined in application software.

  • address – Slave address which will be transmitted.

  • data – Pointer to the buffer to hold the received data.

  • length – Length of data that to be received.

  • stop – Reserved.

Returns:

Length of received data.

int i2c_read_timeout(i2c_t *obj, int address, char *data, int length, int stop, int timeout_ms)

I2C master read in poll mode.

Parameters:

  • obj – I2C object defined in application software.

  • address – Slave address which will be transmitted.

  • data – Pointer to the buffer to hold the received data.

  • length – Length of data that to be received.

  • stop – Reserved.

  • timeout_ms – Specify timeout time in units of ms.

Returns:

Length of actually received data.

Note

If actual data length is less than expected data length, this transfer fails.

int i2c_repeatread(i2c_t *obj, int address, u8 *pWriteBuf, int Writelen, u8 *pReadBuf, int Readlen)

I2C master send data and read data in poll mode.

Parameters:

  • obj – I2C object defined in application software.

  • address – Slave address which will be transmitted.

  • pWriteBuf – Pointer to the data to be sent.

  • Writelen – Length of data that to be sent.

  • pReadBuf – Pointer to the buffer to hold the received data.

  • Readlen – Length of data that to be received.

Returns:

Length of received data.

void i2c_reset(i2c_t *obj)

Deinitialize the I2C device.

Parameters:

  • obj – I2C object defined in application software.

void i2c_restart_disable(i2c_t *obj)

Disable I2C Master RESTART function.

Parameters:

  • obj – I2C object defined in application software.

Note

Include i2c_ex_api.h to explicitly call this function.

void i2c_restart_enable(i2c_t *obj)

Enable I2C master RESTART function.

Parameters:

  • obj – I2C object defined in application software.

Note

Include i2c_ex_api.h to explicitly call this function.

int i2c_send_restart(I2C_TypeDef *I2Cx, u8 *pBuf, u8 len, u8 restart)

I2C master restart after all bytes are sent.

Parameters:

  • I2Cx – Where I2Cx can be I2C0_DEV to select the I2C peripheral.

  • pBuf – Pointer to the data to be sent.

  • len – Length of data that to be sent.

  • restart – Specify whether a RESTART is issued after all the bytes are sent.

Returns:

Length of sent data.

void i2c_slave_address(i2c_t *obj, int idx, uint32_t address, uint32_t mask)

Set I2C slave address.

Parameters:

  • obj – I2C object defined in application software.

  • idx – Reserved.

  • address – Slave address.

  • mask – Reserved.

void i2c_slave_mode(i2c_t *obj, int enable_slave)

Set I2C device to be slave.

Parameters:

  • obj – I2C object defined in application software.

  • enable_slave –

    Enable slave function, this parameter can be one of the following values:

    • 1: Set I2C device to be slave.

    • 0: No action.

int i2c_slave_read(i2c_t *obj, char *data, int length)

I2C slave read in poll mode.

Parameters:

  • obj – I2C object defined in application software.

  • data – Pointer to the buffer to hold the received data.

  • length – Length of data that to be received.

Returns:

Length of received data.

int i2c_slave_receive(i2c_t *obj)

Get I2C slave state.

Parameters:

  • obj – I2C object defined in application software.

Returns:

State of I2C slave.

int i2c_slave_set_for_data_nak(i2c_t *obj, int set_nak)

Set/clear I2C slave NAK or ACK data part in transfer.

Parameters:

  • obj – I2C object defined in application software.

  • set_nak – Set or clear for data NAK.

Returns:

int i2c_slave_set_for_rd_req(i2c_t *obj, int set)

Set/clear I2C slave RD_REQ interrupt mask.

Parameters:

  • obj – I2C object defined in application software.

  • set – Set or clear for read request.

Returns:

Result:

  • 1: Success.

  • Others: Error.

int i2c_slave_write(i2c_t *obj, const char *data, int length)

I2C slave write in poll mode.

Parameters:

  • obj – I2C object defined in application software.

  • data – Pointer to the data to be sent.

  • length – Length of data that to be sent.

Returns:

Length of sent data.

int i2c_start(i2c_t *obj)

Reserved.

Parameters:

  • obj – Reserved.

Returns:

0

int i2c_stop(i2c_t *obj)

Reserved.

Parameters:

  • obj – Reserved.

Returns:

0

int i2c_write(i2c_t *obj, int address, const char *data, int length, int stop)

I2C master write in poll mode.

Parameters:

  • obj – I2C object defined in application software.

  • address – Slave address which will be transmitted.

  • data – Pointer to the data to be sent.

  • length – Length of data that to be sent.

  • stop – Specify whether a STOP is issued after all the bytes are sent.

Returns:

Length of sent data.

int i2c_write_timeout(i2c_t *obj, int address, char *data, int length, int stop, int timeout_ms)

I2C master write in poll mode.

Parameters:

  • obj – I2C object defined in application software.

  • address – Slave address which will be transmitted.

  • data – Pointer to the buffer of data to be transmitted.

  • length – Length of data that to be received.

  • stop – Reserved.

  • timeout_ms – Specify timeout time in units of ms.

Returns:

Length of written data.

Note