| ISF 1.1 Intelligent Sensing Framework

- Main Page
- Data Structures
- Files
- Sensor Adapters

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf_i2c.h
Go to the documentation of this file.

    00001 /*!
    00002 *****************************************************************
    00003 * File: isf_i2c.h
    00004 *
    00005 * Copyright (c) 2012, Freescale Semiconductor, Inc.
    00006 *
    00007 ******************************************************************/
    00008 /*!
    00009 * @file isf_i2c.h
    00010 * @brief \b isf_i2c.h describes the definitions and types for the ISF I2C component.
    00011 */
    00012
    00013 #ifndef INCLUDE_I2C_TYPES_H
    00014 #define INCLUDE_I2C_TYPES_H
    00015
    00016 #include <isf_types.h>
    00017 #include "isf.h"
    00018 #include <isf_comm.h>
    00019
    00020
    00021 /*******************
    00022 ** Macro Definitions
    00023 */
    00024
    00025 #define I2C_SIZED_BUFFER(bufSize) \
    00026     struct { uint16 size; uint8 buffer[(bufSize)]; }
    00027     /*!< Properly sized buffer for reads and writes. */
    00028
    00029 #define I2C_FIND_FIRST_SLAVE { 0, NULL}   /*!< A macro used with * ::i2c_bus_enumerate() to specify a full search for slave
    00030 * devices. */
    00031
    00032
    00033 #define I2C_CMD_DEFN(cmdLen) \
    00034     struct { uint16 nWrite; uint16 nRead; uint8 cmdWords[(cmdLen)]; }    /*!< Macro used for storing the created concretely sized typdedefs compatible with ::i2c_Command_t.  */
    00035
    00036 #define I2C_10BITADDRESS_BITMASK   0x8000     /*!<Macro used to add a flag to distinguish an address as
    00037 * 10-bit,creating an address understandable by the I2C driver.*/
    00038
    00039 #define I2C_MAKE_10BITADDRESS(addr)             (addr | I2C_10BITADDRESS_BITMASK)
    00040 /*!< Macro used for 10-bit addressing. As an example, for
    00041  * an actual 10-bit address of 0x120,
    00042  * I2C_MAKE_10BITADDRESS(0x120) is called to make it acceptable to the I2C module.
    00043  */
    00044
    00045 /**************
    00046 ** Enumerations
    00047 */
    00048 /*! @brief These are I2C bus configuration parameters. */
    00049 enum i2c_BusConfigFlag_vals {
    00050     I2C_CONFIG_MASTER   = 0x1  /*!< Configure as Bus Master. */
    00051 };
    00052
    00053 /*! @brief These are flags for modifying the behavior of a write.
    00054  */
    00055 enum i2c_writeFlags_vals {
    00056     I2C_WRITE_FLAGS_DEFAULT = 0x0  /*!< The default write flag values are used. */
    00057 };
    00058
    00059 /*! @brief These are flags for modifying the behavior of a read.
    00060  */
    00061 enum i2c_readFlags_vals {
    00062     I2C_READ_FLAGS_DEFAULT   = 0x0   /*!< The default read flag values are used. */
    00063 };
    00064
    00065 /*! @brief These are hardware-specific configuration parameters
    00066  *  for devices similar to the FXLC95000CL and should not be
    00067  *  modified.
    00068  */
    00069 enum i2c_HWSpecificReg_Config{
    00070     HWSPECIFIC_REG_FREQUENCY = 0,         /*!< The frequency register.  */
    00071     HWSPECIFIC_REG_CTRL_1 = 1,            /*!< The control one register.  */
    00072     HWSPECIFIC_MAX = 2                    /*!< The maximum number of registers. */
    00073 };
    00074 /*! @brief These values establish the i2C bus speed.  The user
    00075  *  can specify other valid speeds by configuring the frequency
    00076  *  register via the hwSpecificCfg parameter in the
    00077  *  ::i2c_BusConfig_t structure. */
    00078 enum i2c_Speed{
    00079     I2C_SPEED_START = 0,                 /*!< The start of the speed range.  */
    00080     I2C_SPEED_600_KHZ = I2C_SPEED_START, /*!< The speed at 600 KHz.  */
    00081     I2C_SPEED_400_KHZ = 1,               /*!< The speed at 400 KHz.  */
    00082     I2C_SPEED_200_KHZ = 2,               /*!< The speed at 200 KHz.  */
    00083     I2C_SPEED_END = 3                    /*!< The end of the speed range. It is 200 KHz now. */
    00084 };
    00085 /*********************
    00086 **  and Typedefs
    00087 */
    00088
    00089 typedef comm_Id_t i2c_BusId_t;         /*!< This is a
    00090 * numeric bus identifier used to index into an array of buses.  */
    00091
    00092 typedef uint8 i2c_BusConfigFlags_t;    /*!< This item contains
    00093 * configuration flags used to configure an I2C bus.
    00094 */
    00095
    00096 typedef comm_State_t i2c_BusState_t;   /*!< This item contains an
    00097 * enumerated value describing the state of an I2C bus.
    00098 */
    00099
    00100 typedef comm_Address_t i2c_AddrHint_t; /*!< This item holds an
    00101 * I2C device bus address that can contain both 7-bit and 10-bit
    00102 * addresses.
    00103 */
    00104
    00105 typedef comm_Flags_t i2c_readFlags_t;  /*!< This is a bit array
    00106 * of flags governing I2C read behavior.
    00107 */
    00108
    00109 typedef comm_Flags_t i2c_writeFlags_t; /*!< This is a bit array
    00110 * of flags governing I2C write behavior.
    00111 */
    00112
    00113 /*! @brief This structure defines the user-specified parameters for
    00114  *  bus configuration.
    00115  *
    00116  *  @details An effort has been made to keep the contents of this
    00117  *  type generic, hiding any specific I2C peripheral details in
    00118  *  the pHWSpecificCfg field.
    00119  */
    00120
    00121 typedef struct i2c_BusConfig_struct {
    00122     isf_duration_t       timeout;    /*!< The bus timeout
    00123  * value to use.
    00124  */
    00125     uint8                 speed;      /*!< The speed at
    00126  * which to run the bus.
    00127  */
    00128     i2c_BusConfigFlags_t  configFlags;/*!< Flags used to check bus configurations,
    00129  * masterMode and extendedAddrMode.
    00130  */
    00131     uint8                 hwSpecificCfg[HWSPECIFIC_MAX];
    00132                                       /*!< Any other necessary data
    00133  * used by the bus-specific implementation of
    00134  * ::i2c_bus_init().
    00135  */
    00136 } i2c_BusConfig_t;
    00137
    00138 /*
    00139 **  The design goal with these types is to allow the static portions of
    00140 **  the messages to be usable from flash reducing the RAM usage requirements.
    00141 */
    00142
    00143 /*! @brief This structure defines a buffer to hold data read from
    00144  *  or written to the I2C bus. */
    00145 typedef struct i2c_MessageBuffer_struct {
    00146     uint16 size;          /*!< The size of the buffer.      */
    00147     uint8  buffer[];      /*!< Buffer defined to hold the data. */
    00148 } i2c_MessageBuffer_t;
    00149
    00150 /*! @brief This structure defines the data of a command
    00151  *  transferred over the I2C bus.  */
    00152 typedef struct i2c_Command_struct {
    00153     uint16 nWrite;           /*!< The number of bytes to write. */
    00154     uint16 nRead;            /*!< The number of bytes to read.  */
    00155     uint8  cmdWords[];       /*!< An array containing the transferred command */
    00156 } i2c_Command_t;
    00157
    00158 /*! @brief This structure defines the data bus handle. */
    00159 typedef struct i2c_BusHandle_struct
    00160 {
    00161     uint8 id;                  /*!< The unique ID associated with the bus handle. */
    00162     void *pLock;               /*!< The pointer to the lock.             */
    00163     uint8 nLock;               /*!< The lock count associated with the lock. */
    00164     void *pBusInfo;            /*!< The pointer to the bus information.       */
    00165 }i2c_BusHandle_t;
    00166
    00167 /* Implementation Notes:
    00168  * SlaveHandle should contain a reference to the bus on which the slave resides.
    00169  */
    00170
    00171 /*! @brief This structure defines a slave handler.  */
    00172 typedef struct i2c_SlaveHandle_struct
    00173 {
    00174     i2c_AddrHint_t slaveAddr;       /*!< The slave address. */
    00175     i2c_BusHandle_t *pBusHandle;     /*!< The pointer to the bus handle. */
    00176 }i2c_SlaveHandle_t;
    00177
    00178 /*********************
    00179 ** Function Prototypes
    00180 */
    00181
    00182 /*
    00183 ** Initialization Routines
    00184 */
    00185
    00186 /*! @brief      This function initializes the I2C bus.
    00187  *
    00188  *  @details    Any I2C bus must be initialized prior to use. Initialization creates and initializes the data structures
    00189  *              required to manage the bus.  The bus is implicitly locked during initialization.
    00190  *
    00191  *  @param[in]  aBusId       The ID of the bus to initialize. This is an index into the array of known buses that can be
    00192  *                           used.
    00193  *  @param[out] apBusHandle  The bus handle of the bus to be configured.
    00194  *
    00195  *  @return     ::i2c_bus_init() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00196  *              function call.
    00197  *
    00198  *
    00199  *  @retval      ::COMM_ERROR_NOEXIST   is returned when the supplied bus identifier does not exist.
    00200  *  @retval      ::COMM_ERROR_NULL_PTR  is returned when a NULL parameter was passed into the function.
    00201  *  @retval      ::COMM_ERROR_INIT      is returned when the bus could not be initialized.
    00202  *  @retval      ::COMM_ERROR_TIME_OUT  is returned when the request could not be fulfilled in the specified timeout period.
    00203  *  @retval      ::COMM_ERROR_LOCK      is returned when the lock could not be acquired properly.
    00204  *
    00205  *
    00206  *  @Constraints The following constraints must be observed when using this function:
    00207  *               @li aBusId must be in the range of known bus identifiers.
    00208  *               @li apBusConfig must point to a valid ::i2c_BusConfig_t object for the bus being initialized.
    00209  *
    00210  *  @Reentrant   Yes
    00211  *
    00212  *  @Libs        isf_core.lib
    00213  *
    00214  */
    00215 isf_status_t i2c_bus_init(
    00216     i2c_BusId_t      aBusId,
    00217     i2c_BusHandle_t *apBusHandle
    00218 );
    00219
    00220 /*! @brief      This function configures or reconfigures an already initialized bus.
    00221  *
    00222  *  @details    A bus may be configured during initialization or it may be configured separately after initialization.
    00223  *              Calls made to ::i2c_bus_configure() after initialization overrides any previous configuration values, and
    00224  *              must be made while the bus state is STOPPED.
    00225  *
    00226  *  @param[in]  apBusHandle  The handle of the bus to be configured.
    00227  *  @param[in]  apBusConfig  The configuration parameters to be used during configuration.
    00228  *
    00229  *  @return     ::i2c_bus_configure() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00230  *
    00231  *  @retval     ::COMM_ERROR_STOP      is returned when the bus was not in a STOPPED state.
    00232  *  @retval     ::COMM_ERROR_INIT      is returned when the bus is not initialized.
    00233  *  @retval     ::COMM_ERROR_NULL_PTR  is returned when a NULL parameter was passed into the function.
    00234  *  @retval     ::COMM_ERROR_TIME_OUT  is returned when the request could not be fulfilled in the specified timeout interval.
    00235  *  @retval     ::COMM_ERROR_LOCK      is returned when the request could not be completed as there is a invalid lock associated with the bus.
    00236  *
    00237  *
    00238  *  @Constraints The following constraints must be observed when using this function:
    00239  *               @li The bus must be initialized and have a valid bus handle.
    00240  *               @li It must be called when the bus is STOPPED.
    00241  *
    00242  *  @Reentrant   Yes
    00243  *
    00244  *  @Libs        isf_core.lib
    00245  *
    00246  */
    00247 isf_status_t i2c_bus_configure(
    00248     i2c_BusHandle_t *apBusHandle,
    00249     i2c_BusConfig_t *apBusConfig
    00250 );
    00251
    00252 /*
    00253 ** Queries and Status
    00254 */
    00255
    00256 /*! @brief       This function returns the bus state.
    00257  *
    00258  *  @details     A bus may be queried for its current state.
    00259  *
    00260  *  @param[in]   apBusHandle The handle of the bus to be queried.
    00261  *
    00262  *  @return      ::i2c_get_bus_state() returns a value of type :: i2c_BusState_t indicating the current state of the bus.
    00263  *
    00264  *  @retval      ::COMM_ERROR_NULL_PTR A NULL parameter was passed into the function.
    00265  *  @Constraints None
    00266  *
    00267  *  @Reentrant   Yes
    00268  *
    00269  *  @Libs        isf_core.lib
    00270  *
    00271  */
    00272 i2c_BusState_t i2c_get_bus_state(i2c_BusHandle_t *apBusHandle);
    00273
    00274 /*! @brief       This function returns the current bus configuration.
    00275  *
    00276  *  @details     A bus may be queried for the current configuration in use.
    00277  *
    00278  *  @param[in]   apBusHandle  The handle of the bus to be queried.
    00279  *  @param[out]  apBusConfig  The address of the configuration of the bus queried.
    00280  *
    00281  *  @return      ::i2c_get_bus_config() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00282  *
    00283  *  @retval      ::COMM_ERROR_NULL_PTR is returned when an invalid bus handle was provided to the function.
    00284  *
    00285  *  @Constraints None
    00286  *
    00287  *  @Reentrant   Yes
    00288  *
    00289  *  @Libs        isf_core.lib
    00290  *
    00291  */
    00292  isf_status_t i2c_get_bus_config(
    00293     i2c_BusHandle_t *apBusHandle,
    00294     i2c_BusConfig_t *apBusConfig
    00295  );
    00296
    00297 /*! @brief      This function creates a slave handle for a device at a specified bus address.
    00298  *
    00299  *   @details   The ::i2c_get_slave_at() function obtains the handle to a slave device at a known bus address.
    00300  *  @param[in]  apBusHandle   The handle of the bus to be queried.
    00301  *  @param[in]  aSlaveAddr    The known address of a slave device.
    00302  *  @param[out] apSlaveHandle The address of the slave handle provided for the slave device on the given bus.
    00303  *
    00304  *  @return     ::i2c_get_slave_at() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00305  *
    00306  *  @retval     ::ISF_SUCCESS is returned when a slave with the given address is found.
    00307  *
    00308  *  @retval     ::COMM_ERROR_NOEXIST   is returned when a slave does not exist at the specified address.
    00309  *  @retval     ::COMM_ERROR_INIT      is returned when the bus handle refers to a non-initialized bus.
    00310  *  @retval     ::COMM_ERROR_STOP      is returned when the bus has not been started.
    00311  *  @retval     ::COMM_ERROR_NULL_PTR  is returned when a NULL parameter was passed into the function.
    00312  *  @retval     ::COMM_ERROR_TIME_OUT  is returned when the request could not be fulfilled in the specified timeout period made during the bus configuration.
    00313  *  @retval     ::COMM_ERROR_LOCK      is returned when the internal lock request fails due to an invalid lock on the bus handle.
    00314  *
    00315  *  @Constraints None
    00316  *
    00317  *  @Reentrant   Yes
    00318  *
    00319  *  @Libs        isf_core.lib
    00320  *
    00321  */
    00322  isf_status_t i2c_get_slave_at(
    00323     i2c_BusHandle_t   *apBusHandle,
    00324     i2c_AddrHint_t     aSlaveAddr,
    00325     i2c_SlaveHandle_t *apSlaveHandle
    00326  );
    00327
    00328 /*! @brief       This function searches for a slave device on the bus.
    00329  *
    00330  *  @details    To enumerate a bus, ::i2c_bus_enumerate() is called repeatedly until all the desired slaves are found.
    00331  *               The slave handle found on the preceding call is passed in the subsequent call to find the next slave.
    00332  *               If all slave addresses are known, bus enumeration is not required and ::i2c_get_slave_at() may be used to
    00333  *               acquire all the slave handles.
    00334  *
    00335  *  @param[in]   apBusHandle       The handle of the bus to be queried.
    00336  *  @param[in]   apPrevSlaveHandle The known address of a slave device.
    00337  *  @param[out]  apNextSlaveHandle The known address of the next slave device.
    00338  *
    00339  *  @return      ::i2c_bus_enumerate() returns a value of type  ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00340
    00341  *  @retval      ::ISF_SUCCESS is returned when another slave device was found.
    00342  *
    00343  *  @retval      ::COMM_ERROR_NOEXIST is returned when no more slave devices are found.
    00344  *  @retval      ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized bus.
    00345  *  @retval      ::COMM_ERROR_STOP is returned when the bus is not started.
    00346  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL parameter was passed into the function.
    00347  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period provided during the bus configuration.
    00348  *  @retval      ::COMM_ERROR_LOCK is returned when the internal lock request fails due to an invalid lock on the bus handle.
    00349  *
    00350  *  @Constraints None
    00351  *
    00352  *  @Reentrant   Yes
    00353  *
    00354  *  @Libs        isf_core.lib
    00355  *
    00356  */
    00357  isf_status_t i2c_bus_enumerate(
    00358     i2c_BusHandle_t   *apBusHandle,
    00359     i2c_SlaveHandle_t *apPrevSlaveHandle,   /* pass I2C_FIND_FIRST_SLAVE here to start a full search */
    00360     i2c_SlaveHandle_t *apNextSlaveHandle
    00361  );
    00362
    00363 /*
    00364 ** Bus Control Routines
    00365 */
    00366
    00367 /*! @brief       This function starts a bus.
    00368  *
    00369  *  @details.    ::i2c_bus_start() enables an initialized bus to begin communications. This call enables the hardware
    00370  *               peripherals associated with the bus.
    00371  *
    00372  *  @param[in]   apBusHandle The handle of the bus to be started.
    00373  *
    00374  *  @return      ::i2c_bus_start() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00375
    00376  *  @retval      ::ISF_SUCCESS is returned when the bus is started.
    00377  *
    00378  *  @retval      ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized bus.
    00379  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL parameter is passed into the function.
    00380  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period provided during the bus configuration.
    00381  *  @retval      ::COMM_ERROR_LOCK is returned when the internal lock request fails due to an invalid lock on the bus handle.
    00382  *
    00383  *
    00384  *  @Constraints None
    00385  *
    00386  *  @Reentrant   Yes
    00387  *
    00388  *  @Libs        isf_core.lib
    00389  *
    00390  */
    00391 isf_status_t i2c_bus_start(i2c_BusHandle_t *apBusHandle);
    00392
    00393 /*! @brief       This function stops a bus.
    00394  *
    00395  *  @details     ::i2c_bus_stop() disables an initialized bus and stops communications.  This call disables the hardware
    00396  *               peripherals associated with the bus.
    00397  *
    00398  *  @param[in]   apBusHandle   The handle of the bus to be started.
    00399  *  @param[in]   aTimeout      The length of time to wait before returning without the stop. The timeout parameter may
    00400  *               be set to 0 to wait forever, or as long as necessary to stop.
    00401  *
    00402  *  @return  i2c_bus_stop() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00403  *
    00404  *  @retval      ::ISF_SUCCESS is returned when the bus is stopped.
    00405  *
    00406  *  @retval      ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized bus.
    00407  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL parameter is passed into the function.
    00408  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period provided when the bus was configured.
    00409  *  @retval      ::COMM_ERROR_LOCK is returned when the internal lock request fails due to an invalid lock on the bus handle.
    00410  *
    00411  *  @Constraints None
    00412  *
    00413  *  @Reentrant   Yes
    00414  *
    00415  *  @Libs        isf_core.lib
    00416  *
    00417  */
    00418 isf_status_t i2c_bus_stop(i2c_BusHandle_t *apBusHandle, isf_duration_t aTimeout);
    00419
    00420 /*! @brief       This function locks the bus for exclusive access.
    00421  *
    00422  *  @details     ::i2c_bus_acquire_lock() serializes multi-client access to the bus. Each bus user should acquire a bus
    00423  *               lock prior to sending messages on the bus. While holding the bus lock, no other clients may perform any bus messaging.
    00424  *               For this reason, it is important to release the bus lock as soon as practical.
    00425  *
    00426  *  @param[in]   apBusHandle  The handle of the bus to be locked.
    00427  *  @param[in]   aTimeout    The length of time to wait before returning without the lock.  The timeout parameter may
    00428  *               be set to 0 to wait forever, or as long as necessary to get
    00429  *  the lock.
    00430  *
    00431  *  @return      ::i2c_bus_acquire_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00432  *
    00433  *  @retval      ::ISF_SUCCESS is returned if the lock was acquired.
    00434  *
    00435  *  @retval      ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized bus.
    00436  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00437  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL parameter was passed into the function.
    00438  *
    00439  *  @Constraints None
    00440  *
    00441  *  @Reentrant   Yes
    00442  *
    00443  *  @Libs        isf_core.lib
    00444  *
    00445  */
    00446 isf_status_t i2c_bus_acquire_lock(i2c_BusHandle_t *apBusHandle, isf_duration_t aTimeout );
    00447
    00448 /*! @brief       This function releases exclusive access to the bus.
    00449  *
    00450  *  @details     ::i2c_bus_release_lock() relinquishes the bus.
    00451  *
    00452  *  @param[in]   apBusHandle The handle of the bus to be released.
    00453  *
    00454  *  @return      ::i2c_bus_release_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00455  *
    00456  *  @retval      ::ISF_SUCCESS is returned if the bus was successfully released.
    00457  *
    00458  *  @retval      ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized bus.
    00459  *  @retval      ::COMM_ERROR_LOCK is returned when there is no lock held on the specified bus.
    00460  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL parameter was passed into the function.
    00461  *
    00462  *  @Constraints None
    00463  *
    00464  *  @Reentrant   Yes
    00465  *
    00466  *  @Libs        isf_core.lib
    00467  *
    00468  */
    00469 isf_status_t i2c_bus_release_lock(i2c_BusHandle_t *apBusHandle);
    00470
    00471 /*
    00472 ** Bus Transfer Routines
    00473 */
    00474
    00475 /*! @brief      This function reads from an I2C device.
    00476  *
    00477  *  @details    ::i2c_read() reads data from the specified I2C slave device. The supplied command is sent to the slave
    00478  *              device which triggers the device to return some data. Any data returned by the slave is read and placed
    00479  *              in the provided read buffer.
    00480  *
    00481  *  @param[in]  apSlaveHandle   The handle to the slave device from which to read.
    00482  *  @param[in]  apReadCmd       The read command to transmit to the device.
    00483  *  @param[out] apReadBuffer    Address of the buffer in which to place the read data.
    00484  *  @param[in]  aFlags          A set of bit flags controlling the behavior of the read.
    00485  *
    00486  *  @return     ::i2c_read() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00487  *
    00488  *  @retval     ::ISF_SUCCESS is returned if the read is completed successfully.
    00489  *  @retval     ::COMM_ERROR_INIT is returned when the specified slave device is on an uninitialized bus.
    00490  *  @retval     ::COMM_ERROR_BUF_SIZE is returned when either the the number of bytes to read is zero or the provided buffer is too small to hold all the data returned.
    00491  *              If the provided buffer is too small to hold all the data returned, no data is written to the buffer.
    00492  *  @retval     ::COMM_ERROR_STOP is returned when the read is invoked on a STOPPED bus.
    00493  *  @retval     ::COMM_ERROR_NO_ACK is returned when no acknowledgment has been received from the slave device.
    00494  *  @retval     ::COMM_ERROR_NULL_PTR is returned when a NULL parameter was passed into the function.
    00495  *  @retval     ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00496  *  @retval     ::COMM_ERROR_LOCK is returned when the request could not be completed as there is a invalid lock associated with bus.
    00497  *
    00498  *
    00499  *  @Constraints None
    00500  *
    00501  *  @Reentrant   Yes
    00502  *
    00503  *  @Libs        isf_core.lib
    00504  *
    00505  */
    00506 isf_status_t i2c_read(
    00507     i2c_SlaveHandle_t   *apSlaveHandle,
    00508     i2c_Command_t       *apReadCmd,
    00509     i2c_MessageBuffer_t *apReadBuffer,
    00510     i2c_readFlags_t     aFlags
    00511 );
    00512
    00513 /*! @brief       This function writes to an I2C device.
    00514  *
    00515  *   @details    ::i2c_write() writes data to the specified i2c slave device.
    00516  *               The supplied command writes to the slave device.
    00517  *
    00518  *  @param[in]   apSlaveHandle  The handle to which the slave device is to write.
    00519  *  @param[in]   apWriteCmd     The command to send to the device.
    00520  *  @param[in]   aFlags         A set of bit flags controlling the behavior of the write.
    00521  *
    00522  *  @return      ::i2c_write() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00523  *
    00524  *  @retval      ::ISF_SUCCESS is returned when the write command completes successfully.
    00525  *
    00526  *  @retval      ::COMM_ERROR_INIT is returned when the specified slave device is on an uninitialized bus.
    00527  *  @retval      ::COMM_ERROR_STOP is returned when the write is invoked on a STOPPED bus.
    00528  *  @retval      ::COMM_ERROR_NO_ACK is returned when no acknowledgment has been received from the slave device.
    00529  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL parameter was passed into the function.
    00530  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00531  *  @retval      ::COMM_ERROR_LOCK is returned when the request could not be completed as there is a invalid lock associated with the bus.
    00532  *
    00533  *
    00534  *  @Constraints None
    00535  *
    00536  *  @Reentrant   Yes
    00537  *
    00538  *  @Libs        isf_core.lib
    00539  *
    00540  */
    00541 isf_status_t i2c_write(
    00542     i2c_SlaveHandle_t *apSlaveHandle,
    00543     i2c_Command_t     *apWriteCmd,
    00544     i2c_writeFlags_t  aFlags
    00545 );
    00546
    00547 /*! @brief       This function retrieves the bus handle from a slaveHandle.
    00548  *
    00549  *  @details     ::i2c_get_bus_handle() returns the busHandle associated with the bus where the slave resides.
    00550  *
    00551  *  @param[in]   apSlaveHandle Handle of slave device containing the bus handle of interest.
    00552  *
    00553  *  @return      ::i2c_get_bus_handle() returns a value of type ::i2c_BusHandle_t containing the bus handle.
    00554  *
    00555  *  @retval      NULL is returned when the specified slave is invalid.
    00556  *
    00557  *  @Constraints None
    00558  *
    00559  *  @Reentrant   Yes
    00560  *
    00561  *  @Libs        isf_core.lib
    00562  *
    00563  */
    00564 i2c_BusHandle_t* i2c_get_bus_handle( i2c_SlaveHandle_t *apSlaveHandle);
    00565
    00566
    00567 #endif  /* INCLUDE_I2C_TYPES_H */