This is the mail archive of the
ecos-patches@sources.redhat.com
mailing list for the eCos project.
v2 flash - am29xxxxx v2 docs update
- From: Bart Veer <bartv at ecoscentric dot com>
- To: ecos-patches at ecos dot sourceware dot org
- Date: Wed, 23 Feb 2005 23:10:31 +0000 (GMT)
- Subject: v2 flash - am29xxxxx v2 docs update
Just bringing the driver docs up to date with the current flash code.
Bart
Index: ChangeLog
===================================================================
RCS file: /cvs/ecos/ecos/packages/devs/flash/amd/am29xxxxxv2/current/Attic/ChangeLog,v
retrieving revision 1.1.2.9
diff -u -r1.1.2.9 ChangeLog
--- ChangeLog 23 Feb 2005 15:49:28 -0000 1.1.2.9
+++ ChangeLog 23 Feb 2005 23:09:47 -0000
@@ -1,3 +1,7 @@
+2005-02-23 Bart Veer <bartv@ecoscentric.com>
+
+ * doc/am29xxxxx.sgml: bring up to date.
+
2005-01-19 Jonathan Larmour <jifl@eCosCentric.com>
* src/am29xxxxx_aux.c (am29_hw_erase): Handle interleaved
@@ -47,7 +51,7 @@
//####ECOSGPLCOPYRIGHTBEGIN####
// -------------------------------------------
// This file is part of eCos, the Embedded Configurable Operating System.
-// Copyright (C) 2004 eCosCentric Limited
+// Copyright (C) 2004, 2005 eCosCentric Limited
//
// eCos is free software; you can redistribute it and/or modify it under
// the terms of the GNU General Public License as published by the Free
Index: doc/am29xxxxx.sgml
===================================================================
RCS file: /cvs/ecos/ecos/packages/devs/flash/amd/am29xxxxxv2/current/doc/Attic/am29xxxxx.sgml,v
retrieving revision 1.1.2.3
diff -u -r1.1.2.3 am29xxxxx.sgml
--- doc/am29xxxxx.sgml 22 Nov 2004 20:11:22 -0000 1.1.2.3
+++ doc/am29xxxxx.sgml 23 Feb 2005 23:10:16 -0000
@@ -12,7 +12,7 @@
<!-- ####ECOSPRODOCCOPYRIGHTBEGIN#### -->
<!-- -->
<!-- This file is part of eCosPro(tm) -->
-<!-- Copyright (C) 2004 eCosCentric Limited -->
+<!-- Copyright (C) 2004, 2005 eCosCentric Limited -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- form is prohibited unless prior permission obtained from the -->
<!-- copyright holder -->
@@ -44,7 +44,7 @@
<para>
The <varname>CYGPKG_DEVS_FLASH_AMD_AM29XXXXX_V2</varname> AMD
AM29xxxxx V2 flash driver package implements support for the AM29xxxxx
-family of flash devices and compatibles. The driver is not normally
+family of flash devices and compatibles. Normally the driver is not
accessed directly. Instead application code will use the API provided
by the generic flash driver package
<varname>CYGPKG_IO_FLASH</varname>, for example by calling functions
@@ -112,10 +112,6 @@
#include <cyg/io/am29xxxxx_dev.h>
</funcsynopsisinfo>
<funcprototype>
- <funcdef>int <function>cyg_am29xxxxx_init_nop</function></funcdef>
- <paramdef>struct cyg_flash_dev* <parameter>device</parameter></paramdef>
- </funcprototype>
- <funcprototype>
<funcdef>int <function>cyg_am29xxxxx_init_check_devid_XX</function></funcdef>
<paramdef>struct cyg_flash_dev* <parameter>device</parameter></paramdef>
</funcprototype>
@@ -136,27 +132,6 @@
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
- <funcdef>int <function>cyg_am29xxxxx_query_nop</function></funcdef>
- <paramdef>struct cyg_flash_dev* <parameter>device</parameter></paramdef>
- <paramdef>void* <parameter>data</parameter></paramdef>
- <paramdef>const size_t <parameter>len</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>int <function>cyg_am29xxxxx_hwr_map_error_nop</function></funcdef>
- <paramdef>struct cyg_flash_dev* <parameter>device</parameter></paramdef>
- <paramdef>int <parameter>err</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>int <function>cyg_am29xxxxx_lock_nop</function></funcdef>
- <paramdef>struct cyg_flash_dev* <parameter>device</parameter></paramdef>
- <paramdef>const cyg_flashaddr_t <parameter>addr</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>int <function>cyg_am29xxxxx_unlock_nop</function></funcdef>
- <paramdef>struct cyg_flash_dev* <parameter>device</parameter></paramdef>
- <paramdef>const cyg_flashaddr_t <parameter>addr</parameter></paramdef>
- </funcprototype>
- <funcprototype>
<funcdef>int <function>cyg_am29xxxxx_read_devid_XX</function></funcdef>
<paramdef>struct cyg_flash_dev* <parameter>device</parameter></paramdef>
</funcprototype>
@@ -166,16 +141,16 @@
<refsect1 id="am29xxxxx-instance-description"><title>Description</title>
<para>
The AM29xxxxx family contains some hundreds of different flash
-devices, all supporting the same basic set of operations, with various
-common or uncommon extensions. The devices vary in capacity,
+devices, all supporting the same basic set of operations but with
+various common or uncommon extensions. The devices vary in capacity,
performance, boot block layout, and width. There are also
platform-specific issues such as how many devices are actually present
on the board and where they are mapped in the address space. The
-AM29xxxxx driver package cannot know all this information. Instead it
-is the responsibility of another package, usually the platform HAL, to
-instantiate some flash device structures. Two pieces of information
-are especially important: the bus configuration and the boot block
-layout.
+AM29xxxxx driver package cannot know the details of every chip and
+every platform. Instead it is the responsibility of another package,
+usually the platform HAL, to supply the necessary information by
+instantiating some data structures. Two pieces of information are
+especially important: the bus configuration and the boot block layout.
</para>
<para>
Flash devices are typically 8-bits, 16-bits, or 32-bits wide (64-bit
@@ -185,10 +160,9 @@
or more of these devices on the bus. For example there may be a single
16-bit device on a 16-bit bus, or two 16-bit devices on a 32-bit bus.
The processor's bus logic determines which combinations are possible,
-and usually there will be a trade off between cost and performance.
-For example two 16-bit devices in parallel can provide twice the
-memory bandwidth of a single device. The driver supports the following
-combinations:
+and there will be a trade off between cost and performance: two 16-bit
+devices in parallel can provide twice the memory bandwidth of a single
+device. The driver supports the following combinations:
</para>
<variablelist>
<varlistentry>
@@ -226,7 +200,7 @@
<listitem><para>
Two parallel 16-bit devices on a 32-bit bus, with one device providing
the bottom two bytes of each 32-bit datum and the other device
-providing the upper two bytes.
+providing the top two bytes.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -248,7 +222,7 @@
</para></caution>
<para>
The second piece of information is the boot block layout. Flash
-devices are subdivided into blocks (also known as sectors, both terms
+devices are subdivided into blocks (also known as sectors - both terms
are in common use). Some operations such as erase work on a whole
block at a time, and for most applications a block is the smallest
unit that gets updated. A typical block size is 64K. It is inefficient
@@ -266,11 +240,11 @@
<refsect1 id="am29xxxxx-instance-example"><title>Example</title>
<para>
-Flash support is usually specific to each platform. Even if two
+In most cases flash support is specific to a platform. Even if two
platforms happen to use the same flash device there are likely to be
differences such as the location in the address map. Hence there is
little possibility of re-using the platform-specific code, and this
-code is generally placed in the platform HAL rather than in a separate
+code should be placed in the platform HAL rather than in a separate
package. Typically this involves a separate file and a corresponding
compile property in the platform HAL's CDL:
</para>
@@ -295,18 +269,17 @@
#ifdef CYGPKG_DEVS_FLASH_AMD_AM29XXXXX_V2
#include <cyg/io/flash.h>
-#include <cyg/io/flash_priv.h>
+#include <cyg/io/flash_dev.h>
#include <cyg/io/am29xxxxx_dev.h>
static const CYG_FLASH_FUNS(hal_alaia_flash_amd_funs,
&cyg_am29xxxxx_init_check_devid_16,
- &cyg_am29xxxxx_query_nop,
+ &cyg_flash_devfn_query_nop,
&cyg_am29xxxxx_erase_16,
&cyg_am29xxxxx_program_16,
(int (*)(struct cyg_flash_dev*, const cyg_flashaddr_t, void*, size_t))0,
- &cyg_am29xxxxx_hwr_map_error_nop,
- &cyg_am29xxxxx_lock_nop,
- &cyg_am29xxxxx_unlock_nop);
+ &cyg_flash_devfn_lock_nop,
+ &cyg_flash_devfn_unlock_nop);
static const cyg_am29xxxxx_dev hal_alaia_flash_priv = {
.devid = 0x45,
@@ -321,7 +294,7 @@
CYG_FLASH_DRIVER(hal_alaia_flash,
&hal_alaia_flash_amd_funs,
0,
- 0xFFE00000,
+ 0xFFC00000,
0xFFFFFFFF,
4,
hal_alaia_flash_priv.block_info,
@@ -330,20 +303,21 @@
#endif
</programlisting>
<para>
-The bulk of the file is protected by an ifdef for the AM29xxxxx flash
-driver. That driver will only be active if the generic flash support
-is enabled. Without that support there will be no way of accessing
-the device so there is no point in instantiating the device. The rest
-of the file is split into three definitions. The first supplies the
-functions which will be used to perform the actual flash accesses,
-using a macro provided by the generic flash code in <filename
-class="headerfile">cyg/io/flash_priv.h</filename>. The
-relevant ones have an <literal>_16</literal> suffix, indicating that
-on this board there is a single 16-bit flash device on a 16-bit
-bus. The second definition provides information specific to AM29xxxxx
-flash devices. The third provides the
-<structname>cyg_flash_dev</structname> structure needed by the generic
-flash code, which contains pointers to the previous two.
+The bulk of the file is protected by an <literal>#ifdef</literal> for
+the AM29xxxxx flash driver. That driver will only be active if the
+generic flash support is enabled. Without that support there will be
+no way of accessing the device so instantiating the data structures
+would serve no purpose. The rest of the file is split into three
+structure definitions. The first supplies the functions which will be
+used to perform the actual flash accesses, using a macro provided by
+the generic flash code in <filename
+class="headerfile">cyg/io/flash_dev.h</filename>. The relevant ones
+have an <literal>_16</literal> suffix, indicating that on this board
+there is a single 16-bit flash device on a 16-bit bus. The second
+provides information specific to AM29xxxxx flash devices.
+The third provides the <structname>cyg_flash_dev</structname>
+structure needed by the generic flash code, which contains pointers to
+the previous two.
</para>
</refsect1>
@@ -351,15 +325,13 @@
<para>
All eCos flash device drivers must implement a standard interface,
defined by the generic flash code <varname>CYGPKG_IO_FLASH</varname>.
-This interface includes a table of 8 function pointers for various
-operations: initialization, query, erase, program, read, error code
-handling, locking and unlocking. The query operation is optional and
-the AM29xxxxx driver only provides a dummy implementation
-<function>cyg_am29xxxxx_query_nop</function>. AM29xxxxx flash devices
-are always directly accessible so there is no need for a separate read
-function. Standard flash error codes are used so only a dummy
-<function>cyg_am29xxxxx_hwr_map_error_nop</function> function is
-needed. The remaining functions are more complicated.
+This interface includes a table of seven function pointers for various
+operations: initialization, query, erase, program, read, locking and
+unlocking. The query operation is optional and the generic flash
+support provides a dummy implementation
+<function>cyg_flash_devfn_query_nop</function>. AM29xxxxx flash
+devices are always directly accessible so there is no need for a
+separate read function. The remaining functions are more complicated.
</para>
<para>
Usually the table can be declared <literal>const</literal>. In a ROM
@@ -372,8 +344,8 @@
<refsect2 id="am29xxxxx-instance-functions-init"><title>Initialization</title>
<para>
There is a choice of three main initialization functions. The simplest
-is <function>cyg_am29xxxxx_init_nop</function>, which does nothing. It
-can be used if the <structname>cyg_am29xxxxx_dev</structname> and
+is <function>cyg_flash_devfn_init_nop</function>, which does nothing.
+It can be used if the <structname>cyg_am29xxxxx_dev</structname> and
<structname>cyg_flash_dev</structname> structures are fully
initialized statically and the flash will just work without special
effort. This is useful if it is guaranteed that the board will always
@@ -383,15 +355,14 @@
<para>
The next step up is
<function>cyg_am29xxxxx_init_check_devid_XX</function>, where
-<literal>XX</literal> will be replaced by the suffix appropriate for the
-bus configurati
+CDL can require appropriate values for these options.
</para>
</refsect2>
<refsect2 id="am29xxxxx-instance-functions-locking"><title>Locking</title>
<para>
There is no single way of implementing the block lock and unlock
-operations on AM29xxxxx devices. If these operations are supported at
-all then usually they involve manipulating the voltages on certain
+operations on all AM29xxxxx devices. If these operations are supported
+at all then usually they involve manipulating the voltages on certain
pins. This cannot be handled by generic driver code since it requires
-knowing exactly how these pins can be manipulated via the processor's
-GPIO pins. Therefore the AM29xxxxx driver does not provide functional
-lock and unlock functions, only dummy functions
-<function>cyg_am29xxxxx_lock_nop</function> and
-<function>cyg_am29xxxxx_unlock_nop</function>. If there is a way of
-implementing the locking then this can be handled by platform-specific
-functions.
+knowing how these voltages can be manipulated via the processor's GPIO
+lines. Therefore the AM29xxxxx driver does not provide lock and unlock
+functions, and instead the generic dummy functions
+<function>cyg_flash_devfn_lock_nop</function> and
+<function>cyg_flash_devfn_unlock_nop</function> should be used. If a
+platform does provide a way of implementing the locking then this can
+be handled by platform-specific functions.
</para>
<programlisting width=72>
static int
@@ -569,7 +547,7 @@
<orderedlist>
<listitem><para>
If the driver initialization function is set to
-<function>cyg_am29xxxxx_init_nop</function> or
+<function>cyg_flash_devfn_init_nop</function> or
<function>cyg_am29xxxxx_init_check_devid_XX</function> then the block
information should be provided statically. This is appropriate if the
board will also be manufactured using the same flash chip.
@@ -597,7 +575,7 @@
If the <structname>cyg_am29xxxxx_dev</structname> structure is
statically initialized then it can be <literal>const</literal>. This
saves a small amount of memory in ROM startup applications. If the
-structure may be updated at run-time, either by
+structure is updated at run-time, either by
<function>cyg_am29xxxxx_init_cfi_XX</function> or by a
platform-specific initialization routine, then it cannot be
<literal>const</literal>.
@@ -606,7 +584,7 @@
<refsect1 id="am29xxxxx-instance-flash"><title>Flash Structure</title>
<para>
-Internally the flash code works in terms of
+Internally the generic flash code works in terms of
<structname>cyg_flash_dev</structname> structures, and the platform
HAL should define one of these. The structure should be placed in the
<literal>cyg_flashdev</literal> table. The following fields need to be