qf.hpp

Go to the documentation of this file.

//============================================================================
// QP/C++ Real-Time Embedded Framework (RTEF)
// Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
//
// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
//
// This software is dual-licensed under the terms of the open source GNU
// General Public License version 3 (or any later version), or alternatively,
// under the terms of one of the closed source Quantum Leaps commercial
// licenses.
//
// The terms of the open source GNU General Public License version 3
// can be found at: <www.gnu.org/licenses/gpl-3.0>
//
// The terms of the closed source Quantum Leaps commercial licenses
// can be found at: <www.state-machine.com/licensing>
//
// Redistributions in source code must retain this top-level comment block.
// Plagiarizing this software to sidestep the license obligations is illegal.
//
// Contact information:
// <www.state-machine.com>
// <info@state-machine.com>
//============================================================================
 
#ifndef QF_HPP
#define QF_HPP
 
//============================================================================
#ifndef QPSET_HPP
#include "qpset.hpp"
#endif
 
#ifdef Q_EVT_CTOR
#include <new>  // for placement new
#endif // Q_EVT_CTOR
 
//============================================================================
// apply defaults for all undefined configuration parameters
//
#ifndef QF_EVENT_SIZ_SIZE
    #define QF_EVENT_SIZ_SIZE    2U
#endif
 
#ifndef QF_MAX_EPOOL
    #define QF_MAX_EPOOL         3U
#endif
 
#ifndef QF_MAX_TICK_RATE
    #define QF_MAX_TICK_RATE     1U
#elif (QF_MAX_TICK_RATE > 15U)
    #error "QF_MAX_TICK_RATE exceeds the maximum of 15U"
#endif
 
#ifndef QF_TIMEEVT_CTR_SIZE
    #define QF_TIMEEVT_CTR_SIZE  2U
#endif
 
//============================================================================
namespace QP {
 
#if (QF_EVENT_SIZ_SIZE == 1U)
    using QEvtSize = std::uint8_t;
#elif (QF_EVENT_SIZ_SIZE == 2U)
    using QEvtSize = std::uint16_t;
#elif (QF_EVENT_SIZ_SIZE == 4U)
    using QEvtSize = std::uint32_t;
#else
    #error "QF_EVENT_SIZ_SIZE defined incorrectly, expected 1U, 2U, or 4U"
#endif
 
//============================================================================
#if (QF_TIMEEVT_CTR_SIZE == 1U)
    using QTimeEvtCtr = std::uint8_t;
#elif (QF_TIMEEVT_CTR_SIZE == 2U)
    using QTimeEvtCtr = std::uint16_t;
#elif (QF_TIMEEVT_CTR_SIZE == 4U)
    using QTimeEvtCtr = std::uint32_t;
#else
    #error "QF_TIMEEVT_CTR_SIZE defined incorrectly, expected 1U, 2U, or 4U"
#endif
 
class QEQueue; // forward declaration
 
//============================================================================
class QActive : public QHsm {
public: // for access from extern "C" functions
#ifdef QF_EQUEUE_TYPE
    QF_EQUEUE_TYPE m_eQueue;
#endif
 
#ifdef QF_OS_OBJECT_TYPE
    QF_OS_OBJECT_TYPE m_osObject;
#endif
 
#ifdef QF_THREAD_TYPE
    QF_THREAD_TYPE m_thread;
#endif
 
#ifdef QXK_HPP // QXK kernel used?
    std::uint8_t m_dynPrio;
#endif
 
    std::uint8_t m_prio;
 
protected:
    QActive(QStateHandler const initial) noexcept;
 
public:
    virtual void start(std::uint_fast8_t const prio,
        QEvt const * * const qSto, std::uint_fast16_t const qLen,
        void * const stkSto, std::uint_fast16_t const stkSize,
        void const * const par);
 
    virtual void start(std::uint_fast8_t const prio,
         QEvt const * * const qSto, std::uint_fast16_t const qLen,
         void * const stkSto, std::uint_fast16_t const stkSize)
    {
        this->start(prio, qSto, qLen, stkSto, stkSize, nullptr);
    }
 
#ifdef QF_ACTIVE_STOP
    void stop(void);
#endif
 
#ifndef Q_SPY
    virtual bool post_(QEvt const * const e,
                       std::uint_fast16_t const margin) noexcept;
#else
    virtual bool post_(QEvt const * const e, std::uint_fast16_t const margin,
                       void const * const sender) noexcept;
#endif
 
    virtual void postLIFO(QEvt const * const e) noexcept;
 
    void unsubscribeAll(void) const noexcept;
 
    void subscribe(enum_t const sig) const noexcept;
 
    void unsubscribe(enum_t const sig) const noexcept;
 
    bool defer(QEQueue * const eq, QEvt const * const e) const noexcept;
 
    bool recall(QEQueue * const eq) noexcept;
 
    std::uint_fast16_t flushDeferred(QEQueue * const eq) const noexcept;
 
    std::uint_fast8_t getPrio(void) const noexcept {
        return static_cast<std::uint_fast8_t>(m_prio);
    }
 
    void setPrio(std::uint_fast8_t const prio) {
        m_prio = static_cast<std::uint8_t>(prio);
    }
 
    void setAttr(std::uint32_t attr1, void const *attr2 = nullptr);
 
#ifdef QF_OS_OBJECT_TYPE
    QF_OS_OBJECT_TYPE &getOsObject(void) noexcept { return m_osObject; }
#endif
 
#ifdef QF_THREAD_TYPE
    QF_THREAD_TYPE &getThread(void) noexcept { return m_thread; }
#endif
 
    QEvt const *get_(void) noexcept;
 
// duplicated API to be used exclusively inside ISRs (useful in some QP ports)
#ifdef QF_ISR_API
#ifdef Q_SPY
    virtual bool postFromISR_(QEvt const * const e,
        std::uint_fast16_t const margin, void *par,
        void const * const sender) noexcept;
#else
    virtual bool postFromISR_(QEvt const * const e,
        std::uint_fast16_t const margin, void *par) noexcept;
#endif // Q_SPY
#endif // QF_ISR_API
 
// friendships...
private:
    friend class QF;
    friend class QTimeEvt;
    friend class QTicker;
#ifdef QK_HPP
    friend class QMutex;
#endif // QK_HPP
#ifdef QXK_HPP
    friend class QXK;
    friend class QXThread;
    friend class QXMutex;
    friend class QXSemaphore;
#endif // QXK_HPP
#ifdef Q_UTEST
    friend class QActiveDummy;
#endif // Q_UTEST
};
 
//============================================================================
class QMActive : public QActive {
public:
    // all the following operations delegate to the QHsm class...
    void init(void const * const e,
              std::uint_fast8_t const qs_id) override;
    void init(std::uint_fast8_t const qs_id) override;
    void dispatch(QEvt const * const e,
                  std::uint_fast8_t const qs_id) override;
 
#ifdef Q_SPY
    QStateHandler getStateHandler() noexcept override;
#endif
 
    bool isInState(QMState const * const st) const noexcept;
 
    QMState const *stateObj(void) const noexcept {
        return m_state.obj;
    }
 
    QMState const *childStateObj(QMState const * const parent) const noexcept;
 
protected:
    QMActive(QStateHandler const initial) noexcept;
 
private:
    using QHsm::isIn;
    using QHsm::state;
    using QHsm::childState;
};
 
//============================================================================
class QTimeEvt : public QEvt {
private:
 
    QTimeEvt * volatile m_next;
 
    void * volatile m_act;
 
    QTimeEvtCtr volatile m_ctr;
 
    QTimeEvtCtr m_interval;
 
public:
    QTimeEvt(QActive * const act, enum_t const sgnl,
             std::uint_fast8_t const tickRate = 0U) noexcept;
 
    void armX(QTimeEvtCtr const nTicks,
              QTimeEvtCtr const interval = 0U) noexcept;
 
    bool disarm(void) noexcept;
 
    bool rearm(QTimeEvtCtr const nTicks) noexcept;
 
    bool wasDisarmed(void) noexcept;
 
    QTimeEvtCtr currCtr(void) const noexcept;
 
private:
    QTimeEvt(void) noexcept;
 
    QTimeEvt(QTimeEvt const &) = delete;
 
    QTimeEvt & operator=(QTimeEvt const &) = delete;
 
    QActive  *toActive(void) noexcept {
        return static_cast<QActive *>(m_act);
    }
 
    QTimeEvt *toTimeEvt(void) noexcept {
        return static_cast<QTimeEvt *>(m_act);
    }
 
    friend class QF;
    friend class QS;
#ifdef QXK_HPP
    friend class QXThread;
    friend void QXK_activate_(void);
#endif // QXK_HPP
};
 
//============================================================================
using QSubscrList = QPSet;
 
//============================================================================
class QF {
public:
    static char const *getVersion(void) noexcept {
        return versionStr;
    }
 
    static void init(void);
 
    static void psInit(QSubscrList * const subscrSto,
                       enum_t const maxSignal) noexcept;
 
    static void poolInit(void * const poolSto,
                         std::uint_fast32_t const poolSize,
                         std::uint_fast16_t const evtSize) noexcept;
 
    static std::uint_fast16_t poolGetMaxBlockSize(void) noexcept;
 
 
    static int_t run(void);
 
    static void onStartup(void);
 
    static void onCleanup(void);
 
    static void stop(void);
 
#ifndef Q_SPY
    static void publish_(QEvt const * const e) noexcept;
    static void tickX_(std::uint_fast8_t const tickRate) noexcept;
#else
    static void publish_(QEvt const * const e,
                         void const * const sender,
                         std::uint_fast8_t const qs_id) noexcept;
 
    static void tickX_(std::uint_fast8_t const tickRate,
                       void const * const sender) noexcept;
#endif // Q_SPY
 
    static bool noTimeEvtsActiveX(std::uint_fast8_t const tickRate) noexcept;
 
    static std::uint_fast16_t getPoolMin(std::uint_fast8_t const poolId)
        noexcept;
 
    static std::uint_fast16_t getQueueMin(std::uint_fast8_t const prio)
        noexcept;
 
    static QEvt *newX_(std::uint_fast16_t const evtSize,
                       std::uint_fast16_t const margin,
                       enum_t const sig) noexcept;
 
    static void gc(QEvt const * const e) noexcept;
 
    static QEvt const *newRef_(QEvt const * const e,
                               QEvt const * const evtRef) noexcept;
 
    static void deleteRef_(QEvt const * const evtRef) noexcept;
 
    static void remove_(QActive * const a) noexcept;
 
    static QActive *active_[QF_MAX_ACTIVE + 1U];
 
    static void thread_(QActive *act);
 
    static void add_(QActive * const a) noexcept;
 
    static void bzero(void * const start,
                      std::uint_fast16_t const len) noexcept;
 
// API to be used exclusively inside ISRs (useful in some QP ports)
#ifdef QF_ISR_API
#ifdef Q_SPY
    static void publishFromISR_(QEvt const *e, void *par,
                                void const *sender) noexcept;
    static void tickXfromISR_(std::uint_fast8_t const tickRate, void *par,
                              void const * const sender) noexcept;
#else
    static void publishFromISR_(QEvt const *e, void *par) noexcept;
    static void tickXfromISR_(std::uint_fast8_t const tickRate,
                              void *par) noexcept;
#endif // Q_SPY
 
    static QEvt *newXfromISR_(std::uint_fast16_t const evtSize,
                              std::uint_fast16_t const margin,
                              enum_t const sig) noexcept;
    static void gcFromISR(QEvt const *e) noexcept;
 
#endif // QF_ISR_API
 
// to be used in QF ports only...
private:
    static QTimeEvt timeEvtHead_[QF_MAX_TICK_RATE];
 
