| .. 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`. |