Introduction

I2C driver interface

Files
file	I2C.h
	I2C driver interface.

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...

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)

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...

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)

Macro Definition Documentation

◆ I2C_CMD_RESERVED

#define I2C_CMD_RESERVED 32

Common I2C_control command code reservation offset. I2C driver implementations should offset command codes with I2C_CMD_RESERVED growing positively

Example implementation specific command codes:

#define I2CXYZ_COMMAND0 I2C_CMD_RESERVED + 0

#define I2CXYZ_COMMAND1 I2C_CMD_RESERVED + 1

◆ I2C_CMD_PROBE

#define I2C_CMD_PROBE (0U)

I2C probe IOCTL. This IOCTL returns I2C_STATUS_SUCCESS if the device is present. Returns I2C_STATUS_ERROR otherwise. The argument to this IOCTL is the uint32_t * of the device address.

◆ I2C_CMD_SET_BUS_FREQUENCY

#define I2C_CMD_SET_BUS_FREQUENCY (1U)

This command sets the i2c bus speed dynamically. This command returns I2C_STATUS_SUCCESS if the device is present. Returns I2C_STATUS_ERROR otherwise. The argument to this accepts the two macros I2C_100kHz, I2C_400kHz.

◆ I2C_CMD_RECOVER_BUS

#define I2C_CMD_RECOVER_BUS (2U)

This command performs bus recovery in case of timeout error. This command returns I2C_STATUS_SUCCESS if the device is present. Returns I2C_STATUS_ERROR otherwise. The argument to this accepts the delay value.

◆ I2C_CMD_SMBUS_TYPE

#define I2C_CMD_SMBUS_TYPE (3U)

This command performs SMBUS command and code setup. This command returns I2C_STATUS_SUCCESS if a valid smbus cmd is passed. Returns I2C_STATUS_ERROR otherwise. The argument to this accepts the SMBUS command and its subcode.

◆ I2C_STATUS_RESERVED

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

Common I2C_control status code reservation offset. I2C driver implementations should offset status codes with I2C_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

#define I2CXYZ_STATUS_ERROR0     I2C_STATUS_RESERVED - 0
#define I2CXYZ_STATUS_ERROR1     I2C_STATUS_RESERVED - 1
#define I2CXYZ_STATUS_ERROR2     I2C_STATUS_RESERVED - 2

◆ I2C_STATUS_SUCCESS

#define I2C_STATUS_SUCCESS ((int32_t)(0))

Successful status code returned by I2C_control().

I2C_control() returns I2C_STATUS_SUCCESS if the control code was executed successfully.

◆ I2C_STATUS_ERROR

#define I2C_STATUS_ERROR (-((int32_t)1))

Generic error status code returned by I2C_control().

I2C_control() returns I2C_STATUS_ERROR if the control code was not executed successfully.

◆ I2C_STATUS_UNDEFINEDCMD

#define I2C_STATUS_UNDEFINEDCMD (-((int32_t)2))

An error status code returned by I2C_control() for undefined command codes.

I2C_control() returns I2C_STATUS_UNDEFINEDCMD if the control code is not recognized by the driver implementation.

◆ I2C_STS_SUCCESS

#define I2C_STS_SUCCESS ((int16_t)(1))

A status code returned by I2C_transfer().

I2C_transfer() returns I2C_STS_SUCCESS if the transfer is succesful.

◆ I2C_STS_RESTART

#define I2C_STS_RESTART ((int16_t)(2))

A restart status code returned by I2C transfer callback.

I2C transfer callback function returns I2C_STS_RESTART if the restart condition is detected. This status is only valid in slave mode.

◆ I2C_STS_ERR

#define I2C_STS_ERR ((int16_t)(0))

A error status code returned by I2C_transfer().

I2C_transfer() returns I2C_STS_ERR if the transfer is failed.

◆ I2C_STS_ERR_TIMEOUT

#define I2C_STS_ERR_TIMEOUT (-(int16_t)(1))

A error status code returned by I2C_transfer().

I2C_transfer() returns I2C_STS_ERR_TIMEOUT if the timeout error is occured during the transfer.

◆ I2C_STS_ERR_BUS_BUSY

#define I2C_STS_ERR_BUS_BUSY (-(int16_t)(2))

I2C bus busy error.

◆ I2C_STS_ERR_NO_ACK

#define I2C_STS_ERR_NO_ACK (-(int16_t)(3))

I2C no ack error when no acknowledgement is received.

◆ I2C_STS_ERR_ARBITRATION_LOST

#define I2C_STS_ERR_ARBITRATION_LOST (-(int16_t)(4))

