system/zbus: Port the Zephyr zbus message bus to NuttX

[JorgeGzm]

Summary

This PR ports the Zephyr RTOS zbus (a many-to-many message bus with
typed channels and decoupled observers) to NuttX, preserving the
original declarative API (ZBUS_CHAN_DEFINE, ZBUS_LISTENER_DEFINE,
ZBUS_SUBSCRIBER_DEFINE, zbus_chan_pub/read/notify, ...) so that
existing Zephyr application code and documentation translate directly.
Original zbus by Rodrigo Peixoto (Apache-2.0); copyright preserved in
the derived files.

Ported features: listeners (synchronous callbacks), subscribers
(queue of channel references), message subscribers (ordered message
copies), async listeners (callback on the LP work queue), a deferred
ISR-safe publisher (ZBUS_ISR_PUBLISHER_DEFINE / zbus_isr_pub),
runtime observers, per-observation notification masks, observer
enable/disable, message validators, channel user data, publish
statistics, lookup by name/id and channel/observer iteration.

Everything is built on native NuttX primitives, with no compatibility
shim layer:

Zephyr	NuttX
k_sem channel lock + priority boost (HLP)	sem_t + native CONFIG_PRIORITY_INHERITANCE
k_msgq / k_fifo + net_buf pools	kernel message queues (file_mq_*), lazy-opened; mq payload copy replaces net_buf entirely
k_work	work_queue() (LP queue)
SYS_INIT	lazy init via pthread_once()
iterable sections	include/nuttx/iterable_sections.h (companion PR)
k_timeout_t	milliseconds, CLOCK_MONOTONIC deadlines (ZBUS_NO_WAIT / ZBUS_FOREVER)

Board integration (why one linker-script line matters here)

In Zephyr, zbus works on every board out of the box because boards have
no linker scripts: a single common per-arch linker template already
includes the shared common-rom.ld/common-ram.ld fragments where the
zbus iterable sections are collected. In NuttX each board owns its .ld,
so an adopting board needs one of:

• two #include <nuttx/linker/common-{rom,ram}.ld> lines in its board
  script (done for linum-stm32h753bi, the first adopter, in the
  companion PR), or
• CONFIG_ZBUS_LINKER_INSERT=y (zero-touch INSERT AFTER mode, with
  the MEMORY-region constraint documented in the companion PR).

This is documented in the Kconfig help, in README.rst and in the
Sphinx page added by the companion PR.

Also included:

• examples/zbus (CONFIG_EXAMPLES_ZBUS): a runnable demo with one channel,
  one listener, one subscriber, runtime masking.
• testing/zbus (CONFIG_TESTING_ZBUS): a cmocka suite, 16 tests
  covering the full API surface: pub/read/listener/subscriber,
  multi-channel index isolation, validators, message subscribers
  (ordered copies), bit-exact float/double payload delivery
  (sensor-style message with a float-math validator rejecting
  non-finite samples), claim/finish/notify, masks, enable/disable,
  runtime observers (error paths included), async listeners (bursts),
  ISR publisher, from_name/from_id, iteration, accessors, and
  timeout/overflow semantics.

Not ported (documented in the "Not ported" section of the docs):
multi-domain proxy agent (experimental upstream), direct publishing from
ISRs (the deferred zbus_isr_pub helper covers the use case), the
priority-boost/HLP scheme (superseded by native priority inheritance)
and the net_buf pool machinery (unnecessary with mq payload copies).

Impact

• New optional application (CONFIG_ZBUS, default n); no impact
  when disabled.
• Requirements: FLAT build (uses kernel-side file_mq_* so queues
  survive the creating task, since mqd_t is a per-task fd in NuttX);
  CONFIG_MQ_MAXMSGSIZE >= sizeof(pointer) + CONFIG_ZBUS_MSG_SUBSCRIBER_MAX_MSG_SIZE when message subscribers are
  enabled (checked and documented in Kconfig); board linker integration
  as described above.
• Build process: Make and CMake supported.
• Documentation: README.rst here; full Sphinx documentation (with
  the upstream zbus diagrams, Apache-2.0) lands with the companion
  nuttx PR.
• License: Apache-2.0, derived from Zephyr zbus; original copyright
  retained.

Testing

Host: Ubuntu 24.04.4 x86_64, Arm GNU Toolchain 13.2.rel1
(arm-none-eabi-gcc 13.2.1).

Target: linum-stm32h753bi:zbus (STM32H753BI; board configuration
added by the companion nuttx PR): CONFIG_ZBUS with all options
enabled (message/async/ISR observers, runtime observers),
CONFIG_EXAMPLES_ZBUS, CONFIG_TESTING_ZBUS. Flashed via ST-LINK V3;
console on the ST-LINK VCP.

nsh> uname -a
NuttX 13.0.1-RC0 a1b0941bec Aug 20 2026 21:17:15 arm linum-stm32h753bi

Example (zbus): 5 messages published; listener correctly skips the
masked message #4; listener notified before the subscriber (observer
priority order):

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 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

cmocka suite: 16/16 passing, run twice in the same boot (guards
against the lazy-init/fd-lifetime regression class):

nsh> cmocka_zbus_test
[==========] tests: Running 16 test(s).
...
[ RUN      ] test_float_payload
[       OK ] test_float_payload
...
[==========] tests: 16 test(s) run.
[  PASSED  ] 16 test(s).

(The could not notify observer: -42 line during test_timeouts is the
expected -ENOMSG queue-overflow path being exercised.)

Builds: Make (make -j) and CMake (cmake -GNinja + ninja) both
OK for the target config; _zbus_* iterable-section symbols verified in
the map on both. Stock build with CONFIG_ZBUS disabled: no zbus
sections/symbols (no-op). tools/checkpatch.sh -g on the commit: all
checks pass.

The companion nuttx PR adds a linum-stm32h753bi:zbus board
configuration reproducing this exact run
(./tools/configure.sh linum-stm32h753bi:zbus); since that defconfig
enables Kconfig symbols introduced here, the two PRs should land
together.

[linguini1]

Please add the Assisted-by field to your commit message to indicate AI use.

[xiaoxiang781216]

file can only be used by kernel

[xiaoxiang781216]

NuttX design is totally different from zephyr, but more like traditional POSIX OS, so it isn't suitable to port RTOS code blindly to userspace without the careful consideration. for example:

1. use file_mq API directly in userspace
2. access obs field from sender, or access chan field from receiver

if you want to port zbus without the significant architecture change, the only choice is put it into the kernel space.
or you can study uorb design to learn how to make a message subsystem work in the POSIX context:
https://nuttx.apache.org/docs/latest/applications/system/uorb/index.html
https://nuttx.apache.org/docs/latest/components/drivers/special/sensors/sensors_uorb.htmle
especially the usensor design: userspace sensor register implementation

[JorgeGzm]

The objection is correct: the code assumes every task shares one address space, which only holds in BUILD_FLAT. Passing a channel pointer between tasks, reading chan->message on the receiver, touching observer state from the publisher and calling file_mq_* from userspace all follow from that, and it has to be fixed.

My proposal is to fix it by declaring the scope rather than by moving the bus into the kernel: zbus as a process-local event bus, the threads of one application. That makes it POSIX only (mq_open() per task, sem_t, pthread_once()), takes struct file out of the public header, removes the global state opened by whichever task runs first, and no pointer ever crosses a process boundary.

Measured on an STM32H7 at 480 MHz with up_perf_gettime():

• publish to a synchronous listener: 4.4 us
• the same notification to a callback in another task: 16.2 us end to end

That is 3.7x, plus a context switch per message. [...] the cost is losing the synchronous callback, which is what zbus exists for, and a kernel-side bus cannot offer that callback to an application.

This is also what zbus is upstream. It has no CONFIG_USERSPACE support in Zephyr: supervisor mode, one address space, and the subscriber path passes the channel pointer through a msgq exactly as it does here. When a channel has to cross a domain, upstream adds an explicit forwarder (subsys/zbus/proxy_agent) instead of making the bus global.

[xiaoxiang781216]

it's wrong to open/modify ALL obs field from the first zbus task.