Detailed Description

I2C driver implementation for a CC26XX I2C controller.

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

Driver Include

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

Refer to I2C.h for a complete description of APIs.

Overview

The general I2C API is normally used in application code, e.g. I2C_open() is used instead of I2CCC26XX_open(). The board file will define the device specific config, and casting in the general API will ensure that the correct device specific functions are called. This is also reflected in the example code in Use Cases.

General Behavior

Before using the I2C in CC26XX:

The I2C driver is initialized by calling I2C_init().
The I2C HW is configured and system dependencies are declared (e.g. IOs, power, etc.) by calling I2C_open().

The following is true for receive operation:

RX is enabled by calling I2C_transfer(). The readCount of the I2C_Transaction must be set to a non-zero value.
If the I2C_transfer() succeeds, the I2C remains enabled.
The application must check the return value from I2C_transfer() to verify that the transfer succeeded.

The following apply for transmit operation:

TX is enabled by calling I2C_transfer(). The writeCount of the I2C_Transaction must be set to a non-zero value.
If the I2C_transfer() succeeds, the I2C remains enabled.
The application must check the return value from I2C_transfer() to verify that the transfer succeeded.

After I2C operation has ended:

Release system dependencies for I2C by calling I2C_close().

Error handling

If an error occurs during operation:

The I2C Master transmits a stop bit and remains enabled.

Power Management

The I2CCC26XX driver sets a power constraint during transactions to keep the device out of standby; so when all tasks are blocked, the device will enter idle mode instead of standby. When the transactions have finished, the power constraint to prohibit standby is released. The following statements are valid:

After I2C_open() call: I2C is enabled, there are no active I2C transactions, the device can enter standby.
After I2C_transfer() call: active I2C transactions exist, the device might enter idle, but not standby.
When I2C_transfer() returns, either after success or error, I2C remains enabled, and the device can enter standby.
After I2C_close() call: I2C is disabled

Supported Functions

Generic API Function	API Function	Description
I2C_init()	I2CCC26XX_init()	Initialize I2C driver
I2C_open()	I2CCC26XX_open()	Initialize I2C HW and set system dependencies
I2C_close()	I2CCC26XX_close()	Disable I2C HW and release system dependencies
I2C_transfer()	I2CCC26XX_transfer()	Start I2C transfer

Note: All calls should go through the generic API.

Unsupported Functionality

The CC26XX I2C driver currently does not support:

Multi-master mode
I2C slave mode

Use Cases

Basic Receive

Receive 10 bytes over I2C in I2C_MODE_BLOCKING.

// Locals
I2C_Handle handle;
I2C_Params params;
I2C_Transaction i2cTrans;
uint8_t rxBuf[32];      // Receive buffer
uint8_t txBuf[32];      // Transmit buffer
// Configure I2C parameters.
I2C_Params_init(&params);
// Initialize master I2C transaction structure
i2cTrans.writeCount   = 0;
i2cTrans.writeBuf     = txBuf;
i2cTrans.readCount    = 10;
i2cTrans.readBuf      = rxBuf;
i2cTrans.slaveAddress = 0x3C;
// Open I2C
handle = I2C_open(Board_I2C, &params);
// Do I2C transfer receive
I2C_transfer(handle, &i2cTrans);

Basic Transmit

Transmit 16 bytes over I2C in I2C_MODE_CALLBACK.

