Inter Integrated Circuit - Peripheral Abstraction Layer(I2C PAL)

Detailed Description

Inter Integrated Circuit- Peripheral Abstraction Layer.

The I2C PAL driver allows communication on an I2C bus. It was designed to be portable across all platforms and IPs which support I2C communication.

How to integrate I2C in your application

I2C PAL modules need to include a configuration file named i2c_pal_cfg.h, which allows the user to specify which IPSs are used and how many resources are allocated for each of them (state structures). The following code example shows how to configure one instance for each available I2C IPs.

#ifndef I2C_PAL_cfg_H
#define I2C_PAL_cfg_H
/* Define which IP instance will be used in current project */
#define I2C_OVER_LPI2C
#define I2C_OVER_FLEXIO
#define I2C_OVER_I2C
#define I2C_OVER_SWI2C
/* Define the resources necessary for current project */
#define NO_OF_LPI2C_INSTS_FOR_I2C 2
#define NO_OF_FLEXIO_INSTS_FOR_I2C 1
#define NO_OF_I2C_INSTS_FOR_I2C 0
#define NO_OF_SWI2C_INSTS_FOR_I2C 1
#endif /* I2C_PAL_cfg_H */

The following table contains the matching between platforms and available IPs

IP/MCU S32K142S32K144S32K148MPC5748GMPC5746CMPC5744P
LPI2C YES YES YES NO NO NO
FlexIO YES YES YES NO NO NO
I2C NO NO NO YES YES YES
SWI2C NO NO NO YES YES YES

In order to use the I2C driver it must be first initialized in either master or slave mode, using functions I2C_MasterInit() or I2C_SlaveInit(). Once initialized, it cannot be initialized again for the same I2C module instance until it is de-initialized, using I2C_SlaveDeinit() or I2C_MasterDeinit. Different I2C module instances can work independently of each other.

In each mode (master/slave) are available two types of transfers: blocking and non-blocking. The functions which initiate blocking transfers will configure the time out for transmission. If time expires the blocking functions will return STATUS_TIMEOUT and transmission will be aborted. The blocking functions are: I2C_MasterSendDataBlocking, I2C_MasterReceiveDataBlocking, I2C_SlaveSendDataBlocking and I2C_SlaveReceiveDataBlocking.

Slave Mode provides functions for transmitting or receiving data to/from any I2C master. There are two slave operating modes, selected by the field slaveListening in the slave configuration structure:

The configuration structure includes a special field named extension. It will be used only for I2C transfers over FLEXIO and should contain a pointer to extension_flexio_for_i2c_t structure. The purpose of this structure is to configure which FLEXIO pins are used by the applications and their functionality (SDA and SCL).

Important Notes

Example code

