Overview

The MCUXpresso SDK provides a peripheral driver for the Inter-Integrated Circuit (I2C) module of MCUXpresso SDK devices.

The I2C driver includes functional APIs and transactional APIs.

Functional APIs target the low-level APIs. Functional APIs can be used for the I2C master/slave initialization/configuration/operation for optimization/customization purpose. Using the functional APIs requires knowing the I2C master peripheral and how to organize functional APIs to meet the application requirements. The I2C functional operation groups provide the functional APIs set.

Transactional APIs target the high-level APIs. The transactional APIs can be used to enable the peripheral quickly and also in the application if the code size and performance of transactional APIs satisfy the requirements. If the code size and performance are critical requirements, see the transactional API implementation and write custom code using the functional APIs or accessing the hardware registers.

Transactional APIs support asynchronous transfer. This means that the functions I2C_MasterTransferNonBlocking() set up the interrupt non-blocking transfer. When the transfer completes, the upper layer is notified through a callback function with the status.

Typical use case

Master Operation in functional method

i2c_master_config_t masterConfig;
uint8_t status;
status_t result = kStatus_Success;
uint8_t txBuff[BUFFER_SIZE];
/* Gets the default configuration for master. */
I2C_MasterGetDefaultConfig(&masterConfig);
/* Inititializes the I2C master. */
I2C_MasterInit(EXAMPLE_I2C_MASTER_BASEADDR, &masterConfig, I2C_MASTER_CLK);
/* Sends a start and a slave address. */
I2C_MasterStart(EXAMPLE_I2C_MASTER_BASEADDR, 7-bit slave address, kI2C_Write/kI2C_Read);
/* Waits for the sent out address. */
while(!((status = I2C_GetStatusFlag(EXAMPLE_I2C_MASTER_BASEADDR)) & kI2C_IntPendingFlag))
{
}
if(status & kI2C_ReceiveNakFlag)
{
    return kStatus_I2C_Nak;
}
result = I2C_MasterWriteBlocking(EXAMPLE_I2C_MASTER_BASEADDR, txBuff, BUFFER_SIZE, kI2C_TransferDefaultFlag);
if(result)
{
    return result;
}

Master Operation in interrupt transactional method

i2c_master_handle_t g_m_handle;
volatile bool g_MasterCompletionFlag = false;
i2c_master_config_t masterConfig;
uint8_t status;
status_t result = kStatus_Success;
uint8_t txBuff[BUFFER_SIZE];
i2c_master_transfer_t masterXfer;
static void i2c_master_callback(I2C_Type *base, i2c_master_handle_t *handle, status_t status, void *userData)
{
    /* Signal transfer success when received success status. */
    if (status == kStatus_Success)
    {
        g_MasterCompletionFlag = true;
    }
}
/* Gets a default configuration for master. */
I2C_MasterGetDefaultConfig(&masterConfig);
/* Initializes the I2C master. */
I2C_MasterInit(EXAMPLE_I2C_MASTER_BASEADDR, &masterConfig, I2C_MASTER_CLK);
masterXfer.slaveAddress = I2C_MASTER_SLAVE_ADDR_7BIT;
masterXfer.direction = kI2C_Write;
masterXfer.subaddress = NULL;
masterXfer.subaddressSize = 0;
masterXfer.data = txBuff;
masterXfer.dataSize = BUFFER_SIZE;
masterXfer.flags = kI2C_TransferDefaultFlag;
I2C_MasterTransferCreateHandle(EXAMPLE_I2C_MASTER_BASEADDR, &g_m_handle, i2c_master_callback, NULL);
I2C_MasterTransferNonBlocking(EXAMPLE_I2C_MASTER_BASEADDR, &g_m_handle, &masterXfer);
/*  Waits for a transfer to be completed. */
while (!g_MasterCompletionFlag)
{
}
g_MasterCompletionFlag = false;

Master Operation in DMA transactional method

i2c_master_dma_handle_t g_m_dma_handle;
dma_handle_t dmaHandle;
volatile bool g_MasterCompletionFlag = false;
i2c_master_config_t masterConfig;
uint8_t txBuff[BUFFER_SIZE];
i2c_master_transfer_t masterXfer;
static void i2c_master_callback(I2C_Type *base, i2c_master_dma_handle_t *handle, status_t status, void *userData)
{
    /* Signal transfer success when received success status. */
    if (status == kStatus_Success)
    {
        g_MasterCompletionFlag = true;
    }
}
/* Gets the default configuration for the master. */
I2C_MasterGetDefaultConfig(&masterConfig);
/* Initializes the I2C master. */
I2C_MasterInit(EXAMPLE_I2C_MASTER_BASEADDR, &masterConfig, I2C_MASTER_CLK);
masterXfer.slaveAddress = I2C_MASTER_SLAVE_ADDR_7BIT;
masterXfer.direction = kI2C_Write;
masterXfer.subaddress = NULL;
masterXfer.subaddressSize = 0;
masterXfer.data = txBuff;
masterXfer.dataSize = BUFFER_SIZE;
masterXfer.flags = kI2C_TransferDefaultFlag;
DMAMGR_RequestChannel((dma_request_source_t)DMA_REQUEST_SRC, 0, &dmaHandle);
I2C_MasterTransferCreateHandleDMA(EXAMPLE_I2C_MASTER_BASEADDR, &g_m_dma_handle, i2c_master_callback, NULL, &dmaHandle);
I2C_MasterTransferDMA(EXAMPLE_I2C_MASTER_BASEADDR, &g_m_dma_handle, &masterXfer);
/*  Wait for transfer completed. */
while (!g_MasterCompletionFlag)
{
}
g_MasterCompletionFlag = false;

