/*
 * Copyright (c) 2015-2016, 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      I2C driver interface
 *
 *  The I2C driver interface provides device independent APIs, data types,
 *  and macros. The I2C header file should be included in an application as
 *  follows:
 *  @code
 *  #include <ti/drivers/I2C.h>
 *  @endcode
 *
 *  # Overview #
 *  This section assumes that you have background knowledge and understanding
 *  about how the I2C protocol operates. For the full I2C specifications and
 *  user manual (UM10204), see the NXP Semiconductors website.
 *
 *  The I2C driver has been designed to operate as a single I2C master by
 *  performing I2C transactions between the target and I2C slave peripherals.
 *  The I2C driver does not support I2C slave mode.
 *  I2C is a communication protocol - the specifications define how data
 *  transactions are to occur via the I2C bus. The specifications do not
 *  define how data is to be formatted or handled, allowing for flexible
 *  implementations across different peripheral vendors. As a result, the
 *  I2C handles only the exchange of data (or transactions) between master
 *  and slaves. It is the left to the application to interpret and
 *  manipulate the contents of each specific I2C peripheral.
 *
 *  The I2C driver has been designed to operate in an RTOS environment.  It
 *  protects its transactions with OS primitives supplied by the underlying
 *  RTOS.
 *
 *  # Usage #
 *
 *  The I2C driver includes the following APIs:
 *    - I2C_init(): Initialize the I2C driver.
 *    - I2C_Params_init():  Initialize an #I2C_Params structure with default
 *      vaules.
 *    - I2C_open():  Open an instance of the I2C driver.
 *    - I2C_control():  Performs implemenation-specific features on a given
 *      I2C peripheral.
 *    - I2C_transfer():  Transfer the data.
 *    - I2C_close():  De-initialize the I2C instance.
 *
 *
 *  ### 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:
 *
 *  @code
 *  typedef struct I2C_Config_ {
 *      I2C_FxnTable  const    *fxnTablePtr;
 *      void                   *object;
 *      void          const    *hwAttrs;
 *  } I2C_Config;
 *  @endcode
 *
 *  The application must declare an array of I2C_Config elements, named
 *  I2C_config[].  Each element of I2C_config[] must be 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 I2C_config[] corresponds to
 *  an I2C instance, and none of the elements should have NULL pointers.
 *  There is no correlation between the index and the
 *  peripheral designation (such as I2C0 or I2C1).  For example, it is
 *  possible to use I2C_config[0] for I2C1.
 *
 *  Because the I2C configuration is very device dependent, you will need to
 *  check the doxygen for the device specific I2C implementation.  There you
 *  will find a description of the I2C hardware attributes.  Please also
 *  refer to the Board.c file of any of your examples to see the I2C
 *  configuration.
 *
 *  ### Initializing the I2C Driver #
 *
 *  I2C_init() must be called before any other I2C APIs.  This function
 *  iterates through the elements of the I2C_config[] array, calling
 *  the element's device implementation I2C initialization function.
 *
 *  ### I2C Parameters
 *
 *  The #I2C_Params structure is passed to the I2C_open() call.  If NULL
 *  is passed for the parameters, I2C_open() uses default parameters.
 *  An #I2C_Params structure is initialized with default values by passing
 *  it to I2C_Params_init().
 *  Some of the I2C parameters are described below.  To see brief descriptions
 *  of all the parameters, see #I2C_Params.
 *
 *  #### I2C Transfer Mode
 *  The I2C driver supports two transfer modes of operation: blocking and
 *  callback:
 *  - #I2C_MODE_BLOCKING: The call to I2C_transfer() blocks until the
 *    transfer completes.
 *  - #I2C_MODE_CALLBACK: The call to I2C_transfer() returns immediately.
 *    When the transfer completes, the I2C driver will call a user-
 *    specified callback function.
 *
 *  The transfer mode is determined by the #I2C_Params.transferMode parameter
 *  passed to I2C_open().  The I2C driver defaults to blocking mode, if the
 *  application does not set it.
 *
 *  In blocking mode, a task calling I2C_transfer() is blocked until the
 *  transaction completes.  Other tasks requesting I2C transactions while
 *  a transaction is currently taking place, are also placed into a
 *  blocked state.
 *
 *  In callback mode, an I2C_transfer() functions asynchronously, which
 *  means that it does not block a calling task's execution.  In this
 *  mode, the user must set #I2C_Params.transferCallbackFxn to a user-
 *  provided callback function. After an I2C transaction has completed,
 *  the I2C driver calls the user- provided callback function.
 *  If another I2C transaction is requested, the transaction is queued up.
 *  As each transfer completes, the I2C driver will call the user-specified
 *  callback function.  The user callback will be called from either hardware
 *  or software interrupt context, depending upon the device implementation.
 *
 *  Once an I2C driver instance is opened, the
 *  only way to change the transfer mode is to close and re-open the I2C
 *  instance with the new transfer mode.
 *
 *  #### Specifying an I2C Bus Frequency
 *  The I2C controller's bus frequency is determined by #I2C_Params.bitRate
 *  passed to I2C_open().  The standard I2C bus frequencies are 100 kHz and
 *  400 kHz, with 100 kHz being the default.
 *
 *  ### 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 I2C_config[] array and an I2C parameters data
 *  structure.   The I2C instance is specified by the index of the I2C in
 *  I2C_config[].  Only one I2C index can be used at a time;
 *  calling I2C_open() a second time with the same index previosly
 *  passed to I2C_open() will result in an error.  You can,
 *  though, re-use the index if the instance is closed via I2C_close().
 *
 *  If no I2C_Params structure is passed to I2C_open(), default values are
 *  used. If the open call is successful, it returns a non-NULL value.
 *
 *  Example opening an I2C driver instance in blocking mode:
 *  @code
 *  I2C_Handle i2c;
 *
 *  // NULL params are used, so default to blocking mode, 100 KHz
 *  i2c = I2C_open(Board_I2C0, NULL);
 *
 *  if (!i2c) {
 *      // Error opening the I2C
 *  }
 *  @endcode
 *
 *  Example opening an I2C driver instance in callback mode and 400KHz bit rate:
 *
 *  @code
 *  I2C_Handle i2c;
 *  I2C_Params params;
 *
 *  I2C_Params_init(&params);
 *  params.transferMode  = I2C_MODE_CALLBACK;
 *  params.transferCallbackFxn = myCallbackFunction;
 *  params.bitRate  = I2C_400kHz;
 *
 *  handle = I2C_open(Board_I2C0, &params);
 *  if (!i2c) {
 *      // Error opening I2C
 *  }
 *  @endcode
 *
 *  ### Transferring data #
 *  An I2C transaction with an I2C peripheral is started by calling
 *  I2C_transfer().  Three types of transactions are supported: Write, Read,
 *  or Write/Read. 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 details of each transaction are specified with an #I2C_Transaction data
 *  structure. This structure defines the slave I2C address, pointers
 *  to write and read buffers, and their associated byte counts. If
 *  no data needs to be written or read, the corresponding byte counts should
 *  be set to zero.
 *
 *  If an I2C transaction is requested while a transaction is currently
 *  taking place, the new transaction is placed onto a queue to be processed
 *  in the order in which it was received.
 *
 *  The below example shows sending three bytes of data to a slave peripheral
 *  at address 0x50, in blocking mode:
 *
 *  @code
 *  unsigned char writeBuffer[3];
 *  I2C_Transaction i2cTransaction;
 *
 *  i2cTransaction.slaveAddress = 0x50;
 *  i2cTransaction.writeBuf = writeBuffer;
 *  i2cTransaction.writeCount = 3;
 *  i2cTransaction.readBuf = NULL;
 *  i2cTransaction.readCount = 0;
 *
 *  status = I2C_transfer(i2c, &i2cTransaction);
 *  if (!status) {
 *      // Unsuccessful I2C transfer
 *  }
 *  @endcode
 *
 *  The next example shows reading of five bytes of data from the I2C
 *  peripheral, also in blocking mode:
 *
 *  @code
 *  unsigned char readBuffer[5];
 *  I2C_Transaction i2cTransaction;
 *
 *  i2cTransaction.slaveAddress = 0x50;
 *  i2cTransaction.writeBuf = NULL;
 *  i2cTransaction.writeCount = 0;
 *  i2cTransaction.readBuf = readBuffer;
 *  i2cTransaction.readCount = 5;
 *
 *  status = I2C_transfer(i2c, &i2cTransaction);
 *  if (!status) {
 *      // Unsuccessful I2C transfer
 *  }
 *  @endcode
 *
 *  This example shows writing of two bytes and reading of four bytes in a
 *  single transaction.
 *
 *  @code
 *  unsigned char readBuffer[4];
 *  unsigned char writeBuffer[2];
 *  I2C_Transaction i2cTransaction;
 *
 *  i2cTransaction.slaveAddress = 0x50;
 *  i2cTransaction.writeBuf = writeBuffer;
 *  i2cTransaction.writeCount = 2;
 *  i2cTransaction.readBuf = readBuffer;
 *  i2cTransaction.readCount = 4;
 *
 *  status = I2C_transfer(i2c, &i2cTransaction);
 *  if (!status) {
 *      // 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.  (This is a
 *  general rule, that I2C_Transaction structures cannot be reused until
 *  it is known that the previous transaction has completed.)
 *
 *  First, for the callback function (that is specified in the I2C_open() call)
 *  the "arg" in the I2C_Transaction structure is a SemaphoreP_Handle; when
 *  this value is non-NULL, SemaphoreP_post() is called in the callback using
 *  the specified handle, to signal completion to the task that queued the
 *   transactions:
 *
 *  @code
 *  Void callbackFxn(I2C_Handle handle, I2C_Transaction *msg, Bool transfer) {
 *      if (msg->arg != NULL) {
 *          SemaphoreP_post((SemaphoreP_Handle)(msg->arg));
 *      }
 *  }
 *  @endcode
 *
 *  Snippets of the task code that initiates the transactions are shown below.
 *  Note the use of multiple I2C_Transaction structures, and passing of the
 *  handle of the semaphore to be posted via 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, and then
 *  eventually SemaphoreP_pend() is called to wait for the last I2C
 *  transaction to complete.  Once the callback posts the semaphore, the task
 *  will be moved to the ready state, so the task can resume execution, after
 *  the SemaphoreP_pend() call.
 *
 *  @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);
 *
 *      ...
 *
 *      SemaphoreP_pend(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 *I2C_config*.
 *  *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. Each entry in *I2C_config* contains a:
 *  - (I2C_FxnTable *) to a set of functions that implement a I2C peripheral
 *  - (void *) data object that is associated with the I2C_FxnTable
 *  - (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 <stdint.h>
#include <stdbool.h>
#include <stddef.h>

/**
 *  @defgroup I2C_CONTROL I2C_control command and status codes
 *  These I2C macros are reservations for I2C.h
 *  @{
 */

/*!
 * Common I2C_control command code reservation offset.
 * I2C driver implementations should offset command codes with I2C_CMD_RESERVED
 * growing positively
 *
 * Example implementation specific command codes:
 * @code
 * #define I2CXYZ_CMD_COMMAND0      I2C_CMD_RESERVED + 0
 * #define I2CXYZ_CMD_COMMAND1      I2C_CMD_RESERVED + 1
 * @endcode
 */
#define I2C_CMD_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:
 * @code
 * #define I2CXYZ_STATUS_ERROR0     I2C_STATUS_RESERVED - 0
 * #define I2CXYZ_STATUS_ERROR1     I2C_STATUS_RESERVED - 1
 * #define I2CXYZ_STATUS_ERROR2     I2C_STATUS_RESERVED - 2
 * @endcode
 */
#define I2C_STATUS_RESERVED        (-32)

/**
 *  @defgroup I2C_STATUS Status Codes
 *  I2C_STATUS_* macros are general status codes returned by I2C_control()
 *  @{
 *  @ingroup I2C_CONTROL
 */

/*!
 * @brief   Successful status code returned by I2C_control().
 *
 * I2C_control() returns I2C_STATUS_SUCCESS if the control code was executed
 * successfully.
 */
#define I2C_STATUS_SUCCESS         (0)

/*!
 * @brief   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_ERROR           (-1)

/*!
 * @brief   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.
 */
#define I2C_STATUS_UNDEFINEDCMD    (-2)
/** @}*/

/**
 *  @defgroup I2C_CMD Command Codes
 *  I2C_CMD_* macros are general command codes for I2C_control(). Not all I2C
 *  driver implementations support these command codes.
 *  @{
 *  @ingroup I2C_CONTROL
 */

/* Add I2C_CMD_<commands> here */

/** @}*/

/** @}*/

/*!
 *  @brief      A handle that is returned from an I2C_open() call.
 */
typedef struct I2C_Config_    *I2C_Handle;

/*!
 *  @brief  I2C transaction
 *
 *  This structure defines an I2C transaction. It specifies the buffer(s) and
 *  buffer size(s) to be written to and/or read from an I2C slave peripheral.
 *  arg is an optional user-supplied argument that will be passed
 *  to the user-supplied callback function when the I2C driver is in
 *  I2C_MODE_CALLBACK.
 *  nextPtr is a pointer used internally by the driver for queuing of multiple
 *  transactions; this value must never be modified by the user application.
 */
typedef struct I2C_Transaction_ {
    void    *writeBuf;    /*!< Buffer containing data to be written */
    size_t   writeCount;  /*!< Number of bytes to be written to the slave */

    void    *readBuf;     /*!< Buffer to which data is to be read into */
    size_t   readCount;   /*!< Number of bytes to be read from the slave */

    uint_least8_t slaveAddress; /*!< Address of the I2C slave peripheral */

    void    *arg;         /*!< Argument to be passed to the callback function */
    void    *nextPtr;     /*!< Used for queuing in I2C_MODE_CALLBACK mode */
} I2C_Transaction;

