Introduction

This module contains APIs to program and use the I2C LLD module. The APIs can be used by other drivers to get access to I2C and also by application to initiate transaction operations.

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

#include <drivers/i2c/v1/lld/i2c_lld.h>

Files
file	i2c_lld.h
	I2C LLD Driver API/interface file.

Data Structures
struct	I2CLLD_Transaction
	I2C Transaction. More...

struct	I2CLLD_Message
	I2C Message. More...

struct	I2C_ExtendedParams
	Data structure used with I2C_lld_write(), I2C_lld_writeIntr(), I2C_lld_read(), I2C_lld_readIntr() More...

struct	I2C_Memory_ExtendedParams
	Data structure used with I2C_lld_mem_write(), I2C_lld_mem_writeIntr(), I2C_lld_mem_read(), I2C_lld_mem_readIntr() More...

struct	I2CLLD_targetTransaction
	I2C Target Transaction. More...

struct	I2CLLD_Object
	I2C Driver Object. More...

Functions
int32_t	I2C_lld_init (I2CLLD_Handle handle)
	This API Initializes the I2C instance. More...

int32_t	I2C_lld_deInit (I2CLLD_Handle handle)
	This API De-Initializes the I2C instance. More...

int32_t	I2C_lld_Transaction_init (I2CLLD_Transaction *transaction)
	API to set default values of I2CLLD_Transaction in transaction. More...

int32_t	I2C_lld_Message_init (I2CLLD_Message *msg)
	API to set default values of I2CLLD_Message in msg. More...

int32_t	I2C_lld_write (I2CLLD_Handle handle, I2C_ExtendedParams *extendedParams, uint32_t timeout)
	API to initiate the write transaction in polled mode. More...

int32_t	I2C_lld_writeIntr (I2CLLD_Handle handle, I2C_ExtendedParams *extendedParams)
	API to initiate the write transaction in Interrupt mode. More...

int32_t	I2C_lld_read (I2CLLD_Handle handle, I2C_ExtendedParams *extendedParams, uint32_t timeout)
	API to initiate the read transaction in polled mode. More...

int32_t	I2C_lld_readIntr (I2CLLD_Handle handle, I2C_ExtendedParams *extendedParams)
	API to initiate the read transaction in Interrupt mode. More...

int32_t	I2C_lld_mem_write (I2CLLD_Handle handle, I2C_Memory_ExtendedParams *mem_extendedParams, uint32_t timeout)
	Function to initiate a transfer from I2C in interrupt mode. More...

int32_t	I2C_lld_mem_writeIntr (I2CLLD_Handle handle, I2C_Memory_ExtendedParams *mem_extendedParams)
	Function to initiate a transfer from I2C in interrupt mode. More...

int32_t	I2C_lld_mem_read (I2CLLD_Handle handle, I2C_Memory_ExtendedParams *mem_extendedParams, uint32_t timeout)
	Function to initiate a transfer from I2C in interrupt mode. More...

int32_t	I2C_lld_mem_readIntr (I2CLLD_Handle handle, I2C_Memory_ExtendedParams *mem_extendedParams)
	Function to initiate a transfer from I2C in interrupt mode. More...

int32_t	I2C_lld_transferPoll (I2CLLD_Handle handle, I2CLLD_Message *msg)
	Function to initiate a transfer from I2C in polled mode. More...

int32_t	I2C_lld_transferIntr (I2CLLD_Handle handle, I2CLLD_Message *msg)
	Function to initiate a transfer from I2C in interrupt mode. More...

int32_t	I2C_lld_targetTransferIntr (I2CLLD_Handle handle, I2CLLD_targetTransaction *txn)
	Function to initiate a transfer from I2C in target mode. More...

int32_t	I2C_lld_probe (I2CLLD_Handle handle, uint32_t targetAddr)
	Function to probe I2C. More...

int32_t	I2C_lld_setBusFrequency (I2CLLD_Handle handle, uint32_t busFrequency)
	Function to set the bus frequency. More...

void	I2C_lld_controllerIsr (void *args)
	This is the I2C Controller ISR and can be used as IRQ handler in Controller mode. More...

void	I2C_lld_targetIsr (void *args)
	This is the I2C Target ISR and can be used as IRQ handler in Target mode. More...

Typedefs
typedef uint32_t(*	I2C_Clock_getTicks) (void)
	The definition of a get System Tick function used by the I2C driver to keep track of time. More...

typedef uint32_t(*	I2C_Clock_usecToTicks) (uint64_t usecs)
	The definition of a micro seconds to ticks function used by the I2C driver to get ticks from microseconds. More...

