blob: 4ad500f85a4622b7c907a5436cf462528e29f11e [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.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>etc romfs &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="Thread Local Storage" href="thread_local_storage.html" />
<link rel="prev" title="Run time stack statistics" href="stackrecord.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"><a class="reference internal" href="../components/index.html">OS Components</a></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 current"><a class="reference internal" href="index.html">Guides</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="nfs.html">NFS Client How-To</a></li>
<li class="toctree-l2"><a class="reference internal" href="usbtrace.html">USB Device Trace</a></li>
<li class="toctree-l2"><a class="reference internal" href="simulator.html">Simulator</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemugdb.html">How to debug NuttX using QEMU and GDB</a></li>
<li class="toctree-l2"><a class="reference internal" href="rndis.html">How to use RNDIS</a></li>
<li class="toctree-l2"><a class="reference internal" href="drivers.html">Drivers</a></li>
<li class="toctree-l2"><a class="reference internal" href="tasktrace.html">Task Trace</a></li>
<li class="toctree-l2"><a class="reference internal" href="cpp_cmake.html">C++ Example using CMake</a></li>
<li class="toctree-l2"><a class="reference internal" href="pysimcoder.html">pysimCoder integration with NuttX</a></li>
<li class="toctree-l2"><a class="reference internal" href="customboards.html">Custom Boards How-To</a></li>
<li class="toctree-l2"><a class="reference internal" href="customapps.html">Custom Apps How-to</a></li>
<li class="toctree-l2"><a class="reference internal" href="citests.html">Running CI Test Locally</a></li>
<li class="toctree-l2"><a class="reference internal" href="zerolatencyinterrupts.html">High Performance: Zero Latency Interrupts, Maskable nested interrupts</a></li>
<li class="toctree-l2"><a class="reference internal" href="kasan.html">The Kernel Address Sanitizer (KASAN)</a></li>
<li class="toctree-l2"><a class="reference internal" href="nestedinterrupts.html">Nested Interrupts</a></li>
<li class="toctree-l2"><a class="reference internal" href="cortexmhardfaults.html">Analyzing Cortex-M Hardfaults</a></li>
<li class="toctree-l2"><a class="reference internal" href="coredump.html">Core Dump</a></li>
<li class="toctree-l2"><a class="reference internal" href="coresight.html">Coresight - HW Assisted Tracing on ARM</a></li>
<li class="toctree-l2"><a class="reference internal" href="gdbserver.html">gdbserver</a></li>
<li class="toctree-l2"><a class="reference internal" href="gdbwithpython.html">GDB with Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="ofloader.html">Open Flash Loader</a></li>
<li class="toctree-l2"><a class="reference internal" href="testingtcpip.html">Testing TCP/IP Network Stacks</a></li>
<li class="toctree-l2"><a class="reference internal" href="automounter.html">Auto-Mounter</a></li>
<li class="toctree-l2"><a class="reference internal" href="stm32nullpointer.html">STM32 Null Pointer Detection</a></li>
<li class="toctree-l2"><a class="reference internal" href="stm32ccm.html">STM32 CCM Allocator</a></li>
<li class="toctree-l2"><a class="reference internal" href="stackrecord.html">Run time stack statistics</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">etc romfs</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#configuration">Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="#start-up-scripts">Start up Scripts</a></li>
<li class="toctree-l3"><a class="reference internal" href="#customizing-start-up-scripts">Customizing Start up Scripts</a></li>
<li class="toctree-l3"><a class="reference internal" href="#customizing-romfs-image">Customizing ROMFS Image</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="thread_local_storage.html">Thread Local Storage</a></li>
</ul>
</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">Guides</a></li>
<li class="breadcrumb-item active">etc romfs</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/guides/etcromfs.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="etc-romfs">
<h1>etc romfs<a class="headerlink" href="#etc-romfs" title="Permalink to this heading"></a></h1>
<p>The ROMFS image is the contents of the <code class="docutils literal notranslate"><span class="pre">/etc</span></code> directory, including the start-up script
contains any command support by Nuttx, and other customized contents needed.</p>
<section id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this heading"></a></h2>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">CONFIG_NSH_ROMFS /* Mount a ROMFS file system at &quot;/etc&quot; and provide a system init script at</span>
<span class="go"> &quot;/etc/init.d.rc.sysinit&quot; and a startup script at &quot;etc/init.d/rcS&quot;. */</span>
<span class="go">CONFIG_ETC_ROMFSMOUNTPT /* The default mountpoint for the ROMFS volume is &quot;/etc&quot;, but that can be</span>
<span class="go"> changed with this setting. This must be a absolute path beginning with &#39;/&#39;</span>
<span class="go"> and enclosed in quotes. */</span>
<span class="go">CONFIG_ETC_ROMFSDEVNO /* This is the minor number of the ROMFS block device. The default is &#39;0&#39;</span>
<span class="go"> corresponding to &quot;/dev/ram0&quot;. */</span>
<span class="go">CONFIG_ETC_ROMFSSECTSIZE /* This is the sector size to use with the ROMFS volume. Since the default volume</span>
<span class="go"> is very small, this defaults to 64 but should be increased if the ROMFS volume</span>
<span class="go"> were to be become large. Any value selected must be a power of 2. */</span>
</pre></div>
</div>
<p>This capability also depends on:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">CONFIG_DISABLE_MOUNTPOINT /* If mount point support is disabled, then you cannot mount any file systems. */</span>
<span class="go">CONFIG_FS_ROMFS /* This option enables ROMFS file system support. */</span>
</pre></div>
</div>
</section>
<section id="start-up-scripts">
<h2>Start up Scripts<a class="headerlink" href="#start-up-scripts" title="Permalink to this heading"></a></h2>
<p><strong>Start-Up Script</strong>. The start-up script contains any command support by Nuttx
(i.e., that you see when you enter ‘nsh&gt; help’). The implementation that is provided is
intended to provide great flexibility for the use of Start-Up files.
This paragraph will discuss the general behavior when all of the
configuration options are set to the default values.</p>
<p>In this default case, enabling <code class="docutils literal notranslate"><span class="pre">CONFIG_ETC_ROMFS</span></code> will cause Nuttx to
behave as follows at Nuttx start-up time:</p>
<blockquote>
<div><ul>
<li><p>Nuttx will create a read-only RAM disk (a ROM disk), containing a tiny
ROMFS file system containing the following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>`--init.d/
`-- rcS
`-- rc.sysinit
</pre></div>
</div>
<p>Where <code class="docutils literal notranslate"><span class="pre">rcS</span></code> is the start-up script.
Where <code class="docutils literal notranslate"><span class="pre">rc.sysinit</span></code> is the system-init script.</p>
</li>
<li><p>Nuttx will then mount the ROMFS file system at <code class="docutils literal notranslate"><span class="pre">/etc</span></code>, resulting in:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>|--dev/
| `-- ram0
`--etc/
`--init.d/
`-- rcS
`-- rc.sysinit
</pre></div>
</div>
</li>
<li><p>By default, the contents of <code class="docutils literal notranslate"><span class="pre">rc.sysinit</span></code> script are:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># Create a RAMDISK and mount it at /tmp
mkrd -m 1 -s 512 1024
mkfatfs /dev/ram1
mount -t vfat /dev/ram1 /tmp
</pre></div>
</div>
</li>
<li><p>NSH will execute the script at <code class="docutils literal notranslate"><span class="pre">/etc/init.d/rc.sysinit</span></code> at system
init (before the first NSH prompt). After execution of the script,
the root FS will look like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>|--dev/
| |-- ram0
| `-- ram1
|--etc/
| `--init.d/
| `-- rcS
| `-- rc.sysinit
`--tmp/
</pre></div>
</div>
</li>
</ul>
</div></blockquote>
<p><strong>Example Configurations</strong>. Here are some configurations that have
<code class="docutils literal notranslate"><span class="pre">CONFIG_ETC_ROMFS=y</span></code> in the NuttX configuration file. They might
provide useful examples:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">boards/arm/stm32/hymini-stm32v/nsh2</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/arm/dm320/ntosd-dm320/nsh</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/sim/sim/sim/nsh</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/sim/sim/sim/nsh2</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/sim/sim/sim/nx</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/sim/sim/sim/nx11</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/sim/sim/sim/touchscreen</span></code></p></li>
</ul>
</div></blockquote>
<p>In most of these cases, the configuration sets up the <em>default</em>
<code class="docutils literal notranslate"><span class="pre">/etc/init.d/rc.sysinit</span></code> and <code class="docutils literal notranslate"><span class="pre">/etc/init.d/rcS</span></code> script. The default
script is here: <code class="docutils literal notranslate"><span class="pre">apps/nshlib/rc.sysinit.template</span></code> and
<code class="docutils literal notranslate"><span class="pre">apps/nshlib/rcS.template</span></code>. (The funny values in the rc.sysinit.template
like <code class="docutils literal notranslate"><span class="pre">XXXMKRDMINORXXX</span></code> get replaced via <code class="docutils literal notranslate"><span class="pre">sed</span></code> at build time). This
default configuration creates a ramdisk and mounts it at <code class="docutils literal notranslate"><span class="pre">/tmp</span></code> as
discussed above.</p>
</section>
<section id="customizing-start-up-scripts">
<h2>Customizing Start up Scripts<a class="headerlink" href="#customizing-start-up-scripts" title="Permalink to this heading"></a></h2>
<p>In order to modify the start-up behavior, there are three things to study:</p>
<blockquote>
<div><ol class="arabic">
<li><p><strong>Configuration Options.</strong> The additional <code class="docutils literal notranslate"><span class="pre">CONFIG_ETC_ROMFS</span></code>
configuration options discussed with <cite>Configuration</cite></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tools/mkromfsimg.sh</span></code> <strong>Script</strong>. The script
<code class="docutils literal notranslate"><span class="pre">tools/mkromfsimg.sh</span></code> creates <code class="docutils literal notranslate"><span class="pre">etc_romfs.c</span></code>. It is not
automatically executed. If you want to change the configuration
settings associated with creating and mounting the <code class="docutils literal notranslate"><span class="pre">/tmp</span></code>
directory, then it will be necessary to re-generate this header file
using the <code class="docutils literal notranslate"><span class="pre">tools/mkromfsimg.sh</span></code> script.</p>
<p>The behavior of this script depends upon several things:</p>
<ol class="arabic simple">
<li><p>The configuration settings then installed configuration.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">genromfs</span></code> tool(available from
<a class="reference external" href="http://romfs.sourceforge.net/">http://romfs.sourceforge.net</a>)
or included within the NuttX buildroot toolchain. There is also a
snapshot available in the NuttX tools repository
<a class="reference external" href="https://bitbucket.org/nuttx/tools/src/master/genromfs-0.5.2.tar.gz">here</a>.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">xxd</span></code> tool that is used to generate the C header files (xxd
is a normal part of a complete Linux or Cygwin installation,
usually as part of the <code class="docutils literal notranslate"><span class="pre">vi</span></code> package).</p></li>
<li><p>The file <code class="docutils literal notranslate"><span class="pre">include/arch/board/rc.sysinit.template</span></code> and
the file <code class="docutils literal notranslate"><span class="pre">include/arch/board/rcs.template</span></code></p></li>
</ol>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">rc.sysinit.template</span></code>. The file <code class="docutils literal notranslate"><span class="pre">apps/nshlib/rc.sysinit.template</span></code>
contains the general form of the <code class="docutils literal notranslate"><span class="pre">rc.sysinit</span></code> file; configured values
are plugged into this template file to produce the final <code class="docutils literal notranslate"><span class="pre">rc.sysinit</span></code> file.</p>
<p><code class="docutils literal notranslate"><span class="pre">rcS.template</span></code>. The file <code class="docutils literal notranslate"><span class="pre">apps/nshlib/rcS.template</span></code> contains the
general form of the <code class="docutils literal notranslate"><span class="pre">rcS</span></code> file; configured values are plugged into
this template file to produce the final <code class="docutils literal notranslate"><span class="pre">rcS</span></code> file.</p>
<p>To generate a custom <code class="docutils literal notranslate"><span class="pre">rc.sysinit</span></code> and <code class="docutils literal notranslate"><span class="pre">rcS</span></code> file a copy of
<code class="docutils literal notranslate"><span class="pre">rc.sysinit.template</span></code> and <code class="docutils literal notranslate"><span class="pre">rcS.template</span></code> needs to
be placed at <code class="docutils literal notranslate"><span class="pre">tools/</span></code> and changed according to the desired start-up
behaviour. Running <code class="docutils literal notranslate"><span class="pre">tools/mkromfsimg.h</span></code> creates <code class="docutils literal notranslate"><span class="pre">etc_romfs.c</span></code>
which needs to be copied to <code class="docutils literal notranslate"><span class="pre">arch/board/src</span></code> and compiled in Makefile</p>
</li>
</ol>
</div></blockquote>
<p>All of the startup-behavior is contained in <code class="docutils literal notranslate"><span class="pre">rc.sysinit.template</span></code> and
<code class="docutils literal notranslate"><span class="pre">rcS.template</span></code>. The role of <code class="docutils literal notranslate"><span class="pre">mkromfsimg.sh</span></code> script is to (1) apply
the specific configuration settings to <code class="docutils literal notranslate"><span class="pre">rc.sysinit.template</span></code> to create
the final <code class="docutils literal notranslate"><span class="pre">rc.sysinit</span></code>, and <code class="docutils literal notranslate"><span class="pre">rcS.template</span></code> to create the final <code class="docutils literal notranslate"><span class="pre">rcS</span></code>,
and (2) to generate the source file <code class="docutils literal notranslate"><span class="pre">etc_romfs.c</span></code> containing the ROMFS file
system image. To do this, <code class="docutils literal notranslate"><span class="pre">mkromfsimg.sh</span></code> uses two tools that must be
installed in your system:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">genromfs</span></code> tool that is used to generate the ROMFS file system
image.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">xxd</span></code> tool that is used to create the C header file.</p></li>
</ol>
</div></blockquote>
</section>
<section id="customizing-romfs-image">
<h2>Customizing ROMFS Image<a class="headerlink" href="#customizing-romfs-image" title="Permalink to this heading"></a></h2>
<p>The ROMFS image can be generated from the content in the corresponding
<code class="docutils literal notranslate"><span class="pre">board/arch/board/board/src/etc</span></code> directory, and added by Makefile.</p>
<p><strong>Example Configurations</strong>. Here are some configurations that have
<code class="docutils literal notranslate"><span class="pre">CONFIG_ETC_ROMFS=y</span></code> in the NuttX configuration file. They might
provide useful examples:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">boards/risc-v/bl808/ox64/src/etc</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/risc-v/qemu-rv/rv-virt/src/etc</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/risc-v/esp32c3/esp32c3-devkit/src/etc</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/risc-v/k230/canmv230/src/etc</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/risc-v/jh7110/star64/src/etc</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/arm64/rk3399/nanopi_m4/src/etc</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">boards/sim/sim/sim/src/etc</span></code></p></li>
</ul>
</div></blockquote>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="stackrecord.html" class="btn btn-neutral float-left" title="Run time stack statistics" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="thread_local_storage.html" class="btn btn-neutral float-right" title="Thread Local Storage" 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>