Slave Operation in functional method

i2c_slave_config_t slaveConfig;
uint8_t status;
status_t result = kStatus_Success;
I2C_SlaveGetDefaultConfig(&slaveConfig); /*A default configuration 7-bit addressing mode*/
slaveConfig.slaveAddr = 7-bit address
slaveConfig.addressingMode = kI2C_Address7bit/kI2C_RangeMatch;
I2C_SlaveInit(EXAMPLE_I2C_SLAVE_BASEADDR, &slaveConfig, I2C_SLAVE_CLK);
/* Waits for an address match. */
while(!((status = I2C_GetStatusFlag(EXAMPLE_I2C_SLAVE_BASEADDR)) & kI2C_AddressMatchFlag))
{
}
/* A slave transmits; master is reading from the slave. */
if (status & kI2C_TransferDirectionFlag)
{
    result = I2C_SlaveWriteBlocking(EXAMPLE_I2C_SLAVE_BASEADDR, txBuff, BUFFER_SIZE);
}
else
{
    I2C_SlaveReadBlocking(EXAMPLE_I2C_SLAVE_BASEADDR, rxBuff, BUFFER_SIZE);
}
return result;

Slave Operation in interrupt transactional method

i2c_slave_config_t slaveConfig;
i2c_slave_handle_t g_s_handle;
volatile bool g_SlaveCompletionFlag = false;
static void i2c_slave_callback(I2C_Type *base, i2c_slave_transfer_t *xfer, void *userData)
{
    switch (xfer->event)
    {
        /*  Transmit request */
        case kI2C_SlaveTransmitEvent:
            /*  Update information for transmit process */
            xfer->data = g_slave_buff;
            xfer->dataSize = I2C_DATA_LENGTH;
            break;
        /*  Receives request */
        case kI2C_SlaveReceiveEvent:
            /*  Update information for received process */
            xfer->data = g_slave_buff;
            xfer->dataSize = I2C_DATA_LENGTH;
            break;
        /*  Transfer is done */
        case kI2C_SlaveCompletionEvent:
            g_SlaveCompletionFlag = true;
            break;
        default:
            g_SlaveCompletionFlag = true;
            break;
    }
}
I2C_SlaveGetDefaultConfig(&slaveConfig); /*A default configuration 7-bit addressing mode*/
slaveConfig.slaveAddr = 7-bit address
slaveConfig.addressingMode = kI2C_Address7bit/kI2C_RangeMatch;
I2C_SlaveInit(EXAMPLE_I2C_SLAVE_BASEADDR, &slaveConfig, I2C_SLAVE_CLK);
I2C_SlaveTransferCreateHandle(EXAMPLE_I2C_SLAVE_BASEADDR, &g_s_handle, i2c_slave_callback, NULL);
I2C_SlaveTransferNonBlocking(EXAMPLE_I2C_SLAVE_BASEADDR, &g_s_handle, kI2C_SlaveCompletionEvent);
/*  Waits for a transfer to be completed. */
while (!g_SlaveCompletionFlag)
{
}
g_SlaveCompletionFlag = false;

Data Structures
struct	i2c_master_config_t
	I2C master user configuration. More...

struct	i2c_slave_config_t
	I2C slave user configuration. More...

struct	i2c_master_transfer_t
	I2C master transfer structure. More...

struct	i2c_master_handle_t
	I2C master handle structure. More...

struct	i2c_slave_transfer_t
	I2C slave transfer structure. More...

struct	i2c_slave_handle_t
	I2C slave handle structure. More...

Typedefs
typedef void(*	i2c_master_transfer_callback_t )(I2C_Type base, i2c_master_handle_t handle, status_t status, void *userData)
	I2C master transfer callback typedef. More...

typedef void(*	i2c_slave_transfer_callback_t )(I2C_Type base, i2c_slave_transfer_t xfer, void *userData)
	I2C slave transfer callback typedef. More...

Enumerations
enum	_i2c_status { kStatus_I2C_Busy = MAKE_STATUS(kStatusGroup_I2C, 0), kStatus_I2C_Idle = MAKE_STATUS(kStatusGroup_I2C, 1), kStatus_I2C_Nak = MAKE_STATUS(kStatusGroup_I2C, 2), kStatus_I2C_ArbitrationLost = MAKE_STATUS(kStatusGroup_I2C, 3), kStatus_I2C_Timeout = MAKE_STATUS(kStatusGroup_I2C, 4), kStatus_I2C_Addr_Nak = MAKE_STATUS(kStatusGroup_I2C, 5) }
	I2C status return codes. More...

enum	_i2c_flags { kI2C_ReceiveNakFlag = I2C_S_RXAK_MASK, kI2C_IntPendingFlag = I2C_S_IICIF_MASK, kI2C_TransferDirectionFlag = I2C_S_SRW_MASK, kI2C_RangeAddressMatchFlag = I2C_S_RAM_MASK, kI2C_ArbitrationLostFlag = I2C_S_ARBL_MASK, kI2C_BusBusyFlag = I2C_S_BUSY_MASK, kI2C_AddressMatchFlag = I2C_S_IAAS_MASK, kI2C_TransferCompleteFlag = I2C_S_TCF_MASK, kI2C_StopDetectFlag = I2C_FLT_STOPF_MASK << 8, kI2C_StartDetectFlag = I2C_FLT_STARTF_MASK << 8 }
	I2C peripheral flags. More...