    friend class QActive;
    friend class QTimeEvt;
    friend class QS;
#ifdef QXK_HPP
    friend class QXThread;
#endif // QXK_HPP
};
 
std::uint_fast16_t const QF_NO_MARGIN = 0xFFFFU;
 
 
//============================================================================
class QTicker : public QActive {
public:
    explicit QTicker(std::uint_fast8_t const tickRate) noexcept; // ctor
 
    void init(void const * const e,
              std::uint_fast8_t const qs_id) noexcept override;
    void init(std::uint_fast8_t const qs_id) noexcept override;
    void dispatch(QEvt const * const e,
                  std::uint_fast8_t const qs_id) noexcept override;
#ifndef Q_SPY
    bool post_(QEvt const * const e,
               std::uint_fast16_t const margin) noexcept override;
#else
    bool post_(QEvt const * const e, std::uint_fast16_t const margin,
               void const * const sender) noexcept override;
#endif
    void postLIFO(QEvt const * const e) noexcept override;
};
 
} // namespace QP
 
//============================================================================
#ifndef QF_CRIT_EXIT_NOP
    #define QF_CRIT_EXIT_NOP()   (static_cast<void>(0))
#endif
 
//============================================================================
// Provide the constructor for the QEvt class?
#ifdef Q_EVT_CTOR
 
    #define Q_NEW(evtT_, sig_, ...)                             \
        (new(QP::QF::newX_(sizeof(evtT_), QP::QF_NO_MARGIN, 0)) \
            evtT_((sig_),  ##__VA_ARGS__))
 
    #define Q_NEW_X(e_, evtT_, margin_, sig_, ...) do {        \
        (e_) = static_cast<evtT_ *>(                           \
                  QP::QF::newX_(sizeof(evtT_), (margin_), 0)); \
        if ((e_) != nullptr) {                                 \
            new((e_)) evtT_((sig_),  ##__VA_ARGS__);           \
        } \
     } while (false)
 
#else // QEvt is a POD (Plain Old Datatype)
 
    #define Q_NEW(evtT_, sig_) (static_cast<evtT_ *>( \
         QP::QF::newX_(sizeof(evtT_), QP::QF_NO_MARGIN, (sig_))))
 
    #define Q_NEW_X(e_, evtT_, margin_, sig_)        \
        ((e_) = static_cast<evtT_ *>(QP::QF::newX_(  \
                    sizeof(evtT_), (margin_), (sig_))))
#endif
 
#define Q_NEW_REF(evtRef_, evtT_)  \
    ((evtRef_) = static_cast<evtT_ const *>(QP::QF::newRef_(e, (evtRef_))))
 
#define Q_DELETE_REF(evtRef_) do { \
    QP::QF::deleteRef_((evtRef_)); \
    (evtRef_) = 0U;                \
} while (false)
 
//============================================================================
// QS software tracing integration, only if enabled
#ifdef Q_SPY
 
    #define TICK_X(tickRate_, sender_) tickX_((tickRate_), (sender_))
 
    #define PUBLISH(e_, sender_) \
        publish_((e_), (sender_), (sender_)->getPrio())
 
    #define POST(e_, sender_) post_((e_), QP::QF_NO_MARGIN, (sender_))
 
    #define POST_X(e_, margin_, sender_) \
        post_((e_), (margin_), (sender_))
 
#else
 
    #define PUBLISH(e_, dummy_)         publish_((e_))
    #define POST(e_, dummy_)            post_((e_), QP::QF_NO_MARGIN)
    #define POST_X(e_, margin_, dummy_) post_((e_), (margin_))
    #define TICK_X(tickRate_, dummy_)   tickX_((tickRate_))
 
#endif // Q_SPY
 
#define TICK(sender_) TICK_X(0U, (sender_))
 
#endif // QF_HPP