Skip to content

zbus: Add linker support, documentation and linum-stm32h753bi configuration - #20027

Open
JorgeGzm wants to merge 2 commits into
apache:masterfrom
JorgeGzm:feature/add_zbus
Open

zbus: Add linker support, documentation and linum-stm32h753bi configuration#20027
JorgeGzm wants to merge 2 commits into
apache:masterfrom
JorgeGzm:feature/add_zbus

Conversation

@JorgeGzm

Copy link
Copy Markdown
Member

Summary

Integration of the zbus message bus port (apache/nuttx-apps#3743) on
top of the iterable sections infrastructure (#19927, merged), in two
commits (NuttX-side zbus support, then the board adoption):

  1. zbus linker support: the zbus ITERABLE_SECTION() blocks,
    guarded by CONFIG_ZBUS, in include/nuttx/linker/common-rom.ld
    (include mode) and common-insert.ld (zero-touch INSERT mode of
    include/nuttx: Add link-time iterable sections infrastructure #19927); plus the zbus Sphinx documentation.
  2. linum-stm32h753bi adoption (first adopter board): 2 #include
    lines in flash.ld and a zbus board configuration enabling the
    zbus example, its cmocka test suite and the OS test (ostest),
    reproducible with ./tools/configure.sh linum-stm32h753bi:zbus.

This resubmits the content of #19916, which was merged and then reverted
in #20009 because it landed before apache/nuttx-apps#3743: the board
configuration enables CONFIG_EXAMPLES_ZBUS and CONFIG_TESTING_ZBUS,
which only exist once the application side is in. Both dependencies are
declared with depends-on: lines, and this PR should only be merged
after both of them.

Impact

  • Users: zbus becomes usable out of the box on the
    linum-stm32h753bi through the new :zbus configuration; any other
    board can adopt it the same way (two linker-script lines, or the
    INSERT mode with no board edit).
  • Existing boards/configs: none. The included fragments expand to
    nothing unless CONFIG_ZBUS is enabled (verified: the stock :nsh
    map has zero zbus sections).
  • Build process: no build logic touched in this PR (the INSERT-mode
    hook lives in include/nuttx: Add link-time iterable sections infrastructure #19927); Make and CMake both supported for the include
    mode.
  • Hardware: only the linum-stm32h753bi board is touched.
  • Documentation: zbus application pages and a zbus entry in the
    board configuration list.
  • Tooling: the reused zbus SVG diagrams are added to the
    .codespellrc skip list (their embedded base64 raster data trips the
    spell checker with false positives).
  • Security / compatibility: no changes to existing runtime code.

Testing

Host: Ubuntu 24.04.4 x86_64, arm-none-eabi-gcc 13.2.1 (GNU ld 2.41).
Target: linum-stm32h753bi (STM32H753BI), built with #19927 and
apache/nuttx-apps#3743 applied (as CI does).

  • Stock :nsh build: no zbus references in the map or in the
    preprocessed linker script (no-op proof).

  • :zbus build (Make and CMake): OK, the three _zbus_*_list sections
    collected name-sorted in flash as required by the zbus VDED algorithm.

  • On hardware (ST-LINK V3): the 17-test zbus cmocka suite passes twice
    in the same boot and the zbus example produces the expected output,
    with the fourth message correctly masked for the listener and the
    listener notified before the subscriber:

    nsh> zbus
    zbus: publishing 5 messages to acc_chan
    zbus:  listener: x=1 y=10 z=100
    zbus:  subscriber: x=1 y=10 z=100
    zbus:  listener: x=2 y=20 z=200
    zbus:  subscriber: x=2 y=20 z=200
    zbus:  listener: x=3 y=30 z=300
    zbus: listener masked
    zbus:  subscriber: x=3 y=30 z=300
    zbus: listener unmasked
    zbus:  subscriber: x=4 y=40 z=400
    zbus:  listener: x=5 y=50 z=500
    zbus:  subscriber: x=5 y=50 z=500
    zbus: done
    
  • ostest on the same boot, after the zbus suite (the zbus async
    listener task stays alive throughout): ostest_main: Exiting with status 0, no failures.

  • INSERT mode: common-insert.ld preprocessed with CONFIG_ZBUS expands
    to the three zbus ITERABLE_SECTION blocks inside .iterable_sections
    (INSERT AFTER .text) and to an empty section without it;
    common-rom.ld expands to nothing in that mode.

  • tools/checkpatch.sh -c -u -m -g on both commits (nxstyle +
    codespell, same flags as CI): all checks pass. sphinx-build -W:
    clean.

Depends-On #20015
Depends-On apache/nuttx-apps/pull/3743

NuttX-side support for the zbus message bus port (apps/system/zbus in
nuttx-apps), built on the link-time iterable sections infrastructure
added in a companion PR:

- include/nuttx/linker/common-rom.ld and common-insert.ld: register the
  zbus channel, observer and channel observation iterable sections
  (ITERABLE_SECTION blocks guarded by CONFIG_ZBUS, no-op otherwise) for
  the include and the zero-touch INSERT modes respectively;
  common-ram.ld: note that zbus needs no RAM sections.
- Documentation/applications/system/zbus: Sphinx documentation for the
  zbus application, with the upstream Zephyr diagrams (Apache-2.0).
- .codespellrc: skip the reused zbus SVG diagrams (embedded base64
  raster data trips the spell checker).

Assisted-by: Claude Code
Signed-off-by: Jorge Guzman <jorge.gzm@gmail.com>
Adopt the zbus message bus on the linum-stm32h753bi (first adopter
board):

- scripts/flash.ld: include the iterable sections common fragments
  (2 lines: common-rom.ld inside .text, common-ram.ld inside .data).
- configs/zbus/defconfig: board configuration enabling zbus with all
  observer types, the zbus example and its cmocka test suite
  (./tools/configure.sh linum-stm32h753bi:zbus).
- Board documentation: describe the new configuration.

Validated on hardware: the 16-test cmocka suite passes twice in the
same boot and the zbus example produces the expected output.

Assisted-by: Claude Code
Signed-off-by: Jorge Guzman <jorge.gzm@gmail.com>
@github-actions github-actions Bot added Area: Documentation Improvements or additions to documentation Size: L The size of the change in this PR is large Board: arm labels Aug 31, 2026
@github-actions

Copy link
Copy Markdown

MemBrowse Memory Report

No memory changes detected for:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Area: Documentation Improvements or additions to documentation Board: arm Size: L The size of the change in this PR is large

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants