packages/io/flash/v2_0/include/flash.h

   1 //==========================================================================
   2 //
   3 //      flash.h
   4 //
   5 //      Flash programming - external interfaces
   6 //
   7 //==========================================================================
   8 //####ECOSGPLCOPYRIGHTBEGIN####
   9 // -------------------------------------------
  10 // This file is part of eCos, the Embedded Configurable Operating System.
  11 // Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
  12 // Copyright (C) 2003 Gary Thomas
  13 //
  14 // eCos is free software; you can redistribute it and/or modify it under
  15 // the terms of the GNU General Public License as published by the Free
  16 // Software Foundation; either version 2 or (at your option) any later version.
  17 //
  18 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
  19 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
  20 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  21 // for more details.
  22 //
  23 // You should have received a copy of the GNU General Public License along
  24 // with eCos; if not, write to the Free Software Foundation, Inc.,
  25 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  26 //
  27 // As a special exception, if other files instantiate templates or use macros
  28 // or inline functions from this file, or you compile this file and link it
  29 // with other works to produce a work based on this file, this file does not
  30 // by itself cause the resulting work to be covered by the GNU General Public
  31 // License. However the source code for this file must still be made available
  32 // in accordance with section (3) of the GNU General Public License.
  33 //
  34 // This exception does not invalidate any other reasons why a work based on
  35 // this file might be covered by the GNU General Public License.
  36 //
  37 // Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
  38 // at http://sources.redhat.com/ecos/ecos-license/
  39 // -------------------------------------------
  40 //####ECOSGPLCOPYRIGHTEND####
  41 //==========================================================================
  42 //#####DESCRIPTIONBEGIN####
  43 //
  44 // Author(s):    gthomas
  45 // Contributors: gthomas
  46 // Date:         2000-07-14
  47 // Purpose:
  48 // Description:
  49 //
  50 //####DESCRIPTIONEND####
  51 //
  52 //==========================================================================
  53
  54 #ifndef _IO_FLASH_H_
  55 #define _IO_FLASH_H_
  56
  57 #include <pkgconf/io_flash.h>
  58 #include <cyg/hal/hal_cache.h>
  59
  60 typedef int _printf(const char *fmt, ...);
  61
  62 externC int flash_init(_printf *pf);
  63 externC int flash_erase(void *base, int len, void **err_address);
  64 externC int flash_program(void *flash_base, void *ram_base, int len, void **err_address);
  65 externC int flash_read(void *flash_base, void *ram_base, int len, void **err_address);
  66 externC void flash_dev_query(void *data);
  67 #ifdef CYGHWR_IO_FLASH_BLOCK_LOCKING
  68 externC int flash_lock(void *base, int len, void **err_address);
  69 externC int flash_unlock(void *base, int len, void **err_address);
  70 #endif
  71 externC int flash_verify_addr(void *base);
  72 externC int flash_get_limits(void *base, void **start, void **end);
  73 externC int flash_get_block_info(int *block_size, int *blocks);
  74 externC bool flash_code_overlaps(void *start, void *end);
  75 externC char *flash_errmsg(int err);
  76
  77 #define FLASH_ERR_OK              0x00  // No error - operation complete
  78 #define FLASH_ERR_INVALID         0x01  // Invalid FLASH address
  79 #define FLASH_ERR_ERASE           0x02  // Error trying to erase
  80 #define FLASH_ERR_LOCK            0x03  // Error trying to lock/unlock
  81 #define FLASH_ERR_PROGRAM         0x04  // Error trying to program
  82 #define FLASH_ERR_PROTOCOL        0x05  // Generic error
  83 #define FLASH_ERR_PROTECT         0x06  // Device/region is write-protected
  84 #define FLASH_ERR_NOT_INIT        0x07  // FLASH info not yet initialized
  85 #define FLASH_ERR_HWR             0x08  // Hardware (configuration?) problem
  86 #define FLASH_ERR_ERASE_SUSPEND   0x09  // Device is in erase suspend mode
  87 #define FLASH_ERR_PROGRAM_SUSPEND 0x0a  // Device is in in program suspend mode
  88 #define FLASH_ERR_DRV_VERIFY      0x0b  // Driver failed to verify data
  89 #define FLASH_ERR_DRV_TIMEOUT     0x0c  // Driver timed out waiting for device
  90 #define FLASH_ERR_DRV_WRONG_PART  0x0d  // Driver does not support device
  91 #define FLASH_ERR_LOW_VOLTAGE     0x0e  // Not enough juice to complete job
  92
  93 #ifdef CYGPKG_IO_FLASH_BLOCK_DEVICE
  94 typedef struct {
  95     CYG_ADDRESS offset;
  96     int len;
  97     int flasherr;
  98     void **err_address;
  99 } cyg_io_flash_getconfig_erase_t;
 100
 101 typedef struct {
 102     int dev_size;
 103 } cyg_io_flash_getconfig_devsize_t;
 104
 105 typedef struct {
 106     CYG_ADDRESS offset;
 107     int block_size;
 108 } cyg_io_flash_getconfig_blocksize_t;
 109 #endif
 110
 111 #ifdef _FLASH_PRIVATE_
 112
 113 struct flash_info {
 114     int   block_size;   // Assuming fixed size "blocks"
 115     int   blocks;       // Number of blocks
 116     int   buffer_size;  // Size of write buffer (only defined for some devices)
 117     unsigned long block_mask;
 118     void *start, *end;  // Address range
 119     int   init;
 120     _printf *pf;
 121 };
 122
 123 externC struct flash_info flash_info;
 124 externC int  flash_hwr_init(void);
 125 externC int  flash_hwr_map_error(int err);
 126
 127 //
 128 // Some FLASH devices may require additional support, e.g. to turn on
 129 // appropriate voltage drivers, before any operation.
 130 //
 131 #ifdef  CYGIMP_FLASH_ENABLE
 132 #define FLASH_Enable CYGIMP_FLASH_ENABLE
 133 extern void CYGIMP_FLASH_ENABLE(void *, void *);
 134 #else
 135 #define FLASH_Enable(_start_, _end_)
 136 #endif
 137 #ifdef  CYGIMP_FLASH_DISABLE
 138 #define FLASH_Disable CYGIMP_FLASH_DISABLE
 139 extern void CYGIMP_FLASH_DISABLE(void *, void *);
 140 #else
 141 #define FLASH_Disable(_start_, _end_)
 142 #endif
 143
 144 //
 145 // Some platforms have a DIP switch or jumper that tells the software that
 146 // the flash is write protected.
 147 //
 148 #ifdef CYGSEM_IO_FLASH_SOFT_WRITE_PROTECT
 149 externC cyg_bool plf_flash_query_soft_wp(void *addr, int len);
 150 #endif
 151
 152 //---------------------------------------------------------------------------
 153 // Execution of flash code must be done inside a
 154 // HAL_FLASH_CACHES_OFF/HAL_FLASH_CACHES_ON region - disabling the
 155 // cache on unified cache systems is necessary to prevent burst access
 156 // to the flash area being programmed. With Harvard style caches, only
 157 // the data cache needs to be disabled, but the instruction cache is
 158 // disabled for consistency.
 159
 160 // Targets may provide alternative implementations for these macros in
 161 // the hal_cache.h (or var/plf) files.
 162
 163 // The first part below is a generic, optimal implementation.  The
 164 // second part is the old implementation that has been tested to work
 165 // on some targets - but it is not be suitable for targets that would
 166 // do burst access to the flash (it does not disable the data cache).
 167
 168 // Both implementations must be called with interrupts disabled.
 169
 170 // NOTE: Do _not_ change any of the below macros without checking that
 171 //       the changed code still works on _all_ platforms that rely on these
 172 //       macros. There is no such thing as logical and correct when dealing
 173 //       with different cache and IO models, so _do not_ mess with this code
 174 //       unless you test it properly afterwards.
 175
 176 #ifndef HAL_FLASH_CACHES_OFF
 177
 178 // Some drivers have only been tested with the old macros below.
 179 #ifndef HAL_FLASH_CACHES_OLD_MACROS
 180
 181 #ifdef HAL_CACHE_UNIFIED
 182
 183 // Note: the ucache code has not been tested yet on any target.
 184 #define HAL_FLASH_CACHES_OFF(_d_, _i_)          \
 185     CYG_MACRO_START                             \
 186     _i_ = 0; /* avoids warning */               \
 187     HAL_UCACHE_IS_ENABLED(_d_);                 \
 188     HAL_UCACHE_SYNC();                          \
 189     HAL_UCACHE_INVALIDATE_ALL();                \
 190     HAL_UCACHE_DISABLE();                       \
 191     CYG_MACRO_END
 192
 193 #define HAL_FLASH_CACHES_ON(_d_, _i_)           \
 194     CYG_MACRO_START                             \
 195     if (_d_) HAL_UCACHE_ENABLE();               \
 196     CYG_MACRO_END
 197
 198 #else  // HAL_CACHE_UNIFIED
 199
 200 #define HAL_FLASH_CACHES_OFF(_d_, _i_)          \
 201     CYG_MACRO_START                             \
 202     _i_ = 0; /* avoids warning */               \
 203     HAL_DCACHE_IS_ENABLED(_d_);                 \
 204     HAL_DCACHE_SYNC();                          \
 205     HAL_DCACHE_INVALIDATE_ALL();                \
 206     HAL_DCACHE_DISABLE();                       \
 207     HAL_ICACHE_INVALIDATE_ALL();                \
 208     CYG_MACRO_END
 209
 210 #define HAL_FLASH_CACHES_ON(_d_, _i_)           \
 211     CYG_MACRO_START                             \
 212     if (_d_) HAL_DCACHE_ENABLE();               \
 213     CYG_MACRO_END
 214
 215 #endif // HAL_CACHE_UNIFIED
 216
 217 #else  // HAL_FLASH_CACHES_OLD_MACROS
 218
 219 // Note: This implementation is broken as it will always enable the i-cache
 220 //       even if it was not enabled before. It also doesn't work if the
 221 //       target uses burst access to flash since the d-cache is left enabled.
 222 //       However, this does not mean you can change this code! Leave it as
 223 //       is - if you want a different implementation, provide it in the
 224 //       arch/var/platform cache header file.
 225
 226 #define HAL_FLASH_CACHES_OFF(_d_, _i_)          \
 227     _d_ = 0; /* avoids warning */               \
 228     _i_ = 0; /* avoids warning */               \
 229     HAL_DCACHE_SYNC();                          \
 230     HAL_ICACHE_DISABLE();
 231
 232 #define HAL_FLASH_CACHES_ON(_d_, _i_)           \
 233     HAL_ICACHE_ENABLE();
 234
 235 #endif  // HAL_FLASH_CACHES_OLD_MACROS
 236
 237 #endif  // HAL_FLASH_CACHES_OFF
 238
 239 #endif  // _FLASH_PRIVATE_
 240
 241 #endif  // _IO_FLASH_H_