1.. zephyr:code-sample:: zbus-priority-boost
2   :name: zbus Priority Boost
3   :relevant-api: zbus_apis
4
5   Illustrates zbus priority boost feature with a priority inversion scenario.
6
7Overview
8********
9This sample implements a simple application that illustrates the priority boost feature. The
10application implements the below figure scenario. When the priority boost feature is disabled, the
11execution sequence presents a priority inversion problem, which may not affect much of the
12developer's application. Those who want to avoid priority inversions between message subscribers and
13plain subscribers should use the priority boost strategy.
14
15.. code-block:: c
16
17   ZBUS_CHAN_DEFINE(chan_a,
18                    int,
19                    NULL,
20                    NULL,
21                    ZBUS_OBSERVERS(l1, ms1, ms2, s1, l2),
22                    0
23   );
24
25
26.. figure:: zbus_publishing_process_example_scenario.svg
27    :alt: ZBus priority boost scenario example.
28    :width: 45%
29
30.. note::
31
32   The developer must use the :c:func:`zbus_obs_attach_to_thread` function to ensure a proper
33   priority boost execution.
34
35
36Building and Running
37********************
38
39The figure below illustrates the execution of the cited scenario but with the priority boost
40disabled.
41
42.. figure:: without_hlp_priority_boost_feature.svg
43    :alt: ZBus example scenario for priority boost disabled.
44    :width: 70%
45
46
47It can be built and executed on QEMU as follows:
48
49.. zephyr-app-commands::
50   :zephyr-app: samples/subsys/zbus/priority_boost
51   :gen-args: -DCONFIG_ZBUS_PRIORITY_BOOST=n
52   :host-os: unix
53   :board: qemu_x86
54   :goals: run
55
56Sample Output
57=============
58
59.. code-block:: console
60
61   I: --------------
62   I: 0 -> T1: prio before 5
63   I: 0 ---> L1: T1 prio 5
64   I: 0 -> MS1:  T1 prio 5
65   I: 0 -> MS2:  T1 prio 5
66   I: 0 ---> L2: T1 prio 5
67   I: 0 -> T1: prio after 5
68   I: N -> S1:  T1 prio 5
69   I: 0 -> S1:  T1 prio 5
70   I: --------------
71   I: 1 -> T1: prio before 5
72   I: 1 ---> L1: T1 prio 5
73   I: 1 -> MS1:  T1 prio 5
74   I: 1 -> MS2:  T1 prio 5
75   I: 1 ---> L2: T1 prio 5
76   I: 1 -> T1: prio after 5
77   I: N -> S1:  T1 prio 5
78   I: 1 -> S1:  T1 prio 5
79   I: --------------
80   I: 2 -> T1: prio before 5
81   I: 2 ---> L1: T1 prio 5
82   I: 2 -> MS1:  T1 prio 5
83   I: 2 ---> L2: T1 prio 5
84   I: 2 -> T1: prio after 5
85   I: 2 -> MS2:  T1 prio 5
86   I: --------------
87   I: 3 -> T1: prio before 5
88   I: 3 ---> L1: T1 prio 5
89   I: 3 -> MS1:  T1 prio 5
90   I: 3 ---> L2: T1 prio 5
91   I: 3 -> T1: prio after 5
92   I: 3 -> MS2:  T1 prio 5
93   I: --------------
94   I: 4 -> T1: prio before 5
95   I: 4 ---> L1: T1 prio 5
96   I: 4 ---> L2: T1 prio 5
97   I: 4 -> T1: prio after 5
98   I: 4 -> MS2:  T1 prio 5
99   I: --------------
100   I: 5 -> T1: prio before 5
101   I: 5 ---> L1: T1 prio 5
102   I: 5 ---> L2: T1 prio 5
103   I: 5 -> T1: prio after 5
104   I: 5 -> MS2:  T1 prio 5
105   I: --------------
106   I: 6 -> T1: prio before 5
107   I: 6 ---> L1: T1 prio 5
108   I: 6 -> MS1:  T1 prio 5
109   I: 6 -> MS2:  T1 prio 5
110   I: 6 ---> L2: T1 prio 5
111   I: 6 -> T1: prio after 5
112   I: N -> S1:  T1 prio 5
113   I: 6 -> S1:  T1 prio 5
114   I: --------------
115   <continues>
116
117
118Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
119
120
121The figure below illustrates the execution of the same scenario but with the priority boost enabled.
122The developer must enable the priority boost and properly attach all the observers to their threads.
123
124.. figure:: with_hlp_priority_boost_feature.svg
125    :alt: ZBus example scenario for priority boost enabled.
126    :width: 75%
127
128To execute the sample with priority boost feature enabled, run the following command:
129
130.. zephyr-app-commands::
131   :zephyr-app: samples/subsys/zbus/priority_boost
132   :gen-args: -DCONFIG_ZBUS_PRIORITY_BOOST=y
133   :host-os: unix
134   :board: qemu_x86
135   :goals: run
136
137Sample Output
138=============
139
140.. code-block:: console
141
142   I: --------------
143   I: 0 -> T1: prio before 5
144   I: 0 ---> L1: T1 prio 1
145   I: 0 ---> L2: T1 prio 1
146   I: N -> S1:  T1 prio 5
147   I: 0 -> S1:  T1 prio 5
148   I: 0 -> MS1:  T1 prio 5
149   I: 0 -> MS2:  T1 prio 5
150   I: 0 -> T1: prio after 5
151   I: --------------
152   I: 1 -> T1: prio before 5
153   I: 1 ---> L1: T1 prio 1
154   I: 1 ---> L2: T1 prio 1
155   I: N -> S1:  T1 prio 5
156   I: 1 -> S1:  T1 prio 5
157   I: 1 -> MS1:  T1 prio 5
158   I: 1 -> MS2:  T1 prio 5
159   I: 1 -> T1: prio after 5
160   I: --------------
161   I: 2 -> T1: prio before 5
162   I: 2 ---> L1: T1 prio 2
163   I: 2 ---> L2: T1 prio 2
164   I: 2 -> MS1:  T1 prio 5
165   I: 2 -> MS2:  T1 prio 5
166   I: 2 -> T1: prio after 5
167   I: --------------
168   I: 3 -> T1: prio before 5
169   I: 3 ---> L1: T1 prio 2
170   I: 3 ---> L2: T1 prio 2
171   I: 3 -> MS1:  T1 prio 5
172   I: 3 -> MS2:  T1 prio 5
173   I: 3 -> T1: prio after 5
174   I: --------------
175   I: 4 -> T1: prio before 5
176   I: 4 ---> L1: T1 prio 3
177   I: 4 ---> L2: T1 prio 3
178   I: 4 -> MS2:  T1 prio 5
179   I: 4 -> T1: prio after 5
180   I: --------------
181   I: 5 -> T1: prio before 5
182   I: 5 ---> L1: T1 prio 3
183   I: 5 ---> L2: T1 prio 3
184   I: 5 -> MS2:  T1 prio 5
185   I: 5 -> T1: prio after 5
186   I: --------------
187   I: 6 -> T1: prio before 5
188   I: 6 ---> L1: T1 prio 1
189   I: 6 ---> L2: T1 prio 1
190   I: N -> S1:  T1 prio 5
191   I: 6 -> S1:  T1 prio 5
192   I: 6 -> MS1:  T1 prio 5
193   I: 6 -> MS2:  T1 prio 5
194   I: 6 -> T1: prio after 5
195   I: --------------
196   <continues>
197
198
199Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
200