Kinetis SDK v.2.0 API Reference Manual  Rev. 0
Freescale Semiconductor, Inc.
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

Overview

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

Overview

The I2C driver includes functional APIs and transactional APIs.

Functional APIs are feature/property target 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 the knowledge of 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 are transaction target 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];
/* Get default configuration for master.
I2C_MasterGetDefaultConfig(&masterConfig);
/* Init I2C master.
I2C_MasterInit(EXAMPLE_I2C_MASTER_BASEADDR, &masterConfig, I2C_MASTER_CLK);
/* Send start and slave address.
I2C_MasterStart(EXAMPLE_I2C_MASTER_BASEADDR, 7-bit slave address, kI2C_Write/kI2C_Read);
/* Wait address sent out.
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);
if(result)
{
/* If error occours, send STOP.
I2C_MasterStop(EXAMPLE_I2C_MASTER_BASEADDR, kI2CStop);
return result;
}
while(!(I2C_GetStatusFlag(EXAMPLE_I2C_MASTER_BASEADDR) & kI2C_IntPendingFlag))
{
}
/* Wait all data sent out, send STOP.
I2C_MasterStop(EXAMPLE_I2C_MASTER_BASEADDR, kI2CStop);

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];
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;
}
}
/* Get default configuration for master.
I2C_MasterGetDefaultConfig(&masterConfig);
/* Init 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);
/* Wait for transfer 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];
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;
}
}
/* Get default configuration for master.
I2C_MasterGetDefaultConfig(&masterConfig);
/* Init 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); /*default configuration 7-bit addressing mode
slaveConfig.slaveAddr = 7-bit address
slaveConfig.addressingMode = kI2C_Address7bit/kI2C_RangeMatch;
I2C_SlaveInit(EXAMPLE_I2C_SLAVE_BASEADDR, &slaveConfig);
/* Wait address match.
while(!((status = I2C_GetStatusFlag(EXAMPLE_I2C_SLAVE_BASEADDR)) & kI2C_AddressMatchFlag))
{
}
/* Slave transmit, master reading from slave.
if (status & kI2C_TransferDirectionFlag)
{
result = I2C_SlaveWriteBlocking(EXAMPLE_I2C_SLAVE_BASEADDR);
}
else
{
I2C_SlaveReadBlocking(EXAMPLE_I2C_SLAVE_BASEADDR);
}
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;
/* Receive request
case kI2C_SlaveReceiveEvent:
/* Update information for received process
xfer->data = g_slave_buff;
xfer->dataSize = I2C_DATA_LENGTH;
break;
/* Transfer done
case kI2C_SlaveCompletionEvent:
g_SlaveCompletionFlag = true;
break;
default:
g_SlaveCompletionFlag = true;
break;
}
}
I2C_SlaveGetDefaultConfig(&slaveConfig); /*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_SlaveTransferCreateHandle(EXAMPLE_I2C_SLAVE_BASEADDR, &g_s_handle, i2c_slave_callback, NULL);
I2C_SlaveTransferNonBlocking(EXAMPLE_I2C_SLAVE_BASEADDR, &g_s_handle, kI2C_SlaveCompletionEvent);
/* Wait for transfer completed.
while (!g_SlaveCompletionFlag)
{
}
g_SlaveCompletionFlag = false;

Files

file  fsl_i2c.h
 

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)
}
 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
}
 I2C peripheral flags. More...
 
enum  _i2c_interrupt_enable { kI2C_GlobalInterruptEnable = I2C_C1_IICIE_MASK }
 I2C feature interrupt source. More...
 
enum  i2c_direction_t {
  kI2C_Write = 0x0U,
  kI2C_Read = 0x1U
}
 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_SlaveCompletionEvent = 0x20U,
  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, 0))
 I2C driver version 2.0.0. 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)
 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 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)
 Performs a polling send transaction on the I2C bus without a STOP signal. More...
 
status_t I2C_MasterReadBlocking (I2C_Type *base, uint8_t *rxBuff, size_t rxSize)
 Performs a polling receive transaction on the I2C bus with a STOP signal. 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...
 
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
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
 Enable general call addressing mode. More...
 
bool enableWakeUp
 Enables/disables waking up MCU from low power mode. More...
 
bool enableBaudRateCtl
 Enables/disables independent slave baud rate on SCL in very fast I2C modes. More...
 
uint16_t slaveAddress
 Slave address configuration. More...
 
uint16_t upperAddress
 Maximum boundary slave address used in range matching mode. More...
 
i2c_slave_address_mode_t addressingMode
 Addressing mode configuration of i2c_slave_address_mode_config_t. 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::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
struct i2c_master_transfer_t

Data Fields

uint32_t flags
 Transfer flag which controls the transfer. More...
 
uint8_t slaveAddress
 7-bit slave address. More...
 
i2c_direction_t direction
 Transfer direction, read or write. More...
 
uint32_t subaddress
 Sub address. More...
 
uint8_t subaddressSize
 Size of command buffer. More...
 
uint8_t *volatile data
 Transfer buffer. More...
 
volatile size_t dataSize
 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
 Transfer state maintained during transfer. More...
 
i2c_master_transfer_callback_t completionCallback
 Callback function called when transfer finished. More...
 
void * userData
 Callback parameter passed to 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
 Reason the callback is being invoked. More...
 
uint8_t *volatile data
 Transfer buffer. More...
 
volatile size_t dataSize
 Transfer size. More...
 
status_t completionStatus
 Success or error code describing how the transfer completed. More...
 
size_t transferredCount
 Number of bytes actually transferred since start or 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

bool isBusy
 Whether transfer is busy. More...
 
i2c_slave_transfer_t transfer
 I2C slave transfer copy. More...
 
uint32_t eventMask
 Mask of enabled events. More...
 
i2c_slave_transfer_callback_t callback
 Callback function called at transfer event. More...
 
void * userData
 Callback parameter passed to callback. More...
 

Field Documentation

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, 0))

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

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.

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.

Enumerator
kI2C_GlobalInterruptEnable 

I2C global interrupt.

Enumerator
kI2C_Write 

Master transmit to slave.

kI2C_Read 

Master receive from slave.

Enumerator
kI2C_Address7bit 

7-bit addressing mode.

kI2C_RangeMatch 

Range address match addressing mode.

Enumerator
kI2C_TransferDefaultFlag 

Transfer starts with a start signal, stops with a stop signal.

kI2C_TransferNoStartFlag 

Transfer starts without a start signal.

kI2C_TransferRepeatedStartFlag 

Transfer starts with a repeated start signal.

kI2C_TransferNoStopFlag 

Transfer ends without a stop signal.

These event enumerations are used for two related purposes. First, a bit mask created by OR'ing together events is passed to I2C_SlaveTransferNonBlocking() in order 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 

Callback is requested to provide data to transmit (slave-transmitter role).

kI2C_SlaveReceiveEvent 

Callback is requested to provide a buffer in which to place received data (slave-receiver role).

kI2C_SlaveTransmitAckEvent 

Callback needs to either transmit an ACK or NACK.

kI2C_SlaveCompletionEvent 

A stop was detected or finished transfer, completing the transfer.

kI2C_SlaveAllEvents 

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 to use the I2C driver, or any operation to the I2C module could cause hard fault because clock is not enabled. The configuration structure can be filled by user from scratch, or be set with default values by I2C_MasterGetDefaultConfig(). After calling this API, the master is ready to transfer. Example:
.enableMaster = true,
.enableStopHold = false,
.highDrive = false,
.baudRate_Bps = 100000,
.glitchFilterWidth = 0
};
I2C_MasterInit(I2C0, &config, 12000000U);
Parameters
baseI2C base pointer
masterConfigpointer to master configuration structure
srcClock_HzI2C peripheral clock frequency in Hz
void I2C_SlaveInit ( I2C_Type *  base,
const i2c_slave_config_t slaveConfig 
)

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

Note
This API should be called at the beginning of the application to use the I2C driver, or 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 can be filled by the user. Example
.enableSlave = true,
.enableGeneralCall = false,
.addressingMode = kI2C_Address7bit,
.slaveAddress = 0x1DU,
.enableWakeUp = false,
.enablehighDrive = false,
.enableBaudRateCtl = false
};
I2C_SlaveInit(I2C0, &config);
Parameters
baseI2C base pointer
slaveConfigpointer to slave configuration structure
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
baseI2C 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
baseI2C 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 I2C_MasterConfigure(), or modify some fields of the structure before calling I2C_MasterConfigure(). Example:

Parameters
masterConfigPointer 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 I2C_SlaveConfigure(). Modify fields of the structure before calling the I2C_SlaveConfigure(). Example:

Parameters
slaveConfigPointer to the slave configuration structure.
static void I2C_Enable ( I2C_Type *  base,
bool  enable 
)
inlinestatic
Parameters
baseI2C base pointer
enablepass true to enable module, false to disable module
uint32_t I2C_MasterGetStatusFlags ( I2C_Type *  base)
Parameters
baseI2C base pointer
Returns
status flag, use status flag to AND _i2c_flags could get the related status.
static uint32_t I2C_SlaveGetStatusFlags ( I2C_Type *  base)
inlinestatic
Parameters
baseI2C base pointer
Returns
status flag, use status flag to AND _i2c_flags could 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
baseI2C base pointer
statusMaskThe status flag mask, defined in type i2c_status_flag_t. The parameter could 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
baseI2C base pointer
statusMaskThe status flag mask, defined in type i2c_status_flag_t. The parameter could 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
baseI2C base pointer
maskinterrupt 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
baseI2C base pointer
maskinterrupt source The parameter can be combination of the following source if defined:
  • kI2C_GlobalInterruptEnable
  • kI2C_StopDetectInterruptEnable/kI2C_StartDetectInterruptEnable
  • kI2C_SdaTimeoutInterruptEnable
static uint32_t I2C_GetDataRegAddr ( I2C_Type *  base)
inlinestatic

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

Parameters
baseI2C base pointer
Returns
data register address
void I2C_MasterSetBaudRate ( I2C_Type *  base,
uint32_t  baudRate_Bps,
uint32_t  srcClock_Hz 
)
Parameters
baseI2C base pointer
baudRate_Bpsthe baud rate value in bps
srcClock_HzSource 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
baseI2C peripheral base pointer
address7-bit slave device address.
directionMaster transfer directions(transmit/receive).
Return values
kStatus_SuccessSuccessfully send the start signal.
kStatus_I2C_BusyCurrent bus is busy.
status_t I2C_MasterStop ( I2C_Type *  base)
Return values
kStatus_SuccessSuccessfully send the stop signal.
kStatus_I2C_TimeoutSend stop signal failed, timeout.
status_t I2C_MasterRepeatedStart ( I2C_Type *  base,
uint8_t  address,
i2c_direction_t  direction 
)
Parameters
baseI2C peripheral base pointer
address7-bit slave device address.
directionMaster transfer directions(transmit/receive).
Return values
kStatus_SuccessSuccessfully send the start signal.
kStatus_I2C_BusyCurrent bus is busy but not occupied by current I2C master.
status_t I2C_MasterWriteBlocking ( I2C_Type *  base,
const uint8_t *  txBuff,
size_t  txSize 
)
Parameters
baseThe I2C peripheral base pointer.
txBuffThe pointer to the data to be transferred.
txSizeThe length in bytes of the data to be transferred.
Return values
kStatus_SuccessSuccessfully complete the data transmission.
kStatus_I2C_ArbitrationLostTransfer error, arbitration lost.
kStataus_I2C_NakTransfer error, receive NAK during transfer.
status_t I2C_MasterReadBlocking ( I2C_Type *  base,
uint8_t *  rxBuff,
size_t  rxSize 
)
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
baseI2C peripheral base pointer.
rxBuffThe pointer to the data to store the received data.
rxSizeThe length in bytes of the data to be received.
Return values
kStatus_SuccessSuccessfully complete the data transmission.
kStatus_I2C_TimeoutSend stop signal failed, timeout.
status_t I2C_SlaveWriteBlocking ( I2C_Type *  base,
const uint8_t *  txBuff,
size_t  txSize 
)
Parameters
baseThe I2C peripheral base pointer.
txBuffThe pointer to the data to be transferred.
txSizeThe length in bytes of the data to be transferred.
Return values
kStatus_SuccessSuccessfully complete the data transmission.
kStatus_I2C_ArbitrationLostTransfer error, arbitration lost.
kStataus_I2C_NakTransfer error, receive NAK during transfer.
void I2C_SlaveReadBlocking ( I2C_Type *  base,
uint8_t *  rxBuff,
size_t  rxSize 
)
Parameters
baseI2C peripheral base pointer.
rxBuffThe pointer to the data to store the received data.
rxSizeThe 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
baseI2C peripheral base address.
xferPointer to the transfer structure.
Return values
kStatus_SuccessSuccessfully complete the data transmission.
kStatus_I2C_BusyPrevious transmission still not finished.
kStatus_I2C_TimeoutTransfer error, wait signal timeout.
kStatus_I2C_ArbitrationLostTransfer error, arbitration lost.
kStataus_I2C_NakTransfer 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
baseI2C base pointer.
handlepointer to i2c_master_handle_t structure to store the transfer state.
callbackpointer to user callback function.
userDatauser paramater 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 will return immediately after transfer initiates, 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
baseI2C base pointer.
handlepointer to i2c_master_handle_t structure which stores the transfer state.
xferpointer to i2c_master_transfer_t structure.
Return values
kStatus_SuccessSucessully start the data transmission.
kStatus_I2C_BusyPrevious transmission still not finished.
kStatus_I2C_TimeoutTransfer error, wait signal timeout.
status_t I2C_MasterTransferGetCount ( I2C_Type *  base,
i2c_master_handle_t *  handle,
size_t *  count 
)
Parameters
baseI2C base pointer.
handlepointer to i2c_master_handle_t structure which stores the transfer state.
countNumber of bytes transferred so far by the non-blocking transaction.
Return values
kStatus_InvalidArgumentcount is Invalid.
kStatus_SuccessSuccessfully 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
baseI2C base pointer.
handlepointer to i2c_master_handle_t structure which stores the transfer state
void I2C_MasterTransferHandleIRQ ( I2C_Type *  base,
void *  i2cHandle 
)
Parameters
baseI2C base pointer.
i2cHandlepointer 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
baseI2C base pointer.
handlepointer to i2c_slave_handle_t structure to store the transfer state.
callbackpointer to user callback function.
userDatauser 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
baseThe I2C peripheral base address.
handlePointer to #i2c_slave_handle_t structure which stores the transfer state.
eventMaskBit 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_SuccessSlave transfers were successfully started.
kStatus_I2C_BusySlave 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
baseI2C base pointer.
handlepointer 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
baseI2C base pointer.
handlepointer to i2c_slave_handle_t structure.
countNumber of bytes transferred so far by the non-blocking transaction.
Return values
kStatus_InvalidArgumentcount is Invalid.
kStatus_SuccessSuccessfully return the count.
void I2C_SlaveTransferHandleIRQ ( I2C_Type *  base,
void *  i2cHandle 
)
Parameters
baseI2C base pointer.
i2cHandlepointer to i2c_slave_handle_t structure which stores the transfer state