Overview

This section describes the programming interface of the I2C master mode Peripheral driver. The I2C master Peripheral driver provides functions for a master device to send and receive data.

I2C Initialization

To initialize the I2C driver, define an i2c_master_state_t type variable and pass it in the i2c_init. The variable does not need to have a specific value because the I2C driver only needs the memory associated with the variable. Because all I2C master API functions need the run-time structure, it should be maintained as long as the driver is used.
Because I2C drivers use the OSA_Delay form OSA layer, OSA_Init must be called before calling I2C transaction API functions. Otherwise, the API functions do not work.

I2C Data Transactions

I2C master driver provides these APIs for data transactions:

I2C_DRV_MasterSendDataBlocking \n

I2C_DRV_MasterReceiveDataBlocking \n

Both of these functions perform a blocking transaction, which means that the function does not return until all data is sent/received OR a time out occurs.
Before calling the API functions, the application should define the slave device with "i2c_device_t" type. Note that, if the slave is a 10-bit address, the first 6 bits must be 011110 in binary.

typedef struct I2CDevice 
{
    uint16_t address; // Slave's 7-bit or 10-bit address. If 10-bit address, the first 6 bits must be 011110 in binary.//
    uint32_t baudRate_kbps; // The baud rate in kbps to use with this slave device.//
} i2c_device_t;

If the buadRate_kbps inside the i2c_device_t object is changed, it is automatically applied to the next send/receive transaction.

Data Structures
struct	i2c_device_t
	Information necessary to communicate with an I2C slave device. More...

struct	i2c_master_state_t
	Internal driver state information. More...

Variables
I2C_Type *const	g_i2cBase [I2C_INSTANCE_COUNT]
	Table of base addresses for I2C instances. More...

I2C Master
i2c_status_t	I2C_DRV_MasterInit (uint32_t instance, i2c_master_state_t *master)
	Initializes the I2C master mode driver. More...

i2c_status_t	I2C_DRV_MasterDeinit (uint32_t instance)
	Shuts down the driver. More...

void	I2C_DRV_MasterSetBaudRate (uint32_t instance, const i2c_device_t *device)
	Configures the I2C bus to access a device. More...

i2c_status_t	I2C_DRV_MasterSendDataBlocking (uint32_t instance, const i2c_device_t device, const uint8_t cmdBuff, uint32_t cmdSize, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout_ms)
	Performs a blocking send transaction on the I2C bus. More...

i2c_status_t	I2C_DRV_MasterSendData (uint32_t instance, const i2c_device_t device, const uint8_t cmdBuff, uint32_t cmdSize, const uint8_t *txBuff, uint32_t txSize)
	Performs a non-blocking send transaction on the I2C bus. More...

i2c_status_t	I2C_DRV_MasterGetSendStatus (uint32_t instance, uint32_t *bytesRemaining)
	Gets the current status of the I2C master transmit. More...

i2c_status_t	I2C_DRV_MasterAbortSendData (uint32_t instance)
	Terminates a non-blocking I2C Master transmission early. More...

i2c_status_t	I2C_DRV_MasterReceiveDataBlocking (uint32_t instance, const i2c_device_t device, const uint8_t cmdBuff, uint32_t cmdSize, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout_ms)
	Performs a blocking receive transaction on the I2C bus. More...

i2c_status_t	I2C_DRV_MasterReceiveData (uint32_t instance, const i2c_device_t device, const uint8_t cmdBuff, uint32_t cmdSize, uint8_t *rxBuff, uint32_t rxSize)
	Performs a non-blocking receive transaction on the I2C bus. More...

i2c_status_t	I2C_DRV_MasterGetReceiveStatus (uint32_t instance, uint32_t *bytesRemaining)
	Gets the current status of the I2C master receive. More...

static i2c_status_t	I2C_DRV_MasterReceiveDataPolling (uint32_t instance, uint16_t slaveAddr, const uint8_t cmdBuff, uint32_t cmdSize, uint8_t rxBuff, uint32_t rxSize)
	Performs a polling receive transaction on the I2C bus. More...

