qp_port.h

Go to the documentation of this file.

/*! @file
@code_uid{qp_port.h, Sample @QPX port}
@code_litem{Details}
This is just an example of a QF port for a generic C11 compiler. Other specific QF ports will define the QF facilities differently.
@endcode_uid
*/
#ifndef QP_PORT_H_
#define QP_PORT_H_
 
#include <stdint.h>  // Exact-width types. WG14/N843 C99-C11 Standard
#include <stdbool.h> // Boolean type.      WG14/N843 C99-C11 Standard
 
/*!
@code_uid{#Q_NORETURN, No-return specifier for the Q_onError() callback function.}
@code_litem{Details}
Per the Software Safety Requirement @ref SSR_QA_FDM_20, the Q_onError() handler 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. Unfortunately, MISRA-C:2025 still considers the specifier `_Noreturn` as an "emergent language feature", which should not be used (MISRA-C:2025 Rule 1.4, Required). The #Q_NORETURN macro encapsulates this deviation.
@note
If 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`.
@code_bw_trace{brief}
- @tr{SSR_QA_FDM_20}: <i>@QPX Application shall implement custom error handler such that it does <u>not return</u>.</i>
@code_fw_trace
- @tr{SSM_QA_CSOU_21}: <i>Mandate: @QPX Application must ensure that the Q_onError() Custom Error Handler does <u>not return</u>.</i>
@endcode_uid
*/
#define Q_NORETURN  _Noreturn  void
 
// QF configuration for the data members of the QActive class ----------------
/*!
@code_uid{QACTIVE_EQUEUE_TYPE, Port-specific ::QActive event queue type.}
@code_fw_trace
@endcode_uid
*/
#define QACTIVE_EQUEUE_TYPE  QEQueue
 
/*!
@code_uid{QACTIVE_OS_OBJ_TYPE, Port-specific ::QActive "OS-object" type.}
@code_fw_trace
@endcode_uid
*/
#define QACTIVE_OS_OBJ_TYPE  void*
 
/*!
@code_uid{QACTIVE_THREAD_TYPE, Port-specific ::QActive thread type.}
@code_fw_trace
@endcode_uid
*/
#define QACTIVE_THREAD_TYPE  void const *
 
// interrupt disabling mechanism ---------------------------------------------
/*!
@code_uid{QF_INT_DISABLE(), Port-specific interrupt disable}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_INT_DISABLE()    intDisable()
 
/*!
@code_uid{QF_INT_ENABLE(), Port-specific interrupt enable}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_INT_ENABLE()     intEnable()
 
// QF critical section mechanism ---------------------------------------------
/*!
@code_uid{#QF_CRIT_STAT, Define the critical section status that was present before entering the critical section.}
@code_litem{Details}
For 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.
@note
This 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.
@code_fw_trace
@endcode_uid
*/
#define QF_CRIT_STAT  crit_stat_t crit_stat_;
 
/*!
@code_uid{QF_CRIT_ENTRY(), Port-specific critical section entry}
@code_litem{Details}
If 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.
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_CRIT_ENTRY()        (crit_stat_ = critEntry())
 
/*!
@code_uid{QF_CRIT_EXIT(), Port-specific critical section exit}
@code_litem{Details}
If 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.
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_CRIT_EXIT()        critExit(crit_stat_)
 
/*!
@code_uid{QF_CRIT_EXIT_NOP(), No-operation for exiting a critical section}
@code_litem{Details}
In 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.
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_CRIT_EXIT_NOP()    __asm volatile ("isb" ::: "memory")
 
/*!
@code_uid{QF_CRIT_EST(), Port-specific establishing a critical section (without saving the status)}
@code_litem{Details}
This 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.
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_CRIT_EST()        ((void)critEntry())
 
/*!
@code_uid{QF_LOG2(), Port-specific integer log-base-2 of a 32-bit bitmask}
@code_litem{Details}
Calculate 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.
@param[in] bitmask_  32-bit bitmask
@returns 1-based integer log-base-2 of the provided bitmask. Examples:
- QF_LOG2(0x00000000U) == 0U
- QF_LOG2(0x00000001U) == 1U
- QF_LOG2(0x00000002U) == 2U
- QF_LOG2(0x00000004U) == 3U
- QF_LOG2(0x00000008U) == 4U
- QF_LOG2(0x00000010U) == 5U
...
- QF_LOG2(0x80000010U) == 32U
 
@note
This operation is performed frequently in time-critical parts of the code. Some CPUs provide such calculation in hardware (e.g., as a machine intruction). For example, ARMv7 and higher architectures support the related CLZ (count leading zeroes) instruction, with the following relationship:
QF_LOG2(bitmask_) == 32U - CLZ(bitmask_).
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9B}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (CORRECT diagnostics)</i>
@endcode_uid
*/
#define QF_LOG2(bitmask_) QF_qlog2((uint32_t)(bitmask_))
 
//typedef unsigned int crit_stat_t;
//crit_stat_t critEntry(void);
//void critExit(crit_stat_t stat);
 