enum	_i2c_interrupt_enable { kI2C_GlobalInterruptEnable = I2C_C1_IICIE_MASK, kI2C_StartStopDetectInterruptEnable = I2C_FLT_SSIE_MASK }
	I2C feature interrupt source. More...

enum	i2c_direction_t { kI2C_Write = 0x0U, kI2C_Read = 0x1U }
	The direction of master and slave transfers. More...

enum	i2c_slave_address_mode_t { kI2C_Address7bit = 0x0U, kI2C_RangeMatch = 0X2U }
	Addressing mode. More...

enum	_i2c_master_transfer_flags { kI2C_TransferDefaultFlag = 0x0U, kI2C_TransferNoStartFlag = 0x1U, kI2C_TransferRepeatedStartFlag = 0x2U, kI2C_TransferNoStopFlag = 0x4U }
	I2C transfer control flag. More...

enum	i2c_slave_transfer_event_t { kI2C_SlaveAddressMatchEvent = 0x01U, kI2C_SlaveTransmitEvent = 0x02U, kI2C_SlaveReceiveEvent = 0x04U, kI2C_SlaveTransmitAckEvent = 0x08U, kI2C_SlaveStartEvent = 0x10U, kI2C_SlaveCompletionEvent = 0x20U, kI2C_SlaveGenaralcallEvent = 0x40U, kI2C_SlaveAllEvents }
	Set of events sent to the callback for nonblocking slave transfers. More...

Driver version
#define	FSL_I2C_DRIVER_VERSION (MAKE_VERSION(2, 0, 3))
	I2C driver version 2.0.3. More...

Initialization and deinitialization
void	I2C_MasterInit (I2C_Type base, const i2c_master_config_t masterConfig, uint32_t srcClock_Hz)
	Initializes the I2C peripheral. More...

void	I2C_SlaveInit (I2C_Type base, const i2c_slave_config_t slaveConfig, uint32_t srcClock_Hz)
	Initializes the I2C peripheral. More...

void	I2C_MasterDeinit (I2C_Type *base)
	De-initializes the I2C master peripheral. More...

void	I2C_SlaveDeinit (I2C_Type *base)
	De-initializes the I2C slave peripheral. More...

void	I2C_MasterGetDefaultConfig (i2c_master_config_t *masterConfig)
	Sets the I2C master configuration structure to default values. More...

void	I2C_SlaveGetDefaultConfig (i2c_slave_config_t *slaveConfig)
	Sets the I2C slave configuration structure to default values. More...

static void	I2C_Enable (I2C_Type *base, bool enable)
	Enables or disabless the I2C peripheral operation. More...

Status
uint32_t	I2C_MasterGetStatusFlags (I2C_Type *base)
	Gets the I2C status flags. More...

static uint32_t	I2C_SlaveGetStatusFlags (I2C_Type *base)
	Gets the I2C status flags. More...

static void	I2C_MasterClearStatusFlags (I2C_Type *base, uint32_t statusMask)
	Clears the I2C status flag state. More...

static void	I2C_SlaveClearStatusFlags (I2C_Type *base, uint32_t statusMask)
	Clears the I2C status flag state. More...

Interrupts
void	I2C_EnableInterrupts (I2C_Type *base, uint32_t mask)
	Enables I2C interrupt requests. More...

void	I2C_DisableInterrupts (I2C_Type *base, uint32_t mask)
	Disables I2C interrupt requests. More...

DMA Control
static void	I2C_EnableDMA (I2C_Type *base, bool enable)
	Enables/disables the I2C DMA interrupt. More...

static uint32_t	I2C_GetDataRegAddr (I2C_Type *base)
	Gets the I2C tx/rx data register address. More...

Bus Operations
void	I2C_MasterSetBaudRate (I2C_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz)
	Sets the I2C master transfer baud rate. More...

status_t	I2C_MasterStart (I2C_Type *base, uint8_t address, i2c_direction_t direction)
	Sends a START on the I2C bus. More...

status_t	I2C_MasterStop (I2C_Type *base)
	Sends a STOP signal on the I2C bus. More...

status_t	I2C_MasterRepeatedStart (I2C_Type *base, uint8_t address, i2c_direction_t direction)
	Sends a REPEATED START on the I2C bus. More...

status_t	I2C_MasterWriteBlocking (I2C_Type base, const uint8_t txBuff, size_t txSize, uint32_t flags)
	Performs a polling send transaction on the I2C bus. More...

status_t	I2C_MasterReadBlocking (I2C_Type base, uint8_t rxBuff, size_t rxSize, uint32_t flags)
	Performs a polling receive transaction on the I2C bus. More...

status_t	I2C_SlaveWriteBlocking (I2C_Type base, const uint8_t txBuff, size_t txSize)
	Performs a polling send transaction on the I2C bus. More...

void	I2C_SlaveReadBlocking (I2C_Type base, uint8_t rxBuff, size_t rxSize)
	Performs a polling receive transaction on the I2C bus. More...