typedef void(*	I2C_Clock_uSleep) (uint32_t usec)
	The definition of a sleep function used by the I2C driver for delay. More...

typedef void(*	I2C_lld_transferCompleteCallback) (void args, const I2CLLD_Message msg, int32_t transferStatus)
	The definition of a transfer completion callback function used by the I2C driver when used in Controller Callback Mode. More...

typedef void(*	I2C_lld_targetTransferCompleteCallback) (void args, const I2CLLD_targetTransaction targetTxn, int32_t transferStatus)
	The definition of a transfer completion callback function used by the I2C driver when used in Target Mode. More...

typedef struct I2CLLD_Object *	I2CLLD_Handle

Return status

#define	I2C_STS_SUCCESS ((int32_t) 0)
	Return status when the API execution was successful. More...

#define	I2C_STS_ERR ((int32_t)-1)
	Return status when the API execution was not successful due to a generic Error. More...

#define	I2C_STS_ERR_TIMEOUT ((int32_t)-2)
	Return status when the API execution was not successful due to a time out. More...

#define	I2C_STS_ERR_INVALID_PARAM ((int32_t)-3)
	Return status when the API execution failed due invalid parameters. More...

#define	I2C_STS_ERR_BUS_BUSY ((int32_t)-4)
	Return status when the API execution failed due to driver busy. More...

#define	I2C_STS_ERR_NO_ACK ((int32_t)-5)
	Return status when the API execution failed due to no Acknowledgement from target. More...

#define	I2C_STS_ERR_ARBITRATION_LOST ((int32_t)-6)
	Return status when the API execution failed due to loss in arbitration during transmission. More...

Timeout values

#define	I2C_NO_WAIT ((uint32_t)0)
	Value to use when needing a timeout of zero or NO timeout, return immediately on resource not available. More...

#define	I2C_WAIT_FOREVER ((uint32_t)-1)
	Value to use when needing a timeout of infinity or wait forver until resource is available. More...

I2C Driver states
#define	I2C_STATE_RESET ((uint8_t) 0U)
	I2C driver is in Reset State prior to driver init and post driver deinit. More...

#define	I2C_STATE_IDLE ((uint8_t) 1U)
	I2C driver accepts runtime APIs only Ready State, otherwise return error. More...

#define	I2C_STATE_BUSY ((uint8_t) 2U)
	I2C driver is busy performing operation with peripherals, return error when APIs are invoked. More...

#define	I2C_STATE_ERROR ((uint8_t) 3U)
	I2C driver ran into error, returns error for all APIs other than deinit in this state. More...

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

#define	I2C_400KHZ ((uint8_t) 1U)
	I2C bus frequency : 400KHz. More...

MACROS for the possible values of Memory Write/Read API parameter.

#define	I2C_MEM_ADDR_SIZE_8_BITS ((uint8_t) 1U)
	I2C Target Internal Memory address 8 bits. More...

#define	I2C_MEM_ADDR_SIZE_16_BITS ((uint8_t) 2U)
	I2C Target Internal Memory address 16 bits. More...

MACROS used to define the state of the I2C Driver State Machine

#define	I2C_WRITE_STATE ((uint8_t) 10U)
	I2C is in Write state. More...

#define	I2C_READ_STATE ((uint8_t) 11U)
	I2C is in Write state. More...

#define	I2C_TARGET_XFER_STATE ((uint8_t) 12U)
	I2C is trasferring in target mode. More...

#define	I2C_TARGET_RESTART_STATE ((uint8_t) 13U)
	I2C is restarting trasfer in target mode. More...

Macro Definition Documentation

◆ I2C_STS_SUCCESS

#define I2C_STS_SUCCESS ((int32_t) 0)

Return status when the API execution was successful.

◆ I2C_STS_ERR

#define I2C_STS_ERR ((int32_t)-1)

Return status when the API execution was not successful due to a generic Error.

◆ I2C_STS_ERR_TIMEOUT

#define I2C_STS_ERR_TIMEOUT ((int32_t)-2)

Return status when the API execution was not successful due to a time out.

◆ I2C_STS_ERR_INVALID_PARAM

#define I2C_STS_ERR_INVALID_PARAM ((int32_t)-3)

Return status when the API execution failed due invalid parameters.

◆ I2C_STS_ERR_BUS_BUSY

#define I2C_STS_ERR_BUS_BUSY ((int32_t)-4)

Return status when the API execution failed due to driver busy.

◆ I2C_STS_ERR_NO_ACK

#define I2C_STS_ERR_NO_ACK ((int32_t)-5)

