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 I2C_OVER_LPI2C
#define I2C_OVER_FLEXIO
#define I2C_OVER_I2C
#define I2C_OVER_SWI2C
#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
The following table contains the matching between platforms and available IPs
IP/MCU | S32K142 | S32K144 | S32K148 | MPC5748G | MPC5746C | MPC5744P |
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:
- Slave always listening: the slave interrupt is enabled at initialization time and the slave always listens to the line for a master addressing it. Any events are reported to the application through the callback function provided at initialization time.
- On-demand operation: the slave is commanded to transmit or receive data through the call of I2C_SlaveSendData() and I2C_SlaveReceiveData() (or their blocking counterparts). The actual moment of the transfer depends on the I2C master.
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
- The I2C transfers could be done using interrupts and DMA mode.
- FlexIO driver only supports master mode.
- The driver enables the interrupts for the corresponding module, but any interrupt priority setting must be done by the application.
- SWI2C driver supports only master mode.
- The baud rate for SWI2C can reach a maximum value of 20Khz (without compiler optimiztations).
- For send/receive blocking functions the timeout parameter is unused for SWI2C driver. The driver has a timeout independent of this parameter.
Example code
{
.is10bitAddr = false,
.baudRate = 100000,
.dmaChannel1 = 255,
.dmaChannel2 = 255,
.callback = NULL,
.callbackParam = NULL,
.extension = NULL
};
{
.is10bitAddr = false,
.slaveListening = true,
.dmaChannel = 255,
.callback = i2c2_SlaveCallback0,
.callbackParam = NULL
};
{
}
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};
|
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...
|
|
|
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...
|
|
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.
Gets the default configuration structure for master.
The default configuration structure is:
- Parameters
-
[out] | config | Pointer to configuration structure |
- Returns
- Error or success status returned by API
Definition at line 889 of file i2c_pal.c.
Gets the default configuration structure for slave.
The default configuration structure is:
- Parameters
-
[out] | config | Pointer to configuration structure |
- Returns
- Error or success status returned by API
Definition at line 916 of file i2c_pal.c.
Abort a non-blocking I2C Master transmission or reception.
- Parameters
-
instance | I2C peripheral instance number |
- Returns
- Error or success status returned by API
Definition at line 1388 of file i2c_pal.c.
De-initializes the I2C master module.
This function de-initialized the I2C master module.
- Parameters
-
[in] | instance | The name of the instance |
- Returns
- Error or success status returned by API
Definition at line 642 of file i2c_pal.c.
Get the master baud rate for the I2C communication.
This function returns the master baud rate of the I2C master module.
- Parameters
-
instance | I2C peripheral instance number |
- Returns
- the baud rate in Hz
Definition at line 834 of file i2c_pal.c.
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
-
instance | I2C peripheral instance number |
bytesRemaining | the 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.
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] | instance | The name of the instance |
[in] | config | The 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
-
instance | The name of the instance |
rxBuff | pointer to the buffer where to store received data |
rxSize | length in bytes of the data to be transferred |
sendStop | specifies 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
-
instance | The name of the instance |
rxBuff | pointer to the buffer where to store received data |
rxSize | length in bytes of the data to be transferred |
sendStop | specifies whether or not to generate stop condition after the reception |
timeout | timeout 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
-
instance | The name of the instance |
txBuff | pointer to the data to be transferred |
txSize | length in bytes of the data to be transferred |
sendStop | specifies 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
-
instance | The name of the instance |
txBuff | pointer to the data to be transferred |
txSize | length in bytes of the data to be transferred |
sendStop | specifies whether or not to generate stop condition after the transmission |
timeout | timeout for the transfer in milliseconds |
- Returns
- Error or success status returned by API
Definition at line 486 of file i2c_pal.c.
Set the master baud rate for the I2C communication.
This function sets the master baud rate of the I2C master module.
- Parameters
-
instance | I2C peripheral instance number |
baudRate | the 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
-
instance | I2C peripheral instance number |
address | slave 7-bit or 10-bit address |
Definition at line 702 of file i2c_pal.c.
Abort a non-blocking I2C slave transmission or reception.
- Parameters
-
instance | I2C peripheral instance number |
- Returns
- Error or success status returned by API
Definition at line 1441 of file i2c_pal.c.
De-initializes the i2c slave module.
This function de-initialized the i2c slave module.
- Parameters
-
[in] | instance | The name of the instance |
- Returns
- Error or success status returned by API
Definition at line 1234 of file i2c_pal.c.
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
-
instance | I2C peripheral instance number |
bytesRemaining | the 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.
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] | instance | The name of the instance |
[in] | config | The configuration structure |
- Returns
- Error or success status returned by API
Definition at line 358 of file i2c_pal.c.
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
-
instance | The name of the instance |
rxBuff | pointer to the buffer where to store received data |
rxSize | length 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
-
instance | The name of the instance |
rxBuff | pointer to the buffer where to store received data |
rxSize | length in bytes of the data to be transferred |
timeout | timeout for the transfer in milliseconds |
- Returns
- Error or success status returned by API
Definition at line 1084 of file i2c_pal.c.
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
-
instance | The name of the instance |
txBuff | pointer to the data to be transferred |
txSize | length 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
-
instance | The name of the instance |
txBuff | pointer to the data to be transferred |
txSize | length in bytes of the data to be transferred |
timeout | timeout for the transfer in milliseconds |
- Returns
- Error or success status returned by API
Definition at line 983 of file i2c_pal.c.
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
-
instance | I2C peripheral instance number |
rxBuff | pointer to the data to be transferred |
rxSize | length 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
-
instance | I2C peripheral instance number |
txBuff | pointer to the data to be transferred |
txSize | length 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.