zbus: add multidomain support infrastructure

Trond-F-Christiansen · Trond-F-Christiansen · commit 5610a02fc1c5 · 2025-09-17T15:50:06.000+02:00
Add core multidomain support to ZBus, enabling communication between
separate domains. This includes:

- New shadow channel concept with is_shadow_channel flag
- ZBUS_SHADOW_CHAN_DEFINE macros for defining shadow channels
- ZBUS_MULTIDOMAIN_CHAN_DEFINE for conditional channel definitions
- ZBUS_CHANNEL_IS_SHADOW macro for checking shadow status
- ZBUS_CHANNEL_IS_MASTER macro for checking master status
- zbus_chan_pub_shadow() for internal shadow channel publishing
- Protection against publishing to shadow channels from application code
- Configuration options for multidomain support

Shadow channels represent channels defined in other domains, allowing
observation without direct publishing. The multidomain macros enable
shared channel definitions that create master channels in one domain
and shadow channels in others.

Signed-off-by: Trond F. Christiansen &lt;trond.christiansen@nordicsemi.no&gt;
diff --git a/include/zephyr/zbus/zbus.h b/include/zephyr/zbus/zbus.h
@@ -109,6 +109,16 @@ struct zbus_channel {
 
 	/** Mutable channel data struct. */
 	struct zbus_channel_data *data;
+
+#if defined(CONFIG_ZBUS_MULTIDOMAIN) || defined(__DOXYGEN__)
+
+	/** Indicates if the channel is a shadow channel.
+	 * A shadow channel is a channel that should not be used directly, but rather
+	 * shadows another channel, usually one that is defined in another domain.
+	 */
+	bool is_shadow_channel;
+
+#endif /* CONFIG_ZBUS_MULTIDOMAIN */
 };
 
 /**
@@ -275,7 +285,7 @@ struct zbus_channel_observation {
 #define _ZBUS_MESSAGE_NAME(_name) _CONCAT(_zbus_message_, _name)
 
 /* clang-format off */
