qf.h

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_H
#define QF_H
 
#ifndef QPSET_H
#include "qpset.h"
#endif
 
/*==========================================================================*/
#ifndef QF_EVENT_SIZ_SIZE
    #define QF_EVENT_SIZ_SIZE 2U
#endif
#if (QF_EVENT_SIZ_SIZE == 1U)
    typedef uint8_t QEvtSize;
#elif (QF_EVENT_SIZ_SIZE == 2U)
    typedef uint16_t QEvtSize;
#elif (QF_EVENT_SIZ_SIZE == 4U)
    typedef uint32_t QEvtSize;
#else
    #error "QF_EVENT_SIZ_SIZE defined incorrectly, expected 1, 2, or 4"
#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 15"
#endif
 
#ifndef QF_TIMEEVT_CTR_SIZE
    #define QF_TIMEEVT_CTR_SIZE  2U
#endif
 
/*==========================================================================*/
struct QEQueue; /* forward declaration */
 
/*==========================================================================*/
typedef struct QActive {
    QHsm super; 
#ifdef QF_EQUEUE_TYPE
    QF_EQUEUE_TYPE eQueue;
#endif
 
#ifdef QF_OS_OBJECT_TYPE
    QF_OS_OBJECT_TYPE osObject;
#endif
 
#ifdef QF_THREAD_TYPE
    QF_THREAD_TYPE thread;
#endif
 
#ifdef QXK_H  /* QXK kernel used? */
    uint8_t dynPrio;
#endif
 
    uint8_t prio;
 
} QActive;
 
typedef struct {
    struct QHsmVtable super; 
    void (*start)(QActive * const me, uint_fast8_t prio,
                  QEvt const * * const qSto, uint_fast16_t const qLen,
                  void * const stkSto, uint_fast16_t const stkSize,
                  void const * const par);
 
#ifdef Q_SPY
    bool (*post)(QActive * const me, QEvt const * const e,
                 uint_fast16_t const margin, void const * const sender);
#else
    bool (*post)(QActive * const me, QEvt const * const e,
                 uint_fast16_t const margin);
#endif
 
    void (*postLIFO)(QActive * const me, QEvt const * const e);
 
} QActiveVtable;
 
/* QActive public operations... */
#define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, par_) do { \
    Q_ASSERT((Q_HSM_UPCAST(me_))->vptr);                                     \
    (*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->start)(          \
        (QActive *)(me_), (prio_),                                           \
        (qSto_), (qLen_), (stkSto_), (stkLen_), (par_));                     \
} while (false)
 
#ifdef Q_SPY
    #define QACTIVE_POST(me_, e_, sender_)                                   \
        ((void)(*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)(\
            (me_), (e_), QF_NO_MARGIN, (sender_)))
 
    #define QACTIVE_POST_X(me_, e_, margin_, sender_)                        \
        ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)((me_),\
         (e_), (margin_), (sender_)))
#else
 
    #define QACTIVE_POST(me_, e_, sender_)                                   \
        ((void)(*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)(\
             (me_), (e_), QF_NO_MARGIN))
 
    #define QACTIVE_POST_X(me_, e_, margin_, sender_)                   \
        ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)( \
            (me_), (e_), (margin_)))
 
#endif
 
#define QACTIVE_POST_LIFO(me_, e_)                                      \
    ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->postLIFO)( \
        (me_), (e_)))
 
/* QActive protected operations... */
void QActive_ctor(QActive * const me, QStateHandler initial);
 
#ifdef QF_ACTIVE_STOP
    void QActive_stop(QActive * const me);
#endif
 
void QActive_subscribe(QActive const * const me, enum_t const sig);
 
void QActive_unsubscribe(QActive const * const me, enum_t const sig);
 
void QActive_unsubscribeAll(QActive const * const me);
 
bool QActive_defer(QActive const * const me,
                   QEQueue * const eq, QEvt const * const e);
 
bool QActive_recall(QActive * const me, QEQueue * const eq);
 
uint_fast16_t QActive_flushDeferred(QActive const * const me,
                                    QEQueue * const eq);
 
void QActive_setAttr(QActive *const me, uint32_t attr1, void const *attr2);
 
/*==========================================================================*/
typedef struct {
    QActive super; 
} QMActive;
 
typedef QActiveVtable QMActiveVtable;
 
/* QMActive protected operations... */
void QMActive_ctor(QMActive * const me, QStateHandler initial);
 
/*==========================================================================*/
#if (QF_TIMEEVT_CTR_SIZE == 1U)
    typedef uint8_t QTimeEvtCtr;
#elif (QF_TIMEEVT_CTR_SIZE == 2U)
 
    typedef uint16_t QTimeEvtCtr;
#elif (QF_TIMEEVT_CTR_SIZE == 4U)
    typedef uint32_t QTimeEvtCtr;
#else
    #error "QF_TIMEEVT_CTR_SIZE defined incorrectly, expected 1, 2, or 4"
#endif
 
