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 controller or a target on a single-controller 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
handle =
I2C_open(someI2C_configIndexValue, ¶ms);
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 controller or target peripheral.
i2cTransaction.
writeBuf = someWriteBuffer;
i2cTransaction.
readBuf = someReadBuffer;
if (!ret) {
System_printf("Unsuccessful I2C transfer");
}
|
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) |
|
◆ I2C_MAX_NUM_OWN_TARGET_ADDR
#define I2C_MAX_NUM_OWN_TARGET_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
◆ 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) |
◆ I2C_Handle
◆ I2C_CallbackFxn
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 target 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 |
◆ I2C_init()
Initialize the I2C module.
◆ I2C_deinit()
De-nitialize the I2C module.
◆ I2C_Params_init()
Function to set default values of I2C_Params in params.
- Parameters
-
params | [IN] pointer to the structure to be initialized |
◆ I2C_open()
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()
Function to set default values of I2C_Transaction in transaction.
- Parameters
-
transaction | [IN] pointer to the structure to be initialized |
◆ I2C_transfer()
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 |
targetAddr |
|
) |
| |
Function to probe I2C.
- Parameters
-
handle | [IN] handle to the I2C |
targetAddr | [IN] address of the target 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 target |
- Returns
- I2C_StatusCode
◆ I2C_close()
Function to close the I2C.
- Parameters
-
handle | [IN] handle to the I2C |
◆ I2C_getHandle()
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