TI-RTOS for SimpleLink Wireless MCUs
2.14.01.20
|
I2C driver interface.
============================================================================
The I2C header file should be included in an application as follows:
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 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.
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.
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:
Currently the following I2C peripheral implementations are supported:
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>
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 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... | |
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_Config * | I2C_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_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 a 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_close (I2C_Handle handle) |
Function to close a I2C peripheral specified by the I2C handle. More... | |
int | I2C_control (I2C_Handle handle, unsigned int 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 (unsigned int index, 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... | |
bool | I2C_transfer (I2C_Handle handle, I2C_Transaction *transaction) |
Function that handles the I2C transfer for SYS/BIOS. More... | |
#define I2C_CMD_RESERVED 32 |
#define I2C_STATUS_RESERVED -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 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 -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 -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.
typedef struct I2C_Config* I2C_Handle |
A handle that is returned from a I2C_open() call.
typedef struct I2C_Transaction I2C_Transaction |
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.
typedef enum I2C_TransferMode 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
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.
I2C_Handle | I2C_Handle |
I2C_Transaction* | Address of the I2C_Transaction performed |
bool | Results 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 to 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. (regardless of error state).
I2C_BitRate specifies the I2C bus rate used for I2C communications.
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 a 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.
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 | handle | ) |
Function to close a I2C peripheral specified by the I2C handle.
handle | A I2C_Handle returned from I2C_open |
int I2C_control | ( | I2C_Handle | handle, |
unsigned int | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given I2C_Handle.
handle | 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 | ( | unsigned int | index, |
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.
index | 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
bool I2C_transfer | ( | I2C_Handle | handle, |
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!
handle | 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. |