From 70ff2d8a9b1c0307ab2ebe7bf6e6eec526c25ea0 Mon Sep 17 00:00:00 2001 From: Jordan Yates Date: Wed, 22 Jan 2025 09:15:36 +1000 Subject: [PATCH] doc: zbus: document `ZBUS_CHAN_DEFINE_WITH_ID` Add documentation for the `ZBUS_CHAN_DEFINE_WITH_ID` feature. Signed-off-by: Jordan Yates --- doc/services/zbus/index.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/services/zbus/index.rst b/doc/services/zbus/index.rst index 1cc053ce75d7..0473d7157083 100644 --- a/doc/services/zbus/index.rst +++ b/doc/services/zbus/index.rst @@ -636,6 +636,34 @@ the defined channels and observers. ZBUS_CHAN_DECLARE(acc_chan, version_chan); +Unique channel identifiers +-------------------------- + +To simplify integrations with external entities, it is possible to assign a unique numeric identifier +to a channel. Users can then retrieve the channel reference by using the identifier with +:c:func:`zbus_chan_from_id`, rather than needing to obtain the reference at compile time with +:c:macro:`ZBUS_CHAN_DECLARE`. Channels using this feature are declared with +:c:func:`ZBUS_CHAN_DEFINE_WITH_ID`. + +.. code-block:: c + + ZBUS_CHAN_DEFINE_WITH_ID(control_chan, /* Name */ + 0x12345678, /* Unique channel identifier */ + struct control_msg, /* Message type */ + control_validator, /* Validator */ + &message_count, /* User data */ + ZBUS_OBSERVERS_EMPTY, /* observers */ + ZBUS_MSG_INIT(.move = 0) /* Initial value */ + ); + + static void channel_retrieve(void) + { + const struct zbus_channel *chan = zbus_chan_from_id(0x12345678); + + ... + } + + Iterating over channels and observers =====================================