1 //==========================================================================
5 // Flash programming - external interfaces
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
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.
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
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.
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.
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.
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####
45 // Contributors: gthomas
50 //####DESCRIPTIONEND####
52 //==========================================================================
57 #include <pkgconf/io_flash.h>
58 #include <cyg/hal/hal_cache.h>
60 typedef int _printf(const char *fmt, ...);
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);
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);
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
93 #ifdef CYGPKG_IO_FLASH_BLOCK_DEVICE
99 } cyg_io_flash_getconfig_erase_t;
103 } cyg_io_flash_getconfig_devsize_t;
108 } cyg_io_flash_getconfig_blocksize_t;
111 #ifdef _FLASH_PRIVATE_
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
123 externC struct flash_info flash_info;
124 externC int flash_hwr_init(void);
125 externC int flash_hwr_map_error(int err);
128 // Some FLASH devices may require additional support, e.g. to turn on
129 // appropriate voltage drivers, before any operation.
131 #ifdef CYGIMP_FLASH_ENABLE
132 #define FLASH_Enable CYGIMP_FLASH_ENABLE
133 extern void CYGIMP_FLASH_ENABLE(void *, void *);
135 #define FLASH_Enable(_start_, _end_)
137 #ifdef CYGIMP_FLASH_DISABLE
138 #define FLASH_Disable CYGIMP_FLASH_DISABLE
139 extern void CYGIMP_FLASH_DISABLE(void *, void *);
141 #define FLASH_Disable(_start_, _end_)
145 // Some platforms have a DIP switch or jumper that tells the software that
146 // the flash is write protected.
148 #ifdef CYGSEM_IO_FLASH_SOFT_WRITE_PROTECT
149 externC cyg_bool plf_flash_query_soft_wp(void *addr, int len);
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.
160 // Targets may provide alternative implementations for these macros in
161 // the hal_cache.h (or var/plf) files.
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).
168 // Both implementations must be called with interrupts disabled.
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.
176 #ifndef HAL_FLASH_CACHES_OFF
178 // Some drivers have only been tested with the old macros below.
179 #ifndef HAL_FLASH_CACHES_OLD_MACROS
181 #ifdef HAL_CACHE_UNIFIED
183 // Note: the ucache code has not been tested yet on any target.
184 #define HAL_FLASH_CACHES_OFF(_d_, _i_) \
186 _i_ = 0; /* avoids warning */ \
187 HAL_UCACHE_IS_ENABLED(_d_); \
189 HAL_UCACHE_INVALIDATE_ALL(); \
190 HAL_UCACHE_DISABLE(); \
193 #define HAL_FLASH_CACHES_ON(_d_, _i_) \
195 if (_d_) HAL_UCACHE_ENABLE(); \
198 #else // HAL_CACHE_UNIFIED
200 #define HAL_FLASH_CACHES_OFF(_d_, _i_) \
202 _i_ = 0; /* avoids warning */ \
203 HAL_DCACHE_IS_ENABLED(_d_); \
205 HAL_DCACHE_INVALIDATE_ALL(); \
206 HAL_DCACHE_DISABLE(); \
207 HAL_ICACHE_INVALIDATE_ALL(); \
210 #define HAL_FLASH_CACHES_ON(_d_, _i_) \
212 if (_d_) HAL_DCACHE_ENABLE(); \
215 #endif // HAL_CACHE_UNIFIED
217 #else // HAL_FLASH_CACHES_OLD_MACROS
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.
226 #define HAL_FLASH_CACHES_OFF(_d_, _i_) \
227 _d_ = 0; /* avoids warning */ \
228 _i_ = 0; /* avoids warning */ \
230 HAL_ICACHE_DISABLE();
232 #define HAL_FLASH_CACHES_ON(_d_, _i_) \
235 #endif // HAL_FLASH_CACHES_OLD_MACROS
237 #endif // HAL_FLASH_CACHES_OFF
239 #endif // _FLASH_PRIVATE_
241 #endif // _IO_FLASH_H_