AM261x MCU+ SDK: I2C High Level Driver

| AM261x MCU+ SDK 26.00.00 |

I2C High Level Driver

# Features Supported

- Controller and Target mode of Operation
- Interrupt, Polled Mode
- Blocking and Non-blocking (Callback) Transfers
- Queueing of I2C transactions
- I2C Bus Recovery

# SysConfig Features

Note
  It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.

SysConfig can be used to configure below parameters apart from common configuration like Clock,MPU,RAT and others.

- I2C module configuration parameters like bitrate, Own target address, Clock Source.
- I2C instances and pin Configurations.
- Interrupt Mode enable option. If disabled, gets configured to carry out transactions in Polling mode.
- Based on above parameters, the SysConfig generated code does below as part of Drivers_open and Drivers_close functions.
  - Set I2C instance parameter configuration.
  - Driver ISR registration if Interrupt Mode is enabled.

# Features NOT Supported

- DMA Mode Operation.

# Usage Overview

## API Sequence

To use the I2C HLD driver to transmit/receive data over the I2C bus, probe target and set bus frequency the application may call the following APIs:

- I2C_open(): Open an I2C HLD Instance.
- I2C_close(): Close an I2C HLD Instance.
- I2C_Memory_Transaction_init(): Fill Default Value in Memory Transaction object.
- I2C_Transaction_init(): Fill Default Value in Transaction object.
- I2C_transfer(): Initiate an I2C Transaction.
- I2C_memory_transfer(): Initiate an I2C Memory Transaction.
- I2C_probe(): Probe I2C Target.
- I2C_setBusFrequency(): Set Bus frequency.
- I2C_getHandle(): Get I2C Handle from index.

## Initializing the I2C HLD Driver

I2C_init() must be called before any other I2C Open is called.

I2C_open() must be called before calling any I2C APIs. This function takes index and params to initialize an instance and returns the handle to the I2C instance.

Calling I2C_close() closes the instance passed.

Please note that the initialization of I2C HLD instances is taken care by the SysConfig generated code.

# Example Usage

Include the below file to access the APIs

#include <drivers/i2c.h>

Instance Open Example

I2C_Params params;
I2C_Params_init(&params);
params.transferMode = I2C_MODE_BLOCKING;
I2C_init();
gI2cHandle = I2C_open(CONFIG_I2C0, &params);
if (!gI2cHandle) {
DebugP_assert(FALSE);
}

Instance Close Example

I2C_close(gI2cHandle);

I2c Transfer Example

int32_t status;
I2C_Transaction i2cTransaction;
I2C_Transaction_init(&i2cTransaction);
i2cTransaction.writeBuf = txBuffer;
i2cTransaction.writeCount = 1U;
i2cTransaction.readBuf = rxBuffer;
i2cTransaction.readCount = 2U;
status = I2C_transfer(gI2cHandle, &i2cTransaction);
if (SystemP_SUCCESS != status) {
DebugP_assert(FALSE);
}

# API

APIs for I2C HLD

I2C_Params_init
void I2C_Params_init(I2C_Params *params)
API to set default values of I2C_Params in params.
FALSE
#define FALSE
Definition: os_defs.h:32
I2C_MODE_BLOCKING
#define I2C_MODE_BLOCKING
Definition: i2c.h:136
I2C_Transaction::writeBuf
const void * writeBuf
Definition: i2c.h:233
I2C_transfer
int32_t I2C_transfer(I2C_Handle handle, I2C_Transaction *transaction)
API to initiate a transfer from I2C Instance.
I2C_Transaction
I2C Transaction.
Definition: i2c.h:229
I2C_Params
I2C Parameters.
Definition: i2c.h:288
I2C_open
I2C_Handle I2C_open(uint32_t idx, const I2C_Params *params)
API to Open I2C at index idx with parameters params.
SystemP_SUCCESS
#define SystemP_SUCCESS
Return status when the API execution was successful.
Definition: SystemP.h:56
I2C_Transaction_init
void I2C_Transaction_init(I2C_Transaction *transaction)
API to set default values of I2C_Transaction in transaction.
I2C_Transaction::readBuf
void * readBuf
Definition: i2c.h:239
I2C_Transaction::writeCount
size_t writeCount
Definition: i2c.h:236
I2C_Transaction::readCount
size_t readCount
Definition: i2c.h:242
DebugP_assert
#define DebugP_assert(expression)
Function to call for assert check.
Definition: DebugP.h:187
I2C_close
void I2C_close(I2C_Handle handle)
API to close the I2C instance specified by the handle passed.
I2C_Params::transferMode
uint8_t transferMode
Definition: i2c.h:290
I2C_init
void I2C_init(void)
Initialize the I2C module.