Detailed Description

Low Power Inter-Integrated Circuit (LPI2C) Peripheral Driver.

Low Power Inter-Integrated Circuit Driver.

The LPI2C driver allows communication on an I2C bus using the LPI2C module in the S32144K processor.

Features

Functionality

In order to use the LPI2C driver it must be first initialized in either master of slave mode, using functions LPI2C_DRV_MasterInit() or LPI2C_DRV_SlaveInit(). Once initialized, it cannot be initialized again for the same LPI2C module instance until it is de-initialized, using LPI2C_DRV_MasterDeinit() or LPI2C_DRV_SlaveDeinit(). Different LPI2C module instances can function independently of each other.

Master Mode

Master Mode provides functions for transmitting or receiving data to/from any I2C slave. Slave address and baud rate are provided at initialization time through the master configuration structure, but they can be changed at runtime by using LPI2C_DRV_MasterSetBaudRate() or LPI2C_DRV_MasterSetSlaveAddr(). Note that due to module limitation not any baud rate can be achieved. The driver will set a baud rate as close as possible to the requested baud rate, but there may still be substantial differences, for example if requesting a high baud rate while using a low-frequency protocol clock for the LPI2C module. The application should call LPI2C_DRV_MasterGetBaudRate() after LPI2C_DRV_MasterSetBaudRate() to check what baud rate was actually set.

To send or receive data to/from the currently configured slave address, use functions LPI2C_DRV_MasterSendData() or LPI2C_DRV_MasterReceiveData() (or their blocking counterparts). Parameter sendStop can be used to chain multiple transfers with repeated START condition between them, for example when sending a command and then immediately receiving a response. The application should ensure that any send or receive transfer with sendStop set to false is followed by another transfer, otherwise the LPI2C master will hold the SCL line low indefinitely and block the I2C bus. The last transfer from a chain should always have sendStop set to true.

Blocking operations will return only when the transfer is completed, either successfully or with error. Non-blocking operations will initiate the transfer and return STATUS_SUCCESS, but the module is still busy with the transfer and another transfer can't be initiated until the current transfer is complete. The application can check the status of the current transfer by calling LPI2C_DRV_MasterGetTransferStatus(). If the transfer is completed, the functions will return either STATUS_SUCCESS or an error code, depending on the outcome of the last transfer.

The driver supports any operating mode supported by the module. The operating mode is set together with the baud rate, by LPI2C_DRV_MasterSetBaudRate(). For High-Speed mode a second baud rate is required, for high-speed communication. Note that due to module limitation (common prescaler setting for normal and fast baud rate) there is a limit on the maximum difference between the two baud rates. LPI2C_DRV_MasterGetBaudRate() can be used to check the baud rate setting for both modes.

Slave Mode

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:

Important Notes

Data Structures

struct  lpi2c_master_user_config_t
 Defines the example structure. More...
 
struct  lpi2c_slave_user_config_t
 Slave configuration structure. More...
 
struct  lpi2c_baud_rate_params_t
 Baud rate structure. More...
 
struct  lpi2c_master_state_t
 Master internal context structure. More...
 
struct  lpi2c_slave_state_t
 Slave internal context structure. More...
 

Enumerations

enum  lpi2c_mode_t { LPI2C_STANDARD_MODE = 0x0U, LPI2C_FAST_MODE = 0x1U }
 I2C operating modes Implements : lpi2c_mode_t_Class. More...
 
enum  lpi2c_transfer_type_t { LPI2C_USING_DMA = 0, LPI2C_USING_INTERRUPTS = 1 }
 Type of LPI2C transfer (based on interrupts or DMA). Implements : lpi2c_transfer_type_t_Class. More...
 

LPI2C Driver

status_t LPI2C_DRV_MasterInit (uint32_t instance, const lpi2c_master_user_config_t *userConfigPtr, lpi2c_master_state_t *master)
 Initialize the LPI2C master mode driver. More...
 
status_t LPI2C_DRV_MasterDeinit (uint32_t instance)
 De-initialize the LPI2C master mode driver. More...
 
void LPI2C_DRV_MasterGetBaudRate (uint32_t instance, lpi2c_baud_rate_params_t *baudRate)
 Get the currently configured baud rate. More...
 
