<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
<book id="MTD-NAND-Guide">
<bookinfo>
<title>MTD NAND Driver Programming Interface</title>
<authorgroup>
<author>
<firstname>Thomas</firstname>
<surname>Gleixner</surname>
<affiliation>
<address>
<email>tglx@linutronix.de</email>
</address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2004</year>
<holder>Thomas Gleixner</holder>
</copyright>
<legalnotice>
<para>
This documentation is free software; you can redistribute
it and/or modify it under the terms of the GNU General Public
License version 2 as published by the Free Software Foundation.
</para>
<para>
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
</para>
<para>
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA
</para>
<para>
For more details see the file COPYING in the source
distribution of Linux.
</para>
</legalnotice>
</bookinfo>
<toc></toc>
<chapter id="intro">
<title>Introduction</title>
<para>
The generic NAND driver supports almost all NAND and AG-AND based
chips and connects them to the Memory Technology Devices (MTD)
subsystem of the Linux Kernel.
</para>
<para>
This documentation is provided for developers who want to implement
board drivers or filesystem drivers suitable for NAND devices.
</para>
</chapter>
<chapter id="bugs">
<title>Known Bugs And Assumptions</title>
<para>
None.
</para>
</chapter>
<chapter id="dochints">
<title>Documentation hints</title>
<para>
The function and structure docs are autogenerated. Each function and
struct member has a short description which is marked with an [XXX] identifier.
The following chapters explain the meaning of those identifiers.
</para>
<sect1 id="Function_identifiers_XXX">
<title>Function identifiers [XXX]</title>
<para>
The functions are marked with [XXX] identifiers in the short
comment. The identifiers explain the usage and scope of the
functions. Following identifiers are used:
</para>
<itemizedlist>
<listitem><para>
[MTD Interface]</para><para>
These functions provide the interface to the MTD kernel API.
They are not replaceable and provide functionality
which is complete hardware independent.
</para></listitem>
<listitem><para>
[NAND Interface]</para><para>
These functions are exported and provide the interface to the NAND kernel API.
</para></listitem>
<listitem><para>
[GENERIC]</para><para>
Generic functions are not replaceable and provide functionality
which is complete hardware independent.
</para></listitem>
<listitem><para>
[DEFAULT]</para><para>
Default functions provide hardware related functionality which is suitable
for most of the implementations. These functions can be replaced by the
board driver if necessary. Those functions are called via pointers in the
NAND chip description structure. The board driver can set the functions which
should be replaced by board dependent functions before calling nand_scan().
If the function pointer is NULL on entry to nand_scan() then the pointer
is set to the default function which is suitable for the detected chip type.
</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="Struct_member_identifiers_XXX">
<title>Struct member identifiers [XXX]</title>
<para>
The struct members are marked with [XXX] identifiers in the
comment. The identifiers explain the usage and scope of the
members. Following identifiers are used:
</para>
<itemizedlist>
<listitem><para>
[INTERN]</para><para>
These members are for NAND driver internal use only and must not be
modified. Most of these values are calculated from the chip geometry
information which is evaluated during nand_scan().
</para></listitem>
<listitem><para>
[REPLACEABLE]</para><para>
Replaceable members hold hardware related functions which can be
provided by the board driver. The board driver can set the functions which
should be replaced by board dependent functions before calling nand_scan().
If the function pointer is NULL on entry to nand_scan() then the pointer
is set to the default function which is suitable for the detected chip type.
</para></listitem>
<listitem><para>
[BOARDSPECIFIC]</para><para>
Board specific members hold hardware related information which must
be provided by the board driver. The board driver must set the function
pointers and datafields before calling nand_scan().
</para></listitem>
<listitem><para>
[OPTIONAL]</para><para>
Optional members can hold information relevant for the board driver. The
generic NAND driver code does not use this information.
</para></listitem>
</itemizedlist>
</sect1>
</chapter>
<chapter id="basicboarddriver">
<title>Basic board driver</title>
<para>
For most boards it will be sufficient to provide just the
basic functions and fill out some really board dependent
members in the nand chip description structure.
</para>
<sect1 id="Basic_defines">
<title>Basic defines</title>
<para>
At least you have to provide a mtd structure and
a storage for the ioremap'ed chip address.
You can allocate the mtd structure using kmalloc
or you can allocate it statically.
In case of static allocation you have to allocate
a nand_chip structure too.
</para>
<para>
Kmalloc based example
</para>
<programlisting>
static struct mtd_info *board_mtd;
static void __iomem *baseaddr;
</programlisting>
<para>
Static example
</para>
<programlisting>
static struct mtd_info board_mtd;
static struct nand_chip board_chip;
static void __iomem *baseaddr;
</programlisting>
</sect1>
<sect1 id="Partition_defines">
<title>Partition defines</title>
<para>
If you want to divide your device into partitions, then
define a partitioning scheme suitable to your board.
</para>
<programlisting>
#define NUM_PARTITIONS 2
static struct mtd_partition partition_info[] = {
{ .name = "Flash partition 1",
.offset = 0,
.size = 8 * 1024 * 1024 },
{ .name = "Flash partition 2",
.offset = MTDPART_OFS_NEXT,
.size = MTDPART_SIZ_FULL },
};
</programlisting>