/*!
 *  @brief  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 enum I2C_TransferMode_ {
    I2C_MODE_BLOCKING,  /*!< I2C_transfer() blocks execution */
    I2C_MODE_CALLBACK   /*!< I2C_transfer() does not block */
} I2C_TransferMode;

/*!
 *  @brief  I2C callback function
 *
 *  User-definable callback function prototype. The I2C driver will call this
 *  callback upon transfer completion, specifying the I2C handle for the
 *  transfer (as returned from I2C_open()), the pointer to the I2C_Transaction
 *  that just completed, and the return value of I2C_transfer().  Note that
 *  this return value will be the same as if the transfer were performed in
 *  blocking mode.
 *
 *  @param  I2C_Handle          I2C_Handle

 *  @param  I2C_Transaction*    Address of the I2C_Transaction

 *  @param  bool                Result of the I2C transfer
 */
typedef void (*I2C_CallbackFxn)(I2C_Handle handle, I2C_Transaction *transaction,
    bool transferStatus);

/*!
 *  @brief  I2C bitRate
 *
 *  Specifies one of the standard I2C bus bit rates for I2C communications.
 *  The default is I2C_100kHz.
 */
typedef enum I2C_BitRate_ {
    I2C_100kHz = 0,
    I2C_400kHz = 1
} I2C_BitRate;

/*!
 *  @brief  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, I2C_transfer() function
 *  calls will block thread execution until the transaction has completed.  In
 *  this case, the transferCallbackFxn parameter will be ignored.
 *
 *  If I2C_TransferMode is set to I2C_MODE_CALLBACK, I2C_transfer() will not
 *  block thread execution, but it will call the function specified by
 *  transferCallbackFxn upon transfer completion. Sequential calls to
 *  I2C_transfer() in I2C_MODE_CALLBACK will put the I2C_Transaction structures
 *  onto an internal queue that automatically starts queued transactions after
 *  the previous transaction has completed. This queuing occurs regardless of
 *  any error state from previous transactions.
 *
 *  I2C_BitRate specifies the I2C bus rate used for I2C communications.
 *
 *  @sa     I2C_Params_init()
 */
