qf.h

Go to the documentation of this file.

/*****************************************************************************
* Product: QP/C
* Last Updated for Version: 4.5.04
* Date of the Last Update:  Feb 05, 2013
*
*                    Q u a n t u m     L e a P s
*                    ---------------------------
*                    innovating embedded systems
*
* Copyright (C) 2002-2013 Quantum Leaps, LLC. All rights reserved.
*
* This program is open source software: you can redistribute it and/or
* modify it under the terms of the GNU General Public License as published
* by the Free Software Foundation, either version 2 of the License, or
* (at your option) any later version.
*
* Alternatively, this program may be distributed and modified under the
* terms of Quantum Leaps commercial licenses, which expressly supersede
* the GNU General Public License and are specifically designed for
* licensees interested in retaining the proprietary status of their code.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* Contact information:
* Quantum Leaps Web sites: http://www.quantum-leaps.com
*                          http://www.state-machine.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 QEvtSize;
#elif (QF_EVENT_SIZ_SIZE == 2)
    typedef uint16_t QEvtSize;
#elif (QF_EVENT_SIZ_SIZE == 4)
    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 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;

#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

    uint8_t prio;

} QActive;

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

#ifdef Q_SPY

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

    #define QACTIVE_POST(me_, e_, sender_) \
        (QActive_postFIFO((me_), (e_), (void const *)(sender_)))

#else

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

#endif

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

/* protected functions ...*/

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

void QActive_stop(QActive * const me);

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


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

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

QEvt const *QActive_get_(QActive *const 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 {
    QEvt super;

    struct QTimeEvtTag *next;

    QActive *act;

    QTimeEvtCtr ctr;

    QTimeEvtCtr interval;
} QTimeEvt;

/* public functions */

void QTimeEvt_ctor(QTimeEvt * const me, enum_t const 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 * const me);

uint8_t QTimeEvt_rearm(QTimeEvt * const me, QTimeEvtCtr const nTicks);

QTimeEvtCtr QTimeEvt_ctr(QTimeEvt const * const me);

/* private functions */

void QTimeEvt_arm_(QTimeEvt * const me,
                   QActive * const act, QTimeEvtCtr const 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 * const subscrSto, uint32_t const maxSignal);

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

int16_t 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(QEvt const * const e, void const * const sender);

    #define QF_PUBLISH(e_, sender_) \
        (QF_publish((e_), (void const *)(sender_)))
#else

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

#endif

#ifdef Q_SPY

    void QF_tick(void const * const sender);

    #define QF_TICK(sender_)              (QF_tick(sender_))

#else

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

#endif

uint8_t QF_noTimeEvtsActive(void);


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

void QF_add_(QActive * const a);

void QF_remove_(QActive const * 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 const poolId);

uint32_t QF_getQueueMargin(uint8_t const prio);


#ifdef Q_EVT_CTOR            /* Provide the constructor for the QEvt class? */

    QEvt *QF_new_(QEvtSize const evtSize);

    #define Q_NEW(evtT_, sig_, ...) \
        (evtT_##_ctor((evtT_ *)QF_new_((QEvtSize)sizeof(evtT_)), \
                      (sig_), ##__VA_ARGS__))
#else

    QEvt *QF_new_(QEvtSize const evtSize, enum_t const sig);

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

#endif                                                        /* Q_EVT_CTOR */


void QF_gc(QEvt const * const e);


/****************************************************************************/
/* Useful lookup tables ...*/
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];

/* Log-base-2 calculations ...*/
#ifndef QF_LOG2

    #define QF_LOG2(n_) (Q_ROM_BYTE(QF_log2Lkup[(n_)]))

    extern uint8_t const Q_ROM Q_ROM_VAR QF_log2Lkup[256];

#endif                                                           /* QF_LOG2 */


extern QActive *QF_active_[QF_MAX_ACTIVE + 1];

#endif                                                              /* qf_h */