I2C.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2018, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       I2C.h
 *  @brief      Inter-Intergrated Circuit driver interface.
 *
 *  To use the I2C driver, ensure that the correct driver library for your
 *  device is linked in and include this header file as follows:
 *  @code
 *  #include <ti/drivers/I2C.h>
 *  @endcode
 *
 *  This module serves as the main interface for applications using an
 *  underlying I2C peripheral. Its purpose is to redirect the I2C APIs to
 *  device specific driver implementations which are specified using a pointer
 *  to a #I2C_FxnTable.
 *
 *  # Overview #
 *
 *  This section assumes that you have prior knowledge about the I2C protocol.
 *  For the full I2C-bus specification and user manual, view the \b UM10204
 *  document available online.
 *
 *  This I2C driver is designed to operate as an I2C master. This driver
 *  does not support I2C slave mode. This driver assumes it is the only I2C
 *  master on the I2C bus. Using the I2C APIs, you can transmit and recieve
 *  data over an I2C bus. The I2C-bus specification does not define how data
 *  is to be formatted or handled. This allows for flexible implementations
 *  across different peripheral vendors. As a result, this driver only
 *  performs the exchange of data between the master and slave(s). The
 *  application is responsible for manipulating and interpretting the data.
 *
 *  # Thread Safety #
 *
 *  This driver has been designed to operate in a Real-Time Operating System
 *  (RTOS) environment. This driver protects data transactions with operating
 *  system primitives supplied by the underlying RTOS.
 *
 *  # Usage #
 *
 *  The following code example opens an I2C instance.
 *
 *  @code
 *  I2C_Handle i2cHandle;
 *
 *  i2cHandle = I2C_open(Board_I2C0, NULL);
 *
 *  if (i2cHandle == NULL) {
 *      // Error opening I2C
 *      while (1);
 *  }
 *  @endcode
 *
 *  ## I2C Driver Configuration ##
 *
 *  In order to use the I2C APIs, the application is required to provide
 *  device-specific I2C configuration in the Board.c file. The I2C driver
 *  interface defines a configuration data structure, #I2C_Config.
 *
 *  The application must declare an array of #I2C_Config elements, named
 *  \p I2C_config[]. Each element of \p I2C_config[] is populated with
 *  pointers to a device specific I2C driver implementation's function
 *  table, driver object, and hardware attributes. The hardware attributes
 *  define properties such as the I2C peripheral's base address and
 *  pins. Each element in \p I2C_config[] corresponds to an I2C instance,
 *  and none of the elements should have \p NULL pointers.
 *
 *  The I2C configuration is device dependent. You will need to check the
 *  device specific I2C driver documentation. There you will find a
 *  description of the I2C hardware attributes.
 *
 *  ## Initializing the I2C Driver ##
 *
 *  I2C_init() must be called before any other I2C APIs. This function
 *  calls the device specific implementation's I2C initialization function
 *  for each element of \p NVS_config[].
 *
 *  ## Opening the I2C Driver ##
 *
 *  After initializing the I2C driver by calling I2C_init(), the application
 *  can open an I2C instance by calling I2C_open(). This function
 *  takes an index into the \p I2C_config[] array and an #I2C_Params structure.
 *  The #I2C_Handle returned from the I2C_open() is then associated with that
 *  index into the \p I2C_config[] array.
 *
 *  \note Each I2C index can only be opened exclusively. Calling I2C_open()
 *  multiple times with the same index will result in an error. The index can
 *  be re-used if I2C_close() is called first.
 *
 *  This example shows opening an I2C driver instance in callback mode
 *  with a bit rate of 400kbps.
 *
 *  @code
 *  I2C_Handle i2cHandle;
 *  I2C_Params i2cParams;
 *
 *  I2C_Params_init(&i2cParams);
 *
 *  i2cParams.transferMode = I2C_MODE_CALLBACK;
 *  i2cParams.transferCallbackFxn = myCallbackFunction;
 *  i2cParams.bitRate = I2C_400kHz;
 *
 *  i2cHandle = I2C_open(Board_I2C0, &i2cParams);
 *
 *  if (i2cHandle == NULL) {
 *      // Error opening I2C
 *      while (1);
 *  }
 *  @endcode
 *
 *  ## Transferring data ##
 *
 *  An I2C data transfer is performed using the I2C_transfer() function. Three
 *  types of transactions are supported: write, read, and write + read. The
 *  details of each transaction are specified with an #I2C_Transaction
 *  structure. Each transfer is completed before another transfer is initiated.
 *
 *  For write + read transactions, the specified data is first written to the
 *  peripheral, then a repeated start is sent by the driver, which initiates
 *  the read operation. This type of transfer is useful if an I2C peripheral
 *  has a pointer register that needs to be adjusted prior to reading from
 *  the referenced data register.
 *
 *  The below example shows sending three bytes of data to a slave peripheral
 *  at address 0x50, in blocking mode:
 *
 *  @code
 *  uint8_t writeBuffer[3];
 *  I2C_Transaction i2cTransaction;
 *
 *  i2cTransaction.slaveAddress = 0x50;
 *  i2cTransaction.writeBuf = writeBuffer;
 *  i2cTransaction.writeCount = 3;
 *  i2cTransaction.readBuf = NULL;
 *  i2cTransaction.readCount = 0;
 *
 *  status = I2C_transfer(i2cHandle, &i2cTransaction);
 *
 *  if (status == False) {
 *      // Unsuccessful I2C transfer
 *  }
 *  @endcode
 *
 *  The next example shows reading five bytes of data from the I2C
 *  peripheral, in blocking mode:
 *
 *  @code
 *  uint8_t readBuffer[5];
 *  I2C_Transaction i2cTransaction;
 *
 *  i2cTransaction.slaveAddress = 0x50;
 *  i2cTransaction.writeBuf = NULL;
 *  i2cTransaction.writeCount = 0;
 *  i2cTransaction.readBuf = readBuffer;
 *  i2cTransaction.readCount = 5;
 *
 *  status = I2C_transfer(i2cHandle, &i2cTransaction);
 *
 *  if (status == False) {
 *      // Unsuccessful I2C transfer
 *  }
 *  @endcode
 *
 *  This example shows writing two bytes and reading four bytes in a
 *  single transaction.
 *
 *  @code
 *  uint8_t readBuffer[4];
 *  uint8_t writeBuffer[2];
 *  I2C_Transaction i2cTransaction;
 *
 *  i2cTransaction.slaveAddress = 0x50;
 *  i2cTransaction.writeBuf = writeBuffer;
 *  i2cTransaction.writeCount = 2;
 *  i2cTransaction.readBuf = readBuffer;
 *  i2cTransaction.readCount = 4;
 *
 *  status = I2C_transfer(i2cHandle, &i2cTransaction);
 *
 *  if (status == False) {
 *      // Unsuccessful I2C transfer
 *  }
 *  @endcode
 *
 *  This final example shows usage of asynchronous callback mode, with queuing
 *  of multiple transactions. Because multiple transactions are simultaneously
 *  queued, separate #I2C_Transaction structures must be used.
 *
 *  \note #I2C_Transaction structures cannot be \b re-used until the previous
 *        transaction has completed.
 *
 *  First, the callback function specified by #I2C_Params.transferCallbackFxn
 *  is created. In this example, the #I2C_Transaction will contain a custom
 *  application argument. This argument will be a semaphore handle. The
 *  #I2C_Transaction.arg will point to the semaphore handle. When the callback
 *  function is called, the #I2C_Transaction.arg is checked for \p NULL. If
 *  this value is not \p NULL, then it can be assumed the \p arg is pointing
 *  to a valid semaphore handle. The semaphore handle is then used to call
 *  \p sem_post(). Hypothetically, this can be used to signal transaction
 *  completion to the task(s) that queued the transaction(s).
 *
 *  @code
 *  void callbackFxn(I2C_Handle handle, I2C_Transaction *msg, bool transfer)
 *  {
 *
 *      // Check for a semaphore handle
 *      if (msg->arg != NULL) {
 *
 *          // Perform a semaphore post
 *          sem_post((sem_t *) (msg->arg));
 *      }
 *  }
 *  @endcode
 *
 *  Snippets of the task code that initiates the transactions are shown below.
 *  Note the use of multiple #I2C_Transaction structures. The handle of the
 *  semaphore to be posted is specified via \p i2cTransaction2.arg.
 *  I2C_transfer() is called three times to initiate each transaction.
 *  Since callback mode is used, these functions return immediately. After
 *  the transactions have been queued, other work can be done. Eventually,
 *  \p sem_wait() is called causing the task to block until the transaction
 *  completes. When the transaction completes, the application's callback
 *  callback function, \p callbackFxn will be called. Once \p callbackFxn
 *  above posts the semaphore the task will be unblocked and can resume
 *  execution.
 *
 *  @code
 *  void taskfxn(arg0, arg1)
 *  {
 *
 *      I2C_Transaction i2cTransaction0;
 *      I2C_Transaction i2cTransaction1;
 *      I2C_Transaction i2cTransaction2;
 *
 *      // ...
 *
 *      i2cTransaction0.arg = NULL;
 *      i2cTransaction1.arg = NULL;
 *      i2cTransaction2.arg = semaphoreHandle;
 *
 *      // ...
 *
 *      I2C_transfer(i2c, &i2cTransaction0);
 *      I2C_transfer(i2c, &i2cTransaction1);
 *      I2C_transfer(i2c, &i2cTransaction2);
 *
 *      // ...
 *
 *      sem_wait(semaphoreHandle);
 *  }
 *  @endcode
 *
 *  # Implementation #
 *
 *  This top-level I2C module serves as the main interface for RTOS
 *  applications. Its purpose is to redirect the module's APIs to specific
 *  peripheral implementations which are specified using a pointer to an
 *  #I2C_FxnTable.
 *
 *  The I2C driver interface module is joined (at link time) to an
 *  array of #I2C_Config data structures named \p I2C_config.
 *  \p I2C_config is typically defined in the Board.c file used for the
 *  application. If there are multiple instances of I2C peripherals on the
 *  device, there will typically be multiple #I2C_Config structures defined in
 *  the board file in the form of an array. Each entry in \p I2C_config
 *  contains a:
 *  - #I2C_FxnTable pointer to a set of functions that implement an I2C
 *    peripheral.
 *  - (\p void *) data object that is associated with the #I2C_FxnTable
 *  - (\p void *) hardware attributes that are associated to the #I2C_FxnTable
 *
 *
 ******************************************************************************
 */

