Introduction

This file containing the I2C API.

The I2C header file should be included in an application as follows:

Operation

The I2C driver operates as a master or a slave on a single-master I2C bus, in either I2C_MODE_BLOCKING or I2C_MODE_CALLBACK. In blocking mode, the task's execution is blocked during the I2C transaction. When the transfer has completed, code execution will resume. In callback mode, the task's execution is not blocked, allowing for other transactions to be queued up or to process some other code. When the transfer has completed, the I2C driver will call a user-specified callback function (from a HWI context).

The APIs in this driver serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible to create all the SYS/BIOS specific primitives to allow for thread-safe operation.

Opening the driver

I2C_Handle      handle;
I2C_Params      params;
 
I2C_Params_init(&params);
params.transferMode  = I2C_MODE_BLOCKING;
I2C_init();
handle = I2C_open(someI2C_configIndexValue, &params);
if (!handle) {
    System_printf("I2C did not open");
}

Transferring data

A I2C transaction with a I2C peripheral is started by calling I2C_transfer(). The details of the I2C transaction is specified with a I2C_Transaction data structure. This structure allows for any of the three types of transactions: Write, Read, or Write/Read. Each transfer is performed atomically with the I2C master or slave peripheral.

I2C_Transaction i2cTransaction;
I2C_Transaction_init(&i2cTransaction);
 
i2cTransaction.writeBuf = someWriteBuffer;
i2cTransaction.writeCount = numOfBytesToWrite;
 
i2cTransaction.readBuf = someReadBuffer;
i2cTransaction.readCount = numOfBytesToRead;
 
i2cTransaction.slaveAddress = some7BitI2CSlaveAddress;
 
ret = I2C_transfer(handle, &i2cTransaction);
if (!ret) {
    System_printf("Unsuccessful I2C transfer");
}

Data Structures
struct	I2C_HwAttrs
	I2C Hardware attributes. More...

struct	I2C_Transaction
	I2C transaction. More...

struct	I2C_Params
	I2C Parameters. More...

struct	I2C_Object
	I2C Object. More...

struct	I2C_Config
	I2C Global configuration. More...

Functions
void	I2C_init (void)
	Initialize the I2C module. More...

void	I2C_deinit (void)
	De-nitialize the I2C module. More...

void	I2C_Params_init (I2C_Params *params)
	Function to set default values of I2C_Params in params. More...

I2C_Handle	I2C_open (uint32_t idx, const I2C_Params *params)
	Open the I2C at index idx with parameters params. More...

void	I2C_Transaction_init (I2C_Transaction *transaction)
	Function to set default values of I2C_Transaction in transaction. More...

int32_t	I2C_transfer (I2C_Handle handle, I2C_Transaction *transaction)
	Function to initiate a transfer from I2C. More...

int32_t	I2C_probe (I2C_Handle handle, uint32_t slaveAddr)
	Function to probe I2C. More...

int32_t	I2C_setBusFrequency (I2C_Handle handle, uint32_t busFrequency)
	Function to set the bus frequency. More...

int32_t	I2C_recoverBus (I2C_Handle handle, uint32_t i2cDelay)
	Function to recover the bus in case of error. More...

void	I2C_close (I2C_Handle handle)
	Function to close the I2C. More...

I2C_Handle	I2C_getHandle (uint32_t index)
	This function returns the handle of an open I2C instance from the instance index. More...

Typedefs
typedef struct I2C_Config_s *	I2C_Handle
	A handle that is returned from a I2C_open() call. More...

typedef void(*	I2C_CallbackFxn) (I2C_Handle handle, I2C_Transaction *msg, int32_t transferStatus)
	I2C callback function. More...

Macros
#define	I2C_MAX_NUM_OWN_SLAVE_ADDR (4U)

MACROS used to select the transfer mode
I2C_MODE_BLOCKING block task execution while a I2C transfer is in progress I2C_MODE_CALLBACK does not block task execution; but calls a callback function when the I2C transfer has completed
#define	I2C_MODE_BLOCKING ((uint8_t) 0U)

#define	I2C_MODE_CALLBACK ((uint8_t) 1U)