Return status when the API execution failed due to no Acknowledgement from target.

◆ I2C_STS_ERR_ARBITRATION_LOST

#define I2C_STS_ERR_ARBITRATION_LOST ((int32_t)-6)

Return status when the API execution failed due to loss in arbitration during transmission.

◆ I2C_NO_WAIT

#define I2C_NO_WAIT ((uint32_t)0)

Value to use when needing a timeout of zero or NO timeout, return immediately on resource not available.

◆ I2C_WAIT_FOREVER

#define I2C_WAIT_FOREVER ((uint32_t)-1)

Value to use when needing a timeout of infinity or wait forver until resource is available.

◆ I2C_STATE_RESET

#define I2C_STATE_RESET ((uint8_t) 0U)

I2C driver is in Reset State prior to driver init and post driver deinit.

◆ I2C_STATE_IDLE

#define I2C_STATE_IDLE ((uint8_t) 1U)

I2C driver accepts runtime APIs only Ready State, otherwise return error.

◆ I2C_STATE_BUSY

#define I2C_STATE_BUSY ((uint8_t) 2U)

I2C driver is busy performing operation with peripherals, return error when APIs are invoked.

◆ I2C_STATE_ERROR

#define I2C_STATE_ERROR ((uint8_t) 3U)

I2C driver ran into error, returns error for all APIs other than deinit in this state.

◆ I2C_100KHZ

#define I2C_100KHZ ((uint8_t) 0U)

I2C bus frequency : 100KHz.

◆ I2C_400KHZ

#define I2C_400KHZ ((uint8_t) 1U)

I2C bus frequency : 400KHz.

◆ I2C_MEM_ADDR_SIZE_8_BITS

#define I2C_MEM_ADDR_SIZE_8_BITS ((uint8_t) 1U)

I2C Target Internal Memory address 8 bits.

◆ I2C_MEM_ADDR_SIZE_16_BITS

#define I2C_MEM_ADDR_SIZE_16_BITS ((uint8_t) 2U)

I2C Target Internal Memory address 16 bits.

◆ I2C_WRITE_STATE

#define I2C_WRITE_STATE ((uint8_t) 10U)

I2C is in Write state.

◆ I2C_READ_STATE

#define I2C_READ_STATE ((uint8_t) 11U)

I2C is in Write state.

◆ I2C_TARGET_XFER_STATE

#define I2C_TARGET_XFER_STATE ((uint8_t) 12U)

I2C is trasferring in target mode.

◆ I2C_TARGET_RESTART_STATE

#define I2C_TARGET_RESTART_STATE ((uint8_t) 13U)

I2C is restarting trasfer in target mode.

Typedef Documentation

◆ I2C_Clock_getTicks

typedef uint32_t(* I2C_Clock_getTicks) (void)

The definition of a get System Tick function used by the I2C driver to keep track of time.

Returns: Returns system ticks in 32-bit unsigned int format

◆ I2C_Clock_usecToTicks

typedef uint32_t(* I2C_Clock_usecToTicks) (uint64_t usecs)

The definition of a micro seconds to ticks function used by the I2C driver to get ticks from microseconds.

Parameters

usecs Micro Seconds

Returns: Returns system ticks in 32-bit unsigned int format

◆ I2C_Clock_uSleep

typedef void(* I2C_Clock_uSleep) (uint32_t usec)

The definition of a sleep function used by the I2C driver for delay.

Parameters

usec	Micro Seconds

◆ I2C_lld_transferCompleteCallback

typedef void(* I2C_lld_transferCompleteCallback) (void *args, const I2CLLD_Message *msg, int32_t transferStatus)

The definition of a transfer completion callback function used by the I2C driver when used in Controller Callback Mode.

Parameters

args	Void Pointer
msg	Pointer to I2CLLD_Message Object
transferStatus	Transfer Status

◆ I2C_lld_targetTransferCompleteCallback

typedef void(* I2C_lld_targetTransferCompleteCallback) (void *args, const I2CLLD_targetTransaction *targetTxn, int32_t transferStatus)

The definition of a transfer completion callback function used by the I2C driver when used in Target Mode.

Parameters

args	Void Pointer
targetTxn	Pointer to I2CLLD_targetTransaction Object
transferStatus	Transfer Status

◆ I2CLLD_Handle

typedef struct I2CLLD_Object * I2CLLD_Handle

Function Documentation

◆ I2C_lld_init()

int32_t I2C_lld_init ( I2CLLD_Handle handle )

This API Initializes the I2C instance.

Parameters

handle [IN] Handle to the I2C instance used

Returns: I2C_StatusCode

