Introduction

I2C driver interface.

============================================================================

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_Transaction i2cTransaction;
I2C_Params_init(&params);
params.transferMode  = I2C_MODE_CALLBACK;
params.transferCallbackFxn = someI2CCallbackFunction;
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;
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");
}

Implementation

This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a I2C_FxnTable.

The I2C driver interface module is joined (at link time) to a NULL-terminated array of I2C_Config data structures named I2C_config. I2C_config is implemented in the application with each entry being an instance of a I2C peripheral. Each entry in I2C_config contains a:

(I2C_FxnTable *) to a set of functions that implement a I2C peripheral
(void *) data object that is associated with the I2C_FxnTable
(void *) hardware attributes that are associated to the I2C_FxnTable

Instrumentation

The I2C driver interface produces log statements if instrumentation is enabled.

Go to the source code of this file.

Data Structures
struct	I2C_Transaction

struct	I2C_Params
	I2C Parameters. More...

struct	I2C_FxnTable
	The definition of a I2C function table that contains the required set of functions to control a specific I2C driver implementation. More...

struct	I2C_Config
	I2C Global configuration. More...

Macros
#define	I2C_CMD_RESERVED 32

#define	I2C_CMD_PROBE (0U)

#define	I2C_CMD_SET_BUS_FREQUENCY (1U)

#define	I2C_CMD_RECOVER_BUS (2U)

#define	I2C_CMD_SMBUS_TYPE (3U)

#define	I2C_STATUS_RESERVED (-((int32_t)32))

#define	I2C_STATUS_SUCCESS ((int32_t)(0))
	Successful status code returned by I2C_control(). More...

#define	I2C_STATUS_ERROR (-((int32_t)1))
	Generic error status code returned by I2C_control(). More...

#define	I2C_STATUS_UNDEFINEDCMD (-((int32_t)2))
	An error status code returned by I2C_control() for undefined command codes. More...

#define	I2C_STS_SUCCESS ((int16_t)(1))
	A status code returned by I2C_transfer(). More...

#define	I2C_STS_RESTART ((int16_t)(2))
	A restart status code returned by I2C transfer callback. More...

#define	I2C_STS_ERR ((int16_t)(0))
	A error status code returned by I2C_transfer(). More...

#define	I2C_STS_ERR_TIMEOUT (-(int16_t)(1))
	A error status code returned by I2C_transfer(). More...

#define	I2C_STS_ERR_BUS_BUSY (-(int16_t)(2))
	I2C bus busy error. More...

#define	I2C_STS_ERR_NO_ACK (-(int16_t)(3))
	I2C no ack error when no acknowledgement is received. More...

#define	I2C_STS_ERR_ARBITRATION_LOST (-(int16_t)(4))
	I2C Arbitration lost error. More...

#define	I2C_STS_ERR_ACCESS_ERROR (-(int16_t)(5))
	I2C Bus Access error. More...

#define	I2C_STS_ERR_COMMAND_FAILURE (-(int16_t)(6))
	I2C FW Command Access Failure. More...

#define	I2C_STS_ERR_INVALID_COMMAND (-(int16_t)(7))
	I2C FW Invalid Command passed. More...

#define	I2C_TRANS_VALID_PARAM_MASTER_MODE (0x00000001U)
	I2C_TRANSACTION valid parameter bit fields. More...

#define	I2C_TRANS_VALID_PARAM_EXPAND_SA (0x00000002U)
	I2C transaction. More...

#define	I2C_WAIT_FOREVER (~((uint32_t)0U))

#define	I2C_MAX_CONFIG_CNT (14U)

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, int16_t transferStatus)
	I2C callback function. More...

typedef void(*	I2C_CloseFxn) (I2C_Handle handle)
	A function pointer to a driver specific implementation of I2C_close(). More...

typedef int32_t(*	I2C_ControlFxn) (I2C_Handle handle, uint32_t cmd, void *arg)
	A function pointer to a driver specific implementation of I2C_control(). More...

typedef void(*	I2C_InitFxn) (I2C_Handle handle)
	A function pointer to a driver specific implementation of I2C_init(). More...

typedef I2C_Handle(*	I2C_OpenFxn) (I2C_Handle handle, const I2C_Params *params)
	A function pointer to a driver specific implementation of I2C_open(). More...

typedef int16_t(*	I2C_TransferFxn) (I2C_Handle handle, I2C_Transaction *transaction)
	A function pointer to a driver specific implementation of I2C_transfer(). More...

typedef I2C_Config	I2C_config_list[I2C_MAX_CONFIG_CNT]

Enumerations
enum	I2C_TransferMode { I2C_MODE_BLOCKING, I2C_MODE_CALLBACK }
	I2C transfer mode. More...

enum	I2C_BitRate { I2C_100kHz = 0, I2C_400kHz = 1, I2C_1P0Mhz = 2, I2C_3P4Mhz = 3 }
	I2C bitRate. More...

Functions
void	I2C_close (I2C_Handle i2cHnd)
	Function to close a I2C peripheral specified by the I2C handle. More...

int32_t	I2C_control (I2C_Handle i2cHnd, uint32_t cmd, void *arg)
	Function performs implementation specific features on a given I2C_Handle. More...

void	I2C_init (void)
	Function to initializes the I2C module. More...

I2C_Handle	I2C_open (uint32_t idx, I2C_Params *params)
	Function to initialize a given I2C peripheral specified by the particular index value. The parameter specifies which mode the I2C will operate. More...

void	I2C_Params_init (I2C_Params *params)
	Function to initialize the I2C_Params struct to its defaults. More...

int16_t	I2C_transfer (I2C_Handle i2cHnd, I2C_Transaction *transaction)
	Function that handles the I2C transfer for SYS/BIOS. More...

void	I2C_transactionInit (I2C_Transaction *transaction)

Introduction

Operation

Opening the driver

Transferring data

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions