I2C driver APIs

Collaboration diagram for I2C driver APIs:

Data Structures
struct	I2CMSPM0_I2CPinCfg
	I2C Pin Configuration. More...
struct	I2CMSPM0_HWAttrs
	I2C Hardware attributes. More...
struct	I2CMSPM0_Object
	I2C Object. More...

Macros
#define	I2C_CONTROLLER_INTERRUPTS_MASK   0xFFFF
	I2C controller interrupt mask.

Detailed Description

Overview

Refer to ti_drivers_I2C_Overview for a complete description of APIs and examples of use.

The general I2C API is normally used in application code, e.g. I2C_open() is used instead of I2CMSPM0_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.

General Behavior

Before using the I2C:

• 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 Controller transmits a stop bit and remains enabled.

Power Management

The I2C 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() completes, either after success or error, I2C remains enabled, and the device can enter standby.
• After I2C_close() call: I2C is disabled
• If the device goes into idle during a transaction, the state of SDA is undefined in the time between the transaction completing and the device waking up. SCL will go low until the device wakes up and starts another transaction or releases the bus. If this is a problem for another device on the I2C bus, you can set a power constraint for PowerMSPM0_DISALLOW_IDLE before the transaction and release it when the transaction completes.

Supported Functions

Generic API Function	API Function	Description
I2C_init()	I2CMSPM0_initHw()	Initialize I2C driver
I2C_open()	I2C_open()	Initialize I2C HW and set system dependencies
I2C_close()	I2C_close()	Disable I2C HW and release system dependencies
I2C_transfer()	I2CSupport_primeTransfer()	Start I2C transfer

Note

All calls should go through the generic API.

Supported Bit Rates

• I2C_100kHz
• I2C_400kHz
• I2C_1000kHz

  Unsupported Functionality

The I2C driver currently does not support:

• Multi-controller mode
• I2C target 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 I2C transaction structure
i2cTrans.writeCount    = 0;
i2cTrans.writeBuf      = txBuf;
i2cTrans.readCount     = 10;
i2cTrans.readBuf       = rxBuf;
i2cTrans.targetAddress = 0x3C;

// Open I2C
handle = I2C_open(CONFIG_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(uintptr_t a0, uintptr_t 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 I2C transaction structure
    i2cTrans.writeCount    = 16;
    i2cTrans.writeBuf      = txBuffer;
    i2cTrans.readCount     = 0;
    i2cTrans.readBuf       = rxBuffer;
    i2cTrans.targetAddress = 0x3C;

    // Open I2C
    handle = I2C_open(CONFIG_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];           // Receive buffer 2
uint8_t txBuffer2[64];           // Transmit buffer 2
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(uintptr_t a0, uintptr_t 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 I2C transaction structure
    i2cTrans.writeCount    = 10;
    i2cTrans.writeBuf      = txBuffer;
    i2cTrans.readCount     = 0;
    i2cTrans.readBuf       = rxBuffer;
    i2cTrans.targetAddress = 0x3C;

    // Second transaction
    i2cTrans2.writeCount    = 32;
    i2cTrans2.writeBuf      = txBuffer2;
    i2cTrans2.readCount     = 0;
    i2cTrans2.readBuf       = rxBuffer2;
    i2cTrans2.targetAddress = 0x2E;

    // Open I2C
    handle = I2C_open(CONFIG_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