qep.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 QEP_H
#define QEP_H
 
/*==========================================================================*/
#define QP_VERSION      700U
 
#define QP_VERSION_STR  "7.0.0"
 
#define QP_RELEASE      0x7CCAAA13U
 
/*==========================================================================*/
/* typedefs for basic numerical types; MISRA-C 2012 Dir 4.6(A). */
 
typedef signed int int_t;
 
typedef signed int enum_t;
 
typedef float float32_t;
 
typedef double float64_t;
 
extern char const QP_versionStr[7];
 
/*==========================================================================*/
#ifndef Q_SIGNAL_SIZE
    #define Q_SIGNAL_SIZE 2U
#endif
#if (Q_SIGNAL_SIZE == 1U)
    typedef uint8_t QSignal;
#elif (Q_SIGNAL_SIZE == 2U)
    typedef uint16_t QSignal;
#elif (Q_SIGNAL_SIZE == 4U)
    typedef uint32_t QSignal;
#else
    #error "Q_SIGNAL_SIZE defined incorrectly, expected 1U, 2U, or 4U"
#endif
 
/*==========================================================================*/
typedef struct {
    QSignal sig;
 
    uint8_t poolId_;
 
    uint8_t volatile refCtr_;
} QEvt;
 
#ifdef Q_EVT_CTOR /* Shall the constructor for the ::QEvt class be provided? */
 
QEvt *QEvt_ctor(QEvt * const me, enum_t const sig);
 
#endif
 
/*==========================================================================*/
#define Q_EVT_CAST(class_) ((class_ const *)e)
 
#define Q_UINT2PTR_CAST(type_, uintptr_)  ((type_ *)(uintptr_))
 
/*==========================================================================*/
typedef uint_fast8_t QState;
 
/* forward declaration */
typedef struct QXThread QXThread;
 
typedef QState (*QStateHandler)(void * const me, QEvt const * const e);
 
typedef QState (*QActionHandler)(void * const me);
 
typedef void (*QXThreadHandler)(QXThread * const me);
 
#define Q_STATE_CAST(handler_)  ((QStateHandler)(handler_))
 
#define Q_ACTION_CAST(action_)  ((QActionHandler)(action_))
 
/* forward declarations... */
struct QMState;
struct QHsmVtable;
typedef struct QMTranActTable QMTranActTable;
 
union QHsmAttr {
    QStateHandler   fun;         
    QActionHandler  act;         
    QXThreadHandler thr;         
    struct QMState const *obj;   
    QMTranActTable const *tatbl; 
};
 
/*==========================================================================*/
typedef struct {
    struct QHsmVtable const *vptr; 
    union QHsmAttr state; 
    union QHsmAttr temp;  
} QHsm;
 
struct QHsmVtable {
#ifdef Q_SPY
    void (*init)(QHsm * const me, void const * const e,
                 uint_fast8_t const qs_id);
 
    void (*dispatch)(QHsm * const me, QEvt const * const e,
                     uint_fast8_t const qs_id);
 
    QStateHandler (*getStateHandler)(QHsm * const me);
#else
    void (*init)(QHsm * const me, void const * const e);
    void (*dispatch)(QHsm * const me, QEvt const * const e);
#endif /* Q_SPY */
};
 
/* QHsm public operations... */
#ifdef Q_SPY
    #define QHSM_INIT(me_, par_, qs_id_) do {          \
        Q_ASSERT((me_)->vptr);                         \
        (*(me_)->vptr->init)((me_), (par_), (qs_id_)); \
    } while (false)
 
    void QHsm_init_(QHsm * const me, void const * const e,
                    uint_fast8_t const qs_id);
#else
 
    #define QHSM_INIT(me_, par_, dummy) do { \
        Q_ASSERT((me_)->vptr);               \
        (*(me_)->vptr->init)((me_), (par_)); \
    } while (false)
 
    void QHsm_init_(QHsm * const me, void const * const e);
 
#endif /* Q_SPY */
 
#ifdef Q_SPY
    #define QHSM_DISPATCH(me_, e_, qs_id_) \
        ((*(me_)->vptr->dispatch)((me_), (e_), (qs_id_)))
 
    void QHsm_dispatch_(QHsm * const me, QEvt const * const e,
                        uint_fast8_t const qs_id);
 
    QStateHandler QHsm_getStateHandler_(QHsm * const me);
#else
 
    #define QHSM_DISPATCH(me_, e_, dummy) \
        ((*(me_)->vptr->dispatch)((me_), (e_)))
 
    void QHsm_dispatch_(QHsm * const me, QEvt const * const e);
 
#endif /* Q_SPY */
 
#define Q_HSM_UPCAST(ptr_) ((QHsm *)(ptr_))
 