I2C Arbitration lost error.

◆ I2C_STS_ERR_ACCESS_ERROR

#define I2C_STS_ERR_ACCESS_ERROR (-(int16_t)(5))

I2C Bus Access error.

◆ I2C_STS_ERR_COMMAND_FAILURE

#define I2C_STS_ERR_COMMAND_FAILURE (-(int16_t)(6))

I2C FW Command Access Failure.

◆ I2C_STS_ERR_INVALID_COMMAND

#define I2C_STS_ERR_INVALID_COMMAND (-(int16_t)(7))

I2C FW Invalid Command passed.

◆ I2C_TRANS_VALID_PARAM_MASTER_MODE

#define I2C_TRANS_VALID_PARAM_MASTER_MODE (0x00000001U)

I2C_TRANSACTION valid parameter bit fields.

Valid bit fields supported

I2C_TRANS_VALID_PARAM_MASTER_MODE I2C_TRANS_VALID_PARAM_EXPAND_SA

◆ I2C_TRANS_VALID_PARAM_EXPAND_SA

#define I2C_TRANS_VALID_PARAM_EXPAND_SA (0x00000002U)

I2C transaction.

This structure defines the nature of the I2C transaction.

I2C master mode: This structure specifies the buffer and buffer's size that is to be written to or read from the I2C slave peripheral.

I2C slave mode: This structure specifies the buffer and buffer's size that is to be read from or written to the I2C master. In restart condition, readBuf/writeBuf and readCount/writeCount are used repeatedly for every start in one transfer. When each restart happens, driver will call back to application with the restart transfer status, and application should save the data transferred in the previous start, and provide the new data to the current start. When all the starts complete (stop condition), driver will call back to application with transfer success status, and readBuf/writeBuf and readCount/writeCount will only record the data transferred in the last start condition.

arg is an optional user supplied argument that will be passed to the callback function when the I2C driver is in I2C_MODE_CALLBACK. nextPtr is to be only used by the I2C driver.

◆ I2C_WAIT_FOREVER

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

◆ I2C_MAX_CONFIG_CNT

#define I2C_MAX_CONFIG_CNT (14U)

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, int16_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

I2C_Handle	I2C_Handle
I2C_Transaction*	Address of the I2C_Transaction performed
bool	Results of the I2C transaction

◆ I2C_CloseFxn

typedef void(* I2C_CloseFxn) (I2C_Handle handle)

A function pointer to a driver specific implementation of I2C_close().

◆ I2C_ControlFxn

typedef int32_t(* I2C_ControlFxn) (I2C_Handle handle, uint32_t cmd, void *arg)

A function pointer to a driver specific implementation of I2C_control().

◆ I2C_InitFxn

typedef void(* I2C_InitFxn) (I2C_Handle handle)

A function pointer to a driver specific implementation of I2C_init().

◆ I2C_OpenFxn

typedef I2C_Handle(* I2C_OpenFxn) (I2C_Handle handle, const I2C_Params *params)

A function pointer to a driver specific implementation of I2C_open().

◆ I2C_TransferFxn

typedef int16_t(* I2C_TransferFxn) (I2C_Handle handle, I2C_Transaction *transaction)

A function pointer to a driver specific implementation of I2C_transfer().

◆ I2C_config_list

typedef I2C_Config I2C_config_list[I2C_MAX_CONFIG_CNT]

Enumeration Type Documentation

◆ I2C_TransferMode

enum I2C_TransferMode

I2C 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

Enumerator
I2C_MODE_BLOCKING	I2C_transfer blocks execution
I2C_MODE_CALLBACK	I2C_transfer queues transactions and does not block

◆ I2C_BitRate

enum I2C_BitRate

I2C bitRate.

Specify one of the standardized I2C bus bit rates for I2C communications. The default is I2C_100kHz.

Enumerator
I2C_100kHz
I2C_400kHz
I2C_1P0Mhz
I2C_3P4Mhz

Function Documentation

◆ I2C_close()

void I2C_close ( I2C_Handle i2cHnd )

Function to close a I2C peripheral specified by the I2C handle.

Precondition: I2C_open() had to be called first.

Parameters

i2cHnd A I2C_Handle returned from I2C_open

See also: I2C_open()

◆ I2C_control()

