ecos-v3_0-branch: packages/io/flash/current/doc/flash.sgml annotate

annotate packages/io/flash/current/doc/flash.sgml @ 2816:422d0a343b4d

* include/flash.h: Modest API change: cyg_flash_init() no longer takes a printf function argument. Instead two new API functions are available: cyg_flash_set_printf() and cyg_flash_set_global_printf(). * src/flash.c (CHATTER): Don't attempt output if printf function is NULL. (cyg_flash_init): No longer takes printf arg. (cyg_flash_set_printf): New. Set per-device printf function, locking if needed. (cyg_flash_set_global_printf): New. Set printf function for all devices, locking if needed. * src/flashiodev.c (flashiodev_init): cyg_flash_init no longer takes printf arg, and we can leave global printf at default. * src/flashiodevlegacy.c (flashiodev_init): Ditto. * src/legacy_api.c (flash_init): cyg_flash_init no longer takes printf arg. So call cyg_flash_set_global_printf as well. * src/legacy_dev.c (legacy_flash_init): legacy drivers can't handle NULL printf function, so provide a dummy. * doc/flash.sgml: Document removal of printf functionality of cyg_flash_init() and document cyg_flash_set_printf() and cyg_flash_set_global_printf().

author	jlarmour
date	Thu, 19 Feb 2009 00:14:26 +0000
parents	0da3d39aa3df
children	c4521b91e076

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

Mercurial > ecos-v3_0-branch

annotate packages/io/flash/current/doc/flash.sgml @ 2816:422d0a343b4d