mirror of
https://github.com/apache/nuttx.git
synced 2026-10-08 14:55:18 +00:00
f6ecf80ebb
The documentation grew one page at a time, so the tree follows the
history of who wrote what and not the shape of NuttX. Scheduling is
spread over three places, a driver page can sit above the subsystem
that owns it, and the front page lists everything at the same level.
That is a lot to face when all you want to know is where the scheduler
lives.
This change files every page under the code it describes. It is a move,
not a rewrite: outside the ten pages named below, every page keeps the
text that is already in master, and no page's text is deleted.
What it does:
* Groups the table of contents into nine chapters.
* Moves the OS subsystems under os/: scheduling, memory, drivers,
filesystem, networking, IPC, interrupts, libs, time.
* Renames the platform pages to the names the source tree uses, and
derives their tags from the tree instead of by hand.
* Splits guides/ by subject.
* Adds Documentation/redirects.py, with a rule for every page that left
its old path, so old URLs keep working. The redirect page also carries
a link's #anchor across to the new page.
Ten pages have text that is new or rewritten. Nine of them are the
landing page of a chapter, which has to exist for the new structure:
index the front page
os/index OS Design
os/scheduling/index Scheduling
os/interrupts/index Interrupts
os/ipc/index IPC
os/time/index Time and timers
about/index About
developing/index Developing NuttX
ReleaseNotes/index Release notes
The tenth is os/libs/libbuiltin, the only page here with technical
content: libs/libbuiltin/ had no page at all. Five SVG diagrams come
with these pages, hand-written XML with no editor metadata.
Nothing outside Documentation/ is touched.
How it was checked:
* Sphinx builds with -W: no warnings, and no document left outside a
toctree.
* A script, offered in the PR, proves the narrow claim this rests on.
For every page outside the ten named above it erases what a move
touches -- link target, path, tag line, toctree block, table border --
from the whole old text and the whole new text, and requires the two
to be byte for byte identical. It also requires every sentence of a
deleted page to turn up somewhere, and every page that left its old
path to have a redirect, from a URL that existed, to where its content
went. It exits non-zero and names the page if any of that is not true,
and it tests added pages too, so forgetting to declare one cannot make
it pass.
* An independent audit checked 133 factual claims on these ten pages
against the tree, one shell command per claim: 130 confirmed, 1
refuted and fixed here, 2 not checkable.
* tools/checkpatch.sh is clean over the range.
The diff is large because moving a page changes every link that points
to it. Most of it is pure renames, and board pages that gained one tag
line.
Assisted-by: Claude:claude-opus-5
257 lines
7.5 KiB
ReStructuredText
257 lines
7.5 KiB
ReStructuredText
.. include:: /substitutions.rst
|
|
|
|
.. todo::
|
|
This is mostly untouched from the original documentation. It does
|
|
not really belong to "quickstart". Also, this needs cleanup.
|
|
|
|
.. _organization:
|
|
|
|
===================
|
|
Directory Structure
|
|
===================
|
|
|
|
This is included for reference, and it's not necessary to know
|
|
all the details at first.
|
|
|
|
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:
|
|
|
|
**Configuration Files**. The NuttX configuration consists of logic
|
|
in processor architecture directories, *chip/SoC* directories, and
|
|
board configuration directories. The complete configuration is
|
|
specified by several settings in the NuttX configuration file.
|
|
|
|
- *Processor architecture specific files*. These are the files
|
|
contained in the ``arch/<arch-name>/`` directory and
|
|
are discussed in a paragraph
|
|
`below <#arch-subdirectory-structure>`__. As an example, all ARM
|
|
processor architectures are provided under the ``arch/arm/``
|
|
directory which is selected with the ``CONFIG_ARCH="arm"``
|
|
configuration option.
|
|
|
|
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 ``arch/arm/include/armv7-m``
|
|
and ``arch/arm/src/armv7-m`` directories which are selected by
|
|
the ``CONFIG_ARCH_CORTEXM3=y``, ``CONFIG_ARCH_CORTEXM4=y``, or
|
|
``CONFIG_ARCH_CORTEXM7=y`` configuration options
|
|
|
|
- *Chip/SoC specific files*. Each processor architecture is
|
|
embedded in a *System-on-a-Chip* (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.).
|
|
|
|
These chip-specific files are contained within chip-specific
|
|
sub-directories also under the ``arch/<arch-name>/``
|
|
directory and are selected via the ``CONFIG_ARCH_CHIP``
|
|
selection.
|
|
|
|
As an example, the STMicro STM32 SoC architecture is based on
|
|
the ARMv7-M processor and is supported by logic in the
|
|
``arch/arm/include/stm32`` and ``arch/arm/src/stm32``
|
|
directories which are selected with the
|
|
``CONFIG_ARCH_CHIP="stm32"`` configuration setting.
|
|
|
|
- *Board specific configurations*. 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.).
|
|
|
|
These board-specific configuration files can be found in the
|
|
``boards/<arch-name>/<chip-name>/<board-name>/``
|
|
sub-directories and are discussed in a paragraph
|
|
`below <#boards-subdirectory-structure>`__.
|
|
|
|
The directory ``boards/arm/stm32f4/stm32f4discovery/``, as an
|
|
example, holds board-specific logic for the STM32F4 Discovery
|
|
board and is selected via the
|
|
``CONFIG_ARCH_BOARD="stm32f4discovery"`` configuration setting.
|
|
|
|
``nuttx/Documentation``
|
|
=======================
|
|
|
|
This directory holds the NuttX documentation. It's made with
|
|
the `Sphinx documentation system <https://www.sphinx-doc.org>`_. See the
|
|
README.md file for information on how to build it.
|
|
|
|
``nuttx/arch``
|
|
==============
|
|
|
|
This sub-directory holds the NuttX supported architectures.
|
|
|
|
For details see :doc:`/os/arch/index`.
|
|
|
|
``nuttx/binfmt``
|
|
================
|
|
|
|
The ``binfmt/`` subdirectory contains logic for loading binaries
|
|
in the file system into memory in a form that can be used to
|
|
execute them.
|
|
|
|
``nuttx/audio``
|
|
===============
|
|
|
|
The ``audio/`` subdirectory contains the NuttX audio sub-system.
|
|
|
|
.. _nuttx_boards:
|
|
|
|
``nuttx/boards``
|
|
================
|
|
|
|
The ``boards/`` subdirectory contains custom logic and board
|
|
configuration data for each board. These board-specific
|
|
configurations plus the architecture-specific configurations in
|
|
the ``arch/`` subdirectory complete define a customized port of
|
|
NuttX.
|
|
|
|
Boards Subdirectory Structure
|
|
-----------------------------
|
|
|
|
The ``boards/`` directory contains board specific configuration
|
|
files. Each board must provide a sub-directory <board-name> under
|
|
``boards/<arch-name>/<chip-name>/``.
|
|
|
|
See :doc:`/components/boards` for details.
|
|
|
|
``nuttx/cmake``
|
|
===============
|
|
|
|
This sub-directory holds the NuttX CMake functions.
|
|
|
|
For details see :doc:`/components/cmake`.
|
|
|
|
``nuttx/crypto``
|
|
================
|
|
|
|
This sub-directory holds the NuttX cryptographic sub-system.
|
|
|
|
For details see :doc:`/os/crypto`.
|
|
|
|
``nuttx/drivers``
|
|
=================
|
|
|
|
This directory holds architecture-independent device drivers.
|
|
|
|
For details see :doc:`/os/drivers/index`.
|
|
|
|
``nuttx/fs``
|
|
============
|
|
|
|
This directory contains the NuttX file system. This file system is
|
|
described `below <#NxFileSystem>`__.
|
|
|
|
``nuttx/graphics``
|
|
==================
|
|
|
|
This directory contains files for graphics/video support under
|
|
NuttX.
|
|
|
|
For details see :doc:`/os/graphics/index`.
|
|
|
|
``nuttx/include``
|
|
=================
|
|
|
|
This directory holds NuttX header files. Standard header files
|
|
file retained in can be included in the *normal* fashion:
|
|
|
|
``nuttx/libs/libc``
|
|
===================
|
|
|
|
This directory holds a collection of standard libc-like functions
|
|
with custom interfaces into NuttX.
|
|
|
|
For details see :doc:`/os/libs/index`.
|
|
|
|
``nuttx/mm``
|
|
============
|
|
|
|
This is the NuttX memory manager.
|
|
|
|
For details see :doc:`/os/memory/index`.
|
|
|
|
``nuttx/net``
|
|
=============
|
|
|
|
This directory contains the implementation of the NuttX networking
|
|
layer including internal socket APIs.
|
|
|
|
For details see :doc:`/os/networking/index`.
|
|
|
|
``nuttx/openamp``
|
|
=================
|
|
|
|
This directory contains OpenAMP support for NuttX.
|
|
|
|
For details see :doc:`/os/openamp`.
|
|
|
|
``nuttx/pass1``
|
|
===============
|
|
|
|
This directory provides support for the two-pass build
|
|
(``CONFIG_BUILD_2PASS=y``). In a two-pass build, the application logic
|
|
is built during pass 1 and the operating system kernel during pass 2.
|
|
Applications may generate and install source files into this directory
|
|
during pass 1; those files are then compiled and linked into the kernel
|
|
address space during pass 2.
|
|
|
|
The primary use of this mechanism is to generate kernel symbol tables
|
|
required for loadable kernel module support.
|
|
|
|
``nuttx/sched``
|
|
===============
|
|
|
|
The files forming core of the NuttX RTOS reside here.
|
|
|
|
``nuttx/syscall``
|
|
=================
|
|
|
|
If NuttX is built as a separately compiled kernel (with
|
|
``CONFIG_BUILD_PROTECTED=y`` or ``CONFIG_BUILD_KERNEL=y``), 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.
|
|
|
|
For details see :doc:`/os/syscall`.
|
|
|
|
``nuttx/tools``
|
|
===============
|
|
|
|
This directory holds a collection of tools and scripts to simplify
|
|
configuring, building and maintaining NuttX.
|
|
|
|
Refer to the :doc:`/components/tools/index` page for more
|
|
information about the individual files. Some of these tools are
|
|
discussed below as well in the discussion of `configuring and
|
|
building <#configandbuild>`__ NuttX.
|
|
|
|
``nuttx/video``
|
|
===============
|
|
|
|
This directory holds support for video sub-system.
|
|
|
|
For details see :doc:`/os/video`.
|
|
|
|
``nuttx/wireless``
|
|
==================
|
|
|
|
This directory holds support for hardware-independent wireless
|
|
support.
|
|
|
|
For details see :doc:`/os/wireless`.
|
|
|
|
``nuttx/CMakeLists.txt``
|
|
========================
|
|
|
|
The top-level ``CMakeLists.txt`` file.
|
|
|
|
``nuttx/Makefile``
|
|
==================
|
|
|
|
The top-level ``Makefile`` in the ``$(TOPDIR)`` directory contains
|
|
all of the top-level control logic to build NuttX.
|