QP/C  7.0.0
Real-Time Embedded Framework
qep.h
Go to the documentation of this file.
1/*============================================================================
2* QP/C Real-Time Embedded Framework (RTEF)
3* Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
4*
5* SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
6*
7* This software is dual-licensed under the terms of the open source GNU
8* General Public License version 3 (or any later version), or alternatively,
9* under the terms of one of the closed source Quantum Leaps commercial
10* licenses.
11*
12* The terms of the open source GNU General Public License version 3
13* can be found at: <www.gnu.org/licenses/gpl-3.0>
14*
15* The terms of the closed source Quantum Leaps commercial licenses
16* can be found at: <www.state-machine.com/licensing>
17*
18* Redistributions in source code must retain this top-level comment block.
19* Plagiarizing this software to sidestep the license obligations is illegal.
20*
21* Contact information:
22* <www.state-machine.com>
23* <info@state-machine.com>
24============================================================================*/
34#ifndef QEP_H
35#define QEP_H
36
37/*==========================================================================*/
42#define QP_VERSION 700U
43
48#define QP_VERSION_STR "7.0.0"
49
51#define QP_RELEASE 0x7CCAAA13U
52
53/*==========================================================================*/
54/* typedefs for basic numerical types; MISRA-C 2012 Dir 4.6(A). */
55
57typedef signed int int_t;
58
60typedef signed int enum_t;
61
68typedef float float32_t;
69
76typedef double float64_t;
77
79extern char const QP_versionStr[7];
80
81/*==========================================================================*/
82#ifndef Q_SIGNAL_SIZE
83 #define Q_SIGNAL_SIZE 2U
84#endif
85#if (Q_SIGNAL_SIZE == 1U)
86 typedef uint8_t QSignal;
87#elif (Q_SIGNAL_SIZE == 2U)
97 typedef uint16_t QSignal;
98#elif (Q_SIGNAL_SIZE == 4U)
99 typedef uint32_t QSignal;
100#else
101 #error "Q_SIGNAL_SIZE defined incorrectly, expected 1U, 2U, or 4U"
102#endif
103
104/*==========================================================================*/
119typedef struct {
124
128 uint8_t poolId_;
129
133 uint8_t volatile refCtr_;
134} QEvt;
135
136#ifdef Q_EVT_CTOR /* Shall the constructor for the ::QEvt class be provided? */
137
142QEvt *QEvt_ctor(QEvt * const me, enum_t const sig);
143
144#endif
145
146/*==========================================================================*/
158#define Q_EVT_CAST(class_) ((class_ const *)e)
159
166#define Q_UINT2PTR_CAST(type_, uintptr_) ((type_ *)(uintptr_))
167
168/*==========================================================================*/
170typedef uint_fast8_t QState;
171
172/* forward declaration */
173typedef struct QXThread QXThread;
174
176typedef QState (*QStateHandler)(void * const me, QEvt const * const e);
177
179typedef QState (*QActionHandler)(void * const me);
180
182typedef void (*QXThreadHandler)(QXThread * const me);
183
196#define Q_STATE_CAST(handler_) ((QStateHandler)(handler_))
197
207#define Q_ACTION_CAST(action_) ((QActionHandler)(action_))
208
209/* forward declarations... */
210struct QMState;
211struct QHsmVtable;
212typedef struct QMTranActTable QMTranActTable;
213
219union QHsmAttr {
223 struct QMState const *obj;
225};
226
227/*==========================================================================*/
253typedef struct {
254 struct QHsmVtable const *vptr;
255 union QHsmAttr state;
256 union QHsmAttr temp;
257} QHsm;
258
262#ifdef Q_SPY
264 void (*init)(QHsm * const me, void const * const e,
265 uint_fast8_t const qs_id);
266
268 void (*dispatch)(QHsm * const me, QEvt const * const e,
269 uint_fast8_t const qs_id);
270
273#else
274 void (*init)(QHsm * const me, void const * const e);
275 void (*dispatch)(QHsm * const me, QEvt const * const e);
276#endif /* Q_SPY */
277};
278
279/* QHsm public operations... */
280#ifdef Q_SPY
296 #define QHSM_INIT(me_, par_, qs_id_) do { \
297 Q_ASSERT((me_)->vptr); \
298 (*(me_)->vptr->init)((me_), (par_), (qs_id_)); \
299 } while (false)
300
304 void QHsm_init_(QHsm * const me, void const * const e,
305 uint_fast8_t const qs_id);
306#else
307
308 #define QHSM_INIT(me_, par_, dummy) do { \
309 Q_ASSERT((me_)->vptr); \
310 (*(me_)->vptr->init)((me_), (par_)); \
311 } while (false)
312
314 void QHsm_init_(QHsm * const me, void const * const e);
315
316#endif /* Q_SPY */
317
318#ifdef Q_SPY
330 #define QHSM_DISPATCH(me_, e_, qs_id_) \
331 ((*(me_)->vptr->dispatch)((me_), (e_), (qs_id_)))
332
336 void QHsm_dispatch_(QHsm * const me, QEvt const * const e,
337 uint_fast8_t const qs_id);
338
343#else
344
345 #define QHSM_DISPATCH(me_, e_, dummy) \
346 ((*(me_)->vptr->dispatch)((me_), (e_)))
347
348 void QHsm_dispatch_(QHsm * const me, QEvt const * const e);
349
350#endif /* Q_SPY */
351
365#define Q_HSM_UPCAST(ptr_) ((QHsm *)(ptr_))
366
373static inline QStateHandler QHsm_state(QHsm * const me) {
374 return Q_STATE_CAST(me->state.fun);
375}
376
385 QStateHandler const parent);
386
391bool QHsm_isIn(QHsm * const me, QStateHandler const state);
392
393/* QHsm protected operations... */
397void QHsm_ctor(QHsm * const me, QStateHandler initial);
398
402QState QHsm_top(void const * const me, QEvt const * const e);
403
404/*==========================================================================*/
425typedef struct {
427} QMsm;
428
442struct QMState {
443 struct QMState const *superstate;
448};
449typedef struct QMState QMState;
450
453 struct QMState const *target;
455};
456
457/* QMsm public operations... */
464static inline QMState const *QMsm_stateObj(QHsm * const me) {
465 return me->state.obj;
466}
467
475QMState const *QMsm_childStateObj(QHsm const * const me,
476 QMState const * const parent);
477
482bool QMsm_isInState(QMsm const * const me, QMState const * const state);
483
484/* QMsm protected operations... */
488void QMsm_ctor(QMsm * const me, QStateHandler initial);
489
490/* QMsm private operations... */
494#ifdef Q_SPY
495void QMsm_init_(QHsm * const me, void const * const e,
496 uint_fast8_t const qs_id);
497#else
498void QMsm_init_(QHsm * const me, void const * const e);
499#endif
500
504#ifdef Q_SPY
505void QMsm_dispatch_(QHsm * const me, QEvt const * const e,
506 uint_fast8_t const qs_id);
507#else
508void QMsm_dispatch_(QHsm * const me, QEvt const * const e);
509#endif
510
514#ifdef Q_SPY
516#endif
517
526#define Q_TRAN(target_) \
527 ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(target_), (QState)Q_RET_TRAN)
528
537#define Q_TRAN_HIST(hist_) \
538 ((Q_HSM_UPCAST(me))->temp.fun = (hist_), (QState)Q_RET_TRAN_HIST)
539
548#define Q_SUPER(super_) \
549 ((Q_HSM_UPCAST(me))->temp.fun = Q_STATE_CAST(super_), (QState)Q_RET_SUPER)
550
554#define Q_HANDLED() ((QState)Q_RET_HANDLED)
555
560#define Q_UNHANDLED() ((QState)Q_RET_UNHANDLED)
561
565#define Q_ACTION_NULL ((QActionHandler)0)
566
567/*==========================================================================*/
571enum {
572 /* unhandled and need to "bubble up" */
577 /* handled and do not need to "bubble up" */
581 /* entry/exit */
585 /* no side effects */
588 /* transitions need to execute transition-action table in ::QMsm */
593 /* transitions that additionally clobber me->state */
597
598#ifdef Q_SPY
602 #define QM_ENTRY(state_) \
603 ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_ENTRY)
604
608 #define QM_EXIT(state_) \
609 ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
610
611#else
612 #define QM_ENTRY(dummy) ((QState)Q_RET_ENTRY)
613
614 #define QM_EXIT(dummy) ((QState)Q_RET_EXIT)
615
616#endif /* Q_SPY */
617
621#define QM_SM_EXIT(state_) \
622 ((Q_HSM_UPCAST(me))->temp.obj = (state_), (QState)Q_RET_EXIT)
623
627#define QM_TRAN(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
628 = (QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN)
629
633#define QM_TRAN_INIT(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
634 = (QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN_INIT)
635
639#define QM_TRAN_HIST(history_, tatbl_) \
640 ((((Q_HSM_UPCAST(me))->state.obj = (history_)), \
641 ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))), \
642 (QState)Q_RET_TRAN_HIST)
643
647#define QM_TRAN_EP(tatbl_) ((Q_HSM_UPCAST(me))->temp.tatbl \
648 = (QMTranActTable const *)(tatbl_), (QState)Q_RET_TRAN_EP)
649
653#define QM_TRAN_XP(xp_, tatbl_) \
654 ((((Q_HSM_UPCAST(me))->state.act = (xp_)), \
655 ((Q_HSM_UPCAST(me))->temp.tatbl = (QMTranActTable const *)(tatbl_))), \
656 (QState)Q_RET_TRAN_XP)
657
661#define QM_HANDLED() ((QState)Q_RET_HANDLED)
662
668#define QM_UNHANDLED() ((QState)Q_RET_UNHANDLED)
669
673#define QM_SUPER() ((QState)Q_RET_SUPER)
674
678#define QM_SUPER_SUB(host_) \
679 ((Q_HSM_UPCAST(me))->temp.obj = (host_), (QState)Q_RET_SUPER_SUB)
680
684#define QM_STATE_NULL ((QMState *)0)
685
687enum {
693
694#endif /* QEP_H */
signed int int_t
Definition: qep.h:57
@ Q_RET_ENTRY
Definition: qep.h:582
@ Q_RET_HANDLED
Definition: qep.h:578
@ Q_RET_TRAN_XP
Definition: qep.h:595
@ Q_RET_IGNORED
Definition: qep.h:579
@ Q_RET_TRAN_INIT
Definition: qep.h:590
@ Q_RET_TRAN
Definition: qep.h:589
@ Q_RET_UNHANDLED
Definition: qep.h:575
@ Q_RET_SUPER
Definition: qep.h:573
@ Q_RET_NULL
Definition: qep.h:586
@ Q_RET_TRAN_HIST
Definition: qep.h:594
@ Q_RET_SUPER_SUB
Definition: qep.h:574
@ Q_RET_TRAN_EP
Definition: qep.h:591
@ Q_RET_EXIT
Definition: qep.h:583
float float32_t
Definition: qep.h:68
#define Q_STATE_CAST(handler_)
Definition: qep.h:196
QState(* QStateHandler)(void *const me, QEvt const *const e)
Definition: qep.h:176
double float64_t
Definition: qep.h:76
uint_fast8_t QState
Definition: qep.h:170
void(* QXThreadHandler)(QXThread *const me)
Definition: qep.h:182
char const QP_versionStr[7]
Definition: qep_hsm.c:47
@ Q_INIT_SIG
Definition: qep.h:690
@ Q_USER_SIG
Definition: qep.h:691
@ Q_EXIT_SIG
Definition: qep.h:689
@ Q_ENTRY_SIG
Definition: qep.h:688
QState(* QActionHandler)(void *const me)
Definition: qep.h:179
uint16_t QSignal
Definition: qep.h:97
signed int enum_t
Definition: qep.h:60
Definition: qep.h:119
QSignal sig
Definition: qep.h:123
uint8_t poolId_
Definition: qep.h:128
uint8_t volatile refCtr_
Definition: qep.h:133
Definition: qep.h:253
bool QHsm_isIn(QHsm *const me, QStateHandler const state)
Definition: qep_hsm.c:628
struct QHsmVtable const * vptr
Definition: qep.h:254
void QHsm_ctor(QHsm *const me, QStateHandler initial)
Definition: qep_hsm.c:139
static QStateHandler QHsm_state(QHsm *const me)
Definition: qep.h:373
union QHsmAttr state
Definition: qep.h:255
void QHsm_init_(QHsm *const me, void const *const e, uint_fast8_t const qs_id)
Definition: qep_hsm.c:167
QState QHsm_top(void const *const me, QEvt const *const e)
Definition: qep_hsm.c:261
QStateHandler QHsm_getStateHandler_(QHsm *const me)
Definition: qep_hsm.c:605
void QHsm_dispatch_(QHsm *const me, QEvt const *const e, uint_fast8_t const qs_id)
Definition: qep_hsm.c:286
QStateHandler QHsm_childState(QHsm *const me, QStateHandler const parent)
Definition: qep_hsm.c:677
void(* init)(QHsm *const me, void const *const e, uint_fast8_t const qs_id)
Definition: qep.h:264
void(* dispatch)(QHsm *const me, QEvt const *const e, uint_fast8_t const qs_id)
Definition: qep.h:268
QStateHandler(* getStateHandler)(QHsm *const me)
Definition: qep.h:272
Definition: qep.h:442
struct QMState const * superstate
Definition: qep.h:443
QActionHandler const entryAction
Definition: qep.h:445
QActionHandler const initAction
Definition: qep.h:447
QActionHandler const exitAction
Definition: qep.h:446
QStateHandler const stateHandler
Definition: qep.h:444
QActionHandler const act[1]
Definition: qep.h:454
struct QMState const * target
Definition: qep.h:453
Definition: qep.h:425
static QMState const * QMsm_stateObj(QHsm *const me)
Definition: qep.h:464
QHsm super
Definition: qep.h:426
QStateHandler QMsm_getStateHandler_(QHsm *const me)
Definition: qep_msm.c:397
void QMsm_init_(QHsm *const me, void const *const e, uint_fast8_t const qs_id)
Definition: qep_msm.c:142
void QMsm_dispatch_(QHsm *const me, QEvt const *const e, uint_fast8_t const qs_id)
Definition: qep_msm.c:206
QMState const * QMsm_childStateObj(QHsm const *const me, QMState const *const parent)
Definition: qep_msm.c:657
bool QMsm_isInState(QMsm const *const me, QMState const *const state)
Definition: qep_msm.c:623
void QMsm_ctor(QMsm *const me, QStateHandler initial)
Definition: qep_msm.c:114
Definition: qep.h:219
QMTranActTable const * tatbl
Definition: qep.h:224
QXThreadHandler thr
Definition: qep.h:222
QStateHandler fun
Definition: qep.h:220
struct QMState const * obj
Definition: qep.h:223
QActionHandler act
Definition: qep.h:221