S32 SDK
FlexIO I2C Driver

Detailed Description

I2C communication over FlexIO module (FLEXIO_I2C)

The FLEXIO_I2C Driver allows communication on an I2C bus using the FlexIO module in the S32144K processor.

Features

Functionality

Before using any Flexio driver the device must first be initialized using function FLEXIO_DRV_InitDevice. Then the FLEXIO_I2C Driver must be initialized using functions FLEXIO_I2C_DRV_MasterInit(). It is possible to use more driver instances on the same FlexIO device, as long as sufficient resources are available. Different driver instances on the same FlexIO device can function independently of each other. When it is no longer needed, the driver can be de-initialized, using FLEXIO_I2C_DRV_MasterDeinit(). This will release the hardware resources, allowing other driver instances to be initialized.

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 FLEXIO_I2C_DRV_MasterSetBaudRate() or FLEXIO_I2C_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 FlexIO clock. The application should call FLEXIO_I2C_DRV_MasterGetBaudRate() after FLEXIO_I2C_DRV_MasterSetBaudRate() to check what baud rate was actually set.

To send or receive data to/from the currently configured slave address, use functions FLEXIO_I2C_DRV_MasterSendData() or FLEXIO_I2C_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. The last transfer from a chain should always have sendStop set to true. This driver does not support continuous send/receive using a user callback function. The callback function is only used to signal the end of a transfer.

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 will be notified through the user callback when the transfer completes, or it can check the status of the current transfer by calling FLEXIO_I2C_DRV_MasterGetStatus(). If the transfer is still ongoing this function will return STATUS_BUSY. If the transfer is completed, the function will return either STATUS_SUCCESS or an error code, depending on the outcome of the last transfer.

The driver supports interrupt, DMA and polling mode. In polling mode the function FLEXIO_I2C_DRV_MasterGetStatus() ensures the progress of the transfer by checking and handling transmit and receive events reported by the FlexIO module. The application should ensure that this function is called often enough (at least once per transferred byte) to avoid Tx underflows or Rx overflows. In DMA mode the DMA channels that will be used by the driver are received through the configuration structure. The channels must be initialized by the application before the flexio_i2c driver is initialized. The flexio_i2c driver will only set the DMA request source.

Important Notes

Data Structures

struct  flexio_i2c_master_user_config_t
 Master configuration structure. More...
 
struct  flexio_i2c_master_state_t
 Master internal context structure. More...
 

Macros

#define FLEXIO_I2C_MAX_SIZE   (((uint32_t)((0xFFU - 1U) / 18U)) - 1U)
 Maximum size of a transfer. The restriction is that the total number of SCL edges must not exceed 8 bits, such that it can be programmed in the upper part of the timer compare register. There are 2 SCL edges per bit, 9 bits per byte (including ACK). The extra 1 is for the STOP condition. More...
 

FLEXIO_I2C Driver

status_t FLEXIO_I2C_DRV_MasterInit (uint32_t instance, const flexio_i2c_master_user_config_t *userConfigPtr, flexio_i2c_master_state_t *master)
 Initialize the FLEXIO_I2C master mode driver. More...
 
status_t FLEXIO_I2C_DRV_MasterDeinit (flexio_i2c_master_state_t *master)
 De-initialize the FLEXIO_I2C master mode driver. More...
 
status_t FLEXIO_I2C_DRV_MasterSetBaudRate (flexio_i2c_master_state_t *master, uint32_t baudRate)
 Set the baud rate for any subsequent I2C communication. More...
 
status_t FLEXIO_I2C_DRV_MasterGetBaudRate (flexio_i2c_master_state_t *master, uint32_t *baudRate)
 Get the currently configured baud rate. More...
 
status_t FLEXIO_I2C_DRV_MasterSetSlaveAddr (flexio_i2c_master_state_t *master, const uint16_t address)
 Set the slave address for any subsequent I2C communication. More...
 
status_t FLEXIO_I2C_DRV_MasterSendData (flexio_i2c_master_state_t *master, const uint8_t *txBuff, uint32_t txSize, bool sendStop)
 Perform a non-blocking send transaction on the I2C bus. More...
 
status_t FLEXIO_I2C_DRV_MasterSendDataBlocking (flexio_i2c_master_state_t *master, const uint8_t *txBuff, uint32_t txSize, bool sendStop, uint32_t timeout)
 Perform a blocking send transaction on the I2C bus. More...
 
status_t FLEXIO_I2C_DRV_MasterReceiveData (flexio_i2c_master_state_t *master, uint8_t *rxBuff, uint32_t rxSize, bool sendStop)
 Perform a non-blocking receive transaction on the I2C bus. More...
 
status_t FLEXIO_I2C_DRV_MasterReceiveDataBlocking (flexio_i2c_master_state_t *master, uint8_t *rxBuff, uint32_t rxSize, bool sendStop, uint32_t timeout)
 Perform a blocking receive transaction on the I2C bus. More...
 
status_t FLEXIO_I2C_DRV_MasterTransferAbort (flexio_i2c_master_state_t *master)
 Aborts a non-blocking I2C master transaction. More...
 