/* Configure I2C master */
i2c_master_t i2c1_MasterConfig0 =
{
.slaveAddress = 10,
.is10bitAddr = false,
.baudRate = 100000,
.transferType = I2C_PAL_USING_INTERRUPTS,
.operatingMode = I2C_PAL_STANDARD_MODE,
.dmaChannel1 = 255,
.dmaChannel2 = 255,
.callback = NULL,
.callbackParam = NULL,
.extension = NULL
};
/* Configure I2C slave */
i2c_slave_t i2c2_SlaveConfig0 =
{
.slaveAddress = 10,
.is10bitAddr = false,
.slaveListening = true,
.transferType = I2C_PAL_USING_INTERRUPTS,
.dmaChannel = 255,
.callback = i2c2_SlaveCallback0,
.callbackParam = NULL
};
i2c_instance_t i2c1_instance = {I2C_INST_TYPE_FLEXIO, 0U};
i2c_instance_t i2c2_instance = {I2C_INST_TYPE_LPI2C, 0U};
i2c_instance_t i2c3_instance = {I2C_INST_TYPE_LPI2C, 1U};
/* Callback for I2C slave */
void i2c2_SlaveCallback0(i2c_slave_event_t slaveEvent, void *userData)
{
/* Get instance number from userData */
i2c_instance_t * instance;
instance = (i2c_instance_t *) userData;
/* Check the event type:
* - set RX or TX buffers depending on the master request type
*/
if (slaveEvent == I2C_SLAVE_EVENT_RX_REQ)
I2C_SlaveSetRxBuffer(instance, slaveRxBuffer, TRANSFER_SIZE);
if (slaveEvent == I2C_SLAVE_EVENT_TX_REQ)
I2C_SlaveSetTxBuffer(instance, slaveTxBuffer, TRANSFER_SIZE);
}
/* Configure FLEXIO pins routing */
extension.sclPin = 1;
extension.sdaPin = 0;
i2c1_MasterConfig0.extension = &extension;
/* Buffers */
uint8_t slaveTxBuffer[16] = {0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xA, 0xB, 0xC, 0xD, 0xE, 0xF};
uint8_t slaveRxBuffer[16] = {0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0};
uint8_t masterTxBuffer[16] = {0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xA, 0xB, 0xC, 0xD, 0xE, 0xF};
uint8_t masterRxBuffer[16] = {0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0};
/* Initializes I2C master for FlexIO */
I2C_MasterInit(&i2c1_instance, &i2c1_MasterConfig0);
/* Initialize I2C slave instance for LPI2C driver*/
I2C_SlaveInit(&i2c2_instance, &i2c2_SlaveConfig0);
/* FlexIO master sends masterTxBuffer to LPI2C0 configured as slave */
I2C_MasterSendDataBlocking(&i2c1_instance, masterTxBuffer, BUFFER_SIZE, true, 0xFF);
/* Initialize I2C master for LPI2C1 instance */
I2C_MasterInit(&i2c3_instance, &i2c1_MasterConfig0);
/* LPI2C1 master sends data to LPI2C0 configured as slave */
I2C_MasterSendDataBlocking(&i2c3_instance, masterTxBuffer, BUFFER_SIZE, true, 0xFF);
/* De-initialize I2C modules */
I2C_MasterDeinit(&i2c1_instance);
I2C_MasterDeinit(&i2c3_instance);
I2C_SlaveDeinit(&i2c2_instance);

Data Structures

struct  extension_flexio_for_i2c_t
 Defines the extension structure for the I2C over FLEXIO Implements : extension_flexio_for_i2c_t_Class. More...
 
struct  i2c_master_t
 Defines the configuration structure for I2C master Implements : i2c_master_t_Class. More...
 
struct  i2c_slave_t
 Defines the configuration structure for I2C slave Implements: i2c_slave_t_Class. More...
 

Enumerations

enum  i2c_pal_transfer_type_t { I2C_PAL_USING_DMA = 0U, I2C_PAL_USING_INTERRUPTS = 1U }
 Defines the mechanism to update the rx or tx buffers Implements : i2c_pal_transfer_type_t_Class. More...
 
enum  i2c_operating_mode_t {
  I2C_PAL_STANDARD_MODE = 0x0U, I2C_PAL_FAST_MODE = 0x1U, I2C_PAL_FASTPLUS_MODE = 0x2U, I2C_PAL_HIGHSPEED_MODE = 0x3U,
  I2C_PAL_ULTRAFAST_MODE = 0x4U
}
 Defines the operation mode of the i2c pal Implements : i2c_operating_mode_t_Class. More...
 

Functions

status_t I2C_MasterInit (const i2c_instance_t *const instance, const i2c_master_t *config)
 Initializes the I2C module in master mode. More...
 
status_t I2C_MasterSendData (const i2c_instance_t *const instance, const uint8_t *txBuff, uint32_t txSize, bool sendStop)
 Perform a non-blocking send transaction on the I2C bus. More...
 
status_t I2C_MasterSendDataBlocking (const i2c_instance_t *const instance, const uint8_t *txBuff, uint32_t txSize, bool sendStop, uint32_t timeout)
 Perform a blocking send transaction on the I2C bus. More...
 
