PDK API Guide for J721E
|
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) |
#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 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.
#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.
#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.
#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.
#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 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.
#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.
#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.
#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.
#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.
#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.
#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.
#define I2C_STS_ERR_BUS_BUSY (-(int16_t)(2)) |
I2C bus busy error.
#define I2C_STS_ERR_NO_ACK (-(int16_t)(3)) |
I2C no ack error when no acknowledgement is received.
#define I2C_STS_ERR_ARBITRATION_LOST (-(int16_t)(4)) |
I2C Arbitration lost error.
#define I2C_STS_ERR_ACCESS_ERROR (-(int16_t)(5)) |
I2C Bus Access error.
#define I2C_STS_ERR_COMMAND_FAILURE (-(int16_t)(6)) |
I2C FW Command Access Failure.
#define I2C_STS_ERR_INVALID_COMMAND (-(int16_t)(7)) |
I2C FW Invalid Command passed.
#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
#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.
#define I2C_WAIT_FOREVER (~((uint32_t)0U)) |
#define I2C_MAX_CONFIG_CNT (14U) |
typedef struct I2C_Config_s* I2C_Handle |
A handle that is returned from a I2C_open() call.
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.
I2C_Handle | I2C_Handle |
I2C_Transaction* | Address of the I2C_Transaction performed |
bool | Results of the I2C transaction |
typedef void(* I2C_CloseFxn) (I2C_Handle handle) |
A function pointer to a driver specific implementation of I2C_close().
typedef int32_t(* I2C_ControlFxn) (I2C_Handle handle, uint32_t cmd, void *arg) |
A function pointer to a driver specific implementation of I2C_control().
typedef void(* I2C_InitFxn) (I2C_Handle handle) |
A function pointer to a driver specific implementation of I2C_init().
typedef I2C_Handle(* I2C_OpenFxn) (I2C_Handle handle, const I2C_Params *params) |
A function pointer to a driver specific implementation of I2C_open().
typedef int16_t(* I2C_TransferFxn) (I2C_Handle handle, I2C_Transaction *transaction) |
A function pointer to a driver specific implementation of I2C_transfer().
typedef I2C_Config I2C_config_list[I2C_MAX_CONFIG_CNT] |
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 |
enum I2C_BitRate |
void I2C_close | ( | I2C_Handle | i2cHnd | ) |
Function to close a I2C peripheral specified by the I2C handle.
i2cHnd | A I2C_Handle returned from I2C_open |
int32_t I2C_control | ( | I2C_Handle | i2cHnd, |
uint32_t | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given I2C_Handle.
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 |
void I2C_init | ( | void | ) |
Function to initializes the I2C module.
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.
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). |
void I2C_Params_init | ( | I2C_Params * | params | ) |
Function to initialize the I2C_Params struct to its defaults.
params | An pointer to I2C_Params structure for initialization |
Defaults values are: transferMode = I2C_MODE_BLOCKING transferCallbackFxn = NULL bitRate = I2C_100kHz
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!
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. |
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;
void I2C_transactionInit | ( | I2C_Transaction * | transaction | ) |