qf.h

Go to the documentation of this file.

// Product: QF/C++ platform-independent public interface
// Last Updated for Version: 4.3.00
// Date of the Last Update:  Nov 01, 2011
//
//                    Q u a n t u m     L e a P s
//                    ---------------------------
//                    innovating embedded systems
//
// Copyright (C) 2002-2011 Quantum Leaps, LLC. All rights reserved.
//
// This software may be distributed and modified under the terms of the GNU
// General Public License version 2 (GPL) as published by the Free Software
// Foundation and appearing in the file GPL.TXT included in the packaging of
// this file. Please note that GPL Section 2[b] requires that all works based
// on this software must also be made publicly available under the terms of
// the GPL ("Copyleft").
//
// Alternatively, this software may be distributed and modified under the
// terms of Quantum Leaps commercial licenses, which expressly supersede
// the GPL and are specifically designed for licensees interested in
// retaining the proprietary status of their code.
//
// Contact information:
// Quantum Leaps Web site:  http://www.quantum-leaps.com
// e-mail:                  info@quantum-leaps.com
#ifndef qf_h
#define qf_h


#ifdef Q_USE_NAMESPACE
namespace QP {
#endif

#if (QF_MAX_ACTIVE < 1) || (63 < QF_MAX_ACTIVE)
    #error "QF_MAX_ACTIVE not defined or out of range. Valid range is 1..63"
#endif

#ifndef QF_EVENT_SIZ_SIZE

    #define QF_EVENT_SIZ_SIZE 2
#endif
#if (QF_EVENT_SIZ_SIZE == 1)

    typedef uint8_t QEventSize;
#elif (QF_EVENT_SIZ_SIZE == 2)
    typedef uint16_t QEventSize;
#elif (QF_EVENT_SIZ_SIZE == 4)
    typedef uint32_t QEventSize;
#else
    #error "QF_EVENT_SIZ_SIZE defined incorrectly, expected 1, 2, or 4"
#endif

#ifndef QF_MAX_EPOOL

    #define QF_MAX_EPOOL 3
#endif

#ifndef QF_ACTIVE_SUPER_

    #define QF_ACTIVE_SUPER_  QHsm

    #define QF_ACTIVE_STATE_  QStateHandler

#endif

class QEQueue;                                          // forward declaration


class QActive : public QF_ACTIVE_SUPER_ {
private:

    QF_EQUEUE_TYPE m_eQueue;

public:
#ifdef QF_OS_OBJECT_TYPE






    QF_OS_OBJECT_TYPE m_osObject;
#endif

#ifdef QF_THREAD_TYPE






    QF_THREAD_TYPE m_thread;
#endif

    uint8_t m_prio;

    uint8_t m_running;

public:

    void start(uint8_t prio,
               QEvent const *qSto[], uint32_t qLen,
               void *stkSto, uint32_t stkSize,
               QEvent const *ie = (QEvent *)0);

#ifndef Q_SPY
    void postFIFO(QEvent const *e);
#else
    void postFIFO(QEvent const *e, void const *sender);
#endif

    void postLIFO(QEvent const *e);

    void run(void);

    QEvent const *get_(void);

protected:

    QActive(QF_ACTIVE_STATE_ initial) : QF_ACTIVE_SUPER_(initial) {
    }

    void stop(void);

    void subscribe(QSignal sig) const;

    void unsubscribe(QSignal sig) const;

    void defer(QEQueue *eq, QEvent const *e);

    uint8_t recall(QEQueue *eq);

public:
    void unsubscribeAll(void) const;

private:

    friend class QF;
    friend class QTimeEvt;
    #ifndef QF_INT_KEY_TYPE
        friend void QK_schedule_(void);
        friend void QK_scheduleExt_(void);
    #else
        friend void QK_schedule_(QF_INT_KEY_TYPE intLockKey);
        friend void QK_scheduleExt_(QF_INT_KEY_TYPE intLockKey);
    #endif
};


#ifndef QF_TIMEEVT_CTR_SIZE