status_t I2C_MasterReceiveData (const i2c_instance_t *const instance, uint8_t *rxBuff, uint32_t rxSize, bool sendStop)
 Perform a non-blocking receive transaction on the I2C bus. More...
 
status_t I2C_MasterReceiveDataBlocking (const i2c_instance_t *const instance, uint8_t *rxBuff, uint32_t rxSize, bool sendStop, uint32_t timeout)
 Perform a blocking receive transaction on the I2C bus. More...
 
status_t I2C_MasterSetSlaveAddress (const i2c_instance_t *const instance, const uint16_t address, const bool is10bitAddr)
 Set the slave address for the I2C communication. More...
 
status_t I2C_MasterDeinit (const i2c_instance_t *const instance)
 De-initializes the I2C master module. More...
 
status_t I2C_GetDefaultMasterConfig (i2c_master_t *config)
 Gets the default configuration structure for master. More...
 
status_t I2C_GetDefaultSlaveConfig (i2c_slave_t *config)
 Gets the default configuration structure for slave. More...
 
status_t I2C_SlaveInit (const i2c_instance_t *const instance, const i2c_slave_t *config)
 Initializes the I2C module in slave mode. More...
 
status_t I2C_SlaveSendData (const i2c_instance_t *const instance, const uint8_t *txBuff, uint32_t txSize)
 Perform a non-blocking send transaction on the I2C bus. More...
 
status_t I2C_SlaveSendDataBlocking (const i2c_instance_t *const instance, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout)
 Perform a blocking send transaction on the I2C bus. More...
 
status_t I2C_SlaveReceiveData (const i2c_instance_t *const instance, uint8_t *rxBuff, uint32_t rxSize)
 Perform a non-blocking receive transaction on the I2C bus. More...
 
status_t I2C_SlaveReceiveDataBlocking (const i2c_instance_t *const instance, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout)
 Perform a blocking receive transaction on the I2C bus. More...
 
status_t I2C_SlaveSetRxBuffer (const i2c_instance_t *const instance, uint8_t *rxBuff, uint32_t rxSize)
 Provide a buffer for receiving data. More...
 
status_t I2C_SlaveSetTxBuffer (const i2c_instance_t *const instance, const uint8_t *txBuff, uint32_t txSize)
 Provide a buffer for transmitting data. More...
 
status_t I2C_SlaveDeinit (const i2c_instance_t *const instance)
 De-initializes the i2c slave module. More...
 
status_t I2C_MasterGetTransferStatus (const i2c_instance_t *const instance, uint32_t *bytesRemaining)
 Return the current status of the I2C master transfer. More...
 
status_t I2C_SlaveGetTransferStatus (const i2c_instance_t *const instance, uint32_t *bytesRemaining)
 Return the current status of the I2C slave transfer. More...
 
status_t I2C_MasterSetBaudRate (const i2c_instance_t *const instance, const i2c_master_t *config, uint32_t baudRate)
 Set the master baud rate for the I2C communication. More...
 
status_t I2C_MasterGetBaudRate (const i2c_instance_t *const instance, uint32_t *baudRate)
 Get the master baud rate for the I2C communication. More...
 
status_t I2C_MasterAbortTransfer (const i2c_instance_t *const instance)
 Abort a non-blocking I2C Master transmission or reception. More...
 
status_t I2C_SlaveAbortTransfer (const i2c_instance_t *const instance)
 Abort a non-blocking I2C slave transmission or reception. More...
 

Enumeration Type Documentation

Defines the operation mode of the i2c pal Implements : i2c_operating_mode_t_Class.

Enumerator
I2C_PAL_STANDARD_MODE 

Standard-mode (Sm), bidirectional data transfers up to 100 kbit/s

I2C_PAL_FAST_MODE 

Fast-mode (Fm), bidirectional data transfers up to 400 kbit/s

I2C_PAL_FASTPLUS_MODE 

Fast-mode Plus (Fm+), bidirectional data transfers up to 1 Mbit/s