status_t	I2C_MasterTransferBlocking (I2C_Type base, i2c_master_transfer_t xfer)
	Performs a master polling transfer on the I2C bus. More...

Transactional
void	I2C_MasterTransferCreateHandle (I2C_Type base, i2c_master_handle_t handle, i2c_master_transfer_callback_t callback, void *userData)
	Initializes the I2C handle which is used in transactional functions. More...

status_t	I2C_MasterTransferNonBlocking (I2C_Type base, i2c_master_handle_t handle, i2c_master_transfer_t *xfer)
	Performs a master interrupt non-blocking transfer on the I2C bus. More...

status_t	I2C_MasterTransferGetCount (I2C_Type base, i2c_master_handle_t handle, size_t *count)
	Gets the master transfer status during a interrupt non-blocking transfer. More...

void	I2C_MasterTransferAbort (I2C_Type base, i2c_master_handle_t handle)
	Aborts an interrupt non-blocking transfer early. More...

void	I2C_MasterTransferHandleIRQ (I2C_Type base, void i2cHandle)
	Master interrupt handler. More...

void	I2C_SlaveTransferCreateHandle (I2C_Type base, i2c_slave_handle_t handle, i2c_slave_transfer_callback_t callback, void *userData)
	Initializes the I2C handle which is used in transactional functions. More...

status_t	I2C_SlaveTransferNonBlocking (I2C_Type base, i2c_slave_handle_t handle, uint32_t eventMask)
	Starts accepting slave transfers. More...

void	I2C_SlaveTransferAbort (I2C_Type base, i2c_slave_handle_t handle)
	Aborts the slave transfer. More...

status_t	I2C_SlaveTransferGetCount (I2C_Type base, i2c_slave_handle_t handle, size_t *count)
	Gets the slave transfer remaining bytes during a interrupt non-blocking transfer. More...

void	I2C_SlaveTransferHandleIRQ (I2C_Type base, void i2cHandle)
	Slave interrupt handler. More...

Data Structure Documentation

struct i2c_master_config_t

Data Fields
bool	enableMaster
	Enables the I2C peripheral at initialization time. More...

bool	enableStopHold
	Controls the stop hold enable. More...

bool	enableDoubleBuffering
	Controls double buffer enable; notice that enabling the double buffer disables the clock stretch. More...

uint32_t	baudRate_Bps
	Baud rate configuration of I2C peripheral. More...

uint8_t	glitchFilterWidth
	Controls the width of the glitch. More...

Field Documentation

bool i2c_master_config_t::enableMaster

bool i2c_master_config_t::enableStopHold

bool i2c_master_config_t::enableDoubleBuffering

uint32_t i2c_master_config_t::baudRate_Bps

uint8_t i2c_master_config_t::glitchFilterWidth

struct i2c_slave_config_t

Data Fields
bool	enableSlave
	Enables the I2C peripheral at initialization time. More...

bool	enableGeneralCall
	Enables the general call addressing mode. More...

bool	enableWakeUp
	Enables/disables waking up MCU from low-power mode. More...

bool	enableDoubleBuffering
	Controls a double buffer enable; notice that enabling the double buffer disables the clock stretch. More...

bool	enableBaudRateCtl
	Enables/disables independent slave baud rate on SCL in very fast I2C modes. More...

uint16_t	slaveAddress
	A slave address configuration. More...

uint16_t	upperAddress
	A maximum boundary slave address used in a range matching mode. More...

i2c_slave_address_mode_t	addressingMode
	An addressing mode configuration of i2c_slave_address_mode_config_t. More...

uint32_t	sclStopHoldTime_ns
	the delay from the rising edge of SCL (I2C clock) to the rising edge of SDA (I2C data) while SCL is high (stop condition), SDA hold time and SCL start hold time are also configured according to the SCL stop hold time. More...

Field Documentation

bool i2c_slave_config_t::enableSlave

bool i2c_slave_config_t::enableGeneralCall

bool i2c_slave_config_t::enableWakeUp

bool i2c_slave_config_t::enableDoubleBuffering

bool i2c_slave_config_t::enableBaudRateCtl

uint16_t i2c_slave_config_t::slaveAddress

uint16_t i2c_slave_config_t::upperAddress

i2c_slave_address_mode_t i2c_slave_config_t::addressingMode

uint32_t i2c_slave_config_t::sclStopHoldTime_ns

struct i2c_master_transfer_t

Data Fields
uint32_t	flags
	A transfer flag which controls the transfer. More...

uint8_t	slaveAddress
	7-bit slave address. More...

i2c_direction_t	direction
	A transfer direction, read or write. More...

uint32_t	subaddress
	A sub address. More...

uint8_t	subaddressSize
	A size of the command buffer. More...

uint8_t *volatile	data
	A transfer buffer. More...

volatile size_t	dataSize
	A transfer size. More...

Field Documentation

uint32_t i2c_master_transfer_t::flags

uint8_t i2c_master_transfer_t::slaveAddress

i2c_direction_t i2c_master_transfer_t::direction

uint32_t i2c_master_transfer_t::subaddress

Transferred MSB first.

uint8_t i2c_master_transfer_t::subaddressSize

uint8_t* volatile i2c_master_transfer_t::data

volatile size_t i2c_master_transfer_t::dataSize

struct _i2c_master_handle

I2C master handle typedef.

Data Fields
i2c_master_transfer_t	transfer
	I2C master transfer copy. More...

size_t	transferSize
	Total bytes to be transferred. More...

