TI-RTOS Drivers  tidrivers_cc13xx_cc26xx_2_20_00_08
Data Structures | Macros | Typedefs | Enumerations | Functions
I2C.h File Reference

Detailed Description

I2C driver interface.

============================================================================

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

#include <ti/drivers/I2C.h>

Operation

The I2C driver operates as a master on a single-master 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 or SWI context, depending on the device).

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_Transaction i2cTransaction;
I2C_Params_init(&params);
params.transferCallbackFxn = someI2CCallbackFunction;
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 slave peripheral.

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

Implementation

This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a I2C_FxnTable.

The I2C driver interface module is joined (at link time) to a NULL-terminated array of I2C_Config data structures named I2C_config. I2C_config is implemented in the application with each entry being an instance of a I2C peripheral. Each entry in I2C_config contains a:

Instrumentation

The I2C driver interface produces log statements if instrumentation is enabled.

Diagnostics Mask Log details
Diags_USER1 basic operations performed
Diags_USER2 detailed operations performed

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
Include dependency graph for I2C.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  I2C_Transaction
 I2C transaction. More...
 
struct  I2C_Params
 I2C Parameters. More...
 
struct  I2C_FxnTable
 The definition of an 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...
 

Macros

#define I2C_CMD_RESERVED   32
 
#define I2C_STATUS_RESERVED   -32
 
#define I2C_STATUS_SUCCESS   0
 Successful status code returned by I2C_control(). More...
 
#define I2C_STATUS_ERROR   -1
 Generic error status code returned by I2C_control(). More...
 
#define I2C_STATUS_UNDEFINEDCMD   -2
 An error status code returned by I2C_control() for undefined command codes. More...
 

Typedefs

typedef struct I2C_ConfigI2C_Handle
 A handle that is returned from a I2C_open() call. More...
 
typedef struct I2C_Transaction I2C_Transaction
 I2C transaction. More...
 
typedef enum I2C_TransferMode I2C_TransferMode
 I2C transfer mode. More...
 
typedef void(* I2C_CallbackFxn) (I2C_Handle, I2C_Transaction *, bool)
 I2C callback function. More...
 
typedef enum I2C_BitRate I2C_BitRate
 I2C bitRate. More...
 
typedef struct I2C_Params I2C_Params
 I2C Parameters. More...
 
typedef void(* I2C_CancelFxn) (I2C_Handle handle)
 A function pointer to a driver-specific implementation of I2C_cancel(). More...
 
typedef void(* I2C_CloseFxn) (I2C_Handle handle)
 A function pointer to a driver-specific implementation of I2C_close(). More...
 
typedef int(* I2C_ControlFxn) (I2C_Handle handle, unsigned int 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, I2C_Params *params)
 A function pointer to a driver-specific implementation of I2C_open(). More...
 
typedef bool(* I2C_TransferFxn) (I2C_Handle handle, I2C_Transaction *transaction)
 A function pointer to a driver-specific implementation of I2C_transfer(). More...
 
typedef struct I2C_FxnTable I2C_FxnTable
 The definition of an I2C function table that contains the required set of functions to control a specific I2C driver implementation. More...
 
typedef struct I2C_Config I2C_Config
 I2C global configuration. More...
 

Enumerations

enum  I2C_TransferMode {
  I2C_MODE_BLOCKING,
  I2C_MODE_CALLBACK
}
 I2C transfer mode. More...
 
enum  I2C_BitRate {
  I2C_100kHz = 0,
  I2C_400kHz = 1
}
 I2C bitRate. More...
 

Functions

void I2C_cancel (I2C_Handle handle)
 Cancel all I2C transfers. More...
 
void I2C_close (I2C_Handle handle)
 Close an I2C peripheral specified by an I2C handle. More...
 
int I2C_control (I2C_Handle handle, unsigned int cmd, void *arg)
 Perform implementation specific features on a given I2C_Handle. More...
 
void I2C_init (void)
 Initializes the I2C module. More...
 
I2C_Handle I2C_open (unsigned int index, I2C_Params *params)
 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)
 Initialize an I2C_Params struct to its defaults. More...
 
bool I2C_transfer (I2C_Handle handle, I2C_Transaction *transaction)
 Perform an I2C transaction with an I2C slave peripheral. More...
 

Typedef Documentation

typedef struct I2C_Config* I2C_Handle

A handle that is returned from a I2C_open() call.

I2C transaction.

This structure defines the nature of the I2C transaction. This structure specifies the buffer and buffer's size that is to be written to or read from the I2C slave peripheral. 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.

I2C transfer mode.

I2C_MODE_BLOCKING blocks task execution while an I2C transfer is in progress I2C_MODE_CALLBACK does not block task execution; but calls a callback function when the I2C transfer has completed

typedef void(* I2C_CallbackFxn) (I2C_Handle, I2C_Transaction *, bool)

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.

Parameters
I2C_HandleI2C_Handle
I2C_Transaction*Address of the I2C_Transaction performed
boolResults of the I2C transaction
typedef enum I2C_BitRate I2C_BitRate

I2C bitRate.

Specify one of the standardized I2C bus bit rates for I2C communications. The default is I2C_100kHz.

typedef struct I2C_Params I2C_Params

I2C Parameters.

I2C parameters are used with the I2C_open() call. Default values for these parameters are set using I2C_Params_init().

If I2C_TransferMode is set to I2C_MODE_BLOCKING then I2C_transfer function calls will block thread execution until the transaction has completed.

