Add drivers/mtd/README.txt

5 files changed, 197 insertions, 40 deletions

diff --git a/nuttx/ChangeLog b/nuttx/ChangeLog
index b48cf6fd5..7b54b6192 100644
--- a/nuttx/ChangeLog
+++ b/nuttx/ChangeLog
@@ -6159,3 +6159,5 @@
 	  the media option. It just takes to long! (2013-12-02).
 	* drivers/mtd/mtd_nand.c: Fix a typo in calculation of page number
 	  (2013-12-02).
+	* drivers/mtd/README.txt:  New README file (2013-12-04).
+
diff --git a/nuttx/Documentation/README.html b/nuttx/Documentation/README.html
index 75883709f..66e7aede6 100644
--- a/nuttx/Documentation/README.html
+++ b/nuttx/Documentation/README.html
@@ -229,6 +229,8 @@
  |   |- drivers/
  |   |   |- lcd/
  |   |   |   `- <a href="http://sourceforge.net/p/nuttx/git/ci/master/tree/nuttx/drivers/lcd/README.txt"><b><i>README.txt</i></b></a>
+ |   |   |- mtd/
+ |   |   |   `- <a href="http://sourceforge.net/p/nuttx/git/ci/master/tree/nuttx/drivers/mtd/README.txt"><b><i>README.txt</i></b></a>
  |   |   |- sercomm/
  |   |   |   `- <a href="http://sourceforge.net/p/nuttx/git/ci/master/tree/nuttx/drivers/sercomm/README.txt">README.txt</a>
  |   |   |- syslog/
diff --git a/nuttx/README.txt b/nuttx/README.txt
index b293bfe86..f643eff49 100644
--- a/nuttx/README.txt
+++ b/nuttx/README.txt
@@ -20,7 +20,7 @@ README
   o Shells
   o Building NuttX
     - Building
-    - Re-building 
+    - Re-building
     - Build Targets and Options
     - Native Windows Build
     - Installing GNUWin32
@@ -47,7 +47,7 @@ Installing Cygwin
      discussion "Native Windows Build" below).
 
   Some Cygwin installation tips:
-  
+
   1. Install at C:\cygwin
 
   2. Install EVERYTHING:  "Only the minimal base packages from the
@@ -58,7 +58,7 @@ Installing Cygwin
      provide you with the opportunity to install every Cygwin package.
      Be advised that this will download and install hundreds of megabytes
      to your computer."
-     
+
      If you use the "default" installation, you will be missing many
      of the Cygwin utilities that you will need to build NuttX.  The
      build will fail in numerous places because of missing packages.
@@ -100,10 +100,10 @@ Semi-Optional apps/ Package
   should exactly match the version of the NuttX tarball).  Again, you
   might want to rename the directory to simply apps/ to match what
   you read in the documentation
-  
+
   After unpacking the apps tarball, you will have two directories side
   by side like this:
-  
+
              |
         +----+----+
         |         |
@@ -128,7 +128,7 @@ Installation Directories with Spaces in the Path
 
   I work around spaces in the home directory name, by creating a
   new directory that does not contain any spaces, such as /home/nuttx.
-  Then I install NuttX in /home/nuttx and always build from 
+  Then I install NuttX in /home/nuttx and always build from
   /home/nuttx/nuttx-code.
 
 Downloading from Repositories
@@ -300,7 +300,7 @@ NuttX Configuration Tool
 
   WARNING:  Never do 'make menuconfig' on a configuration that has
   not been converted to use the kconfig-frontends tools!  This will
-  damage your configuration (see 
+  damage your configuration (see
   http://www.nuttx.org/doku.php?id=wiki:howtos:convertconfig).
 
   The 'menuconfig' make target depends on two things:
@@ -410,7 +410,7 @@ Converting Older Configurations to use the Configuration Tool
              cp configs/<board>/<condfiguration>/defconfig .config
              make menuconfig  (Just exit and save the new .config file)
              tools/cmpconfig configs/<board>/<condfiguration>/defconfig .config | grep file1
- 
+
            The final grep will show settings in the old defconfig file that
            do not appear in the new .config file (or have a different value
            in the new .config file).  In the new configuration, you will
@@ -495,7 +495,7 @@ NuttX Configuration Tool under DOS
           the Cygwin kconfig-mconf running in the Windows console.  The
           following change to the top-level Kconfig file seems to work
           around these problems:
-  
+
           config APPSDIR
               string
           -   option env="APPSDIR"
@@ -605,7 +605,7 @@ Building
   arguments on the make command.  Read ${TOPDIR}/configs/<board-name>/README.txt
   to see if that applies to your target.
 
-Re-building 
+Re-building
 -----------
 
   Re-building is normally simple -- just type make again.
@@ -623,9 +623,9 @@ Re-building
   build is still using the version of the file in the copied directory, not
   your modified file! To work around this annoying behavior, do the
   following when you re-build:
-   
+
      make clean_context all
-   
+
   This 'make' command will remove of the copied directories, re-copy them,
   then make NuttX.
 
@@ -743,7 +743,7 @@ Native Windows Build
   the you not install the optional MSYS components as there may be conflicts.
 
   This capability should still be considered a work in progress because:
- 
+
   (1) It has not been verfied on all targets and tools, and
   (2) it still lacks some of the creature-comforts of the more mature environments
       (like 'make menuconfig' support.  See the section "NuttX Configuration Tool
@@ -883,7 +883,7 @@ Window Native Toolchain Issues
      If you are building natively on Windows, then no such conflict exists
      and the best selection is:
 
-       MKDEP                = $(TOPDIR)/tools/mkdeps.exe 
+       MKDEP                = $(TOPDIR)/tools/mkdeps.exe
 
 General Pre-built Toolchain Issues
 
@@ -898,7 +898,7 @@ General Pre-built Toolchain Issues
   then you may incounter these:
 
   4. Header Files.  Most pre-built toolchains will build with a foreign C
-     library (usually newlib, but maybe uClibc or glibc if you are using a 
+     library (usually newlib, but maybe uClibc or glibc if you are using a
      Linux toolchain).  This means that the header files from the foreign
      C library will be built into the toolchain.  So if you "include <stdio.h>",
      you will get the stdio.h from the incompatible, foreign C library and
@@ -906,7 +906,7 @@ General Pre-built Toolchain Issues
 
      This can cause really confusion in the buildds and you must always be
      sure the -nostdinc is included in the CFLAGS.  That will assure that
-     you take the include files only from 
+     you take the include files only from
 
   5. Libraries.  What was said above header files applies to libraries.
      You do not want to include code from the libraries of any foreign
@@ -1157,6 +1157,8 @@ nuttx
  |- drivers/
  |   |- lcd/
  |   |   `- README.txt
