JorgeGzm opened a new pull request, #19916:
URL: https://github.com/apache/nuttx/pull/19916
## Summary
This PR adds generic support for **link-time registration of struct
instances** ("iterable sections"), modeled after the Zephyr
`STRUCT_SECTION_*` mechanism. It allows a subsystem to collect statically
defined objects into name-sorted linker sections delimited by
`_<type>_list_start/_end` symbols, iterable at runtime with zero init
code and zero RAM overhead for the registry itself.
New files:
- `include/nuttx/iterable_sections.h`: `STRUCT_SECTION_ITERABLE` /
`STRUCT_SECTION_FOREACH` / `STRUCT_SECTION_GET` / `STRUCT_SECTION_COUNT`
macros.
- `include/nuttx/linker/iterable_sections.ld`: `ITERABLE_SECTION()`
macro emitting the `KEEP` + `SORT_BY_NAME` collection statements.
- `include/nuttx/linker/common-rom.ld` / `common-ram.ld`: central
aggregators meant to be `#include`d by board linker scripts (inside
`.text` and `.data` respectively), with per-subsystem Kconfig guards.
- `include/nuttx/linker/zbus.ld` + a `tools/Config.mk` hook
(`CONFIG_ZBUS_LINKER_INSERT`): an alternative **zero-touch** mode using
GNU ld `INSERT AFTER`, for boards that do not include the common
fragments.
- `boards/arm/stm32h7/linum-stm32h753bi/scripts/flash.ld`: first
adopter (2 lines), plus a `zbus` board configuration
(`configs/zbus/defconfig`) enabling the zbus example and its cmocka
test suite, so the hardware validation below is reproducible with
`./tools/configure.sh linum-stm32h753bi:zbus`.
- Documentation: `Documentation/components/iterable_sections.rst`,
`Documentation/applications/system/zbus/` (Sphinx, with diagrams) and
a `zbus` entry in the linum-stm32h753bi board configuration list.
First user: the port of the Zephyr **zbus** message bus
(`apps/system/zbus`, companion PR:
https://github.com/apache/nuttx-apps/pull/3743), which relies
on iterable sections for channel/observer registration exactly like the
Zephyr original.
### Why board opt-in? (how Zephyr solves this vs. NuttX)
In Zephyr this mechanism needs **no per-board work** because boards own
**no linker scripts at all**: there is a single common linker template
per architecture (e.g.
`include/zephyr/arch/arm/cortex_m/scripts/linker.ld`) which already
includes the shared `common-rom.ld` / `common-ram.ld` fragments, so
iterable sections are available on every board automatically.
NuttX has the opposite layout: **each board owns its linker script**
(~584 `.ld` files under `boards/`), so there is no single central file
to hook into. This PR therefore mirrors the Zephyr *content* while
adapting the *integration point*:
1. **Include mode (default, chosen for the first adopter):** the central
fragments live in `include/nuttx/linker/` and an adopting board adds
two lines to its script:
`#include <nuttx/linker/common-rom.ld>` inside `.text` and
`#include <nuttx/linker/common-ram.ld>` inside `.data`. This works
because `ARCHSCRIPT` linker scripts are already CPP-preprocessed
(`tools/Config.mk`), with upstream precedent (qemu-armv7a/r,
nRF52/91 boards already `#include` in their `.ld`). The fragments are
fully guarded by `#ifdef CONFIG_*`, so they are a **no-op for every
configuration that does not enable a subsystem using them**.
2. **INSERT mode (optional, zero-touch):** `CONFIG_ZBUS_LINKER_INSERT`
adds `zbus.ld` (GNU ld `INSERT AFTER .text`) through `ARCHSCRIPT`,
requiring no board edit. The in-file comments document the two
constraints discovered while validating it: the INSERT script must
precede the board script on the ld command line, and the first
`MEMORY` region compatible with read-only sections must be the ROM
region (which is why the Linum board uses the include mode instead).
A future mass migration of board scripts to include the common fragments
(bringing NuttX closer to the Zephyr single-template behavior) is
possible but out of scope here; it would deserve its own RFC.
## Impact
- **Existing boards/configs: none.** The fragments are Kconfig-guarded;
a stock `linum-stm32h753bi:nsh` build with the feature disabled was
verified to produce zero `zbus`/iterable sections in the map file
(byte-identical placement, proof the `#include` lines are a no-op).
- **Build process:** the `Config.mk` hook only activates with
`CONFIG_ZBUS_LINKER_INSERT=y` (Make build). The CMake build
preprocesses `LD_SCRIPT` as well, so the include mode works on both
build systems.
- **Users:** new documented component available to any subsystem that
needs static registration (drivers, test registries, etc.).
- **Documentation:** new Sphinx pages included;
`Documentation/components/index.rst` updated; `zbus` configuration
documented in the linum-stm32h753bi board page.
- **Security / compatibility:** no new runtime code in this PR (headers,
linker fragments and docs only).
## Testing
**Host:** Ubuntu 24.04.4 x86_64, Arm GNU Toolchain 13.2.rel1
(arm-none-eabi-gcc 13.2.1), GNU ld 2.41 (binutils from the same
toolchain).
**Target:** linum-stm32h753bi (STM32H753BI, ARMv7-M): stock `:nsh`
config for the no-op check, the `:zbus` config added by this PR for the
feature validation.
1. **Stock build (feature disabled):** `make` with `:nsh` OK;
`nuttx.map` contains no iterable/zbus sections → the board script
change is a no-op.
2. **Build with the `:zbus` config** (zbus + example + cmocka suite from
the companion apps PR): OK. Map file shows the sorted sections:
```
_zbus_channel_list_start = 0x0803e070
_zbus_observer_list_start = 0x0803e0fc
_zbus_channel_observation_list_start = 0x0803e1c4
```
with observation entries ordered by `SORT_BY_NAME` (priority
prefixes) as required by the zbus VDED algorithm.
3. **On hardware** (flashed via ST-LINK V3):
```
NuttX 13.0.1-RC0 a1b0941bec Aug 20 2026 21:17:15 arm linum-stm32h753bi
```
The zbus cmocka suite passes **16/16 tests, twice in the same boot**
(including bit-exact float/double payload delivery), and the `zbus`
example produces the expected output (see companion PR for the full
logs), exercising section iteration, name-sorted observation
grouping and the ROM-preserved mask initial values. The run is
reproducible with `./tools/configure.sh linum-stm32h753bi:zbus`
(board config added by this PR).
Note for CI/reviewers: the `zbus` defconfig enables Kconfig symbols
provided by the companion nuttx-apps PR, so the defconfig check for
this board config only passes when built together with it; the two
PRs should land together.
4. **CMake build:** `cmake -GNinja` + `ninja` with the same config: OK,
`_zbus_*` symbols present in `System.map` (CMake preprocesses the
board `.ld`, so the `#include` works there too).
5. **INSERT mode:** validated in a standalone ld harness (placement,
sorting, no overlap); constraints are documented in `zbus.ld`.
6. `tools/checkpatch.sh -g` on the commit: all checks pass.
Documentation built with `make html`: clean, pages render correctly.
Depends-On: https://github.com/apache/nuttx-apps/pull/3743
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
