QP/C  6.1.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 611
49 
54 #define QP_VERSION_STR "6.1.1"
55 
57 #define QP_RELEASE 0x9494E7FCU
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 int enum_t;
77 
85 typedef float float32_t;
86 
94 typedef double float64_t;
95 
96 
98 extern char_t const QP_versionStr[6];
99 
101 #define QEP_getVersion() (QP_versionStr)
102 
103 
104 /****************************************************************************/
105 #ifndef Q_SIGNAL_SIZE
106 
115  #define Q_SIGNAL_SIZE 2
116 #endif
117 #if (Q_SIGNAL_SIZE == 1)
118  typedef uint8_t QSignal;
119 #elif (Q_SIGNAL_SIZE == 2)
120 
130  typedef uint16_t QSignal;
131 #elif (Q_SIGNAL_SIZE == 4)
132  typedef uint32_t QSignal;
133 #else
134  #error "Q_SIGNAL_SIZE defined incorrectly, expected 1, 2, or 4"
135 #endif
136 
137 
138 /****************************************************************************/
153 typedef struct {
156  uint8_t volatile refCtr_;
157 } QEvt;
158 
159 #ifdef Q_EVT_CTOR /* Shall the constructor for the QEvt class be provided? */
160 
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 
193 #define Q_DIM(array_) (sizeof(array_) / sizeof((array_)[0]))
194 
204 #define Q_UINT2PTR_CAST(type_, uint_) ((type_ *)(uint_))
205 
206 
207 /****************************************************************************/
210 
212 typedef QState (*QStateHandler)(void * const me, QEvt const * const e);
213 
215 typedef QState (*QActionHandler)(void * const me);
216 
227 #define Q_STATE_CAST(handler_) ((QStateHandler)(handler_))
228 
236 #define Q_ACTION_CAST(action_) ((QActionHandler)(action_))
237 
238 /* forward declarations... */
239 struct QMState;
240 struct QMTranActTable;
241 struct QHsmVtbl;
242 
249 union QHsmAttr {
252  struct QMState const *obj;
253  struct QMTranActTable const *tatbl;
254 };
255 
256 /****************************************************************************/
257 /* Hierarchical State Machine */
258 
281 typedef struct {
282  struct QHsmVtbl const *vptr;
283  union QHsmAttr state;
284  union QHsmAttr temp;
285 } QHsm;
286 
288 struct QHsmVtbl {
290  void (*init)(QHsm * const me, QEvt const * const e);
291 
293  void (*dispatch)(QHsm * const me, QEvt const * const e);
294 };
295 
297 void QHsm_ctor(QHsm * const me, QStateHandler initial);
298 
311 #define QHSM_INIT(me_, e_) ((*(me_)->vptr->init)((me_), (e_)))
312 
314 void QHsm_init_(QHsm * const me, QEvt const * const e);
315 
326 #define QHSM_DISPATCH(me_, e_) ((*(me_)->vptr->dispatch)((me_), (e_)))
327 
329 void QHsm_dispatch_(QHsm * const me, QEvt const * const e);
330 
337 #define QHsm_state(me_) (Q_STATE_CAST(Q_HSM_UPCAST(me_)->state.fun))
338 
346 #define QHsm_childState(me_, parent_) \
347  QHsm_childState_(Q_HSM_UPCAST(me_), Q_STATE_CAST(parent_))
348 
351  QStateHandler const parent);
352 
356 bool QHsm_isIn(QHsm * const me, QStateHandler const state);
357 
358 /* protected methods */
359 
361 QState QHsm_top(void const * const me, QEvt const * const e);
362 
363 
364 /****************************************************************************/
385 typedef QHsm QMsm;
386 
388 typedef struct QHsmVtbl QMsmVtbl;
389 
402 typedef struct QMState {
403  struct QMState const *superstate;
408 } QMState;
409 
411 typedef struct QMTranActTable {
412  QMState const *target;
413  QActionHandler const act[1];
415 
417 void QMsm_ctor(QMsm * const me, QStateHandler initial);
418 
420 void QMsm_init_(QMsm * const me, QEvt const * const e);
421 
423 void QMsm_dispatch_(QMsm * const me, QEvt const * const e);
424 
431 #define QMsm_stateObj(me_) (Q_HSM_UPCAST(me_)->state.obj)
432 
440 #define QMsm_childStateObj(me_, parent_) \
441  QMsm_childStateObj_(Q_HSM_UPCAST(me_), (parent_))
442 
444 QMState const *QMsm_childStateObj_(QMsm const * const me,
445  QMState const * const parent);
446 
450 bool QMsm_isInState(QMsm const * const me, QMState const * const state);
451 
456 #define Q_TRAN(target_) \
457  ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)
458 
465 #define Q_TRAN_HIST(hist_) \
466  ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)
467 
474 #define Q_SUPER(super_) \
475  ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)
476 
480 #define Q_HANDLED() ((QState)Q_RET_HANDLED)
481 
486 #define Q_UNHANDLED() ((QState)Q_RET_UNHANDLED)
487 
488 
489 /****************************************************************************/
494 enum {
495  /* unhandled and need to "bubble up" */
500  /* handled and do not need to "bubble up" */
504  /* entry/exit */
508  /* no side effects */
511  /* transitions need to execute transition-action table in ::QMsm */
516  /* transitions that additionally clobber me->state */
519 };
520 
521 #ifdef Q_SPY
522 
525  #define QM_ENTRY(state_) \
526  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)
527 
531  #define QM_EXIT(state_) \
532  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
533 
534 #else
535  #define QM_ENTRY(dummy) ((QState)Q_RET_ENTRY)
536 
537  #define QM_EXIT(dummy) ((QState)Q_RET_EXIT)
538 
539 #endif /* Q_SPY */
540 
544 #define QM_SM_EXIT(state_) \
545  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
546 
550 #define QM_TRAN(tatbl_) \
551  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \
552  (QState)Q_RET_TRAN)
553 
557 #define QM_TRAN_INIT(tatbl_) \
558  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \
559  (QState)Q_RET_TRAN_INIT)
560 
564 #define QM_TRAN_HIST(history_, tatbl_) \
565  ((((Q_HSM_UPCAST(me))->state.obj = (history_)), \
566  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))), \
567  (QState)Q_RET_TRAN_HIST)
568 
572 #define QM_TRAN_EP(tatbl_) \
573  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \
574  (QState)Q_RET_TRAN_EP)
575 
579 #define QM_TRAN_XP(xp_, tatbl_) \
580  ((((Q_HSM_UPCAST(me))->state.act = (xp_)), \
581  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))),\
582  (QState)Q_RET_TRAN_XP)
583 
587 #define QM_HANDLED() ((QState)Q_RET_HANDLED)
588 
594 #define QM_UNHANDLED() ((QState)Q_RET_UNHANDLED)
595 
599 #define QM_SUPER() ((QState)Q_RET_SUPER)
600 
604 #define QM_SUPER_SUB(host_) \
605  ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)
606 
608 enum {
613 };
614 
615 #endif /* qep_h */
616 
QState(* QStateHandler)(void *const me, QEvt const *const e)
Pointer to a state-handler function.
Definition: qep.h:212
initial transition in a state or submachine
Definition: qep.h:513
regular transition
Definition: qep.h:512
QStateHandler fun
pointer to a state-handler function
Definition: qep.h:250
event handled (internal transition)
Definition: qep.h:501
event silently ignored (bubbled up to top)
Definition: qep.h:502
QSignal sig
signal of the event instance
Definition: qep.h:154
event passed to submachine superstate
Definition: qep.h:497
transition to history of a given state
Definition: qep.h:517
char char_t
typedef for character strings.
Definition: qep.h:70
entry-point transition into a submachine
Definition: qep.h:514
char_t const QP_versionStr[6]
the current QP version number string in ROM, based on QP_VERSION_STR
Definition: qep_hsm.c:52
Virtual table for the QHsm class.
Definition: qep.h:288
struct QHsmVtbl const * vptr
virtual pointer
Definition: qep.h:282
QState QHsm_top(void const *const me, QEvt const *const e)
the top-state.
Definition: qep_hsm.c:233
first signal that can be used for user signals
Definition: qep.h:612
unsigned short uint16_t
exact-width 16-bit unsigned int
Definition: stdint.h:29
event passed to superstate to handle
Definition: qep.h:496
void QHsm_dispatch_(QHsm *const me, QEvt const *const e)
Implementation of dispatching events to a QHsm subclass.
Definition: qep_hsm.c:252
event unhandled due to a guard
Definition: qep.h:498
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:28
void QHsm_init_(QHsm *const me, QEvt const *const e)
Implementation of the top-most initial transition in QHsm subclass.
Definition: qep_hsm.c:147
QActionHandler const entryAction
entry action handler function
Definition: qep.h:405
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:558
void(* init)(QHsm *const me, QEvt const *const e)
Triggers the top-most initial transition in a HSM.
Definition: qep.h:290
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
QHsm QMsm
QM State Machine implementation strategy.
Definition: qep.h:385
void QMsm_ctor(QMsm *const me, QStateHandler initial)
Protected "constructor" of QMsm.
Definition: qep_msm.c:111
int enum_t
typedef for enumerations used for event signals
Definition: qep.h:76
void QMsm_dispatch_(QMsm *const me, QEvt const *const e)
Implementation of disparching events to QMsm.
Definition: qep_msm.c:184
uint16_t QSignal
QSignal represents the signal of an event.
Definition: qep.h:130
return value without any effect
Definition: qep.h:509
QActionHandler const exitAction
exit action handler function
Definition: qep.h:406
Event structure.
Definition: qep.h:153
void(* dispatch)(QHsm *const me, QEvt const *const e)
Dispatches an event to a SM.
Definition: qep.h:293
uint8_t volatile refCtr_
reference counter
Definition: qep.h:156
void QHsm_ctor(QHsm *const me, QStateHandler initial)
Protected "constructor" of QHsm.
Definition: qep_hsm.c:127
signal for coding entry actions
Definition: qep.h:609
State object for the QMsm class (QM State Machine).
Definition: qep.h:402
uint8_t poolId_
pool ID (0 for static event)
Definition: qep.h:155
unsigned long uint32_t
exact-width 32-bit unsigned int
Definition: stdint.h:30
QActionHandler act
pointer to an action-handler function
Definition: qep.h:251
Definition: qep.h:281
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:209
state entry action executed
Definition: qep.h:505
exit-point transition out of a submachine
Definition: qep.h:518
QState(* QActionHandler)(void *const me)
Pointer to an action-handler function.
Definition: qep.h:215
QStateHandler const stateHandler
state handler function
Definition: qep.h:404
void QMsm_init_(QMsm *const me, QEvt const *const e)
Implementation of the top-most initial transition in QMsm.
Definition: qep_msm.c:133
Attribute of for the QHsm class (Hierarchical State Machine).
Definition: qep.h:249
state exit action executed
Definition: qep.h:506
struct QMTranActTable const * tatbl
transition-action table
Definition: qep.h:253
float float32_t
IEEE 754 32-bit floating point number, MISRA-C 2004 rule 6.3(req)
Definition: qep.h:85
struct QMState const * obj
pointer to QMState object
Definition: qep.h:252
int int_t
typedef for line numbers in assertions and return from QF_run()
Definition: qep.h:73
QActionHandler const initAction
init action handler function
Definition: qep.h:407
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:527
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:606
double float64_t
IEEE 754 64-bit floating point number, MISRA-C 2004 rule 6.3(req)
Definition: qep.h:94
signal for coding initial transitions
Definition: qep.h:611
struct QMState const * superstate
superstate of this state
Definition: qep.h:403
signal for coding exit actions
Definition: qep.h:610
Transition-Action Table for the Meta State Machine.
Definition: qep.h:411
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:561