4This is just an example of a QF port for a generic C11 compiler.
5Other specific QF ports will define the QF facilities differently.
6@endcode_uid
7*/
8
9#ifndef QP_PORT_HPP_
10#define QP_PORT_HPP_
11
12#include <cstdint>// Exact-width types. C++11 Standard
13
14/*!
15@code_uid{#Q_NORETURN, No-return specifier for the Q_onError() callback function.}
16@code_litem{Details}
17Per the Software Safety Requirement @ref SREQ_QP_FDM_03, the Custom Error Handler Q_onError() should never return. Starting with the C99 Standard, the no-return specification can be provided at the language level, which may allow the compiler to apply optimizations (e.g., for impossible code paths downstream of Q_onError()). Also, the no-return specification is immensely valuable for static analysis tools.
18@note
19If the `Q_NORETURN` macro is not defined in the QP port (`qf_port.h`), the default will be the C99 specifier `_Noreturn` applied in `qsafe.h`.
20@code_bw_trace{brief}
21- @tr{SREQ_QP_FDM_03}: <i>@QPX fault management shall be based on the <u>Crash-Only model</u>.</i>
68@code_uid{#QF_CRIT_STAT, Define the critical section status that was present before entering the critical section.}
69@code_litem{Details}
70For critical sections that are allowed to nest, the critical section status must be saved and restored at the end. This macro provides the storage for saving the status.
71@note
72This macro might be empty, in which case, the critical section status is not saved or restored. Such critical sections won't be able to nest. Also, note that the macro should be invoked without the closing semicolon.
81If the critical section status is provided, the macro saves the critical section status from before entering the critical section. Otherwise, the macro just unconditionally enters the critical section without saving the status.
82@code_fw_trace
83- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
91If the critical section status is provided, the macro restores the critical section status saved by QF_CRIT_ENTRY(). Otherwise, the macro just unconditionally exits the critical section.
92@code_fw_trace
93- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
99@code_uid{QF_CRIT_EXIT_NOP(), No-operation for exiting a critical section}
100@code_litem{Details}
101In some QF ports, the critical section exit takes effect only on the next machine instruction. If this next instruction is another entry to a critical section, the critical section won't be exited, but rather the two adjacent critical sections would be _merged_. The QF_CRIT_EXIT_NOP() macro contains minimal code required to prevent such merging of critical sections in QF ports.
102@code_fw_trace
103- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
109@code_uid{QF_CRIT_EST(), Port-specific establishing a critical section (without saving the status)}
110@code_litem{Details}
111This port-specific macro only establishes a critical section (to later call Q_onError() error handler), but since Q_onError() never returns, there is no need to exit such established critical section.
112@code_fw_trace
113- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
119@code_uid{QF_LOG2(), Port-specific integer log-base-2 of a 32-bit bitmask}
120@code_litem{Details}
121Calculate integer log-base-2 of a given bitmask (1-based) used to quickly determine the higest-number 1-bit in the bitmask. This operation is used frequently during task scheduling and publish-subscribe.
122@param[in] bitmask_ 32-bit bitmask
123@returns 1-based integer log-base-2 of the provided bitmask. Examples:
124- QF_LOG2(0x00000000U) == 0U
125- QF_LOG2(0x00000001U) == 1U
126- QF_LOG2(0x00000002U) == 2U
127- QF_LOG2(0x00000004U) == 3U
128- QF_LOG2(0x00000008U) == 4U
129- QF_LOG2(0x00000010U) == 5U
130...
131- QF_LOG2(0x80000010U) == 32U
132
133@note
134This operation is performed frequently in time-critical parts of the code. Some CPUs provide such calculation in hardware (e.g., as a machine instruction). For example, ARMv7 and higher architectures support the related CLZ (count leading zeroes) instruction, with the following relationship:
135QF_LOG2(bitmask_) == 32U - CLZ(bitmask_).
136@code_fw_trace
137- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
212@code_uid{QV_CPU_SLEEP(), Port-specific method to put the CPU to sleep __safely__ in the non-preemptive QV kernel (to be called from QV::QV_onIdle()).}
434@code_uid{QF_EPOOL_PUT_(), Port-specific event pool put() operation (for internal use in QF only).}
435@param[in,out] p_ event pool pointer
436@param[out] e_ event pointer to return to the pool
437@param[in] qsId_ QS ID for the QS local filter
438@code_fw_trace
439- @tr{DVR_QP_MP2_R8_2_3}: <i>Rule 8.2.3(Required): A cast shall not remove any 'const' or 'volatile' qualification from the type pointer to by a pointer or by reference</i>
440- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>