#ifdef QF_MEM_ISOLATE
 
    /*!
    @code_uid{QF_ON_CONTEXT_SW, Enable memory isolation requires the context-switch}
    @code_fw_trace
    @endcode_uid
    */
    #define QF_ON_CONTEXT_SW   1U
 
    /*!
    @code_uid{QF_MEM_SYS(), Port-specific establishing _System Context_ for memory protection}
    @code_fw_trace
    - @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
    @endcode_uid
    */
    #define QF_MEM_SYS() QF_onMemSys()
 
    /*!
    @code_uid{QF_MEM_APP(), Port-specific establishing _Application Context_ for memory protection}
    @code_fw_trace
    - @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
    @endcode_uid
    */
    #define QF_MEM_APP() QF_onMemApp()
 
#endif // QF_MEM_ISOLATE
 
// QV-specific ---------------------------------------------------------------
/*!
@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()).}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QV_CPU_SLEEP()     \
do {                       \
    __disable_interrupt(); \
    QF_INT_ENABLE();       \
    __WFI();               \
    __enable_interrupt();  \
} while (false)
 
 
// QK-specific ---------------------------------------------------------------
/*!
@code_uid{QK_ISR_CONTEXT_(), Port-specific method to check if the QK kernel executes in the ISR context (used internally in QK only).}
@returns `true` if the caller executes in the ISR context and `false` otherwise
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QK_ISR_CONTEXT_() (QK_priv_.intNest != 0U)
 
/*!
@code_uid{QK_ISR_ENTRY(), Port-specific method to inform QK kernel about the ISR entry.}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QK_ISR_ENTRY()                               \
do {                                                 \
    QF_INT_DISABLE();                                \
    ++QK_priv_.intNest;                              \
    QF_QS_ISR_ENTRY(QK_priv_.intNest, QK_currPrio_); \
    QF_INT_ENABLE();                                 \
} while (false)
 
/*!
@code_uid{QK_ISR_EXIT(), Port-specific method to inform QK kernel about the ISR exit.}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QK_ISR_EXIT()             \
do {                              \
    QF_INT_DISABLE();             \
    --QK_priv_.intNest;           \
    if (QK_priv_.intNest == 0U) { \
        if (QK_sched_() != 0U) {  \
            QK_activate_();       \
        }                         \
    }                             \
    QF_INT_ENABLE();              \
} while (false)
 
// QXK-specific --------------------------------------------------------------
/*!
@code_uid{QXK_ISR_CONTEXT_(), Port-specific method to check if the QXK kernel executes in the ISR context (used internally in QXK only).}
@returns `true` if the caller executes in the ISR context and `false` otherwise
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QXK_ISR_CONTEXT_() (QXK_get_IPSR() != 0U)
 
/*!
@code_uid{QXK_CONTEXT_SWITCH_(), Port-specific method to trigger context switch (used internally in QXK only).}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QXK_CONTEXT_SWITCH_() (trigPendSV())
 
/*!
@code_uid{QXK_ISR_ENTRY(), Port-specific method to inform QXK kernel about the ISR entry.}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QXK_ISR_ENTRY() ((void)0)
 
/*!
@code_uid{QXK_ISR_EXIT(), Port-specific method to inform QXK kernel about the ISR exit.}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QXK_ISR_EXIT()  do {                                  \
    QF_INT_DISABLE();                                         \
    if (QXK_sched_() != 0U) {                                 \
        *Q_UINT2PTR_CAST(uint32_t, 0xE000ED04U) = (1U << 28U);\
    }                                                         \
    QF_INT_ENABLE();                                          \
    QXK_ARM_ERRATUM_838869();                                 \
} while (false)
 
// Scheduling locking port interface (example) -------------------------------
/*!
@code_uid{QF_SCHED_STAT_, Port-specific type of the scheduler lock status (for internal use in QF only).}
@code_fw_trace
@endcode_uid
*/
#define QF_SCHED_STAT_ QSchedStatus lockStat_;
 