uint8_t rxBuffer[32];            // Receive buffer
uint8_t txBuffer[32];            // Transmit buffer
bool transferDone = false;
static void transferCallback(I2C_Handle handle, I2C_Transaction *transac, bool result)
{
    // Set length bytes
    if (result) {
        transferDone = true;
    } else {
        // Transaction failed, act accordingly...
        .
        .
    }
}
static void taskFxn(UArg a0, UArg a1)
{
    // Locals
    I2C_Handle handle;
    I2C_Params params;
    I2C_Transaction i2cTrans;
    // Configure I2C parameters.
    I2C_Params_init(&params);
    params.transferMode = I2C_MODE_CALLBACK;
    params.transferCallbackFxn = transferCallback;
    // Prepare data to send, send 0x00, 0x01, 0x02, ...0xFF, 0x00, 0x01...
    for(uint32_t i = 0; i < numTxBytes; i++)
        txBuffer[i] = (uint8_t) i;
    // Initialize master I2C transaction structure
    i2cTrans.writeCount   = 16;
    i2cTrans.writeBuf     = txBuffer;
    i2cTrans.readCount    = 0;
    i2cTrans.readBuf      = rxBuffer;
    i2cTrans.slaveAddress = 0x3C;
    // Open I2C
    handle = I2C_open(Board_I2C, &params);
    // Do I2C transfer (in callback mode)
    I2C_transfer(handle, &i2cTrans);
    // Do other stuff while I2C is handling the transfer
    .
    .
    // Do something if I2C transfer is finished
    if(transferDone) {
        .
        .
    }
    // Continue...
    .
    .
}

Chained Transactions

Transmit 10 bytes and then 32 bytes over I2C in I2C_MODE_CALLBACK.

uint8_t rxBuffer[32];            // Receive buffer
uint8_t txBuffer[32];            // Transmit buffer
uint8_t rxBuffer2[64];           // 2. Receive buffer
uint8_t txBuffer2[64];           // 2. Transmit buffer
bool transferDone = false;
static void writeCallbackDefault(I2C_Handle handle, I2C_Transaction *transac, bool result)
{
    // Set length bytes
    if (result) {
        transferDone = true;
    } else {
        // Transaction failed, act accordingly...
        .
        .
    }
}
static void taskFxn(UArg a0, UArg a1)
{
    // Locals
    I2C_Handle handle;
    I2C_Params params;
    I2C_Transaction i2cTrans;
    I2C_Transaction i2cTrans2;
    // Configure I2C parameters.
    I2C_Params_init(&params);
    params.transferMode = I2C_MODE_CALLBACK;
    params.transferCallbackFxn = writeCallbackDefault;
    // Prepare data to send, send 0x00, 0x01, 0x02, ...0xFF, 0x00, 0x01...
    for(uint32_t i = 0; i < numTxBytes; i++)
        txBuffer[i] = (uint8_t) i;
    // Initialize first master I2C transaction structure
    i2cTrans.writeCount   = 10;
    i2cTrans.writeBuf     = txBuffer;
    i2cTrans.readCount    = 0;
    i2cTrans.readBuf      = rxBuffer;
    i2cTrans.slaveAddress = 0x3C;
    // Second transaction
    i2cTrans2.writeCount   = 32;
    i2cTrans2.writeBuf     = txBuffer2;
    i2cTrans2.readCount    = 0;
    i2cTrans2.readBuf      = rxBuffer2;
    i2cTrans2.slaveAddress = 0x2E;
    // Open I2C
    handle = I2C_open(Board_I2C, &params);
    // Do chained I2C transfers (in callback mode).
    I2C_transfer(handle, &i2cTrans);
    I2C_transfer(handle, &i2cTrans2);
    // Do other stuff while I2C is handling the transfers
    .
    .
    // Do something if I2C transfers are finished
    if(transferDone) {
        .
        .
    }
    // Continue...
    .
    .
}

Instrumentation

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

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

#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/I2C.h>
#include <ti/drivers/pin/PINCC26XX.h>
#include <ti/drivers/Power.h>
#include <ti/sysbios/family/arm/m3/Hwi.h>
#include <ti/sysbios/knl/Swi.h>
#include <ti/sysbios/knl/Semaphore.h>

Include dependency graph for I2CCC26XX.h:

Go to the source code of this file.

Data Structures
struct	I2CCC26XX_I2CPinCfg
	I2CCC26XX Pin Configuration. More...

struct	I2CCC26XX_HWAttrsV1
	I2CCC26XX Hardware attributes. More...