void LPI2C_DRV_MasterSetBaudRate (uint32_t instance, const lpi2c_mode_t operatingMode, const lpi2c_baud_rate_params_t baudRate)
 Set the baud rate for any subsequent I2C communication. More...
 
void LPI2C_DRV_MasterSetSlaveAddr (uint32_t instance, const uint16_t address, const bool is10bitAddr)
 Set the slave address for any subsequent I2C communication. More...
 
status_t LPI2C_DRV_MasterSendData (uint32_t instance, const uint8_t *txBuff, uint32_t txSize, bool sendStop)
 Perform a non-blocking send transaction on the I2C bus. More...
 
status_t LPI2C_DRV_MasterSendDataBlocking (uint32_t 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 LPI2C_DRV_MasterAbortTransferData (uint32_t instance)
 Abort a non-blocking I2C Master transmission or reception. More...
 
status_t LPI2C_DRV_MasterReceiveData (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, bool sendStop)
 Perform a non-blocking receive transaction on the I2C bus. More...
 
status_t LPI2C_DRV_MasterReceiveDataBlocking (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, bool sendStop, uint32_t timeout)
 Perform a blocking receive transaction on the I2C bus. More...
 
status_t LPI2C_DRV_MasterGetTransferStatus (uint32_t instance, uint32_t *bytesRemaining)
 Return the current status of the I2C master transfer. More...
 
void LPI2C_DRV_MasterIRQHandler (uint32_t instance)
 Handle master operation when I2C interrupt occurs. More...
 
status_t LPI2C_DRV_SlaveInit (uint32_t instance, const lpi2c_slave_user_config_t *userConfigPtr, lpi2c_slave_state_t *slave)
 Initialize the I2C slave mode driver. More...
 
status_t LPI2C_DRV_SlaveDeinit (uint32_t instance)
 De-initialize the I2C slave mode driver. More...
 
status_t LPI2C_DRV_SlaveSetTxBuffer (uint32_t instance, const uint8_t *txBuff, uint32_t txSize)
 Provide a buffer for transmitting data. More...
 
status_t LPI2C_DRV_SlaveSetRxBuffer (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize)
 Provide a buffer for receiving data. More...
 
status_t LPI2C_DRV_SlaveSendData (uint32_t instance, const uint8_t *txBuff, uint32_t txSize)
 Perform a non-blocking send transaction on the I2C bus. More...
 
status_t LPI2C_DRV_SlaveSendDataBlocking (uint32_t instance, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout)
 Perform a blocking send transaction on the I2C bus. More...
 
status_t LPI2C_DRV_SlaveReceiveData (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize)
 Perform a non-blocking receive transaction on the I2C bus. More...
 
status_t LPI2C_DRV_SlaveReceiveDataBlocking (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout)
 Perform a blocking receive transaction on the I2C bus. More...
 
status_t LPI2C_DRV_SlaveGetTransferStatus (uint32_t instance, uint32_t *bytesRemaining)
 Return the current status of the I2C slave transfer. More...
 
status_t LPI2C_DRV_SlaveAbortTransferData (uint32_t instance)
 Abort a non-blocking I2C Master transmission or reception. More...
 
void LPI2C_DRV_SlaveIRQHandler (uint32_t instance)
 Handle slave operation when I2C interrupt occurs. More...
 
void LPI2C_DRV_ModuleIRQHandler (uint32_t instance)
 Handler for both slave and master operation when I2C interrupt occurs. More...
 

Enumeration Type Documentation

I2C operating modes Implements : lpi2c_mode_t_Class.

Enumerator
LPI2C_STANDARD_MODE 

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

LPI2C_FAST_MODE 

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

Definition at line 74 of file lpi2c_driver.h.

Type of LPI2C transfer (based on interrupts or DMA). Implements : lpi2c_transfer_type_t_Class.

Enumerator
LPI2C_USING_DMA 

The driver will use DMA to perform I2C transfer

LPI2C_USING_INTERRUPTS 

The driver will use interrupts to perform I2C transfer

Definition at line 92 of file lpi2c_driver.h.

Function Documentation

status_t LPI2C_DRV_MasterAbortTransferData ( uint32_t  instance)

Abort a non-blocking I2C Master transmission or reception.

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

Definition at line 1493 of file lpi2c_driver.c.

status_t LPI2C_DRV_MasterDeinit ( uint32_t  instance)

De-initialize the LPI2C master mode driver.

This function de-initializes the LPI2C driver in master mode. The driver can't be used again until reinitialized. The context structure is no longer needed by the driver and can be freed after calling this function.

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

Definition at line 1114 of file lpi2c_driver.c.

void LPI2C_DRV_MasterGetBaudRate ( uint32_t  instance,
lpi2c_baud_rate_params_t baudRate 
)

Get the currently configured baud rate.

This function returns the currently configured baud rate.

Parameters
instanceLPI2C peripheral instance number
baudRatestructure that contains the current baud rate in hertz and the baud rate in hertz for High-speed mode (unused in other modes, can be NULL)

Definition at line 1147 of file lpi2c_driver.c.

status_t LPI2C_DRV_MasterGetTransferStatus ( uint32_t  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
instanceLPI2C peripheral instance number
bytesRemainingthe number of remaining bytes in the active I2C transfer
Returns
Error or success status returned by API

Definition at line 1662 of file lpi2c_driver.c.

status_t LPI2C_DRV_MasterInit ( uint32_t  instance,
const lpi2c_master_user_config_t userConfigPtr,
lpi2c_master_state_t master 
)

Initialize the LPI2C master mode driver.

This function initializes the LPI2C driver in master mode.

Parameters
instanceLPI2C peripheral instance number
userConfigPtrPointer to the LPI2C master user configuration structure. The function reads configuration data from this structure and initializes the driver accordingly. The application may free this structure after the function returns.
masterPointer to the LPI2C master driver context structure. The driver uses this memory area for its internal logic. The application must make no assumptions about the content of this structure, and must not free this memory until the driver is de-initialized using LPI2C_DRV_MasterDeinit().
Returns
Error or success status returned by API

Definition at line 1032 of file lpi2c_driver.c.

void LPI2C_DRV_MasterIRQHandler ( uint32_t  instance)

Handle master operation when I2C interrupt occurs.

This is the interrupt service routine for the LPI2C master mode driver. It handles the rest of the transfer started by one of the send/receive functions.

Parameters
instanceLPI2C peripheral instance number

Definition at line 1704 of file lpi2c_driver.c.

status_t LPI2C_DRV_MasterReceiveData ( uint32_t  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. Use LPI2C_DRV_MasterGetReceiveStatus() to check the progress of the reception.

Parameters
instanceLPI2C peripheral instance number
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 1528 of file lpi2c_driver.c.

status_t LPI2C_DRV_MasterReceiveDataBlocking ( uint32_t  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
instanceLPI2C peripheral instance number
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 1621 of file lpi2c_driver.c.

status_t LPI2C_DRV_MasterSendData ( uint32_t  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. Use LPI2C_DRV_MasterGetSendStatus() to check the progress of the transmission.

Parameters
instanceLPI2C peripheral instance number
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 1378 of file lpi2c_driver.c.

status_t LPI2C_DRV_MasterSendDataBlocking ( uint32_t  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
instanceLPI2C peripheral instance number
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 1456 of file lpi2c_driver.c.

void LPI2C_DRV_MasterSetBaudRate ( uint32_t  instance,
const lpi2c_mode_t  operatingMode,
const lpi2c_baud_rate_params_t  baudRate 
)

Set the baud rate for any subsequent I2C communication.

This function sets the baud rate (SCL frequency) for the I2C master. It can also change the operating mode. If the operating mode is High-Speed, a second baud rate must be provided for high-speed communication. Note that due to module limitation not any baud rate can be achieved. The driver will set a baud rate as close as possible to the requested baud rate, but there may still be substantial differences, for example if requesting a high baud rate while using a low-frequency protocol clock for the LPI2C module. The application should call LPI2C_DRV_MasterGetBaudRate() after LPI2C_DRV_MasterSetBaudRate() to check what baud rate was actually set.

Parameters
instanceLPI2C peripheral instance number
operatingModeI2C operating mode
baudRatestructure that contains the baud rate in hertz to use by current slave device and also the baud rate in hertz for High-speed mode (unused in other modes)

Definition at line 1199 of file lpi2c_driver.c.

void LPI2C_DRV_MasterSetSlaveAddr ( uint32_t  instance,
const uint16_t  address,
const bool  is10bitAddr 
)

Set the slave address for any subsequent I2C communication.

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

Parameters
instanceLPI2C peripheral instance number
addressslave address, 7-bit or 10-bit
is10bitAddrspecifies if provided address is 10-bit

Definition at line 1357 of file lpi2c_driver.c.

void LPI2C_DRV_ModuleIRQHandler ( uint32_t  instance)

Handler for both slave and master operation when I2C interrupt occurs.

This is the interrupt service routine for the LPI2C slave and master mode driver. It handles any transfer initiated by an I2C master and notifies the application via the provided callback when relevant events occur.

Parameters
instanceLPI2C peripheral instance number
status_t LPI2C_DRV_SlaveAbortTransferData ( uint32_t  instance)

Abort a non-blocking I2C Master transmission or reception.

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

Definition at line 2300 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveDeinit ( uint32_t  instance)

De-initialize the I2C slave mode driver.

This function de-initializes the LPI2C driver in slave mode. The driver can't be used again until reinitialized. The context structure is no longer needed by the driver and can be freed after calling this function.

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

Definition at line 1941 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveGetTransferStatus ( uint32_t  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
instanceLPI2C peripheral instance number
bytesRemainingthe number of remaining bytes in the active I2C transfer
Returns
Error or success status returned by API

Definition at line 2261 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveInit ( uint32_t  instance,
const lpi2c_slave_user_config_t userConfigPtr,
lpi2c_slave_state_t slave 
)

Initialize the I2C slave mode driver.

Parameters
instanceLPI2C peripheral instance number
userConfigPtrPointer to the LPI2C slave user configuration structure. The function reads configuration data from this structure and initializes the driver accordingly. The application may free this structure after the function returns.
slavePointer to the LPI2C slave driver context structure. The driver uses this memory area for its internal logic. The application must make no assumptions about the content of this structure, and must not free this memory until the driver is de-initialized using LPI2C_DRV_SlaveDeinit().
Returns
Error or success status returned by API

Definition at line 1820 of file lpi2c_driver.c.

void LPI2C_DRV_SlaveIRQHandler ( uint32_t  instance)

Handle slave operation when I2C interrupt occurs.

This is the interrupt service routine for the LPI2C slave mode driver. It handles any transfer initiated by an I2C master and notifies the application via the provided callback when relevant events occur.

Parameters
instanceLPI2C peripheral instance number

Definition at line 2329 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveReceiveData ( uint32_t  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. Use LPI2C_DRV_SlaveGetReceiveStatus() to check the progress of the reception.

Parameters
instanceLPI2C peripheral instance number
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 2152 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveReceiveDataBlocking ( uint32_t  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
instanceLPI2C peripheral instance number
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 2222 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveSendData ( uint32_t  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. Use LPI2C_DRV_SlaveGetTransmitStatus() to check the progress of the transmission.

Parameters
instanceLPI2C 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 2034 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveSendDataBlocking ( uint32_t  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
instanceLPI2C peripheral instance number
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 2117 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveSetRxBuffer ( uint32_t  instance,
uint8_t *  rxBuff,
uint32_t  rxSize 
)

Provide a buffer for receiving data.

This function provides a buffer in which the LPI2C 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 LPI2C_SLAVE_EVENT_RX_REQ or LPI2C_SLAVE_EVENT_RX_FULL.

Parameters
instanceLPI2C 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 2007 of file lpi2c_driver.c.

status_t LPI2C_DRV_SlaveSetTxBuffer ( uint32_t  instance,
const uint8_t *  txBuff,
uint32_t  txSize 
)

Provide a buffer for transmitting data.

This function provides a buffer from which the LPI2C 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 LPI2C_SLAVE_EVENT_TX_REQ or LPI2C_SLAVE_EVENT_TX_EMPTY.

Parameters
instanceLPI2C 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 1980 of file lpi2c_driver.c.