static i2c_status_t	I2C_DRV_MasterSendDataPolling (uint32_t instance, uint16_t slaveAddr, const uint8_t cmdBuff, uint32_t cmdSize, const uint8_t txBuff, uint32_t txSize)
	Performs a polling send transaction on the I2C bus. More...

void	I2C_DRV_MasterIRQHandler (uint32_t instance)
	The interrupt handler for I2C master mode. More...

Data Structure Documentation

struct i2c_device_t

Data Fields
uint16_t	address
	Slave's 7-bit or 10-bit address. More...

uint32_t	baudRate_kbps
	The baud rate in kbps to use by current slave device.

Field Documentation

uint16_t i2c_device_t::address

If 10-bit address, the first 6 bits must be 011110 in binary.

struct i2c_master_state_t

Note: The contents of this structure are internal to the driver and should not be modified by users. Also, contents of the structure are subject to change in future releases.

Function Documentation

i2c_status_t I2C_DRV_MasterInit	(	uint32_t	instance,
		i2c_master_state_t *	master
	)

Parameters

instance	The I2C peripheral instance number.
master	The pointer to the I2C master driver state structure.

Returns: Error or success status returned by API.

i2c_status_t I2C_DRV_MasterDeinit ( uint32_t instance )

Parameters

instance The I2C peripheral instance number.

Returns: Error or success status returned by API.

void I2C_DRV_MasterSetBaudRate	(	uint32_t	instance,
		const i2c_device_t *	device
	)

Parameters

instance	The I2C peripheral instance number.
device	The pointer to the I2C device information structure.

i2c_status_t I2C_DRV_MasterSendDataBlocking	(	uint32_t	instance,
		const i2c_device_t *	device,
		const uint8_t *	cmdBuff,
		uint32_t	cmdSize,
		const uint8_t *	txBuff,
		uint32_t	txSize,
		uint32_t	timeout_ms
	)

Both cmdBuff and txBuff are byte aligned, user needs to prepare these buffers according to related protocol if slave devices data are not byte-aligned.

Parameters

instance	The I2C peripheral instance number.
device	The pointer to the I2C device information structure.
cmdBuff	The pointer to the commands to be transferred, could be NULL.
cmdSize	The length in bytes of the commands to be transferred, could be 0.
txBuff	The pointer to the data to be transferred, cannot be NULL.
txSize	The length in bytes of the data to be transferred, cannot be 0.
timeout_ms	A timeout for the transfer in microseconds.

Returns: Error or success status returned by API.

i2c_status_t I2C_DRV_MasterSendData	(	uint32_t	instance,
		const i2c_device_t *	device,
		const uint8_t *	cmdBuff,
		uint32_t	cmdSize,
		const uint8_t *	txBuff,
		uint32_t	txSize
	)

This function returns immediately when set buffer pointer and length to transfer buffer and transfer Size. The user must check the status of I2C to know the whether transmission is finished or not. Both cmdBuff and txBuff are byte aligned, user needs to prepare these buffers according to related protocol if slave devices data are not byte-aligned.

Parameters

instance	The I2C peripheral instance number.
device	The pointer to the I2C device information structure.
cmdBuff	The pointer to the commands to be transferred,could be NULL.
cmdSize	The length in bytes of the commands to be transferred, could be 0.
txBuff	The pointer to the data to be transferred, cannot be NULL.
txSize	The length in bytes of the data to be transferred, cannot be 0.

Returns: Error or success status returned by API.

i2c_status_t I2C_DRV_MasterGetSendStatus	(	uint32_t	instance,
		uint32_t *	bytesRemaining
	)

This function gets the current I2C status of the non-blocking transmit.

Parameters

instance	Instance number of the I2C module.
bytesRemaining	The number of remaining bytes in the active I2C transmits.

Returns: Current status of I2C transmission: in progress (busy) or complete (success).

i2c_status_t I2C_DRV_MasterAbortSendData ( uint32_t instance )

Parameters

instance Instance number of the I2C module.

Returns: Whether the aborting is success or not.

i2c_status_t I2C_DRV_MasterReceiveDataBlocking	(	uint32_t	instance,
		const i2c_device_t *	device,
		const uint8_t *	cmdBuff,
		uint32_t	cmdSize,
		uint8_t *	rxBuff,
		uint32_t	rxSize,
		uint32_t	timeout_ms
	)

