vl6180_i2c_fn.h

00001 /*******************************************************************************
00002 Copyright © 2019, STMicroelectronics International N.V.
00003 All rights reserved.
00004 
00005 Redistribution and use in source and binary forms, with or without
00006 modification, are permitted provided that the following conditions are met:
00007     * Redistributions of source code must retain the above copyright
00008       notice, this list of conditions and the following disclaimer.
00009     * Redistributions in binary form must reproduce the above copyright
00010       notice, this list of conditions and the following disclaimer in the
00011       documentation and/or other materials provided with the distribution.
00012     * Neither the name of STMicroelectronics nor the
00013       names of its contributors may be used to endorse or promote products
00014       derived from this software without specific prior written permission.
00015 
00016 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00017 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00018 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
00019 NON-INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS ARE DISCLAIMED. 
00020 IN NO EVENT SHALL STMICROELECTRONICS INTERNATIONAL N.V. BE LIABLE FOR ANY
00021 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00022 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00023 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00024 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00025 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00026 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027 ********************************************************************************/
00028  
00029 /**
00030  * @file vl6180_i2c.h
00031  *
00032  * @brief  CCI interface to "raw i2c" translation layer
00033  */
00034 
00035 #ifndef VL6180_I2C_fn_H_
00036 #define VL6180_I2C_fn_H_
00037 
00038 #include "vl6180_platform.h"
00039 
00040 /**
00041  * @defgroup cci_i2c  CCI to RAW I2C translation layer
00042  *
00043  * This optional tranlation layer is implemented in __platform/cci-i2c__ directory. If user uses this translation layer for his platform, only @a VL6180_I2CRead() and
00044  * @a VL6180_I2CWrite() functions need to be implemented. Also, some code adaption (via macro) is required for multi-threading and for multiple device support.
00045  *
00046  * File vl6180_i2c.c implements device register access via raw i2c access. If the targeted application and platform has no multi-thread,  no multi-cpu and uses single
00047  * device, then nothing else is required than the 2 mandatory function : @a VL6180_I2CRead() and @a VL6180_I2CWrite().\n
00048  * In other cases, review and customize @a VL6180_GetI2CAccess() and @a VL6180_DoneI2CAccess() functions as well as @a #VL6180_I2C_USER_VAR macro. This should be enough
00049  * to conform to a wide range of platform OS and application requirements .\n
00050  *
00051  * If your configured i2c for per device buffer via  @a #I2C_BUFFER_CONFIG == 2, you must implement @a VL6180_GetI2cBuffer()
00052  *
00053  * __I2C Port sample__ \n
00054  * A __linux kernel__ port need a "long flags" var for its spin_lock in all functions. the following code example declares a spin lock "lock" in the custom device structure. \n
00055  * @code
00056 struct MyVL6180Dev_t {
00057      struct VL6180DevData_t StData;
00058      ...
00059      spinlock_t i2c_lock;
00060 };
00061 typedef struct MyVL6180Dev_t *VL6180Dev_t;
00062 
00063 #define VL6180_I2C_USER_VAR   unsigned long flags;
00064 #define GetI2CAccess(dev)      spin_lock_irqsave(dev->i2c_lock, flags)
00065 #define DoneI2CAccess(dev)     spin_unlock_irqrestore(dev->i2c_lock,flags)
00066 @endcode
00067 
00068 *  __POSIX pthread__ application porting could be as follows :\n
00069 * @code
00070 struct MyVL6180Dev_t {
00071     struct VL6180DevData_t StData;
00072     ...
00073     pthread_mutex_t *lock;
00074 };
00075 typedef struct MyVL6180Dev_t *VL6180Dev_t;
00076 
00077 #define VL6180_I2C_USER_VAR        //no need
00078 #define VL6180_GetI2CAccess(dev)   pthread_mutex_lock(dev->lock)
00079 #define VL6180_DoneI2CAcces(dev)   pthread_mutex_unlock(dev->lock)
00080  * @endcode
00081  */
00082 
00083 /**
00084  * @def I2C_BUFFER_CONFIG
00085  *
00086  * @brief Configure device register I2C access
00087  *
00088  * @li 0 : one GLOBAL buffer \n
00089  *   Use one global buffer of MAX_I2C_XFER_SIZE byte in data space \n
00090  *   This solution is not multi-device compliant nor multi-thread cpu safe \n
00091  *   It can be the best option for small 8/16 bit MCU without stack and limited ram  (STM8s, 80C51 ...)
00092  *
00093  * @li 1 : ON_STACK/local \n
00094  *   Use local variable (on stack) buffer \n
00095  *   This solution is multi-thread with use of i2c resource lock or mutex see @a VL6180_GetI2CAccess() \n
00096  *
00097  * @li 2 : User defined \n
00098  *    Per device potentially dynamic allocated. Requires @a VL6180_GetI2cBuffer() to be implemented.
00099  * @ingroup Configuration
00100  */
00101 #define I2C_BUFFER_CONFIG 1
00102 
00103 /**
00104  * @brief       Write data buffer to VL6180 device via i2c
00105  * @param dev   The device to write to
00106  * @param buff  The data buffer
00107  * @param len   The length of the transaction in byte
00108  * @return      0 on success
00109  * @ingroup cci_i2c
00110  */
00111 int  VL6180_I2CWrite(VL6180Dev_t dev, uint8_t  *buff, uint8_t len);
00112 
00113 /**
00114  *
00115  * @brief       Read data buffer from VL6180 device via i2c
00116  * @param dev   The device to read from
00117  * @param buff  The data buffer to fill
00118  * @param len   The length of the transaction in byte
00119  * @return      0 on success
00120  * @ingroup  cci_i2c
00121  */
00122 int VL6180_I2CRead(VL6180Dev_t dev, uint8_t *buff, uint8_t len);
00123 
00124 
00125 /**
00126  * @brief Declare any required variables used by i2c lock (@a VL6180_DoneI2CAccess() and @a VL6180_GetI2CAccess())
00127  * and buffer access : @a VL6180_GetI2cBuffer()
00128  *
00129  * @ingroup cci_i2c
00130  */
00131 #define VL6180_I2C_USER_VAR
00132 
00133 /**
00134  *  @brief Acquire lock or mutex for access to i2c data buffer and bus.\n
00135  *  Delete the default VL6180_GetI2CAccess 'do-nothing' macro below if you decide to implement this function.
00136  *
00137  *  This function is used to perform i2c bus level and multiple access locking required for multi thread/proccess system.\n
00138  *  Multiple access (read and update) will lock once and do multiple basic i2c rd/wr to complete the overall transfer.\n
00139  *  When no locking is needed this can be a void macro.\n
00140  *
00141  * @param dev  the device
00142  * @ingroup cci_i2c
00143  */
00144 void VL6180_GetI2CAccess(VL6180Dev_t dev);
00145 
00146 /**
00147  * @def VL6180_GetI2CAccess
00148  * @brief Default 'do-nothing' macro for @a VL6180_GetI2CAccess(). Delete if used.
00149  * @ingroup cci_i2c
00150  */
00151 #define VL6180_GetI2CAccess(dev) (void)0 /* TODO delete if function used */
00152 
00153 /**
00154  * @brief Release acquired lock or mutex for i2c access.\n
00155  * Delete default VL6180_DoneI2CAccess 'do-nothing' macro below if implementing that function.
00156  *
00157  * This function is used to release the acquired lock.
00158  * @param dev The device
00159  * @ingroup cci_i2c
00160  */
00161 void VL6180_DoneI2CAccess(VL6180Dev_t dev);
00162 
00163 /** @def VL6180_DoneI2CAcces
00164  * @brief Default 'do-nothing' macro for @a VL6180_DoneI2CAcces(). Delete if used.
00165  * @ingroup cci_i2c
00166  */
00167 #define VL6180_DoneI2CAcces(dev) (void)0  /*TODO delete  if function used */
00168 
00169 /**
00170  * @brief Provided data buffer for i2c access for at least n_byte.
00171  *
00172  * You must implement it when i2c @a #I2C_BUFFER_CONFIG is set to 2 (User defined).\n
00173  * This is used used in the context of #VL6180_I2C_USER_VAR
00174  *
00175  * @param dev     The device
00176  * @param n_byte  Minimal number of byte
00177  * @return        The buffer (cannot fail return not checked)
00178  * @ingroup cci_i2c
00179  */
00180 uint8_t *VL6180_GetI2cBuffer(VL6180Dev_t dev, int n_byte);
00181 #if I2C_BUFFER_CONFIG == 2
00182 #error /* TODO add your macro of code here for VL6180_GetI2cBuffer */
00183 #endif
00184 
00185 
00186 
00187 
00188 
00189 #endif /* VL6180_I2C_H_ */
00190