You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Usage of numfig=True option in conf.py significantly increases doc build
time. While it is a nice feature, it's not extensively used in Zephyr
documentation, so let's remove its usage in favor of faster doc builds.
Signed-off-by: Gerard Marull-Paretas <[email protected]>
Copy file name to clipboardExpand all lines: doc/services/zbus/index.rst
+8-14Lines changed: 8 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,39 +12,36 @@ The :dfn:`Zephyr message bus - Zbus` is a lightweight and flexible message bus e
12
12
Concepts
13
13
********
14
14
15
-
Threads can broadcast messages to all interested observers using zbus. Many-to-many communication is possible. The bus implements message-passing and publish/subscribe communication paradigms that enable threads to communicate synchronously or asynchronously through shared memory. The communication through zbus is channel-based, where threads publish and read to and from using messages. Additionally, threads can observe channels and receive notifications from the bus when the channels are modified. :numref:`zbus common` shows an example of a typical application using zbus in which the application logic (hardware independent) talks to other threads via message bus. Note that the threads are decoupled from each other because they only use zbus' channels and do not need to know each other to talk.
15
+
Threads can broadcast messages to all interested observers using zbus. Many-to-many communication is possible. The bus implements message-passing and publish/subscribe communication paradigms that enable threads to communicate synchronously or asynchronously through shared memory. The communication through zbus is channel-based, where threads publish and read to and from using messages. Additionally, threads can observe channels and receive notifications from the bus when the channels are modified. The figure below shows an example of a typical application using zbus in which the application logic (hardware independent) talks to other threads via message bus. Note that the threads are decoupled from each other because they only use zbus' channels and do not need to know each other to talk.
16
16
17
17
18
-
.. _zbus common:
19
18
.. figure:: images/zbus_overview.svg
20
19
:alt:zbus usage overview
21
20
:width:75%
22
21
23
22
A typical zbus application architecture.
24
23
25
-
:numref:`zbus anatomy` illustrates zbus' anatomy. The bus comprises:
24
+
The bus comprises:
26
25
27
26
* Set of channels that consists of a unique identifier, its control metadata information, and the message itself;
28
27
* :dfn:`Virtual distributed event dispatcher` (VDED), the bus logic responsible for sending notifications to the observers. The VDED logic runs inside the publishing action in the same thread context, giving the bus an idea of a distributed execution. When a thread publishes to a channel, it also propagates the notifications to the observers;
29
28
* Threads (subscribers) and callbacks (listeners) publishing, reading, and receiving notifications from the bus.
30
29
31
-
.. _zbus anatomy:
32
30
.. figure:: images/zbus_anatomy.svg
33
31
:alt:Zbus anatomy
34
32
:width:70%
35
33
36
-
Zbus internals details.
34
+
Zbus anatomy.
37
35
38
36
The bus makes the publish, read, and subscribe actions available over channels. Publishing and reading are available in all RTOS thread contexts. However, it cannot run inside Interrupt Service Routines (ISR) because it uses mutexes to control channels access, and mutexes cannot work appropriately inside ISRs. The publish and read operations are simple and fast; the procedure is a mutex locking followed by a memory copy to and from a shared memory region and then a mutex unlocking. Another essential aspect of zbus is the observers, which can be:
39
37
40
38
* Static; defined in compile time. It is not possible to remove it at runtime, but it is possible to suppress it by calling the :c:func:`zbus_obs_set_enable`;
41
39
* Dynamic; it can be added and removed to and from a channel at runtime.
42
40
43
41
44
-
For illustration purposes, suppose a usual sensor-based solution in :numref:`zbus operations`. When the timer is triggered, it pushes an action to a work queue that publishes to the ``Start trigger`` channel. As the sensor thread subscribed to the ``Start trigger`` channel, it fetches the sensor data. Notice the VDED executes the blink callback because it also listens to the ``Start trigger`` channel. When the sensor data is ready, the sensor thread publishes it to the ``Sensor data`` channel. The core thread, as a ``Sensor data`` channel subscriber, processes the sensor data and stores it in an internal sample buffer. It repeats until the sample buffer is full; when it happens, the core thread aggregates the sample buffer information, prepares a package, and publishes that to the ``Payload`` channel. The Lora thread receives that because it is a ``Payload`` channel subscriber and sends the payload to the cloud. When it completes the transmission, the Lora thread publishes to the ``Transmission done`` channel. The VDED executes the blink callback again since it listens to the ``Transmission done`` channel.
42
+
For illustration purposes, suppose a usual sensor-based solution in the figure below. When the timer is triggered, it pushes an action to a work queue that publishes to the ``Start trigger`` channel. As the sensor thread subscribed to the ``Start trigger`` channel, it fetches the sensor data. Notice the VDED executes the blink callback because it also listens to the ``Start trigger`` channel. When the sensor data is ready, the sensor thread publishes it to the ``Sensor data`` channel. The core thread, as a ``Sensor data`` channel subscriber, processes the sensor data and stores it in an internal sample buffer. It repeats until the sample buffer is full; when it happens, the core thread aggregates the sample buffer information, prepares a package, and publishes that to the ``Payload`` channel. The Lora thread receives that because it is a ``Payload`` channel subscriber and sends the payload to the cloud. When it completes the transmission, the Lora thread publishes to the ``Transmission done`` channel. The VDED executes the blink callback again since it listens to the ``Transmission done`` channel.
45
43
46
44
47
-
.. _zbus operations:
48
45
.. figure:: images/zbus_operations.svg
49
46
:alt:Zbus sensor-based application
50
47
:width:80%
@@ -73,9 +70,8 @@ The VDED execution always happens in the publishing's (thread) context. So it ca
73
70
* At last, the publishing function unlocks the channel.
74
71
75
72
76
-
To illustrate the VDED execution, consider the example the :numref:`zbus vded scenario` shows. We have four threads in ascending priority T1, T2, T3, and T4 (the highest priority); two listeners, L1 and L2; and channel A. Suposing L1, L2, T2, T3, and T4 observer channel A.
73
+
To illustrate the VDED execution, consider the example illustrated below. We have four threads in ascending priority T1, T2, T3, and T4 (the highest priority); two listeners, L1 and L2; and channel A. Suposing L1, L2, T2, T3, and T4 observer channel A.
@@ -97,10 +93,9 @@ The following code implements channel A. Note the ``struct a_msg`` is illustrati
97
93
);
98
94
99
95
100
-
In :numref:`zbus vded`, the letters indicate some action related to the VDED execution. The X-axis represents the time, and the Y-axis represents the priority of threads. Channel A's message, represented by a voice balloon, is only one memory portion (shared memory). It appears several times only as an illustration of the message at that point in time.
96
+
In the figure below, the letters indicate some action related to the VDED execution. The X-axis represents the time, and the Y-axis represents the priority of threads. Channel A's message, represented by a voice balloon, is only one memory portion (shared memory). It appears several times only as an illustration of the message at that point in time.
@@ -109,10 +104,9 @@ In :numref:`zbus vded`, the letters indicate some action related to the VDED exe
109
104
110
105
111
106
112
-
The :numref:`zbus vded` illustrates the actions performed during the VDED execution when T1 publishes to channel A. Thus, :numref:`zbus vded table` describes the actions (represented by a letter) of the VDED execution.
107
+
The figure above illustrates the actions performed during the VDED execution when T1 publishes to channel A. Thus, the figure below describes the actions (represented by a letter) of the VDED execution.
113
108
114
109
115
-
.. _zbus vded table:
116
110
.. list-table:: VDED execution steps in detail.
117
111
:widths: 5 65
118
112
:header-rows: 1
@@ -279,7 +273,7 @@ Messages are read from a channel in zbus by calling :c:func:`zbus_chan_read`. So
279
273
Do not use this function inside an ISR.
280
274
281
275
.. warning::
282
-
Choose the timeout of :c:func:`zbus_chan_read` after receiving a notification from :c:func:`zbus_sub_wait` carefully because the channel will always be unavailable during the VDED execution. Using ``K_NO_WAIT`` for reading is highly likely to return a timeout error if there are more than one subscriber. For example, consider the :numref:`zbus vded` again and notice how ``T3`` and ``T4's`` read attempts would definitely fail with K_NO_WAIT. For more details, check the `Virtual Distributed Event Dispatcher`_ section.
276
+
Choose the timeout of :c:func:`zbus_chan_read` after receiving a notification from :c:func:`zbus_sub_wait` carefully because the channel will always be unavailable during the VDED execution. Using ``K_NO_WAIT`` for reading is highly likely to return a timeout error if there are more than one subscriber. For example, consider the VDED illustration again and notice how ``T3`` and ``T4's`` read attempts would definitely fail with K_NO_WAIT. For more details, check the `Virtual Distributed Event Dispatcher`_ section.
0 commit comments