static inline QStateHandler QHsm_state(QHsm * const me) {
    return Q_STATE_CAST(me->state.fun);
}
 
QStateHandler QHsm_childState(QHsm * const me,
                              QStateHandler const parent);
 
bool QHsm_isIn(QHsm * const me, QStateHandler const state);
 
/* QHsm protected operations... */
void QHsm_ctor(QHsm * const me, QStateHandler initial);
 
QState QHsm_top(void const * const me, QEvt const * const e);
 
/*==========================================================================*/
typedef struct {
    QHsm super; 
} QMsm;
 
struct QMState {
    struct QMState const *superstate;  
    QStateHandler  const stateHandler; 
    QActionHandler const entryAction;  
    QActionHandler const exitAction;   
    QActionHandler const initAction;   
};
typedef struct QMState QMState;
 
struct QMTranActTable {
    struct QMState const *target;      
    QActionHandler const act[1];       
};
 
/* QMsm public operations... */
static inline QMState const *QMsm_stateObj(QHsm * const me) {
    return me->state.obj;
}
 
QMState const *QMsm_childStateObj(QHsm const * const me,
                                  QMState const * const parent);
 
bool QMsm_isInState(QMsm const * const me, QMState const * const state);
 
/* QMsm protected operations... */
void QMsm_ctor(QMsm * const me, QStateHandler initial);
 
/* QMsm private operations... */
#ifdef Q_SPY
void QMsm_init_(QHsm * const me, void const * const e,
                uint_fast8_t const qs_id);
#else
void QMsm_init_(QHsm * const me, void const * const e);
#endif
 
#ifdef Q_SPY
void QMsm_dispatch_(QHsm * const me, QEvt const * const e,
                    uint_fast8_t const qs_id);
#else
void QMsm_dispatch_(QHsm * const me, QEvt const * const e);
#endif
 
#ifdef Q_SPY
QStateHandler QMsm_getStateHandler_(QHsm * const me);
#endif
 
#define Q_TRAN(target_)  \
    ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)
 
#define Q_TRAN_HIST(hist_)  \
    ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)
 
#define Q_SUPER(super_)  \
    ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)
 
#define Q_HANDLED()      ((QState)Q_RET_HANDLED)
 
#define Q_UNHANDLED()    ((QState)Q_RET_UNHANDLED)
 
#define Q_ACTION_NULL    ((QActionHandler)0)
 
/*==========================================================================*/
enum {
    /* unhandled and need to "bubble up" */
    Q_RET_SUPER,     
    Q_RET_SUPER_SUB, 
    Q_RET_UNHANDLED, 
    /* handled and do not need to "bubble up" */
    Q_RET_HANDLED,   
    Q_RET_IGNORED,   
    /* entry/exit */
    Q_RET_ENTRY,     
    Q_RET_EXIT,      
    /* no side effects */
    Q_RET_NULL,      
    /* transitions need to execute transition-action table in ::QMsm */
    Q_RET_TRAN,      
    Q_RET_TRAN_INIT, 
    Q_RET_TRAN_EP,   
    /* transitions that additionally clobber me->state */
    Q_RET_TRAN_HIST, 
    Q_RET_TRAN_XP    
};
 
#ifdef Q_SPY
    #define QM_ENTRY(state_) \
        ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)
 
    #define QM_EXIT(state_) \
        ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
 
#else
    #define QM_ENTRY(dummy) ((QState)Q_RET_ENTRY)
 
    #define QM_EXIT(dummy)  ((QState)Q_RET_EXIT)
 
#endif /* Q_SPY */
 
#define QM_SM_EXIT(state_) \
    ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
 
#define QM_TRAN(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
      = (QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN)
 
#define QM_TRAN_INIT(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
    = (QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN_INIT)
 
#define QM_TRAN_HIST(history_, tatbl_)                                      \
    ((((Q_HSM_UPCAST(me))->state.obj  = (history_)),                        \
      ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))), \
     (QState)Q_RET_TRAN_HIST)
 
#define QM_TRAN_EP(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
    = (QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN_EP)
 
#define QM_TRAN_XP(xp_, tatbl_)                                             \
    ((((Q_HSM_UPCAST(me))->state.act  = (xp_)),                             \
      ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))), \
     (QState)Q_RET_TRAN_XP)
 
#define QM_HANDLED()     ((QState)Q_RET_HANDLED)
 
#define QM_UNHANDLED()   ((QState)Q_RET_UNHANDLED)
 
#define QM_SUPER()       ((QState)Q_RET_SUPER)
 
#define QM_SUPER_SUB(host_) \
    ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)
 
#define QM_STATE_NULL    ((QMState *)0)
 
enum {
    Q_ENTRY_SIG = 1,  
    Q_EXIT_SIG,       
    Q_INIT_SIG,       
    Q_USER_SIG        
};
 
#endif /* QEP_H */