path: root/Documentation/DocBook/mtdnand.tmpl

<?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 replacable 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 replacable 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 neccecary. 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>
	</sect1>
	<sect1 id="Hardware_control_functions">
		<title>Hardware control function</title>
		<para>
			The hardware control function provides access to the 
			control pins of the NAND chip(s). 
			The access can be done by GPIO pins or by address lines.
			If yo