status_t FLEXIO_I2C_DRV_MasterGetStatus (flexio_i2c_master_state_t *master, uint32_t *bytesRemaining)
 Get the status of the current non-blocking I2C master transaction. More...
 

Macro Definition Documentation

#define FLEXIO_I2C_MAX_SIZE   (((uint32_t)((0xFFU - 1U) / 18U)) - 1U)

Maximum size of a transfer. The restriction is that the total number of SCL edges must not exceed 8 bits, such that it can be programmed in the upper part of the timer compare register. There are 2 SCL edges per bit, 9 bits per byte (including ACK). The extra 1 is for the STOP condition.

Definition at line 67 of file flexio_i2c_driver.h.

Function Documentation

status_t FLEXIO_I2C_DRV_MasterDeinit ( flexio_i2c_master_state_t master)

De-initialize the FLEXIO_I2C master mode driver.

This function de-initializes the FLEXIO_I2C 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
masterPointer to the FLEXIO_I2C master driver context structure.
Returns
Error or success status returned by API

Definition at line 1205 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterGetBaudRate ( flexio_i2c_master_state_t master,
uint32_t *  baudRate 
)

Get the currently configured baud rate.

This function returns the currently configured I2C baud rate.

Parameters
masterPointer to the FLEXIO_I2C master driver context structure.
baudRatethe current baud rate in hertz
Returns
Error or success status returned by API

Definition at line 1269 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterGetStatus ( flexio_i2c_master_state_t master,
uint32_t *  bytesRemaining 
)

Get the status of the current non-blocking I2C master transaction.

This function returns the current status of a non-blocking I2C master transaction. A return code of STATUS_BUSY means the transfer is still in progress. Otherwise the function returns a status reflecting the outcome of the last transfer. When the driver is initialized in polling mode this function also advances the transfer by checking and handling the transmit and receive events, so it must be called frequently to avoid overflows or underflows.

Parameters
masterPointer to the FLEXIO_I2C master driver context structure.
bytesRemainingThe remaining number of bytes to be transferred
Returns
Error or success status returned by API

Definition at line 1468 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterInit ( uint32_t  instance,
const flexio_i2c_master_user_config_t userConfigPtr,
flexio_i2c_master_state_t master 
)

Initialize the FLEXIO_I2C master mode driver.

This function initializes the FLEXIO_I2C driver in master mode.

Parameters
instanceFLEXIO peripheral instance number
userConfigPtrPointer to the FLEXIO_I2C 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 FLEXIO_I2C 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 FLEXIO_I2C_DRV_MasterDeinit().
Returns
Error or success status returned by API

Definition at line 1114 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterReceiveData ( flexio_i2c_master_state_t master,
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 transmission is handled by the interrupt service routine (if the driver is initialized in interrupt mode) or by the FLEXIO_I2C_DRV_MasterGetStatus function (if the driver is initialized in polling mode). Use FLEXIO_I2C_DRV_MasterGetStatus() to check the progress of the reception.

Parameters
masterPointer to the FLEXIO_I2C master driver context structure.
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 1384 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterReceiveDataBlocking ( flexio_i2c_master_state_t master,
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
masterPointer to the FLEXIO_I2C master driver context structure.
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 1404 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterSendData ( flexio_i2c_master_state_t master,
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 (if the driver is initialized in interrupt mode) or by the FLEXIO_I2C_DRV_MasterGetStatus function (if the driver is initialized in polling mode). Use FLEXIO_I2C_DRV_MasterGetStatus() to check the progress of the transmission.

Parameters
masterPointer to the FLEXIO_I2C master driver context structure.
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 1326 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterSendDataBlocking ( flexio_i2c_master_state_t master,
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
masterPointer to the FLEXIO_I2C master driver context structure.
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 1346 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterSetBaudRate ( flexio_i2c_master_state_t master,
uint32_t  baudRate 
)

Set the baud rate for any subsequent I2C communication.

This function sets the baud rate (SCL frequency) for the I2C master. 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 FlexIO clock. The application should call FLEXIO_I2C_DRV_MasterGetBaudRate() after FLEXIO_I2C_DRV_MasterSetBaudRate() to check what baud rate was actually set.

Parameters
masterPointer to the FLEXIO_I2C master driver context structure.
baudRatethe desired baud rate in hertz
Returns
Error or success status returned by API

Definition at line 1228 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterSetSlaveAddr ( flexio_i2c_master_state_t master,
const uint16_t  address 
)

Set the slave address for any subsequent I2C communication.

This function sets the slave address which will be used for any future transfer.

Parameters
masterPointer to the FLEXIO_I2C master driver context structure.
addressslave address, 7-bit
Returns
Error or success status returned by API

Definition at line 1307 of file flexio_i2c_driver.c.

status_t FLEXIO_I2C_DRV_MasterTransferAbort ( flexio_i2c_master_state_t master)

Aborts a non-blocking I2C master transaction.

This function aborts a non-blocking I2C transfer.

Parameters
masterPointer to the FLEXIO_I2C master driver context structure.
Returns
Error or success status returned by API

Definition at line 1442 of file flexio_i2c_driver.c.