QP/C 6.8.1
qep.h
Go to the documentation of this file.
1 
40 #ifndef QEP_H
41 #define QEP_H
42 
43 /****************************************************************************/
48 #define QP_VERSION 682U
49 
54 #define QP_VERSION_STR "6.8.2"
55 
57 #define QP_RELEASE 0x886A47F5U
58 
59 
60 /****************************************************************************/
61 /* typedefs for basic numerical types; MISRA-C 2004 rule 6.3(req). */
62 
70 typedef char char_t;
71 
73 typedef int int_t;
74 
76 typedef unsigned uint_t;
77 
79 typedef int enum_t;
80 
88 typedef float float32_t;
89 
97 typedef double float64_t;
98 
100 extern char_t const QP_versionStr[7];
101 
102 /****************************************************************************/
103 #ifndef Q_SIGNAL_SIZE
104 
113  #define Q_SIGNAL_SIZE 2U
114 #endif
115 #if (Q_SIGNAL_SIZE == 1U)
116  typedef uint8_t QSignal;
117 #elif (Q_SIGNAL_SIZE == 2U)
118 
128  typedef uint16_t QSignal;
129 #elif (Q_SIGNAL_SIZE == 4U)
130  typedef uint32_t QSignal;
131 #else
132  #error "Q_SIGNAL_SIZE defined incorrectly, expected 1U, 2U, or 4U"
133 #endif
134 
135 
136 /****************************************************************************/
151 typedef struct {
154  uint8_t volatile refCtr_;
155 } QEvt;
156 
157 #ifdef Q_EVT_CTOR /* Shall the constructor for the QEvt class be provided? */
158 
162 QEvt *QEvt_ctor(QEvt * const me, enum_t const sig);
163 
164 #endif
165 
166 /****************************************************************************/
180 #define Q_HSM_UPCAST(ptr_) ((QHsm *)(ptr_))
181 
190 #define Q_EVT_CAST(class_) ((class_ const *)e)
191 
199 #define Q_UINT2PTR_CAST(type_, uintptr_) ((type_ *)(uintptr_))
200 
201 
202 /****************************************************************************/
205 
206 /* forward declaration */
207 typedef struct QXThread QXThread;
208 
210 typedef QState (*QStateHandler)(void * const me, QEvt const * const e);
211 
213 typedef QState (*QActionHandler)(void * const me);
214 
216 typedef void (*QXThreadHandler)(QXThread * const me);
217 
228 #define Q_STATE_CAST(handler_) ((QStateHandler)(handler_))
229 
237 #define Q_ACTION_CAST(action_) ((QActionHandler)(action_))
238 
239 /* forward declarations... */
240 struct QMState;
241 struct QHsmVtable;
242 typedef struct QMTranActTable QMTranActTable;
243 
250 union QHsmAttr {
254  struct QMState const *obj;
256 };
257 
258 /****************************************************************************/
282 typedef struct {
283  struct QHsmVtable const *vptr;
284  union QHsmAttr state;
285  union QHsmAttr temp;
286 } QHsm;
287 
289 struct QHsmVtable {
291  void (*init)(QHsm * const me, void const * const e);
292 
294  void (*dispatch)(QHsm * const me, QEvt const * const e);
295 };
296 
297 /* QHsm public operations... */
312 #define QHSM_INIT(me_, par_) do { \
313  Q_ASSERT((me_)->vptr); \
314  (*(me_)->vptr->init)((me_), (par_)); \
315 } while (false)
316 
318 void QHsm_init_(QHsm * const me, void const * const e);
319 
332 #define QHSM_DISPATCH(me_, e_) ((*(me_)->vptr->dispatch)((me_), (e_)))
333 
335 void QHsm_dispatch_(QHsm * const me, QEvt const * const e);
336 
345 #define QHsm_state(me_) (Q_STATE_CAST(Q_HSM_UPCAST(me_)->state.fun))
346 
356 #define QHsm_childState(me_, parent_) \
357  QHsm_childState_(Q_HSM_UPCAST(me_), Q_STATE_CAST(parent_))
358 
363 bool QHsm_isIn(QHsm * const me, QStateHandler const state);
364 
365 /* QHsm protected operations... */
369 void QHsm_ctor(QHsm * const me, QStateHandler initial);
370 
374 QState QHsm_top(void const * const me, QEvt const * const e);
375 
376 /* QHsm private operations... */
381  QStateHandler const parent);
382 
383 
384 /****************************************************************************/
407 typedef struct {
409 } QMsm;
410 
423 struct QMState {
424  struct QMState const *superstate;
429 };
430 typedef struct QMState QMState;
431 
434  struct QMState const *target;
435  QActionHandler const act[1];
436 };
437 
438 /* QMsm public operations... */
447 #define QMsm_stateObj(me_) (Q_HSM_UPCAST(me_)->state.obj)
448 
458 #define QMsm_childStateObj(me_, parent_) \
459  QMsm_childStateObj_(Q_HSM_UPCAST(me_), (parent_))
460 
464 QMState const *QMsm_childStateObj_(QMsm const * const me,
465  QMState const * const parent);
466 
471 bool QMsm_isInState(QMsm const * const me, QMState const * const state);
472 
473 /* QMsm protected operations... */
477 void QMsm_ctor(QMsm * const me, QStateHandler initial);
478 
479 /* QMsm private operations... */
483 void QMsm_init_(QHsm * const me, void const * const e);
484 
488 void QMsm_dispatch_(QHsm * const me, QEvt const * const e);
489 
490 
495 #define Q_TRAN(target_) \
496  ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)
497 
504 #define Q_TRAN_HIST(hist_) \
505  ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)
506 
513 #define Q_SUPER(super_) \
514  ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)
515 
519 #define Q_HANDLED() ((QState)Q_RET_HANDLED)
520 
525 #define Q_UNHANDLED() ((QState)Q_RET_UNHANDLED)
526 
530 #define Q_ACTION_NULL ((QActionHandler)0)
531 
532 
533 /****************************************************************************/
538 enum {
539  /* unhandled and need to "bubble up" */
544  /* handled and do not need to "bubble up" */
548  /* entry/exit */
552  /* no side effects */
555  /* transitions need to execute transition-action table in ::QMsm */
560  /* transitions that additionally clobber me->state */
563 };
564 
565 #ifdef Q_SPY
566 
569  #define QM_ENTRY(state_) \
570  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)
571 
575  #define QM_EXIT(state_) \
576  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
577 
578 #else
579  #define QM_ENTRY(dummy) ((QState)Q_RET_ENTRY)
580 
581  #define QM_EXIT(dummy) ((QState)Q_RET_EXIT)
582 
583 #endif /* Q_SPY */
584 
588 #define QM_SM_EXIT(state_) \
589  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
590 
594 #define QM_TRAN(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
595  = (QMTranActTable *)(tatbl_), (QState)Q_RET_TRAN)
596 
600 #define QM_TRAN_INIT(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
601  = (QMTranActTable *)(tatbl_), (QState)Q_RET_TRAN_INIT)
602 
606 #define QM_TRAN_HIST(history_, tatbl_) \
607  ((((Q_HSM_UPCAST(me))->state.obj = (history_)), \
608  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable *)(tatbl_))), \
609  (QState)Q_RET_TRAN_HIST)
610 
614 #define QM_TRAN_EP(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
615  = (struct QMTranActTable *)(tatbl_), (QState)Q_RET_TRAN_EP)
616 
620 #define QM_TRAN_XP(xp_, tatbl_) \
621  ((((Q_HSM_UPCAST(me))->state.act = (xp_)), \
622  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable *)(tatbl_))), \
623  (QState)Q_RET_TRAN_XP)
624 
628 #define QM_HANDLED() ((QState)Q_RET_HANDLED)
629 
635 #define QM_UNHANDLED() ((QState)Q_RET_UNHANDLED)
636 
640 #define QM_SUPER() ((QState)Q_RET_SUPER)
641 
645 #define QM_SUPER_SUB(host_) \
646  ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)
647 
651 #define QM_STATE_NULL ((QMState *)0)
652 
654 enum {
658  Q_USER_SIG
659 };
660 
661 #endif /* QEP_H */
662 
QMTranActTable::act
QActionHandler const act[1]
Definition: qep.h:435
QMState::stateHandler
QStateHandler const stateHandler
state handler function
Definition: qep.h:425
QHsmAttr::obj
struct QMState const * obj
pointer to QMState object
Definition: qep.h:254
uint8_t
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: 16bit/stdint.h:29
QMState::exitAction
QActionHandler const exitAction
exit action handler function
Definition: qep.h:427
QMState::initAction
QActionHandler const initAction
init action handler function
Definition: qep.h:428
QHsm_dispatch_
void QHsm_dispatch_(QHsm *const me, QEvt const *const e)
Implementation of dispatching events to a QHsm subclass.
Definition: qep_hsm.c:252
QHsmAttr
Attribute of for the QHsm class (Hierarchical State Machine).
Definition: qep.h:250
QHsmAttr::fun
QStateHandler fun
pointer to a state-handler function
Definition: qep.h:251
QEvt::sig
QSignal sig
signal of the event instance
Definition: qep.h:152
QMState
State object for the QMsm class (QM State Machine).
Definition: qep.h:423
QMsm::QMsm_isInState
bool QMsm_isInState(QMsm const *const me, QMState const *const state)
Tests if a given state is part of the current active state configuration in a MSM.
Definition: qep_msm.c:557
Q_RET_IGNORED
@ Q_RET_IGNORED
event silently ignored (bubbled up to top)
Definition: qep.h:546
QStateHandler
QState(* QStateHandler)(void *const me, QEvt const *const e)
Pointer to a state-handler function.
Definition: qep.h:210
QHsm_init_
void QHsm_init_(QHsm *const me, void const *const e)
Implementation of the top-most initial transition in QHsm subclass.
Definition: qep_hsm.c:146
QMTranActTable
Transition-Action Table for the Meta State Machine.
Definition: qep.h:433
QSignal
uint16_t QSignal
QSignal represents the signal of an event.
Definition: qep.h:128
Q_RET_TRAN
@ Q_RET_TRAN
regular transition
Definition: qep.h:556
Q_RET_TRAN_INIT
@ Q_RET_TRAN_INIT
initial transition in a state or submachine
Definition: qep.h:557
QHsmAttr::act
QActionHandler act
pointer to an action-handler function
Definition: qep.h:252
QMsm::QMsm_dispatch_
void QMsm_dispatch_(QHsm *const me, QEvt const *const e)
Implementation of disparching events to QMsm.
Definition: qep_msm.c:195
QMsm::QMsm_init_
void QMsm_init_(QHsm *const me, void const *const e)
Implementation of the top-most initial transition in QMsm.
Definition: qep_msm.c:142
QP_versionStr
char_t const QP_versionStr[7]
the current QP version number string in ROM, based on QP_VERSION_STR
Definition: qep_hsm.c:53
QXThread
eXtended (blocking) thread of the QXK preemptive kernel
Definition: qxthread.h:71
uint16_t
unsigned int uint16_t
exact-width 16-bit unsigned int
Definition: 16bit/stdint.h:30
Q_RET_ENTRY
@ Q_RET_ENTRY
state entry action executed
Definition: qep.h:549
Q_RET_TRAN_XP
@ Q_RET_TRAN_XP
exit-point transition out of a submachine
Definition: qep.h:562
QHsm::QHsm_ctor
void QHsm_ctor(QHsm *const me, QStateHandler initial)
Protected "constructor" of QHsm.
Definition: qep_hsm.c:126
Q_RET_EXIT
@ Q_RET_EXIT
state exit action executed
Definition: qep.h:550
Q_ENTRY_SIG
@ Q_ENTRY_SIG
signal for coding entry actions
Definition: qep.h:655
float64_t
double float64_t
IEEE 754 64-bit floating point number, MISRA-C 2004 rule 6.3(req)
Definition: qep.h:97
uint_fast8_t
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: 16bit/stdint.h:36
QHsmVtable::dispatch
void(* dispatch)(QHsm *const me, QEvt const *const e)
Dispatches an event to a SM.
Definition: qep.h:294
QHsmAttr::thr
QXThreadHandler thr
pointer to an thread-handler function
Definition: qep.h:253
QEvt::poolId_
uint8_t poolId_
pool ID (0 for static event)
Definition: qep.h:153
QState
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:204
Q_RET_HANDLED
@ Q_RET_HANDLED
event handled (internal transition)
Definition: qep.h:545
QMTranActTable::target
struct QMState const * target
Definition: qep.h:434
Q_RET_TRAN_EP
@ Q_RET_TRAN_EP
entry-point transition into a submachine
Definition: qep.h:558
QHsmAttr::tatbl
QMTranActTable const * tatbl
transition-action table
Definition: qep.h:255
QEvt
Event class.
Definition: qep.h:151
QHsm::QHsm_top
QState QHsm_top(void const *const me, QEvt const *const e)
the top-state.
Definition: qep_hsm.c:233
float32_t
float float32_t
IEEE 754 32-bit floating point number, MISRA-C 2004 rule 6.3(req)
Definition: qep.h:88
QMState::entryAction
QActionHandler const entryAction
entry action handler function
Definition: qep.h:426
QMsm::super
QHsm super
inherits QHsm
Definition: qep.h:408
Q_EXIT_SIG
@ Q_EXIT_SIG
signal for coding exit actions
Definition: qep.h:656
QHsm::vptr
struct QHsmVtable const * vptr
virtual pointer
Definition: qep.h:283
QXThreadHandler
void(* QXThreadHandler)(QXThread *const me)
Pointer to a thread-handler function.
Definition: qep.h:216
QEvt::refCtr_
uint8_t volatile refCtr_
reference counter
Definition: qep.h:154
QHsm
Hierarchical State Machine class.
Definition: qep.h:282
QActionHandler
QState(* QActionHandler)(void *const me)
Pointer to an action-handler function.
Definition: qep.h:213
QMsm
QM State Machine implementation strategy.
Definition: qep.h:407
char_t
char char_t
typedef for character strings.
Definition: qassert.h:77
QHsmVtable
Virtual table for the QHsm class.
Definition: qep.h:289
QMState::superstate
struct QMState const * superstate
superstate of this state
Definition: qep.h:424
QHsm::QHsm_childState_
QStateHandler QHsm_childState_(QHsm *const me, QStateHandler const parent)
Helper function to obtain the current active child state of a parent.
Definition: qep_hsm.c:605
Q_RET_NULL
@ Q_RET_NULL
return value without any effect
Definition: qep.h:553
Q_RET_TRAN_HIST
@ Q_RET_TRAN_HIST
transition to history of a given state
Definition: qep.h:561
int_t
int int_t
typedef for line numbers in assertions and return from QF_run()
Definition: qep.h:73
QMsm::QMsm_childStateObj_
QMState const * QMsm_childStateObj_(QMsm const *const me, QMState const *const parent)
Helper function to obtain the current active child state of a parent.
Definition: qep_msm.c:588
Q_RET_SUPER_SUB
@ Q_RET_SUPER_SUB
event passed to submachine superstate
Definition: qep.h:541
uint_t
unsigned uint_t
typedef for unsigned int promotions in expressions
Definition: qep.h:76
enum_t
int enum_t
typedef for enumerations used for event signals
Definition: qep.h:79
QHsm::QHsm_isIn
bool QHsm_isIn(QHsm *const me, QStateHandler const state)
Tests if a given state is part of the current active state configuration in QHsm subclasses.
Definition: qep_hsm.c:559
Q_INIT_SIG
@ Q_INIT_SIG
signal for coding initial transitions
Definition: qep.h:657
Q_USER_SIG
@ Q_USER_SIG
first signal that can be used for user signals
Definition: qep.h:658
char_t
char char_t
typedef for character strings.
Definition: qep.h:70
Q_RET_UNHANDLED
@ Q_RET_UNHANDLED
event unhandled due to a guard
Definition: qep.h:542
Q_RET_SUPER
@ Q_RET_SUPER
event passed to superstate to handle
Definition: qep.h:540
QHsmVtable::init
void(* init)(QHsm *const me, void const *const e)
Triggers the top-most initial transition in a HSM.
Definition: qep.h:291
QMsm::QMsm_ctor
void QMsm_ctor(QMsm *const me, QStateHandler initial)
Constructor of QMsm.
Definition: qep_msm.c:119
uint32_t
unsigned long int uint32_t
exact-width 32-bit unsigned int
Definition: 16bit/stdint.h:31