-#define _ZBUS_CHAN_DEFINE(_name, _id, _type, _validator, _user_data)                               \
+#define _ZBUS_CHAN_DEFINE(_name, _id, _type, _validator, _user_data, _is_shadow)                   \
 	static struct zbus_channel_data _CONCAT(_zbus_chan_data_, _name) = {                       \
 		.observers_start_idx = -1,                                                         \
 		.observers_end_idx = -1,                                                           \
@@ -295,6 +305,7 @@ struct zbus_channel_observation {
 		.user_data = _user_data,                                                           \
 		.validator = _validator,                                                           \
 		.data = &_CONCAT(_zbus_chan_data_, _name),                                         \
+		IF_ENABLED(CONFIG_ZBUS_MULTIDOMAIN, (.is_shadow_channel = _is_shadow,))            \
 		IF_ENABLED(ZBUS_MSG_SUBSCRIBER_NET_BUF_POOL_ISOLATION,                             \
 			   (.msg_subscriber_pool = &_zbus_msg_subscribers_pool,))                  \
 	}
@@ -388,12 +399,46 @@ struct zbus_channel_observation {
  */
 #define ZBUS_CHAN_DEFINE(_name, _type, _validator, _user_data, _observers, _init_val)              \
 	static _type _ZBUS_MESSAGE_NAME(_name) = _init_val;                                        \
-	_ZBUS_CHAN_DEFINE(_name, ZBUS_CHAN_ID_INVALID, _type, _validator, _user_data);             \
+	_ZBUS_CHAN_DEFINE(_name, ZBUS_CHAN_ID_INVALID, _type, _validator, _user_data, false);      \
+	/* Extern declaration of observers */                                                      \
+	ZBUS_OBS_DECLARE(_observers);                                                              \
+	/* Create all channel observations from observers list */                                  \
+	FOR_EACH_FIXED_ARG_NONEMPTY_TERM(_ZBUS_CHAN_OBSERVATION, (;), _name, _observers)
+
+#if defined(CONFIG_ZBUS_MULTIDOMAIN) || defined(__DOXYGEN__)
+
+/**
+ * @brief Zbus shadow channel definition.
+ *
+ * This macro defines a shadow channel.
+ * Similar to ZBUS_CHAN_DEFINE, but defines the channel with the
+ * is_shadow_channel flag set to true, blocking the channel from
+ * being published to normally.
+ *
+ * @param _name The channel's name.
+ * @param _type The Message type. It must be a struct or union.
+ * @param _validator The validator function.
+ * @param _user_data A pointer to the user data.
+ *
+ * @see struct zbus_channel
+ * @param _observers The observers list. The sequence indicates the priority of the observer. The
+ * first the highest priority.
+ * @param _init_val The message initialization.
+ *
+ * @note This macro is used to define shadow channels in a multi-domain setup.
+ * Shadow channels are used to represent channels that are defined in another domain, allowing
+ * the current domain to observe them without directly publishing to them.
+ */
+#define ZBUS_SHADOW_CHAN_DEFINE(_name, _type, _validator, _user_data, _observers, _init_val)       \
+	static _type _ZBUS_MESSAGE_NAME(_name) = _init_val;                                        \
+	_ZBUS_CHAN_DEFINE(_name, ZBUS_CHAN_ID_INVALID, _type, _validator, _user_data, true);       \
 	/* Extern declaration of observers */                                                      \
 	ZBUS_OBS_DECLARE(_observers);                                                              \
 	/* Create all channel observations from observers list */                                  \
 	FOR_EACH_FIXED_ARG_NONEMPTY_TERM(_ZBUS_CHAN_OBSERVATION, (;), _name, _observers)
 
+#endif /* CONFIG_ZBUS_MULTIDOMAIN */
+
 /**
  * @brief Zbus channel definition with numeric identifier.
  *
@@ -412,12 +457,133 @@ struct zbus_channel_observation {
  */
 #define ZBUS_CHAN_DEFINE_WITH_ID(_name, _id, _type, _validator, _user_data, _observers, _init_val) \
 	static _type _ZBUS_MESSAGE_NAME(_name) = _init_val;                                        \
-	_ZBUS_CHAN_DEFINE(_name, _id, _type, _validator, _user_data);                              \
+	_ZBUS_CHAN_DEFINE(_name, _id, _type, _validator, _user_data, false);                       \
 	/* Extern declaration of observers */                                                      \
 	ZBUS_OBS_DECLARE(_observers);                                                              \
 	/* Create all channel observations from observers list */                                  \
 	FOR_EACH_FIXED_ARG_NONEMPTY_TERM(_ZBUS_CHAN_OBSERVATION, (;), _name, _observers)
 
+#if defined(CONFIG_ZBUS_MULTIDOMAIN) || defined(__DOXYGEN__)
+
+/**
+ * @brief Zbus shadow channel definition.
+ *
+ * This macro defines a shadow channel.
+ * Similar to ZBUS_CHAN_DEFINE, but defines the channel with the
+ * is_shadow_channel flag set to true, blocking the channel from
+ * being published to normally.
+ *
+ * @param _name The channel's name.
+ * @param _id The channel's unique numeric identifier.
+ * @param _type The Message type. It must be a struct or union.
+ * @param _validator The validator function.
+ * @param _user_data A pointer to the user data.
+ *
+ * @see struct zbus_channel
+ * @param _observers The observers list. The sequence indicates the priority of the observer. The
+ * first the highest priority.
+ * @param _init_val The message initialization.
+ *
+ * @note This macro is used to define shadow channels in a multi-domain setup.
+ * Shadow channels are used to represent channels that are defined in another domain, allowing
+ * the current domain to observe them without directly publishing to them.
+ */
+#define ZBUS_SHADOW_CHAN_DEFINE_WITH_ID(_name, _id, _type, _validator, _user_data, _observers,     \
+					_init_val)                                                 \
+	static _type _ZBUS_MESSAGE_NAME(_name) = _init_val;                                        \
+	_ZBUS_CHAN_DEFINE(_name, _id, _type, _validator, _user_data, true);                        \
+	/* Extern declaration of observers */                                                      \
+	ZBUS_OBS_DECLARE(_observers);                                                              \
+	/* Create all channel observations from observers list */                                  \
+	FOR_EACH_FIXED_ARG_NONEMPTY_TERM(_ZBUS_CHAN_OBSERVATION, (;), _name, _observers)
+
+/**
+ * @brief Macro to check if a channel is a shadow channel.
+ *
+ * @param _chan The channel to check.
+ * @return true if the channel is a shadow channel, false otherwise.
+ */
+#define ZBUS_CHANNEL_IS_SHADOW(_chan) ((_chan)->is_shadow_channel)
+
+/**
+ * @brief Macro to check if a channel is a master channel.
+ *
+ * @param _chan The channel to check.
+ * @return true if the channel is a master channel, false if it is a shadow channel.
+ */
+#define ZBUS_CHANNEL_IS_MASTER(_chan) (!(_chan)->is_shadow_channel)
+
+/**
+ * @brief Zbus multi-domain channel definition.
+ *
+ * This macro defines a channel that can be either a master or a shadow channel based on the
+ * is_master and is_included flags. If is_master is true, it defines a normal channel, otherwise
+ * it defines a shadow channel. If is_included is false, the channel will not be defined at all.
+ * Intended usage is in a shared header in multi-domain setups where the channel is defined in
+ * one domain and shadowed in others, using device specific defines to control the inclusion
+ * and master status.
+ *
+ * @param _name The channel's name.
+ * @param _type The Message type. It must be a struct or union.
+ * @param _validator The validator function.
+ * @param _user_data A pointer to the user data.
+ * @param _observers The observers list. The sequence indicates the priority of the observer. The
+ * first the highest priority.
+ * @param _init_val The message initialization.
+ * @param _is_master Indicates if this is the master channel (true) or a shadow channel (false).
+ * @param _is_included Indicates if the channel should be included in this device (true) or not
+ * (false).
+ *
+ * @note This macro is used to define channels in a multi-domain setup where the channel can be
+ * either a master channel or a shadow channel, depending on the device configuration.
+ */
+#define ZBUS_MULTIDOMAIN_CHAN_DEFINE(_name, _type, _validator, _user_data, _observers, _init_val,  \
+				     _is_master, _is_included)                                     \
+	COND_CODE_1(_is_included,                                                                  \
+		(COND_CODE_1(_is_master,                                                           \
+			(ZBUS_CHAN_DEFINE(_name, _type, _validator, _user_data, _observers,	   \
+					  _init_val)),                                             \
+			(ZBUS_SHADOW_CHAN_DEFINE(_name, _type, _validator, _user_data, _observers, \
+						 _init_val)))),                                    \
+		(/* Channel not included on this device - no definition*/))
+
+/**
+ * @brief Zbus multi-domain channel definition with ID.
+ *
+ * This macro defines a channel that can be either a master or a shadow channel based on the
+ * is_master and is_included flags. If is_master is true, it defines a normal channel with a unique
+ * ID, otherwise it defines a shadow channel with the same ID. If is_included is false, the channel
+ * will not be defined at all. Intended usage is in a shared header in multi-domain setups where the
+ * channel is defined in one domain and shadowed in others, using device specific defines to control
+ * the inclusion and master status.
+ *
+ * @param _name The channel's name.
+ * @param _id The channel's unique numeric identifier.
+ * @param _type The Message type. It must be a struct or union.
+ * @param _validator The validator function.
+ * @param _user_data A pointer to the user data.
+ * @param _observers The observers list. The sequence indicates the priority of the observer. The
+ * first the highest priority.
+ * @param _init_val The message initialization.
+ * @param _is_master Indicates if this is the master channel (true) or a shadow channel (false).
+ * @param _is_included Indicates if the channel should be included in this device (true) or not
+ * (false).
+ *
+ * @note This macro is used to define channels in a multi-domain setup where the channel can be
+ * either a master channel or a shadow channel, depending on the device configuration.
+ */
+#define ZBUS_MULTIDOMAIN_CHAN_DEFINE_WITH_ID(_name, _id, _type, _validator, _user_data,            \
+					     _observers, _init_val, _is_master, _is_included)      \
+	COND_CODE_1(_is_included,                                                                  \
+		(COND_CODE_1(_is_master,                                                           \
+			(ZBUS_CHAN_DEFINE_WITH_ID(_name, _id, _type, _validator, _user_data,       \
+						  _observers, _init_val)),                         \
+			(ZBUS_SHADOW_CHAN_DEFINE_WITH_ID(_name, _id, _type, _validator, _user_data,\
+							 _observers, _init_val)))),                \
+		(/* Channel not included on this device - no definition*/))
+
+#endif /* CONFIG_ZBUS_MULTIDOMAIN */
+
 /**
  * @brief Initialize a message.
  *
@@ -575,9 +741,46 @@ struct zbus_channel_observation {
  * @retval -EFAULT A parameter is incorrect, the notification could not be sent to one or more
  * observer, or the function context is invalid (inside an ISR). The function only returns this
  * value when the @kconfig{CONFIG_ZBUS_ASSERT_MOCK} is enabled.
+ * @retval -EPERM Attempt to publish a shadow channel. Shadow channels can only be published to
+ * via the zbus_chan_pub_shadow function. The function only returns this value when the
+ * @kconfig{CONFIG_ZBUS_MULTIDOMAIN} is enabled.
  */
 int zbus_chan_pub(const struct zbus_channel *chan, const void *msg, k_timeout_t timeout);
 
