Devin Heitmueller | ca3355a | 2010-07-04 18:42:11 -0300 | [diff] [blame] | 1 | /* |
| 2 | Copyright (c), 2004-2005,2007-2010 Trident Microsystems, Inc. |
| 3 | All rights reserved. |
| 4 | |
| 5 | Redistribution and use in source and binary forms, with or without |
| 6 | modification, are permitted provided that the following conditions are met: |
| 7 | |
| 8 | * Redistributions of source code must retain the above copyright notice, |
| 9 | this list of conditions and the following disclaimer. |
| 10 | * Redistributions in binary form must reproduce the above copyright notice, |
| 11 | this list of conditions and the following disclaimer in the documentation |
| 12 | and/or other materials provided with the distribution. |
| 13 | * Neither the name of Trident Microsystems nor Hauppauge Computer Works |
| 14 | nor the names of its contributors may be used to endorse or promote |
| 15 | products derived from this software without specific prior written |
| 16 | permission. |
| 17 | |
| 18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| 19 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 20 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 21 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
| 22 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| 23 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| 24 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| 25 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| 26 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| 27 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| 28 | POSSIBILITY OF SUCH DAMAGE. |
| 29 | */ |
| 30 | |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 31 | /** |
| 32 | * \file $Id: bsp_i2c.h,v 1.5 2009/07/07 14:20:30 justin Exp $ |
| 33 | * |
| 34 | * \brief I2C API, implementation depends on board specifics |
| 35 | * |
| 36 | * This module encapsulates I2C access.In some applications several devices |
| 37 | * share one I2C bus. If these devices have the same I2C address some kind |
| 38 | * off "switch" must be implemented to ensure error free communication with |
| 39 | * one device. In case such a "switch" is used, the device ID can be used |
| 40 | * to implement control over this "switch". |
| 41 | * |
| 42 | * |
| 43 | */ |
| 44 | |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 45 | #ifndef __BSPI2C_H__ |
| 46 | #define __BSPI2C_H__ |
| 47 | /*------------------------------------------------------------------------------ |
| 48 | INCLUDES |
| 49 | ------------------------------------------------------------------------------*/ |
| 50 | #include "bsp_types.h" |
| 51 | |
| 52 | #ifdef __cplusplus |
| 53 | extern "C" { |
| 54 | #endif |
| 55 | /*------------------------------------------------------------------------------ |
| 56 | TYPEDEFS |
| 57 | ------------------------------------------------------------------------------*/ |
| 58 | /** |
| 59 | * \typedef I2Caddr_t |
| 60 | * \brief I2C device address (7-bit or 10-bit) |
| 61 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 62 | typedef u16_t I2Caddr_t; |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 63 | |
| 64 | /** |
| 65 | * \typedef I2CdevId_t |
| 66 | * \brief Device identifier. |
| 67 | * |
| 68 | * The device ID can be useful if several devices share an I2C address, |
| 69 | * or if multiple I2C busses are used. |
| 70 | * It can be used to control a "switch" selecting the correct device and/or |
| 71 | * I2C bus. |
| 72 | * |
| 73 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 74 | typedef u16_t I2CdevId_t; |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 75 | |
| 76 | /** |
| 77 | * \struct _I2CDeviceAddr_t |
| 78 | * \brief I2C device parameters. |
| 79 | * |
| 80 | * This structure contains the I2C address, the device ID and a userData pointer. |
| 81 | * The userData pointer can be used for application specific purposes. |
| 82 | * |
| 83 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 84 | struct _I2CDeviceAddr_t { |
| 85 | I2Caddr_t i2cAddr; |
| 86 | /**< The I2C address of the device. */ |
| 87 | I2CdevId_t i2cDevId; |
| 88 | /**< The device identifier. */ |
| 89 | void *userData; |
| 90 | /**< User data pointer */ |
| 91 | }; |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 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 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 100 | typedef struct _I2CDeviceAddr_t I2CDeviceAddr_t; |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 101 | |
| 102 | /** |
| 103 | * \typedef pI2CDeviceAddr_t |
| 104 | * \brief Pointer to I2C device parameters. |
| 105 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 106 | typedef I2CDeviceAddr_t *pI2CDeviceAddr_t; |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 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 | |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 139 | /** |
| 140 | * \fn DRXBSP_I2C_Init() |
| 141 | * \brief Initialize I2C communication module. |
| 142 | * \return DRXStatus_t Return status. |
| 143 | * \retval DRX_STS_OK Initialization successful. |
| 144 | * \retval DRX_STS_ERROR Initialization failed. |
| 145 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 146 | DRXStatus_t DRXBSP_I2C_Init(void); |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 147 | |
| 148 | /** |
| 149 | * \fn DRXBSP_I2C_Term() |
| 150 | * \brief Terminate I2C communication module. |
| 151 | * \return DRXStatus_t Return status. |
| 152 | * \retval DRX_STS_OK Termination successful. |
| 153 | * \retval DRX_STS_ERROR Termination failed. |
| 154 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 155 | DRXStatus_t DRXBSP_I2C_Term(void); |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 156 | |
| 157 | /** |
| 158 | * \fn DRXStatus_t DRXBSP_I2C_WriteRead( pI2CDeviceAddr_t wDevAddr, |
| 159 | * u16_t wCount, |
| 160 | * pu8_t wData, |
| 161 | * pI2CDeviceAddr_t rDevAddr, |
| 162 | * u16_t rCount, |
| 163 | * pu8_t rData) |
| 164 | * \brief Read and/or write count bytes from I2C bus, store them in data[]. |
| 165 | * \param wDevAddr The device i2c address and the device ID to write to |
| 166 | * \param wCount The number of bytes to write |
| 167 | * \param wData The array to write the data to |
| 168 | * \param rDevAddr The device i2c address and the device ID to read from |
| 169 | * \param rCount The number of bytes to read |
| 170 | * \param rData The array to read the data from |
| 171 | * \return DRXStatus_t Return status. |
| 172 | * \retval DRX_STS_OK Succes. |
| 173 | * \retval DRX_STS_ERROR Failure. |
| 174 | * \retval DRX_STS_INVALID_ARG Parameter 'wcount' is not zero but parameter |
| 175 | * 'wdata' contains NULL. |
| 176 | * Idem for 'rcount' and 'rdata'. |
| 177 | * Both wDevAddr and rDevAddr are NULL. |
| 178 | * |
| 179 | * This function must implement an atomic write and/or read action on the I2C bus |
| 180 | * No other process may use the I2C bus when this function is executing. |
| 181 | * The critical section of this function runs from and including the I2C |
| 182 | * write, up to and including the I2C read action. |
| 183 | * |
| 184 | * The device ID can be useful if several devices share an I2C address. |
| 185 | * It can be used to control a "switch" on the I2C bus to the correct device. |
| 186 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 187 | DRXStatus_t DRXBSP_I2C_WriteRead(pI2CDeviceAddr_t wDevAddr, |
| 188 | u16_t wCount, |
| 189 | pu8_t wData, |
| 190 | pI2CDeviceAddr_t rDevAddr, |
| 191 | u16_t rCount, pu8_t rData); |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 192 | |
| 193 | /** |
| 194 | * \fn DRXBSP_I2C_ErrorText() |
| 195 | * \brief Returns a human readable error. |
| 196 | * Counter part of numerical DRX_I2C_Error_g. |
| 197 | * |
| 198 | * \return char* Pointer to human readable error text. |
| 199 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 200 | char *DRXBSP_I2C_ErrorText(void); |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 201 | |
| 202 | /** |
| 203 | * \var DRX_I2C_Error_g; |
| 204 | * \brief I2C specific error codes, platform dependent. |
| 205 | */ |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 206 | extern int DRX_I2C_Error_g; |
Devin Heitmueller | 38b2df9 | 2012-08-13 21:18:02 -0300 | [diff] [blame] | 207 | |
| 208 | /*------------------------------------------------------------------------------ |
| 209 | THE END |
| 210 | ------------------------------------------------------------------------------*/ |
| 211 | #ifdef __cplusplus |
| 212 | } |
| 213 | #endif |
Mauro Carvalho Chehab | 443f18d | 2012-03-20 00:00:42 -0300 | [diff] [blame^] | 214 | #endif /* __BSPI2C_H__ */ |