qp_port.hpp

Go to the documentation of this file.

/*! @file
@code_uid{qp_port.hpp, 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_HPP_
#define QP_PORT_HPP_
 
#include <cstdint>  // Exact-width types. C++11 Standard
 
/*!
@code_uid{#Q_NORETURN, No-return specifier for the Q_onError() callback function.}
@code_litem{Details}
Per the Software Safety Requirement @ref SSRS_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.
@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{SSRS_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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_INT_DISABLE()    intDisable()
 
/*!
@code_uid{QF_INT_ENABLE(), Port-specific interrupt enable}
@code_fw_trace
- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_CRIT_EST()        (static_cast<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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_LOG2(bitmask_) QF_qlog2(static_cast<std::uint32_t>(bitmask_))
 
extern "C" {
    //void intDisable(void);
    //void intEnable(void);
    //std::uint32_t critEntry(void);
    //void critExit(std::uint32_t stat);
    //std::uint32_t QK_get_IPSR(void);
} // extern "C"
 
 
#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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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
@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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QK_ISR_EXIT()                 \
do {                                  \
    QF_INT_DISABLE();                 \
    --QP::QK::priv_.intNest;          \
    if (QP::QK::priv_.intNest == 0U) {\
        if (QP::QK::sched_() != 0U) { \
            QP::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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QXK_ISR_EXIT()  do {                                  \
    QF_INT_DISABLE();                                         \
    if (QP::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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_SCHED_UNLOCK_() do { \
    if (lockStat_ != 0xFFU) { \
        QP::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
@code_fw_trace
- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QACTIVE_EQUEUE_WAIT_(me_) (static_cast<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
@code_fw_trace
- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QACTIVE_EQUEUE_SIGNAL_(me_) do { \
    QP::QK::priv_.readySet.insert( \
        static_cast<std::uint_fast8_t>((me_)->m_prio)); \
    if (!QP::QK_ISR_CONTEXT_()) { \
        if (QP::QK::sched_() != 0U) { \
            QP::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
@code_fw_trace
- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QXTHREAD_EQUEUE_SIGNAL_(me_) do { \
    if ((me_)->m_temp.obj == QXK::qmstate_cast_(&(me_)->m_eQueue)) { \
        static_cast<void>(static_cast<QP::QXThread *>(me_)->teDisarm_()); \
        QXK_priv_.readySet.insert( \
            static_cast<std::uint_fast8_t>((me_)->m_prio)); \
        QXK_priv_.readySet.update_(&QXK_priv_.readySet_dis); \
        if (!QXK_ISR_CONTEXT_()) { \
            static_cast<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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_) \
    (p_).init((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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_EPOOL_EVENT_SIZE_(p_)  ((p_).getBlockSize())
 
/*!
@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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_EPOOL_GET_(p_, e_, m_, qsId_) \
    ((e_) = static_cast<QEvt *>((p_).get((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_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>
- @tr{DVR_QP_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_EPOOL_PUT_(p_, e_, qsId_) ((p_).put((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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_EPOOL_USE_(ePool_)   ((ePool_)->getUse())
 
/*!
@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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_EPOOL_FREE_(ePool_)  ((ePool_)->getFree())
 
/*!
@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_MP2_R19_0_2}: <i>Rule 19.0.2(Required): Function-like macros shall not be defined</i>
@endcode_uid
*/
#define QF_EPOOL_MIN_(ePool_)   ((ePool_)->getMin())
 
// include files -------------------------------------------------------------
#include "qequeue.hpp"   // QK kernel uses the native QP event queue
#include "qmpool.hpp"    // QK kernel uses the native QP memory pool
#include "qp.hpp"        // QP framework
#include "qk.hpp"        // QK kernel
 
#endif // QP_PORT_HPP_