QP port to Zephyr RTOS

About the QP/C++ Port to Zephyr

This directory contains a generic platform-independent QP/C++ port to the Zephyr RTOS.

Typically, you should not need to change the files in this directory to adapt the QP/C++-Zephyr port on any CPU/Compiler to which Zephyr has been ported, because all the CPU and compiler specifics are handled by the Zephyr RTOS.

The QP/C++-Zephyr port works as follows:

The critical section used in this port is based on k_spin_lock()/k_spin_unlock() Zephyr API. This is the modern Zephyr critical section API, which is ready for SMP (symmetric multiprocessing).
Each QP/C++ active object executes in a separate Zephyr thread (struct k_thread) and requires a private stack space.

Note: As demonstrated in the examples/zephyr folder, the private stacks for active objects in this port must be allocated with the Zephyr K_THREAD_STACK_DEFINE() macro. Also, the stack size passed to QACTIVE_START() must be calculated with the Zephyr K_THREAD_STACK_SIZEOF() macro. Failure to use these macros can lead to memory corruption in the application.

The active object event queue is implemented with the Zephyr message queue (struct k_msgq).

Note: The Zephyr message queue currently supports only the FIFO policy and does NOT support the LIFO policy. For that reason, the QActive_postLIFO_() implementation in this port uses the FIFO policy. A feature request has been filed in the Zephyr project for adding the LIFO policy, so perhaps this can be improved, if the feature is added.

The QP/C++ port uses Zephyr scheduler locking (k_sched_lock()/k_sched_unlock()), which locks all threads indiscriminately. Currently Zephyr does not provide a selective scheduler locking (with priority-ceiling).
The QP/C++ port uses the native QF memory pool (::QMPool) to implement event pools.
The QP/C++ port does not mandate any specific method to manage the QP/C++ time events, but the provided examples use the Zephyr timer (struct k_timer) to tick periodically and invoke QF_TICK_X().

QP/C++ Source Files Needed in the Zephyr port
It is important to note that not all QP/C++ source files should be included in the build process. Specifically, the QP/C++ source files qf_actq.c must NOT be included in the build, because this functionality is taken from Zephyr. Here is the list of QP/C++ source files needed:

qpcpp/
+---src/
|   +---qf/
|   |       qep_hsm.cpp
|   |       qep_msm.cpp
|   |       qf_act.cpp
|   |       qf_actq.cpp  // NOT included (implemented in Zephyr)
|   |       qf_defer.cpp
|   |       qf_dyn.cpp
|   |       qf_mem.cpp
|   |       qf_ps.cpp
|   |       qf_qeq.cpp
|   |       qf_qmact.cpp
|   |       qf_time.cpp
|   |
|   +---qs/
|   |       qs.cpp       // included only in the Spy build configuration
|   |       qs_fp.cpp    // included only in the Spy build configuration
|
+---zephyr/         // QP/C++ port to Zephyr (packaged as a "Zephyr module")
|       CMakeLists.txt
|       Kconfig
|       module.yml
|       qp_port.hpp
|       qs_port.hpp
|       qf_port.cpp   // implementation of the Zephyr port

Note: The QP/C++ port to Zephyr is NOT located in the qpc/ports folder (as all other 3rd-party RTOS ports) because the port is packaged according to the rules of a "Zephyr Module". These rules require a "Zephyr Module" to be located directly in the qpcpp folder.

Examples for the Zephyr port

The example projects for this port are located in the examples/zephyr folder.

Ports to General-Purpose OSes