    #define QF_TIMEEVT_CTR_SIZE 2
#endif
#if (QF_TIMEEVT_CTR_SIZE == 1)

    typedef uint8_t QTimeEvtCtr;
#elif (QF_TIMEEVT_CTR_SIZE == 2)
    typedef uint16_t QTimeEvtCtr;
#elif (QF_TIMEEVT_CTR_SIZE == 4)
    typedef uint32_t QTimeEvtCtr;
#else
    #error "QF_TIMEEVT_CTR_SIZE defined incorrectly, expected 1, 2, or 4"
#endif

class QTimeEvt : public QEvent {
private:

    QTimeEvt *m_prev;

    QTimeEvt *m_next;

    QActive *m_act;

    QTimeEvtCtr m_ctr;

    QTimeEvtCtr m_interval;

public:

    QTimeEvt(QSignal s);

    void postIn(QActive *act, QTimeEvtCtr nTicks) {
        m_interval = (uint16_t)0;
        arm_(act, nTicks);
    }

    void postEvery(QActive *act, QTimeEvtCtr nTicks) {
        m_interval = nTicks;
        arm_(act, nTicks);
    }

    uint8_t disarm(void);

    uint8_t rearm(QTimeEvtCtr nTicks);

    QTimeEvtCtr ctr(void);

private:

    void arm_(QActive *act, QTimeEvtCtr nTicks);

    friend class QF;
};


#if (QF_MAX_ACTIVE > 63)
    #error "QF_MAX_ACTIVE exceeds 63"
#endif

class QSubscrList {
private:

    uint8_t m_bits[((QF_MAX_ACTIVE - 1) / 8) + 1];

    friend class QF;
    friend class QActive;
};

class QF {
public:

    static void init(void);

    static void psInit(QSubscrList *subscrSto, QSignal maxSignal);

    static void poolInit(void *poolSto, uint32_t poolSize,
                         QEventSize evtSize);

    static void run(void);

    static void onStartup(void);

    static void onCleanup(void);

#ifndef QF_INT_KEY_TYPE
    static void onIdle(void);                // interrupt lock key NOT defined

#else

    static void onIdle(QF_INT_KEY_TYPE intLockKey);   // int. lock key defined

#endif                                                      // QF_INT_KEY_TYPE

    static void stop(void);

#ifndef Q_SPY
    static void publish(QEvent const *e);
#else
    static void publish(QEvent const *e, void const *sender);
#endif

#ifndef Q_SPY
    static void tick(void);
#else
    static void tick(void const *sender);
#endif

    static char const Q_ROM * Q_ROM_VAR getVersion(void);

    static char const Q_ROM * Q_ROM_VAR getPortVersion(void);

    static uint32_t getPoolMargin(uint8_t poolId);

    static uint32_t getQueueMargin(uint8_t prio);

