|
…
|
||
|---|---|---|
| .. | ||
| src | ||
| CMakeLists.txt | ||
| README.rst | ||
| prj.conf | ||
| sample.yaml | ||
| with_hlp_priority_boost_feature.svg | ||
| without_hlp_priority_boost_feature.svg | ||
| zbus_publishing_process_example_scenario.svg | ||
README.rst
.. zephyr:code-sample:: zbus-priority-boost
:name: zbus Priority Boost
:relevant-api: zbus_apis
Illustrates zbus priority boost feature with a priority inversion scenario.
Overview
********
This sample implements a simple application that illustrates the priority boost feature. The
application implements the below figure scenario. When the priority boost feature is disabled, the
execution sequence presents a priority inversion problem, which may not affect much of the
developer's application. Those who want to avoid priority inversions between message subscribers and
plain subscribers should use the priority boost strategy.
.. code-block:: c
ZBUS_CHAN_DEFINE(chan_a,
int,
NULL,
NULL,
ZBUS_OBSERVERS(l1, ms1, ms2, s1, l2),
0
);
.. figure:: zbus_publishing_process_example_scenario.svg
:alt: ZBus priority boost scenario example.
:width: 45%
.. note::
The developer must use the :c:func:`zbus_obs_attach_to_thread` function to ensure a proper
priority boost execution.
Building and Running
********************
The figure below illustrates the execution of the cited scenario but with the priority boost
disabled.
.. figure:: without_hlp_priority_boost_feature.svg
:alt: ZBus example scenario for priority boost disabled.
:width: 70%
It can be built and executed on QEMU as follows:
.. zephyr-app-commands::
:zephyr-app: samples/subsys/zbus/priority_boost -- -DCONFIG_ZBUS_PRIORITY_BOOST=n
:host-os: unix
:board: qemu_x86
:goals: run
Sample Output
=============
.. code-block:: console
I: --------------
I: 0 -> T1: prio before 5
I: 0 ---> L1: T1 prio 5
I: 0 -> MS1: T1 prio 5
I: 0 -> MS2: T1 prio 5
I: 0 ---> L2: T1 prio 5
I: 0 -> T1: prio after 5
I: N -> S1: T1 prio 5
I: 0 -> S1: T1 prio 5
I: --------------
I: 1 -> T1: prio before 5
I: 1 ---> L1: T1 prio 5
I: 1 -> MS1: T1 prio 5
I: 1 -> MS2: T1 prio 5
I: 1 ---> L2: T1 prio 5
I: 1 -> T1: prio after 5
I: N -> S1: T1 prio 5
I: 1 -> S1: T1 prio 5
I: --------------
I: 2 -> T1: prio before 5
I: 2 ---> L1: T1 prio 5
I: 2 -> MS1: T1 prio 5
I: 2 ---> L2: T1 prio 5
I: 2 -> T1: prio after 5
I: 2 -> MS2: T1 prio 5
I: --------------
I: 3 -> T1: prio before 5
I: 3 ---> L1: T1 prio 5
I: 3 -> MS1: T1 prio 5
I: 3 ---> L2: T1 prio 5
I: 3 -> T1: prio after 5
I: 3 -> MS2: T1 prio 5
I: --------------
I: 4 -> T1: prio before 5
I: 4 ---> L1: T1 prio 5
I: 4 ---> L2: T1 prio 5
I: 4 -> T1: prio after 5
I: 4 -> MS2: T1 prio 5
I: --------------
I: 5 -> T1: prio before 5
I: 5 ---> L1: T1 prio 5
I: 5 ---> L2: T1 prio 5
I: 5 -> T1: prio after 5
I: 5 -> MS2: T1 prio 5
I: --------------
I: 6 -> T1: prio before 5
I: 6 ---> L1: T1 prio 5
I: 6 -> MS1: T1 prio 5
I: 6 -> MS2: T1 prio 5
I: 6 ---> L2: T1 prio 5
I: 6 -> T1: prio after 5
I: N -> S1: T1 prio 5
I: 6 -> S1: T1 prio 5
I: --------------
<continues>
Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.
The figure below illustrates the execution of the same scenario but with the priority boost enabled.
The developer must enable the priority boost and properly attach all the observers to their threads.
.. figure:: with_hlp_priority_boost_feature.svg
:alt: ZBus example scenario for priority boost enabled.
:width: 75%
To execute the sample with priority boost feature enabled, run the following command:
.. zephyr-app-commands::
:zephyr-app: samples/subsys/zbus/priority_boost -- -DCONFIG_ZBUS_PRIORITY_BOOST=y
:host-os: unix
:board: qemu_x86
:goals: run
Sample Output
=============
.. code-block:: console
I: --------------
I: 0 -> T1: prio before 5
I: 0 ---> L1: T1 prio 1
I: 0 ---> L2: T1 prio 1
I: N -> S1: T1 prio 5
I: 0 -> S1: T1 prio 5
I: 0 -> MS1: T1 prio 5
I: 0 -> MS2: T1 prio 5
I: 0 -> T1: prio after 5
I: --------------
I: 1 -> T1: prio before 5
I: 1 ---> L1: T1 prio 1
I: 1 ---> L2: T1 prio 1
I: N -> S1: T1 prio 5
I: 1 -> S1: T1 prio 5
I: 1 -> MS1: T1 prio 5
I: 1 -> MS2: T1 prio 5
I: 1 -> T1: prio after 5
I: --------------
I: 2 -> T1: prio before 5
I: 2 ---> L1: T1 prio 2
I: 2 ---> L2: T1 prio 2
I: 2 -> MS1: T1 prio 5
I: 2 -> MS2: T1 prio 5
I: 2 -> T1: prio after 5
I: --------------
I: 3 -> T1: prio before 5
I: 3 ---> L1: T1 prio 2
I: 3 ---> L2: T1 prio 2
I: 3 -> MS1: T1 prio 5
I: 3 -> MS2: T1 prio 5
I: 3 -> T1: prio after 5
I: --------------
I: 4 -> T1: prio before 5
I: 4 ---> L1: T1 prio 3
I: 4 ---> L2: T1 prio 3
I: 4 -> MS2: T1 prio 5
I: 4 -> T1: prio after 5
I: --------------
I: 5 -> T1: prio before 5
I: 5 ---> L1: T1 prio 3
I: 5 ---> L2: T1 prio 3
I: 5 -> MS2: T1 prio 5
I: 5 -> T1: prio after 5
I: --------------
I: 6 -> T1: prio before 5
I: 6 ---> L1: T1 prio 1
I: 6 ---> L2: T1 prio 1
I: N -> S1: T1 prio 5
I: 6 -> S1: T1 prio 5
I: 6 -> MS1: T1 prio 5
I: 6 -> MS2: T1 prio 5
I: 6 -> T1: prio after 5
I: --------------
<continues>
Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.