123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258 |
- README
- ======
- o Overview
- o gencromfs
- o Architecture
- o Configuration
- Overview
- ========
- 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 using 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 ratios, 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>
- gencromfs
- =========
- The genromfs program can be found in tools/. It is a single C file called
- gencromfs.c. It can be built in this way:
- cd tools
- make -f Makefile.host gencromfs
- The genromfs tool used to generate CROMFS file system images. Usage is
- simple:
- gencromfs <dir-path> <out-file>
- Where:
- <dir-path> is the path to the directory will be at the root of the
- new CROMFS file system image.
- <out-file> the name of the generated, output C file. This file must
- be compiled in order to generate the binary CROMFS file system
- image.
- All of these steps are automated in the apps/examples/cromfs/Makefile.
- Refer to that Makefile as an reference.
- Architecture
- ============
- The CROMFS file system is represented by an in-memory data structure. This
- structure is a "tree." At the root of the tree is a "volume node" that
- describes the overall operating system. Other entities within the file
- system are presented by other types of nodes: hard links, directories, and
- files. These nodes are all described in fs/cromfs/cromfs.h.
- In addition to general volume information, the volume node provides an
- offset to the the "root directory". The root directory, like all other
- CROMFS directories is simply a singly linked list of other nodes: hard link
- nodes, directory nodes, and files. This list is managed by "peer offsets":
- Each node in the directory contains an offset to its peer in the same
- directory. This directory list is terminated with a zero offset.
- The volume header lies at offset zero. Hence, any offset to a node or data
- block can be converted to an absolute address in the in-memory CROMFS image
- by simply adding that offset to the well-known address of the volume header.
- Each hard link, directory, and file node in the directory list includes
- such a "peer offset" to the next node in the list. Each node is followed
- by the NUL-terminated name of the node. Each node also holds an additional
- offset. Directory nodes contain a "child offset". That is, the offset to
- the first entry in another singly linked list of nodes comprising the sub-
- directory.
- Hard link nodes hold the "link offset" to the node which is the target of
- the link. The link offset may be an offset to another hard link node, to a
- directory, or to a file node. The directory link offset would refer the
- first node in singly linked directory list that represents the directory.
- File nodes provide file data. The file name string is followed by a
- variable length list of compressed data blocks. In this case each
- compressed data block begins with an LZF header as described in
- include/lzf.h.
- So, given this description, we could illustrate the sample CROMFS file
- system above with these nodes (where V=volume node, H=Hard link node,
- D=directory node, F=file node, D=Data block):
- V
- `- +- H: .
- |
- +- F: BaaBaaBlackSheep.txt
- | `- D,D,D,...D
- +- D: emptydir
- | |- H: .
- | `- H: ..
- +- F: JackSprat.txt
- | `- D,D,D,...D
- +- D: testdir1
- | |- H: .
- | |- H: ..
- | |- F: DingDongDell.txt
- | | `- D,D,D,...D
- | `- F: SeeSawMargorieDaw.txt
- | `- D,D,D,...D
- +- D: testdir2
- | |- H: .
- | |- H: ..
- | |- F: HickoryDickoryDock.txt
- | | `- D,D,D,...D
- | `- F: TheThreeLittlePigs.txt
- | `- D,D,D,...D
- +- D: testdir3
- |- H: .
- |- H: ..
- `- F: JackBeNimble.txt
- `- D,D,D,...D
- Where, for example:
- H: ..
- Represents a hard-link node with name ".."
- |
- +- D: testdir1
- | |- H: .
- Represents a directory node named "testdir1". The first node of the
- directory list is a hard link with name "."
- |
- +- F: JackSprat.txt
- | `- D,D,D,...D
- Represents f file node named "JackSprat.txt" and is followed by some
- sequence of compressed data blocks, D.
- Configuration
- =============
- To build the CROMFS file system, you would add the following to your
- configuration:
- 1. Enable LZF (The other LZF settings apply only to compression
- and, hence, have no impact on CROMFS which only decompresses):
- CONFIG_LIBC_LZF=y
- NOTE: This should be selected automatically when CONFIG_FS_CROMFS
- is enabled.
- 2. Enable the CROMFS file system:
- CONFIG_FS_CROMFS=y
- 3. Enable the apps/examples/cromfs example:
- CONFIG_EXAMPLES_CROMFS=y
- Or the apps/examples/elf example if you like:
- CONFIG_ELF=y
- # CONFIG_BINFMT_DISABLE is not set
- CONFIG_EXAMPLES_ELF=y
- CONFIG_EXAMPLES_ELF_CROMFS=y
- Or implement your own custom CROMFS file system that example as a
- guideline.
|