    static QEvent *new_(uint16_t evtSize, QSignal sig);

#ifdef Q_EVT_CTOR
    #define Q_NEW(evtT_, sig_, ...) \
        (new(QF::new_(sizeof(evtT_), sig_)) evtT_((sig_), ##__VA_ARGS__))
#else













    #define Q_NEW(evtT_, sig_) ((evtT_ *)QF::new_(sizeof(evtT_), (sig_)))
#endif

    static void gc(QEvent const *e);

    static QActive *active_[];

private:                              // functions to be used in QF ports only

    static void add_(QActive *a);

public:
    static void remove_(QActive const *a);

    friend class QActive;
};

// useful lookup tables

extern uint8_t const Q_ROM Q_ROM_VAR QF_log2Lkup[256];

extern uint8_t const Q_ROM Q_ROM_VAR QF_pwr2Lkup[65];

extern uint8_t const Q_ROM Q_ROM_VAR QF_invPwr2Lkup[65];

extern uint8_t const Q_ROM Q_ROM_VAR QF_div8Lkup[65];

// deprecated features defined for backwards compatibility...
#if !defined(QF_CRIT_STAT_TYPE) && defined(QF_INT_KEY_TYPE)
    #define QF_CRIT_STAT_TYPE    QF_INT_KEY_TYPE
#endif
#if !defined(QF_CRIT_ENTRY) && defined(QF_INT_LOCK)
    #define QF_CRIT_ENTRY(stat_) QF_INT_LOCK(stat_)
#endif
#if !defined(QF_CRIT_EXIT) && defined(QF_INT_UNLOCK)
    #define QF_CRIT_EXIT(stat_)  QF_INT_UNLOCK(stat_)
#endif

#ifdef Q_USE_NAMESPACE
}                                                              // namespace QP
#endif

#ifdef Q_EVT_CTOR
#include <new>                                            // for placement new
#endif

// QS software tracing integration, only if enabled
#ifdef Q_SPY                                   // QS software tracing enabled?
    #ifndef qs_h
    #include "qs_port.h"                                    // include QS port
    #endif                                                             // qs_h

    #define TICK(sender_)                  tick(sender_)

    #define PUBLISH(e_, sender_)           publish((e_), (sender_))

    #define POST(e_, sender_)              postFIFO((e_), (sender_))

    #if (QF_EQUEUE_CTR_SIZE == 1)

        #define QS_EQC_(ctr_)       QS::u8_(ctr_)
    #elif (QF_EQUEUE_CTR_SIZE == 2)
        #define QS_EQC_(ctr_)       QS::u16_(ctr_)
    #elif (QF_EQUEUE_CTR_SIZE == 4)
        #define QS_EQC_(ctr_)       QS::u32_(ctr_)
    #else
        #error "QF_EQUEUE_CTR_SIZE not defined"
    #endif


    #if (QF_EVENT_SIZ_SIZE == 1)

        #define QS_EVS_(size_)      QS::u8_(size_)
    #elif (QF_EVENT_SIZ_SIZE == 2)
        #define QS_EVS_(size_)      QS::u16_(size_)
    #elif (QF_EVENT_SIZ_SIZE == 4)
        #define QS_EVS_(size_)      QS::u32_(size_)
    #endif


    #if (QF_MPOOL_SIZ_SIZE == 1)

        #define QS_MPS_(size_)      QS::u8_(size_)
    #elif (QF_MPOOL_SIZ_SIZE == 2)
        #define QS_MPS_(size_)      QS::u16_(size_)
    #elif (QF_MPOOL_SIZ_SIZE == 4)
        #define QS_MPS_(size_)      QS::u32_(size_)
    #endif

    #if (QF_MPOOL_CTR_SIZE == 1)

        #define QS_MPC_(ctr_)       QS::u8_(ctr_)
    #elif (QF_MPOOL_CTR_SIZE == 2)
        #define QS_MPC_(ctr_)       QS::u16_(ctr_)
    #elif (QF_MPOOL_CTR_SIZE == 4)
        #define QS_MPC_(ctr_)       QS::u32_(ctr_)
    #endif


    #if (QF_TIMEEVT_CTR_SIZE == 1)

        #define QS_TEC_(ctr_)       QS::u8_(ctr_)
    #elif (QF_TIMEEVT_CTR_SIZE == 2)
        #define QS_TEC_(ctr_)       QS::u16_(ctr_)
    #elif (QF_TIMEEVT_CTR_SIZE == 4)
        #define QS_TEC_(ctr_)       QS::u32_(ctr_)
    #endif

#else
    #ifndef qs_dummy_h
    #include "qs_dummy.h"                   // disable the QS software tracing
    #endif

    #define TICK(dummy_)                   tick()
    #define PUBLISH(e_, dummy_)            publish((e_))
    #define POST(e_, dummy_)               postFIFO((e_))

#endif                                                                // Q_SPY

#endif                                                                 // qf_h