drivers/media/dvb-frontends/drx39xyj/bsp_i2c.h

   1 /**
   2 * \file $Id: bsp_i2c.h,v 1.5 2009/07/07 14:20:30 justin Exp $
   3 *
   4 * \brief I2C API, implementation depends on board specifics
   5 *
   6 * This module encapsulates I2C access.In some applications several devices
   7 * share one I2C bus. If these devices have the same I2C address some kind
   8 * off "switch" must be implemented to ensure error free communication with
   9 * one device.  In case such a "switch" is used, the device ID can be used
  10 * to implement control over this "switch".
  11 *
  12 *
  13 */
  14
  15 /*
  16 * $(c) 2004-2005,2008-2009 Trident Microsystems, Inc. - All rights reserved.
  17 *
  18 * This software and related documentation (the 'Software') are intellectual
  19 * property owned by Trident and are copyright of Trident, unless specifically
  20 * noted otherwise.
  21 *
  22 * Any use of the Software is permitted only pursuant to the terms of the
  23 * license agreement, if any, which accompanies, is included with or applicable
  24 * to the Software ('License Agreement') or upon express written consent of
  25 * Trident. Any copying, reproduction or redistribution of the Software in
  26 * whole or in part by any means not in accordance with the License Agreement
  27 * or as agreed in writing by Trident is expressly prohibited.
  28 *
  29 * THE SOFTWARE IS WARRANTED, IF AT ALL, ONLY ACCORDING TO THE TERMS OF THE
  30 * LICENSE AGREEMENT. EXCEPT AS WARRANTED IN THE LICENSE AGREEMENT THE SOFTWARE
  31 * IS DELIVERED 'AS IS' AND TRIDENT HEREBY DISCLAIMS ALL WARRANTIES AND
  32 * CONDITIONS WITH REGARD TO THE SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES
  33 * AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIT
  34 * ENJOYMENT, TITLE AND NON-INFRINGEMENT OF ANY THIRD PARTY INTELLECTUAL
  35 * PROPERTY OR OTHER RIGHTS WHICH MAY RESULT FROM THE USE OR THE INABILITY
  36 * TO USE THE SOFTWARE.
  37 *
  38 * IN NO EVENT SHALL TRIDENT BE LIABLE FOR INDIRECT, INCIDENTAL, CONSEQUENTIAL,
  39 * PUNITIVE, SPECIAL OR OTHER DAMAGES WHATSOEVER INCLUDING WITHOUT LIMITATION,
  40 * DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
  41 * INFORMATION, AND THE LIKE, ARISING OUT OF OR RELATING TO THE USE OF OR THE
  42 * INABILITY TO USE THE SOFTWARE, EVEN IF TRIDENT HAS BEEN ADVISED OF THE
  43 * POSSIBILITY OF SUCH DAMAGES, EXCEPT PERSONAL INJURY OR DEATH RESULTING FROM
  44 * TRIDENT'S NEGLIGENCE.                                                        $
  45 *
  46 */
  47
  48 #ifndef __BSPI2C_H__
  49 #define __BSPI2C_H__
  50 /*------------------------------------------------------------------------------
  51 INCLUDES
  52 ------------------------------------------------------------------------------*/
  53 #include "bsp_types.h"
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58 /*------------------------------------------------------------------------------
  59 TYPEDEFS
  60 ------------------------------------------------------------------------------*/
  61 /**
  62 * \typedef I2Caddr_t
  63 * \brief I2C device address (7-bit or 10-bit)
  64 */
  65 typedef u16_t I2Caddr_t;
  66
  67 /**
  68 * \typedef I2CdevId_t
  69 * \brief Device identifier.
  70 *
  71 * The device ID can be useful if several devices share an I2C address,
  72 * or if multiple I2C busses are used.
  73 * It can be used to control a "switch" selecting the correct device and/or
  74 * I2C bus.
  75 *
  76 */
  77 typedef u16_t I2CdevId_t;
  78
  79 /**
  80 * \struct _I2CDeviceAddr_t
  81 * \brief I2C device parameters.
  82 *
  83 * This structure contains the I2C address, the device ID and a userData pointer.
  84 * The userData pointer can be used for application specific purposes.
  85 *
  86 */
  87 struct _I2CDeviceAddr_t {
  88    I2Caddr_t  i2cAddr;        /**< The I2C address of the device. */
  89    I2CdevId_t i2cDevId;       /**< The device identifier. */
  90    void       *userData;      /**< User data pointer */
  91 };
  92
  93 /**
  94 * \typedef I2CDeviceAddr_t
  95 * \brief I2C device parameters.
  96 *
  97 * This structure contains the I2C address and the device ID.
  98 *
  99 */
 100 typedef struct _I2CDeviceAddr_t I2CDeviceAddr_t;
 101
 102 /**
 103 * \typedef pI2CDeviceAddr_t
 104 * \brief Pointer to I2C device parameters.
 105 */
 106 typedef I2CDeviceAddr_t *pI2CDeviceAddr_t;
 107
 108 /*------------------------------------------------------------------------------
 109 DEFINES
 110 ------------------------------------------------------------------------------*/
 111
 112 /*------------------------------------------------------------------------------
 113 MACROS
 114 ------------------------------------------------------------------------------*/
 115
 116 /**
 117 * \def IS_I2C_10BIT( addr )
 118 * \brief Determine if I2C address 'addr' is a 10 bits address or not.
 119 * \param addr The I2C address.
 120 * \return int.
 121 * \retval 0 if address is not a 10 bits I2C address.
 122 * \retval 1 if address is a 10 bits I2C address.
 123 */
 124 #define IS_I2C_10BIT(addr) \
 125          (((addr) & 0xF8) == 0xF0)
 126
 127 /*------------------------------------------------------------------------------
 128 ENUM
 129 ------------------------------------------------------------------------------*/
 130
 131 /*------------------------------------------------------------------------------
 132 STRUCTS
 133 ------------------------------------------------------------------------------*/
 134
 135 /*------------------------------------------------------------------------------
 136 Exported FUNCTIONS
 137 ------------------------------------------------------------------------------*/
 138
 139
 140 /**
 141 * \fn DRXBSP_I2C_Init()
 142 * \brief Initialize I2C communication module.
 143 * \return DRXStatus_t Return status.
 144 * \retval DRX_STS_OK Initialization successful.
 145 * \retval DRX_STS_ERROR Initialization failed.
 146 */
 147 DRXStatus_t DRXBSP_I2C_Init( void );
 148
 149
 150 /**
 151 * \fn DRXBSP_I2C_Term()
 152 * \brief Terminate I2C communication module.
 153 * \return DRXStatus_t Return status.
 154 * \retval DRX_STS_OK Termination successful.
 155 * \retval DRX_STS_ERROR Termination failed.
 156 */
 157 DRXStatus_t DRXBSP_I2C_Term( void );
 158
 159 /**
 160 * \fn DRXStatus_t DRXBSP_I2C_WriteRead( pI2CDeviceAddr_t wDevAddr,
 161 *                                       u16_t wCount,
 162 *                                       pu8_t wData,
 163 *                                       pI2CDeviceAddr_t rDevAddr,
 164 *                                       u16_t rCount,
 165 *                                       pu8_t rData)
 166 * \brief Read and/or write count bytes from I2C bus, store them in data[].
 167 * \param wDevAddr The device i2c address and the device ID to write to
 168 * \param wCount   The number of bytes to write
 169 * \param wData    The array to write the data to
 170 * \param rDevAddr The device i2c address and the device ID to read from
 171 * \param rCount   The number of bytes to read
 172 * \param rData    The array to read the data from
 173 * \return DRXStatus_t Return status.
 174 * \retval DRX_STS_OK Succes.
 175 * \retval DRX_STS_ERROR Failure.
 176 * \retval DRX_STS_INVALID_ARG Parameter 'wcount' is not zero but parameter
 177 *                                       'wdata' contains NULL.
 178 *                                       Idem for 'rcount' and 'rdata'.
 179 *                                       Both wDevAddr and rDevAddr are NULL.
 180 *
 181 * This function must implement an atomic write and/or read action on the I2C bus
 182 * No other process may use the I2C bus when this function is executing.
 183 * The critical section of this function runs from and including the I2C
 184 * write, up to and including the I2C read action.
 185 *
 186 * The device ID can be useful if several devices share an I2C address.
 187 * It can be used to control a "switch" on the I2C bus to the correct device.
 188 */
 189 DRXStatus_t DRXBSP_I2C_WriteRead(   pI2CDeviceAddr_t wDevAddr,
 190                                     u16_t            wCount,
 191                                     pu8_t            wData,
 192                                     pI2CDeviceAddr_t rDevAddr,
 193                                     u16_t            rCount,
 194                                     pu8_t            rData);
 195
 196
 197 /**
 198 * \fn DRXBSP_I2C_ErrorText()
 199 * \brief Returns a human readable error.
 200 * Counter part of numerical DRX_I2C_Error_g.
 201 *
 202 * \return char* Pointer to human readable error text.
 203 */
 204 char* DRXBSP_I2C_ErrorText( void );
 205
 206 /**
 207 * \var DRX_I2C_Error_g;
 208 * \brief I2C specific error codes, platform dependent.
 209 */
 210 extern int DRX_I2C_Error_g;
 211
 212
 213 /*------------------------------------------------------------------------------
 214 THE END
 215 ------------------------------------------------------------------------------*/
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219 #endif /* __BSPI2C_H__ */