doc: zbus: add documentation for multi-domain zbus

Trond-F-Christiansen · Trond-F-Christiansen · commit 1f20007dcd7b · 2025-10-02T09:39:49.000+02:00
Add documentation for the multi-domain zbus feature, and multi-domain
zbus samples.

Signed-off-by: Trond F. Christiansen &lt;trond.christiansen@nordicsemi.no&gt;
diff --git a/doc/services/zbus/images/zbus_proxy_agent.png b/doc/services/zbus/images/zbus_proxy_agent.png
diff --git a/doc/services/zbus/index.rst b/doc/services/zbus/index.rst
@@ -878,6 +878,134 @@ illustrates the runtime registration usage.
   the channel observer it was first associated with through :c:func:`zbus_chan_rm_obs`.
 
 
+Multi-domain Communication
+***************************
+
+ZBus supports multi-domain communication, enabling message passing between different execution
+domains such as CPU cores or separate devices. This is achieved through proxy agents that
+forward messages between domains.
+
+.. figure:: images/zbus_proxy_agent.png
+    :alt: ZBus publish processing detail
+    :width: 75%
+
+..
+  Temporary image illustrating zbus multi-domain communication with proxy agents.
+
+Concepts
+========
+
+Multi-domain zbus introduces several key concepts:
+
+* **Master channels**: Channels where messages are published locally within a domain
+* **Shadow channels**: Read-only channels that mirror master channels from other domains
+* **Proxy agents**: Background services that synchronize channel data between domains
+* **Transport backends**: Communication mechanisms (IPC, UART) used by proxy agents
+
+The :c:macro:`ZBUS_MULTIDOMAIN_CHAN_DEFINE` macro enables conditional compilation to create
+master channels in one domain and corresponding shadow channels in other domains.
+
+Transport Backends
+==================
+
+ZBus multi-domain communication relies on transport backends to forward messages between different
+execution domains.
+
+IPC Backend
+-----------
+
+The IPC backend facilitates communication between CPU cores within the same system using
+Inter-Process Communication mechanisms.
+
+See the :zephyr:code-sample:`zbus-ipc-forwarder` sample for a complete implementation.
+
+UART Backend
+------------
+
+The UART backend enables communication between physically separate devices over serial connections.
+This backend extends zbus messaging across device boundaries, allowing distributed systems to
+maintain a unified message bus architecture.
+
+See the :zephyr:code-sample:`zbus-uart-forwarder` sample for a complete implementation.
+
+Usage
+=====
+
+Multi-domain zbus requires defining shared channels and setting up proxy agents. Here's a typical setup:
+
+**common.h** - Shared channel definitions:
+
+.. code-block:: c
+
+    #include <zephyr/zbus/zbus.h>
+    #include <zephyr/zbus/multidomain/zbus_multidomain.h>
+
+    struct request_data {
+        // ...
+    };
+
+    struct response_data {
+        // ...
+    };
+
+    ZBUS_MULTIDOMAIN_CHAN_DEFINE(request_channel, struct request_data,
+                                 NULL, NULL, ZBUS_OBSERVERS_EMPTY,
+                                 ZBUS_MSG_INIT(0),
+                                 IS_ENABLED(DOMAIN_A), /* Master on domain A */
+                                 1 /* Include on both domains */);
+
+    ZBUS_MULTIDOMAIN_CHAN_DEFINE(response_channel, struct response_data,
+                                 NULL, NULL, ZBUS_OBSERVERS_EMPTY,
+                                 ZBUS_MSG_INIT(0),
+                                 IS_ENABLED(DOMAIN_B), /* Master on domain B */
+                                 1 /* Include on both domains */);
+
+**Domain A** - Requester setup:
+
+.. code-block:: c
+
+    #define DOMAIN_A 1
+    #include "common.h"
+
+    /* Set up proxy agent and add channels for forwarding */
+    ZBUS_PROXY_AGENT_DEFINE(proxy_agent, ZBUS_MULTIDOMAIN_TYPE_IPC, ipc_instance);
+    ZBUS_PROXY_ADD_CHANNEL(proxy_agent, request_channel);
+
+    void response_listener_cb(const struct zbus_channel *chan) {
+        const struct response_data *resp = zbus_chan_const_msg(chan);
+        LOG_INF("Received response: ...");
+    }
+    ZBUS_LISTENER_DEFINE(response_listener, response_listener_cb);
+    ZBUS_CHAN_ADD_OBS(response_channel, response_listener, 0);
+
+    int main(void)
+    {
+        struct request_data req = { /* ... */ };
+        zbus_chan_pub(&request_channel, &req, K_MSEC(100));
+        return 0;
+    }
+
+**Domain B** - Responder setup:
+
+.. code-block:: c
+
+    #define DOMAIN_B 1
+    #include "common.h"
+
+    /* Set up proxy agent and add channels for forwarding */
+    ZBUS_PROXY_AGENT_DEFINE(proxy_agent, ZBUS_MULTIDOMAIN_TYPE_IPC, ipc_instance);
+    ZBUS_PROXY_ADD_CHANNEL(proxy_agent, response_channel);
+
+    /* Observe requests and publish responses */
+    void request_listener_cb(const struct zbus_channel *chan) {
+        const struct request_data *req = zbus_chan_const_msg(chan);
+        struct response_data resp = { /* ... */ };
+        zbus_chan_pub(&response_channel, &resp, K_MSEC(100));
+        LOG_INF("Processed request ...");
+    }
+    ZBUS_LISTENER_DEFINE(request_listener, request_listener_cb);
+    ZBUS_CHAN_ADD_OBS(request_channel, request_listener, 0);
+
 Samples
 *******
 
@@ -901,7 +1029,8 @@ available:
   observer registration feature;
 * :zephyr:code-sample:`zbus-confirmed-channel` implements a way of implement confirmed channel only
   with subscribers;
-* :zephyr:code-sample:`zbus-benchmark` implements a benchmark with different combinations of inputs.
+* :zephyr:code-sample:`zbus-ipc-forwarder` demonstrates multi-core communication using IPC forwarders;
+* :zephyr:code-sample:`zbus-uart-forwarder` demonstrates inter-device communication using UART forwarders.
 
 Suggested Uses
 **************
@@ -913,6 +1042,13 @@ subscribers (if you need a thread) or listeners (if you need to be lean and fast
 the listener, another asynchronous message processing mechanism (like :ref:`message queues
 <message_queues_v2>`) may be necessary to retain the pending message until it gets processed.
 
+For multi-domain scenarios, use zbus to enable communication across execution boundaries:
+
+* **Multi-core systems**: Use IPC backend to coordinate between application and network processors,
+  or distribute workloads across multiple CPU cores.
+* **Distributed devices**: Use UART backend to create distributed applications where multiple
+  connected devices participate in the same logical message bus over serial connections.
+
 .. note::
    ZBus can be used to transfer streams from the producer to the consumer. However, this can
    increase zbus' communication latency. So maybe consider a Pipe a good alternative for this
@@ -954,6 +1090,30 @@ Related configuration options:
   observers to statically allocate.
 * :kconfig:option:`CONFIG_ZBUS_RUNTIME_OBSERVERS_NODE_ALLOC_NONE` use user-provided runtime
   observers nodes;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN` enable multi-domain communication support.
+
+Multi-domain Configuration Options
+==================================
+
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_IPC` enable IPC backend for multi-domain communication;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_UART` enable UART backend for multi-domain communication;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_LOG_LEVEL` set the log level for multi-domain operations;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_MESSAGE_SIZE` maximum message size for multi-domain
+  channels;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_CHANNEL_NAME_SIZE` maximum size of channel names in
+  multi-domain communication;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_PROXY_STACK_SIZE` stack size for proxy agent threads;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_PROXY_PRIORITY` priority of proxy agent threads;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_SENT_MSG_POOL_SIZE` number of sent messages to track for
+  acknowledgments;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_MAX_TRANSMIT_ATTEMPTS` maximum retry attempts for message
+  transmission;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_SENT_MSG_ACK_TIMEOUT` initial acknowledgment timeout for
+  sent messages;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_SENT_MSG_ACK_TIMEOUT_MAX` maximum acknowledgment timeout
+  for exponential backoff;
+* :kconfig:option:`CONFIG_ZBUS_MULTIDOMAIN_UART_BUF_COUNT` number of UART buffers for multi-domain
+  communication;
 
 API Reference
 *************
diff --git a/samples/subsys/zbus/ipc_forwarder/README.rst b/samples/subsys/zbus/ipc_forwarder/README.rst
@@ -0,0 +1,87 @@
+.. zephyr:code-sample:: zbus-ipc-forwarder
+   :name: zbus Proxy agent - IPC forwarder
+   :relevant-api: zbus_apis
+
+   Forward zbus messages between different domains using IPC.
+
+Overview
+********
+This sample demonstrates zbus inter-domain communication on multi-core platforms.
+The sample implements a request-response pattern where:
+
+- The **application CPU** acts as a requester, publishing requests on a master channel and receiving responses on a shadow channel
+- The **remote CPU** acts as a responder, receiving requests on a shadow channel and publishing responses on a master channel
+- **IPC forwarders** automatically synchronize channel data between CPU domains using the zbus proxy functionality
+
+The ``common/common.h`` file defines shared channels using :c:macro:`ZBUS_MULTIDOMAIN_CHAN_DEFINE` with conditional
+compilation to create master channels on one domain and shadow channels on the other.
+
+This architecture enables message passing between different CPU cores while maintaining zbus's
+publish-subscribe structure across domain boundaries.
+
+Building and Running
+********************
+
+Use sysbuild to build this sample for multi-core platforms:
+
+For nRF54H20 with CPURAD:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/zbus/ipc_forwarder
+   :board: nrf54h20dk/nrf54h20/cpuapp
+   :goals: build
+   :west-args: --sysbuild -S nordic-log-stm
+
+It can also be built for the other cores in the nRF54H20 using sysbuild configurations:
+
+.. code-block::
+
+   SB_CONFIG_REMOTE_BOARD_NRF54H20_CPURAD=y # Default
+   SB_CONFIG_REMOTE_BOARD_NRF54H20_CPUPPR=y
+   SB_CONFIG_REMOTE_BOARD_NRF54H20_CPUPPR_XIP=y
+   SB_CONFIG_REMOTE_BOARD_NRF54H20_CPUFLPR_XIP=y
+
+For nRF5340:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/zbus/ipc_forwarder
+   :board: nrf5340dk/nrf5340/cpuapp
+   :goals: build
+   :west-args: --sysbuild
+
+Sample Output
+*************
+
+Application CPU Output
+======================
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build v4.2.0-1157-gaaa3626d8206 ***
+   <inf> main: ZBUS Multidomain IPC Forwarder Sample Application
+   <inf> main: Channel request_channel is a master channel
+   <inf> main: Channel response_channel is a shadow channel
+   <inf> main: Published on channel request_channel. Request ID=1, Min=-1, Max=1
+   <inf> main: Received message on channel response_channel
+   <inf> main: Response ID: 1, Value: 0
+   <inf> main: Published on channel request_channel. Request ID=2, Min=-2, Max=2
+   <inf> main: Received message on channel response_channel
+   <inf> main: Response ID: 2, Value: -1
+
+Remote CPU Output
+=================
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build v4.2.0-1157-gaaa3626d8206 ***
+   <inf> main: ZBUS Multidomain IPC Forwarder Sample Application
+   <inf> main: Channel request_channel is a shadow channel
+   <inf> main: Channel response_channel is a master channel
+   <inf> main: Received message on channel request_channel
+   <inf> main: Request ID: 1, Min: -1, Max: 1
+   <inf> main: Sending response: ID=1, Value=0
+   <inf> main: Response published on channel response_channel
+   <inf> main: Received message on channel request_channel
+   <inf> main: Request ID: 2, Min: -2, Max: 2
+   <inf> main: Sending response: ID=2, Value=-1
+   <inf> main: Response published on channel response_channel
diff --git a/samples/subsys/zbus/uart_forwarder/README.rst b/samples/subsys/zbus/uart_forwarder/README.rst
@@ -0,0 +1,85 @@
+.. zephyr:code-sample:: zbus-uart-forwarder
+   :name: zbus Proxy agent - UART forwarder
+   :relevant-api: zbus_apis
+
+   Forward zbus messages between different devices using UART.
+
+Overview
+********
+This sample demonstrates zbus inter-device communication using UART forwarders between separate devices.
+The sample implements a request-response pattern where:
+
+- **Device A** acts as a requester, publishing requests on a master channel and receiving responses on a shadow channel
+- **Device B** acts as a responder, receiving requests on a shadow channel and publishing responses on a master channel
+- **UART forwarders** automatically synchronize channel data between devices using the zbus proxy functionality over UART
+
+The ``common/common.h`` file defines shared channels using :c:macro:`ZBUS_MULTIDOMAIN_CHAN_DEFINE` with conditional
+compilation to create master channels on one device and shadow channels on the other.
+
+This architecture enables message passing between different devices while maintaining zbus's
+publish-subscribe structure across device boundaries.
+
+Building and Running
+********************
+
+This sample requires two separate devices connected via UART. Each device runs a different application:
+
+For Device A (Requester):
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/zbus/uart_forwarder/dev_a
+   :board: nrf5340dk/nrf5340/cpuapp
+   :goals: build flash
+
+For Device B (Responder):
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/zbus/uart_forwarder/dev_b
+   :board: nrf5340dk/nrf5340/cpuapp
+   :goals: build flash
+
+Hardware Setup
+==============
+
+Connect the two devices via UART:
+
+- Device A TX → Device B RX
+- Device A RX → Device B TX
+- Connect GND between devices
+
+Sample Output
+=============
+
+Device A Output (Requester)
+****************************
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build v4.2.0-1157-g7bf51d719a31 ***
+   <inf> main: ZBUS Multidomain UART Forwarder Sample Application
+   <inf> main: Channel request_channel is a master channel
+   <inf> main: Channel response_channel is a shadow channel
+   <inf> main: Published on channel request_channel. Request ID=1, Min=-1, Max=1
+   <inf> main: Received message on channel response_channel
+   <inf> main: Response ID: 1, Value: 1
+   <inf> main: Published on channel request_channel. Request ID=2, Min=-2, Max=2
+   <inf> main: Received message on channel response_channel
+   <inf> main: Response ID: 2, Value: 0
+
+Device B Output (Responder)
+****************************
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build v4.2.0-1157-g7bf51d719a31 ***
+   <inf> main: ZBUS Multidomain UART Forwarder Sample Application
+   <inf> main: Channel request_channel is a shadow channel
+   <inf> main: Channel response_channel is a master channel
+   <inf> main: Received message on channel request_channel
+   <inf> main: Request ID: 1, Min: -1, Max: 1
+   <inf> main: Sending response: ID=1, Value=1
+   <inf> main: Response published on channel response_channel
+   <inf> main: Received message on channel request_channel
+   <inf> main: Request ID: 2, Min: -2, Max: 2
+   <inf> main: Sending response: ID=2, Value=-1
+   <inf> main: Response published on channel response_channel