◆ I2C_lld_deInit()

int32_t I2C_lld_deInit ( I2CLLD_Handle handle )

This API De-Initializes the I2C instance.

Parameters

handle [IN] Handle to the I2C instance used

Returns: I2C_StatusCode

◆ I2C_lld_Transaction_init()

int32_t I2C_lld_Transaction_init ( I2CLLD_Transaction * transaction )

API to set default values of I2CLLD_Transaction in transaction.

Parameters

transaction [IN] Pointer to the structure to be initialized

Returns: I2C_StatusCode

◆ I2C_lld_Message_init()

int32_t I2C_lld_Message_init ( I2CLLD_Message * msg )

API to set default values of I2CLLD_Message in msg.

Parameters

msg	[IN] Pointer to the structure to be initialized

Returns: I2C_StatusCode

◆ I2C_lld_write()

int32_t I2C_lld_write	(	I2CLLD_Handle	handle,
		I2C_ExtendedParams *	extendedParams,
		uint32_t	timeout
	)

API to initiate the write transaction in polled mode.

Parameters

handle	[IN] Handle to the I2C instance used
extendedParams	[IN] Pointer to structure containing transfer parameters
timeout	[IN] Timeout for read operation in Micro Seconds I2cTimeoutValues

Returns: I2C_StatusCode

◆ I2C_lld_writeIntr()

int32_t I2C_lld_writeIntr	(	I2CLLD_Handle	handle,
		I2C_ExtendedParams *	extendedParams
	)

API to initiate the write transaction in Interrupt mode.

Parameters

handle	[IN] Handle to the I2C instance used
extendedParams	[IN] Pointer to structure containing transfer parameters

Returns: I2C_StatusCode

◆ I2C_lld_read()

int32_t I2C_lld_read	(	I2CLLD_Handle	handle,
		I2C_ExtendedParams *	extendedParams,
		uint32_t	timeout
	)

API to initiate the read transaction in polled mode.

Parameters

handle	[IN] Handle to the I2C instance used
extendedParams	[IN] Pointer to structure containing transfer parameters
timeout	[IN] Timeout for read operation in Micro Seconds I2cTimeoutValues

Returns: I2C_StatusCode

◆ I2C_lld_readIntr()

int32_t I2C_lld_readIntr	(	I2CLLD_Handle	handle,
		I2C_ExtendedParams *	extendedParams
	)

API to initiate the read transaction in Interrupt mode.

Parameters

handle	[IN] Handle to the I2C instance used
extendedParams	[IN] Pointer to structure containing transfer parameters

Returns: I2C_StatusCode

◆ I2C_lld_mem_write()

int32_t I2C_lld_mem_write	(	I2CLLD_Handle	handle,
		I2C_Memory_ExtendedParams *	mem_extendedParams,
		uint32_t	timeout
	)

Function to initiate a transfer from I2C in interrupt mode.

Parameters

handle	[IN] Handle to the I2C instance used
mem_extendedParams	[IN] Pointer to structure containing transfer parameters
timeout	[IN] Timeout for read operation in Micro Seconds I2cTimeoutValues

Returns: I2C_StatusCode

◆ I2C_lld_mem_writeIntr()

int32_t I2C_lld_mem_writeIntr	(	I2CLLD_Handle	handle,
		I2C_Memory_ExtendedParams *	mem_extendedParams
	)

Function to initiate a transfer from I2C in interrupt mode.

Parameters

handle	[IN] Handle to the I2C instance used
mem_extendedParams	[IN] Pointer to structure containing transfer parameters

Returns: I2C_StatusCode

◆ I2C_lld_mem_read()

int32_t I2C_lld_mem_read	(	I2CLLD_Handle	handle,
		I2C_Memory_ExtendedParams *	mem_extendedParams,
		uint32_t	timeout
	)

Function to initiate a transfer from I2C in interrupt mode.

Parameters

handle	[IN] Handle to the I2C instance used
mem_extendedParams	[IN] Pointer to structure containing transfer parameters
timeout	[IN] Timeout for read operation in Micro Seconds I2cTimeoutValues

Returns: I2C_StatusCode

◆ I2C_lld_mem_readIntr()

int32_t I2C_lld_mem_readIntr	(	I2CLLD_Handle	handle,
		I2C_Memory_ExtendedParams *	mem_extendedParams
	)

Function to initiate a transfer from I2C in interrupt mode.

Parameters

handle	[IN] Handle to the I2C instance used
mem_extendedParams	[IN] Pointer to structure containing transfer parameters

Returns: I2C_StatusCode

◆ I2C_lld_transferPoll()

