AM261x MCU+ SDK: APIs for I2C HLD

| AM261x MCU+ SDK 26.00.00 |

Data Structures | Functions | Typedefs
APIs for I2C HLD
APIs for SOC Specific Device Drivers

## Introduction

This file containing the I2C API.

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

#include <drivers/i2c.h>

# 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

I2C_Handle handle;
I2C_Params params;
I2C_Params_init(&params);
params.transferMode = I2C_MODE_BLOCKING;
I2C_init();
handle = I2C_open(someI2C_configIndexValue, &params);
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.

I2C_Transaction i2cTransaction;
I2C_Transaction_init(&i2cTransaction);
i2cTransaction.writeBuf = someWriteBuffer;
i2cTransaction.writeCount = numOfBytesToWrite;
i2cTransaction.readBuf = someReadBuffer;
i2cTransaction.readCount = numOfBytesToRead;
i2cTransaction.targetAddress = some7BitI2CTargetAddress;
ret = I2C_transfer(handle, &i2cTransaction);
if (!ret) {
System_printf("Unsuccessful I2C transfer");
}

## Data Structures
struct | I2C_HwAttrs
| I2C Hardware attributes. More...
struct | I2C_Mem_Transaction
| I2C Memory Transaction. More...
struct | I2C_Transaction
| I2C Transaction. More...
struct | I2C_Params
| I2C Parameters. More...
struct | I2C_Object
| I2C Object. More...
struct | I2C_Config
| I2C Global configuration. More...

## Functions
void | I2C_init (void)
| Initialize the I2C module. More...
void | I2C_deinit (void)
| De-nitialize the I2C module. More...
void | I2C_Params_init (I2C_Params *params)
| API to set default values of I2C_Params in params. More...
I2C_Handle | I2C_open (uint32_t idx, const I2C_Params *params)
| API to Open I2C at index idx with parameters params. More...
void | I2C_close (I2C_Handle handle)
| API to close the I2C instance specified by the handle passed. More...
void | I2C_Memory_Transaction_init (I2C_Mem_Transaction *memTransaction)
| API to set default values of I2C_Mem_Transaction in memTransaction. More...
void | I2C_Transaction_init (I2C_Transaction *transaction)
| API to set default values of I2C_Transaction in transaction. More...
int32_t | I2C_transfer (I2C_Handle handle, I2C_Transaction *transaction)
| API to initiate a transfer from I2C Instance. More...
int32_t | I2C_memory_transfer (I2C_Handle handle, I2C_Mem_Transaction *transaction)
| API to initiate a memory transfer from I2C Instance. More...
int32_t | I2C_probe (I2C_Handle handle, uint32_t targetAddr)
| API to probe I2C Device. More...
int32_t | I2C_setBusFrequency (I2C_Handle handle, uint32_t busFrequency)
| API to set the bus frequency of I2C Instance. More...
I2C_Handle | I2C_getHandle (uint32_t index)
| API to get the handle of an open I2C instance from the instance index. More...

## 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, int32_t transferStatus)
| I2C Callback Function. More...

## MACROS used to select the 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
#define | I2C_MODE_BLOCKING ((uint8_t) 0U)
#define | I2C_MODE_CALLBACK ((uint8_t) 1U)

## MACROS for the possible values of I2C_Mem_Transaction member
memDataDir. Deafults to I2C_TXN_DIR_INVALID
#define | I2C_MEM_TXN_DIR_INVALID ((uint8_t) 0U)
| I2C LLD invalid dataDir. More...
#define | I2C_MEM_TXN_DIR_TX ((uint8_t) 1U)
| I2C LLD Write. More...
#define | I2C_MEM_TXN_DIR_RX ((uint8_t) 2U)
| I2C LLD Read. More...

## Macro Definition Documentation

## ◆ I2C_MODE_BLOCKING

#define I2C_MODE_BLOCKING ((uint8_t) 0U)

## ◆ I2C_MODE_CALLBACK

#define I2C_MODE_CALLBACK ((uint8_t) 1U)

## ◆ I2C_MEM_TXN_DIR_INVALID

#define I2C_MEM_TXN_DIR_INVALID ((uint8_t) 0U)

I2C LLD invalid dataDir.

## ◆ I2C_MEM_TXN_DIR_TX

#define I2C_MEM_TXN_DIR_TX ((uint8_t) 1U)

