packages/io/flash/v2_0/doc/flash.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     flash.sgml                                                  -->
   6 <!--                                                                 -->
   7 <!--     eCos FLASH support                                          -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 2004 Andrew Lunn                                  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <PART id="io-flash">
  33 <TITLE>FLASH Library</TITLE>
  34 <CHAPTER id="ecos-flash-library">
  35 <TITLE>The eCos FLASH Library</TITLE>
  36 <PARA>The FLASH library is an optional part of eCos, and is only
  37         applicable to some platforms.</PARA>
  38 <SECT1 id="flash-library">
  39 <TITLE>FLASH Library</TITLE>
  40
  41 <PARA>The eCos FLASH library provides the following functionality:</PARA>
  42
  43 <orderedlist>
  44 <listitem><PARA>Identifying installed device of a FLASH family.
  45           </PARA>
  46 </listitem>
  47 <listitem><PARA>Read, erasing and writing to FLASH blocks.</PARA></listitem>
  48 <listitem><PARA>Validating an address is within the FLASH.</PARA></listitem>
  49 <listitem><PARA>Determining the number and size of FLASH blocks.
  50           </PARA></listitem>
  51 </orderedlist>
  52
  53 <PARA>
  54 The library has a number of limitations:</PARA>
  55
  56 <orderedlist>
  57 <listitem><PARA>Only one family of FLASH device may be supported at once.
  58          </PARA>
  59 </listitem>
  60 <listitem><PARA>Multiple devices of one family are supported, but they must
  61                 be contiguous in memory.
  62           </PARA>
  63 </listitem>
  64 <listitem><PARA>The library is not thread or interrupt safe under
  65                 some conditions.
  66           </PARA>
  67 </listitem>
  68 <listitem><PARA>The library currently does not use the eCos naming
  69                  convention for its functions. This may change in the
  70                  future but backward compatibility is likely to be kept.
  71           </PARA>
  72 </listitem>
  73 </orderedlist>
  74
  75 <PARA>All of the functions described below are declared in the header
  76 file <filename>&lt;cyg/io/flash.h.h&gt;</filename> which all users of
  77 the FLASH library should include.</PARA>
  78
  79 <SECT2>
  80 <TITLE>Initializing the FLASH library</TITLE>
  81
  82 <PARA>The FLASH library needs to be initialized before other FLASH
  83 operations can be performed. This only needs to be done once. The
  84 following function will only do the initialization once so it's safe
  85 to call multiple times: </PARA>
  86
  87 <PROGRAMLISTING>externC int flash_init( _printf *pf ); typedef int
  88 _printf(const char *fmt, ...); </PROGRAMLISTING>
  89
  90 <PARA>
  91 The parameter <parameter>pf</parameter> is a pointer to a function
  92 which is to be used for diagnostic output. Typically the function
  93 <function>diag_printf()</function> will be passed. Normally this
  94 function is not used by the higher layer of the library unless
  95 <literal>CYGSEM_IO_FLASH_CHATTER</literal> is enabled.  Passing a
  96 <parameter>NULL</parameter> is not recommended, even when
  97 CYGSEM_IO_FLASH_CHATTER is disabled. The lower layers of the library
  98 may unconditionally call this function, especially when errors occur,
  99 probably resulting in a more serious error/crash!.</PARA>
 100 </SECT2>
 101
 102 <SECT2>
 103 <TITLE>Retrieving information about the FLASH</TITLE>
 104
 105 <PARA>
 106 The following four functions return information about the FLASH.
 107 </PARA>
 108
 109 <PROGRAMLISTING>externC int flash_get_block_info(int *block_size, int *blocks);
 110 externC int flash_get_limits(void *target, void **start, void **end);
 111 externC int flash_verify_addr(void *target);
 112 externC bool flash_code_overlaps(void *start, void *end);
 113 </PROGRAMLISTING>
 114
 115 <PARA>
 116 The function <FUNCTION>flash_get_block_info()</FUNCTION> returns the
 117 size and number of blocks. When the device has a mixture of block
 118 sizes, the size of the "normal" block will be returned. Please read
 119 the source code to determine exactly what this means.
 120 <FUNCTION>flash_get_limits()</FUNCTION> returns the lower and upper
 121 memory address the FLASH occupies. The <PARAMETER>target</PARAMETER>
 122 parameter is current unused. <FUNCTION> flash_verify_addr()
 123 </FUNCTION> tests if the target addresses is within the flash,
 124 returning <LITERAL>FLASH_ERR_OK</LITERAL> if so. Lastly, <FUNCTION>
 125 flash_code_overlaps() </FUNCTION> checks if the executing code is
 126 resident in the section of flash indicated by
 127 <PARAMETER>start</PARAMETER> and <PARAMETER> end</PARAMETER>. If this
 128 function returns true, erase and program operations within this range
 129 are very likely to cause the target to crash and burn horribly. Note
 130 the FLASH library does allow you to shoot yourself in the foot in this
 131 way.</PARA>
 132
 133 </SECT2>
 134 <SECT2>
 135
 136 <TITLE>Reading from FLASH</TITLE>
 137
 138 <PARA>
 139 There are two methods for reading from FLASH. The first is to use the
 140 following function. </PARA>
 141
 142 <PROGRAMLISTING>
 143 externC int flash_read(void *flash_base, void *ram_base, int len, void **err_address);
 144 </PROGRAMLISTING>
 145
 146 <PARA>
 147 <PARAMETER>flash_base</PARAMETER> is where in the flash to read
 148 from. <PARAMETER>ram_base</PARAMETER> indicates where the data read
 149 from flash should be placed into RAM. <PARAMETER>len</PARAMETER> is
 150 the number of bytes to be read from the FLASH and
 151 <PARAMETER>err_address</PARAMETER> is used to return the location in
 152 FLASH that any error occurred while reading.
 153 </PARA>
 154
 155 <PARA>
 156 The second method is to simply <FUNCTION>memcpy()</FUNCTION> directly
 157 from the FLASH. This is not recommended since some types of device
 158 cannot be read in this way, eg NAND FLASH. Using the FLASH library
 159 function to read the FLASH will always work so making it easy to port
 160 code from one FLASH device to another.
 161 </PARA>
 162
 163 </SECT2>
 164 <SECT2>
 165
 166 <TITLE>Erasing areas of FLASH</TITLE>
 167
 168 <PARA>
 169 Blocks of FLASH can be erased using the following function:
 170 </PARA>
 171
 172 <PROGRAMLISTING>externC int flash_erase(void *flash_base, int len, void **err_address);
 173 </PROGRAMLISTING>
 174
 175 <PARA>
 176 <PARAMETER>flash_base</PARAMETER> is where in the flash to erase
 177 from. <PARAMETER>len</PARAMETER> is the minimum number of bytes to
 178 erase in the FLASH and <PARAMETER>err_address</PARAMETER> is used to
 179 return the location in FLASH that any error occurred while erasing. It
 180 should be noted that FLASH devices are block oriented when erasing. It
 181 is not possible to erase a few bytes within a block, the whole block
 182 will be erased. <PARAMETER>flash_base</PARAMETER> may be anywhere
 183 within the first block to be erased and <PARAMETER>flash_base+len
 184 </PARAMETER> maybe anywhere in the last block to be erased.  </PARA>
 185
 186 </SECT2>
 187 <SECT2>
 188
 189 <TITLE>Programming the FLASH</TITLE>
 190
 191 <PARA> Programming of the flash is achieved using the following
 192 function.</PARA>
 193
 194 <PROGRAMLISTING>externC int flash_program(void *flash_base, void *ram_base, int len, void **err_address);
 195 </PROGRAMLISTING>
 196
 197 <PARA>
 198 <PARAMETER>flash_base</PARAMETER> is where in the flash to program
 199 from. <PARAMETER>ram_base</PARAMETER> indicates where the data to be
 200 programmed into FLASH should be read from in RAM. <PARAMETER>len
 201 </PARAMETER> is the number of bytes to be program into the FLASH and
 202 <PARAMETER>err_address</PARAMETER> is used to return the location in
 203 FLASH that any error occurred while programming. </PARA>
 204
 205 </SECT2>
 206 <SECT2>
 207
 208 <TITLE>Locking and unlocking blocks</TITLE>
 209
 210 <PARA>
 211 Some flash devices have the ability to lock and unlock blocks. A
 212 locked block cannot be erased or programmed without it first being
 213 unlocked. For devices which support this feature and when <LITERAL>
 214 CYGHWR_IO_FLASH_BLOCK_LOCKING</LITERAL> is enabled then the following
 215 two functions are available:</PARA>
 216
 217 <PROGRAMLISTING>
 218 externC int flash_lock(void *flash_base, int len, void **err_address);
 219 externC int flash_unlock(void *flash_base, int len, void **err_address);
 220 </PROGRAMLISTING>
 221
 222 </SECT2>
 223 <SECT2>
 224
 225 <TITLE>Return values and errors</TITLE>
 226
 227 <PARA>All the functions above, except <FUNCTION>flash_code_overlaps()
 228 </FUNCTION> return one of the following return values.</PARA>
 229
 230 <PROGRAMLISTING>
 231 FLASH_ERR_OK              No error - operation complete
 232 FLASH_ERR_INVALID         Invalid FLASH address
 233 FLASH_ERR_ERASE           Error trying to erase
 234 FLASH_ERR_LOCK            Error trying to lock/unlock
 235 FLASH_ERR_PROGRAM         Error trying to program
 236 FLASH_ERR_PROTOCOL        Generic error
 237 FLASH_ERR_PROTECT         Device/region is write-protected
 238 FLASH_ERR_NOT_INIT        FLASH info not yet initialized
 239 FLASH_ERR_HWR             Hardware (configuration?) problem
 240 FLASH_ERR_ERASE_SUSPEND   Device is in erase suspend mode
 241 FLASH_ERR_PROGRAM_SUSPEND Device is in program suspend mode
 242 FLASH_ERR_DRV_VERIFY      Driver failed to verify data
 243 FLASH_ERR_DRV_TIMEOUT     Driver timed out waiting for device
 244 FLASH_ERR_DRV_WRONG_PART  Driver does not support device
 245 FLASH_ERR_LOW_VOLTAGE     Not enough juice to complete job
 246 </PROGRAMLISTING>
 247
 248 <PARA>To turn an error code into a human readable string the following
 249 function can be used:</PARA>
 250
 251 <PROGRAMLISTING>externC char *flash_errmsg(int err);
 252 </PROGRAMLISTING>
 253 </SECT2>
 254
 255 <SECT2>
 256
 257 <TITLE> Notes on using the FLASH library</TITLE>
 258
 259 <PARA>
 260 The FLASH library evolved from the needs and environment of RedBoot
 261 rather than being a general purpose eCos component. This history
 262 explains some of the problems with the library.  </PARA>
 263
 264 <PARA>The library is not thread safe. Multiple simultaneous calls to
 265 its library functions will likely fail and may cause a crash. It is
 266 the callers responsibility to use the necessary mutex's if needed.
 267 </PARA>
 268
 269 <PARA>FLASH devices cannot be read from when an erase or write
 270 operation is active. This means it is not possible to execute code
 271 from flash while an erase or write operation is active. It is possible
 272 to use the library when the executable image is resident in FLASH. The
 273 low level drivers are written such that the linker places the
 274 functions that actually manipulate the flash into RAM.  However the
 275 library may not be interrupt safe. An interrupt must not cause
 276 execution of code that is resident in FLASH. This may be the image
 277 itself, or RedBoot. In some configurations of eCos, ^C on the serial
 278 port or debugging via Ethernet may cause an interrupt handler to call
 279 RedBoot. If RedBoot is resident in FLASH this will cause a crash.
 280 Similarly, if another thread invokes a virtual vector function to
 281 access RedBoot, eg to perform a <FUNCTION>diag_printf()</FUNCTION> a
 282 crash could result.
 283 </PARA>
 284
 285 <PARA> Thus with a ROM based image or a ROM based Redboot it is
 286 recommended to disable interrupts while erasing or programming
 287 flash. Using both a ROMRAM or RAM images and a ROMRAM or RAM RedBoot
 288 are safe and there is no need to disable interrupts. Similarly,
 289 </PARA>
 290
 291 </SECT2>
 292 <SECT2>
 293
 294 <TITLE>Danger, Will Robinson! Danger!</TITLE>
 295
 296 <PARA>Unlike nearly every other aspect of embedded system programming,
 297 getting it wrong with FLASH devices can render your target system
 298 useless. Most targets have a boot loader in the FLASH. Without this
 299 boot loader the target will obviously not boot. So before starting to
 300 play with this library its worth investigating a few things. How do
 301 you recover your target if you delete the boot loader? Do you have the
 302 necessary JTAG cable? Or is specialist hardware needed? Is it even
 303 possible to recover the target boards or must it be thrown into the
 304 rubbish bin? How does killing the board affect your project schedule?
 305 </PARA>
 306
 307 </SECT2>
 308 </SECT1>
 309 </CHAPTER>
 310 </PART>