ecos: packages/io/flash/current/doc/flash.sgml annotate

annotate packages/io/flash/current/doc/flash.sgml @ 2658:aee6bfaf78cd

* doc/flash.sgml: Fix flash.h header name typos.

author	jlarmour
date	Sun, 23 Nov 2008 02:41:29 +0000
parents	a2f5434df2cb
children	74dbf4c3f2e1

rev	line source
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1 <!-- DOCTYPE part PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	2
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	3 <!-- {{{ Banner -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	4
304f194b1c78 First draft version of documentation. asl parents: diff changeset	5 <!-- =============================================================== -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	6 <!-- -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	7 <!-- flash.sgml -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	8 <!-- -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	9 <!-- eCos FLASH support -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	10 <!-- -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	11 <!-- =============================================================== -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	12 <!-- ####COPYRIGHTBEGIN#### -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	13 <!-- -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	14 <!-- =============================================================== -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	15 <!-- Copyright (C) 2004 Andrew Lunn -->
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	16 <!-- Copyright (C) 2004, 2005, 2006, 2007 eCosCentric Limited -->
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	17 <!-- This material may be distributed only subject to the terms -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	18 <!-- and conditions set forth in the Open Publication License, v1.0 -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	19 <!-- or later (the latest version is presently available at -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	20 <!-- http://www.opencontent.org/openpub/) -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	21 <!-- Distribution of the work or derivative of the work in any -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	22 <!-- standard (paper) book form is prohibited unless prior -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	23 <!-- permission obtained from the copyright holder -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	24 <!-- =============================================================== -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	25 <!-- -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	26 <!-- ####COPYRIGHTEND#### -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	27 <!-- =============================================================== -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	28 <!-- #####DESCRIPTIONBEGIN#### -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	29 <!-- -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	30 <!-- ####DESCRIPTIONEND#### -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	31 <!-- =============================================================== -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	32
304f194b1c78 First draft version of documentation. asl parents: diff changeset	33 <!-- }}} -->
304f194b1c78 First draft version of documentation. asl parents: diff changeset	34
304f194b1c78 First draft version of documentation. asl parents: diff changeset	35 <PART id="io-flash">
304f194b1c78 First draft version of documentation. asl parents: diff changeset	36 <TITLE>FLASH Library</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	37 <CHAPTER id="ecos-flash-library">
304f194b1c78 First draft version of documentation. asl parents: diff changeset	38 <TITLE>The eCos FLASH Library</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	39 <PARA>The FLASH library is an optional part of eCos, and is only
304f194b1c78 First draft version of documentation. asl parents: diff changeset	40 applicable to some platforms.</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	41 <PARA>The eCos FLASH library provides the following functionality:</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	42
304f194b1c78 First draft version of documentation. asl parents: diff changeset	43 <orderedlist>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	44 <listitem><PARA>Identifying installed device of a FLASH family.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	45 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	46 </listitem>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	47 <listitem><PARA>Read, erasing and writing to FLASH blocks.</PARA></listitem>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	48 <listitem><PARA>Validating an address is within the FLASH.</PARA></listitem>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	49 <listitem><PARA>Determining the number and size of FLASH blocks.
1745 a9728471a0b5 doco fix msalter parents: 1672 diff changeset	50 </PARA></listitem>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	51 </orderedlist>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	52
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	53 <PARA> There are two APIs with the flash library. The old API is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	54 retained for backwards compatibility reasons, but should slowly be
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	55 replaced with the new API which is much more flexible and does not
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	56 pollute the name space as much.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	57 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	58
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	59 <SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	60 <TITLE>Notes on using the FLASH library</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	61
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	62 <PARA>FLASH devices cannot be read from when an erase or write
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	63 operation is active. This means it is not possible to execute code
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	64 from flash while an erase or write operation is active. It is possible
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	65 to use the library when the executable image is resident in FLASH. The
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	66 low level drivers are written such that the linker places the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	67 functions that actually manipulate the flash into RAM. However the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	68 library may not be interrupt safe. An interrupt must not cause
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	69 execution of code that is resident in FLASH. This may be the image
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	70 itself, or RedBoot. In some configurations of eCos, ^C on the serial
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	71 port or debugging via Ethernet may cause an interrupt handler to call
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	72 RedBoot. If RedBoot is resident in FLASH this will cause a crash.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	73 Similarly, if another thread invokes a virtual vector function to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	74 access RedBoot, eg to perform a <FUNCTION>diag_printf()</FUNCTION> a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	75 crash could result.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	76 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	77
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	78 <PARA> Thus with a ROM based image or a ROM based Redboot it is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	79 recommended to disable interrupts while erasing or programming
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	80 flash. Using both a ROMRAM or RAM images and a ROMRAM or RAM RedBoot
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	81 are safe and there is no need to disable interrupts. Similarly,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	82 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	83 </SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	84
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	85 <SECT1 id="io-flash-danger">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	86 <TITLE>Danger, Will Robinson! Danger!</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	87
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	88 <PARA>Unlike nearly every other aspect of embedded system programming,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	89 getting it wrong with FLASH devices can render your target system
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	90 useless. Most targets have a boot loader in the FLASH. Without this
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	91 boot loader the target will obviously not boot. So before starting to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	92 play with this library its worth investigating a few things. How do
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	93 you recover your target if you delete the boot loader? Do you have the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	94 necessary JTAG cable? Or is specialist hardware needed? Is it even
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	95 possible to recover the target boards or must it be thrown into the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	96 rubbish bin? How does killing the board affect your project schedule?
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	97 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	98
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	99 </SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	100 </CHAPTER>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	101
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	102 <CHAPTER id="ecos-flash-v2">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	103 <TITLE>The Version 2 eCos FLASH API</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	104
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	105 <PARA> There are two APIs described here. The first is the application
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	106 API which programs should use. The second API is that between the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	107 FLASH IO library and the device drivers. </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	108
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	109 <SECT1 id="ecos-flash-v2-api">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	110 <TITLE>FLASH user API</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	111
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	112 <PARA>All of the functions described below are declared in the header
2658 aee6bfaf78cd * doc/flash.sgml: Fix flash.h header name typos. jlarmour parents: 2626 diff changeset	113 file <filename><cyg/io/flash.h></filename> which all users of
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	114 the FLASH library should include.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	115
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	116 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	117 <TITLE>Initializing the FLASH library</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	118
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	119 <PARA>The FLASH library needs to be initialized before other FLASH
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	120 operations can be performed. This only needs to be done once. The
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	121 following function will only do the initialization once so it's safe
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	122 to call multiple times: </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	123
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	124 <PROGRAMLISTING>__externC int cyg_flash_init(const cyg_flash_printf *pf);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	125 typedef int cyg_flash_printf(const char *fmt, ...); </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	126
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	127 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	128 The parameter <parameter>pf</parameter> is a pointer to a function
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	129 which is to be used for diagnostic output. Typically the function
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	130 <function>diag_printf()</function> will be passed. Normally this
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	131 function is not used by the higher layer of the library unless
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	132 <literal>CYGSEM_IO_FLASH_CHATTER</literal> is enabled. Passing a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	133 <parameter>NULL</parameter> is not recommended, even when
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	134 CYGSEM_IO_FLASH_CHATTER is disabled. The lower layers of the library
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	135 may unconditionally call this function, especially when errors occur,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	136 probably resulting in a more serious error/crash!.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	137 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	138
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	139 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	140 <TITLE>Retrieving information about FLASH devices</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	141
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	142 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	143 The following five functions return information about the FLASH.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	144 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	145
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	146 <PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	147 __externC int cyg_flash_get_info(cyg_uint32 devno, cyg_flash_info_t * info);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	148 __externC int cyg_flash_get_info_addr(cyg_flashaddr_t flash_base, cyg_flash_info_t * info);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	149 __externC int cyg_flash_verify_addr(const flashaddr_t address);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	150 __extern size_t cyg_flash_block_size(const cyg_flashaddr_t flash_base);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	151
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	152 typedef struct cyg_flash_block_info
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	153 size_t block_size;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	154 cyg_uint32 blocks;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	155 } cyg_flash_block_info_t;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	156
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	157 typedef struct {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	158 cyg_flashaddr_t start; // First address
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	159 cyg_flashaddr_t end; // Last address
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	160 cyg_uint32 num_block_infos // Number of entries
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	161 const cyg_flash_block_info_t *blocks_info; // Info about one block size
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	162 } cyg_flash_info_t;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	163 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	164
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	165 <PARA><FUNCTION>cyg_flash_get_info()</FUNCTION> is the main function
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	166 to get information about installed flash devices. Parameter
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	167 <PARAMETER>devno</PARAMETER> is used to iterate over the available
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	168 flash devices, starting from 0. If the devno'th device exists, the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	169 structure pointed to by <PARAMETER>info</PARAMETER> is filled in and
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	170 <LITERAL>CYG_FLASH_ERR_OK</LITERAL> is returned, otherwise
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	171 <LITERAL>CYG_FLASH_ERR_INVALID</LITERAL>.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	172 <FUNCTION>cyg_flash_get_info()</FUNCTION> is similar, but returns the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	173 information about the flash device at the given address.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	174 <FUNCTION>cyg_flash_block_size()</FUNCTION> returns the size of the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	175 block at the given address. <FUNCTION>cyg_flash_verify_addr()
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	176 </FUNCTION> tests if the target addresses is within one of the FLASH
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	177 devices, returning <LITERAL>CYG_FLASH_ERR_OK </LITERAL> if so.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	178 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	179 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	180 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	181
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	182 <TITLE>Reading from FLASH</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	183
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	184 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	185 There are two methods for reading from FLASH. The first is to use the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	186 following function. </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	187
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	188 <PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	189 __externC int cyg_flash_read(cyg_flashaddr_t flash_base, void ram_base, size_t len, cyg_flashaddr_t err_address);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	190 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	191
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	192 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	193 <PARAMETER>flash_base</PARAMETER> is where in the flash to read
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	194 from. <PARAMETER>ram_base</PARAMETER> indicates where the data read
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	195 from flash should be placed into RAM. <PARAMETER>len</PARAMETER> is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	196 the number of bytes to be read from the FLASH and
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	197 <PARAMETER>err_address</PARAMETER> is used to return the location in
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	198 FLASH that any error occurred while reading.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	199 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	200
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	201 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	202 The second method is to simply <FUNCTION>memcpy()</FUNCTION> directly
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	203 from the FLASH. This is not recommended since some types of device
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	204 cannot be read in this way, eg NAND FLASH. Using the FLASH library
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	205 function to read the FLASH will always work so making it easy to port
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	206 code from one FLASH device to another.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	207 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	208
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	209 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	210 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	211
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	212 <TITLE>Erasing areas of FLASH</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	213
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	214 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	215 Blocks of FLASH can be erased using the following function:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	216 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	217
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	218 <PROGRAMLISTING>__externC int cyg_flash_erase(cyg_flashaddr_t flash_base, size_t len, cyg_flashaddr_t *err_address);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	219 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	220
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	221 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	222 <PARAMETER>flash_base</PARAMETER> is where in the flash to erase
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	223 from. <PARAMETER>len</PARAMETER> is the minimum number of bytes to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	224 erase in the FLASH and <PARAMETER>err_address</PARAMETER> is used to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	225 return the location in FLASH that any error occurred while erasing. It
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	226 should be noted that FLASH devices are block oriented when erasing. It
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	227 is not possible to erase a few bytes within a block, the whole block
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	228 will be erased. <PARAMETER>flash_base</PARAMETER> may be anywhere
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	229 within the first block to be erased and <PARAMETER>flash_base+len
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	230 </PARAMETER> may be anywhere in the last block to be erased. </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	231
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	232 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	233 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	234
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	235 <TITLE>Programming the FLASH</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	236
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	237 <PARA> Programming of the flash is achieved using the following
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	238 function.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	239
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	240 <PROGRAMLISTING>__externC int cyg_flash_program(cyg_flashaddr_t flash_base, void ram_base, size_t len, cyg_flashaddr_t err_address);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	241 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	242
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	243 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	244 <PARAMETER>flash_base</PARAMETER> is where in the flash to program
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	245 from. <PARAMETER>ram_base</PARAMETER> indicates where the data to be
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	246 programmed into FLASH should be read from in RAM. <PARAMETER>len
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	247 </PARAMETER> is the number of bytes to be program into the FLASH and
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	248 <PARAMETER>err_address</PARAMETER> is used to return the location in
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	249 FLASH that any error occurred while programming. </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	250
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	251 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	252 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	253
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	254 <TITLE>Locking and unlocking blocks</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	255
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	256 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	257 Some flash devices have the ability to lock and unlock blocks. A
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	258 locked block cannot be erased or programmed without it first being
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	259 unlocked. For devices which support this feature and when <LITERAL>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	260 CYGHWR_IO_FLASH_BLOCK_LOCKING</LITERAL> is enabled then the following
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	261 two functions are available:</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	262
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	263 <PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	264 __externC int cyg_flash_lock(const cyg_flashaddr_t flash_base, size_t len, cyg_flashaddr_t *err_address);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	265 __externC int cyg_flash_unlock(const cyg_flashaddr_t flash_base, size_t len, cyg_flashaddr_t *err_address);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	266 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	267
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	268 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	269
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	270 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	271 <TITLE>Locking FLASH Mutex's</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	272
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	273 <PARA>When the eCos kernel package is included in the eCos
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	274 configuration, the FLASH IO library will perform mutex locking on
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	275 FLASH operations. This makes the API defined here thread safe. However
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	276 applications may wish to directly access the contents of the FLASH. In
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	277 order for this to be thread safe it is necessary for the application
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	278 to use the following two functions to inform the FLASH IO library that
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	279 the FLASH devices are being used and other API calls should be
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	280 blocked.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	281
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	282 <PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	283 __externC int cyg_flash_mutex_lock(const cyg_flashaddr_t from, size_t len);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	284 __externC int cyg_flash_mutex_unlock(const cyg_flashaddr_t from, size_t len);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	285 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	286
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	287 </SECT2
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	288
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	289 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	290
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	291 <TITLE>Return values and errors</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	292
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	293 <PARA>All the functions above return one of the following return
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	294 values.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	295
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	296 <PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	297 CYG_FLASH_ERR_OK No error - operation complete
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	298 CYG_FLASH_ERR_INVALID Invalid FLASH address
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	299 CYG_FLASH_ERR_ERASE Error trying to erase
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	300 CYG_FLASH_ERR_LOCK Error trying to lock/unlock
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	301 CYG_FLASH_ERR_PROGRAM Error trying to program
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	302 CYG_FLASH_ERR_PROTOCOL Generic error
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	303 CYG_FLASH_ERR_PROTECT Device/region is write-protected
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	304 CYG_FLASH_ERR_NOT_INIT FLASH info not yet initialized
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	305 CYG_FLASH_ERR_HWR Hardware (configuration?) problem
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	306 CYG_FLASH_ERR_ERASE_SUSPEND Device is in erase suspend mode
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	307 CYG_FLASH_ERR_PROGRAM_SUSPEND Device is in program suspend mode
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	308 CYG_FLASH_ERR_DRV_VERIFY Driver failed to verify data
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	309 CYG_FLASH_ERR_DRV_TIMEOUT Driver timed out waiting for device
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	310 CYG_FLASH_ERR_DRV_WRONG_PART Driver does not support device
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	311 CYG_FLASH_ERR_LOW_VOLTAGE Not enough juice to complete job
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	312 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	313
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	314 <PARA>To turn an error code into a human readable string the following
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	315 function can be used:</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	316
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	317 <PROGRAMLISTING>__externC const char *cyg_flash_errmsg(const int err);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	318 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	319 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	320
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	321 </SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	322
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	323 <SECT1 id="ecos-flash-v2-dev">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	324 <TITLE>FLASH device API</TITLE> <PARA>This section describes the API
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	325 between the FLASH IO library the FLASH device drivers.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	326
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	327 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	328 <TITLE>The FLASH device Structure</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	329
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	330 <PARA>This structure keeps all the information about a single driver.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	331
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	332 <PROGRAMLISTING>struct cyg_flash_dev {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	333 const struct cyg_flash_dev_funs *funs; // Function pointers
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	334 cyg_uint32 flags; // Device characteristics
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	335 cyg_flashaddr_t start; // First address
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	336 cyg_flashaddr_t end; // Last address
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	337 cyg_uint32 num_block_infos; // Number of entries
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	338 const cyg_flash_block_info_t *block_info; // Info about one block size
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	339
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	340 const void *priv; // Devices private data
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	341
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	342 // The following are only written to by the FLASH IO layer.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	343 cyg_flash_printf *pf; // Pointer to diagnostic printf
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	344 bool init; // Device has been initialised
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	345 #ifdef CYGPKG_KERNEL
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	346 cyg_mutex_t mutex; // Mutex for thread safeness
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	347 #endif
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	348 #if (CYGHWR_IO_FLASH_DEVICE > 1)
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	349 struct cyg_flash_dev *next; // Pointer to next device
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	350 #endif
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	351 };
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	352
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	353 struct cyg_flash_dev_funs {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	354 int (flash_init) (struct cyg_flash_dev dev);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	355 size_t (flash_query) (struct cyg_flash_dev dev, void * data, size_t len);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	356 int (flash_erase_block) (struct cyg_flash_dev dev, cyg_flashaddr_t block_base);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	357 int (flash_program) (struct cyg_flash_dev dev, cyg_flashaddr_t base, const void* data, size_t len);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	358 int (flash_read) (struct cyg_flash_dev dev, const cyg_flashaddr_t base, void* data, size_t len);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	359 #ifdef CYGHWR_IO_FLASH_BLOCK_LOCKING
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	360 int (flash_block_lock) (struct cyg_flash_dev dev, const cyg_flashaddr_t block_base);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	361 int (flash_block_unlock) (struct cyg_flash_dev dev, const cyg_flashaddr_t block_base);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	362 #endif
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	363 };
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	364 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	365
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	366 <PARA>The FLASH IO layer will only pass requests for operations on a single block.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	367 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	368 </SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	369 </CHAPTER>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	370
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	371 <CHAPTER id="ecos-flash-v1">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	372 <TITLE>The legacy Version 1 eCos FLASH API</TITLE>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	373 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	374 The library has a number of limitations:</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	375
304f194b1c78 First draft version of documentation. asl parents: diff changeset	376 <orderedlist>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	377 <listitem><PARA>Only one family of FLASH device may be supported at once.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	378 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	379 </listitem>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	380 <listitem><PARA>Multiple devices of one family are supported, but they must
304f194b1c78 First draft version of documentation. asl parents: diff changeset	381 be contiguous in memory.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	382 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	383 </listitem>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	384 <listitem><PARA>The library is not thread or interrupt safe under
304f194b1c78 First draft version of documentation. asl parents: diff changeset	385 some conditions.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	386 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	387 </listitem>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	388 <listitem><PARA>The library currently does not use the eCos naming
304f194b1c78 First draft version of documentation. asl parents: diff changeset	389 convention for its functions. This may change in the
304f194b1c78 First draft version of documentation. asl parents: diff changeset	390 future but backward compatibility is likely to be kept.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	391 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	392 </listitem>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	393 </orderedlist>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	394
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	395 <PARA> There are two APIs described here. The first is the application
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	396 API which programs should use. The second API is that between the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	397 FLASH io library and the device drivers. </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	398
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	399 <SECT1 id="ecos-flash-v1-api">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	400 <TITLE>FLASH user API</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	401
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	402 <PARA>All of the functions described below are declared in the header
2658 aee6bfaf78cd * doc/flash.sgml: Fix flash.h header name typos. jlarmour parents: 2626 diff changeset	403 file <filename><cyg/io/flash.h></filename> which all users of
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	404 the FLASH library should include.</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	405
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	406
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	407 <SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	408 <TITLE>Initializing the FLASH library</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	409
304f194b1c78 First draft version of documentation. asl parents: diff changeset	410 <PARA>The FLASH library needs to be initialized before other FLASH
304f194b1c78 First draft version of documentation. asl parents: diff changeset	411 operations can be performed. This only needs to be done once. The
304f194b1c78 First draft version of documentation. asl parents: diff changeset	412 following function will only do the initialization once so it's safe
304f194b1c78 First draft version of documentation. asl parents: diff changeset	413 to call multiple times: </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	414
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	415 <PROGRAMLISTING>externC int flash_init( _printf *pf );
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	416 typedef int _printf(const char *fmt, ...); </PROGRAMLISTING>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	417
304f194b1c78 First draft version of documentation. asl parents: diff changeset	418 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	419 The parameter <parameter>pf</parameter> is a pointer to a function
304f194b1c78 First draft version of documentation. asl parents: diff changeset	420 which is to be used for diagnostic output. Typically the function
304f194b1c78 First draft version of documentation. asl parents: diff changeset	421 <function>diag_printf()</function> will be passed. Normally this
304f194b1c78 First draft version of documentation. asl parents: diff changeset	422 function is not used by the higher layer of the library unless
304f194b1c78 First draft version of documentation. asl parents: diff changeset	423 <literal>CYGSEM_IO_FLASH_CHATTER</literal> is enabled. Passing a
304f194b1c78 First draft version of documentation. asl parents: diff changeset	424 <parameter>NULL</parameter> is not recommended, even when
304f194b1c78 First draft version of documentation. asl parents: diff changeset	425 CYGSEM_IO_FLASH_CHATTER is disabled. The lower layers of the library
304f194b1c78 First draft version of documentation. asl parents: diff changeset	426 may unconditionally call this function, especially when errors occur,
304f194b1c78 First draft version of documentation. asl parents: diff changeset	427 probably resulting in a more serious error/crash!.</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	428 </SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	429
304f194b1c78 First draft version of documentation. asl parents: diff changeset	430 <SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	431 <TITLE>Retrieving information about the FLASH</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	432
304f194b1c78 First draft version of documentation. asl parents: diff changeset	433 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	434 The following four functions return information about the FLASH.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	435 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	436
304f194b1c78 First draft version of documentation. asl parents: diff changeset	437 <PROGRAMLISTING>externC int flash_get_block_info(int block_size, int blocks);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	438 externC int flash_get_limits(void target, void start, void *end);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	439 externC int flash_verify_addr(void *target);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	440 externC bool flash_code_overlaps(void start, void end);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	441 </PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	442
304f194b1c78 First draft version of documentation. asl parents: diff changeset	443 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	444 The function <FUNCTION>flash_get_block_info()</FUNCTION> returns the
304f194b1c78 First draft version of documentation. asl parents: diff changeset	445 size and number of blocks. When the device has a mixture of block
304f194b1c78 First draft version of documentation. asl parents: diff changeset	446 sizes, the size of the "normal" block will be returned. Please read
304f194b1c78 First draft version of documentation. asl parents: diff changeset	447 the source code to determine exactly what this means.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	448 <FUNCTION>flash_get_limits()</FUNCTION> returns the lower and upper
304f194b1c78 First draft version of documentation. asl parents: diff changeset	449 memory address the FLASH occupies. The <PARAMETER>target</PARAMETER>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	450 parameter is current unused. <FUNCTION> flash_verify_addr()
304f194b1c78 First draft version of documentation. asl parents: diff changeset	451 </FUNCTION> tests if the target addresses is within the flash,
304f194b1c78 First draft version of documentation. asl parents: diff changeset	452 returning <LITERAL>FLASH_ERR_OK</LITERAL> if so. Lastly, <FUNCTION>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	453 flash_code_overlaps() </FUNCTION> checks if the executing code is
304f194b1c78 First draft version of documentation. asl parents: diff changeset	454 resident in the section of flash indicated by
304f194b1c78 First draft version of documentation. asl parents: diff changeset	455 <PARAMETER>start</PARAMETER> and <PARAMETER> end</PARAMETER>. If this
304f194b1c78 First draft version of documentation. asl parents: diff changeset	456 function returns true, erase and program operations within this range
304f194b1c78 First draft version of documentation. asl parents: diff changeset	457 are very likely to cause the target to crash and burn horribly. Note
304f194b1c78 First draft version of documentation. asl parents: diff changeset	458 the FLASH library does allow you to shoot yourself in the foot in this
304f194b1c78 First draft version of documentation. asl parents: diff changeset	459 way.</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	460
304f194b1c78 First draft version of documentation. asl parents: diff changeset	461 </SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	462 <SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	463
304f194b1c78 First draft version of documentation. asl parents: diff changeset	464 <TITLE>Reading from FLASH</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	465
304f194b1c78 First draft version of documentation. asl parents: diff changeset	466 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	467 There are two methods for reading from FLASH. The first is to use the
304f194b1c78 First draft version of documentation. asl parents: diff changeset	468 following function. </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	469
304f194b1c78 First draft version of documentation. asl parents: diff changeset	470 <PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	471 externC int flash_read(void flash_base, void ram_base, int len, void **err_address);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	472 </PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	473
304f194b1c78 First draft version of documentation. asl parents: diff changeset	474 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	475 <PARAMETER>flash_base</PARAMETER> is where in the flash to read
304f194b1c78 First draft version of documentation. asl parents: diff changeset	476 from. <PARAMETER>ram_base</PARAMETER> indicates where the data read
304f194b1c78 First draft version of documentation. asl parents: diff changeset	477 from flash should be placed into RAM. <PARAMETER>len</PARAMETER> is
304f194b1c78 First draft version of documentation. asl parents: diff changeset	478 the number of bytes to be read from the FLASH and
304f194b1c78 First draft version of documentation. asl parents: diff changeset	479 <PARAMETER>err_address</PARAMETER> is used to return the location in
304f194b1c78 First draft version of documentation. asl parents: diff changeset	480 FLASH that any error occurred while reading.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	481 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	482
304f194b1c78 First draft version of documentation. asl parents: diff changeset	483 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	484 The second method is to simply <FUNCTION>memcpy()</FUNCTION> directly
304f194b1c78 First draft version of documentation. asl parents: diff changeset	485 from the FLASH. This is not recommended since some types of device
304f194b1c78 First draft version of documentation. asl parents: diff changeset	486 cannot be read in this way, eg NAND FLASH. Using the FLASH library
304f194b1c78 First draft version of documentation. asl parents: diff changeset	487 function to read the FLASH will always work so making it easy to port
304f194b1c78 First draft version of documentation. asl parents: diff changeset	488 code from one FLASH device to another.
304f194b1c78 First draft version of documentation. asl parents: diff changeset	489 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	490
304f194b1c78 First draft version of documentation. asl parents: diff changeset	491 </SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	492 <SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	493
304f194b1c78 First draft version of documentation. asl parents: diff changeset	494 <TITLE>Erasing areas of FLASH</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	495
304f194b1c78 First draft version of documentation. asl parents: diff changeset	496 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	497 Blocks of FLASH can be erased using the following function:
304f194b1c78 First draft version of documentation. asl parents: diff changeset	498 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	499
304f194b1c78 First draft version of documentation. asl parents: diff changeset	500 <PROGRAMLISTING>externC int flash_erase(void flash_base, int len, void *err_address);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	501 </PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	502
304f194b1c78 First draft version of documentation. asl parents: diff changeset	503 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	504 <PARAMETER>flash_base</PARAMETER> is where in the flash to erase
304f194b1c78 First draft version of documentation. asl parents: diff changeset	505 from. <PARAMETER>len</PARAMETER> is the minimum number of bytes to
304f194b1c78 First draft version of documentation. asl parents: diff changeset	506 erase in the FLASH and <PARAMETER>err_address</PARAMETER> is used to
304f194b1c78 First draft version of documentation. asl parents: diff changeset	507 return the location in FLASH that any error occurred while erasing. It
304f194b1c78 First draft version of documentation. asl parents: diff changeset	508 should be noted that FLASH devices are block oriented when erasing. It
304f194b1c78 First draft version of documentation. asl parents: diff changeset	509 is not possible to erase a few bytes within a block, the whole block
304f194b1c78 First draft version of documentation. asl parents: diff changeset	510 will be erased. <PARAMETER>flash_base</PARAMETER> may be anywhere
304f194b1c78 First draft version of documentation. asl parents: diff changeset	511 within the first block to be erased and <PARAMETER>flash_base+len
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	512 </PARAMETER> may be anywhere in the last block to be erased. </PARA>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	513
304f194b1c78 First draft version of documentation. asl parents: diff changeset	514 </SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	515 <SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	516
304f194b1c78 First draft version of documentation. asl parents: diff changeset	517 <TITLE>Programming the FLASH</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	518
304f194b1c78 First draft version of documentation. asl parents: diff changeset	519 <PARA> Programming of the flash is achieved using the following
304f194b1c78 First draft version of documentation. asl parents: diff changeset	520 function.</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	521
304f194b1c78 First draft version of documentation. asl parents: diff changeset	522 <PROGRAMLISTING>externC int flash_program(void flash_base, void ram_base, int len, void **err_address);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	523 </PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	524
304f194b1c78 First draft version of documentation. asl parents: diff changeset	525 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	526 <PARAMETER>flash_base</PARAMETER> is where in the flash to program
304f194b1c78 First draft version of documentation. asl parents: diff changeset	527 from. <PARAMETER>ram_base</PARAMETER> indicates where the data to be
304f194b1c78 First draft version of documentation. asl parents: diff changeset	528 programmed into FLASH should be read from in RAM. <PARAMETER>len
304f194b1c78 First draft version of documentation. asl parents: diff changeset	529 </PARAMETER> is the number of bytes to be program into the FLASH and
304f194b1c78 First draft version of documentation. asl parents: diff changeset	530 <PARAMETER>err_address</PARAMETER> is used to return the location in
304f194b1c78 First draft version of documentation. asl parents: diff changeset	531 FLASH that any error occurred while programming. </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	532
304f194b1c78 First draft version of documentation. asl parents: diff changeset	533 </SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	534 <SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	535
304f194b1c78 First draft version of documentation. asl parents: diff changeset	536 <TITLE>Locking and unlocking blocks</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	537
304f194b1c78 First draft version of documentation. asl parents: diff changeset	538 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	539 Some flash devices have the ability to lock and unlock blocks. A
304f194b1c78 First draft version of documentation. asl parents: diff changeset	540 locked block cannot be erased or programmed without it first being
304f194b1c78 First draft version of documentation. asl parents: diff changeset	541 unlocked. For devices which support this feature and when <LITERAL>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	542 CYGHWR_IO_FLASH_BLOCK_LOCKING</LITERAL> is enabled then the following
304f194b1c78 First draft version of documentation. asl parents: diff changeset	543 two functions are available:</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	544
304f194b1c78 First draft version of documentation. asl parents: diff changeset	545 <PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	546 externC int flash_lock(void flash_base, int len, void *err_address);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	547 externC int flash_unlock(void flash_base, int len, void *err_address);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	548 </PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	549
304f194b1c78 First draft version of documentation. asl parents: diff changeset	550 </SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	551 <SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	552
304f194b1c78 First draft version of documentation. asl parents: diff changeset	553 <TITLE>Return values and errors</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	554
304f194b1c78 First draft version of documentation. asl parents: diff changeset	555 <PARA>All the functions above, except <FUNCTION>flash_code_overlaps()
304f194b1c78 First draft version of documentation. asl parents: diff changeset	556 </FUNCTION> return one of the following return values.</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	557
304f194b1c78 First draft version of documentation. asl parents: diff changeset	558 <PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	559 FLASH_ERR_OK No error - operation complete
304f194b1c78 First draft version of documentation. asl parents: diff changeset	560 FLASH_ERR_INVALID Invalid FLASH address
304f194b1c78 First draft version of documentation. asl parents: diff changeset	561 FLASH_ERR_ERASE Error trying to erase
304f194b1c78 First draft version of documentation. asl parents: diff changeset	562 FLASH_ERR_LOCK Error trying to lock/unlock
304f194b1c78 First draft version of documentation. asl parents: diff changeset	563 FLASH_ERR_PROGRAM Error trying to program
304f194b1c78 First draft version of documentation. asl parents: diff changeset	564 FLASH_ERR_PROTOCOL Generic error
304f194b1c78 First draft version of documentation. asl parents: diff changeset	565 FLASH_ERR_PROTECT Device/region is write-protected
304f194b1c78 First draft version of documentation. asl parents: diff changeset	566 FLASH_ERR_NOT_INIT FLASH info not yet initialized
304f194b1c78 First draft version of documentation. asl parents: diff changeset	567 FLASH_ERR_HWR Hardware (configuration?) problem
304f194b1c78 First draft version of documentation. asl parents: diff changeset	568 FLASH_ERR_ERASE_SUSPEND Device is in erase suspend mode
304f194b1c78 First draft version of documentation. asl parents: diff changeset	569 FLASH_ERR_PROGRAM_SUSPEND Device is in program suspend mode
304f194b1c78 First draft version of documentation. asl parents: diff changeset	570 FLASH_ERR_DRV_VERIFY Driver failed to verify data
304f194b1c78 First draft version of documentation. asl parents: diff changeset	571 FLASH_ERR_DRV_TIMEOUT Driver timed out waiting for device
304f194b1c78 First draft version of documentation. asl parents: diff changeset	572 FLASH_ERR_DRV_WRONG_PART Driver does not support device
304f194b1c78 First draft version of documentation. asl parents: diff changeset	573 FLASH_ERR_LOW_VOLTAGE Not enough juice to complete job
304f194b1c78 First draft version of documentation. asl parents: diff changeset	574 </PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	575
304f194b1c78 First draft version of documentation. asl parents: diff changeset	576 <PARA>To turn an error code into a human readable string the following
304f194b1c78 First draft version of documentation. asl parents: diff changeset	577 function can be used:</PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	578
304f194b1c78 First draft version of documentation. asl parents: diff changeset	579 <PROGRAMLISTING>externC char *flash_errmsg(int err);
304f194b1c78 First draft version of documentation. asl parents: diff changeset	580 </PROGRAMLISTING>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	581 </SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	582
304f194b1c78 First draft version of documentation. asl parents: diff changeset	583 <SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	584
304f194b1c78 First draft version of documentation. asl parents: diff changeset	585 <TITLE> Notes on using the FLASH library</TITLE>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	586
304f194b1c78 First draft version of documentation. asl parents: diff changeset	587 <PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	588 The FLASH library evolved from the needs and environment of RedBoot
304f194b1c78 First draft version of documentation. asl parents: diff changeset	589 rather than being a general purpose eCos component. This history
304f194b1c78 First draft version of documentation. asl parents: diff changeset	590 explains some of the problems with the library. </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	591
304f194b1c78 First draft version of documentation. asl parents: diff changeset	592 <PARA>The library is not thread safe. Multiple simultaneous calls to
304f194b1c78 First draft version of documentation. asl parents: diff changeset	593 its library functions will likely fail and may cause a crash. It is
304f194b1c78 First draft version of documentation. asl parents: diff changeset	594 the callers responsibility to use the necessary mutex's if needed.
1745 a9728471a0b5 doco fix msalter parents: 1672 diff changeset	595 </PARA>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	596
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	597 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	598 </SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	599
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	600 <SECT1 id="ecos-flash-v1-dev">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	601 <TITLE>FLASH device API</TITLE> <PARA>This section describes the API
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	602 between the FLASH IO library the FLASH device drivers.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	603
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	604 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	605 <TITLE>The flash_info structure</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	606
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	607 <PARA> The <parameter>flash_info</parameter>structure is used by both
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	608 the FLASH IO library and the device driver.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	609 <PROGRAMLISTING>struct flash_info {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	610 int block_size; // Assuming fixed size "blocks"
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	611 int blocks; // Number of blocks
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	612 int buffer_size; // Size of write buffer (only defined for some devices)
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	613 unsigned long block_mask;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	614 void start, end; // Address range
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	615 int init; // FLASH API initialised
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	616 _printf *pf; // printf like function for diagnostics
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	617 };
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	618 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	619
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	620 <PARA>block_mask is used internally in the FLASH IO library. It
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	621 contains a mask which can be used to turn an arbitrary address in
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	622 flash to the base address of the block which contains the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	623 address.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	624
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	625 <PARA>There exists one global instance of this structure with the name
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	626 <parameter>flash_info</parameter>. All calls into the device driver
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	627 makes use of this global structure to maintain state.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	628
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	629 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	630
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	631 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	632 <TITLE>Initializing the device driver</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	633
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	634 <PARA>The FLASH IO library will call the following function to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	635 initialize the device driver:</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	636
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	637 <PROGRAMLISTING>externC int flash_hwr_init(void);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	638 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	639
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	640 <PARA>The device driver should probe the hardware to see if the FLASH
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	641 devices exist. If it does it should fill in <parameter>start, end,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	642 blocks and block_size.</parameter>If the FLASH contains a write buffer
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	643 the size of this should be placed in <parameter>buffer_size
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	644 </parameter>. On successful probing the function should return
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	645 <literal>FLASH_ERR_OK</literal>. When things go wrong it can be
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	646 assumed that <parameter>pf</parameter> points to a printf like
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	647 function for outputting error messages.
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	648 </PARA>
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	649 </SECT2>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	650
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	651 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	652 <TITLE>Querying the FLASH</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	653
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	654 <PARA>FLASH devices can be queried to return there manufacture ID,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	655 size etc. This function allows this information to be returned.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	656
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	657 <PROGRAMLISTING>int flash_query(unsigned char *data);</PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	658
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	659 <PARA>The caller must know the size of data to be returned and provide
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	660 an appropriately sized buffer pointed to be parameter
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	661 <parameter>data</parameter>. This function is generally used by
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	662 <function>flash_hwr_init()</function>.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	663
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	664 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	665 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	666 <TITLE>Erasing a block of FLASH</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	667
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	668 <PARA>So that the FLASH IO layer can erase a block of FLASH the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	669 following function should be provided.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	670
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	671 <PROGRAMLISTING>int flash_erase_block(volatile flash_t *block, unsigned int block_size);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	672 </PROGRAMLISTING>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	673
304f194b1c78 First draft version of documentation. asl parents: diff changeset	674 </SECT2>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	675 <SECT2>
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	676 <TITLE>Programming a region of FLASH</TITLE>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	677
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	678 <PARA>The following function must be provided so that data can be
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	679 written into the FLASH.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	680
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	681 <PROGRAMLISTING>int flash_program_buf(volatile flash_t addr, flash_t data, int len,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	682 unsigned long block_mask, int buffer_size);</PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	683
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	684 <PARA>The device will only be asked to program data in one block of
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	685 the flash. The FLASH IO layer will break longer user requests into a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	686 smaller writes.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	687
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	688 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	689
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	690 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	691 <TITLE>Reading a region from FLASH</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	692
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	693 <PARA>Some FLASH devices are not memory mapped so it is not possible
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	694 to read there contents directly. The following function read a region
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	695 of FLASH.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	696
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	697 <PROGRAMLISTING>int flash_read_buf(volatile flash_t* addr, flash_t* data, int len);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	698 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	699
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	700 <PARA>As with writing to the flash, the FLASH IO layer will break
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	701 longer user requests for data into a number of reads which are at
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	702 maximum one block in size.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	703
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	704 <PARA>A device which cannot be read directy should set
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	705 <LITERAL>CYGSEM_IO_FLASH_READ_INDIRECT</LITERAL> so that the IO layer
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	706 makes use of the <function>flash_read_buf()</function>function.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	707
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	708 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	709
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	710 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	711 <TITLE>Locking and unlocking FLASH blocks</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	712
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	713 <PARA>Some flash devices allow blocks to be locked so that they cannot
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	714 be written to. The device driver should provide the following
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	715 functions to manipulate these locks.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	716
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	717 <PROGRAMLISTING>int flash_lock_block(volatile flash_t *block);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	718 int flash_unlock_block(volatile flash_t *block, int block_size, int blocks);
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	719 </PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	720
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	721 <PARA>These functions are only used if
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	722 <LITERAL>CYGHWR_IO_FLASH_BLOCK_LOCKING</LITERAL></PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	723
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	724 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	725
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	726 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	727 <TITLE>Mapping FLASH error codes to FLASH IO error codes</TITLE>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	728
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	729 <PARA>The functions <function>flash_erase_block(),
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	730 flash_program_buf(), flash_read_buf(), flash_lock_block() and
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	731 flash_unlock_block()</function> return an error code which is specific
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	732 to the flash device. To map this into a FLASH IO error code, the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	733 driver should provide the following function: </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	734
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	735 <PROGRAMLISTING>int flash_hwr_map_error(int err);</PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	736
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	737 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	738
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	739 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	740 <TITLE>Determining if code is in FLASH</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	741
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	742 <PARA>Although a general function, the device driver is expected to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	743 provide the implementation of the function
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	744 <function>flash_code_overlaps()</function>.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	745
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	746 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	747
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	748 <SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	749 <TITLE>Implementation Notes</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	750
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	751 <PARA>The FLASH IO layer will manipulate the caches as required. The
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	752 device drivers do not need to enable/disable caches when performing
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	753 operations of the FLASH.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	754
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	755 <PARA>Device drivers should keep all chatter to a minimum when
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	756 <literal>CYGSEM_IO_FLASH_CHATTER</literal> is not defined. All output
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	757 should use the print function in the <parameter>pf</parameter> in
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	758 <parameter>flash_info</parameter> and not
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	759 <function>diag_printf()</function></PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	760
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	761 <PARA>Device driver functions which manipulate the state of the flash
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	762 so that it cannot be read from for program execute need to ensure
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	763 there code is placed into RAM. The linker will do this if the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	764 appropriate attribute is added to the function. e.g:</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	765
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	766 <PROGRAMLISTING>int flash_program_buf(volatile flash_t addr, flash_t data, int len,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	767 unsigned long block_mask, int buffer_size)
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	768 __attribute__ ((section (".2ram.flash_program_buf")));</PROGRAMLISTING>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	769
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	770 </SECT2>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	771 </SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	772 </CHAPTER>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	773
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	774 <CHAPTER id="ecos-flash-iodevice">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	775 <TITLE>FLASH I/O devices</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	776
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	777 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	778 It can be useful to be able to access FLASH devices using the generic
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	779 I/O infrastructure found in <varname>CYGPKG_IO</varname>, and the generic
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	780 FLASH layer provides an optional ability to do so. This allows
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	781 the use of functions like <function>cyg_io_lookup()</function>,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	782 <function>cyg_io_read()</function>,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	783 <function>cyg_io_write()</function> etc.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	784 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	785 <PARA> Additionally it means that, courtesy of the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	786 “devfs” pseudo-filesystem in the file I/O layer
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	787 (<varname>CYGPKG_IO_FILEIO</varname>), functions like
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	788 <function>open()</function>, <function>read()</function>,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	789 <function>write()</function> etc. can even be used directly
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	790 on the FLASH devices.
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	791 </PARA>
304f194b1c78 First draft version of documentation. asl parents: diff changeset	792
2626 a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	793 <SECT1 id="ecos-flash-iodevice-overview-config">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	794 <TITLE>Overview and CDL Configuration</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	795
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	796 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	797 This package implements support for FLASH as an I/O device by exporting
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	798 it as if it is a block device. To enable this support, the CDL option
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	799 titled “Provide /dev block devices”, also known as
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	800 <varname>CYGPKG_IO_FLASH_BLOCK_DEVICE</varname>, must be enabled.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	801 (There is also a legacy format alternative which is now deprecated).
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	802 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	803 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	804 There are two methods of addressing FLASH as a block device:</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	805
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	806 <orderedlist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	807 <listitem><para>Using the FLASH Information System (FIS) - this is a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	808 method of defining and naming FLASH partitions, usually in RedBoot.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	809 This option is only valid if RedBoot is resident and was used to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	810 boot the application. To reference FLASH partitions in this way,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	811 you would use a device name of the form
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	812 <filename>/dev/flash/fis/<replaceable>partition-name</replaceable></filename>,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	813 for example <filename>/dev/flash/fis/jffs2</filename> to reference a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	814 FIS partition named JFFS2.</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	815
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	816 <para>The CDL option <varname>CYGFUN_IO_FLASH_BLOCK_FROM_FIS</varname>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	817 must be enabled for this support.</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	818 </listitem>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	819
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	820 <listitem><para>Referencing by device number, offset and length - this
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	821 method extracts addressing information from the name itself. The form
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	822 of the device would be
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	823 <filename>/dev/flash/<replaceable>device-number</replaceable>/<replaceable>offset</replaceable>[,<replaceable>length</replaceable></filename>]</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	824
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	825 <variablelist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	826 <varlistentry><term><replaceable>device-number</replaceable></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	827
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	828 <listitem><para>This is a fixed number allocated to identify each FLASH
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	829 region in the system. The first region is numbered 0, the second 1,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	830 and so on. If you have only one FLASH device, it will be numbered 0.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	831 </para></listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	832
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	833 <varlistentry><term><replaceable>offset</replaceable></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	834 <listitem><para>This is the index into the FLASH region in bytes to use. It
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	835 may be specified as decimal, or if prefixed with
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	836 <literal>0x</literal>, then hexadecimal.</para></listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	837
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	838 <varlistentry><term><replaceable>length</replaceable></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	839 <listitem><para>This field is optional and defaults to the remainder
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	840 of the FLASH region. Again it may be specified in decimal or
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	841 hexadecimal.</para></listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	842 </variablelist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	843
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	844 <para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	845 Some examples:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	846 <variablelist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	847 <varlistentry><term>/dev/flash/0/0</term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	848 <listitem><para>This defines a block device that uses the entirety of
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	849 FLASH region 0.</para></listitem>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	850 </varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	851 <varlistentry><term>/dev/flash/1/0x20000,65536</term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	852 <listitem><para>This defines a block device which points inside FLASH region 1,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	853 starting at offset 0x20000 (128Kb) and extending for 64Kb.</para></listitem>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	854 </varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	855 <varlistentry><term>/dev/flash/0/65536</term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	856 <listitem><para>This defines a block device which points inside FLASH region 0,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	857 starting at offset 64Kb and continuing up to the end of the device.</para></listitem>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	858 </varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	859 </variablelist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	860 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	861 <para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	862 Obviously great care is required when constructing the device names as
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	863 using the wrong specification may subsequently overwrite important areas
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	864 of FLASH, such as RedBoot. Using the alternative via FIS names is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	865 preferable as these are less error-prone to configure, and also allows for
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	866 the FLASH region to be relocated without requiring program recompilation.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	867 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	868 </listitem>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	869 </orderedlist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	870 </SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	871 <SECT1 id="ecos-flash-iodevice-usage">
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	872 <TITLE>Using FLASH I/O devices</TITLE>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	873 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	874 The FLASH I/O block devices can be accessed, read and written using
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	875 the standard interface supplied by the generic I/O
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	876 (<varname>CYGPKG_IO</varname>) package. These include the functions:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	877 <function>cyg_io_lookup()</function> to access the device and get a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	878 handle, <function>cyg_io_read()</function> and
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	879 <function>cyg_io_write()</function> for sequential read and write
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	880 operations, <function>cyg_io_bread()</function> and
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	881 <function>cyg_io_bwrite()</function> for random access read and write
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	882 operations, and <function>cyg_io_get_config()</function> and
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	883 <function>cyg_io_setconfig()</function> for run-time configuration
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	884 inspection and control.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	885 </PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	886 <PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	887 However there are two aspects that differ from some other I/O devices
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	888 accessed this way:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	889 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	890 <orderedlist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	891 <listitem><para>The first is that the lookup operation uses up
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	892 resources which must be subsequently freed when the last user of the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	893 I/O handle is finished. The number of FLASH I/O devices that may be
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	894 simultaneously opened is configured with the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	895 <varname>CYGNUM_IO_FLASH_BLOCK_DEVICES</varname> CDL option. After the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	896 last user is finished, the device may be closed using
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	897 <function>cyg_io_setconfig()</function> with the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	898 <varname>CYG_IO_SET_CONFIG_CLOSE</varname> key. Reference counting to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	899 ensure that it is only the last user that causes a close, is left to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	900 higher layers.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	901 </para></listitem>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	902 <listitem><para>The second is that write operations assume that the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	903 flash is already erased. Attempting to write to Flash that has
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	904 already been written to may result in errors. Instead FLASH must
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	905 be erased before it may be written.</para></listitem>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	906 </orderedlist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	907
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	908 <PARA>FLASH block devices can also be read and written using the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	909 standard POSIX primitives, <function>open()</function>,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	910 <function>close()</function>, <function>read()</function>,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	911 <function>write()</function>, <function>lseek()</function>, and so on
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	912 if the POSIX file I/O package (<varname>CYGPKG_FILEIO</varname>) is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	913 included in the configuration. As with the eCos generic I/O interface
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	914 you must call <function>close()</function> to ensure resources
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	915 are freed when the device is no longer used.</PARA>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	916
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	917 <PARA>Other configuration keys are provided to perform FLASH erase
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	918 operations, and to retrieve device sizes, and FLASH block sizes at
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	919 a particular address. These operations are accessed with
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	920 <function>cyg_io_get_config()</function> (or if using the POSIX
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	921 file I/O API, <function>cyg_fs_getinfo()</function>) with the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	922 following keys:</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	923
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	924 <variablelist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	925 <varlistentry><term><varname>CYG_IO_GET_CONFIG_FLASH_ERASE</varname></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	926 <listitem><para>This erases a region of FLASH.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	927 <function>cyg_io_get_config()</function> must be passed a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	928 structure defined as per the following, which is also supplied
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	929 in <filename><cyg/io/flash.h></filename>:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	930 <programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	931 typedef struct {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	932 CYG_ADDRESS offset;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	933 size_t len;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	934 int flasherr;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	935 cyg_flashaddr_t err_address;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	936 } cyg_io_flash_getconfig_erase_t;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	937 </programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	938 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	939 <para> In this structure, <structfield>offset</structfield> specifies
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	940 the offset within the block device to erase, <structfield>len</structfield>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	941 specifies the amount to address, <structfield>flasherr</structfield> is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	942 set on return to specify an error with the FLASH erase operation itself,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	943 and <structfield>err_address</structfield> is used if there was an error
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	944 to specify at which address the error happened.</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	945 </listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	946
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	947 <varlistentry><term><varname>CYG_IO_GET_CONFIG_FLASH_LOCK</varname></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	948 <listitem><para>This protects a region of FLASH using the locking facilities
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	949 available on the card, if provided by the underlying driver.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	950 <function>cyg_io_get_config()</function> must be passed a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	951 structure defined as per the following:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	952 <programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	953 typedef struct {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	954 CYG_ADDRESS offset;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	955 size_t len;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	956 int flasherr;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	957 cyg_flashaddr_t err_address;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	958 } cyg_io_flash_getconfig_lock_t;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	959 </programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	960 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	961 <para> In this structure, <structfield>offset</structfield> specifies
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	962 the offset within the block device to lock, <structfield>len</structfield>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	963 specifies the amount to address, <structfield>flasherr</structfield> is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	964 set on return to specify an error with the FLASH lock operation itself,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	965 and <structfield>err_address</structfield> is used if there was an error
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	966 to specify at which address the error happened. If locking
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	967 support is not available -EINVAL will be returned from
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	968 <function>cyg_io_get_config()</function>.</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	969 </listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	970
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	971 <varlistentry><term><varname>CYG_IO_GET_CONFIG_FLASH_UNLOCK</varname></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	972 <listitem><para>This disables protection for a region of FLASH using the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	973 unlocking facilities available on the card, if provided by the underlying driver.
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	974 <function>cyg_io_get_config()</function> must be passed a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	975 structure defined as per the following:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	976 <programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	977 typedef struct {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	978 CYG_ADDRESS offset;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	979 size_t len;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	980 int flasherr;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	981 cyg_flashaddr_t err_address;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	982 } cyg_io_flash_getconfig_unlock_t;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	983 </programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	984 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	985 <para> In this structure, <structfield>offset</structfield> specifies
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	986 the offset within the block device to unlock, <structfield>len</structfield>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	987 specifies the amount to address, <structfield>flasherr</structfield> is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	988 set on return to specify an error with the FLASH unlock operation itself,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	989 and <structfield>err_address</structfield> is used if there was an error
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	990 to specify at which address the error happened. If unlocking
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	991 support is not available -EINVAL will be returned from
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	992 <function>cyg_io_get_config()</function>.</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	993 </listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	994
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	995 <varlistentry><term><varname>CYG_IO_GET_CONFIG_FLASH_DEVSIZE</varname></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	996 <listitem><para>This returns the size of the FLASH block device. The
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	997 <function>cyg_io_get_config()</function> function must be passed a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	998 structure defined as per the following, which is also supplied
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	999 in <filename><cyg/io/flash.h></filename>:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1000 <programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1001 typedef struct {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1002 size_t dev_size;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1003 } cyg_io_flash_getconfig_devsize_t;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1004 </programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1005 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1006 <para> In this structure, <structfield>dev_size</structfield> is used to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1007 return the size of the FLASH device.</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1008 </listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1009
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1010 <varlistentry><term><varname>CYG_IO_GET_CONFIG_FLASH_DEVADDR</varname></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1011 <listitem><para>This returns the address in the virtual memory map that the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1012 generic flash layer has been informed that this FLASH device is mapped to. Note
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1013 that some flash devices such as dataflash are not truly memory mapped,
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1014 and so this function only returns useful information when used with a true
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1015 memory mapped FLASH device. The
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1016 <function>cyg_io_get_config()</function> function must be passed a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1017 structure defined as per the following, which is also supplied
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1018 in <filename><cyg/io/flash.h></filename>:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1019 <programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1020 typedef struct {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1021 cyg_flashaddr_t dev_addr;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1022 } cyg_io_flash_getconfig_devaddr_t;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1023 </programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1024 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1025 <para> In this structure, <structfield>dev_addr</structfield> is used to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1026 return the address corresponding to the base of the FLASH device in the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1027 virtual memory map.</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1028 </listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1029
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1030 <varlistentry><term><varname>CYG_IO_GET_CONFIG_FLASH_BLOCKSIZE</varname></term>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1031 <listitem><para>This returns the size of a FLASH block at a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1032 supplied offset in the FLASH block device. The
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1033 <function>cyg_io_get_config()</function> function must be passed a
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1034 structure defined as per the following, which is also supplied
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1035 in <filename><cyg/io/flash.h></filename>:
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1036 <programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1037 typedef struct {
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1038 CYG_ADDRESS offset;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1039 size_t block_size;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1040 } cyg_io_flash_getconfig_blocksize_t;
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1041 </programlisting>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1042 </para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1043 <para> In this structure, <structfield>offset</structfield> specifies the
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1044 address within the block device of which the FLASH block size is
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1045 required - a single FLASH device may contain blocks of differing
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1046 sizes. The <structfield>block_size</structfield> field is used to
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1047 return the block size at the specified offset.</para>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1048 </listitem></varlistentry>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1049 </variablelist>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1050 </SECT1>
a2f5434df2cb Merge flashv2 branch to trunk, with eCosCentric additions jlarmour parents: 1745 diff changeset	1051 </CHAPTER>
1672 304f194b1c78 First draft version of documentation. asl parents: diff changeset	1052 </PART>

Mercurial > ecos

annotate packages/io/flash/current/doc/flash.sgml @ 2658:aee6bfaf78cd