If I2C_TransferMode is set to I2C_MODE_CALLBACK then I2C_transfer will not block thread execution and it will call the function specified by transferCallbackFxn. Sequential calls to I2C_transfer in I2C_MODE_CALLBACK mode will put the designated transaction onto an internal queue that automatically starts queued transactions after the previous transaction has completed. This queuing occurs regardless of error state.

I2C_BitRate specifies the I2C bus rate used for I2C communications.

See also
I2C_Params_init()
typedef void(* I2C_CancelFxn) (I2C_Handle handle)

A function pointer to a driver-specific implementation of I2C_cancel().

typedef void(* I2C_CloseFxn) (I2C_Handle handle)

A function pointer to a driver-specific implementation of I2C_close().

typedef int(* I2C_ControlFxn) (I2C_Handle handle, unsigned int 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, I2C_Params *params)

A function pointer to a driver-specific implementation of I2C_open().

typedef bool(* I2C_TransferFxn) (I2C_Handle handle, I2C_Transaction *transaction)

A function pointer to a driver-specific implementation of I2C_transfer().

typedef struct I2C_FxnTable I2C_FxnTable

The definition of an I2C function table that contains the required set of functions to control a specific I2C driver implementation.

typedef struct I2C_Config I2C_Config

I2C global configuration.

The I2C_Config structure contains a set of pointers used to characterize the I2C driver implementation.

This structure needs to be defined before calling I2C_init() and it must not be changed thereafter.

See also
I2C_init()

Enumeration Type Documentation

I2C transfer mode.

I2C_MODE_BLOCKING blocks task execution while an 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

I2C bitRate.

Specify one of the standardized I2C bus bit rates for I2C communications. The default is I2C_100kHz.

Enumerator
I2C_100kHz 
I2C_400kHz 

Function Documentation

void I2C_cancel ( I2C_Handle  handle)

Cancel all I2C transfers.

This function will cancel asynchronous I2C_transfer() operations, and is applicable only for I2C_MODE_CALLBACK. An in progress transfer, as well as any queued transfers will be canceled. The individual callback functions for each transfer will be called from the context that I2C_cancel is called.

Precondition
I2C_Transfer() has been called.
Parameters
handleAn I2C_Handle returned from I2C_open
Note
Different I2C slave devices will behave differently when an in-progress transfer fails and needs to be canceled. The slave may need to be reset, or there may be other slave-specifc steps that can be used to successfully resume communication.
See also
I2C_transfer()
void I2C_close ( I2C_Handle  handle)

Close an I2C peripheral specified by an I2C handle.

Precondition
I2C_open() has been called.
Parameters
handleA I2C_Handle returned from I2C_open
See also
I2C_open()
int I2C_control ( I2C_Handle  handle,
unsigned int  cmd,
void *  arg 
)

Perform implementation specific features on a given I2C_Handle.

Commands for I2C_control can originate from I2C.h or from implementation specific I2C*.h (I2CCC26XX.h, I2CTiva.h, etc.. ) files. While commands from I2C.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific I2C*.h files add unique driver capabilities but are not API portable across all I2C driver implementations.

Commands supported by I2C.h follow a I2C_CMD_<cmd> naming convention.
Commands supported by I2C*.h follow a I2C*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See I2C_control command codes for command codes.

See I2C_control return status codes for status codes.

Precondition
I2C_open() has to be called first.
Parameters
handleA I2C handle returned from I2C_open()
cmdI2C.h or I2C*.h command.
argAn optional R/W (read/write) command argument accompanied with cmd
Returns
Implementation specific return codes. Negative values indicate unsuccessful operations.
See also
I2C_open()
void I2C_init ( void  )

Initializes the I2C module.

Precondition
The I2C_config structure must exist and be persistent before this function can be called. This function must also be called before any other I2C driver APIs. This function call does not modify any peripheral registers.
I2C_Handle I2C_open ( unsigned int  index,
I2C_Params params 
)

Initialize a given I2C peripheral specified by the particular index value. The parameter specifies which mode the I2C will operate.

Precondition
I2C controller has been initialized
Parameters
indexLogical peripheral number for the I2C indexed into the I2C_config table
paramsPointer to a parameter block. Default values will be used if NULL is specified. All the fields in this structure are are considered RO (read-only).
Returns
A I2C_Handle on success or a NULL on an error or if it has been opened already.
See also
I2C_init()
I2C_close()
void I2C_Params_init ( I2C_Params params)

Initialize an I2C_Params struct to its defaults.

Parameters
paramsA pointer to I2C_Params structure for initialization

Defaults values are: transferMode = I2C_MODE_BLOCKING transferCallbackFxn = NULL bitRate = I2C_100kHz

bool I2C_transfer ( I2C_Handle  handle,
I2C_Transaction transaction 
)

Perform an I2C transaction with an I2C slave peripheral.

This function will start an 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. Any data to be written will always be 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, the I2C_transfer will block task execution until the transaction completes.

In I2C_MODE_CALLBACK, the I2C_transfer does not block task execution. A callback function (specified by transferCallbackFxn) is called when the transfer completes. Success or failure of the transaction is reported via the callback function's bool argument. If a transfer is already in progress, the new 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!

Parameters
handleA I2C_Handle
transactionA pointer to an I2C_Transaction. All of the fields within transaction should be considered write only, unless otherwise noted in the driver implementation.
Returns
In I2C_MODE_BLOCKING: true for a successful transfer; false for an error (for example, an I2C bus fault (NACK)). In I2C_MODE_CALLBACK: always true. The transferCallbackFxn's bool argument will be true to indicate success, and false on an error.
See also
I2C_open
Copyright 2016, Texas Instruments Incorporated