fs/cromfs: Add a README file.

Documentation/README.html

@@ -8,7 +8,7 @@
   <tr align="center" bgcolor="#e4e4e4">
     <td>
       <h1><big><font color="#3c34ec"><i>NuttX README Files</i></font></big></h1>
-      <p>Last Updated: January 8, 2018</p>
+      <p>Last Updated: March 22, 2018</p>
     </td>
   </tr>
 </table>
@@ -369,6 +369,8 @@ nuttx/
  |- fs/
  |   |- binfs/
  |   |   `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/binfs/README.txt" target="_blank"><b><i>README.txt</i></b></a>
+ |   |- cromfs/
+ |   |   `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/cromfs/README.txt" target="_blank"><b><i>README.txt</i></b></a>
  |   |- mmap/
  |   |   `- <a href="https://bitbucket.org/nuttx/nuttx/src/master/fs/mmap/README.txt" target="_blank"><b><i>README.txt</i></b></a>
  |   |- nxffs/

README.txt

@@ -1937,6 +1937,8 @@ nuttx/
  |- fs/
  |   |- binfs/
  |   |   `- README.txt
+ |   |- cromfs/
+ |   |   `- README.txt
  |   |- mmap/
  |   |   `- README.txt
  |   |- nxffs/

fs/cromfs/README.txt

@@ -0,0 +1,120 @@
+README
+======
+
+This directory contains the the CROMFS file system.  This is an in-memory
+(meaning no block driver), read-only (meaning that can lie in FLASH) file
+system.  It uses LZF decompression on data only (meta data is not
+compressed).
+
+It accesses the in-memory file system via directory memory reads and, hence,
+can only reside in random access NOR-like FLASH.  It is intended for use
+with on-chip FLASH available on most MCUs (the design could probably be
+extended to access non-random-access FLASH as well, but those extensions
+are not yet in place).
+
+I do not have a good way to measure how much compression we get use LZF.  I
+have seen 37% compression reported in other applications, so I have to
+accept that for now.  That means, for example, that you could have a file
+system with 512Kb of data in only 322Kb of FLASH, giving you 190Kb to do
+ other things with.
+
+LZF compression is not known for its high compression rations, but rather
+for fast decompression.  According to the author of the LZF decompression
+routine, it is nearly as fast as a memcpy!
+
+There is also a new tool at /tools/gencromfs.c that will generate binary
+images for the NuttX CROMFS file system and and an example CROMFS file
+system image at apps/examples/cromfs.  That example includes a test file
+system that looks like:
+
+  $ ls -Rl ../apps/examples/cromfs/cromfs
+  ../apps/examples/cromfs/cromfs:
+  total 2
+  -rwxr--r--+ 1 spuda spuda 171 Mar 20 08:02 BaaBaaBlackSheep.txt
+  drwxrwxr-x+ 1 spuda spuda   0 Mar 20 08:11 emptydir
+  -rwxr--r--+ 1 spuda spuda 118 Mar 20 08:05 JackSprat.txt
+  drwxrwxr-x+ 1 spuda spuda   0 Mar 20 08:06 testdir1
+  drwxrwxr-x+ 1 spuda spuda   0 Mar 20 08:10 testdir2
+  drwxrwxr-x+ 1 spuda spuda   0 Mar 20 08:05 testdir3
+  ../apps/examples/cromfs/cromfs/emptydir:
+  total 0
+  ../apps/examples/cromfs/cromfs/testdir1:
+  total 2
+  -rwxr--r--+ 1 spuda spuda 249 Mar 20 08:03 DingDongDell.txt
+  -rwxr--r--+ 1 spuda spuda 247 Mar 20 08:06 SeeSawMargorieDaw.txt
+  ../apps/examples/cromfs/cromfs/testdir2:
+  total 5
+  -rwxr--r--+ 1 spuda spuda  118 Mar 20 08:04 HickoryDickoryDock.txt
+  -rwxr--r--+ 1 spuda spuda 2082 Mar 20 08:10 TheThreeLittlePigs.txt
+  ../apps/examples/cromfs/cromfs/testdir3:
+  total 1
+  -rwxr--r--+ 1 spuda spuda 138 Mar 20 08:05 JackBeNimble.txt
+
+When built into NuttX and deployed on a target, it looks like:
+
+  NuttShell (NSH) NuttX-7.24
+  nsh> mount -t cromfs /mnt/cromfs
+  nsh> ls -Rl /mnt/cromfs
+  /mnt/cromfs:
+   dr-xr-xr-x       0 .
+   -rwxr--r--     171 BaaBaaBlackSheep.txt
+   dr-xr-xr-x       0 emptydir/
+   -rwxr--r--     118 JackSprat.txt
+   dr-xr-xr-x       0 testdir1/
+   dr-xr-xr-x       0 testdir2/
+   dr-xr-xr-x       0 testdir3/
+  /mnt/cromfs/emptydir:
+   drwxrwxr-x       0 .
+   dr-xr-xr-x       0 ..
+  /mnt/cromfs/testdir1:
+   drwxrwxr-x       0 .
+   dr-xr-xr-x       0 ..
+   -rwxr--r--     249 DingDongDell.txt
+   -rwxr--r--     247 SeeSawMargorieDaw.txt
+  /mnt/cromfs/testdir2:
+   drwxrwxr-x       0 .
+   dr-xr-xr-x       0 ..
+   -rwxr--r--     118 HickoryDickoryDock.txt
+   -rwxr--r--    2082 TheThreeLittlePigs.txt
+  /mnt/cromfs/testdir3:
+   drwxrwxr-x       0 .
+   dr-xr-xr-x       0 ..
+   -rwxr--r--     138 JackBeNimble.txt
+  nsh>
+
+Everything I have tried works:  examining directories, catting files, etc.
+The "." and ".." hard links also work:
+
+  nsh> cd /mnt/cromfs
+  nsh> cat emptydir/../testdir1/DingDongDell.txt
+  Ding, dong, bell,
+  Pussy's in the well.
+  Who put her in?
+  Little Johnny Green.
+
+  Who pulled her out?
+  Little Tommy Stout.
+  What a naughty boy was that,
+  To try to drown poor pussy cat,
+  Who never did him any harm,
+  And killed the mice in his father's barn.
+
+  nsh>
+
+To build the CROMFS file system, you would add the following to your
+configuration:
+
+1. Enable LZF
+
+   CONFIG_LIBC_LZF=y
+   CONFIG_LIBC_LZF_ALIGN=y
+   CONFIG_LIBC_LZF_HLOG=13
+   CONFIG_LIBC_LZF_SMALL=y
+
+2. Enable the CROMFS file system:
+
+   CONFIG_FS_CROMFS=y
+
+3. Enable the apps/examples/cromfs example:
+
+   CONFIG_EXAMPLES_CROMFS=y