uint8_t	state
	A transfer state maintained during transfer. More...

i2c_master_transfer_callback_t	completionCallback
	A callback function called when the transfer is finished. More...

void *	userData
	A callback parameter passed to the callback function. More...

Field Documentation

i2c_master_transfer_t i2c_master_handle_t::transfer

size_t i2c_master_handle_t::transferSize

uint8_t i2c_master_handle_t::state

i2c_master_transfer_callback_t i2c_master_handle_t::completionCallback

void* i2c_master_handle_t::userData

struct i2c_slave_transfer_t

Data Fields
i2c_slave_transfer_event_t	event
	A reason that the callback is invoked. More...

uint8_t *volatile	data
	A transfer buffer. More...

volatile size_t	dataSize
	A transfer size. More...

status_t	completionStatus
	Success or error code describing how the transfer completed. More...

size_t	transferredCount
	A number of bytes actually transferred since the start or since the last repeated start. More...

Field Documentation

i2c_slave_transfer_event_t i2c_slave_transfer_t::event

uint8_t* volatile i2c_slave_transfer_t::data

volatile size_t i2c_slave_transfer_t::dataSize

status_t i2c_slave_transfer_t::completionStatus

Only applies for kI2C_SlaveCompletionEvent.

size_t i2c_slave_transfer_t::transferredCount

struct _i2c_slave_handle

I2C slave handle typedef.

Data Fields
volatile bool	isBusy
	Indicates whether a transfer is busy. More...

i2c_slave_transfer_t	transfer
	I2C slave transfer copy. More...

uint32_t	eventMask
	A mask of enabled events. More...

i2c_slave_transfer_callback_t	callback
	A callback function called at the transfer event. More...

void *	userData
	A callback parameter passed to the callback. More...

Field Documentation

volatile bool i2c_slave_handle_t::isBusy

i2c_slave_transfer_t i2c_slave_handle_t::transfer

uint32_t i2c_slave_handle_t::eventMask

i2c_slave_transfer_callback_t i2c_slave_handle_t::callback

void* i2c_slave_handle_t::userData

Macro Definition Documentation

#define FSL_I2C_DRIVER_VERSION (MAKE_VERSION(2, 0, 3))

Typedef Documentation

typedef void(* i2c_master_transfer_callback_t)(I2C_Type *base, i2c_master_handle_t *handle, status_t status, void *userData)

typedef void(* i2c_slave_transfer_callback_t)(I2C_Type *base, i2c_slave_transfer_t *xfer, void *userData)

Enumeration Type Documentation

enum _i2c_status

Enumerator
kStatus_I2C_Busy	I2C is busy with current transfer.
kStatus_I2C_Idle	Bus is Idle.
kStatus_I2C_Nak	NAK received during transfer.
kStatus_I2C_ArbitrationLost	Arbitration lost during transfer.
kStatus_I2C_Timeout	Wait event timeout.
kStatus_I2C_Addr_Nak	NAK received during the address probe.

enum _i2c_flags

The following status register flags can be cleared:

Note: These enumerations are meant to be OR'd together to form a bit mask.

Enumerator
kI2C_ReceiveNakFlag	I2C receive NAK flag.
kI2C_IntPendingFlag	I2C interrupt pending flag.
kI2C_TransferDirectionFlag	I2C transfer direction flag.
kI2C_RangeAddressMatchFlag	I2C range address match flag.
kI2C_ArbitrationLostFlag	I2C arbitration lost flag.
kI2C_BusBusyFlag	I2C bus busy flag.
kI2C_AddressMatchFlag	I2C address match flag.
kI2C_TransferCompleteFlag	I2C transfer complete flag.
kI2C_StopDetectFlag	I2C stop detect flag.
kI2C_StartDetectFlag	I2C start detect flag.

enum _i2c_interrupt_enable

Enumerator
kI2C_GlobalInterruptEnable	I2C global interrupt.
kI2C_StartStopDetectInterruptEnable	I2C start&stop detect interrupt.

enum i2c_direction_t

Enumerator
kI2C_Write	Master transmits to the slave.
kI2C_Read	Master receives from the slave.

enum i2c_slave_address_mode_t

Enumerator
kI2C_Address7bit	7-bit addressing mode.
kI2C_RangeMatch	Range address match addressing mode.

enum _i2c_master_transfer_flags

Enumerator
kI2C_TransferDefaultFlag	A transfer starts with a start signal, stops with a stop signal.
kI2C_TransferNoStartFlag	A transfer starts without a start signal.
kI2C_TransferRepeatedStartFlag	A transfer starts with a repeated start signal.
kI2C_TransferNoStopFlag	A transfer ends without a stop signal.

enum i2c_slave_transfer_event_t

These event enumerations are used for two related purposes. First, a bit mask created by OR'ing together events is passed to I2C_SlaveTransferNonBlocking() to specify which events to enable. Then, when the slave callback is invoked, it is passed the current event through its transfer parameter.

Note: These enumerations are meant to be OR'd together to form a bit mask of events.