#ifndef ti_drivers_I2C__include
#define ti_drivers_I2C__include

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#define I2C_CMD_RESERVED           (32)

#define I2C_STATUS_RESERVED        (-32)

#define I2C_STATUS_SUCCESS         (0)

#define I2C_STATUS_ERROR           (-1)

#define I2C_STATUS_UNDEFINEDCMD    (-2)

/* Add I2C_CMD_<commands> here */

typedef struct I2C_Config_ *I2C_Handle;

typedef struct I2C_Transaction_ {
    void         *writeBuf;    
    size_t        writeCount;  
    void         *readBuf;     
    size_t        readCount;   
    uint_least8_t slaveAddress; 
    void         *arg;         
    void         *nextPtr;     
} I2C_Transaction;

typedef enum I2C_TransferMode_ {
    I2C_MODE_BLOCKING,  
    I2C_MODE_CALLBACK   
} I2C_TransferMode;

typedef void (*I2C_CallbackFxn)(I2C_Handle handle, I2C_Transaction *transaction,
    bool transferStatus);

typedef enum I2C_BitRate_ {

    I2C_100kHz     = 0,     
    I2C_400kHz     = 1,     
    I2C_1000kHz    = 2,     
    I2C_3330kHz    = 3,     
    I2C_3400kHz    = 3,     
} I2C_BitRate;