typedef struct QTimeEvt {
    QEvt super; 
    struct QTimeEvt * volatile next;
 
    void * volatile act;
 
    QTimeEvtCtr volatile ctr;
 
    QTimeEvtCtr interval;
} QTimeEvt;
 
/* QTimeEvt public operations... */
 
void QTimeEvt_ctorX(QTimeEvt * const me, QActive * const act,
                    enum_t const sig, uint_fast8_t tickRate);
 
void QTimeEvt_armX(QTimeEvt * const me,
                   QTimeEvtCtr const nTicks, QTimeEvtCtr const interval);
 
bool QTimeEvt_rearm(QTimeEvt * const me, QTimeEvtCtr const nTicks);
 
bool QTimeEvt_disarm(QTimeEvt * const me);
 
bool QTimeEvt_wasDisarmed(QTimeEvt * const me);
 
QTimeEvtCtr QTimeEvt_currCtr(QTimeEvt const * const me);
 
/*==========================================================================*/
/* QF services. */
typedef struct {
    uint8_t dummy;
} QF;
 
typedef QPSet QSubscrList;
 
/* public functions */
 
void QF_init(void);
 
void QF_psInit(QSubscrList * const subscrSto, enum_t const maxSignal);
 
void QF_poolInit(void * const poolSto, uint_fast32_t const poolSize,
                 uint_fast16_t const evtSize);
 
uint_fast16_t QF_poolGetMaxBlockSize(void);
 
int_t QF_run(void);
 
void QF_stop(void);
 
void QF_onStartup(void);
 
void QF_onCleanup(void);
 
#ifdef Q_SPY
 
    void QF_publish_(QEvt const * const e,
                     void const * const sender, uint_fast8_t const qs_id);
 
    #define QF_PUBLISH(e_, sender_) \
        (QF_publish_((e_), (void const *)(sender_), (sender_)->prio))
 
#else
 
    void QF_publish_(QEvt const * const e);
    #define QF_PUBLISH(e_, dummy_)   (QF_publish_(e_))
 
#endif
 
#ifdef Q_SPY
 
    void QF_tickX_(uint_fast8_t const tickRate, void const * const sender);
 
    #define QF_TICK_X(tickRate_, sender_) (QF_tickX_((tickRate_), (sender_)))
 
#else
 
    void QF_tickX_(uint_fast8_t const tickRate);
    #define QF_TICK_X(tickRate_, dummy)   (QF_tickX_(tickRate_))
 
#endif
 
#define QF_NO_MARGIN ((uint_fast16_t)0xFFFFU)
 
#define QF_TICK(sender_)   QF_TICK_X(0U, (sender_))
 
bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate);
 
void QF_add_(QActive * const a);
 
void QF_remove_(QActive * const a);
 
uint_fast16_t QF_getPoolMin(uint_fast8_t const poolId);
 
uint_fast16_t QF_getQueueMin(uint_fast8_t const prio);
 
QEvt *QF_newX_(uint_fast16_t const evtSize,
               uint_fast16_t const margin, enum_t const sig);
 
QEvt const *QF_newRef_(QEvt const * const e, void const * const evtRef);
 
void QF_deleteRef_(void const * const evtRef);
 
#ifdef Q_EVT_CTOR /* Shall the ctor for the ::QEvt class be provided? */
 
    #define Q_NEW(evtT_, sig_, ...)                                   \
        (evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
                      QF_NO_MARGIN, 0), (enum_t)(sig_), ##__VA_ARGS__))
 
    #define Q_NEW_X(e_, evtT_, margin_, sig_, ...) do {        \
        (e_) = (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
                                 (margin_), 0);                \
        if ((e_) != (evtT_ *)0) {                              \
            evtT_##_ctor((e_), (enum_t)(sig_), ##__VA_ARGS__); \
        }                                                      \
     } while (false)
 
#else
 
    #define Q_NEW(evtT_, sig_)                           \
        ((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
                           QF_NO_MARGIN, (enum_t)(sig_)))
 
    #define Q_NEW_X(e_, evtT_, margin_, sig_) ((e_) =   \
        (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
                          (margin_), (enum_t)(sig_)))
 
#endif /* Q_EVT_CTOR */
 
#define Q_NEW_REF(evtRef_, evtT_)  \
    ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))
 
#define Q_DELETE_REF(evtRef_) do { \
    QF_deleteRef_((evtRef_));      \
    (evtRef_) = (void *)0;         \
} while (false)
 
void QF_gc(QEvt const * const e);
 
void QF_bzero(void * const start, uint_fast16_t len);
 
#ifndef QF_CRIT_EXIT_NOP
    #define QF_CRIT_EXIT_NOP()   ((void)0)
#endif
 
extern QActive *QF_active_[QF_MAX_ACTIVE + 1U];
 
/*==========================================================================*/
typedef struct {
    QActive super; 
} QTicker;
 
void QTicker_ctor(QTicker * const me, uint_fast8_t tickRate);
 
#endif /* QF_H */