Add drivers/mtd/README.txt

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).
+

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/

README.txt

@@ -1157,6 +1157,8 @@ nuttx
  |- drivers/
  |   |- lcd/
  |   |   `- README.txt
+ |   |- mtd/
+ |   |   `- README.txt
  |   |- sercomm/
  |   |   `- README.txt
  |   |- syslog/

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
+  NAND support is only partial in that there is no file system that works
-  it properly.  It should be considered a work in progress.  You will not
+  with it properly.  It should be considered a work in progress.  You will
-  want to use NAND unless you are interested in investing a little effort.
+  not want to use NAND unless you are interested in investing a little
-  See the STATUS section below.
+  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
+    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.
 
-    The work around for this case is to put the NORBOOT image into Serial
+    2. Booting from Serial Flash. The work around for this case is to put
-    FLASH.  Then, the system will boot from Serial FLASH by copying the
+       the NORBOOT image into Serial FLASH.  Then, the system will boot from
-    NORBOOT image in SRAM which will run and then start the image in NOR
+       Serial FLASH by copying the NORBOOT image in SRAM which will run and
-    FLASH.  See the discussion of the NORBOOT configuration in the
+       then start the image in NOR FLASH.  See the discussion of the NORBOOT
-    "Creating and Using NORBOOT" section above.
+       configuration in the "Creating and Using NORBOOT" section above.
 
-    NOTES: (1) There is jumper on the CM module that must be closed to
+       NOTE thathere is jumper on the CM module that must be closed to enable
-    enable use of the AT25 Serial Flash.  (2) If using SAM-BA, make sure
+       use of the AT25 Serial Flash.  Also, if you are using using SAM-BA,
-    that you load the NOR boot program into the boot area via the pull-
+       make sure that you load the NOR boot program into the boot area via
-    down menu.
+       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
   ------

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.