MACROS used to select one of the standardized bus bit rates for
I2C communication. Deafults to I2C_100KHZ
#define	I2C_100KHZ ((uint8_t) 0U)

#define	I2C_400KHZ ((uint8_t) 1U)

#define	I2C_1P0MHZ ((uint8_t) 2U)

#define	I2C_3P4MHZ ((uint8_t) 3U)

MACROS for the return values of I2C_transfer()

#define	I2C_STS_SUCCESS ( 0)

#define	I2C_STS_ERR (-1)

#define	I2C_STS_ERR_TIMEOUT (-2)

#define	I2C_STS_ERR_BUS_BUSY (-3)

#define	I2C_STS_ERR_NO_ACK (-4)

#define	I2C_STS_ERR_ARBITRATION_LOST (-5)

#define	I2C_STS_ERR_ACCESS_ERROR (-6)

#define	I2C_STS_ERR_COMMAND_FAILURE (-7)

#define	I2C_STS_ERR_INVALID_COMMAND (-8)

#define	I2C_STS_RESTART (-9)

Macro Definition Documentation

◆ I2C_MAX_NUM_OWN_SLAVE_ADDR

#define I2C_MAX_NUM_OWN_SLAVE_ADDR (4U)

◆ I2C_MODE_BLOCKING

#define I2C_MODE_BLOCKING ((uint8_t) 0U)

◆ I2C_MODE_CALLBACK

#define I2C_MODE_CALLBACK ((uint8_t) 1U)

◆ I2C_100KHZ

#define I2C_100KHZ ((uint8_t) 0U)

◆ I2C_400KHZ

#define I2C_400KHZ ((uint8_t) 1U)

◆ I2C_1P0MHZ

#define I2C_1P0MHZ ((uint8_t) 2U)

◆ I2C_3P4MHZ

#define I2C_3P4MHZ ((uint8_t) 3U)

◆ I2C_STS_SUCCESS

#define I2C_STS_SUCCESS ( 0)

◆ I2C_STS_ERR

#define I2C_STS_ERR (-1)

◆ I2C_STS_ERR_TIMEOUT

#define I2C_STS_ERR_TIMEOUT (-2)

◆ I2C_STS_ERR_BUS_BUSY

#define I2C_STS_ERR_BUS_BUSY (-3)

◆ I2C_STS_ERR_NO_ACK

#define I2C_STS_ERR_NO_ACK (-4)

◆ I2C_STS_ERR_ARBITRATION_LOST

#define I2C_STS_ERR_ARBITRATION_LOST (-5)

◆ I2C_STS_ERR_ACCESS_ERROR

#define I2C_STS_ERR_ACCESS_ERROR (-6)

◆ I2C_STS_ERR_COMMAND_FAILURE

#define I2C_STS_ERR_COMMAND_FAILURE (-7)

◆ I2C_STS_ERR_INVALID_COMMAND

#define I2C_STS_ERR_INVALID_COMMAND (-8)

◆ I2C_STS_RESTART

#define I2C_STS_RESTART (-9)

Typedef Documentation

◆ I2C_Handle

typedef struct I2C_Config_s* I2C_Handle

A handle that is returned from a I2C_open() call.

◆ I2C_CallbackFxn

typedef void(* I2C_CallbackFxn) (I2C_Handle handle, I2C_Transaction *msg, int32_t transferStatus)

I2C callback function.

User definable callback function prototype. The I2C driver will call the defined function and pass in the I2C driver's handle, the pointer to the I2C transaction that just completed, and the return value of I2C_transfer.

In slave mode, when there is a restart condtion,the driver calls back to the application with received data and I2C_STS_RESTART transfer status, application needs to provide the restart transmit data in I2C_Transaction rsWrToMstBuf. Restart condition only works in callback mode.

Parameters

handle	I2C_Handle
msg	Address of the I2C_Transaction performed
transferStatus	Results of the I2C transaction

Function Documentation

◆ I2C_init()

void I2C_init ( void )

Initialize the I2C module.

◆ I2C_deinit()

void I2C_deinit ( void )

