readme.txt

H3 M-system NAND flash driver in Linux OS, M-DOC driver

 *******************************************************************************
 *                                                                             *
 *  DOC Driver for Linux 2.6                                                   *
 *  Source Code Edition                                                        *
 *                                                                             *
 *                                                                             *
 *                         INSTALLATION MANUAL                                 *
 *                                                                             *
 *                                                                             *
 *  Version 1.0.83, released on January 07 2007                                *
 *  Based on DOC Driver Block Device SDK version 1.0.0 RC2                     *
 *                                                                             *
 *  Email questions to: [e-mail]                                 *
 *  Copyright (C) SanDisk IL Ltd. 1995 - 2007                                  *
 *  SanDisk IL Ltd., 7 Atir Yeda Street, Kfar Saba 44425, Israel               *
 *                                                                             *
 *  Please note that effective January 1, 2007, the name msystems Ltd. was     *
 *  changed to SanDisk IL Ltd.                                                 *
 *                                                                             *
 *******************************************************************************
 *                                                                             *
 * This program is free software; you can redistribute it and/or modify it     *
 * under the terms of the GNU General Public License as published by the Free  *
 * Software Foundation; either version 2 of the License, or any later version. *
 * 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, which is set forth in the readme.txt file.                    *
 * 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., 51  *
 * Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA                     *
 *                                                                             *
 * This License does not grant you any right to use the trademarks, service    *
 * marks or logos of SanDisk IL Ltd. or SanDisk Corporation.                   *
 * Subject to the foregoing, SanDisk IL Ltd., for itself and on behalf of its  *
 * licensors, hereby reserves all intellectual property rights in the program, *
 * except for the rights expressly granted in this License.                    *
 *                                                                             *
 *******************************************************************************


  Contents
  ========

  1. Introduction
  2. Supported types of mDOC devices
  3. Conventions used in this document
  4. DOC driver's general configuration options
  5. Board specific configuration options
  6. Configuring DOC driver to use Direct Memory Access (DMA)
  7. Configuring DOC driver to use mDOC READY interrupt
  8. Compiling DOC driver
  9. Installing DOC driver
 10. Using DOC driver
 11. Configuring DOC driver to reduce power consumption
 12. Improving DOC driver's I/O performance
 13. Reducing DOC driver's load on CPU
 14. Access to DOC driver's Extended Functions
 15. Formatting mDOC
 16. Updating firmware in mDOC devices
 17. Memory footprint
 18. Known limitations
 19. Disclaimer of Liability
 20. Contact information


  1. Introduction
  ===============

  1.1. This document explains how to install DOC driver, and use mDOC device
       with Linux operating system. The information in this document applies
       to 2.6.x versions of the Linux kernel.

  1.2. The mDOC devices are high performance, low cost data storage products
       based on the latest flash technology. The mDOC devices serve two
       purposes under Linux:

           (1) Main data storage device

               In this role, mDOC devices serve the same purpose that
               conventional hard disks serve in Linux servers or workstations -
               they store various Linux kernel componenets (such as device
               drivers, Linux libraries and configuration files), user
               applications etc. 

           (2) System's boot device

               All mDOC devices feature ROM area which can be programmed via
               IOCTL calls to DOC driver. Boards developers usually arrange
               for this ROM area to appear at CPU's reset vector, and software
               developers program board-specific bootstrap code into it. When
               CPU is reset, it executes this bootstrap code, and boots Linux
               system entirely from mDOC device. Dedicated boot devices such as
               separate ROM or NOR flash chips are no longer needed.

       This document describes only the data storage function of mDOC devices.

  1.3. Although mDOC devices use multi-level cell NAND flash technology
       internally, DOC driver completely hides this fact from the user, and
       implements traditional block device interface. This allow mDOC devices
       to works with all standard disk-oriented Linux file systems (such as
       EXT2, EXT3 etc.). In that respect DOC driver is similar to ATA hard
       disks and CompactFlash cards, and is different from other NAND or NOR
       flash devices (which must be managed by flash-specific file systems such
       as JFFS2). All standard disk oriented Linux utilities (such as 'fdisk',
       'du' etc.) work with mDOC devices.
        
  1.4. DOC driver is distributed in the source code form, and is expected to
       be compiled at customer's site. Instructions on how to configure and
       compile DOC driver are provided in later chapters in this document.



  2. Supported types of mDOC devices
  ==================================

  2.1. This version of DOC driver supports the following types of mDOC
       devices:

           - mDOC H3 family

       ===> NOTE. This version of DOC driver will NOT work with the
                  following types of mDOC devices:
 
                      G3/P3 family
                      G4 family
                      H1 family

                  You will need to use TrueFFS driver version 7.1.0 (or higher)
                  with these types of mDOC devices. 
 


  3. Conventions used in this document
  ====================================
  
  3.1. Term "host" is used in this document to refer to computer where DOC
       driver's source code is located, and where DOC driver is compiled and
       linked. Typically "hosts" are engineering workstations running RedHat
       or SUSE Linux, or Windows operating systems.

       Term "target" is used in this document to refer to computer where DOC
       driver's executable runs, and where mDOC devices are installed. Typical
       targets are mobile devices powered by ARM or XScale microprocessors,
       specialized communication equipment powered by PowerPC microprocessors,
       and various other embedded systems.

       ===> NOTE. Although usually host and target are different systems, in
                  some cases "host" and "target" could actually refer to the
                  same system. For example, it is possible to plug mDOC into
                  the PCI slot of PC workstation running Linux. If this
                  workstation contains kernel's source tree installed on it,
                  then it is possible to compile DOC driver, and run it on
                  this workstation. In this case PC workstation serves both
                  as host and target system.

       All instructions provided by this document refer to the case when
       "host" and "target" are separate systems.
 
  3.2. Installation instructions in this document assume that user is logged
       into the system as "root".



  4. DOC driver's general configuration options
  =============================================

  4.1. Linux kernel requires that every device driver use unique major device
       number. By default, DOC driver uses major device number '100'. If
       you would like DOC driver to use different major device number, you
       can do so by passing "tffs_major=<number>" command line option when
       starting the driver. For example, to tell DOC driver to use major
       device number '120':
 
           insmod tffs.ko tffs_major=120

       ==> NOTE. File Documentation/devices.txt in Linux kernel's directory
                 list all major device numbers that had been reserved for the
                 various types of block devices. When specifying major device
                 number for DOC driver, it is essential to pick the number that
                 isn't listed in that file as already reserved for some other
                 block device. Consider using block device numbers that are
                 allocated for "local/experimental use" (for example, major
                 block device numbers in 120..127 range).



  5. Board specific configuration options
  =======================================

  5.1. As shipped, the DOC driver should work with the following boards:

           - Texas Instruments OMAP 2420 ("H4")
           - Intel PXA27x Development Platform ("Mainstone")

       If you are using one of these boards, you can skip remaining Sections
       in Chapter 5. For all other boards, you will need to configure DOC
       driver as appropriate for your system. Instructions below explain how
       to do this.

  5.2. User must tell DOC driver where to look for mDOC. This can be
       accomplished by using "tffs_addr=<physical_address>" command line
       option, where <physical_address> specifies physical address of the mDOC.
       For example, if in your particular board mDOC resides at physical
       address 0xc0000000, you would start DOC driver as follows: 

           insmod tffs.ko tffs_addr=0xc0000000

       Alternatively, you can set macro TFFS_PHYS_ADDR in DOC driver's header
       tffsarch.h to the physical address of the mDOC, and recompile the
       driver. For example, if mDOC device resides at physical address
       0xc0000000, macro TFFS_PHYS_ADDR should be #defined as follows:

          #define TFFS_PHYS_ADDR 0xc0000000

       In this case you DOC driver by default would look for mDOC at the
       specified address, so you can omit "tffs_addr=<physical_address>"
       command line parameter, and start DOC driver simply as:

           insmod tffs.ko

  5.3. When DOC driver starts up, it calls routine TffsHWInit() to do any
       board-specific hardware initialization (such as configuring Chip Select
       that mDOC is connected to, allocating and configuring DMA channels and
       interrupt request lines to be used by DOC driver etc.). The DOC
       driver's file tffsarch.c contains example implementations of this
       routine for a number of reference boards.

       Users are required to implement this routine as appropriate for their
       particular boards.

  5.4. When DOC driver shuts down, it calls routine TffsHWRelease() to do any
       board-specific hardware cleanup (such as releasing previously allocated
       DMA channels and interrupt request lines etc.). The DOC driver's file
       tffsarch.c contains example implementations of this routine for number
       of reference boards.

       Users are required to implement this routine as appropriate for their
       particular boards.



  6. Configuring DOC driver to use Direct Memory Access (DMA)
  ===========================================================

  6.1. By default, DOC driver uses software loops to transfer blocks of data
       to and from mDOC. In many cases it is possible to substantially improve
       mDOC's 'read' performance by using DMA controler to do these data
       transfers. 

       Current version of DOC driver includes example implementations of DMA
       support for the following reference boards:

           - Texas Instruments OMAP2420 ("H4")
           - Intel PXA27x ("Mainstone")

       These example implementations are found in DOC driver's files
       tffsarch.h and tffsarch.c, and consists of the following items:

          macro flReadEvenNumberOfBytes           defined in tffsarch.h
          macro flWriteEvenNumberOfBytes          defined in tffsarch.h

          routine tffs_dma_init()                 defined in tffsarch.c
          routine tffs_dma_release()              defined in tffsarch.c
          routine __dmasw_bread()                 defined in tffsarch.c
          routine __dmasw_bwrite()                defined in tffsarch.c

       You can use these example implementation as the starting point for DMA
       implementation for your own system. 

       ===> NOTE. Most likely you will be able to use the definitions of all