QP/C  6.5.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 651U
49 
54 #define QP_VERSION_STR "6.5.1"
55 
57 #define QP_RELEASE 0x8E7055B4U
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[7];
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 
201 #define Q_UINT2PTR_CAST(type_, uint_) ((type_ *)(uint_))
202 
203 
204 /****************************************************************************/
207 
209 typedef QState (*QStateHandler)(void * const me, QEvt const * const e);
210 
212 typedef QState (*QActionHandler)(void * const me);
213 
224 #define Q_STATE_CAST(handler_) ((QStateHandler)(handler_))
225 
233 #define Q_ACTION_CAST(action_) ((QActionHandler)(action_))
234 
235 /* forward declarations... */
236 struct QMState;
237 struct QMTranActTable;
238 struct QHsmVtbl;
239 
246 union QHsmAttr {
249  struct QMState const *obj;
250  struct QMTranActTable const *tatbl;
251 };
252 
253 /****************************************************************************/
254 /* Hierarchical State Machine */
255 
278 typedef struct {
279  struct QHsmVtbl const *vptr;
280  union QHsmAttr state;
281  union QHsmAttr temp;
282 } QHsm;
283 
285 struct QHsmVtbl {
287  void (*init)(QHsm * const me, QEvt const * const e);
288 
290  void (*dispatch)(QHsm * const me, QEvt const * const e);
291 };
292 
294 void QHsm_ctor(QHsm * const me, QStateHandler initial);
295 
308 #define QHSM_INIT(me_, e_) do { \
309  Q_ASSERT((me_)->vptr); \
310  (*(me_)->vptr->init)((me_), (e_)); \
311 } while (0)
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 
491 #define Q_ACTION_NULL ((QActionHandler)0)
492 
493 
494 /****************************************************************************/
499 enum {
500  /* unhandled and need to "bubble up" */
505  /* handled and do not need to "bubble up" */
509  /* entry/exit */
513  /* no side effects */
516  /* transitions need to execute transition-action table in ::QMsm */
521  /* transitions that additionally clobber me->state */
524 };
525 
526 #ifdef Q_SPY
527 
530  #define QM_ENTRY(state_) \
531  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)
532 
536  #define QM_EXIT(state_) \
537  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
538 
539 #else
540  #define QM_ENTRY(dummy) ((QState)Q_RET_ENTRY)
541 
542  #define QM_EXIT(dummy) ((QState)Q_RET_EXIT)
543 
544 #endif /* Q_SPY */
545 
549 #define QM_SM_EXIT(state_) \
550  ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
551 
555 #define QM_TRAN(tatbl_) \
556  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \
557  (QState)Q_RET_TRAN)
558 
562 #define QM_TRAN_INIT(tatbl_) \
563  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \
564  (QState)Q_RET_TRAN_INIT)
565 
569 #define QM_TRAN_HIST(history_, tatbl_) \
570  ((((Q_HSM_UPCAST(me))->state.obj = (history_)), \
571  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))), \
572  (QState)Q_RET_TRAN_HIST)
573 
577 #define QM_TRAN_EP(tatbl_) \
578  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_), \
579  (QState)Q_RET_TRAN_EP)
580 
584 #define QM_TRAN_XP(xp_, tatbl_) \
585  ((((Q_HSM_UPCAST(me))->state.act = (xp_)), \
586  ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))),\
587  (QState)Q_RET_TRAN_XP)
588 
592 #define QM_HANDLED() ((QState)Q_RET_HANDLED)
593 
599 #define QM_UNHANDLED() ((QState)Q_RET_UNHANDLED)
600 
604 #define QM_SUPER() ((QState)Q_RET_SUPER)
605 
609 #define QM_SUPER_SUB(host_) \
610  ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)
611 
615 #define QM_STATE_NULL ((QMState const *)0)
616 
618 enum {
623 };
624 
625 #endif /* qep_h */
626 
QState(* QStateHandler)(void *const me, QEvt const *const e)
Pointer to a state-handler function.
Definition: qep.h:209
initial transition in a state or submachine
Definition: qep.h:518
regular transition
Definition: qep.h:517
QStateHandler fun
pointer to a state-handler function
Definition: qep.h:247
event handled (internal transition)
Definition: qep.h:506
event silently ignored (bubbled up to top)
Definition: qep.h:507
QSignal sig
signal of the event instance
Definition: qep.h:154
event passed to submachine superstate
Definition: qep.h:502
transition to history of a given state
Definition: qep.h:522
char char_t
typedef for character strings.
Definition: qep.h:70
entry-point transition into a submachine
Definition: qep.h:519
Virtual table for the QHsm class.
Definition: qep.h:285
struct QHsmVtbl const * vptr
virtual pointer
Definition: qep.h:279
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:622
unsigned short uint16_t
exact-width 16-bit unsigned int
Definition: stdint.h:30
event passed to superstate to handle
Definition: qep.h:501
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:503
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:29
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
char_t const QP_versionStr[7]
the current QP version number string in ROM, based on QP_VERSION_STR
Definition: qep_hsm.c:52
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:570
void(* init)(QHsm *const me, QEvt const *const e)
Triggers the top-most initial transition in a HSM.
Definition: qep.h:287
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:36
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:514
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:290
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:619
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:31
QActionHandler act
pointer to an action-handler function
Definition: qep.h:248
char char_t
typedef for character strings.
Definition: qassert.h:77
Definition: qep.h:278
uint_fast8_t QState
typedef of the return type from a state/action-handler function.
Definition: qep.h:206
state entry action executed
Definition: qep.h:510
exit-point transition out of a submachine
Definition: qep.h:523
QState(* QActionHandler)(void *const me)
Pointer to an action-handler function.
Definition: qep.h:212
QStateHandler const stateHandler
state handler function
Definition: qep.h:404
QActionHandler const act[1]
Definition: qep.h:413
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:246
state exit action executed
Definition: qep.h:511
struct QMTranActTable const * tatbl
transition-action table
Definition: qep.h:250
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:249
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:539
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:607
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:621
struct QMState const * superstate
superstate of this state
Definition: qep.h:403
signal for coding exit actions
Definition: qep.h:620
Transition-Action Table for the Meta State Machine.
Definition: qep.h:411
QMState const * target
Definition: qep.h:412
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:562