nand-ecoscentric: packages/io/nand/current/doc/nand.sgml annotate

annotate packages/io/nand/current/doc/nand.sgml @ 3395:707de7f35fc7

io/nand: Minor doc updates

author	Ross Younger <wry@ecoscentric.com>
date	Tue, 02 Dec 2014 12:13:34 +1300
parents	8502a048ad17
children

rev	line source
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	2 <!-- {{{ Banner -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	3
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	4 <!-- =============================================================== -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	5 <!-- -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	6 <!-- nand.sgml -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	7 <!-- -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	8 <!-- Documentation for the eCos NAND flash access library. -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	9 <!-- -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	10 <!-- =============================================================== -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	11 <!-- ####ECOSDOCCOPYRIGHTBEGIN#### -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	12 <!-- =============================================================== -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	13 <!-- Copyright (C) 2009 eCosCentric Ltd. -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	14 <!-- This material may be distributed only subject to the terms -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	15 <!-- and conditions set forth in the Open Publication License, v1.0 -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	16 <!-- or later (the latest version is presently available at -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	17 <!-- http://www.opencontent.org/openpub/) -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	18 <!-- Distribution of the work or derivative of the work in any -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	19 <!-- standard (paper) book form is prohibited unless prior -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	20 <!-- permission obtained from the copyright holder -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	21 <!-- =============================================================== -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	22 <!-- ####ECOSDOCCOPYRIGHTEND#### -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	23 <!-- =============================================================== -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	24 <!-- #####DESCRIPTIONBEGIN#### -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	25 <!-- -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	26 <!-- Author(s): wry -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	27 <!-- Date: 2009/04/17 -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	28 <!-- -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	29 <!-- ####DESCRIPTIONEND#### -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	30 <!-- =============================================================== -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	31
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	32 <!-- }}} -->
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	33
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	34 <part id="io-nand-overview">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	35 <title>The eCos NAND Flash Library</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	36 <titleabbrev id="io-nand-short">eCos NAND Flash Library</titleabbrev>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	37
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	38 <chapter id="nand-overview-c">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	39 <title>NAND Library Overview</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	40
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	41 <sect1 id="nand-overview1"><title>Description</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	42 <para>This is a library which allows NAND flash devices to be accessed
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	43 by the eCos kernel and applications. It is analogous to the eCos FLASH
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	44 library, but for NAND devices. It exists as a separate library because of
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	45 the fundamental differences between the two types of flash memory.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	46
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	47 <para>This library provides the following functionality:
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	48 <itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	49 <listitem><para>Interrogation to confirm that the expected device is
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	50 present</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	51 <listitem><para>Reading from and writing to flash pages</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	52 <listitem><para>Erasing flash blocks</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	53 <listitem><para>The ability to divide a single device into multiple
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	54 partitions, like those of a hard drive</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	55 <listitem><para>Creation and maintenance of a Bad Block Table</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	56 <listitem><para>Use of an Error Correcting Code to detect and correct
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	57 single-bit errors, and to detect multiple-bit errors</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	58 <listitem><para>Packing of the ECC and application out-of-band data into
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	59 the spare area on the device</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	60 </itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	61 <note><para>The spare area, ECC and bad block table have been
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	62 deliberately created with the intention of compatibility with
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	63 current versions of the Linux MTD layer. For example, this would
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	64 allow a single NAND device to be accessed by RedBoot to load a Linux
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	65 kernel, which could then go on to use another partition as its root
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	66 filesystem.</para></note> </para> <tip><para>This library is also used
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	67 as glue to allow appropriate filesystems to use NAND devices. This
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	68 allows more useful higher-level access by applications and RedBoot via
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	69 the File I/O and POSIX interfaces. In other words, your application
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	70 may not need to invoke this library directly, though of course you
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	71 may still have to write a driver for your chip and/or board.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	72 </para></tip>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	73
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	74 <sect2 id="nand-lib-structure"><title>Structure of the library</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	75 <para>This library has two principal interfaces: one for
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	76 <emphasis>applications</emphasis> to call into it, and another to call
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	77 out to the chip-specific <emphasis>drivers</emphasis>. (The chip drivers
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	78 themselves then require support from the relevant platform HAL to allow
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	79 them to access the physical chip in an appropriate manner for the board -
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	80 such as the memory-mapped I/O range to use.)</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	81
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	82 <para>The following diagram illustrates the calls from two applications
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	83 all the way to an underlying NAND device. Application 1 uses the NAND
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	84 library directly, whereas application 2 is using a filesystem and the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	85 eCos File I/O layer.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	86
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	87 <mediaobject>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	88 <imageobject>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	89 <imagedata fileref="nandlib-layout.png" align=center scalefit=1 depth=600>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	90 </imageobject>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	91 <textobject>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	92 <phrase>Library layout diagram</phrase>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	93 </textobject>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	94 </mediaobject>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	95
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	96 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	97 <sect2 id="nand-lib-devsupport"><title>Device support</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	98 <para>Before this library can be used on a given board, an appropriate
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	99 device driver must be created. Each driver is for a particular NAND
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	100 part or family of parts; the HAL for each board then instantiates the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	101 relevant driver(s) appropriately with board-specific glue such as the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	102 memory-mapped I/O range to use. Full details on creating a driver are
2942 b7de7e438610 * Fixed more "jade" syntax issues alexs parents: 2940 diff changeset	103 presented in <xref linkend="nand-devs-writing">.</para>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	104
2942 b7de7e438610 * Fixed more "jade" syntax issues alexs parents: 2940 diff changeset	105 <para>There is also a <xref linkend="devs-nand-synth"> for testing purposes,
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	106 which is present on the <emphasis>synth</emphasis> target.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	107 </para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	108 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	109 </sect1>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	110 <SECT1 id="nand-danger">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	111 <TITLE>Danger, Will Robinson! Danger!</TITLE>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	112
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	113 <PARA>Unlike nearly every other aspect of embedded system programming,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	114 getting it wrong with FLASH devices can render your target system
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	115 useless. Most targets have a boot loader in the FLASH. Without this
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	116 boot loader the target will obviously not boot. So before starting to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	117 play with this library its worth investigating a few things. How do
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	118 you recover your target if you delete the boot loader? Do you have the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	119 necessary JTAG cable? Or is specialist hardware needed? Is it even
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	120 possible to recover the target boards or must it be thrown into the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	121 rubbish bin? How does killing the board affect your project schedule?
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	122 </PARA>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	123
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	124 </SECT1>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	125
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	126
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	127 <sect1 id="nand-nor-diff"><title>Differences between NAND and NOR flash</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	128 <para>Most flash devices supported by the eCos Flash library are
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	129 categorised as NOR flash. These are fundamentally different from NAND
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	130 flash devices, both in terms of the storage cells deep within the chip,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	131 and how they are addressed and used by applications.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	132
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	133 <informaltable frame=topbot pgwide=1>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	134 <tgroup cols=3>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	135 <colspec colname=what>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	136 <colspec colname=nor>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	137 <colspec colname=nand>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	138 <thead> <row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	139 <entry> Attribute </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	140 <entry> NOR </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	141 <entry> NAND </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	142 </row> </thead>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	143 <tbody>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	144 <row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	145 <entry>Addressing of data</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	146 <entry>By byte address within the device. Usually expressed as
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	147 memory-mapped addresses.</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	148 <entry>By row (page) number. Pages are a power of two; commonly 512 or
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	149 2048 bytes. Optimised for reading and writing a page at a time. Sometimes
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	150 supports column (byte) addressing, but this library does not expose
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	151 such functionality.</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	152 </row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	153 <row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	154 <entry>Are direct reads and writes possible? <footnote><para>In
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	155 other words, can the application read flash directly as if it
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	156 was RAM, or does it have to invoke the driver to copy data in and
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	157 out?</para></footnote></entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	158 <entry>Usually</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	159 <entry>Not in general, though a few special-case exceptions exist such
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	160 as OneNAND devices.</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	161 </row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	162 <row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	163 <entry>Erase block size</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	164 <entry>May vary across the chip</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	165 <entry>A fixed number of pages, typically 64</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	166 </row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	167 <row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	168 <entry>Out-of-band data </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	169 <entry>Not supported </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	170 <entry>A small number of bytes per page - typically 16 "spare" per 512
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	171 "data" bytes - are usable by the application. They are read, written
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	172 and erased at the same time as the "real" page data. </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	173 </row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	174 <row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	175 <entry>May factory-bad regions <footnote><para>Regions which were found
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	176 during manufacture to be bad and marked in some way - usually by placing
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	177 a special code in the Out Of Band area.</para></footnote> exist on the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	178 chip?</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	179 <entry>No </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	180 <entry>Typically up to 20 eraseblocks are marked as factory-bad in
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	181 their OOB area. The OS is expected to scan these to create a Bad Block
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	182 Table. <footnote><para>Once a BBT exists it can then be used to keep
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	183 track of any blocks which fail through wear during the lifetime of the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	184 device.</para></footnote></entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	185 </row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	186 <row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	187 <entry>May data be rewritten without being erased first?</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	188 <entry>Usually (but only by resetting 1-bits to 0) </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	189 <entry>Usually, on SLC NAND chips; not on MLC chips.</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	190 </row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	191 <row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	192 <entry>Error detection and correction</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	193 <entry>Not present</entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	194 <entry>Usually automatic. Typically this involves an Error Correcting
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	195 Code, automatically calculated and stored in the OOB area, then checked
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	196 on read.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	197 </entry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	198 </row>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	199 </tbody>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	200 </tgroup>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	201 </informaltable>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	202
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	203 <para> Since a NAND chip can in general only be read indirectly, its
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	204 contents must be copied to RAM before they can be executed. This means
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	205 that the caveats in the eCos FLASH library about disabling interrupts
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	206 whilst programming do not apply here, except in special cases such as
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	207 OneNAND devices.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	208 </sect1>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	209
2938 931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	210 <sect1 id="nand-deployment-notes"><title>Preparing for deployment</title>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	211 <para>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	212 It is generally not recommended to hard-code physical on-NAND locations
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	213 in case of factory bad blocks or block failures in the field.
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	214 <footnote><para>Usually the first block is guaranteed to be defect free
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	215 for a certain number of erase cycles. This tends to be necessary if
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	216 bootstrapping the CPU off NAND, and is an obvious exception to this
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	217 rule.</para></footnote> Instead it is preferable to set up
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	218 <emphasis>partitions</emphasis> on the chip with a generous safety
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	219 margin and to store data in a location-independent way. This is
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	220 commonly achieved by placing logical tags in the spare area of each
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	221 page, or using a log-structured filesystem such as YAFFS. Such
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	222 strategies remove the dependence on physical addressing, at the cost of
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	223 increased complexity.</para>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	224
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	225 <para>The upshot of this is that you cannot reliably create a simple
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	226 binary image to bulk-program in the factory. A more complicated
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	227 programming operation is required to take account of your chip
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	228 partitions, logical addressing strategy and any bad blocks which
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	229 may be encountered during write.
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	230 </para>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	231 </sect1>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	232
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	233 </chapter>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	234
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	235 <chapter id="nand-using">
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	236 <title>Using the NAND library</title>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	237
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	238 <para>The eCos NAND library exposes two principal APIs: one for
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	239 applications to use and the other to communicate with
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	240 device drivers.</para>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	241
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	242 <sect1 id="nand-app-config"><title>Configuring the NAND library</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	243 <para>The following configuration options are provided. They affect the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	244 library globally, i.e. across all drivers.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	245
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	246 <variablelist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	247 <varlistentry><term><constant>CYGPKG_IO_NAND_CFLAGS_ADD</constant></term>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	248 <term><constant>CYGPKG_IO_NAND_CFLAGS_REMOVE</constant></term>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	249 <listitem><para> Allows specific build options to be added to or
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	250 removed from the CFLAGS list when building this library.</para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	251 <varlistentry><term><constant>CYGSEM_IO_NAND_DEBUG</constant></term>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	252 <listitem><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	253 This is the master switch for all debug reporting from the library.</para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	254 <varlistentry><term><constant>CYGSEM_IO_NAND_DEBUG_FN_DEFAULT</constant></term>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	255 <listitem><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	256 This is the default function that the library will use when sending
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	257 debugging output. It must behave like <function>printf</function>.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	258 The default - <function>cyg_nand_defaultprintf</function>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	259 - is a wrapper to <function>diag_printf</function>.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	260 <note><para>Individual drivers may override this setting in their
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	261 <function>devinit</function> routines by overwriting the pointer in
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	262 the device struct.</para></note></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	263 <varlistentry><term><constant>CYGSEM_IO_NAND_DEBUG_LEVEL</constant></term>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	264 <listitem><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	265 Specifies the verbosity of the NAND library and device drivers.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	266 Ranges from 0 (off) to 9 (incredibly verbose); the default setting is 1.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	267 (Higher values are only likely to be of use during driver development,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	268 if ever.)
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	269 When enabled, messages are printed using the per-device printf-like
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	270 function (see above).</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	271 <note><para>Should a serious problem be encountered it will always
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	272 be reported the printf-like function, regardless of this
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	273 setting. Such messages may be suppressed altogether by turning
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	274 off <constant>CYGSEM_IO_NAND_DEBUG</constant>.</para></note></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	275 <varlistentry><term><constant>CYGSEM_IO_NAND_READONLY</constant></term>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	276 <listitem><para>Globally disables all code which writes to NAND devices.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	277 This may be useful during driver development.</para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	278 <varlistentry><term><constant>CYGNUM_NAND_MAX_PARTITIONS</constant></term>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	279 <listitem><para>Sets a compile-time limit on the number of partitions
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	280 any NAND device may have. The default is 4, which should be enough for
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	281 most purposes; unnecessarily setting this higher wastes RAM.</para></listitem></varlistentry>
2951 0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	282 <varlistentry><term><constant>CYGSEM_IO_NAND_USE_BBT</constant></term>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	283 <listitem><para>Globally enables and disables the use of Bad Block Table.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	284 <warning><para>This setting should not be disabled lightly!
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	285 It is strongly recommended that you leave this setting enabled unless
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	286 you have a very good reason to not use it. It is provided really as a
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	287 convenience for allowing developers to recover their NAND from a
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	288 confused state. </para></warning>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	289 </para></listitem></varlistentry>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	290 </variablelist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	291 </sect1>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	292
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	293 <sect1 id="nand-using-app-api"><title>The NAND Application API</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	294 <para>All of the functions described here are declared in the header file
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	295 <filename><cyg/nand/nand.h></filename>, which should be included
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	296 by all users of the NAND library.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	297
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	298 <note><para> Most of the functions in the library are declared
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	299 as returning <type>int</type>. <emphasis>Unless otherwise stated,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	300 all functions return 0 for success, or a negative eCos error code if
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	301 something went wrong.</emphasis></para></note>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	302
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	303 <sect2 id="nand-app-lookup"><title>Device initialisation and lookup</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	304 <para>NAND devices are identified to the library by name. In many cases
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	305 there will be only one, commonly named <emphasis>onboard</emphasis>,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	306 but this flexibility allows for easy expansion later without cross-device
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	307 confusion.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	308 <note><para>The naming of NAND devices is set up by the code that
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	309 instantiates their drivers. Normally this is done by the platform HAL
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	310 port.</para></note>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	311
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	312 <programlisting> __externC int cyg_nand_lookup(const char devname, cyg_nand_device *dev_o);</programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	313 <para>On success, *dev_o will be set up to point to a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	314 <type>cyg_nand_device</type> struct. On failure, it will not; a return
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	315 code of <constant>-ENOENT</constant> signifies that the requested device
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	316 name was not found.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	317
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	318 <para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	319 Applications will hardly, if ever, need to access the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	320 <type>cyg_nand_device</type> structs directly. The following members
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	321 and convenience macros are most likely to be of relevance:
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	322 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	323 struct _cyg_nand_device_t {
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	324 ...
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	325 cyg_nand_printf pf; // Diagnostic printf-like function for this device to use. May be changed at runtime.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	326 ...
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	327 size_t page_bits; // log2 of no of regular bytes per page
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	328 size_t spare_per_page; // OOB area size in bytes
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	329 size_t block_page_bits; // log2 of no of pages per eraseblock
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	330 size_t blockcount_bits; // log2 of number of blocks
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	331 size_t chipsize_log; // log2 of total chip size in BYTES.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	332 ...
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	333 };
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	334
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	335 #define CYG_NAND_BYTES_PER_PAGE(dev) (1<<(dev)->page_bits)
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	336 #define CYG_NAND_SPARE_PER_PAGE(dev) ((dev)->spare_per_page)
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	337 #define CYG_NAND_PAGES_PER_BLOCK(dev) (1<<(dev)->block_page_bits)
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	338 #define CYG_NAND_BLOCKCOUNT(dev) (1<<(dev)->blockcount_bits)
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	339 #define CYG_NAND_PAGECOUNT(dev) (NAND_BLOCKCOUNT(dev) * NAND_PAGES_PER_BLOCK(dev))
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	340 #define CYG_NAND_CHIPSIZE(dev) (1<<(dev)->chipsize_log)
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	341 #define CYG_NAND_APPSPARE_PER_PAGE(dev) ((dev)->oob->app_size)
3395 707de7f35fc7 io/nand: Minor doc updates Ross Younger <wry@ecoscentric.com> parents: 3017 diff changeset	342 #define CYG_NAND_BYTES_PER_BLOCK(dev) (1<<( (dev)->block_page_bits + (dev)->page_bits ))
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	343
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	344 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	345 </para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	346 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	347
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	348 <sect2 id="nand-app-addressing"><title>NAND device addressing</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	349 <para>NAND devices are arranged as a series of <emphasis>pages</emphasis>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	350 and <emphasis>eraseblocks</emphasis>. The eCos NAND library numbers
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	351 pages and eraseblocks sequentially, both starting at 0 and continuing
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	352 until the end of the chip. For example, eraseblock 0 might contain pages
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	353 0 through 63; eraseblock 1, pages 64 through 127; and so on.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	354 <caution><para>This numbering scheme is independent of the device's
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	355 addressing scheme. Take care, particularly when erasing blocks; some
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	356 devices and some applications effectively express the location to erase as
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	357 a page number (or, in NAND-speak, as the <emphasis>row address</emphasis>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	358 to erase from).</para></caution>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	359
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	360 <warning><para>Most NAND chip manufacturers document restrictions on
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	361 the order in which pages may be written to their device. Typically,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	362 individual pages within an eraseblock must be written in sequential
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	363 order starting from the first, and random-order writes are prohibited
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	364 or unspecified. The eCos NAND library does not attempt to police such
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	365 restrictions; if at all unsure, check the spec sheet for the part. You
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	366 have been warned! </para></warning>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	367
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	368 <para>NAND devices are widely considered to be arranged as one or
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	369 more <emphasis>partitions</emphasis>, and the eCos NAND library
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	370 supports this. However, there is no universal scheme for partition
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	371 sizes to be supplied to the driver, unlike hard drives which encode
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	372 a partition table into their first sector. Partition arrangements are
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	373 often implicitly hardcoded, such as by byte address within the device,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	374 though they could be encoded in a "partition table", user-set, or even
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	375 variable under software control by some esoteric rules. Therefore, every
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	376 device driver is responsible for configuring its partition information
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	377 as appropriate for the device, and this might for example appear as CDL
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	378 options.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	379 <tip><para>Be sure to read the notes associated with the device driver
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	380 to understand how partitions are set up; if no notes are provided,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	381 look in its <function>devinit</function> code.</para></tip>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	382
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	383 <sect3 id="nand-app-partitions"><title>NAND device partitions</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	384 <para>After a NAND device has been initialised, its device struct contains
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	385 a list of partitions. These are numbered from 0 and may go up to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	386 <constant>CYGNUM_NAND_MAX_PARTITIONS</constant>-1. Before an
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	387 application can use the NAND device, it must obtain a partition
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	388 context (pointer) with the following call:
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	389 <programlisting>__externC cyg_nand_partition* cyg_nand_get_partition(cyg_nand_device *dev, unsigned partno);</programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	390 </para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	391
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	392 <note><para>This call returns a pointer to the partition struct, not
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	393 an error code. If the given partition number is inactive or invalid,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	394 it returns NULL.</para></note>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	395 </sect3>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	396
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	397 <sect3 id="nand-app-addressing-spare"><title>About the spare area</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	398 <para>Every page on the NAND array has a small number of "spare" bytes
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	399 associated with it. These are used by the NAND library to store the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	400 page's ECC; whatever is left over may be used by the application for
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	401 whatever purposes may suit it.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	402
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	403 <para>Every page has <function>CYG_NAND_APPSPARE_PER_PAGE(dev)</function>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	404 bytes of spare area available to the application. (This amount is implicit
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	405 from the driver configuration and cannot change during the lifetime of
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	406 a device.) </para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	407
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	408 <note><para>Application spare bytes are not subject to the ECC. When
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	409 reading the spare area data, you must be prepared to cope with the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	410 consequences of the (unlikely) event of a bit drop-out or other
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	411 failure.</para></note> </sect3>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	412
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	413 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	414
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	415 <sect2 id="nand-app-manipulating"><title>Manipulating the NAND array</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	416 <para>Now, finally, given a <type>cyg_nand_partition*</type>,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	417 your application can make use of the NAND array with the following
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	418 functions:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	419
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	420 <sect3 id="nand-app-read"><title>Reading data</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	421 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	422 __externC int cyg_nand_read_page(cyg_nand_partition ctx, cyg_nand_page_addr page, void dest, size_t size, void * spare, size_t spare_size);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	423 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	424
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	425 <blockquote>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	426 <para>Reads a single page and its spare area. The data read from the chip
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	427 will be automatically ECC-checked and repaired if necessary. Parameters
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	428 are as follows:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	429
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	430 <glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	431 <glossentry><glossterm><parameter>ctx</parameter></glossterm><glossdef><para>The
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	432 partition that data is to be read from.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	433 <glossentry><glossterm><parameter>page</parameter></glossterm><glossdef><para>
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	434 The page to be read, <emphasis>numbered from the start of the partition.
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	435 </emphasis>. As a double-check, the library will refuse the
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	436 operation with <constant>-ENOENT</constant> if this address is not within
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	437 partition <parameter>ctx</parameter>.
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	438 <note><para>This was changed in application interface v2; earlier page
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	439 and block addresses were device-relative.</para></note>
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	440 </para></glossdef></glossentry>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	441 <glossentry><glossterm><parameter>dest</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	442 Where to put the data. May be NULL, in which case the page data is not
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	443 read.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	444 <glossentry><glossterm><parameter>size</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	445 The maximum amount of data to read. (In any event, no more than a single
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	446 page will be read, but if your application knows it doesn't need the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	447 whole page, you can place a cap here.) </para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	448 <glossentry><glossterm><parameter>spare</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	449 Where to store the application data read from the spare area. This may
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	450 be NULL if spare data is not required.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	451 <glossentry><glossterm><parameter>spare_size</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	452 The maximum number of bytes to read from the spare area. This will
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	453 not be more than <function>CYG_NAND_APPSPARE_PER_PAGE(dev)</function>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	454 bytes.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	455 </glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	456
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	457 <para>An error response of <constant>-EIO</constant> means that a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	458 multiple-bit I/O error has occurred in the page data, which the ECC
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	459 could not repair. The library stores the data read from the device in
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	460 <parameter>dest</parameter> and <parameter>spare</parameter> on a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	461 best-effort basis; it should not be relied upon. The application should
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	462 take steps to salvage what it can and erase the block as soon as possible.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	463
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	464 </blockquote>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	465 </sect3>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	466
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	467 <sect3 id="nand-app-writing"><title>Writing data</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	468 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	469 __externC int cyg_nand_write_page(cyg_nand_partition ctx, cyg_nand_page_addr page, const void src, size_t size, const void * spare, size_t spare_size);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	470 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	471
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	472 <blockquote>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	473 <para>Writes a single page and its spare area. The ECC will be computed
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	474 and stored automatically. Parameters are as follows:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	475
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	476 <glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	477 <glossentry><glossterm><parameter>ctx</parameter></glossterm><glossdef><para>The
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	478 partition that data is to be written to.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	479 <glossentry><glossterm><parameter>page</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	480 The page to be written, <emphasis>numbered from the start of
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	481 the partition</emphasis>. As a double-check, the
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	482 library will refuse the operation with <constant>-ENOENT</constant>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	483 if this address is not within partition <parameter>ctx</parameter>.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	484 </para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	485 <glossentry><glossterm><parameter>src</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	486 Where to read the data from. May be NULL, in which case the page data
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	487 is not written.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	488 <glossentry><glossterm><parameter>size</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	489 The amount of data to write. (In any event, no more than a single page
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	490 will be written.)</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	491 <glossentry><glossterm><parameter>spare</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	492 Where to read the data to go into the spare area; it will automatically
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	493 be packed around the ECC as necessary. Again, this may be NULL if spare
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	494 data is not required.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	495 <glossentry><glossterm><parameter>spare_size</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	496 The number of bytes to write to the spare area. This should not be
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	497 larger than <function>CYG_NAND_APPSPARE_PER_PAGE(dev)</function>; if it is,
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	498 only that many bytes will be stored.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	499 </glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	500
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	501 <para> An error response of <constant>-EIO</constant> means that
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	502 the page write failed. The application should copy out any data
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	503 it wishes to keep from the rest of the eraseblock, then call
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	504 <function>cyg_nand_bbt_markbad()</function> to put the block beyond use.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	505 </blockquote></sect3>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	506
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	507 <sect3 id="nand-app-erasing"><title>Erasing blocks</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	508
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	509 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	510 __externC int cyg_nand_erase_block(cyg_nand_partition *ctx, cyg_nand_block_addr blk);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	511 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	512
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	513 <blockquote><glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	514 <glossentry><glossterm><parameter>ctx</parameter></glossterm><glossdef><para>The
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	515 partition that data is to be erased from.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	516 <glossentry><glossterm><parameter>blk</parameter></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	517 The block to be erased, <emphasis>numbered from the start of
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	518 the partition</emphasis>. As a double-check, the
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	519 library will refuse the operation with <constant>-ENOENT</constant>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	520 if this address is not within partition <parameter>ctx</parameter>.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	521 </para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	522 </glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	523
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	524 <para>An error response of <constant>-EIO</constant> means that the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	525 block erase failed. In this case, the library automatically marks the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	526 block as bad, and the application need take no further action.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	527
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	528 </blockquote>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	529 </sect3>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	530
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	531 <sect3 id="nand-app-manip-commonerrs"><title>Common error returns</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	532 <para> The following common error returns may be encountered when
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	533 manipulating the NAND array using the above functions:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	534
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	535 <glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	536 <glossentry><glossterm><constant>-EIO</constant></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	537 The operation could not be completed due to an I/O error. This may require
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	538 the application to take further action; check the details provided above
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	539 for the call you have just made.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	540 <glossentry><glossterm><constant>-ENOENT</constant></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	541 The page or block address was not valid for the given
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	542 partition.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	543 <glossentry><glossterm><constant>-EINVAL</constant></glossterm><glossdef><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	544 The page (block) address was (within) a block that is marked
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	545 bad.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	546 </glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	547 </sect3>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	548 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	549
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	550 <sect2 id="nand-app-ancillary"><title>Ancillary NAND functions</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	551 <para>The following functions are provided to allow applications to interact
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	552 with the Bad Block Table:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	553
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	554 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	555 typedef enum {
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	556 CYG_NAND_BBT_OK=0,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	557 CYG_NAND_BBT_WORNBAD=1,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	558 CYG_NAND_BBT_RESERVED=2,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	559 CYG_NAND_BBT_FACTORY_BAD=3
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	560 } cyg_nand_bbt_status_t;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	561
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	562 __externC int cyg_nand_bbt_query(cyg_nand_partition *ctx, cyg_nand_block_addr blk);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	563
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	564 __externC int cyg_nand_bbt_markbad(cyg_nand_partition *ctx, cyg_nand_block_addr blk);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	565 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	566
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	567 <para>To determine the status of an eraseblock, use
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	568 <function>cyg_nand_bbt_query</function>; this returns an enum from
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	569 <type>cyg_nand_bbt_status_t</type> or a negative eCos error code. All
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	570 blocks which return a non-0 enum value are considered inaccessible by
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	571 applications.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	572
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	573 <para>Occasionally, it is necessary for applications to mark a block
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	574 as bad. This most commonly happens when a write operation fails
2942 b7de7e438610 * Fixed more "jade" syntax issues alexs parents: 2940 diff changeset	575 (see <xref linkend="nand-app-writing"> above). To do this, call
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	576 <function>cyg_nand_bbt_markbad</function>; the return is 0 for success,
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	577 or a negative eCos error code. <emphasis>As with other calls, blocks
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	578 are numbered from 0 at the start of the partition, and internally
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	579 translated for the device as appropriate.</emphasis></para>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	580
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	581 <para>Both of these calls may foreseeably return
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	582 <constant>-ENOENT</constant> if the given block address was not valid,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	583 or <constant>-EIO</constant> if something awful happened with the on-chip
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	584 bad block table.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	585 </para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	586 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	587 </sect1>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	588
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	589 </chapter>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	590
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	591 <chapter id="nand-devs-writing">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	592 <title>Writing NAND device drivers</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	593 <sect1 id="nand-devs-planning"><title>Planning a port</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	594
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	595 <para> Before you start, you will need to have sight of appropriate spec
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	596 sheets for both the NAND chip and the board into which it is connected,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	597 and you need to know how the chip is to be partitioned.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	598
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	599 <sect2 id="nand-devs-structure"><title>Driver structure and layout</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	600 <para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	601 A typical NAND device driver falls into two parts:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	602 <itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	603 <listitem><para>high-level operations specific to the NAND chip (page
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	604 reads and writes); and
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	605 </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	606 <listitem><para>board-specific plumbing (sending commands and data to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	607 the chip; reading data back from the chip).
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	608 </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	609 </itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	610
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	611 <para> This distinction is important in the interests of code reuse;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	612 the same part may appear on different boards, or indeed multiple times,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	613 but connected differently. It need not be maintained if there are good
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	614 reasons not to.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	615
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	616 <para> The <emphasis>NAND library device interface</emphasis> consists
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	617 of a C struct, <type>cyg_nand_device</type>, comprising a number of
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	618 data fields and function pointers. Each NAND chip to be made available
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	619 to the library requires exactly one instance of this struct.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	620
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	621 <tip><para>The <type>cyg_nand_device</type> structure includes a
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	622 <structfield>void* priv</structfield> member which is treated
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	623 as opaque. The driver may use this member as it sees fit; it is
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	624 intended to provide an easy means to identify the NAND array, MMIO
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	625 addresses or function pointers to use and so on. Typically this is
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	626 used by the chip driver for its own purposes, and includes a further
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	627 opaque member for the use of the HAL port.
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	628 </para></tip>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	629
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	630 <para>The function pointers in the struct form the driver's high-level
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	631 functions; they make use of the low-level functions to talk to the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	632 chip. We present the high-level functions first, although there is no
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	633 intrinsic reason to prefer either ordering during driver development.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	634
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	635 <para> The high-level chip-specific functions
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	636 are traditionally laid out as an <emphasis>inline
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	637 file</emphasis> in an appropriate package in <filename
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	638 class=directory>devs/nand/<replaceable>CHIP</replaceable></filename>.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	639 The board-specific functions should normally appear in the platform HAL
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	640 and #include the inline.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	641 </para></sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	642
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	643 <sect2 id="nand-devs-partitions"><title>Chip partitions</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	644 <para>Before embarking on the port, you should determine how the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	645 NAND array will be partitioned. This is necessarily a board-specific
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	646 question, and your layout must accommodate any other software users of
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	647 the array. You will need to know either the fixed layout - converted to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	648 eraseblock addresses - or how to determine the layout at initialisation
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	649 time.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	650
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	651 <tip><para>It may be worthwhile to set up partitioning by way of some
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	652 parameters in your platform's CDL, with sensible defaults, instead of
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	653 outright hard-coding the partition layout.</para></tip>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	654
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	655 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	656 <sect2 id="nand-devs-locking"><title>Locking against concurrent access</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	657 <para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	658 The eCos NAND library provides per-device locking, to guard against
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	659 concurrent access during high-level operations. This support is fully
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	660 automatic; drivers need take no action to make use of it.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	661
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	662 <para> This strategy may not be sufficient on all target boards:
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	663 sometimes, accessing a NAND chip requires mediation by CPLD or other
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	664 device, which must be shared with other NAND chips or even other
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	665 peripherals. <emphasis>If this applies, it is the responsibility
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	666 of the driver and platform port to provide further locking as
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	667 appropriate!</emphasis></para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	668
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	669 <tip><para>When using mutexes in a driver, one should
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	670 use the <emphasis>driver API</emphasis> as defined in
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	671 <filename><cyg/hal/drv_api.h></filename> instead of the full kernel
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	672 API. This has the useful property that mutex operations are very cheaply
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	673 implemented when the eCos kernel is not present, such as when operating
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	674 in RedBoot. </para></tip>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	675 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	676
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	677 <sect2 id="nand-devs-cdl">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	678 <title>Required CDL declarations</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	679
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	680 <para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	681 An individual NAND chip driver must declare the largest page
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	682 size it supports by means of CDL. This is done with a statement like
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	683 the following in its cdl_package stanza:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	684
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	685 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	686 requires ( CYGNUM_NAND_PAGEBUFFER >= 2048 )
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	687 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	688
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	689 <note><para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	690 This requirement is due to the internal workings of the eCos NAND
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	691 library: a buffer is required for certain operations which
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	692 manipulate up to a NAND page worth of data, internally to the library.
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	693 This is declared once as a global buffer for safety under low-memory
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	694 conditions; a page may be too big to use temporary storage on the C stack,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	695 and the NAND library deliberately avoids the use of
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	696 <function>malloc</function>.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	697 </note>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	698
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	699 <para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	700 By convention, a driver package would declare
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	701 <constant>CYGPKG_IO_NAND</constant> as its <constant>parent</constant> and use
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	702 <filename>cyg/devs/nand</filename> as its <constant>include_dir</constant>,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	703 but there is no intrinsic reason why this should be so.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	704 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	705 </sect1>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	706
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	707 <sect1 id="nand-devs-highlevel">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	708 <title>High-level (chip) functions</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	709 <para> The high-level functions provided by the chip driver are
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	710 typically created as an <emphasis>inline file</emphasis> providing a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	711 fully-populated <type>cyg_nand_dev_fns_v1</type> struct, instantiated
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	712 by the <type>CYG_NAND_FUNS</type> macro. The high-level driver should
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	713 not directly read or write to the hardware itself, but instead call into
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	714 functions in the low-level driver.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	715
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	716 <para> The form the low-level functions should take is not prescribed;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	717 typically functions will be required to write commands to the device, to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	718 read and write data, and to query any status line which may be present.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	719 The high-level driver should normally provide a header file containing
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	720 prototypes for the functions it requires from the low-level driver.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	721 (The low-level source file would provide the low-level functions required,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	722 include the high-level include, then instantiate the combined driver
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	723 using the <type>CYG_NAND_DEVICE</type> macro.)</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	724
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	725 <para> This source code layout is not intended as a prescription. It
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	726 would for example be entirely in order to store pointers to the low-level
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	727 functions in a struct and set <structfield>priv</structfield> to point
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	728 to that struct, which could be useful in some cases.</para>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	729
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	730 <note><para>The device driver must not call <function>malloc</function>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	731 or otherwise allocate memory; all data should be in the stack or set
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	732 as globals. This is because the driver may be required to run within a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	733 minimal eCos configuration.</para></note>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	734
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	735 <para> These functions should all return 0 on success, or a negative
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	736 eCos error code. In the event of an error, do <emphasis>not</emphasis>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	737 call back into the NAND library; use the <type>NAND_CHATTER</type>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	738 macro to report, in case a human is watching, and return an error
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	739 code. The library will take care of ensuring the correct response to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	740 the application and updating the BBT as necessary.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	741
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	742 <sect2 id="nand-devs-devinit">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	743 <title>Device initialisation</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	744 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	745 static int my_devinit (cyg_nand_device *dev);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	746 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	747
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	748 <para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	749 The <function>devinit</function> function is the most complex, and
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	750 logically one to write first. It is responsible for:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	751 <itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	752 <listitem><para>initialising the device, typically by sending a reset
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	753 command;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	754 </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	755 <listitem><para>interrogating the device to confirm its presence and
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	756 properties;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	757 </para></listitem>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	758 <listitem><para>setting up the partition table list (see
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	759 "Planning a port" above);
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	760 </para></listitem>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	761 <listitem><para>setting up mutexes as necessary (see
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	762 "Locking against concurrent access" above);
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	763 </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	764 <listitem><para>populating the other members of the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	765 <type>cyg_nand_device</type> struct (see below).
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	766 </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	767 </itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	768
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	769 <para> Interrogating the device is normally performed by sending a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	770 <emphasis>Read ID</emphasis> command and examining the result, which
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	771 typically encodes some or all of the chip parameters.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	772
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	773 <para> Given the similarity between many NAND parts, it may be possible
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	774 to write a generic driver to cover all of one or more manufacturer's
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	775 parts, or indeed for all ONFI-compliant parts. At the time of writing,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	776 this has not yet been attempted.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	777
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	778 <variablelist><title>The <function>devinit</function> function must set
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	779 up the following struct members:</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	780 <varlistentry><term><structfield>page_bits</structfield></term><listitem><para>The
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	781 size of the regular (non-spare) part of a page, expressed as the logarithm
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	782 in base 2 of the number of bytes. For example, if pages are 2048 bytes
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	783 long, <structfield>page_bits</structfield> would be 11. Obviously,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	784 the size of a page must be an exact power of two.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	785 </para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	786 <varlistentry><term><structfield>spare_per_page</structfield></term><listitem><para>The
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	787 number of bytes of spare area available in each
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	788 page.</para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	789 <varlistentry><term><structfield>block_page_bits</structfield></term><listitem><para>The
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	790 base-2 log of the number of pages per
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	791 eraseblock.</para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	792 <varlistentry><term><structfield>blockcount_bits</structfield></term><listitem><para>The
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	793 total number of erase blocks in the device, expressed as a base-2
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	794 log. </para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	795 <varlistentry><term><structfield>chipsize_log</structfield></term><listitem><para>The
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	796 total size of the chip, not counting the spare areas. This is required so
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	797 that the library can double-check that the given parameters make sense
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	798 by comparing with the preceding fields. Again, this field is itself a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	799 base-2 logarithm.</para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	800 <varlistentry><term><structfield>bbt.data</structfield></term><listitem><para>Space
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	801 for the in-memory Bad Block Table for this device.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	802 </para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	803 <varlistentry><term><structfield>bbt.datasize</structfield></term><listitem><para>This
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	804 is the size of <structfield>bbt.data</structfield>, in bytes. At present,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	805 this should be two bits times the number of blocks in the device; in
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	806 other words, <varname>1<<(blockcount_bits-2)</varname> bytes.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	807 </para></listitem></varlistentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	808 </variablelist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	809
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	810 <para>The <type>cyg_nand_device</type> struct has two further members
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	811 <structfield>ecc</structfield> and <structfield>oob</structfield>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	812 which must be set up to point to the ECC and OOB descriptors to use for
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	813 the device. This is normally done by the <type>CYG_NAND_DEVICE</type>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	814 low-level instantiation macro, so will be better described in that
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	815 section, but at this level you should be aware that it is also safe
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	816 to set up the descriptor block during <function>devinit</function>.
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	817 for example if multiple semantics might be you had included logic to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	818 detect what semantics to use.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	819
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	820 <para> The Bad Block Table itself is implemented in a way which intends
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	821 to be compatible with the Linux MTD layer. A full parameter struct is
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	822 not currently provided, though one may be in future.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	823 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	824
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	825 <sect2 id="nand-devs-readwrite">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	826 <title>Reading, writing and erasing data</title>
2961 3e4bd6789be2 * Added missing closing tags alexs parents: 2951 diff changeset	827 <para>The read and write operations are divided into three phases, with the following flow:</para>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	828 <itemizedlist>
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	829 <listitem><para>Begin. This is called once; the driver should lock any
2961 3e4bd6789be2 * Added missing closing tags alexs parents: 2951 diff changeset	830 platform-level mutex and send the command and address.</para></listitem>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	831 <listitem><para>Stride. This is called one or more times to read the page
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	832 data from the device. <note><para>The reason for this is if the platform
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	833 provides a NAND controller with hardware ECC: it is often necessary to
2961 3e4bd6789be2 * Added missing closing tags alexs parents: 2951 diff changeset	834 read out the ECC registers every so often.</para></note></para></listitem>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	835 <listitem><para>Finish. This is called once; it should read or write
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	836 the spare area, (on programming) send a "program confirm" command and
2961 3e4bd6789be2 * Added missing closing tags alexs parents: 2951 diff changeset	837 check its status, and unlock any platform-level mutex.</para></listitem>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	838 </itemizedlist>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	839
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	840 <para>Erasing is a single-shot call which should lock any
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	841 platform-specific mutex, send the command, check its status and unlock
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	842 the mutex.</para>
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	843
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	844 <programlisting>
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	845 static int my_read_begin(cyg_nand_device *dev, cyg_nand_page_addr page);
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	846 static int my_read_stride(cyg_nand_device dev, void dest, size_t size);
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	847 static int my_read_finish(cyg_nand_device dev, void spare, size_t spare_size);
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	848
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	849 static int my_write_begin(cyg_nand_device *dev, cyg_nand_page_addr page);
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	850 static int my_write_stride(cyg_nand_device dev, const void src, size_t size);
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	851 static int my_write_finish(cyg_nand_device dev, const void spare, size_t spare_size);
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	852
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	853 static int my_erase_block(cyg_nand_device *dev, cyg_nand_block_addr blk);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	854 </programlisting>
2961 3e4bd6789be2 * Added missing closing tags alexs parents: 2951 diff changeset	855 </sect2>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	856
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	857 <sect2 id="nand-devs-isfactorybad">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	858 <title>Searching for factory-bad blocks</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	859 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	860 static int my_is_factory_bad(cyg_nand_device *dev, cyg_nand_block_addr blk);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	861 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	862
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	863 <para> The very first time a NAND chip is used, the library has to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	864 scan it to check for factory-bad eraseblocks and build up the Bad Block
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	865 Table. This function is called repeatedly to do so, one block at a time;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	866 it should return 1 if the block is marked bad, or 0 if the block appears
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	867 to be OK.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	868
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	869 <para>Typically this function will invoke <function>read_page</function>;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	870 blocks are usually marked factory-bad by the presence of a particular
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	871 signature in the out-of-band area of the first or second page of that
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	872 block.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	873
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	874 <warning><para> It is extremely important that you get this function
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	875 right; after an eraseblock has been written to, it is no longer possible
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	876 to reliably determine whether the block was factory-bad. It is never
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	877 safe to assume that the factory-bad signature for a chip is the same
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	878 as that of a similarly-sized chip or another by the same manufacturer;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	879 <emphasis>always</emphasis> check the correct spec sheet for the actual
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	880 part or part-family in use! </para></warning>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	881
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	882 <tip><para> Because this function is critical and a subtle error could
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	883 cripple your application some time later in the field when it runs
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	884 across undetected factory-bad blocks, you might find it handy to have
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	885 a double-check before proceeding. If you enable CYGSEM_IO_NAND_READONLY
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	886 in your eCos configuration during early development, you can safely fire
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	887 up a test application (which calls <function>cyg_nand_lookup</function>)
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	888 whilst watching the chatter output: the scan will be performed, but no BBT
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	889 will be written. You can then compare the number of bad blocks reported
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	890 against the manufacturer's specification of the maximum. Double-check
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	891 that your <function>is_factory_bad</function> function is correct before
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	892 enabling read-write mode! </para></tip>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	893 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	894
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	895 <sect2 id="nand-devs-declaring-fun-set">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	896 <title>Declaring the function set</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	897 <programlisting>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	898 CYG_NAND_FUNS_V2(mydev_funs, my_devinit,
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	899 my_read_begin, my_read_stride, my_read_finish,
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	900 my_write_begin, my_write_stride, my_write_finish,
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	901 my_erase_block, my_is_factory_bad);
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	902 </programlisting>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	903
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	904 <para> This macro ties the above functions together into a struct whose
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	905 name is given as its first argument. The name of the resulting struct
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	906 must be quoted when the driver is formally instantiated, which is normally
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	907 done by the low-level functions.</para>
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	908 <note><para>Earlier versions of this library used a slightly different
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	909 device interface, keyed off the macro CYG_NAND_FUNS. This interface has
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	910 been retired.</para></note>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	911 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	912 </sect1>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	913
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	914 <sect1 id="nand-devs-lowlevel">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	915 <title>Low-level (board) functions</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	916 <para> The set and prototypes of the functions required here will
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	917 necessarily depend on the board and to a lesser extent on the NAND part
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	918 itself. The following functionality is typically required:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	919
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	920 <itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	921 <listitem><para>Very low-level hardware initialisation - for example,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	922 GPIO pin direction and interrupt config - if this has not already been
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	923 done by the platform HAL</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	924 <listitem><para>Set up the chip partition table (see below) </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	925 <listitem><para>Runtime hardware config as required, such as commanding
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	926 an FPGA or CPLD to route lines to the NAND part </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	927 <listitem><para>Write a command (byte) </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	928 <listitem><para>Write an address (handful of bytes) </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	929 <listitem><para>Write data, usually at the chip's full bus width
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	930 (typically 8 or 16 bits) </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	931 <listitem><para>Read data at full bus width </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	932 <listitem><para>Read data at 8-bit width (if the chip has a 16 bit
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	933 data bus, some commands - commonly ReadID - may return 8-bit data)
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	934 </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	935 <listitem><para>Poll any status lines required or - if supported -
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	936 set them up as interrupts to allow sleeping-wait </para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	937 </itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	938
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	939 <sect2 id="nand-devs-accessing">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	940 <title>Talking to the chip</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	941 <para> It is impossible to prescribe how to achieve this, as it depends
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	942 entirely on how the NAND part is wired up on the board.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	943
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	944 <para> The ideal situation is that the NAND part is wired in via the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	945 CPU's memory controller and that the controller is set up to do most of
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	946 the hard work for you. In that case, reading and writing the device is
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	947 as simple as accessing the correct memory-mapped I/O address; usually
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	948 different address ranges connect to the device's command, address and
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	949 data registers respectively.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	950
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	951 <tip><para>The HAL provides a number of macros in
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	952 <filename><cyg/hal/hal_io.h></filename> to read and write
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	953 memory-mapped I/O. </para></tip>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	954
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	955 <note><para>On platforms with an MMU, MMIO may be rerouted to different
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	956 addresses to those on the board spec sheet. Check the MMU setup in the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	957 platform HAL.</para></note>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	958
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	959 <para> On some platforms, you may have to invoke an FPGA or CPLD to be
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	960 able to talk to the NAND chip. This might typically take the form of a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	961 handful of MMIO accesses, but should hopefully be fairly straightforward
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	962 once you've figured out how the components interrelate.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	963
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	964 <para> The worst case is where you have no support from any sort of
2944 32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	965 controller hardware and have to bit-bang GPIO lines to talk to the chip.
32bcd454bda4 Major update to allow hardware ECC: change driver interface (to "v2" - with CDL marker), expand ECC interface wry parents: 2942 diff changeset	966 This is a much more involved process; you have to take great care to get the
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	967 timings right with carefully tuned delays. The result is usually
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	968 quite CPU intensive, and could be clock speed sensitive too; you should
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	969 check for and take account of any CDL settings in the architecture and
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	970 variant HAL which allow the CPU clock frequency to be changed.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	971
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	972 <tip><para> If your low-level functions take a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	973 <type>cyg_nand_device</type> pointer as an argument, you can use its
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	974 <structfield>priv</structfield> member to hold or point to some relevant
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	975 data like the MMIO addresses to use, which is preferable to hard-coding
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	976 them. Indeed, if you wish your board port to support more than one chip,
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	977 you should use the <structfield>priv</structfield> member to distinguish
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	978 between them.
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	979 </para></tip>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	980 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	981
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	982 <sect2 id="nand-devs-partition">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	983 <title>Setting up the chip partition table</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	984 <para> It is the responsibility of the high-level
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	985 <function>devinit</function> function to set up the device's partition
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	986 table. (It may be appropriate for it to invoke a low-level function to
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	987 do this.)</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	988
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	989 <para>The partition definition is an array of
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	990 <type>cyg_nand_partition</type> entries in the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	991 <type>cyg_nand_device</type>.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	992
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	993 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	994 struct _cyg_nand_partition_t {
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	995 cyg_nand_device *dev;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	996 cyg_nand_block_addr first;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	997 cyg_nand_block_addr last;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	998 };
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	999 typedef struct _cyg_nand_partition_t cyg_nand_partition;
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1000
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1001 struct _cyg_nand_device_t {
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1002 ...
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1003 cyg_nand_partition partition[CYGNUM_NAND_MAX_PARTITIONS];
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1004 ...
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1005 };
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1006 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1007
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1008 <para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1009 Application-visible partition numbers are simply indexes into this array.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1010
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1011 <itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1012 <listitem><para>On a live partition, <structfield>dev</structfield>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1013 must point back to the <type>cyg_nand_device</type> containing it. If
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1014 <constant>NULL</constant>, the partition is inactive.</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1015 <listitem><para><structfield>first</structfield> is the number of the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1016 first block of the partition.</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1017 <listitem><para><structfield>last</structfield> is the number of the last
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1018 block of the partition (<emphasis>not</emphasis> the number of blocks,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1019 unless the partition starts at block 0).</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1020 </itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1021 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1022
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1023 <sect2 id="nand-devs-lowlevel-putting-it-together">
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1024 <title>Putting it all together...</title>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1025 <para> Finally, with everything else in place, we turn to the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1026 CYG_NAND_DEVICE macro to instantiate it.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1027
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1028 <programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1029 CYG_NAND_DEVICE(my_nand, "onboard", &mydev_funs, &my_priv_struct, &linux_mtd_ecc, &nand_mtd_oob_64);
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1030 </programlisting>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1031
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1032 <para>In order, the arguments to this macro are:</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1033
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1034 <itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1035 <listitem><para>The name to give the resultant cyg_nand_device struct;</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1036 <listitem><para>the device identifier string, application-visible to be used in <function>cyg_nand_lookup()</function> ;</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1037 <listitem><para>a pointer to the device high-level function set to use,
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1038 normally set up by the CYG_NAND_FUNS macro;</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1039 <listitem><para>the <structfield>priv</structfield> member to include
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1040 in the struct;</para></listitem>
2951 0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1041 <listitem><para>a pointer to the ECC semantics block to use.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1042 <filename>linux_mtd_ecc</filename> provides software ECC compatible
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1043 with the Linux MTD layer, but it is strongly recommended to use
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1044 onboard hardware ecc support if this is present as it gives a huge
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1045 speed boost. See <xref linkend="nand-ecc"> for more details.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1046 </para></listitem>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1047 <listitem><para>a pointer to the OOB-area layout descriptor to use (see
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1048 <filename>nand_oob.h</filename> : nand_mtd_oob_16 and nand_mtd_oob_64
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1049 are Linux-compatible layouts for devices with 16 and 64 bytes of spare
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1050 area per page respectively).</para></listitem>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1051 </itemizedlist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1052
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1053 <para>The macro invokes the appropriate linker magic to pull all the
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1054 compiled NAND device structs into one section so the NAND library can
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1055 find them.</para>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1056
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1057 </sect2>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1058
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1059 </sect1>
2951 0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1060
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1061 <sect1 id="nand-ecc"><title>ECC implementation</title>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1062
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1063 <para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1064 The use of ECC is strongly recommended with NAND flash parts owing to their
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1065 tendency to occasionally bit-flip. This is usually done with a variant of
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1066 a Hamming code which calculates column and line parity.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1067 The computed ECC is stored in the spare area of the page to which it relates.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1068 </para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1069
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1070 <para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1071 The NAND library automatically computes and stores the ECC of data as it
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1072 is written to the chip. On read, the code is calculated for the data
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1073 actually read; this is compared with the stored code and the data
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1074 repaired if necessary.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1075 </para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1076
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1077 <para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1078 The NAND library comes with a software ECC implementation named
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1079 <filename>linux_mtd_ecc</filename>. This is compatible with the
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1080 ECC used in the Linux MTD layer, hence its name. It calculates
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1081 a 3-byte ECC on a 256-byte data block.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1082 This algorithm is adequate for most circumstances, but it is
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1083 strongly recommended to use any hardware ECC support which may
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1084 be available because of the performance gains it yields.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1085 (In testing, we observed that up to two thirds of the time
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1086 taken by every page read and program call was used in computing
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1087 ECC in software.)
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1088
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1089 </para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1090
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1091 <sect2 id="nand-ecc-interface"><title>The ECC interface</title>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1092 <para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1093 This library draws a semantic distinction between
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1094 <emphasis>hardware</emphasis> and
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1095 <emphasis>software</emphasis>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1096 ECC implementations.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1097 </para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1098
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1099 <itemizedlist>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1100 <listitem><para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1101 A software ECC implementation will typically not require an
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1102 initialisation step. The calculation function will always be
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1103 called with a pointer to the data bytes to compute.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1104 </para></listitem>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1105 <listitem><para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1106 A hardware implementation is assumed to read and act upon the data
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1107 <emphasis>as it goes past</emphasis>.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1108 Therefore, it will not be passed a pointer to the data
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1109 when its <filename>calculate</filename> step is invoked.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1110 </para></listitem>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1111 </itemizedlist>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1112
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1113 <para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1114 An ECC is defined by the following parameters:
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1115 <itemizedlist>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1116 <listitem><para>The size of data block it handles, in bytes.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1117 </para></listitem>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1118 <listitem><para>The size of ECC it calculates on those blocks, in bytes.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1119 </para></listitem>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1120 <listitem><para>Whether the algorithm is hardware or software.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1121 </para></listitem>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1122 </itemizedlist>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1123 </para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1124
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1125 <para>An ECC algorithm must provide the following functions:
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1126 </para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1127
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1128 <programlisting>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1129 /* Initialises an ECC computation. May be NULL if not required. */
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1130 void my_ecc_init(struct _cyg_nand_device_t *dev);
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1131
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1132
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1133 /* Returns the ECC for the given data block.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1134 * If IS_HARDWARE:
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1135 * - dat and nbytes are ignored
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1136 * If ! IS_HARDWARE:
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1137 * - dat and nbytes are required
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1138 * - if nbytes is less than the chunk size, the remainder are
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1139 * assumed to be 0xff.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1140 */
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1141 void my_ecc_calc(struct _cyg_nand_device_t *dev,
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1142 const CYG_BYTE dat, size_t nbytes, CYG_BYTE ecc);
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1143
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1144
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1145 /* Repairs the ECC for the given data block, if needed.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1146 * Call this if your read-from-chip ECC doesn't match what you computed
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1147 * over the data block. Both dat and ecc_read may be corrected.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1148 *
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1149 * `nbytes' is the number of bytes we're interested in; if a correction
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1150 * is indicated outside of that range, it will be ignored.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1151 *
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1152 * Returns:
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1153 * 0 for no errors
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1154 * 1 for a corrected single bit error in the data
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1155 * 2 for a corrected single bit error in the ECC
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1156 * -1 for an uncorrectable error (more than one bit)
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1157 */
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1158 int my_ecc_repair(struct _cyg_nand_device_t *dev,
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1159 CYG_BYTE *dat, size_t nbytes,
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1160 CYG_BYTE ecc_read, const CYG_BYTE ecc_calc);
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1161 </programlisting>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1162
3017 8502a048ad17 Update NAND to latest Ross Younger <wry@ecoscentric.com> parents: 2994 diff changeset	1163 <para>In some cases - particularly where hardware assistance is in use -
8502a048ad17 Update NAND to latest Ross Younger <wry@ecoscentric.com> parents: 2994 diff changeset	1164 it is necessary to specify different functions
8502a048ad17 Update NAND to latest Ross Younger <wry@ecoscentric.com> parents: 2994 diff changeset	1165 for calculating the ECC depending on whether the operation at hand is
3395 707de7f35fc7 io/nand: Minor doc updates Ross Younger <wry@ecoscentric.com> parents: 3017 diff changeset	1166 a page read or a page write. In that case, two
707de7f35fc7 io/nand: Minor doc updates Ross Younger <wry@ecoscentric.com> parents: 3017 diff changeset	1167 <emphasis>init</emphasis>
707de7f35fc7 io/nand: Minor doc updates Ross Younger <wry@ecoscentric.com> parents: 3017 diff changeset	1168 and
707de7f35fc7 io/nand: Minor doc updates Ross Younger <wry@ecoscentric.com> parents: 3017 diff changeset	1169 <emphasis>calc</emphasis>
3017 8502a048ad17 Update NAND to latest Ross Younger <wry@ecoscentric.com> parents: 2994 diff changeset	1170 functions may be supplied, each taking the same prototype.
8502a048ad17 Update NAND to latest Ross Younger <wry@ecoscentric.com> parents: 2994 diff changeset	1171 </para>
8502a048ad17 Update NAND to latest Ross Younger <wry@ecoscentric.com> parents: 2994 diff changeset	1172
2951 0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1173 <para>The algorithm parameters and functions are then tied together
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1174 with one of the following macros:
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1175 </para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1176
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1177 <programlisting>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1178 CYG_NAND_ECC_ALG_SW(my_ecc, _datasize, _eccsize, my_ecc_init, my_ecc_calc, my_ecc_repair);
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1179
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1180 CYG_NAND_ECC_ALG_HW(my_ecc, _datasize, _eccsize, my_ecc_init, my_ecc_calc, my_ecc_repair);
3017 8502a048ad17 Update NAND to latest Ross Younger <wry@ecoscentric.com> parents: 2994 diff changeset	1181
8502a048ad17 Update NAND to latest Ross Younger <wry@ecoscentric.com> parents: 2994 diff changeset	1182 CYG_NAND_ECC_ALG_HW2(my_ecc, _datasize, _eccsize, my_ecc_init, my_ecc_calc_read, my_ecc_calc_write, my_ecc_repair);
3395 707de7f35fc7 io/nand: Minor doc updates Ross Younger <wry@ecoscentric.com> parents: 3017 diff changeset	1183
707de7f35fc7 io/nand: Minor doc updates Ross Younger <wry@ecoscentric.com> parents: 3017 diff changeset	1184 CYG_NAND_ECC_ALG_HW3(my_ecc, _datasize, _eccsize, my_ecc_init_read, my_ecc_init_write, my_ecc_calc_read, my_ecc_calc_write, my_ecc_repair);
2951 0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1185 </programlisting>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1186
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1187 <tip><para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1188 It's OK to use software ECC while getting things going, but if you do
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1189 then switch to a hardware implementation, you probably need to erase
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1190 your entire NAND chip including its Bad Block Table. The
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1191 <filename>nanderase</filename> utility may come in handy for this.)
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1192 </para></tip>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1193
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1194 <warning><para>You must be sure that your ECC repair algorithm is correct.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1195 This can be quite tricky to test.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1196 However, it is often possible to hoodwink the controller into computing
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1197 ECCs for you even if the data is not going to affect the data stored
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1198 on the NAND chip, for example if you send it data but haven't told it to
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1199 program a page.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1200 A variant of the <filename>sweccwalk</filename> test may come in handy
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1201 for this purpose.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1202 </para></warning>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1203
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1204 <para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1205 An example implementation, including an ECC calculation and repair test
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1206 named <filename>eccwalk</filename>, may be found in the STM3210E
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1207 evaluation board platform HAL,
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1208 <filename>packages/hal/cortexm/stm32/stm3210e_eval</filename>.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1209 The chip NAND controller has on-board ECC calculation, but does not
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1210 undertake to repair data; a repair function was written specially.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1211 </para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1212
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1213 </sect2>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1214 </sect1>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1215
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1216 </chapter>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1217
2938 931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	1218 <chapter id="nand-tests-utils">
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1219
2938 931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	1220 <title>Tests and utilities</title>
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	1221
931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	1222 <sect1 id="nand-tests"><title>Unit and functional tests</title>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1223 <para> The NAND library includes a number of tests. The most useful to
2951 0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1224 driver writers are <filename>readwrite</filename>,
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1225 <filename>rwbenchmark</filename>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1226 and
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1227 <filename>sweccwalk</filename>;
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1228 the others are only likely to be of interest to library maintainers.</para>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1229
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1230 <glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1231 <glossentry><glossterm>readwrite</glossterm><glossdef><para>Performs a
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1232 read-write-erase cycle on the first NAND device it finds, checking that
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1233 its operations have had the expected effect on the device contents. This
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1234 is a potentially destructive test; do not run it on a device containing
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1235 data you care about!
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1236 </para></glossdef></glossentry>
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1237 <glossentry><glossterm>rwbenchmark</glossterm><glossdef><para>
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1238 A more involved version of <filename>readwrite</filename>, this is a
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1239 timing test which performs multiple reads, writes and erases and
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1240 applies statistical techniques to the results in the same way that
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1241 <filename>tm_basic</filename> instruments the speed of various eCos kernel functions.
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1242 <emphasis>
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1243 This is a potentially destructive test; do not run it on a device containing
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1244 data you care about!</emphasis>
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1245 </para></glossdef></glossentry>
2951 0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1246 <glossentry><glossterm>sweccwalk</glossterm><glossdef><para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1247 Repeatedly makes single-bit changes to a data buffer and checks that the
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1248 software ECC implementation correctly repairs them.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1249 <tip><para>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1250 This test can be adapted to test out hardware ECC implementations.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1251 The test outputs the raw ECC codes as it goes, which is useful in
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1252 confirming that the bits in the computed ECC are what you think they are.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1253 </para></tip>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1254 </para></glossdef></glossentry>
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1255
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1256 <glossentry><glossterm>nandunit</glossterm><glossdef><para>Some unit tests
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1257 which do not require any NAND device: ECC known answer vectors, and OOB
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1258 area packing/unpacking correctness. </para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1259 <glossentry><glossterm>readlimits</glossterm><glossdef><para>Attempts
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1260 to read a block outside of a partition, confirming that it doesn't
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1261 work.</para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1262 </glosslist>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1263
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1264 <para>There are some further tests of the library which
2961 3e4bd6789be2 * Added missing closing tags alexs parents: 2951 diff changeset	1265 require the <link linkend="devs-nand-synth-tests">synthetic NAND device</link>.
3e4bd6789be2 * Added missing closing tags alexs parents: 2951 diff changeset	1266 </para>
2940 a8bb8cc067c3 * Fixed syntax so jade does not barf alexs parents: 2938 diff changeset	1267 </sect1>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1268
2938 931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	1269 <sect1 id="nand-utils">
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1270 <title>Ancillary NAND utilities</title>
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1271 <para> The following utilities are included with the NAND library.
2951 0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1272 They are standalone eCos applications; for convenience, you can set
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1273 <constant>CYGBLD_IO_NAND_BUILD_UTILS</constant> in your eCos configuration
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1274 and they will be built and placed into
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1275 <filename>install/tests/io/nand/current/utils</filename>.
0eb1d8b14623 NAND: update doc for recent changes; document ECC alg interface Ross Younger <wry@ecoscentric.com> parents: 2944 diff changeset	1276 </para>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1277
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1278 <glosslist>
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1279 <glossentry><glossterm>erasenand.c</glossterm><glossdef><para>
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1280 Loops over all the blocks of a partition, erasing all the blocks which are not
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1281 marked as bad. The device and partition to erase are set by #define.
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1282 <note><para>This will not normally erase the Bad Block Table. This is because
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1283 the BBT reports its own blocks as "Reserved" when queried via
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1284 <function>cyg_nand_bbt_query</function>, which makes them inaccessible
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1285 to applications. However, if
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1286 <constant>CYGSEM_IO_NAND_USE_BBT</constant> is turned off, then any BBT
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1287 present will not be detected and hence will be erased.
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1288 </para></note>
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1289 </para></glossdef></glossentry>
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1290 <glossentry><glossterm>erase_bbt_dangerous.c</glossterm><glossdef><para>
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1291 Erases the NAND blocks comprising the primary and mirror bad-block tables of a device.
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1292 The device to erase is set by #define.
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1293 (The tables are detected by the library in the usual way. If none are present, the
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1294 library will scan the device for factory-bad blocks to create such a table, then this
c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1295 code will immediately erase it.)
2994 3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1296 <warning><para>It is particularly dangerous to run this utility
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1297 on a production device, as it is generally not possible to later
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1298 reconstruct the list of factory-bad blocks. It is intended only as an
3d3b0d53c2e5 NAND: application interface v2: functions take partition-relative addresses. Ross Younger <wry@ecoscentric.com> parents: 2961 diff changeset	1299 aid to driver authors. </para></warning>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1300 </para></glossdef></glossentry>
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1301 </glosslist>
2938 931aba9e89f2 nand doc enhandements Ross Younger <wry@ecoscentric.com> parents: 2937 diff changeset	1302 </sect1>
2937 c3c708068a37 move bbt and multipagebbt to synth nand wry parents: 2930 diff changeset	1303 </chapter>
2930 6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1304
6efd22c2e7b1 Import anoncvs-based NAND and device drivers to 20090826 Ross Younger <wry@ecoscentric.com> parents: diff changeset	1305 </part>

Mercurial > nand-ecoscentric

annotate packages/io/nand/current/doc/nand.sgml @ 3395:707de7f35fc7