De-nitialize the I2C module.

◆ I2C_Params_init()

void I2C_Params_init ( I2C_Params * params )

Function to set default values of I2C_Params in params.

Parameters

params [IN] pointer to the structure to be initialized

◆ I2C_open()

I2C_Handle I2C_open	(	uint32_t	idx,
		const I2C_Params *	params
	)

Open the I2C at index idx with parameters params.

Parameters

idx	[IN] Index of I2C to open in global config
params	[IN] I2C_Params values to use for opening

Returns: I2C_Handle

◆ I2C_Transaction_init()

void I2C_Transaction_init ( I2C_Transaction * transaction )

Function to set default values of I2C_Transaction in transaction.

Parameters

transaction [IN] pointer to the structure to be initialized

◆ I2C_transfer()

int32_t I2C_transfer	(	I2C_Handle	handle,
		I2C_Transaction *	transaction
	)

Function to initiate a transfer from I2C.

Parameters

handle	[IN] handle to the I2C
transaction	[IN] I2C_Transaction structure that contains values for this specific transfer

Returns: I2C_StatusCode

◆ I2C_probe()

int32_t I2C_probe	(	I2C_Handle	handle,
		uint32_t	slaveAddr
	)

Function to probe I2C.

Parameters

handle	[IN] handle to the I2C
slaveAddr	[IN] address of the slave to probe

Returns: I2C_StatusCode

◆ I2C_setBusFrequency()

int32_t I2C_setBusFrequency	(	I2C_Handle	handle,
		uint32_t	busFrequency
	)

Function to set the bus frequency.

Parameters

handle	[IN] handle to the I2C
busFrequency	[IN] frequency value to be set

Returns: I2C_StatusCode

◆ I2C_recoverBus()

int32_t I2C_recoverBus	(	I2C_Handle	handle,
		uint32_t	i2cDelay
	)

Function to recover the bus in case of error.

Parameters

handle	[IN] handle to the I2C
i2cDelay	[IN] the length of delay for sending clock pulses to slave

Returns: I2C_StatusCode

◆ I2C_close()

void I2C_close ( I2C_Handle handle )

Function to close the I2C.

Parameters

handle [IN] handle to the I2C

◆ I2C_getHandle()

I2C_Handle I2C_getHandle ( uint32_t index )

This function returns the handle of an open I2C instance from the instance index.

Precondition: I2C controller has been opened using I2C_open()

Parameters

index [IN] Index of config to use in the I2C_Config array

Returns: An I2C_Handle if it has been opened already or NULL otherwise

Introduction

Operation

Opening the driver

Transferring data

Data Structures

Functions

Typedefs

Macros

MACROS used to select the transfer mode

MACROS used to select one of the standardized bus bit rates for

MACROS for the return values of I2C_transfer()

Macro Definition Documentation

◆ I2C_MAX_NUM_OWN_SLAVE_ADDR

◆ I2C_MODE_BLOCKING

◆ I2C_MODE_CALLBACK

◆ I2C_100KHZ

◆ I2C_400KHZ

◆ I2C_1P0MHZ

◆ I2C_3P4MHZ

◆ I2C_STS_SUCCESS

◆ I2C_STS_ERR

◆ I2C_STS_ERR_TIMEOUT

◆ I2C_STS_ERR_BUS_BUSY

◆ I2C_STS_ERR_NO_ACK

◆ I2C_STS_ERR_ARBITRATION_LOST

◆ I2C_STS_ERR_ACCESS_ERROR

◆ I2C_STS_ERR_COMMAND_FAILURE

◆ I2C_STS_ERR_INVALID_COMMAND

◆ I2C_STS_RESTART

Typedef Documentation

◆ I2C_Handle

◆ I2C_CallbackFxn

Function Documentation

◆ I2C_init()

◆ I2C_deinit()

◆ I2C_Params_init()

◆ I2C_open()

◆ I2C_Transaction_init()

◆ I2C_transfer()

◆ I2C_probe()

◆ I2C_setBusFrequency()

◆ I2C_recoverBus()

◆ I2C_close()

◆ I2C_getHandle()