I2C_PAL_HIGHSPEED_MODE 

High-speed Mode (Hs-mode), bidirectional data transfers up to 3.4 Mbit/s

I2C_PAL_ULTRAFAST_MODE 

Ultra Fast Mode (UFm), unidirectional data transfers up to 5 Mbit/s

Definition at line 90 of file i2c_pal.h.

Defines the mechanism to update the rx or tx buffers Implements : i2c_pal_transfer_type_t_Class.

Enumerator
I2C_PAL_USING_DMA 

The driver will use DMA to perform I2C transfer

I2C_PAL_USING_INTERRUPTS 

The driver will use interrupts to perform I2C transfer

Definition at line 55 of file i2c_pal.h.

Function Documentation

status_t I2C_GetDefaultMasterConfig ( i2c_master_t config)

Gets the default configuration structure for master.

The default configuration structure is:

Parameters
[out]configPointer to configuration structure
Returns
Error or success status returned by API

Definition at line 889 of file i2c_pal.c.

status_t I2C_GetDefaultSlaveConfig ( i2c_slave_t config)

Gets the default configuration structure for slave.

The default configuration structure is:

Parameters
[out]configPointer to configuration structure
Returns
Error or success status returned by API

Definition at line 916 of file i2c_pal.c.

status_t I2C_MasterAbortTransfer ( const i2c_instance_t *const  instance)

Abort a non-blocking I2C Master transmission or reception.

Parameters
instanceI2C peripheral instance number
Returns
Error or success status returned by API

Definition at line 1388 of file i2c_pal.c.

status_t I2C_MasterDeinit ( const i2c_instance_t *const  instance)

De-initializes the I2C master module.

This function de-initialized the I2C master module.

Parameters
[in]instanceThe name of the instance
Returns
Error or success status returned by API

Definition at line 642 of file i2c_pal.c.

status_t I2C_MasterGetBaudRate ( const i2c_instance_t *const  instance,
uint32_t *  baudRate 
)

Get the master baud rate for the I2C communication.

This function returns the master baud rate of the I2C master module.

Parameters
instanceI2C peripheral instance number
Returns
the baud rate in Hz

Definition at line 834 of file i2c_pal.c.

status_t I2C_MasterGetTransferStatus ( const i2c_instance_t *const  instance,
uint32_t *  bytesRemaining 
)

Return the current status of the I2C master transfer.

This function can be called during a non-blocking transmission to check the status of the transfer.

Parameters
instanceI2C peripheral instance number
bytesRemainingthe number of remaining bytes in the active I2C transfer
Returns
Error or success status returned by API

Definition at line 1283 of file i2c_pal.c.

status_t I2C_MasterInit ( const i2c_instance_t *const  instance,
const i2c_master_t config 
)

Initializes the I2C module in master mode.

This function initializes and enables the requested I2C module in master mode, configuring the bus parameters.

Parameters
[in]instanceThe name of the instance
[in]configThe configuration structure
Returns
Error or success status returned by API

Definition at line 213 of file i2c_pal.c.

status_t I2C_MasterReceiveData ( const i2c_instance_t *const  instance,
uint8_t *  rxBuff,
uint32_t  rxSize,
bool  sendStop 
)

Perform a non-blocking receive transaction on the I2C bus.

This function starts the reception of a block of data from the currently configured slave address and returns immediately. The rest of the reception is handled by the interrupt service routine.

Parameters
instanceThe name of the instance
rxBuffpointer to the buffer where to store received data
rxSizelength in bytes of the data to be transferred
sendStopspecifies whether or not to generate stop condition after the reception
Returns
Error or success status returned by API

Definition at line 540 of file i2c_pal.c.

status_t I2C_MasterReceiveDataBlocking ( const i2c_instance_t *const  instance,
uint8_t *  rxBuff,
uint32_t  rxSize,
bool  sendStop,
uint32_t  timeout 
)

Perform a blocking receive transaction on the I2C bus.