+#if defined(CONFIG_ZBUS_MULTIDOMAIN)
+
+/** @cond INTERNAL_HIDDEN */
+
+/**
+ * @brief Publish to a shadow channel
+ *
+ * This routine publishes a message to a shadow channel.
+ *
+ * @param chan The channel's reference.
+ * @param msg Reference to the message where the publish function copies the channel's
+ * message data from.
+ * @param timeout Waiting period to publish the channel,
+ *                or one of the special values K_NO_WAIT and K_FOREVER.
+ *
+ * @retval 0 Channel published.
+ * @retval -ENOMSG The message is invalid based on the validator function or some of the
+ * observers could not receive the notification.
+ * @retval -EBUSY The channel is busy.
+ * @retval -EAGAIN Waiting period timed out.
+ * @retval -EFAULT A parameter is incorrect, the notification could not be sent to one or more
+ * observer, or the function context is invalid (inside an ISR). The function only returns this
+ * value when the @kconfig{CONFIG_ZBUS_ASSERT_MOCK} is enabled.
+ *
+ * @note This function is used to publish messages to shadow channels in a multi-domain setup,
+ * and should not be used by application logic directly. It is intended for internal use to
+ * handle shadow channels.
+ */
+int zbus_chan_pub_shadow(const struct zbus_channel *chan, const void *msg, k_timeout_t timeout);
+
+/** @endcond */
+
+#endif /* CONFIG_ZBUS_MULTIDOMAIN */
+
 /**
  * @brief Read a channel
  *
diff --git a/subsys/zbus/Kconfig b/subsys/zbus/Kconfig
@@ -107,6 +107,13 @@ config ZBUS_ASSERT_MOCK
 	  enabled, _ZBUS_ASSERT returns -EFAULT instead of assert. It makes it more straightforward to test invalid
 	  parameters.
 
+config ZBUS_MULTIDOMAIN
+	bool "ZBus multidomain support"
+	select ZBUS_MSG_SUBSCRIBER
+	select ZBUS_CHANNEL_NAME
+	help
+	  Enables support for ZBus multidomain. This feature allows the ZBus to work with multiple domains,
+	  enabling communication between them.
 
 config HEAP_MEM_POOL_ADD_SIZE_ZBUS
 	int "ZBus requested heap pool size."
diff --git a/subsys/zbus/zbus.c b/subsys/zbus/zbus.c
@@ -403,6 +403,18 @@ int zbus_chan_pub(const struct zbus_channel *chan, const void *msg, k_timeout_t
 	_ZBUS_ASSERT(k_is_in_isr() ? K_TIMEOUT_EQ(timeout, K_NO_WAIT) : true,
 		     "inside an ISR, the timeout must be K_NO_WAIT");
 
+#if defined(CONFIG_ZBUS_MULTIDOMAIN)
+
+	/* Normal publish to a shadow channel is not allowed from application logic. */
+	if (chan->is_shadow_channel) {
+		LOG_ERR("Channel is defined as shadow. Cannot publish to shadow channel %s from "
+			"application logic, only from ZBUS proxy agent",
+			_ZBUS_CHAN_NAME(chan));
+		return -EPERM;
+	}
+
+#endif /* CONFIG_ZBUS_MULTIDOMAIN */
+
 	if (k_is_in_isr()) {
 		timeout = K_NO_WAIT;
 	}
