mirror of
https://github.com/apache/nuttx.git
synced 2026-10-11 16:20:21 +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
161 lines
6.1 KiB
ReStructuredText
161 lines
6.1 KiB
ReStructuredText
====
|
|
libc
|
|
====
|
|
|
|
This directory contains numerous, small functions typically associated with
|
|
what you would expect to find in a standard C library. The sub-directories
|
|
in this directory contain standard interface that can be executed by user-
|
|
mode programs.
|
|
|
|
Normally, NuttX is built with no protection and all threads running in kernel-
|
|
mode. In that mode, there is no real architectural distinction between
|
|
what is a kernel-mode program and what is a user-mode program; the system is
|
|
more like an multi-threaded program that all runs in kernel-mode.
|
|
|
|
But if the ``CONFIG_BUILD_PROTECTED`` option is selected, NuttX will be built
|
|
into distinct user-mode and kernel-mode sections. In that case, most of the
|
|
code in the ``nuttx/`` directory will run in kernel-mode with exceptions
|
|
of (1) the user-mode "proxies" found in syscall/proxies, and (2) the
|
|
standard C library functions found in this directory. In this build mode,
|
|
it is critical to separate the user-mode OS interfaces in this way.
|
|
|
|
If ``CONFIG_BUILD_KERNEL`` is selected, then only a NuttX kernel will be built
|
|
with no applications.
|
|
|
|
Sub-Directories
|
|
===============
|
|
|
|
The files in the ``libs/libc/`` directory are organized (mostly) according
|
|
which file in the ``include/`` directory provides the prototype for library
|
|
functions. So we have::
|
|
|
|
audio - This part of the audio system: nuttx/audio/audio.h
|
|
builtin - Support for builtin applications. Used by nuttx/binfmt and NSH.
|
|
dlfcn - dlfcn.h
|
|
endian - endian.h
|
|
errno - errno.h
|
|
hex2bin - hex2bin.h
|
|
libgen - libgen.h
|
|
locale - locale.h
|
|
lzf - lzf.h
|
|
fixedmath - fixedmath.h
|
|
grp - grp.h
|
|
inttypes - inttypes.h
|
|
machine - Various architecture-specific implementations.
|
|
math - math.h
|
|
elf - Part of module and shared library logic: nuttx/lib/elf.h
|
|
net - Various network-related header files: netinet/ether.h, arpa/inet.h
|
|
pthread - pthread.h
|
|
pwd - pwd.h
|
|
queue - queue.h
|
|
sched - sched.h
|
|
search - search.h
|
|
semaphore - semaphore.h
|
|
stdbit - stdbit.h (optional C23)
|
|
stdio - stdio.h
|
|
stdlib - stdlib.h
|
|
string - string.h (and legacy strings.h and non-standard nuttx/b2c.h)
|
|
time - time.h
|
|
uio - sys/uio.h
|
|
unistd - unistd.h
|
|
wchar - wchar.h
|
|
wctype - wctype.h
|
|
|
|
Most of these are "standard" header files; some are not: ``hex2bin.h`` and
|
|
``fixemath.h`` are non-standard.
|
|
|
|
There is also a ``misc/`` subdirectory that contains various internal functions
|
|
and interfaces from header files that are too few to warrant their own sub-
|
|
directory::
|
|
|
|
misc - Nonstandard "glue" logic, nuttx/debug.h, crc32.h, dirent.h
|
|
|
|
Library Database
|
|
================
|
|
|
|
Information about functions available in the NuttX C library information is
|
|
maintained in a database. That "database" is implemented as a simple comma-
|
|
separated-value file, libc.csv. Most spreadsheets programs will accept this
|
|
format and can be used to maintain the library database.
|
|
|
|
This library database will (eventually) be used to generate symbol library
|
|
symbol table information that can be exported to external applications.
|
|
|
|
The format of the CSV file for each line is::
|
|
|
|
Field 1: Function name
|
|
Field 2: The header file that contains the function prototype
|
|
Field 3: Condition for compilation
|
|
Field 4: The type of function return value.
|
|
Field 5 - N+5: The type of each of the N formal parameters of the function
|
|
|
|
Each type field has a format as follows::
|
|
|
|
type name:
|
|
For all simpler types
|
|
formal type | actual type:
|
|
For array types where the form of the formal (eg. int param[2])
|
|
differs from the type of actual passed parameter (eg. int*). This
|
|
is necessary because you cannot do simple casts to array types.
|
|
formal type | union member actual type | union member fieldname:
|
|
A similar situation exists for unions. For example, the formal
|
|
parameter type union sigval -- You cannot cast a uintptr_t to
|
|
a union sigval, but you can cast to the type of one of the union
|
|
member types when passing the actual parameter. Similarly, we
|
|
cannot cast a union sigval to a uinptr_t either. Rather, we need
|
|
to cast a specific union member fieldname to uintptr_t.
|
|
|
|
NOTE: The tool mksymtab can be used to generate a symbol table from this CSV
|
|
file. See ``Documentation/components/tools`` for further details about the use of mksymtab.
|
|
|
|
symtab
|
|
======
|
|
|
|
Symbol Tables and Build Modes
|
|
-----------------------------
|
|
|
|
This directory provide support for a symbol table which provides all/most of
|
|
system and C library services/functions to the application and NSH.
|
|
|
|
Symbol tables have differing usefulness in different NuttX build modes:
|
|
|
|
#. In the FLAT build (``CONFIG_BUILD_FLAT``), symbol tables are used to bind
|
|
addresses in loaded ELF or NxFLAT modules to base code that usually
|
|
resides in FLASH memory. Both OS interfaces and user/application
|
|
libraries are made available to the loaded module via symbol tables.
|
|
|
|
#. Symbol tables may be of value in a protected build
|
|
(``CONFIG_BUILD_PROTECTED``) where the newly started user task must
|
|
share resources with other user code (but should use system calls to
|
|
interact with the OS).
|
|
|
|
#. But in the kernel build mode (``CONFIG_MODULES``), only fully linked
|
|
executables loadable via ``execl()``, ``execv()``, or ``posix_spawan()``
|
|
can be used.
|
|
There is no use for a symbol table with the kernel build since all
|
|
memory resources are separate; nothing is share-able with the newly
|
|
started process.
|
|
|
|
Code/Text Size Implications
|
|
---------------------------
|
|
|
|
The option can have substantial effect on system image size, mainly
|
|
code/text. That is because the instructions to generate symtab.inc
|
|
above will cause EVERY interface in the NuttX RTOS and the C library to be
|
|
included into build. Add to that the size of a huge symbol table.
|
|
|
|
In order to reduce the code/text size, you may want to manually prune the
|
|
auto-generated symtab.inc file to remove all interfaces that you do
|
|
not wish to include into the base FLASH image.
|
|
|
|
Implementation Details
|
|
======================
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:caption: Contents:
|
|
|
|
search.rst
|
|
stdbit.rst
|
|
stream.rst
|
|
zoneinfo.rst
|