This function receives a block of data from the currently configured slave address, and only returns when the transmission is complete.

Parameters
instanceThe name of the instance
rxBuffpointer to the buffer where to store received data
rxSizelength in bytes of the data to be transferred
sendStopspecifies whether or not to generate stop condition after the reception
timeouttimeout for the transfer in milliseconds
Returns
Error or success status returned by API

Definition at line 592 of file i2c_pal.c.

status_t I2C_MasterSendData ( const i2c_instance_t *const  instance,
const uint8_t *  txBuff,
uint32_t  txSize,
bool  sendStop 
)

Perform a non-blocking send transaction on the I2C bus.

This function starts the transmission of a block of data to the currently configured slave address and returns immediately. The rest of the transmission is handled by the interrupt service routine.

Parameters
instanceThe name of the instance
txBuffpointer to the data to be transferred
txSizelength in bytes of the data to be transferred
sendStopspecifies whether or not to generate stop condition after the transmission
Returns
Error or success status returned by API

Definition at line 429 of file i2c_pal.c.

status_t I2C_MasterSendDataBlocking ( const i2c_instance_t *const  instance,
const uint8_t *  txBuff,
uint32_t  txSize,
bool  sendStop,
uint32_t  timeout 
)

Perform a blocking send transaction on the I2C bus.

This function sends a block of data to the currently configured slave address, and only returns when the transmission is complete.

Parameters
instanceThe name of the instance
txBuffpointer to the data to be transferred
txSizelength in bytes of the data to be transferred
sendStopspecifies whether or not to generate stop condition after the transmission
timeouttimeout for the transfer in milliseconds
Returns
Error or success status returned by API

Definition at line 486 of file i2c_pal.c.

status_t I2C_MasterSetBaudRate ( const i2c_instance_t *const  instance,
const i2c_master_t config,
uint32_t  baudRate 
)

Set the master baud rate for the I2C communication.

This function sets the master baud rate of the I2C master module.

Parameters
instanceI2C peripheral instance number
baudRatethe desired baud rate in Hz

Definition at line 755 of file i2c_pal.c.

status_t I2C_MasterSetSlaveAddress ( const i2c_instance_t *const  instance,
const uint16_t  address,
const bool  is10bitAddr 
)

Set the slave address for the I2C communication.

This function sets the slave address which will be used for any future transfer initiated by the I2C master.

Parameters
instanceI2C peripheral instance number
addressslave 7-bit or 10-bit address

Definition at line 702 of file i2c_pal.c.

status_t I2C_SlaveAbortTransfer ( const i2c_instance_t *const  instance)

Abort a non-blocking I2C slave transmission or reception.

Parameters
instanceI2C peripheral instance number
Returns
Error or success status returned by API

Definition at line 1441 of file i2c_pal.c.

status_t I2C_SlaveDeinit ( const i2c_instance_t *const  instance)

De-initializes the i2c slave module.

This function de-initialized the i2c slave module.

Parameters
[in]instanceThe name of the instance
Returns
Error or success status returned by API

Definition at line 1234 of file i2c_pal.c.

status_t I2C_SlaveGetTransferStatus ( const i2c_instance_t *const  instance,
uint32_t *  bytesRemaining 
)

Return the current status of the I2C slave transfer.

This function can be called during a non-blocking transmission to check the status of the transfer.

Parameters
instanceI2C peripheral instance number
bytesRemainingthe number of remaining bytes in the active I2C transfer
Returns
Error or success status returned by API

Definition at line 1340 of file i2c_pal.c.

status_t I2C_SlaveInit ( const i2c_instance_t *const  instance,
const i2c_slave_t config 
)

Initializes the I2C module in slave mode.

This function initializes and enables the requested I2C module in slave mode, configuring the bus parameters.

Parameters
[in]instanceThe name of the instance
[in]configThe configuration structure
Returns
Error or success status returned by API

Definition at line 358 of file i2c_pal.c.

