ISF  1.1
Intelligent Sensing Framework
 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 */