Enumerator
kI2C_SlaveAddressMatchEvent	Received the slave address after a start or repeated start.
kI2C_SlaveTransmitEvent	A callback is requested to provide data to transmit (slave-transmitter role).
kI2C_SlaveReceiveEvent	A callback is requested to provide a buffer in which to place received data (slave-receiver role).
kI2C_SlaveTransmitAckEvent	A callback needs to either transmit an ACK or NACK.
kI2C_SlaveStartEvent	A start/repeated start was detected.
kI2C_SlaveCompletionEvent	A stop was detected or finished transfer, completing the transfer.
kI2C_SlaveGenaralcallEvent	Received the general call address after a start or repeated start.
kI2C_SlaveAllEvents	A bit mask of all available events.

Function Documentation

void I2C_MasterInit	(	I2C_Type *	base,
		const i2c_master_config_t *	masterConfig,
		uint32_t	srcClock_Hz
	)

Call this API to ungate the I2C clock and configure the I2C with master configuration.

Note: This API should be called at the beginning of the application. Otherwise, any operation to the I2C module can cause a hard fault because the clock is not enabled. The configuration structure can be custom filled or it can be set with default values by using the I2C_MasterGetDefaultConfig(). After calling this API, the master is ready to transfer. This is an example.
* i2c_master_config_t config = {

* .enableMaster = true,

* .enableStopHold = false,

* .highDrive = false,

* .baudRate_Bps = 100000,

* .glitchFilterWidth = 0

* };

* I2C_MasterInit(I2C0, &config, 12000000U);

*

Parameters

base	I2C base pointer
masterConfig	A pointer to the master configuration structure
srcClock_Hz	I2C peripheral clock frequency in Hz

void I2C_SlaveInit	(	I2C_Type *	base,
		const i2c_slave_config_t *	slaveConfig,
		uint32_t	srcClock_Hz
	)

Call this API to ungate the I2C clock and initialize the I2C with the slave configuration.

Note: This API should be called at the beginning of the application. Otherwise, any operation to the I2C module can cause a hard fault because the clock is not enabled. The configuration structure can partly be set with default values by I2C_SlaveGetDefaultConfig() or it can be custom filled by the user. This is an example.
* i2c_slave_config_t config = {

* .enableSlave = true,

* .enableGeneralCall = false,

* .addressingMode = kI2C_Address7bit,

* .slaveAddress = 0x1DU,

* .enableWakeUp = false,

* .enablehighDrive = false,

* .enableBaudRateCtl = false,

* .sclStopHoldTime_ns = 4000

* };

* I2C_SlaveInit(I2C0, &config, 12000000U);

*

Parameters

base	I2C base pointer
slaveConfig	A pointer to the slave configuration structure
srcClock_Hz	I2C peripheral clock frequency in Hz

void I2C_MasterDeinit ( I2C_Type * base )

Call this API to gate the I2C clock. The I2C master module can't work unless the I2C_MasterInit is called.

Parameters

base	I2C base pointer

void I2C_SlaveDeinit ( I2C_Type * base )

Calling this API gates the I2C clock. The I2C slave module can't work unless the I2C_SlaveInit is called to enable the clock.

Parameters

base	I2C base pointer

void I2C_MasterGetDefaultConfig ( i2c_master_config_t * masterConfig )

The purpose of this API is to get the configuration structure initialized for use in the I2C_MasterConfigure(). Use the initialized structure unchanged in the I2C_MasterConfigure() or modify the structure before calling the I2C_MasterConfigure(). This is an example.

* i2c_master_config_t config;
* I2C_MasterGetDefaultConfig(&config);
* 

Parameters

masterConfig A pointer to the master configuration structure.

void I2C_SlaveGetDefaultConfig ( i2c_slave_config_t * slaveConfig )

The purpose of this API is to get the configuration structure initialized for use in the I2C_SlaveConfigure(). Modify fields of the structure before calling the I2C_SlaveConfigure(). This is an example.

* i2c_slave_config_t config;
* I2C_SlaveGetDefaultConfig(&config);
* 

Parameters

slaveConfig A pointer to the slave configuration structure.