int32_t I2C_lld_transferPoll	(	I2CLLD_Handle	handle,
		I2CLLD_Message *	msg
	)

Function to initiate a transfer from I2C in polled mode.

Parameters

handle	[IN] Handle to the I2C instance used
msg	[IN] Pointer to the I2CLLD_Message structure that contains values for this specific transfer

Returns: I2C_StatusCode

◆ I2C_lld_transferIntr()

int32_t I2C_lld_transferIntr	(	I2CLLD_Handle	handle,
		I2CLLD_Message *	msg
	)

Function to initiate a transfer from I2C in interrupt mode.

Parameters

handle	[IN] Handle to the I2C instance used
msg	[IN] Pointer to the I2CLLD_Message structure that contains values for this specific transfer

Returns: I2C_StatusCode

◆ I2C_lld_targetTransferIntr()

int32_t I2C_lld_targetTransferIntr	(	I2CLLD_Handle	handle,
		I2CLLD_targetTransaction *	txn
	)

Function to initiate a transfer from I2C in target mode.

Parameters

handle	[IN] Handle to the I2C instance used
txn	[IN] Poiter to the I2CLLD_targetTransaction structure that contains values for this specific transfer

Returns: I2C_StatusCode

◆ I2C_lld_probe()

int32_t I2C_lld_probe	(	I2CLLD_Handle	handle,
		uint32_t	targetAddr
	)

Function to probe I2C.

Parameters

handle	[IN] handle to the I2C instance used
targetAddr	[IN] address of the target to probe

Returns: I2C_StatusCode

◆ I2C_lld_setBusFrequency()

int32_t I2C_lld_setBusFrequency	(	I2CLLD_Handle	handle,
		uint32_t	busFrequency
	)

Function to set the bus frequency.

Parameters

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

Returns: I2C_StatusCode

◆ I2C_lld_controllerIsr()

void I2C_lld_controllerIsr ( void * args )

This is the I2C Controller ISR and can be used as IRQ handler in Controller mode.

Parameters

args	[IN] Argument to the ISR

◆ I2C_lld_targetIsr()

void I2C_lld_targetIsr ( void * args )

This is the I2C Target ISR and can be used as IRQ handler in Target mode.

Parameters

args	[IN] Argument to the ISR

Introduction

Files

Data Structures

Functions

Typedefs

Return status

Timeout values

I2C Driver states

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

MACROS for the possible values of Memory Write/Read API parameter.

MACROS used to define the state of the I2C Driver State Machine

Macro Definition Documentation

◆ I2C_STS_SUCCESS

◆ I2C_STS_ERR

◆ I2C_STS_ERR_TIMEOUT

◆ I2C_STS_ERR_INVALID_PARAM

◆ I2C_STS_ERR_BUS_BUSY

◆ I2C_STS_ERR_NO_ACK

◆ I2C_STS_ERR_ARBITRATION_LOST

◆ I2C_NO_WAIT

◆ I2C_WAIT_FOREVER

◆ I2C_STATE_RESET

◆ I2C_STATE_IDLE

◆ I2C_STATE_BUSY

◆ I2C_STATE_ERROR

◆ I2C_100KHZ

◆ I2C_400KHZ

◆ I2C_MEM_ADDR_SIZE_8_BITS

◆ I2C_MEM_ADDR_SIZE_16_BITS

◆ I2C_WRITE_STATE

◆ I2C_READ_STATE

◆ I2C_TARGET_XFER_STATE

◆ I2C_TARGET_RESTART_STATE

Typedef Documentation

◆ I2C_Clock_getTicks

◆ I2C_Clock_usecToTicks

◆ I2C_Clock_uSleep

◆ I2C_lld_transferCompleteCallback

◆ I2C_lld_targetTransferCompleteCallback

◆ I2CLLD_Handle

Function Documentation

◆ I2C_lld_init()

◆ I2C_lld_deInit()

◆ I2C_lld_Transaction_init()

◆ I2C_lld_Message_init()

◆ I2C_lld_write()

◆ I2C_lld_writeIntr()

◆ I2C_lld_read()

◆ I2C_lld_readIntr()

◆ I2C_lld_mem_write()

◆ I2C_lld_mem_writeIntr()

◆ I2C_lld_mem_read()

◆ I2C_lld_mem_readIntr()

◆ I2C_lld_transferPoll()

◆ I2C_lld_transferIntr()

◆ I2C_lld_targetTransferIntr()

◆ I2C_lld_probe()

◆ I2C_lld_setBusFrequency()

◆ I2C_lld_controllerIsr()

◆ I2C_lld_targetIsr()