blob: 53db794c7c437c77a45ad3eca350c0737c453b9d [file] [log] [blame]
<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en">
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>CROMFS &mdash; NuttX latest documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../_static/css/theme.css" />
<link rel="stylesheet" type="text/css" href="../../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../../_static/custom.css" />
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/sphinx_highlight.js"></script>
<script src="../../_static/clipboard.min.js"></script>
<script src="../../_static/copybutton.js"></script>
<script src="../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="FAT" href="fat.html" />
<link rel="prev" title="BINFS" href="binfs.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../index.html" class="icon icon-home"> NuttX
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select onchange="javascript:location.href = this.value;">
<option value="../../../latest" selected="selected">latest</option>
<option value="../../../10.0.0" >10.0.0</option>
<option value="../../../10.0.1" >10.0.1</option>
<option value="../../../10.1.0" >10.1.0</option>
<option value="../../../10.2.0" >10.2.0</option>
<option value="../../../10.3.0" >10.3.0</option>
<option value="../../../11.0.0" >11.0.0</option>
<option value="../../../12.0.0" >12.0.0</option>
<option value="../../../12.1.0" >12.1.0</option>
<option value="../../../12.2.0" >12.2.0</option>
<option value="../../../12.2.1" >12.2.1</option>
<option value="../../../12.3.0" >12.3.0</option>
<option value="../../../12.4.0" >12.4.0</option>
<option value="../../../12.5.0" >12.5.0</option>
<option value="../../../12.5.1" >12.5.1</option>
<option value="../../../12.6.0" >12.6.0</option>
<option value="../../../12.7.0" >12.7.0</option>
<option value="../../../12.8.0" >12.8.0</option>
<option value="../../../12.9.0" >12.9.0</option>
<option value="../../../12.10.0" >12.10.0</option>
<option value="../../../12.11.0" >12.11.0</option>
</select>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../quickstart/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contributing/index.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../platforms/index.html">Supported Platforms</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">OS Components</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../binfmt.html">Binary Loader</a></li>
<li class="toctree-l2"><a class="reference internal" href="../drivers/index.html">Device Drivers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../nxflat.html">NXFLAT</a></li>
<li class="toctree-l2"><a class="reference internal" href="../nxgraphics/index.html">NX Graphics Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="../paging.html">On-Demand Paging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../audio/index.html">Audio Subsystem</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">NuttX File System</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="index.html#virtual-file-system-vfs">Virtual File System (VFS)</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html#file-systems">File systems</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="aio.html">Asynchronous I/O support</a></li>
<li class="toctree-l4"><a class="reference internal" href="binfs.html">BINFS</a></li>
<li class="toctree-l4 current"><a class="current reference internal" href="#">CROMFS</a><ul>
<li class="toctree-l5"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l5"><a class="reference internal" href="#gencromfs">gencromfs</a></li>
<li class="toctree-l5"><a class="reference internal" href="#architecture">Architecture</a></li>
<li class="toctree-l5"><a class="reference internal" href="#configuration">Configuration</a></li>
</ul>
</li>
<li class="toctree-l4"><a class="reference internal" href="fat.html">FAT</a></li>
<li class="toctree-l4"><a class="reference internal" href="hostfs.html">Host File System</a></li>
<li class="toctree-l4"><a class="reference internal" href="littlefs.html">LITTLEFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="mmap.html">File mapping emulation (mmap)</a></li>
<li class="toctree-l4"><a class="reference internal" href="mnemofs.html">MNEMOFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="nfs.html">NFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="nxffs.html">NXFFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="partition.html">Partition Table</a></li>
<li class="toctree-l4"><a class="reference internal" href="procfs.html">PROCFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="romfs.html">ROMFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="rpmsgfs.html">RPMSG File System</a></li>
<li class="toctree-l4"><a class="reference internal" href="smartfs.html">SMARTFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="shmfs.html">Shared Memory File System</a></li>
<li class="toctree-l4"><a class="reference internal" href="spiffs.html">SPIFFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="tmpfs.html">TMPFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="unionfs.html">Union File System</a></li>
<li class="toctree-l4"><a class="reference internal" href="userfs.html">User file system</a></li>
<li class="toctree-l4"><a class="reference internal" href="zipfs.html">ZipFS</a></li>
<li class="toctree-l4"><a class="reference internal" href="inotify.html">Inotify</a></li>
<li class="toctree-l4"><a class="reference internal" href="nuttxfs.html">Nuttx FS</a></li>
<li class="toctree-l4"><a class="reference internal" href="nxflat.html">NuttX FLAT Binary Format (NXFLAT)</a></li>
<li class="toctree-l4"><a class="reference internal" href="pseudofs.html">Pseudo File System</a></li>
<li class="toctree-l4"><a class="reference internal" href="special_files_dev_num.html">Special Files and Device Numbers</a></li>
<li class="toctree-l4"><a class="reference internal" href="v9fs.html">V9FS</a></li>
<li class="toctree-l4"><a class="reference internal" href="v9fs.html#adding-v9fs-to-the-nuttx-configuration">Adding V9FS to the NuttX Configuration</a></li>
<li class="toctree-l4"><a class="reference internal" href="v9fs.html#nfs-mount-command">NFS Mount Command</a></li>
<li class="toctree-l4"><a class="reference internal" href="index.html#fs-categories">FS Categories</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../libs/index.html">NuttX libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="../net/index.html">Network Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mm/index.html">Memory Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="../syscall.html">Syscall Layer</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tools/index.html"><code class="docutils literal notranslate"><span class="pre">/tools</span></code> Host Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../arch/index.html">Architecture-Specific Code</a></li>
<li class="toctree-l2"><a class="reference internal" href="../boards.html">Boards Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../cmake.html">CMake Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../openamp.html">OpenAMP Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../video.html">Video Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="../crypto.html">Crypto API Subsystem</a></li>
<li class="toctree-l2"><a class="reference internal" href="../wireless.html">Wireless Subsystem</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../applications/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../implementation/index.html">Implementation Details</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../logos/index.html">NuttX Logos</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">NuttX</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../index.html">OS Components</a></li>
<li class="breadcrumb-item"><a href="index.html">NuttX File System</a></li>
<li class="breadcrumb-item active">CROMFS</li>
<li class="wy-breadcrumbs-aside">
<a href="../../_sources/components/filesystem/cromfs.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="cromfs">
<h1>CROMFS<a class="headerlink" href="#cromfs" title="Permalink to this heading"></a></h1>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this heading"></a></h2>
<p>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).</p>
<p>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).</p>
<p>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.</p>
<p>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!</p>
<p>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:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ 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
</pre></div>
</div>
<p>When built into NuttX and deployed on a target, it looks like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>NuttShell (NSH) NuttX-7.24
nsh&gt; mount -t cromfs /mnt/cromfs
nsh&gt; 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&gt;
</pre></div>
</div>
<p>Everything I have tried works: examining directories, catting files, etc.
The “.” and “..” hard links also work:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>nsh&gt; cd /mnt/cromfs
nsh&gt; cat emptydir/../testdir1/DingDongDell.txt
Ding, dong, bell,
Pussy&#39;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&#39;s barn.
nsh&gt;
</pre></div>
</div>
</section>
<section id="gencromfs">
<h2>gencromfs<a class="headerlink" href="#gencromfs" title="Permalink to this heading"></a></h2>
<p>The genromfs program can be found in tools/. It is a single C file called
gencromfs.c. It can be built in this way:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd tools
make -f Makefile.host gencromfs
</pre></div>
</div>
<p>The genromfs tool used to generate CROMFS file system images. Usage is
simple:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>gencromfs &lt;dir-path&gt; &lt;out-file&gt;
</pre></div>
</div>
<p>Where:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&lt;dir-path&gt; is the path to the directory will be at the root of the
new CROMFS file system image.
&lt;out-file&gt; the name of the generated, output C file. This file must
be compiled in order to generate the binary CROMFS file system
image.
</pre></div>
</div>
<p>All of these steps are automated in the apps/examples/cromfs/Makefile.
Refer to that Makefile as an reference.</p>
</section>
<section id="architecture">
<h2>Architecture<a class="headerlink" href="#architecture" title="Permalink to this heading"></a></h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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
</pre></div>
</div>
<p>Where, for example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>H: ..
Represents a hard-link node with name &quot;..&quot;
|
+- D: testdir1
| |- H: .
Represents a directory node named &quot;testdir1&quot;. The first node of the
directory list is a hard link with name &quot;.&quot;
|
+- F: JackSprat.txt
| `- D,D,D,...D
Represents f file node named &quot;JackSprat.txt&quot; and is followed by some
sequence of compressed data blocks, D.
</pre></div>
</div>
</section>
<section id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this heading"></a></h2>
<p>To build the CROMFS file system, you would add the following to your
configuration:</p>
<ol class="arabic">
<li><p>Enable LZF (The other LZF settings apply only to compression
and, hence, have no impact on CROMFS which only decompresses):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>CONFIG_LIBC_LZF=y
</pre></div>
</div>
<p>NOTE: This should be selected automatically when CONFIG_FS_CROMFS
is enabled.</p>
</li>
<li><p>Enable the CROMFS file system:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>CONFIG_FS_CROMFS=y
</pre></div>
</div>
</li>
<li><p>Enable the apps/examples/cromfs example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>CONFIG_EXAMPLES_CROMFS=y
</pre></div>
</div>
<p>Or the apps/examples/elf example if you like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>CONFIG_ELF=y
# CONFIG_BINFMT_DISABLE is not set
CONFIG_EXAMPLES_ELF=y
CONFIG_EXAMPLES_ELF_CROMFS=y
</pre></div>
</div>
<p>Or implement your own custom CROMFS file system that example as a
guideline.</p>
</li>
</ol>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="binfs.html" class="btn btn-neutral float-left" title="BINFS" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="fat.html" class="btn btn-neutral float-right" title="FAT" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2023, The Apache Software Foundation.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>