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
Describe the jail, leftover pre-opened fds, the NSH command-form scrub,
and the flat-build trust boundary shared with credentials.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
Remove the misspelled crimon placeholder so the application appears
only under its correct name.
Document how nxsched_switch_critmon() updates timing across context
switches, correct the RUN and TIME column descriptions, and link the
application page to the implementation guide.
This follows up on PR #20066
Assisted-by: OpenAI Codex
Signed-off-by: yushuailong <yyyusl@qq.com>
Remove the per-arch testset implementation from the spinlock layer.
The testset abstraction predates the unified spinlock.h API and is no
longer used now that all arches provide spin_lock_irqsave()/
spin_unlock_irqrestore() directly. Drop the per-arch *_testset.{c,S}
implementations and spinlock.h files for arm, sim, sparc, tricore,
x86_64, and xtensa, along with the CXD56_TESTSET,
CXD56_TESTSET_WITH_HWSEM, and CXD56_ATOMIC_WITH_HWSEM Kconfig options
in arch/arm/src/cxd56xx, and simplify the CXD56 semaphore pool loop
in cxd56_sph.c to a single unconditional range.
Signed-off-by: zhangyu117 <zhangyu117@xiaomi.com>
Correct the misspelled up_timer_initialize() and up_initialize()
API names in the tickless OS documentation to match the declarations
in include/nuttx/arch.h.
Signed-off-by: arnavsharma990 <2006arnavsharma@gmail.com>
Supports the UNIX setuid-on-exec sudo helper. Documents the model,
generates an extra ROMFS user and /etc/sudoers for a non-root test,
reports BINFS modes from the builtin table so ls -l matches execute
bits, and skips NULL environment entries when sanitizing a setuid exec.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
Document CONFIG_SCHED_NGROUPS, setgroups/getgroups/initgroups, and
setresuid/setresgid in the user identity guide.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
Documentation/guides/fork_vfork_migration.rst is new. It says what changed
and why, gives the two primitives as a table, states plainly what breaks, and
answers "which replacement do I want?" from the reader's own reason for having
called fork() -- posix_spawn() or vfork() to run a program, pthread_create()
for a second flow of control that shares memory, fork() itself for an
independent copy. It also documents the two configuration symbols, what an
architecture has to implement to gain real fork(), and the one visible
consequence of moving the vfork() suspension into the kernel: a waitpid()
after a child that _exit()s can only report status where
CONFIG_SCHED_CHILD_STATUS is enabled.
reference/user/01_task_control.rst gains an entry for fork() and rewrites the
one for vfork(), which described NuttX's limitations rather than the
interface's contract. standards/posix.rst moves fork() from "No" to "Cond."
and vfork() from "Yes" to "Cond.", both being conditional on the configuration
now. implementation/memory_configurations.rst no longer lists fork() as
unimplementable in the presence of address environments, which was the whole
point of that section's wish list. Three long-standing typos in that file are
corrected while touching it, since codespell checks the whole of any file a
patch modifies.
BREAKING CHANGE: this commit carries no code; it is the migration guide for
the fork() withdrawal in the commit before it, and is marked so that every
commit in the series carries the marker CONTRIBUTING.md 1.13 requires. The
quick fixes are in Documentation/guides/fork_vfork_migration.rst.
Assisted-by: Claude Code:claude-opus-5
Signed-off-by: Marco Casaroli <marco.casaroli@gmail.com>
Describe the shared library open semantics in the FLAT and PROTECTED
builds: dlopen() of a library that is already loaded returns a handle
to it and takes an additional reference, and the library is unloaded
only when the last handle is closed. Note the consequences that follow
from having a single instance: libraries are matched by basename, data
is shared by all users, and constructors and destructors run once.
Contrast this with insmod(), which still rejects a duplicate module
name, and note that dlopen() is not implemented in the KERNEL build.
Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Marco Casaroli <marco.casaroli@gmail.com>
Document inode_checkperm / inode_checkpathperm, mountpoint traverse vs open
semantics, and the optional mountpt_operations.permission hook in
file_permission.rst.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
Document setreuid/setregid, getresuid/getresgid, and how inode_reserve
assigns owner and group for pseudo-filesystem objects.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
Fix repeated and misspelled words in the kernel modules versus shared libraries implementation notes so the text reads correctly.
Signed-off-by: Old-Ding <35417409+Old-Ding@users.noreply.github.com>
Add a new section under Implementation Details explaining the CRC32
variants available in NuttX, including the difference between the
native crc32() and the new Linux/zlib-compatible crc32_ieee().
Signed-off-by: hanzhijian <hanzhijian@zepp.com>
Move the stm32l1 sources, headers and boards into arch/arm/src/stm32l1,
arch/arm/include/stm32l1 and boards/arm/stm32l1, then finalize the split:
source each split family directly in arch/arm/Kconfig and boards/Kconfig and
remove the now-empty combined arch/arm/src/stm32 and boards/arm/stm32 trees.
BREAKING CHANGE: The legacy STM32 architecture and board paths were split into
stm32f1, stm32l1, stm32f2, stm32f3, stm32f4, and stm32g4 directories.
Out-of-tree boards must move from stm32 to the matching split family.
Signed-off-by: raiden00pl <raiden00@railab.me>
BREAKING CHANGE: Common STM32 source and private header files moved to
arch/arm/src/common/stm32. Out-of-tree code that references family-local
common source paths must update includes, build rules, and source paths
to the new common STM32 location.
Signed-off-by: raiden00pl <raiden00@railab.me>
Adds comprehensive documentation for the POSIX three-tier user identity
model (real, effective, saved-set IDs) enabled by CONFIG_SCHED_USER_IDENTITY.
* Updates sched/Kconfig with detailed help text explaining the config.
* Adds user_identity.rst to formally document credential inheritance
and the privilege transition rules for setuid(), seteuid(), setgid(),
and setegid().
* Updates tasks_vs_threads.rst to list credentials as a shared task
group resource.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
The repo bitbucket.org/nuttx/tools is no longer available. This PR changes it to to github.com/patacongo/tools, as explained in https://github.com/apache/nuttx/pull/18890. This PR updates the URL in Dockerfile and Docs.
Signed-off-by: Lup Yuen Lee <luppy@appkaki.com>
Fix 269 occurrences of duplicate "the" word typo found in 209 files
across source code, header files, and configuration.
Signed-off-by: Huang Qi <huangqi3@xiaomi.com>
Since the busy-wait time statistics for entering the critical section have been added, the critmon information in the document has been updated accordingly.
Signed-off-by: wangzhi16 <wangzhi16@xiaomi.com>
This commit adds initial high level overview of the NuttX
make-based build system. It documents:
* Tools used during the build process
* Mechanisms set in place during the build process
Signed-off-by: Luchian Mihai <luchiann.mihai@gmail.com>