typedef struct I2C_Params_ {
    I2C_TransferMode transferMode;        /*!< Blocking or Callback mode */
    I2C_CallbackFxn  transferCallbackFxn; /*!< Callback function pointer */
    I2C_BitRate      bitRate;             /*!< I2C bus bit rate */
    void            *custom;              /*!< Custom argument used by driver
                                               implementation */
} I2C_Params;

/*!
 *  @brief      A function pointer to a driver-specific implementation of
 *              I2C_cancel().
 */
typedef void (*I2C_CancelFxn) (I2C_Handle handle);

/*!
 *  @brief      A function pointer to a driver-specific implementation of
 *              I2C_close().
 */
typedef void (*I2C_CloseFxn) (I2C_Handle handle);

/*!
 *  @brief      A function pointer to a driver-specific implementation of
 *              I2C_control().
 */
typedef int_fast16_t (*I2C_ControlFxn) (I2C_Handle handle, uint_fast16_t cmd,
    void *controlArg);

/*!
 *  @brief      A function pointer to a driver-specific implementation of
 *              I2C_init().
 */
typedef void (*I2C_InitFxn) (I2C_Handle handle);

/*!
 *  @brief      A function pointer to a driver-specific implementation of
 *              I2C_open().
 */
typedef I2C_Handle (*I2C_OpenFxn) (I2C_Handle handle, I2C_Params *params);

/*!
 *  @brief      A function pointer to a driver-specific implementation of
 *              I2C_transfer().
 */
typedef bool (*I2C_TransferFxn) (I2C_Handle handle,
    I2C_Transaction *transaction);

/*!
 *  @brief      The definition of an I2C function table that contains the
 *              required set of functions to control a specific I2C driver
 *              implementation.
 */
typedef struct I2C_FxnTable_ {
    /*! Cancel all I2C data transfers */
    I2C_CancelFxn   cancelFxn;

    /*! Close the specified peripheral */
    I2C_CloseFxn    closeFxn;

    /*! Implementation-specific control function */
    I2C_ControlFxn  controlFxn;

    /*! Initialize the given data object */
    I2C_InitFxn     initFxn;

    /*! Open the specified peripheral */
    I2C_OpenFxn     openFxn;

    /*! Initiate an I2C data transfer */
    I2C_TransferFxn transferFxn;
} I2C_FxnTable;

/*!
 *  @brief  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.
 *
 *  @sa     I2C_init()
 */
typedef struct I2C_Config_ {
    /*! Pointer to a table of driver-specific implementations of I2C APIs */
    I2C_FxnTable const *fxnTablePtr;

    /*! Pointer to a driver-specific data object */
    void               *object;

    /*! Pointer to a driver-specific hardware attributes structure */
    void         const *hwAttrs;
} I2C_Config;

/*!
 *  @brief  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.
 *
 *  @pre    I2C_Transfer() has been called.
 *
 *  @param  handle  An 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-specific
 *          steps that can be used to successfully resume communication.
 *
 *  @sa     I2C_transfer()
 */
extern void I2C_cancel(I2C_Handle handle);

/*!
 *  @brief  Close an I2C peripheral specified by an I2C_Handle
 *
 *  @pre    I2C_open() has been called.
 *
 *  @param  handle  An I2C_Handle returned from I2C_open()
 *
 *  @sa     I2C_open()
 */
extern void I2C_close(I2C_Handle handle);