I2C LLD Write.

## ◆ I2C_MEM_TXN_DIR_RX

#define I2C_MEM_TXN_DIR_RX ((uint8_t) 2U)

I2C LLD Read.

## 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, int32_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 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

## Function Documentation

## ◆ I2C_init()

void I2C_init | ( | void |  | ) |

Initialize the I2C module.

## ◆ I2C_deinit()

void I2C_deinit | ( | void |  | ) |

De-nitialize the I2C module.

## ◆ I2C_Params_init()

void I2C_Params_init | ( | I2C_Params * | params | ) |

API to set default values of I2C_Params in params.

Parameters

  params | [IN] pointer to the structure to be initialized

## ◆ I2C_open()

I2C_Handle I2C_open | ( | uint32_t | idx,
|  | const I2C_Params * | params
| ) |  |

API to Open 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_close()

void I2C_close | ( | I2C_Handle | handle | ) |

API to close the I2C instance specified by the handle passed.

Precondition
  I2C_open() has to be called first

Parameters

  handle | [IN] I2C_Handle returned from I2C_open()

See also
  I2C_open()

## ◆ I2C_Memory_Transaction_init()

void I2C_Memory_Transaction_init | ( | I2C_Mem_Transaction * | memTransaction | ) |

API to set default values of I2C_Mem_Transaction in memTransaction.

Parameters

  memTransaction | [IN] pointer to the structure to be initialized

## ◆ I2C_Transaction_init()

void I2C_Transaction_init | ( | I2C_Transaction * | transaction | ) |

API to set default values of I2C_Transaction in transaction.

Parameters

  transaction | [IN] pointer to the structure to be initialized

## ◆ I2C_transfer()

int32_t I2C_transfer | ( | I2C_Handle | handle,
|  | I2C_Transaction * | transaction
| ) |  |

API to initiate a transfer from I2C Instance.

Parameters

  handle | [IN] handle to the I2C Instance
  transaction | [IN] I2C_Transaction structure that contains values for this specific transfer

Returns
  SystemP_SUCCESS if successful; else error on failure

## ◆ I2C_memory_transfer()

int32_t I2C_memory_transfer | ( | I2C_Handle | handle,
|  | I2C_Mem_Transaction * | transaction
| ) |  |

API to initiate a memory transfer from I2C Instance.

Parameters

  handle | [IN] handle to the I2C Instance
  transaction | [IN] I2C_Mem_Transaction structure that contains values for this memory transfer

Returns
  SystemP_SUCCESS if successful; else error on failure

## ◆ I2C_probe()

int32_t I2C_probe | ( | I2C_Handle | handle,
|  | uint32_t | targetAddr
| ) |  |

API to probe I2C Device.

Parameters

  handle | [IN] handle to the I2C Instance
  targetAddr | [IN] address of the target to probe

Returns
  SystemP_SUCCESS if successful; else error on failure

## ◆ I2C_setBusFrequency()

int32_t I2C_setBusFrequency | ( | I2C_Handle | handle,
|  | uint32_t | busFrequency
| ) |  |

API to set the bus frequency of I2C Instance.

Parameters

  handle | [IN] handle to the I2C
  busFrequency | [IN] frequency value to be set

Returns
  SystemP_SUCCESS if successful; else error on failure

## ◆ I2C_getHandle()

I2C_Handle I2C_getHandle | ( | uint32_t | index | ) |

API to get 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

I2C_Params_init
void I2C_Params_init(I2C_Params *params)
API to set default values of I2C_Params in params.
I2C_MODE_BLOCKING
#define I2C_MODE_BLOCKING
Definition: i2c.h:136
I2C_Transaction::writeBuf
const void * writeBuf
Definition: i2c.h:233
I2C_Handle
struct I2C_Config_s * I2C_Handle
A handle that is returned from a I2C_open() call.
Definition: i2c.h:165
I2C_transfer
int32_t I2C_transfer(I2C_Handle handle, I2C_Transaction *transaction)
API to initiate a transfer from I2C Instance.
I2C_Transaction::targetAddress
uint32_t targetAddress
Definition: i2c.h:247
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.
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
I2C_Params::transferMode
uint8_t transferMode
Definition: i2c.h:290
I2C_init
void I2C_init(void)
Initialize the I2C module.