static void I2C_Enable	(	I2C_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	I2C base pointer
enable	Pass true to enable and false to disable the module.

uint32_t I2C_MasterGetStatusFlags ( I2C_Type * base )

Parameters

base	I2C base pointer

Returns: status flag, use status flag to AND _i2c_flags to get the related status.

static uint32_t I2C_SlaveGetStatusFlags ( I2C_Type * base )

inlinestatic

Parameters

base	I2C base pointer

Returns: status flag, use status flag to AND _i2c_flags to get the related status.

static void I2C_MasterClearStatusFlags	(	I2C_Type *	base,
		uint32_t	statusMask
	)

inlinestatic

The following status register flags can be cleared kI2C_ArbitrationLostFlag and kI2C_IntPendingFlag.

Parameters

base	I2C base pointer
statusMask	The status flag mask, defined in type i2c_status_flag_t. The parameter can be any combination of the following values: kI2C_StartDetectFlag (if available) kI2C_StopDetectFlag (if available) kI2C_ArbitrationLostFlag kI2C_IntPendingFlagFlag

static void I2C_SlaveClearStatusFlags	(	I2C_Type *	base,
		uint32_t	statusMask
	)

inlinestatic

The following status register flags can be cleared kI2C_ArbitrationLostFlag and kI2C_IntPendingFlag

Parameters

base	I2C base pointer
statusMask	The status flag mask, defined in type i2c_status_flag_t. The parameter can be any combination of the following values: kI2C_StartDetectFlag (if available) kI2C_StopDetectFlag (if available) kI2C_ArbitrationLostFlag kI2C_IntPendingFlagFlag

void I2C_EnableInterrupts	(	I2C_Type *	base,
		uint32_t	mask
	)

Parameters

base	I2C base pointer
mask	interrupt source The parameter can be combination of the following source if defined: kI2C_GlobalInterruptEnable kI2C_StopDetectInterruptEnable/kI2C_StartDetectInterruptEnable kI2C_SdaTimeoutInterruptEnable

void I2C_DisableInterrupts	(	I2C_Type *	base,
		uint32_t	mask
	)

Parameters

base	I2C base pointer
mask	interrupt source The parameter can be combination of the following source if defined: kI2C_GlobalInterruptEnable kI2C_StopDetectInterruptEnable/kI2C_StartDetectInterruptEnable kI2C_SdaTimeoutInterruptEnable

static void I2C_EnableDMA	(	I2C_Type *	base,
		bool	enable
	)

inlinestatic

Parameters

base	I2C base pointer
enable	true to enable, false to disable

static uint32_t I2C_GetDataRegAddr ( I2C_Type * base )

inlinestatic

This API is used to provide a transfer address for I2C DMA transfer configuration.

Parameters

base	I2C base pointer

Returns: data register address

void I2C_MasterSetBaudRate	(	I2C_Type *	base,
		uint32_t	baudRate_Bps,
		uint32_t	srcClock_Hz
	)

Parameters

base	I2C base pointer
baudRate_Bps	the baud rate value in bps
srcClock_Hz	Source clock

status_t I2C_MasterStart	(	I2C_Type *	base,
		uint8_t	address,
		i2c_direction_t	direction
	)

This function is used to initiate a new master mode transfer by sending the START signal. The slave address is sent following the I2C START signal.

Parameters

base	I2C peripheral base pointer
address	7-bit slave device address.
direction	Master transfer directions(transmit/receive).

Return values

kStatus_Success	Successfully send the start signal.
kStatus_I2C_Busy	Current bus is busy.

status_t I2C_MasterStop ( I2C_Type * base )

Return values

kStatus_Success	Successfully send the stop signal.
kStatus_I2C_Timeout	Send stop signal failed, timeout.

status_t I2C_MasterRepeatedStart	(	I2C_Type *	base,
		uint8_t	address,
		i2c_direction_t	direction
	)

Parameters

base	I2C peripheral base pointer
address	7-bit slave device address.
direction	Master transfer directions(transmit/receive).

Return values

kStatus_Success	Successfully send the start signal.
kStatus_I2C_Busy	Current bus is busy but not occupied by current I2C master.

status_t I2C_MasterWriteBlocking	(	I2C_Type *	base,
		const uint8_t *	txBuff,
		size_t	txSize,
		uint32_t	flags
	)

Parameters

base	The I2C peripheral base pointer.
txBuff	The pointer to the data to be transferred.
txSize	The length in bytes of the data to be transferred.
flags	Transfer control flag to decide whether need to send a stop, use kI2C_TransferDefaultFlag to issue a stop and kI2C_TransferNoStop to not send a stop.

Return values

kStatus_Success	Successfully complete the data transmission.
kStatus_I2C_ArbitrationLost	Transfer error, arbitration lost.
kStataus_I2C_Nak	Transfer error, receive NAK during transfer.

status_t I2C_MasterReadBlocking	(	I2C_Type *	base,
		uint8_t *	rxBuff,
		size_t	rxSize,
		uint32_t	flags
	)

Note: The I2C_MasterReadBlocking function stops the bus before reading the final byte. Without stopping the bus prior for the final read, the bus issues another read, resulting in garbage data being read into the data register.

Parameters

base	I2C peripheral base pointer.
rxBuff	The pointer to the data to store the received data.
rxSize	The length in bytes of the data to be received.
flags	Transfer control flag to decide whether need to send a stop, use kI2C_TransferDefaultFlag to issue a stop and kI2C_TransferNoStop to not send a stop.

Return values

kStatus_Success	Successfully complete the data transmission.
kStatus_I2C_Timeout	Send stop signal failed, timeout.

status_t I2C_SlaveWriteBlocking	(	I2C_Type *	base,
		const uint8_t *	txBuff,
		size_t	txSize
	)

Parameters

base	The I2C peripheral base pointer.
txBuff	The pointer to the data to be transferred.
txSize	The length in bytes of the data to be transferred.

Return values

kStatus_Success	Successfully complete the data transmission.
kStatus_I2C_ArbitrationLost	Transfer error, arbitration lost.
kStataus_I2C_Nak	Transfer error, receive NAK during transfer.

void I2C_SlaveReadBlocking	(	I2C_Type *	base,
		uint8_t *	rxBuff,
		size_t	rxSize
	)

Parameters

base	I2C peripheral base pointer.
rxBuff	The pointer to the data to store the received data.
rxSize	The length in bytes of the data to be received.

status_t I2C_MasterTransferBlocking	(	I2C_Type *	base,
		i2c_master_transfer_t *	xfer
	)

Note: The API does not return until the transfer succeeds or fails due to arbitration lost or receiving a NAK.

Parameters

base	I2C peripheral base address.
xfer	Pointer to the transfer structure.

Return values

kStatus_Success	Successfully complete the data transmission.
kStatus_I2C_Busy	Previous transmission still not finished.
kStatus_I2C_Timeout	Transfer error, wait signal timeout.
kStatus_I2C_ArbitrationLost	Transfer error, arbitration lost.
kStataus_I2C_Nak	Transfer error, receive NAK during transfer.

void I2C_MasterTransferCreateHandle	(	I2C_Type *	base,
		i2c_master_handle_t *	handle,
		i2c_master_transfer_callback_t	callback,
		void *	userData
	)

Parameters

base	I2C base pointer.
handle	pointer to i2c_master_handle_t structure to store the transfer state.
callback	pointer to user callback function.
userData	user parameter passed to the callback function.

status_t I2C_MasterTransferNonBlocking	(	I2C_Type *	base,
		i2c_master_handle_t *	handle,
		i2c_master_transfer_t *	xfer
	)

Note: Calling the API returns immediately after transfer initiates. The user needs to call I2C_MasterGetTransferCount to poll the transfer status to check whether the transfer is finished. If the return status is not kStatus_I2C_Busy, the transfer is finished.

Parameters

base	I2C base pointer.
handle	pointer to i2c_master_handle_t structure which stores the transfer state.
xfer	pointer to i2c_master_transfer_t structure.

Return values

kStatus_Success	Successfully start the data transmission.
kStatus_I2C_Busy	Previous transmission still not finished.
kStatus_I2C_Timeout	Transfer error, wait signal timeout.

status_t I2C_MasterTransferGetCount	(	I2C_Type *	base,
		i2c_master_handle_t *	handle,
		size_t *	count
	)

Parameters

base	I2C base pointer.
handle	pointer to i2c_master_handle_t structure which stores the transfer state.
count	Number of bytes transferred so far by the non-blocking transaction.

Return values

kStatus_InvalidArgument	count is Invalid.
kStatus_Success	Successfully return the count.

void I2C_MasterTransferAbort	(	I2C_Type *	base,
		i2c_master_handle_t *	handle
	)

Note: This API can be called at any time when an interrupt non-blocking transfer initiates to abort the transfer early.

Parameters

base	I2C base pointer.
handle	pointer to i2c_master_handle_t structure which stores the transfer state

void I2C_MasterTransferHandleIRQ	(	I2C_Type *	base,
		void *	i2cHandle
	)

Parameters

base	I2C base pointer.
i2cHandle	pointer to i2c_master_handle_t structure.

void I2C_SlaveTransferCreateHandle	(	I2C_Type *	base,
		i2c_slave_handle_t *	handle,
		i2c_slave_transfer_callback_t	callback,
		void *	userData
	)

Parameters

base	I2C base pointer.
handle	pointer to i2c_slave_handle_t structure to store the transfer state.
callback	pointer to user callback function.
userData	user parameter passed to the callback function.

status_t I2C_SlaveTransferNonBlocking	(	I2C_Type *	base,
		i2c_slave_handle_t *	handle,
		uint32_t	eventMask
	)

Call this API after calling the I2C_SlaveInit() and I2C_SlaveTransferCreateHandle() to start processing transactions driven by an I2C master. The slave monitors the I2C bus and passes events to the callback that was passed into the call to I2C_SlaveTransferCreateHandle(). The callback is always invoked from the interrupt context.

The set of events received by the callback is customizable. To do so, set the eventMask parameter to the OR'd combination of i2c_slave_transfer_event_t enumerators for the events you wish to receive. The kI2C_SlaveTransmitEvent and #kLPI2C_SlaveReceiveEvent events are always enabled and do not need to be included in the mask. Alternatively, pass 0 to get a default set of only the transmit and receive events that are always enabled. In addition, the kI2C_SlaveAllEvents constant is provided as a convenient way to enable all events.

Parameters

base	The I2C peripheral base address.
handle	Pointer to #i2c_slave_handle_t structure which stores the transfer state.
eventMask	Bit mask formed by OR'ing together i2c_slave_transfer_event_t enumerators to specify which events to send to the callback. Other accepted values are 0 to get a default set of only the transmit and receive events, and kI2C_SlaveAllEvents to enable all events.

Return values

#kStatus_Success	Slave transfers were successfully started.
kStatus_I2C_Busy	Slave transfers have already been started on this handle.

void I2C_SlaveTransferAbort	(	I2C_Type *	base,
		i2c_slave_handle_t *	handle
	)

Note: This API can be called at any time to stop slave for handling the bus events.

Parameters

base	I2C base pointer.
handle	pointer to i2c_slave_handle_t structure which stores the transfer state.

status_t I2C_SlaveTransferGetCount	(	I2C_Type *	base,
		i2c_slave_handle_t *	handle,
		size_t *	count
	)

Parameters

base	I2C base pointer.
handle	pointer to i2c_slave_handle_t structure.
count	Number of bytes transferred so far by the non-blocking transaction.

Return values

kStatus_InvalidArgument	count is Invalid.
kStatus_Success	Successfully return the count.

void I2C_SlaveTransferHandleIRQ	(	I2C_Type *	base,
		void *	i2cHandle
	)

Parameters

base	I2C base pointer.
i2cHandle	pointer to i2c_slave_handle_t structure which stores the transfer state

Overview

Typical use case

Master Operation in functional method

Master Operation in interrupt transactional method

Master Operation in DMA transactional method

Slave Operation in functional method

Slave Operation in interrupt transactional method

Data Structures

Typedefs

Enumerations

Driver version

Initialization and deinitialization

Status

Interrupts

DMA Control

Bus Operations

Transactional

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation