qf.h

Go to the documentation of this file.

/*****************************************************************************
* Product:  QF/C platform-independent public interface
* Last Updated for Version: 4.4.00
* Date of the Last Update:  Jan 17, 2012
*
*                    Q u a n t u m     L e a P s
*                    ---------------------------
*                    innovating embedded systems
*
* Copyright (C) 2002-2012 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

/****************************************************************************/
#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_CTOR_(me_, initial_) QHsm_ctor((me_), (initial_))

    #define QF_ACTIVE_INIT_(me_, e_)       QHsm_init((me_), (e_))

    #define QF_ACTIVE_DISPATCH_(me_, e_)   QHsm_dispatch((me_), (e_))

    #define QF_ACTIVE_STATE_               QStateHandler

#endif

struct QEQueueTag;                                   /* forward declaration */

/****************************************************************************/
typedef struct QActiveTag {
    QF_ACTIVE_SUPER_ super;

    QF_EQUEUE_TYPE eQueue;

#ifdef QF_OS_OBJECT_TYPE

    QF_OS_OBJECT_TYPE osObject;
#endif

#ifdef QF_THREAD_TYPE

    QF_THREAD_TYPE thread;
#endif

    uint8_t prio;

    uint8_t running;
} QActive;

/* public functions */
void QActive_start(QActive *me, uint8_t prio,
                   QEvent const *qSto[], uint32_t qLen,
                   void *stkSto, uint32_t stkSize,
                   QEvent const *ie);

#ifdef Q_SPY

    void QActive_postFIFO(QActive *me, QEvent const *e,
                          void const *sender);


    #define QACTIVE_POST(me_, e_, sender_) \
        QActive_postFIFO((me_), (e_), (sender_))

#else

    void QActive_postFIFO(QActive *me, QEvent const *e);
    #define QACTIVE_POST(me_, e_, dummy_) QActive_postFIFO((me_), (e_))

#endif

void QActive_postLIFO(QActive *me, QEvent const *e);

/* protected functions ...*/

#define QActive_ctor(me_, initial_) QF_ACTIVE_CTOR_(&(me_)->super, (initial_))

void QActive_stop(QActive *me);

void QActive_subscribe(QActive const *me, QSignal sig);

void QActive_unsubscribe(QActive const *me, QSignal sig);

void QActive_unsubscribeAll(QActive const *me);


void QActive_defer(QActive *me, QEQueue *eq, QEvent const *e);

uint8_t QActive_recall(QActive *me, QEQueue *eq);

QEvent const *QActive_get_(QActive *me);
/* friend class QF; */
/* friend class QTimeEvt; */

/****************************************************************************/
#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

typedef struct QTimeEvtTag {
    QEvent super;

    struct QTimeEvtTag *prev;

    struct QTimeEvtTag *next;

    QActive *act;

    QTimeEvtCtr ctr;

    QTimeEvtCtr interval;
} QTimeEvt;

/* public functions */

void QTimeEvt_ctor(QTimeEvt *me, QSignal sig);

#define QTimeEvt_postIn(me_, act_, nTicks_) do { \
    (me_)->interval = (QTimeEvtCtr)0; \
    QTimeEvt_arm_((me_), (act_), (nTicks_)); \
} while (0)

#define QTimeEvt_postEvery(me_, act_, nTicks_) do { \
    (me_)->interval = (nTicks_); \
    QTimeEvt_arm_((me_), (act_), (nTicks_)); \
} while (0)

uint8_t QTimeEvt_disarm(QTimeEvt *me);

uint8_t QTimeEvt_rearm(QTimeEvt *me, QTimeEvtCtr nTicks);

QTimeEvtCtr QTimeEvt_ctr(QTimeEvt const *me);

/* private functions */

void QTimeEvt_arm_(QTimeEvt *me, QActive *act, QTimeEvtCtr nTicks);

/* friend class QF; */

/*****************************************************************************
* QF facilities
*/

typedef struct QSubscrListTag {

    uint8_t bits[((QF_MAX_ACTIVE - 1) / 8) + 1];
} QSubscrList;

/* public functions */

void QF_init(void);

void QF_psInit(QSubscrList *subscrSto, QSignal maxSignal);

void QF_poolInit(void *poolSto, uint32_t poolSize, QEventSize evtSize);

void QF_run(void);

void QF_stop(void);

void QF_onStartup(void);

void QF_onCleanup(void);

void QF_onIdle(void);

#ifdef Q_SPY

    void QF_publish(QEvent const *e, void const *sender);

    #define QF_PUBLISH(e_, sender_)        QF_publish((e_), (sender_))

#else

    void QF_publish(QEvent const *e);
    #define QF_PUBLISH(e_, dummy_)        QF_publish(e_)

#endif

#ifdef Q_SPY

    void QF_tick(void const *sender);

    #define QF_TICK(sender_)              QF_tick(sender_)

#else

    void QF_tick(void);
    #define QF_TICK(dummy_)               QF_tick()

#endif

/* functions used in the QF ports only -------------------------------------*/

void QF_add_(QActive *a);

void QF_remove_(QActive const *a);

char_t const Q_ROM * Q_ROM_VAR QF_getVersion(void);

char_t const Q_ROM * Q_ROM_VAR QF_getPortVersion(void);

uint32_t QF_getPoolMargin(uint8_t poolId);

uint32_t QF_getQueueMargin(uint8_t prio);

QEvent *QF_new_(QEventSize evtSize, QSignal sig);

#define Q_NEW(evtT_, sig_) \
    ((evtT_ *)QF_new_((QEventSize)sizeof(evtT_), (QSignal)(sig_)))

void QF_gc(QEvent const *e);

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];


extern QActive *QF_active_[];

#endif                                                              /* qf_h */