typedef struct I2C_Params_ {
    I2C_TransferMode transferMode;        
    I2C_CallbackFxn  transferCallbackFxn; 
    I2C_BitRate      bitRate;             
    void            *custom;              
} I2C_Params;

typedef void (*I2C_CancelFxn) (I2C_Handle handle);

typedef void (*I2C_CloseFxn) (I2C_Handle handle);

typedef int_fast16_t (*I2C_ControlFxn) (I2C_Handle handle, uint_fast16_t cmd,
    void *controlArg);

typedef void (*I2C_InitFxn) (I2C_Handle handle);

typedef I2C_Handle (*I2C_OpenFxn) (I2C_Handle handle, I2C_Params *params);

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

typedef struct I2C_FxnTable_ {
    I2C_CancelFxn   cancelFxn;

    I2C_CloseFxn    closeFxn;

    I2C_ControlFxn  controlFxn;

    I2C_InitFxn     initFxn;

    I2C_OpenFxn     openFxn;

    I2C_TransferFxn transferFxn;
} I2C_FxnTable;

typedef struct I2C_Config_ {
    I2C_FxnTable const *fxnTablePtr;

    void               *object;

    void         const *hwAttrs;
} I2C_Config;

extern void I2C_cancel(I2C_Handle handle);

extern void I2C_close(I2C_Handle handle);

extern int_fast16_t I2C_control(I2C_Handle handle, uint_fast16_t cmd,
    void *controlArg);

extern void I2C_init(void);

extern I2C_Handle I2C_open(uint_least8_t index, I2C_Params *params);

extern void I2C_Params_init(I2C_Params *params);

extern bool I2C_transfer(I2C_Handle handle, I2C_Transaction *transaction);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_I2C__include */