+ |   |- mtd/
+ |   |   `- README.txt
  |   |- sercomm/
  |   |   `- README.txt
  |   |- syslog/
diff --git a/nuttx/configs/sama5d3x-ek/README.txt b/nuttx/configs/sama5d3x-ek/README.txt
index 09f74253a..a7f06e39a 100644
--- a/nuttx/configs/sama5d3x-ek/README.txt
+++ b/nuttx/configs/sama5d3x-ek/README.txt
@@ -1352,10 +1352,10 @@ SDRAM Support
 NAND Support
 ============
 
-  NAND support is only partial and there is no file system that works with
-  it properly.  It should be considered a work in progress.  You will not
-  want to use NAND unless you are interested in investing a little effort.
-  See the STATUS section below.
+  NAND support is only partial in that there is no file system that works
+  with it properly.  It should be considered a work in progress.  You will
+  not want to use NAND unless you are interested in investing a little
+  effort. See the STATUS section below.
 
   NAND Support
   ------------
@@ -1390,26 +1390,32 @@ NAND Support
     Application Configuration -> NSH Library
       CONFIG_NSH_ARCHINIT=y             : Use architecture-specific initialization
 
-    WARNING:  This will wipe out everything that you may have on the NAND
-    FLASH!  I have found that using the JTAG with no valid image on NAND
-    or Serial FLASH is a problem:  In that case, the code always ends up
-    in the SAM-BA bootloader.
+    NOTES:
+
+    1. WARNING:  This will wipe out everything that you may have on the NAND
+       FLASH!  I have found that using the JTAG with no valid image on NAND
+       or Serial FLASH is a problem:  In that case, the code always ends up
+       in the SAM-BA bootloader.
+
+    2. Booting from Serial Flash. The work around for this case is to put
+       the NORBOOT image into Serial FLASH.  Then, the system will boot from
+       Serial FLASH by copying the NORBOOT image in SRAM which will run and
+       then start the image in NOR FLASH.  See the discussion of the NORBOOT
+       configuration in the "Creating and Using NORBOOT" section above.
 