@@ -434,6 +446,57 @@ int zbus_chan_pub(const struct zbus_channel *chan, const void *msg, k_timeout_t
 	return err;
 }
 
+#if defined(CONFIG_ZBUS_MULTIDOMAIN)
+
+int zbus_chan_pub_shadow(const struct zbus_channel *chan, const void *msg, k_timeout_t timeout)
+{
+	int err;
+
+	_ZBUS_ASSERT(chan != NULL, "chan is required");
+	_ZBUS_ASSERT(msg != NULL, "msg is required");
+	_ZBUS_ASSERT(k_is_in_isr() ? K_TIMEOUT_EQ(timeout, K_NO_WAIT) : true,
+		     "inside an ISR, the timeout must be K_NO_WAIT");
+
+	if (!chan->is_shadow_channel) {
+		/* Shadow publish to a non-shadow channel is not allowed */
+		LOG_ERR("Channel is not defined as shadow. Cannot publish to non-shadow channel %s",
+			_ZBUS_CHAN_NAME(chan));
+		return -EPERM;
+	}
+
+	if (k_is_in_isr()) {
+		timeout = K_NO_WAIT;
+	}
+
+	k_timepoint_t end_time = sys_timepoint_calc(timeout);
+
+	if (chan->validator != NULL && !chan->validator(msg, chan->message_size)) {
+		return -ENOMSG;
+	}
+
+	int context_priority = ZBUS_MIN_THREAD_PRIORITY;
+
+	err = chan_lock(chan, timeout, &context_priority);
+	if (err) {
+		return err;
+	}
+
+#if defined(CONFIG_ZBUS_CHANNEL_PUBLISH_STATS)
+	chan->data->publish_timestamp = k_uptime_ticks();
+	chan->data->publish_count += 1;
+#endif
+
+	memcpy(chan->message, msg, chan->message_size);
+
+	err = _zbus_vded_exec(chan, end_time);
+
+	chan_unlock(chan, context_priority);
+
+	return err;
+}
+
+#endif /* CONFIG_ZBUS_MULTIDOMAIN */
+
 int zbus_chan_read(const struct zbus_channel *chan, void *msg, k_timeout_t timeout)
 {
 	_ZBUS_ASSERT(chan != NULL, "chan is required");
