packages/io/i2c/v2_0/include/i2c.h

   1 #ifndef CYGONCE_IO_I2C_H
   2 #define CYGONCE_IO_I2C_H
   3
   4 //=============================================================================
   5 //
   6 //      i2c.h
   7 //
   8 //      Generic API for accessing devices on an I2C bus
   9 //
  10 //=============================================================================
  11 //####ECOSGPLCOPYRIGHTBEGIN####
  12 // -------------------------------------------
  13 // This file is part of eCos, the Embedded Configurable Operating System.
  14 // Copyright (C) 2004 eCosCentric Limited
  15 //
  16 // eCos is free software; you can redistribute it and/or modify it under
  17 // the terms of the GNU General Public License as published by the Free
  18 // Software Foundation; either version 2 or (at your option) any later version.
  19 //
  20 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
  21 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
  22 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  23 // for more details.
  24 //
  25 // You should have received a copy of the GNU General Public License along
  26 // with eCos; if not, write to the Free Software Foundation, Inc.,
  27 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  28 //
  29 // As a special exception, if other files instantiate templates or use macros
  30 // or inline functions from this file, or you compile this file and link it
  31 // with other works to produce a work based on this file, this file does not
  32 // by itself cause the resulting work to be covered by the GNU General Public
  33 // License. However the source code for this file must still be made available
  34 // in accordance with section (3) of the GNU General Public License.
  35 //
  36 // This exception does not invalidate any other reasons why a work based on
  37 // this file might be covered by the GNU General Public License.
  38 // -------------------------------------------
  39 //####ECOSGPLCOPYRIGHTEND####
  40 //=============================================================================
  41 //####DESCRIPTIONBEGIN####
  42 //
  43 // Author(s):   bartv
  44 // Date:            2004-10-05
  45 //####DESCRIPTIONEND####
  46 //=============================================================================
  47
  48 #include <pkgconf/infra.h>
  49 #include <cyg/infra/cyg_type.h>
  50 #include <cyg/hal/drv_api.h>
  51 #include <cyg/hal/hal_tables.h>
  52 #include <cyg/hal/hal_io.h>
  53
  54 // The information needed for interacting with a specific I2C device.
  55 // The bus provides the tx and rx functions. The address is (usually)
  56 // a 7-bit number sent at the start of each operation. The flags is
  57 // not currently used, but provides room for future expansion such as
  58 // 10-bit addresses. The delay should be a clock period in
  59 // nanoseconds. For the default 100KHz clock that gives a value of
  60 // 10000
  61
  62 typedef struct cyg_i2c_device {
  63     struct cyg_i2c_bus* i2c_bus;
  64     cyg_uint16          i2c_address;
  65     cyg_uint16          i2c_flags;
  66     cyg_uint32          i2c_delay;
  67 } cyg_i2c_device;
  68
  69 #define CYG_I2C_DEFAULT_DELAY   10000
  70
  71 // A utility macro for defining an I2C device
  72 #define CYG_I2C_DEVICE(_name_, _bus_, _address_, _flags_, _delay_)  \
  73     cyg_i2c_device _name_ = {                                       \
  74         .i2c_bus        = _bus_,                                    \
  75         .i2c_address    = _address_,                                \
  76         .i2c_flags      = _flags_,                                  \
  77         .i2c_delay      = _delay_                                   \
  78     }
  79
  80 // The information needed for interacting over a particular I2C bus.
  81 // Most hardware will only have one bus, but multiple buses are
  82 // supported. Thread synchronization happens on a per-bus level.
  83 typedef struct cyg_i2c_bus {
  84     cyg_drv_mutex_t         i2c_lock;
  85 #ifdef CYGDBG_USE_ASSERTS
  86     const cyg_i2c_device*   i2c_current_device;
  87 #endif
  88     // The hardware-specific functions that do the real work
  89     void                    (*i2c_init_fn)(struct cyg_i2c_bus*);
  90     cyg_uint32              (*i2c_tx_fn)(const cyg_i2c_device*, cyg_bool, const cyg_uint8*, cyg_uint32, cyg_bool);
  91     cyg_uint32              (*i2c_rx_fn)(const cyg_i2c_device*, cyg_bool, cyg_uint8*, cyg_uint32, cyg_bool, cyg_bool);
  92     void                    (*i2c_stop_fn)(const cyg_i2c_device*);
  93     // A spare field for use by the driver
  94     void*                   i2c_extra;
  95 } CYG_HAL_TABLE_TYPE cyg_i2c_bus;
  96
  97 #define CYG_I2C_BUS(_name_, _init_fn_, _tx_fn_, _rx_fn_, _stop_fn_, _extra_)    \
  98     cyg_i2c_bus _name_  CYG_HAL_TABLE_ENTRY( i2c_buses ) = {                    \
  99         .i2c_init_fn    = _init_fn_,                                            \
 100         .i2c_tx_fn      = _tx_fn_,                                              \
 101         .i2c_rx_fn      = _rx_fn_,                                              \
 102         .i2c_stop_fn    = _stop_fn_,                                            \
 103         .i2c_extra      = _extra_                                               \
 104     }
 105
 106 // To support static initialization all buses are held in a table.
 107 // Of course usually this table will only contain a single entry
 108 extern cyg_i2c_bus cyg_i2c_buses[], cyg_i2c_buses_end;
 109
 110 // The main exported interface. There are high-level operations for
 111 // simple transmits and receives, and transaction-oriented routines
 112 // for more complicated operations including those involving repeated
 113 // starts.
 114 externC cyg_uint32  cyg_i2c_tx(const cyg_i2c_device*, const cyg_uint8*, cyg_uint32);
 115 externC cyg_uint32  cyg_i2c_rx(const cyg_i2c_device*, cyg_uint8*, cyg_uint32);
 116 externC void        cyg_i2c_transaction_begin(const cyg_i2c_device*);
 117 externC cyg_bool    cyg_i2c_transaction_begin_nb(const cyg_i2c_device*);
 118 externC cyg_uint32  cyg_i2c_transaction_tx(const cyg_i2c_device*, cyg_bool, const cyg_uint8*, cyg_uint32, cyg_bool);
 119 externC cyg_uint32  cyg_i2c_transaction_rx(const cyg_i2c_device*, cyg_bool, cyg_uint8*, cyg_uint32, cyg_bool, cyg_bool);
 120 externC void        cyg_i2c_transaction_stop(const cyg_i2c_device*);
 121 externC void        cyg_i2c_transaction_end(const cyg_i2c_device*);
 122
 123 // Bit-bang support. This merely requires the platform HAL to provide
 124 // a function for the actual bit-bang operation. The rest is handled
 125 // by the generic code.
 126 typedef enum cyg_i2c_bitbang_op {
 127     CYG_I2C_BITBANG_INIT                    = 0,
 128     CYG_I2C_BITBANG_SCL_HIGH                = 1,
 129     CYG_I2C_BITBANG_SCL_LOW                 = 2,
 130     CYG_I2C_BITBANG_SCL_HIGH_CLOCKSTRETCH   = 3,
 131     CYG_I2C_BITBANG_SCL_LOW_SDA_INPUT       = 4,
 132     CYG_I2C_BITBANG_SDA_OUTPUT              = 5,
 133     CYG_I2C_BITBANG_SDA_HIGH                = 6,
 134     CYG_I2C_BITBANG_SDA_LOW                 = 7,
 135     CYG_I2C_BITBANG_SDA_READ                = 8
 136 } cyg_i2c_bitbang_op;
 137
 138 typedef cyg_bool (*cyg_i2c_bitbang_fn)(cyg_i2c_bus*, cyg_i2c_bitbang_op);
 139
 140 // A bitbang bus can be instantiated by just providing the bitbang function.
 141 // That is held in the extra field.
 142 #define CYG_I2C_BITBANG_BUS(_name_, _bitbang_fn_)                   \
 143     CYG_I2C_BUS(_name_,                                             \
 144                 &cyg_i2c_bitbang_init,                              \
 145                 &cyg_i2c_bitbang_tx,                                \
 146                 &cyg_i2c_bitbang_rx,                                \
 147                 &cyg_i2c_bitbang_stop,                              \
 148                 (void*) _bitbang_fn_)
 149
 150 // The generic bit-bang functions. These are not called directly,
 151 // but must be exported for use by the above macro.
 152 externC void        cyg_i2c_bitbang_init(cyg_i2c_bus*);
 153 externC cyg_uint32  cyg_i2c_bitbang_tx(const cyg_i2c_device*, cyg_bool, const cyg_uint8*, cyg_uint32, cyg_bool);
 154 externC cyg_uint32  cyg_i2c_bitbang_rx(const cyg_i2c_device*, cyg_bool, cyg_uint8*, cyg_uint32, cyg_bool, cyg_bool);
 155 externC void        cyg_i2c_bitbang_stop(const cyg_i2c_device*);
 156
 157 // Allow the HAL to export the buses and named devices. There are
 158 // circular dependencies between this header and the HAL ones so
 159 // it is not easy for the HAL headers to define cyg_i2c_device
 160 // externs directly. Instead the HAL can define this macro which
 161 // provides the externs.
 162 #ifdef HAL_I2C_EXPORTED_DEVICES
 163   HAL_I2C_EXPORTED_DEVICES
 164 #endif
 165
 166 //-----------------------------------------------------------------------------
 167 #endif // ifndef CYGONCE_IO_I2C_H
 168 // End of i2c.h