-    The work around for this case is to put the NORBOOT image into Serial
-    FLASH.  Then, the system will boot from Serial FLASH by copying the
-    NORBOOT image in SRAM which will run and then start the image in NOR
-    FLASH.  See the discussion of the NORBOOT configuration in the
-    "Creating and Using NORBOOT" section above.
+       NOTE thathere is jumper on the CM module that must be closed to enable
+       use of the AT25 Serial Flash.  Also, if you are using using SAM-BA,
+       make sure that you load the NOR boot program into the boot area via
+       the pull-down menu.
 
-    NOTES: (1) There is jumper on the CM module that must be closed to
-    enable use of the AT25 Serial Flash.  (2) If using SAM-BA, make sure
-    that you load the NOR boot program into the boot area via the pull-
-    down menu.
+    3. Unfortunately, there are no appropriate NAND file system in NuttX as
+       of this writing.  The following sections discussion issues/problems
+       with using NXFFS and FAT.
 
     NXFFS
     -----
 
-    The NuttX FLASH File System (NXFFS) works will with NOR-like FLASH
+    The NuttX FLASH File System (NXFFS) works well with NOR-like FLASH
     but does not work well with NAND (See comments below under STATUS)
 
     File Systems:
@@ -1442,14 +1448,21 @@ NAND Support
 
       Defaults for all other NXFFS settings should be okay.
 
-      NOTE:  NXFFS will require some significant buffering because of
-      the large size of the NAND flash blocks.  You will also need
-      to enable SDRAM as described above.
-
     Board Selection
       CONFIG_SAMA5_NAND_AUTOMOUNT=y     : Enable FS support on NAND
       CONFIG_SAMA5_NAND_FTL=y           : Use an flash translation layer
 
+      NOTE:  FTL will require some significant buffering because of
+      the large size of the NAND flash blocks.  You will also need
+      to enable SDRAM as described above.
+
+    SMART FS
+    --------
+
+    Another option is Smart FS.  Smart FS is another small file system
+    designed to work with FLASH.  Properties:  It does support some wear-
+    leveling, but like FAT, cannot handle bad blocks.
+
     Using NAND with NXFFS
     ---------------------
 
@@ -1532,7 +1545,7 @@ NAND Support
     You will not that the system comes up immediately because there is not
     need to scan the volume in this case..
 
-    The NSH 'mkfatfs' command can be used to format a FATfile system on
+    The NSH 'mkfatfs' command can be used to format a FAT file system on
     NAND.
 
       nsh> mkfatfs /dev/mtdblock0
@@ -1579,7 +1592,7 @@ NAND Support
     perform bad block detection and sparing so that FAT works transparently
     on top of the NAND.
 
-    Another, less general option would be support bad blocks within FAT.
+    Another, less general, option would be support bad blocks within FAT.
 
   STATUS
   ------