/*!
 *  @brief  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_, I2CMSP432.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.<br>
 *  Commands supported by I2C*.h follow a I2C*_CMD_\<cmd\> naming
 *  convention.<br>
 *  Each control command defines @b arg differently. The types of @b arg are
 *  documented with each command.
 *
 *  See @ref I2C_CMD "I2C_control command codes" for command codes.
 *
 *  See @ref I2C_STATUS "I2C_control return status codes" for status codes.
 *
 *  @pre    I2C_open() has to be called first.
 *
 *  @param  handle      An I2C_Handle returned from I2C_open()
 *
 *  @param  cmd         I2C.h or I2C*.h command.
 *
 *  @param  controlArg  An optional R/W (read/write) command argument
 *                      accompanied with cmd
 *
 *  @return Implementation-specific return codes. Negative values indicate
 *          unsuccessful operations.
 *
 *  @sa     I2C_open()
 */
extern int_fast16_t I2C_control(I2C_Handle handle, uint_fast16_t cmd,
    void *controlArg);

/*!
 *  @brief  Initializes the I2C module
 *
 *  @pre    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.
 */
extern void I2C_init(void);

/*!
 *  @brief  Initialize a given I2C peripheral as identified by an index value.
 *          The I2C_Params structure defines the operating mode, and any
 *          related settings.
 *
 *  @pre    The I2C controller has been initialized, via a previous call to
 *          I2C_init()
 *
 *  @param  index         Logical peripheral number for the I2C indexed into
 *                        the I2C_config table
 *
 *  @param  params        Pointer to a parameter block. Default values will be
 *                        used if NULL is specified for params. All the fields
 *                        in this structure are are considered RO (read-only).
 *
 *  @return An I2C_Handle on success, or NULL on an error, or if the peripheral
 *          is already opened.
 *
 *  @sa     I2C_init()
 *  @sa     I2C_close()
 */
extern I2C_Handle I2C_open(uint_least8_t index, I2C_Params *params);

/*!
 *  @brief  Initialize an I2C_Params struct to its defaults
 *
 *  @param  params      A pointer to I2C_Params structure for
 *                      initialization
 *
 *  Defaults values are:
 *      transferMode = I2C_MODE_BLOCKING
 *      transferCallbackFxn = NULL
 *      bitRate = I2C_100kHz
 */
extern void I2C_Params_init(I2C_Params *params);

/*!
 *  @brief  Perform an I2C transaction with an I2C slave peripheral.
 *
 *  This function will perform an I2C transfer, as specified by an
 *  I2C_Transaction structure.
 *
 *  An I2C transaction may write data to a peripheral, or read data from a
 *  peripheral, or both write and read data, in a single transaction.  If there
 *  is any data to be written, it will always be sent before any data is read
 *  from the peripheral.
 *
 *  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 yes, another START bit is sent, along with the same 7-bit I2C slave
 *  address (with the Read bit).  After the specified number of bytes have been
 *  read, the transfer is ended with a NACK and a STOP bit.  Otherwise, if
 *  no data is to be read, the transfer is concluded with a STOP bit.
 *
 *  In I2C_MODE_BLOCKING, I2C_transfer() will block thread execution until the
 *  transaction completes. Therefore, this function must only be called from an
 *  appropriate thread context (e.g., Task context for the TI-RTOS kernel).
 *
 *  In I2C_MODE_CALLBACK, the I2C_transfer() call does not block thread
 *  execution. Instead, a callback function (specified during I2C_open(), via
 *  the transferCallbackFxn field in the I2C_Params structure) 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 driver
 *  services the queue in a first come first served basis.
 *
 *  @param  handle      An I2C_Handle
 *
 *  @param  transaction A pointer to an I2C_Transaction. All of the fields
 *                      within the transaction structure should be considered
 *                      write only, unless otherwise noted in the driver
 *                      implementation.
 *
 *  @note The I2C_Transaction structure must persist unmodified until the
 *  corresponding call to I2C_transfer() has completed.
 *
 *  @return 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 to indicate
 *          an error.
 *
 *  @sa     I2C_open
 */
extern bool I2C_transfer(I2C_Handle handle, I2C_Transaction *transaction);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_I2C__include */