Both cmdBuff and rxBuff are byte aligned, user needs to prepare these buffers according to related protocol if slave devices data are not byte-aligned.

Parameters

instance	The I2C peripheral instance number.
device	The pointer to the I2C device information structure.
cmdBuff	The pointer to the commands to be transferred, could be NULL.
cmdSize	The length in bytes of the commands to be transferred, could be 0.
rxBuff	The pointer to the data to be transferred, cannot be NULL.
rxSize	The length in bytes of the data to be transferred, cannot be 0.
timeout_ms	A timeout for the transfer in microseconds.

Returns: Error or success status returned by API.

i2c_status_t I2C_DRV_MasterReceiveData	(	uint32_t	instance,
		const i2c_device_t *	device,
		const uint8_t *	cmdBuff,
		uint32_t	cmdSize,
		uint8_t *	rxBuff,
		uint32_t	rxSize
	)

This function returns immediately after set buffer pointer and length to the receive buffer and the receive size. The user must check the status of I2C to know the whether the receiving is finished or not. Both cmdBuff and rxBuff are byte aligned, user needs to prepare these buffers according to related protocol if slave devices data are not byte-aligned.

Parameters

instance	The I2C peripheral instance number.
device	The pointer to the I2C device information structure.
cmdBuff	The pointer to the commands to be transferred, could be NULL.
cmdSize	The length in bytes of the commands to be transferred, could be 0.
rxBuff	The pointer to the data to be transferred, cannot be NULL.
rxSize	The length in bytes of the data to be transferred, cannot be 0.

Returns: Error or success status returned by API.

i2c_status_t I2C_DRV_MasterGetReceiveStatus	(	uint32_t	instance,
		uint32_t *	bytesRemaining
	)

This function is designed to get the current I2C status of a non-blocking receive.

Parameters

instance	Instance number of the I2C module.
bytesRemaining	The number of remaining bytes in the active I2C transmits.

Returns: Current status of I2C receive: in progress (busy) or complete (success).

static i2c_status_t I2C_DRV_MasterReceiveDataPolling	(	uint32_t	instance,
		uint16_t	slaveAddr,
		const uint8_t *	cmdBuff,
		uint32_t	cmdSize,
		uint8_t *	rxBuff,
		uint32_t	rxSize
	)

inlinestatic

Both cmdBuff and rxBuff are byte aligned. The user needs to prepare these buffers according to the related protocol if the slave device data is not byte-aligned.

Parameters

instance	Instance number of the I2C module.
slaveAddr	The slave address to communicate.
cmdBuff	The pointer to the commands to be transferred, could be NULL.
cmdSize	The length in bytes of the commands to be transferred, could be 0.
rxBuff	The pointer to the data to be transferred, cannot be NULL.
rxSize	The length in bytes of the data to be transferred, cannot be 0.

Returns: Error or success status returned by API.

static i2c_status_t I2C_DRV_MasterSendDataPolling	(	uint32_t	instance,
		uint16_t	slaveAddr,
		const uint8_t *	cmdBuff,
		uint32_t	cmdSize,
		const uint8_t *	txBuff,
		uint32_t	txSize
	)

inlinestatic

Both cmdBuff and txBuff are byte aligned. The user needs to prepare these buffers according to the related protocol if the slave device data is not byte-aligned.

Parameters

instance	Instance number of the I2C module.
slaveAddr	The slave address to communicate.
cmdBuff	The pointer to the commands to be transferred, could be NULL.
cmdSize	The length in bytes of the commands to be transferred, could be 0.
txBuff	The pointer to the data to be transferred, cannot be NULL.
txSize	The length in bytes of the data to be transferred, cannot be 0.

Returns: Error or success status returned by API.

void I2C_DRV_MasterIRQHandler ( uint32_t instance )

Parameters

instance Instance number of the I2C module.

Variable Documentation

I2C_Type* const g_i2cBase[I2C_INSTANCE_COUNT]

Overview

I2C Initialization

I2C Data Transactions

Data Structures

Variables

I2C Master

Data Structure Documentation

Data Fields

Field Documentation

Function Documentation

Variable Documentation