int32_t I2C_control	(	I2C_Handle	i2cHnd,
		uint32_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given I2C_Handle.

Precondition: I2C_open() has to be called first.

Parameters

i2cHnd	A I2C handle returned from I2C_open()
cmd	A command value defined by the driver specific implementation
arg	An optional R/W (read/write) argument that is accompanied with cmd

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: I2C_open()

◆ I2C_init()

void I2C_init ( void )

Function to initializes the I2C module.

Precondition: The I2C_config structure must exist and be persistent before this function can be called. This function must also be called before any other I2C driver APIs. This function call does not modify any peripheral registers.

◆ I2C_open()

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.

Precondition: I2C controller has been initialized

Parameters

idx	Logical peripheral number for the I2C indexed into the I2C_config table
params	Pointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only).

Returns: A I2C_Handle on success or a NULL on an error or if it has been opened already.

See also: I2C_init(); I2C_close()

◆ I2C_Params_init()

void I2C_Params_init ( I2C_Params * params )

Function to initialize the I2C_Params struct to its defaults.

Parameters

params An pointer to I2C_Params structure for initialization

Defaults values are: transferMode = I2C_MODE_BLOCKING transferCallbackFxn = NULL bitRate = I2C_100kHz

◆ I2C_transfer()

int16_t I2C_transfer	(	I2C_Handle	i2cHnd,
		I2C_Transaction *	transaction
	)

Function that handles the I2C transfer for SYS/BIOS.

This function will start a I2C transfer and can only be called from a Task context when in I2C_MODE_BLOCKING. The I2C transfer procedure starts with evaluating how many bytes are to be written and how many are to be read from the I2C peripheral. Due to common I2C data transfer processes, to be written will always sent before any data is read.

The data written to the peripheral is preceded with the peripheral's 7-bit I2C slave address (with the Write bit set). After all the data has been transmitted, the driver will evaluate if any data needs to be read from the device. If so, a Re-START bit is sent, along with the same 7-bit I2C slave address (with the Read bit). Else, the transfer is concluded with a STOP bit. After the specified number of bytes have been read by the I2C, the transfer is ended with a NACK and STOP bit.

In I2C_MODE_BLOCKING, I2C_transfer will block task execution until the transaction has completed.

In I2C_MODE_CALLBACK, I2C_transfer does not block task execution and calls a callback function specified by transferCallbackFxn. If a transfer is already taking place, the transaction is put on an internal queue. The queue is serviced in a first come first served basis. The I2C_Transaction structure must stay persistent until the I2C_transfer function has completed!

Parameters

i2cHnd	A I2C_Handle
transaction	A pointer to a I2C_Transaction. All of the fields within transaction are WO (write-only) unless otherwise noted in the driver implementations.

Returns: true on successful transfer false on an error, such as a I2C bus fault

See also: I2C_openFunction to initialize the I2C_Transaction struct to its defaults

Defaults values are: validParams = I2C_TRANS_VALID_PARAM_MASTER_MODE; writeBuf = NULL; writeCount = 0; readBuf = NULL; readCount = 0; slaveAddress = 0; arg = NULL; nextPtr = NULL; timeout = I2C_WAIT_FOREVER; rsWrToMstBuf = NULL; rsWrToMstCnt = 0; masterMode = true;

Returns: transaction parameter structure to initialize

◆ I2C_transactionInit()

void I2C_transactionInit ( I2C_Transaction * transaction )

Introduction

Files

Data Structures

Functions

Typedefs

Enumerations

Macros

Macro Definition Documentation

◆ I2C_CMD_RESERVED

◆ I2C_CMD_PROBE

◆ I2C_CMD_SET_BUS_FREQUENCY

◆ I2C_CMD_RECOVER_BUS

◆ I2C_CMD_SMBUS_TYPE

◆ I2C_STATUS_RESERVED

◆ I2C_STATUS_SUCCESS

◆ I2C_STATUS_ERROR

◆ I2C_STATUS_UNDEFINEDCMD

◆ I2C_STS_SUCCESS

◆ I2C_STS_RESTART

◆ 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_TRANS_VALID_PARAM_MASTER_MODE

◆ I2C_TRANS_VALID_PARAM_EXPAND_SA

◆ I2C_WAIT_FOREVER

◆ I2C_MAX_CONFIG_CNT

Typedef Documentation

◆ I2C_Handle

◆ I2C_CallbackFxn

◆ I2C_CloseFxn

◆ I2C_ControlFxn

◆ I2C_InitFxn

◆ I2C_OpenFxn

◆ I2C_TransferFxn

◆ I2C_config_list

Enumeration Type Documentation

◆ I2C_TransferMode

◆ I2C_BitRate

Function Documentation

◆ I2C_close()

◆ I2C_control()

◆ I2C_init()

◆ I2C_open()

◆ I2C_Params_init()

◆ I2C_transfer()

◆ I2C_transactionInit()