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
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>
nxstyle checks one file per invocation. nxstyle_sweep.sh runs it over
the directories given, or the whole repository, and collects what it
reports.
Signed-off-by: raiden00pl <raiden00@railab.me>
Assisted-by: Claude Code
Document PBKDF2-HMAC-SHA256 ROMFS passwd generation and update board
Kconfig help text accordingly. Set the documented sim/login CI credential
in GitHub Actions.
Enable CONFIG_CODECS_BASE64 and CONFIG_NETUTILS_CODECS on sim:dropbear for
link compatibility with dropbear's bundled libtomcrypt.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
Support NUTTX_ROMFS_PASSWD_PASSWORD via update_romfs_password.sh for
configs that enable ROMFS passwd without a defconfig password (sim/login
CI). Enable RANDOMIZE_KEYS in sim/login defconfig. Update mkpasswd.c
header, platform docs, and the mkpasswd_autogen guide.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
Remove implicit default credentials and add build-time validation.
Add check_passwd_keys.sh and gen_passwd_keys.sh; run key setup via
passwd_keys.mk before config.h is generated. Mirror the same logic in
cmake/nuttx_add_romfs.cmake for CMake builds.
BREAKING CHANGE: Builds with CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE=y now
require an explicit admin password and non-default TEA keys. The
Kconfig default password "Administrator" and default TEA keys are no
longer accepted. Fix: run make menuconfig, set Admin password under
Board Selection -> Auto-generate /etc/passwd, enable random TEA keys or
set CONFIG_FSUTILS_PASSWD_KEY1..4 manually, and use NSH login with
Encrypted password file verification.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
* Add `./tools/checkpatch.sh -c -u -m -g HEAD~...HEAD` example
to match checks performed by our CI.
* Add cross-reference to checkpatch.sh documentation.
Signed-off-by: Tomasz 'CeDeROM' CEDRO <tomek@cedro.info>
In Jan-Feb 2026: NuttX CI hit a [record high usage of GitHub Runners](https://github.com/apache/nuttx/issues/17914), exceeding the limit enforced by ASF Infrastructure Team. We analysed the PRs and discovered that most GitHub Runners were wasted on __(1) Failure to Download the Build Dependencies__ for DTC Device Tree, OpenAMP Messaging, MicroADB Debugger, MCUBoot Bootloader, NimBLE Bluetooth, etc __(2) Resubmitting PR Commits__:
- [Video: Analysing the Most Expensive PR](https://youtu.be/swFaxaTCEQg)
- [Video: Second Most Expensive PR](https://youtu.be/uSpQkzBogEw)
- [Video: Third Most Expensive PR](https://youtu.be/J7w1gyjwZ1w)
- [Video: Most Expensive Apps PR](https://youtu.be/182h8cRpfvI)
- [Spreadsheet: Most Expensive PRs](https://docs.google.com/spreadsheets/d/1HY7fIZzd_fs3QPyA0TX7vsYOjL86m1fNOf1Wls93luI/edit?gid=70515654#gid=70515654)
Why would __Download Failures__ waste GitHub Runners? That's because Download Failures will terminate the Entire CI Build (across All CI Jobs), requiring a restart of the CI Build. And the CI Build isn't terminated immediately upon failure: NuttX CI waits for the CI Job to complete (e.g. arm-01), before terminating the CI Build. Which means that CI Builds can get terminated 2.5 hours into the CI Build, wasting 2.5 elapsed hours x [7.4 parallel processes](https://lupyuen.org/articles/ci3#live-metric-for-full-time-runners) of GitHub Runners.
This PR proposes to __Retry the Build for Each CI Target__. NuttX CI shall rebuild each CI Target (e.g. `sim:nsh`), upon failure, up to 3 times (total 4 builds). Each rebuild will be attempted after a Randomised Delay with Exponential
Backoff, initially set to 60 seconds, then 120 seconds, 240 seconds. The rebuilds will mitigate the effects of Intermittent Download Failures that occur in GitHub Actions. (And eliminate developer frustration)
If the build fails after 3 retries: Subsequent CI Targets will __not be allowed to rebuild__ upon failure. This is to prevent cascading build failures from overloading GitHub Actions, and consuming too many GitHub Runners.
Note that NuttX CI shall retry the build for __Any Kind of Build Failure__, including Download Failures, Compile Errors and Config Errors. We designed it simplistically due to our current constraints: (1) Lack of CI Expertise (2) NuttX CI is Mission Critical (3) Legacy CI Scripts are Highly Complex. To prevent Compile Errors and Config Errors: We expect NuttX Devs to [Build and Test PRs in Our Own Repos](https://github.com/apache/nuttx/issues/18568), before submitting to NuttX.
What about __Resubmitting PR Commits__ and its wastage of GitHub Runners? We also require NuttX Devs to [Build and Test PRs in Our Own Repos](https://github.com/apache/nuttx/issues/18568), before resubmitting to NuttX. GitHub Runners will then be charged to the developer's quota, without affecting the GitHub Runners quota for Apache NuttX Project. We plan to [Kill All CI Jobs](https://youtu.be/182h8cRpfvI?si=MmAuwLISZPPMoqDq&t=1479) for PRs that have been switched to Draft Mode. We'll monitor this through the [NuttX Build Monitor](https://github.com/apache/nuttx/issues/18659).
Modified Files:
`tools/testbuild.sh`: We introduce a New Wrapper Function `retrytest` that will call the Existing Function `dotest`, to build the CI Target and retry on error.
`Documentation/components/tools/testbuild.rst`: Updated the `testbuild.sh` doc with the Retry Logic.
Signed-off-by: Lup Yuen Lee <luppy@appkaki.com>
Document the new mkpasswd-based password generation system and its
integration with the build process.
Changes:
* Add comprehensive mkpasswd tool documentation to components/tools
* Update SIM board docs to explain generated passwd workflow
* Update ESP32-C3-legacy board docs for passwd generation
* Update RX65N board docs with credential handling guidance
* Document how to configure and use BOARD_ETC_ROMFS_PASSWD_* options
* Explain security benefits of build-time generation vs static files
* Update all doc examples from default username "admin" to "root"
BREAKING CHANGE: Boards using static /etc/passwd files in ETC_ROMFS
must migrate to the new build-time generation workflow documented in
Documentation/components/tools/index.rst. The old static passwd files
are no longer present in migrated boards; boards that relied on them
will fail to build until credentials are configured via Kconfig.
Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>
All of the tools listed on the original documentation are now given
their own individual doc pages. This makes it much easier to
cross-reference them from other documentation locations (as many are
used in CI/for specific architectures) and it also makes it easier for
users to digest the information.
Signed-off-by: Matteo Golin <matteo.golin@gmail.com>
* Remove `tools/` from the section name.
* Generate local TOC that lists described tools.
* Update new parsetrace.py toctree location to fix indexing and display.
Signed-off-by: Tomasz 'CeDeROM' CEDRO <tomek@cedro.info>
For the following code, we need to check 'type_attr.form'.
type_attr = DIE.attributes["DW_AT_type"]
base_type_die = dwarfinfo.get_DIE_from_refaddr(xxx)
When type_attr.form==DW_FORM_ref_addr, 'type_attr.value' means
global reference (across compilation units).
When type_attr.form==DW_FORM_ref4, 'type_attr.value' means
local reference (within the same compilation unit).
Signed-off-by: yukangzhi <yukangzhi@xiaomi.com>
[checkkconfig.py] is a tool that simulates the effects of modifying a CONFIG item,
Can be used to check whether my config changes are what I expected.
Signed-off-by: xuxin19 <xuxin19@xiaomi.com>
This script downloads all NuttX RTOS and Application snapshot packages
from the upstream git repository based on the provided git tags list.
These are NOT official release packages as checkum will differ.
When launched from the local NuttX git repository clone the script will
obtain all available tags to be downloaded, otherwise list of tags needs
to be provided manually (or when just selected tag is required).
This script uses ``wget`` underneath, make sure this tool is installed.
Fetch log file is created with a timestamp in name next to the packages.
Having all tags packaged is important for changes comparison
between specific versions, testing a specific version, compatibility
checks, searching for a feature introduction timeline, etc.
Usage: `./nxtagspkgsfetch.sh [download_path] [tags_list_space_separated]`
You can provide optional download path (default `../../nuttx-packages`)
and tags list to get packages for (default all tags from local git clone).
When providing tags you also need to provide download path.
Documentation update contains new tool description (above).
Signed-off-by: Tomasz 'CeDeROM' CEDRO <tomek@cedro.info>
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>
This commit makes it clear how to use the refresh.sh script to
update board configs showing differents usages cenarios.
Signed-off-by: Alan C. Assis <acassis@gmail.com>