/*!
@code_uid{QF_SCHED_LOCK_(), Port-specific method to lock the scheduler (for internal use in QF only).}
@param[in] ceil_  priority-ceiling up to which the scheduler should be locked
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_SCHED_LOCK_(ceil_) do { \
    if (QK_ISR_CONTEXT_()) { \
        lockStat_ = 0xFFU; \
    } else { \
        lockStat_ = QK_schedLock((ceil_)); \
    } \
} while (false)
 
/*!
@code_uid{QF_SCHED_UNLOCK_(), Port-specific method to unlock the scheduler (for internal use in QF only).}
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_SCHED_UNLOCK_() do { \
    if (lockStat_ != 0xFFU) { \
        QK_schedUnlock(lockStat_); \
    } \
} while (false)
 
// Event-Queue port interface (example) --------------------------------------
// QActive event queue customization...
/*!
@code_uid{QACTIVE_EQUEUE_WAIT_(), Port-specific method to wait on an empty Active Object event queue (for internal use only).}
@param[in,out] me_  current instance pointer (see @ref SAS_QP_OO)
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QACTIVE_EQUEUE_WAIT_(me_) ((void)0)
 
/*!
@code_uid{QACTIVE_EQUEUE_SIGNAL_(), Port-specific method to signal Active Object event queue (for internal use only).}
@param[in,out] me_  current instance pointer (see @ref SAS_QP_OO)
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QACTIVE_EQUEUE_SIGNAL_(me_) do { \
    QPSet_insert(&QK_priv_.readySet, (uint_fast8_t)(me_)->prio); \
    QPSet_update_(&QK_priv_.readySet, &QK_priv_.readySet_dis); \
    if (!QK_ISR_CONTEXT_()) { \
        if (QK_sched_() != 0U) { \
            QK_activate_(); \
        } \
    } \
} while (false)
 
/*!
@code_uid{QXTHREAD_EQUEUE_SIGNAL_(), Port-specific method to signal eXtended thread event queue (for internal use only).}
@param[in,out] me_  current instance pointer (see @ref SAS_QP_OO)
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QXTHREAD_EQUEUE_SIGNAL_(me_) do { \
    if (me->super.temp.obj == QXK_PTR_CAST_(QMState*, &me->eQueue)) { \
        (void)QXThread_teDisarm_(QXTHREAD_CAST_(me)); \
        QPSet_insert(&QXK_priv_.readySet, (uint_fast8_t)me->prio); \
        QPSet_update_(&QXK_priv_.readySet, &QXK_priv_.readySet_dis); \
        if (!QXK_ISR_CONTEXT_()) { \
            (void)QXK_sched_(); \
        } \
    } \
} while (false)
 
// Event-Pool port interface (example) ---------------------------------------
/*!
@code_uid{QF_EPOOL_TYPE_, Port-specific type of the event pool (for internal use in QF only).}
@code_fw_trace
@endcode_uid
*/
#define QF_EPOOL_TYPE_  QMPool
 
/*!
@code_uid{QF_EPOOL_INIT_(), Port-specific event pool initialization (for internal use in QF only).}
@param[in,out] p_  event pool pointer
@param[in] poolSto_ storage for the pool (pointer to the pool buffer)
@param[in] poolSize_ size of the pool storage in [bytes]
@param[in] evtSize_  event size of this pool in [bytes]
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_) \
    (QMPool_init(&(p_), (poolSto_), (poolSize_), (evtSize_)))
 
/*!
@code_uid{QF_EPOOL_EVENT_SIZE_(), Port-specific event pool block-size() operation (for internal use in QF only).}
@param[in,out] p_  event pool pointer
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_EPOOL_EVENT_SIZE_(p_)  ((uint16_t)(p_).blockSize)
 
/*!
@code_uid{QF_EPOOL_GET_(), Port-specific event pool get() operation (for internal use in QF only).}
@param[in,out] p_  event pool pointer
@param[out] e_ event pointer to be assigned the obtained event
@param[in]  m_ marign (# free events that must still remain in the pool)
@param[in]  qsId_ QS ID for the QS local filter
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
- @tr{DVR_QP_MC5_R11_5}: <i>MISRA-C:2025 Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object</i>
@endcode_uid
*/
#define QF_EPOOL_GET_(p_, e_, m_, qsId_) \
    ((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qsId_)))
 
/*!
@code_uid{QF_EPOOL_PUT_(), Port-specific event pool put() operation (for internal use in QF only).}
@param[in,out] p_  event pool pointer
@param[out] e_ event pointer to return to the pool
@param[in]  qsId_ QS ID for the QS local filter
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_EPOOL_PUT_(p_, e_, qsId_) (QMPool_put(&(p_), (e_), (qsId_)))
 
/*!
@code_uid{QF_EPOOL_USE_(), Port-specific event pool # used events operation (for internal use in QF only).}
@param[in] ePool_  event pool pointer
@returns # used events in the pool at this moment (allocated and not returned yet)
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_EPOOL_USE_(ePool_)   (QMPool_getUse(ePool_))
 
/*!
@code_uid{QF_EPOOL_FREE_(), Port-specific event pool # free events operation (for internal use in QF only).}
@param[in] ePool_  event pool pointer
@returns # free events in the pool at this moment (available to allocate)
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_EPOOL_FREE_(ePool_)  ((uint16_t)(ePool_)->nFree)
 
/*!
@code_uid{QF_EPOOL_MIN_(), Port-specific event pool minimum # events since initialization (for internal use in QF only).}
@param[in] ePool_  event pool pointer
@returns minimal # free events in the pool since initialization
@code_fw_trace
- @tr{DVR_QP_MC5_D4_9A}: <i>MISRA-C:2025 Directive 4.9(Advisory): A function should be used in preference to a function-like macro where they are interchangeable (FALSE-POSITIVE diagnostics)</i>
@endcode_uid
*/
#define QF_EPOOL_MIN_(ePool_)   ((uint16_t)(ePool_)->nMin)
 
// include files -------------------------------------------------------------
#include "queue.h"    // QK kernel uses the native QP event queue
#include "qmpool.h"   // QK kernel uses the native QP memory pool
#include "qp.h"       // QP framework
#include "qk.h"       // QK kernel
 
#endif // QP_PORT_H_