struct	I2CCC26XX_Object
	I2CCC26XX Object. More...

Macros
#define	ti_sysbios_family_arm_m3_Hwi__nolocalnames

Typedefs
typedef unsigned long	I2CBaseAddrType

typedef unsigned long	I2CDataType

typedef struct I2CCC26XX_I2CPinCfg	I2CCC26XX_I2CPinCfg
	I2CCC26XX Pin Configuration. More...

typedef enum I2CCC26XX_Mode	I2CCC26XX_Mode
	I2CCC26XX mode. More...

typedef struct I2CCC26XX_HWAttrsV1	I2CCC26XX_HWAttrsV1
	I2CCC26XX Hardware attributes. More...

typedef struct I2CCC26XX_Object	I2CCC26XX_Object
	I2CCC26XX Object. More...

Enumerations
enum	I2CCC26XX_Mode { I2CCC26XX_IDLE_MODE = 0, I2CCC26XX_WRITE_MODE, I2CCC26XX_READ_MODE, I2CCC26XX_BUSBUSY_MODE, I2CCC26XX_ERROR = 0xFF }
	I2CCC26XX mode. More...

Variables
const I2C_FxnTable	I2CCC26XX_fxnTable

Macro Definition Documentation

#define ti_sysbios_family_arm_m3_Hwi__nolocalnames

Typedef Documentation

typedef unsigned long I2CBaseAddrType

I2C Base Address type.

typedef unsigned long I2CDataType

typedef struct I2CCC26XX_I2CPinCfg I2CCC26XX_I2CPinCfg

I2CCC26XX Pin Configuration.

Pin configuration that holds non-default pins. The default pin configuration is typically defined in I2CCC26XX_HWAttrsV1 placed in the board file. The pin configuration structure is used by setting the custom void pointer in the I2C_Params to point to this struct. If the custom void pointer is NULL, the I2CCC26XX_HWAttrsV1 pin mapping will be used.

 I2C_Handle handle;
 I2C_Params i2cParams;
 I2CCC26XX_I2CPinCfg pinCfg;
 
 I2C_Params_init(&i2cParams);     // sets custom to NULL
 pinCfg.pinSDA = Board_I2C0_SDA1;
 pinCfg.pinSCL = Board_I2C0_SCL1;
 i2cParams.custom = &pinCfg;
 
 handle = I2C_open(Board_I2C, &i2cParams);

typedef enum I2CCC26XX_Mode I2CCC26XX_Mode

I2CCC26XX mode.

This enum defines the state of the I2C driver's state-machine. Do not modify.

typedef struct I2CCC26XX_HWAttrsV1 I2CCC26XX_HWAttrsV1

I2CCC26XX Hardware attributes.

These fields, with the exception of intPriority, are used by driverlib APIs and therefore must be populated by driverlib macro definitions. For cc26xxware these definitions are found in:

inc/hw_memmap.h
inc/hw_ints.h

intPriority is the I2C peripheral's interrupt priority, as defined by the underlying OS. It is passed unmodified to the underlying OS's interrupt handler creation code, so you need to refer to the OS documentation for usage. For example, for SYS/BIOS applications, refer to the ti.sysbios.family.arm.m3.Hwi documentation for SYS/BIOS usage of interrupt priorities.

A sample structure is shown below:

 const I2CCC26XX_HWAttrsV1 i2cCC26XXHWAttrs[] = {
     {
        .baseAddr = I2C0_BASE,
        .powerMngrId = PERIPH_I2C0,
        .intNum = INT_I2C,
        .intPriority = ~0,
        .swiPriority = 0,
        .sdaPin = Board_I2C_SDA,
        .sclPin = Board_I2C_SCL,
     },
 };

typedef struct I2CCC26XX_Object I2CCC26XX_Object

I2CCC26XX Object.

The application must not access any member variables of this structure!

Enumeration Type Documentation

enum I2CCC26XX_Mode