blob: a60548e32c670d90195951b1f9a69f7a15fec730 [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="viewport" content="width=device-width, initial-scale=1.0">
<title>Directory Structure &mdash; NuttX latest documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/segment.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/menu.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/tabs.css" type="text/css" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script type="text/javascript" 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="Build and Make Details" href="build_and_make.html" />
<link rel="prev" title="Debugging" href="debugging.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
<img src="../_static/NuttX.png" class="logo" alt="Logo"/>
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select>
<option value="latest" selected="selected">latest</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" />
<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="main navigation">
<p class="caption"><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="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Getting Started</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
<li class="toctree-l2"><a class="reference internal" href="install.html">Installing</a></li>
<li class="toctree-l2"><a class="reference internal" href="compiling.html">Compiling</a></li>
<li class="toctree-l2"><a class="reference internal" href="running.html">Running</a></li>
<li class="toctree-l2"><a class="reference internal" href="configuring.html">Configuring</a></li>
<li class="toctree-l2"><a class="reference internal" href="debugging.html">Debugging</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Directory Structure</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-documentation"><code class="docutils literal notranslate"><span class="pre">nuttx/Documentation</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-arch"><code class="docutils literal notranslate"><span class="pre">nuttx/arch</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#subdirectory-structure">Subdirectory Structure</a></li>
<li class="toctree-l4"><a class="reference internal" href="#summary-of-files">Summary of Files</a></li>
<li class="toctree-l4"><a class="reference internal" href="#supported-architectures">Supported Architectures</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-binfmt"><code class="docutils literal notranslate"><span class="pre">nuttx/binfmt</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-audio"><code class="docutils literal notranslate"><span class="pre">nuttx/audio</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-boards"><code class="docutils literal notranslate"><span class="pre">nuttx/boards</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#id2">Subdirectory Structure</a></li>
<li class="toctree-l4"><a class="reference internal" href="#id3">Summary of Files</a></li>
<li class="toctree-l4"><a class="reference internal" href="#supported-boards">Supported Boards</a></li>
<li class="toctree-l4"><a class="reference internal" href="#adding-a-new-board-configuration">Adding a New Board Configuration</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-crypto"><code class="docutils literal notranslate"><span class="pre">nuttx/crypto</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-drivers"><code class="docutils literal notranslate"><span class="pre">nuttx/drivers</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-fs"><code class="docutils literal notranslate"><span class="pre">nuttx/fs</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-graphics"><code class="docutils literal notranslate"><span class="pre">nuttx/graphics</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-include"><code class="docutils literal notranslate"><span class="pre">nuttx/include</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx"><code class="docutils literal notranslate"><span class="pre">nuttx</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-libs-libc"><code class="docutils literal notranslate"><span class="pre">nuttx/libs/libc</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-libs-libxx"><code class="docutils literal notranslate"><span class="pre">nuttx/libs/libxx</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-mm"><code class="docutils literal notranslate"><span class="pre">nuttx/mm</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-net"><code class="docutils literal notranslate"><span class="pre">nuttx/net</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-sched"><code class="docutils literal notranslate"><span class="pre">nuttx/sched</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-syscall"><code class="docutils literal notranslate"><span class="pre">nuttx/syscall</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-tools"><code class="docutils literal notranslate"><span class="pre">nuttx/tools</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-wireless"><code class="docutils literal notranslate"><span class="pre">nuttx/wireless</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#nuttx-makefile"><code class="docutils literal notranslate"><span class="pre">nuttx/Makefile</span></code></a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="build_and_make.html">Build and Make Details</a></li>
</ul>
</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="../boards/index.html">Supported Boards</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="../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Releases</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="../glossary.html">Glossary</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<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="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
<li><a href="index.html">Getting Started</a> &raquo;</li>
<li>Directory Structure</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/quickstart/organization.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">
<div class="section" id="directory-structure">
<span id="organization"></span><h1>Directory Structure<a class="headerlink" href="#directory-structure" title="Permalink to this headline"></a></h1>
<p>This is included for reference, and it’s not necessary to know
all the details at first.</p>
<p>The general directory layout for NuttX is
very similar to the directory structure of the Linux kernel – at
least at the most superficial layers. At the top level is the main
makefile and a series of sub-directories identified below and
discussed in the following paragraphs:</p>
<p><strong>Configuration Files</strong>. The NuttX configuration consists of logic
in processor architecture directories, <em>chip/SoC</em> directories, and
board configuration directories. The complete configuration is
specified by several settings in the NuttX configuration file.</p>
<ul>
<li><p><em>Processor architecture specific files</em>. These are the files
contained in the <code class="docutils literal notranslate"><span class="pre">arch/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code> directory and
are discussed in a paragraph
<a class="reference external" href="#archdirectorystructure">below</a>. As an example, all ARM
processor architectures are provided under the <code class="docutils literal notranslate"><span class="pre">arch/arm/</span></code>
directory which is selected with the <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH=&quot;arm&quot;</span></code>
configuration option.</p>
<p>Variants of the processor architecture may be provided in
sub-directories of the Extending this example, the ARMv7-M ARM
family is supported by logic in <code class="docutils literal notranslate"><span class="pre">arch/arm/include/armv7-m</span></code>
and <code class="docutils literal notranslate"><span class="pre">arch/arm/src/armv7-m</span></code> directories which are selected by
the <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_CORTEXM3=y</span></code>, <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_CORTEXM4=y</span></code>, or
<code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_CORTEXM7=y</span></code> configuration options</p>
</li>
<li><p><em>Chip/SoC specific files</em>. Each processor architecture is
embedded in a <em>System-on-a-Chip</em> (SoC) architecture. The full
SoC architecture includes the processor architecture plus
chip-specific interrupt logic, clocking logic, general purpose
I/O (GPIO) logic, and specialized, internal peripherals (such
as UARTs, USB, etc.).</p>
<p>These chip-specific files are contained within chip-specific
sub-directories also under the <code class="docutils literal notranslate"><span class="pre">arch/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code>
directory and are selected via the <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_CHIP</span></code>
selection.</p>
<p>As an example, the STMicro STM32 SoC architecture is based on
the ARMv7-M processor and is supported by logic in the
<code class="docutils literal notranslate"><span class="pre">arch/arm/include/stm32</span></code> and <code class="docutils literal notranslate"><span class="pre">arch/arm/src/stm32</span></code>
directories which are selected with the
<code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_CHIP=&quot;stm32&quot;</span></code> configuration setting.</p>
</li>
<li><p><em>Board specific configurations</em>. In order to be usable, the
chip must be contained in a board environment. The board
configuration defines additional properties of the board
including such things as peripheral LEDs, external peripherals
(such as networks, USB, etc.).</p>
<p>These board-specific configuration files can be found in the
<code class="docutils literal notranslate"><span class="pre">boards/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code><em>&lt;chip-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code><em>&lt;board-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code>
sub-directories and are discussed in a paragraph
<a class="reference external" href="#boardsdirectorystructure">below</a>.</p>
<p>The directory <code class="docutils literal notranslate"><span class="pre">boards/arm/stm32/stm32f4disovery/</span></code>, as an
example, holds board-specific logic for the STM32F4 Discovery
board and is selected via the
<code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_BOARD=&quot;stm32f4discovery&quot;</span></code> configuration setting.</p>
</li>
</ul>
<div class="section" id="nuttx-documentation">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/Documentation</span></code><a class="headerlink" href="#nuttx-documentation" title="Permalink to this headline"></a></h2>
<p>This directory holds the NuttX documentation. It’s made with
the <a class="reference external" href="https://www.sphinx-doc.org">Sphinx documentation system</a>. See the
README.md file for information on how to build it.</p>
</div>
<div class="section" id="nuttx-arch">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/arch</span></code><a class="headerlink" href="#nuttx-arch" title="Permalink to this headline"></a></h2>
<div class="section" id="subdirectory-structure">
<h3>Subdirectory Structure<a class="headerlink" href="#subdirectory-structure" title="Permalink to this headline"></a></h3>
<p>This directory contains several sub-directories, each containing
architecture-specific logic. The task of porting NuttX to a new
processor consists of add a new subdirectory under <code class="docutils literal notranslate"><span class="pre">arch/</span></code>
containing logic specific to the new architecture. The complete
board port in is defined by the architecture-specific code in this
directory (plus the board-specific configurations in the
<code class="docutils literal notranslate"><span class="pre">config/</span></code> subdirectory). Each architecture must provide a
subdirectory, <em>&lt;arch-name&gt;</em> under <code class="docutils literal notranslate"><span class="pre">arch/</span></code> with the following
characteristics:</p>
</div>
<div class="section" id="summary-of-files">
<h3>Summary of Files<a class="headerlink" href="#summary-of-files" title="Permalink to this headline"></a></h3>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">include/</span></code><em>&lt;chip-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code> This sub-directory contains
chip-specific header files.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">include/arch.h</span></code>: This is a hook for any architecture
specific definitions that may be needed by the system. It is
included by <code class="docutils literal notranslate"><span class="pre">include/nuttx/arch.h</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">include/types.h</span></code>: This provides
architecture/toolchain-specific definitions for standard types.
This file should <code class="docutils literal notranslate"><span class="pre">typedef</span></code>:</p>
<p>and if the architecture supports 24- or 64-bit integers</p>
<p>NOTE that these type names have a leading underscore character.
This file will be included(indirectly) by include/stdint.h and
typedef’ed to the final name without the underscore character.
This roundabout way of doings things allows the stdint.h to be
removed from the include/ directory in the event that the user
prefers to use the definitions provided by their toolchain
header files</p>
<p>And finally</p>
<p>Must be defined to the be the size required to hold the
interrupt enable/disable state.</p>
<p>This file will be included by include/sys/types.h and be made
available to all files.</p>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">include/irq.h</span></code>: This file needs to define some architecture
specific functions (usually inline if the compiler supports
inlining) and some structures. These include:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">xcptcontext</span></code>: This structures represents the saved
context of a thread.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">irqstate_t</span> <span class="pre">up_irq_save(void)</span></code>: Used to disable all
interrupts. In the case of multi-CPU platforms, this
function disables interrupts on CPUs.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">up_irq_restore(irqstate_t</span> <span class="pre">flags)</span></code>: Used to restore
interrupt enables to the same state as before
<code class="docutils literal notranslate"><span class="pre">up_irq_save()</span></code> was called.</p></li>
</ul>
<p>This file must also define <code class="docutils literal notranslate"><span class="pre">NR_IRQS</span></code>, the total number of
IRQs supported by the board.</p>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">include/syscall.h</span></code>: This file needs to define some
architecture specific functions (usually inline if the compiler
supports inlining) to support software interrupts or
<em>syscall</em>s that can be used all from user-mode applications
into kernel-mode NuttX functions. This directory must always be
provided to prevent compilation errors. However, it need only
contain valid function declarations if the architecture
supports the <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_PROTECTED</span></code> or
<code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_KERNEL</span></code>configurations.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">uintptr_t</span> <span class="pre">sys_call0(unsigned</span> <span class="pre">int</span> <span class="pre">nbr)</span></code>: <code class="docutils literal notranslate"><span class="pre">nbr</span></code> is one of
the system call numbers that can be found in
<code class="docutils literal notranslate"><span class="pre">include/sys/syscall.h</span></code>. This function will perform a
system call with no (additional) parameters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">uintptr_t</span> <span class="pre">sys_call1(unsigned</span> <span class="pre">int</span> <span class="pre">nbr,</span> <span class="pre">uintptr_t</span> <span class="pre">parm1)</span></code>:
<code class="docutils literal notranslate"><span class="pre">nbr</span></code> is one of the system call numbers that can be found
in <code class="docutils literal notranslate"><span class="pre">include/sys/syscall.h</span></code>. This function will perform a
system call with one (additional) parameter.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">uintptr_t</span> <span class="pre">sys_call2(unsigned</span> <span class="pre">int</span> <span class="pre">nbr,</span> <span class="pre">uintptr_t</span> <span class="pre">parm1,</span> <span class="pre">uintptr_t</span> <span class="pre">parm2)</span></code>:
<code class="docutils literal notranslate"><span class="pre">nbr</span></code> is one of the system call numbers that can be found
in <code class="docutils literal notranslate"><span class="pre">include/sys/syscall.h</span></code>. This function will perform a
system call with two (additional) parameters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">uintptr_t</span> <span class="pre">sys_call3(unsigned</span> <span class="pre">int</span> <span class="pre">nbr,</span> <span class="pre">uintptr_t</span> <span class="pre">parm1,</span> <span class="pre">uintptr_t</span> <span class="pre">parm2,</span> <span class="pre">uintptr_t</span> <span class="pre">parm3)</span></code>:
<code class="docutils literal notranslate"><span class="pre">nbr</span></code> is one of the system call numbers that can be found
in <code class="docutils literal notranslate"><span class="pre">include/sys/syscall.h</span></code>. This function will perform a
system call with three (additional) parameters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">uintptr_t</span> <span class="pre">sys_call4(unsigned</span> <span class="pre">int</span> <span class="pre">nbr,</span> <span class="pre">uintptr_t</span> <span class="pre">parm1,</span> <span class="pre">uintptr_t</span> <span class="pre">parm2,</span> <span class="pre">uintptr_t</span> <span class="pre">parm3,</span> <span class="pre">uintptr_t</span> <span class="pre">parm4)</span></code>:
<code class="docutils literal notranslate"><span class="pre">nbr</span></code> is one of the system call numbers that can be found
in <code class="docutils literal notranslate"><span class="pre">include/sys/syscall.h</span></code>. This function will perform a
system call with four (additional) parameters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">uintptr_t</span> <span class="pre">sys_call5(unsigned</span> <span class="pre">int</span> <span class="pre">nbr,</span> <span class="pre">uintptr_t</span> <span class="pre">parm1,</span> <span class="pre">uintptr_t</span> <span class="pre">parm2,</span> <span class="pre">uintptr_t</span> <span class="pre">parm3,</span> <span class="pre">uintptr_t</span> <span class="pre">parm4,</span> <span class="pre">uintptr_t</span> <span class="pre">parm5)</span></code>:
<code class="docutils literal notranslate"><span class="pre">nbr</span></code> is one of the system call numbers that can be found
in <code class="docutils literal notranslate"><span class="pre">include/sys/syscall.h</span></code>. This function will perform a
system call with five (additional) parameters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">uintptr_t</span> <span class="pre">sys_call6(unsigned</span> <span class="pre">int</span> <span class="pre">nbr,</span> <span class="pre">uintptr_t</span> <span class="pre">parm1,</span> <span class="pre">uintptr_t</span> <span class="pre">parm2,</span> <span class="pre">uintptr_t</span> <span class="pre">parm3,</span> <span class="pre">uintptr_t</span> <span class="pre">parm4,</span> <span class="pre">uintptr_t</span> <span class="pre">parm5,</span> <span class="pre">uintptr_t</span> <span class="pre">parm6)</span></code>:
<code class="docutils literal notranslate"><span class="pre">nbr</span></code> is one of the system call numbers that can be found
in <code class="docutils literal notranslate"><span class="pre">include/sys/syscall.h</span></code>. This function will perform a
system call with six (additional) parameters.</p></li>
</ul>
<p>This file must also define <code class="docutils literal notranslate"><span class="pre">NR_IRQS</span></code>, the total number of
IRQs supported by the board.</p>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">src/</span></code><em>&lt;chip-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code> This sub-directory contains
chip-specific source files.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">src/Makefile</span></code>: This makefile will be executed to build the
targets <code class="docutils literal notranslate"><span class="pre">src/libup.a</span></code> and <code class="docutils literal notranslate"><span class="pre">src/up_head.o</span></code>. The
<code class="docutils literal notranslate"><span class="pre">up_head.o</span></code> file holds the entry point into the system
(power-on reset entry point, for example). It will be used in
the final link with <code class="docutils literal notranslate"><span class="pre">libup.a</span></code> and other system archives to
generate the final executable.</p></li>
<li><p><em>(architecture-specific source files)</em>. The file
<code class="docutils literal notranslate"><span class="pre">include/nuttx/arch.h</span></code> identifies all of the APIs that must
be provided by the architecture specific logic. (It also
includes <code class="docutils literal notranslate"><span class="pre">arch/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/arch.h</span></code> as described
above).</p></li>
</ul>
</div>
<div class="section" id="supported-architectures">
<h3>Supported Architectures<a class="headerlink" href="#supported-architectures" title="Permalink to this headline"></a></h3>
<p><strong>Architecture- and Chip-Specific Directories</strong>. All processor
architecture-specific directories are maintained in
sub-directories of the <code class="docutils literal notranslate"><span class="pre">arch/</span></code> directory. Different chips or
SoC’s may implement the same processor core. Chip-specific logic
can be found in sub-directories under the architecture directory.
Current architecture/chip directories are summarized below:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">arch/sim</span></code>: A user-mode port of NuttX to the x86 Linux or
Cygwin platform is available. The purpose of this port is
primarily to support OS feature development. This port does not
support interrupts or a real timer (and hence no round robin
scheduler) Otherwise, it is complete.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/arm</span></code>: This directory holds common ARM architectures.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/avr</span></code>: This directory holds common AVR and AVR32
architectures.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/mips</span></code>: This directory holds common MIPS architectures.
This include PIC32MX and PIC32MZ.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/misoc</span></code>: This directory supports the Misoc LM3
architecture.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/or1K</span></code>: This directory supports the OpenRISC mor1kx
architecture.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/renesas</span></code>: This directory is the home for various
Renesas architectures, currently only the M16C and vererable
SuperH-1 architectures.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/risc-v</span></code>: This directory supports the RISC-V NR5
architecture.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/xtensa</span></code>: This directory supports the Xtensa LX6
architecture as used by the ESP32.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/z16f</span></code>: Zilog z16f Microcontroller.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arch/z80</span></code>: This directory holds 8-bit ZiLOG architectures.
At present, this includes the Zilog z80, ez80Acclaim! and
z8Encore! Microcontrollers.</p></li>
</ul>
</div>
</div>
<div class="section" id="nuttx-binfmt">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/binfmt</span></code><a class="headerlink" href="#nuttx-binfmt" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">binfmt/</span></code> subdirectory contains logic for loading binaries
in the file system into memory in a form that can be used to
execute them.</p>
</div>
<div class="section" id="nuttx-audio">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/audio</span></code><a class="headerlink" href="#nuttx-audio" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">audio/</span></code> subdirectory contains the NuttX audio sub-system.</p>
</div>
<div class="section" id="nuttx-boards">
<span id="id1"></span><h2><code class="docutils literal notranslate"><span class="pre">nuttx/boards</span></code><a class="headerlink" href="#nuttx-boards" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">boards/</span></code> subdirectory contains custom logic and board
configuration data for each board. These board-specific
configurations plus the architecture-specific configurations in
the <code class="docutils literal notranslate"><span class="pre">arch/</span></code> subdirectory complete define a customized port of
NuttX.</p>
<div class="section" id="id2">
<h3>Subdirectory Structure<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">boards/</span></code> directory contains board specific configuration
files. Each board must provide a sub-directory &lt;board-name&gt; under
<code class="docutils literal notranslate"><span class="pre">boards/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code>&gt;<em>&lt;chip-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code> with the
following characteristics:</p>
</div>
<div class="section" id="id3">
<h3>Summary of Files<a class="headerlink" href="#id3" title="Permalink to this headline"></a></h3>
<p><strong>Board Specific Logic</strong></p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">include/</span></code>: This directory contains board specific header
files. This directory will be linked as <code class="docutils literal notranslate"><span class="pre">include/arch/board</span></code>
at configuration time and can be included via
<code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&lt;arch/board/header.h&gt;</span></code>. These header file can only
be included by files in <code class="docutils literal notranslate"><span class="pre">arch/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/include/</span></code>
and <code class="docutils literal notranslate"><span class="pre">arch/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/src/</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">src/</span></code>: This directory contains board specific drivers. This
directory will be linked as
<em>&lt;config&gt;</em><code class="docutils literal notranslate"><span class="pre">/arch/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/src/board</span></code> at
configuration time and will be integrated into the build
system.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">src/Makefile</span></code>: This makefile will be invoked to build the
board specific drivers. It must support the following targets:
<code class="docutils literal notranslate"><span class="pre">libext$(LIBEXT)</span></code>, <code class="docutils literal notranslate"><span class="pre">clean</span></code>, and <code class="docutils literal notranslate"><span class="pre">distclean</span></code>.</p></li>
</ul>
<p><strong>Board Specific Configuration Sub-Directories</strong></p>
<p>The
<code class="docutils literal notranslate"><span class="pre">boards/</span></code><em>&lt;arch-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code><em>&lt;chip-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/</span></code><em>&lt;board-name&gt;</em><code class="docutils literal notranslate"><span class="pre">/configs</span></code>
sub-directory holds all of the files that are necessary to
configure NuttX for the particular board. A board may have various
different configurations using the common source files. Each board
configuration is described by two files: <code class="docutils literal notranslate"><span class="pre">Make.defs</span></code> and
<code class="docutils literal notranslate"><span class="pre">defconfig</span></code>. Typically, each set of configuration files is
retained in a separate configuration sub-directory
(<em>&lt;config1-dir&gt;</em>, <em>&lt;config2-dir&gt;</em>, .. in the above diagram).</p>
<p>NOTE: That the <code class="docutils literal notranslate"><span class="pre">Make.defs</span></code> file may reside in one of two
locations: There may be a unique Make.defs file for each
configuration in the configuration directory <em>OR</em> if that file is
absent, there may be a common board <code class="docutils literal notranslate"><span class="pre">Make.defs</span></code> file in the
<code class="docutils literal notranslate"><span class="pre">/scripts</span></code> directory. The <code class="docutils literal notranslate"><span class="pre">Make.defs</span></code> file in the
configuration takes precedence if it is present.</p>
<p>The procedure for configuring NuttX is described
<a class="reference external" href="#configuringnuttx">below</a>, This paragraph will describe the
contents of these configuration files.</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">Make.defs</span></code>: This makefile fragment provides architecture and
tool-specific build options. It will be included by all other
makefiles in the build (once it is installed). This make
fragment should define:</p>
<ul class="simple">
<li><p>Tools: <code class="docutils literal notranslate"><span class="pre">CC</span></code>, <code class="docutils literal notranslate"><span class="pre">LD</span></code>, <code class="docutils literal notranslate"><span class="pre">AR</span></code>, <code class="docutils literal notranslate"><span class="pre">NM</span></code>, <code class="docutils literal notranslate"><span class="pre">OBJCOPY</span></code>,
<code class="docutils literal notranslate"><span class="pre">OBJDUMP</span></code></p></li>
<li><p>Tool options: <code class="docutils literal notranslate"><span class="pre">CFLAGS</span></code>, <code class="docutils literal notranslate"><span class="pre">LDFLAGS</span></code></p></li>
</ul>
<p>When this makefile fragment runs, it will be passed <code class="docutils literal notranslate"><span class="pre">TOPDIR</span></code>
which is the path to the root directory of the build. This
makefile fragment should include:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">$(TOPDIR)/.config</span></code> : Nuttx configuration</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$(TOPDIR)/tools/Config.mk</span></code> : Common definitions</p></li>
</ul>
<p>Definitions in the <code class="docutils literal notranslate"><span class="pre">Make.defs</span></code> file probably depend on some
of the settings in the .<code class="docutils literal notranslate"><span class="pre">config</span></code> file. For example, the
<code class="docutils literal notranslate"><span class="pre">CFLAGS</span></code> will most likely be different if
<code class="docutils literal notranslate"><span class="pre">CONFIG_DEBUG_FEATURES=y</span></code>.</p>
<p>The included <code class="docutils literal notranslate"><span class="pre">tools/Config.mk</span></code> file contains additional
definitions that may be overridden in the architecture-specific
Make.defs file as necessary:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">COMPILE</span></code>, <code class="docutils literal notranslate"><span class="pre">ASSEMBLE</span></code>, <code class="docutils literal notranslate"><span class="pre">ARCHIVE</span></code>, <code class="docutils literal notranslate"><span class="pre">CLEAN</span></code>, and
<code class="docutils literal notranslate"><span class="pre">MKDEP</span></code> macros</p></li>
</ul>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">defconfig</span></code>: This is a configuration file similar to the
Linux configuration file. In contains variable/value pairs
like:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">CONFIG_VARIABLE</span></code>=value</p></li>
</ul>
<p>This configuration file will be used at build time:</p>
<ol class="arabic simple">
<li><p>As a makefile fragment included in other makefiles, and</p></li>
<li><p>to generate <code class="docutils literal notranslate"><span class="pre">include/nuttx/config.h</span></code> which is included by
most C files in the system.</p></li>
</ol>
</li>
</ul>
</div>
<div class="section" id="supported-boards">
<h3>Supported Boards<a class="headerlink" href="#supported-boards" title="Permalink to this headline"></a></h3>
<p>All of the specific boards supported by NuttX are identified in
the
<a class="reference external" href="https://bitbucket.org/nuttx/nuttx/src/master/boards/README.txt">README.txt</a>
file.</p>
</div>
<div class="section" id="adding-a-new-board-configuration">
<h3>Adding a New Board Configuration<a class="headerlink" href="#adding-a-new-board-configuration" title="Permalink to this headline"></a></h3>
<p>Okay, so you have created a new board configuration directory.
Now, how do you hook this board into the configuration system so
that you can select with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">menuconfig</span></code>?</p>
<p>You will need modify the file <code class="docutils literal notranslate"><span class="pre">boards/Kconfig</span></code>. Let’s look at
the STM32F4-Discovery configuration in the <code class="docutils literal notranslate"><span class="pre">Kconfig</span></code> file and
see how we would add a new board directory to the configuration.
For this configuration let’s say that you new board resides in the
directory <code class="docutils literal notranslate"><span class="pre">boards/myarch/mychip/myboard</span></code>; It uses an MCU
selected with <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_CHIP_MYMCU</span></code>; and you want the board
to be selected with <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_BOARD_MYBOARD</span></code>. Then here is
how you can clone the STM32F4-Discovery configuration in
<code class="docutils literal notranslate"><span class="pre">boards/Kconfig</span></code> to support your new board configuration.</p>
<p>In <code class="docutils literal notranslate"><span class="pre">boards/Kconfig</span></code> for the stm32f4-discovery, you will see a
configuration definition like this:</p>
<p>The above selects the STM32F4-Discovery board. The <code class="docutils literal notranslate"><span class="pre">select</span></code>
lines say that the board has both LEDs and buttons and that the
board can generate interrupts from the button presses. You can
just copy the above configuration definition to a new location
(notice that they the configurations are in alphabetical order).
Then you should edit the configuration to support your board. The
final configuration definition might look something like:</p>
<p>Later in the <code class="docutils literal notranslate"><span class="pre">boards/Kconfig</span></code> file, you will see a long, long
string configuration with lots of defaults like this:</p>
<p>This logic will assign string value to a configuration variable
called <code class="docutils literal notranslate"><span class="pre">CONFIG_ARCH_BOARD</span></code> that will name the directory where
the board-specific files reside. In our case, these files reside
in <code class="docutils literal notranslate"><span class="pre">boards/myarch/mychip/myboard</span></code> and we add the following to
the long list of defaults (again in alphabetical order):</p>
<p>Now the build system knows where to find your board configuration!</p>
<p>And finally, add something like this near the bottom of
<code class="docutils literal notranslate"><span class="pre">boards/myarch/mychip/myboard</span></code>:</p>
<p>This includes additional, board-specific configuration variable
definitions in <code class="docutils literal notranslate"><span class="pre">boards/myarch/mychip/myboard/Kconfig</span></code>.</p>
</div>
</div>
<div class="section" id="nuttx-crypto">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/crypto</span></code><a class="headerlink" href="#nuttx-crypto" title="Permalink to this headline"></a></h2>
<p>This sub-directory holds the NuttX cryptographic sub-system.</p>
</div>
<div class="section" id="nuttx-drivers">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/drivers</span></code><a class="headerlink" href="#nuttx-drivers" title="Permalink to this headline"></a></h2>
<p>This directory holds architecture-independent device drivers.</p>
</div>
<div class="section" id="nuttx-fs">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/fs</span></code><a class="headerlink" href="#nuttx-fs" title="Permalink to this headline"></a></h2>
<p>This directory contains the NuttX file system. This file system is
described <a class="reference external" href="#NxFileSystem">below</a>.</p>
</div>
<div class="section" id="nuttx-graphics">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/graphics</span></code><a class="headerlink" href="#nuttx-graphics" title="Permalink to this headline"></a></h2>
<p>This directory contains files for graphics/video support under
NuttX.</p>
</div>
<div class="section" id="nuttx-include">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/include</span></code><a class="headerlink" href="#nuttx-include" title="Permalink to this headline"></a></h2>
<p>This directory holds NuttX header files. Standard header files
file retained in can be included in the <em>normal</em> fashion:</p>
</div>
<div class="section" id="nuttx">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx</span></code><a class="headerlink" href="#nuttx" title="Permalink to this headline"></a></h2>
<p>This is a (almost) empty directory that has a holding place for
generated static libraries. The NuttX build system generates a
collection of such static libraries in this directory during the
compile phase. These libraries are then in a known place for the
final link phase where they are accessed to generated the final
binaries.</p>
</div>
<div class="section" id="nuttx-libs-libc">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/libs/libc</span></code><a class="headerlink" href="#nuttx-libs-libc" title="Permalink to this headline"></a></h2>
<p>This directory holds a collection of standard libc-like functions
with custom interfaces into NuttX.</p>
<p>Normally the logic in this file builds to a single library
(<code class="docutils literal notranslate"><span class="pre">libc.a</span></code>). However, if NuttX is built as a separately compiled
kernel (with <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_PROTECTED=y</span></code> or
<code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_KERNEL=y</span></code>), then the contents of this directory
are built as two libraries: One for use by user programs
(<code class="docutils literal notranslate"><span class="pre">libc.a</span></code>) and one for use only within the &lt;kernel&gt; space
(<code class="docutils literal notranslate"><span class="pre">libkc.a</span></code>).</p>
<p>These user/kernel space libraries (along with the sycalls of
<code class="docutils literal notranslate"><span class="pre">`nuttx/syscall</span></code> &lt;#DirStructSyscall&gt;`__) are needed to support
the two differing protection domains.</p>
<p>Directory structure:</p>
</div>
<div class="section" id="nuttx-libs-libxx">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/libs/libxx</span></code><a class="headerlink" href="#nuttx-libs-libxx" title="Permalink to this headline"></a></h2>
<p>This directory holds a tiny, minimal standard std C++ that can be
used to build some, simple C++ applications in NuttX.</p>
</div>
<div class="section" id="nuttx-mm">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/mm</span></code><a class="headerlink" href="#nuttx-mm" title="Permalink to this headline"></a></h2>
<p>This is the NuttX memory manager.</p>
</div>
<div class="section" id="nuttx-net">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/net</span></code><a class="headerlink" href="#nuttx-net" title="Permalink to this headline"></a></h2>
<p>This directory contains the implementation of the NuttX networking
layer including internal socket APIs.</p>
</div>
<div class="section" id="nuttx-sched">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/sched</span></code><a class="headerlink" href="#nuttx-sched" title="Permalink to this headline"></a></h2>
<p>The files forming core of the NuttX RTOS reside here.</p>
</div>
<div class="section" id="nuttx-syscall">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/syscall</span></code><a class="headerlink" href="#nuttx-syscall" title="Permalink to this headline"></a></h2>
<p>If NuttX is built as a separately compiled kernel (with
<code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_PROTECTED=y</span></code> or <code class="docutils literal notranslate"><span class="pre">CONFIG_BUILD_KERNEL=y</span></code>), then
the contents of this directory are built. This directory holds a
syscall interface that can be used for communication between
user-mode applications and the kernel-mode RTOS.</p>
</div>
<div class="section" id="nuttx-tools">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/tools</span></code><a class="headerlink" href="#nuttx-tools" title="Permalink to this headline"></a></h2>
<p>This directory holds a collection of tools and scripts to simplify
configuring, building and maintaining NuttX.</p>
<p>Refer to the README file in the <code class="docutils literal notranslate"><span class="pre">tools</span></code> directory for more
information about the individual files. Some of these tools are
discussed below as well in the discussion of <a class="reference external" href="#configandbuild">configuring and
building</a> NuttX.</p>
</div>
<div class="section" id="nuttx-wireless">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/wireless</span></code><a class="headerlink" href="#nuttx-wireless" title="Permalink to this headline"></a></h2>
<p>This directory holds support for hardware-independent wireless
support.</p>
</div>
<div class="section" id="nuttx-makefile">
<h2><code class="docutils literal notranslate"><span class="pre">nuttx/Makefile</span></code><a class="headerlink" href="#nuttx-makefile" title="Permalink to this headline"></a></h2>
<p>The top-level <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> in the <code class="docutils literal notranslate"><span class="pre">$(TOPDIR)</span></code> directory contains
all of the top-level control logic to build NuttX. Use of this
<code class="docutils literal notranslate"><span class="pre">Makefile</span></code> to build NuttX is described
<a class="reference external" href="#buildingnuttx">below</a>.</p>
<hr class="docutils" />
<p>Next up is <a class="reference internal" href="build_and_make.html#build-and-make"><span class="std std-ref">Build and Make Details</span></a>.</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2020, The Apache Software Foundation
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>