status_t I2C_SlaveReceiveData ( const i2c_instance_t *const  instance,
uint8_t *  rxBuff,
uint32_t  rxSize 
)

Perform a non-blocking receive transaction on the I2C bus.

Performs a non-blocking receive transaction on the I2C bus when the slave is not in listening mode (initialized with slaveListening = false). It starts the reception and returns immediately. The rest of the reception is handled by the interrupt service routine.

Parameters
instanceThe name of the instance
rxBuffpointer to the buffer where to store received data
rxSizelength in bytes of the data to be transferred
Returns
Error or success status returned by API

Definition at line 1034 of file i2c_pal.c.

status_t I2C_SlaveReceiveDataBlocking ( const i2c_instance_t *const  instance,
uint8_t *  rxBuff,
uint32_t  rxSize,
uint32_t  timeout 
)

Perform a blocking receive transaction on the I2C bus.

Performs a blocking receive transaction on the I2C bus when the slave is not in listening mode (initialized with slaveListening = false). It sets up the reception and then waits for the transfer to complete before returning.

Parameters
instanceThe name of the instance
rxBuffpointer to the buffer where to store received data
rxSizelength in bytes of the data to be transferred
timeouttimeout for the transfer in milliseconds
Returns
Error or success status returned by API

Definition at line 1084 of file i2c_pal.c.

status_t I2C_SlaveSendData ( const i2c_instance_t *const  instance,
const uint8_t *  txBuff,
uint32_t  txSize 
)

Perform a non-blocking send transaction on the I2C bus.

Performs a non-blocking send transaction on the I2C bus when the slave is not in listening mode (initialized with slaveListening = false). It starts the transmission and returns immediately. The rest of the transmission is handled by the interrupt service routine.

Parameters
instanceThe name of the instance
txBuffpointer to the data to be transferred
txSizelength in bytes of the data to be transferred
Returns
Error or success status returned by API

Definition at line 934 of file i2c_pal.c.

status_t I2C_SlaveSendDataBlocking ( const i2c_instance_t *const  instance,
const uint8_t *  txBuff,
uint32_t  txSize,
uint32_t  timeout 
)

Perform a blocking send transaction on the I2C bus.

Performs a blocking send transaction on the I2C bus when the slave is not in listening mode (initialized with slaveListening = false). It sets up the transmission and then waits for the transfer to complete before returning.

Parameters
instanceThe name of the instance
txBuffpointer to the data to be transferred
txSizelength in bytes of the data to be transferred
timeouttimeout for the transfer in milliseconds
Returns
Error or success status returned by API

Definition at line 983 of file i2c_pal.c.

status_t I2C_SlaveSetRxBuffer ( const i2c_instance_t *const  instance,
uint8_t *  rxBuff,
uint32_t  rxSize 
)

Provide a buffer for receiving data.

This function provides a buffer in which the I2C slave-mode driver can store received data. It can be called for example from the user callback provided at initialization time, when the driver reports events I2C_SLAVE_EVENT_RX_REQ or I2C_SLAVE_EVENT_RX_FULL.

Parameters
instanceI2C peripheral instance number
rxBuffpointer to the data to be transferred
rxSizelength in bytes of the data to be transferred
Returns
Error or success status returned by API

Definition at line 1136 of file i2c_pal.c.

status_t I2C_SlaveSetTxBuffer ( const i2c_instance_t *const  instance,
const uint8_t *  txBuff,
uint32_t  txSize 
)

Provide a buffer for transmitting data.

This function provides a buffer from which the I2C slave-mode driver can transmit data. It can be called for example from the user callback provided at initialization time, when the driver reports events I2C_SLAVE_EVENT_TX_REQ or I2C_SLAVE_EVENT_TX_EMPTY.

Parameters
instanceI2C peripheral instance number
txBuffpointer to the data to be transferred
txSizelength in bytes of the data to be transferred
Returns
Error or success status returned by API

Definition at line 1184 of file i2c_pal.c.