diff --git a/nuttx/drivers/mtd/README.txt b/nuttx/drivers/mtd/README.txt
new file mode 100644
index 000000000..ea7bcfbde
--- /dev/null
+++ b/nuttx/drivers/mtd/README.txt
@@ -0,0 +1,138 @@
+MTD README
+==========
+
+  MTD stands for "Memory Technology Devices".  This directory contains
+  drivers that operate on various memory technoldogy devices and provide an
+  MTD interface.  That MTD interface may then by use by higher level logic
+  to control access to the memory device.
+
+  See include/nuttx/mtd/mtd.h for additional information.
+
+NAND MEMORY
+===========
+
+  Files
+  -----
+
+  This directory also includes drivers for NAND memory.  These include:
+
+    mtd_nand.c: The "upper half" NAND MTD driver
+    mtd_nandecc.c, mtd_nandscheme.c, and hamming.c: Implement NAND software
+      ECC
+    mtd_onfi.c, mtd_nandmodel.c, and mtd_modeltab.c: Implement NAND FLASH
+      identification logic.
+
+  File Systems
+  ------------
+
+  NAND support is only partial in that there is no file system that works
+  with it properly.  It should be considered a work in progress.  You will
+  not want to use NAND unless you are interested in investing a little
+  effort. See the STATUS section below.
+
+    NXFFS
+    -----
+
+    The NuttX FLASH File System (NXFFS) works well with NOR-like FLASH
+    but does not work well with NAND.  Some simple usability issues
+    include:
+
+      - NXFFS can be very slow.  The first time that you start the system,
+        be prepared for a wait; NXFFS will need to format the NAND volume.
+        I have lots of debug on so I don't yet know what the optimized wait
+        will be.  But with debug ON, software ECC, and no DMA the wait is
+        in many tens of minutes (and substantially  longer if many debug
+        options are enabled.
+
+      - On subsequent boots, after the NXFFS file system has been created
+        the delay will be less.  When the new file system is empty, it will
+        be very fast.  But the NAND-related boot time can become substantial
+        whenthere has been a lot of usage of the NAND.  This is because
+        NXFFS needs to scan the NAND device and build the in-memory dataset
+        needed to access NAND and there is more that must be scanned after
+        the device has been used.  You may want tocreate a separate thread at
+        boot time to bring up NXFFS so that you don't delay the boot-to-prompt
+        time excessively in these longer delay cases.
+
+      - There is another NXFFS related performance issue:  When the FLASH
+        is fully used, NXFFS will restructure the entire FLASH, the delay
+        to restructure the entire FLASH will probably be even larger.  This
+        solution in this case is to implement an NXFSS clean-up daemon that
+        does the job a little-at-a-time so that there is no massive clean-up
+        when the FLASH becomes full.
+
+    But there is a more serious, showstopping problem with NXFFS and NAND:
+
+      - Bad NXFFS behavior with NAND:  If you restart NuttX, the files that
+        you wrote to NAND will be gone.  Why?  Because the multiple writes
+        have corrupted the NAND ECC bits.  See STATUS below.  NXFFS would
+        require a major overhaul to be usable with NAND.
+
+    There are a few reasons whay NXFFS does not work with NAND. NXFFS was
+    designed to work with NOR-like FLASH and NAND differs from other that
+    FLASH model in several ways.  For one thing, NAND requires error
+    correction (ECC) bytes that must be set in order to work around bit
+    failures.  This affects NXFFS in two ways:
+
+     - First, write failures are not fatal. Rather, they should be tried by
+       bad blocks and simply ignored.  This is because unrecoverable bit
+       failures will cause read failures when reading from NAND.  Setting
+       the CONFIG_EXPERIMENTAL+CONFIG_NXFFS_NAND option will enable this
+       behavior.
+
+       [CONFIG_NXFFS_NAND is only available is CONFIG_EXPERIMENTAL is also
+        selected.]
+
+     - Secondly, NXFFS will write a block many times.  It tries to keep
+       bits in the erased state and assumes that it can overwrite those bits
+       to change them from the erased to the non-erased state.  This works
+       will with NOR-like FLASH.  NAND behaves this way too.  But the
+       problem with NAND is that the ECC bits cannot be re-written in this
+       way.  So once a block has been written, it cannot be modified.  This
+       behavior has NOT been fixed in NXFFS.  Currently, NXFFS will attempt
+       to re-write the ECC bits causing the ECC to become corrupted because
+       the ECC bits cannot be overwritten without erasing the entire block.
+
+     This may prohibit NXFFS from ever being used with NAND.
+
+    FAT
+    ---
+
+    Another option is FAT.  FAT can be used if the Flast Translation Layer
+    (FTL) is enabled.  FTL converts the NAND MTD interface to a block driver
+    that can then be used with FAT.
+
+    FAT, however, will not handle bad blocks and does not perform any wear
+    leveling.  So you can bring up a NAND file system with FAT and a new,
+    clean NAND FLASH but you need to know that eventually, there will be
+    NAND bit failures and FAT will stop working: If you hit a bad block,
+    then FAT is finished.  There is no mechanism in place in FAT not to
+    mark and skip over bad blocks.
+
+    FTL writes are also particularly inefficient with NAND.  In order to
+    write a sector, FTL will read the entire erase block into memory, erase
+    the block on FLASH, modify the sector and re-write the erase block back
+    to FLASH.  For large NANDs this can be very inefficient.  For example,
+    I am currently using nand with a 128KB erase block size and 2K page size
+    so each write can cause a 256KB data transfer!
+
+    NOTE that there is some caching logic within FAT and FTL so that this
+    cached erase block can be re-used if possible and writes will be
+    deferred as long as possible.
+
+    SMART FS
+    --------
+
+    I have not yet tried SmartFS.  But I know that it does not perform bad
+    block checking (like FAT).  I do not know if it assumes that it can write
+    into erased regions of a sector multiple times (like NXFFS).
+
+     What is Needed
+    --------------
+
+    What is needed to work with FAT properly would be another MTD layer
+    between the FTL layer and the NAND FLASH layer.  That layer would
+    perform bad block detection and sparing so that FAT works transparently
+    on top of the NAND.
+
+    Another, less general, option would be support bad blocks within FAT.