QP/C  7.0.0
Real-Time Embedded Framework
qf.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============================================================================*/
32#ifndef QF_H
33#define QF_H
34
35#ifndef QPSET_H
36#include "qpset.h"
37#endif
38
39/*==========================================================================*/
40#ifndef QF_EVENT_SIZ_SIZE
42 #define QF_EVENT_SIZ_SIZE 2U
43#endif
44#if (QF_EVENT_SIZ_SIZE == 1U)
45 typedef uint8_t QEvtSize;
46#elif (QF_EVENT_SIZ_SIZE == 2U)
52 typedef uint16_t QEvtSize;
53#elif (QF_EVENT_SIZ_SIZE == 4U)
54 typedef uint32_t QEvtSize;
55#else
56 #error "QF_EVENT_SIZ_SIZE defined incorrectly, expected 1, 2, or 4"
57#endif
58
59#ifndef QF_MAX_EPOOL
61 #define QF_MAX_EPOOL 3U
62#endif
63
64#ifndef QF_MAX_TICK_RATE
68 #define QF_MAX_TICK_RATE 1U
69#elif (QF_MAX_TICK_RATE > 15U)
70 #error "QF_MAX_TICK_RATE exceeds the maximum of 15"
71#endif
72
73#ifndef QF_TIMEEVT_CTR_SIZE
77 #define QF_TIMEEVT_CTR_SIZE 2U
78#endif
79
80/*==========================================================================*/
81struct QEQueue; /* forward declaration */
82
83/*==========================================================================*/
107typedef struct QActive {
110#ifdef QF_EQUEUE_TYPE
122 QF_EQUEUE_TYPE eQueue;
123#endif
124
125#ifdef QF_OS_OBJECT_TYPE
133 QF_OS_OBJECT_TYPE osObject;
134#endif
135
136#ifdef QF_THREAD_TYPE
143 QF_THREAD_TYPE thread;
144#endif
145
146#ifdef QXK_H /* QXK kernel used? */
148 uint8_t dynPrio;
149#endif
150
152 uint8_t prio;
153
154} QActive;
155
157typedef struct {
158 struct QHsmVtable super;
163 void (*start)(QActive * const me, uint_fast8_t prio,
164 QEvt const * * const qSto, uint_fast16_t const qLen,
165 void * const stkSto, uint_fast16_t const stkSize,
166 void const * const par);
167
168#ifdef Q_SPY
173 bool (*post)(QActive * const me, QEvt const * const e,
174 uint_fast16_t const margin, void const * const sender);
175#else
176 bool (*post)(QActive * const me, QEvt const * const e,
177 uint_fast16_t const margin);
178#endif
179
184 void (*postLIFO)(QActive * const me, QEvt const * const e);
185
187
188/* QActive public operations... */
206#define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, par_) do { \
207 Q_ASSERT((Q_HSM_UPCAST(me_))->vptr); \
208 (*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->start)( \
209 (QActive *)(me_), (prio_), \
210 (qSto_), (qLen_), (stkSto_), (stkLen_), (par_)); \
211} while (false)
212
213#ifdef Q_SPY
238 #define QACTIVE_POST(me_, e_, sender_) \
239 ((void)(*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)(\
240 (me_), (e_), QF_NO_MARGIN, (sender_)))
241
275 #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
276 ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)((me_),\
277 (e_), (margin_), (sender_)))
278#else
279
280 #define QACTIVE_POST(me_, e_, sender_) \
281 ((void)(*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)(\
282 (me_), (e_), QF_NO_MARGIN))
283
284 #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
285 ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)( \
286 (me_), (e_), (margin_)))
287
288#endif
289
295#define QACTIVE_POST_LIFO(me_, e_) \
296 ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->postLIFO)( \
297 (me_), (e_)))
298
299/* QActive protected operations... */
303void QActive_ctor(QActive * const me, QStateHandler initial);
304
305#ifdef QF_ACTIVE_STOP
316 void QActive_stop(QActive * const me);
317#endif
318
322void QActive_subscribe(QActive const * const me, enum_t const sig);
323
327void QActive_unsubscribe(QActive const * const me, enum_t const sig);
328
332void QActive_unsubscribeAll(QActive const * const me);
333
337bool QActive_defer(QActive const * const me,
338 QEQueue * const eq, QEvt const * const e);
339
343bool QActive_recall(QActive * const me, QEQueue * const eq);
344
348uint_fast16_t QActive_flushDeferred(QActive const * const me,
349 QEQueue * const eq);
350
354void QActive_setAttr(QActive *const me, uint32_t attr1, void const *attr2);
355
356/*==========================================================================*/
378typedef struct {
380} QMActive;
381
388
389/* QMActive protected operations... */
393void QMActive_ctor(QMActive * const me, QStateHandler initial);
394
395/*==========================================================================*/
396#if (QF_TIMEEVT_CTR_SIZE == 1U)
397 typedef uint8_t QTimeEvtCtr;
398#elif (QF_TIMEEVT_CTR_SIZE == 2U)
399
409 typedef uint16_t QTimeEvtCtr;
410#elif (QF_TIMEEVT_CTR_SIZE == 4U)
411 typedef uint32_t QTimeEvtCtr;
412#else
413 #error "QF_TIMEEVT_CTR_SIZE defined incorrectly, expected 1, 2, or 4"
414#endif
415
456typedef struct QTimeEvt {
460 struct QTimeEvt * volatile next;
461
463 void * volatile act;
464
471 QTimeEvtCtr volatile ctr;
472
481} QTimeEvt;
482
483/* QTimeEvt public operations... */
484
488void QTimeEvt_ctorX(QTimeEvt * const me, QActive * const act,
489 enum_t const sig, uint_fast8_t tickRate);
490
494void QTimeEvt_armX(QTimeEvt * const me,
495 QTimeEvtCtr const nTicks, QTimeEvtCtr const interval);
496
500bool QTimeEvt_rearm(QTimeEvt * const me, QTimeEvtCtr const nTicks);
501
505bool QTimeEvt_disarm(QTimeEvt * const me);
506
510bool QTimeEvt_wasDisarmed(QTimeEvt * const me);
511
515QTimeEvtCtr QTimeEvt_currCtr(QTimeEvt const * const me);
516
517/*==========================================================================*/
518/* QF services. */
524typedef struct {
525 uint8_t dummy;
526} QF;
527
537
538/* public functions */
539
543void QF_init(void);
544
548void QF_psInit(QSubscrList * const subscrSto, enum_t const maxSignal);
549
553void QF_poolInit(void * const poolSto, uint_fast32_t const poolSize,
554 uint_fast16_t const evtSize);
555
559uint_fast16_t QF_poolGetMaxBlockSize(void);
560
564int_t QF_run(void);
565
570void QF_stop(void);
571
579void QF_onStartup(void);
580
595void QF_onCleanup(void);
596
597#ifdef Q_SPY
598
602 void QF_publish_(QEvt const * const e,
603 void const * const sender, uint_fast8_t const qs_id);
604
626 #define QF_PUBLISH(e_, sender_) \
627 (QF_publish_((e_), (void const *)(sender_), (sender_)->prio))
628
629#else
630
631 void QF_publish_(QEvt const * const e);
632 #define QF_PUBLISH(e_, dummy_) (QF_publish_(e_))
633
634#endif
635
636#ifdef Q_SPY
637
641 void QF_tickX_(uint_fast8_t const tickRate, void const * const sender);
642
675 #define QF_TICK_X(tickRate_, sender_) (QF_tickX_((tickRate_), (sender_)))
676
677#else
678
679 void QF_tickX_(uint_fast8_t const tickRate);
680 #define QF_TICK_X(tickRate_, dummy) (QF_tickX_(tickRate_))
681
682#endif
683
687#define QF_NO_MARGIN ((uint_fast16_t)0xFFFFU)
688
692#define QF_TICK(sender_) QF_TICK_X(0U, (sender_))
693
697bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate);
698
702void QF_add_(QActive * const a);
703
707void QF_remove_(QActive * const a);
708
712uint_fast16_t QF_getPoolMin(uint_fast8_t const poolId);
713
718uint_fast16_t QF_getQueueMin(uint_fast8_t const prio);
719
723QEvt *QF_newX_(uint_fast16_t const evtSize,
724 uint_fast16_t const margin, enum_t const sig);
725
729QEvt const *QF_newRef_(QEvt const * const e, void const * const evtRef);
730
734void QF_deleteRef_(void const * const evtRef);
735
736#ifdef Q_EVT_CTOR /* Shall the ctor for the ::QEvt class be provided? */
737
738 #define Q_NEW(evtT_, sig_, ...) \
739 (evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
740 QF_NO_MARGIN, 0), (enum_t)(sig_), ##__VA_ARGS__))
741
742 #define Q_NEW_X(e_, evtT_, margin_, sig_, ...) do { \
743 (e_) = (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
744 (margin_), 0); \
745 if ((e_) != (evtT_ *)0) { \
746 evtT_##_ctor((e_), (enum_t)(sig_), ##__VA_ARGS__); \
747 } \
748 } while (false)
749
750#else
751
773 #define Q_NEW(evtT_, sig_) \
774 ((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
775 QF_NO_MARGIN, (enum_t)(sig_)))
776
803 #define Q_NEW_X(e_, evtT_, margin_, sig_) ((e_) = \
804 (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
805 (margin_), (enum_t)(sig_)))
806
807#endif /* Q_EVT_CTOR */
808
828#define Q_NEW_REF(evtRef_, evtT_) \
829 ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))
830
845#define Q_DELETE_REF(evtRef_) do { \
846 QF_deleteRef_((evtRef_)); \
847 (evtRef_) = (void *)0; \
848} while (false)
849
853void QF_gc(QEvt const * const e);
854
858void QF_bzero(void * const start, uint_fast16_t len);
859
860#ifndef QF_CRIT_EXIT_NOP
871 #define QF_CRIT_EXIT_NOP() ((void)0)
872#endif
873
877extern QActive *QF_active_[QF_MAX_ACTIVE + 1U];
878
879/*==========================================================================*/
894typedef struct {
896} QTicker;
897
901void QTicker_ctor(QTicker * const me, uint_fast8_t tickRate);
902
903#endif /* QF_H */
#define QF_OS_OBJECT_TYPE
Definition: macros.h:60
#define QF_THREAD_TYPE
Definition: macros.h:45
#define QF_EQUEUE_TYPE
Definition: macros.h:48
signed int int_t
Definition: qep.h:57
QState(* QStateHandler)(void *const me, QEvt const *const e)
Definition: qep.h:176
signed int enum_t
Definition: qep.h:60
QActiveVtable QMActiveVtable
Definition: qf.h:387
QPSet QSubscrList
Definition: qf.h:536
uint8_t QTimeEvtCtr
Definition: qf.h:397
uint8_t QEvtSize
Definition: qf.h:45
QP native, platform-independent priority sets of 32 or 64 elements.
Definition: qpset.h:65
#define QF_MAX_ACTIVE
Definition: qf.h:107
void QActive_unsubscribe(QActive const *const me, enum_t const sig)
Definition: qf_ps.c:253
void QActive_ctor(QActive *const me, QStateHandler initial)
Definition: qf_qact.c:58
bool QActive_recall(QActive *const me, QEQueue *const eq)
Definition: qf_defer.c:111
QHsm super
Definition: qf.h:108
void QActive_setAttr(QActive *const me, uint32_t attr1, void const *attr2)
bool QActive_defer(QActive const *const me, QEQueue *const eq, QEvt const *const e)
Definition: qf_defer.c:71
void QActive_stop(QActive *const me)
Definition: qutest.c:215
uint8_t prio
Definition: qf.h:152
uint_fast16_t QActive_flushDeferred(QActive const *const me, QEQueue *const eq)
Definition: qf_defer.c:181
void QActive_subscribe(QActive const *const me, enum_t const sig)
Definition: qf_ps.c:204
void QActive_unsubscribeAll(QActive const *const me)
Definition: qf_ps.c:303
Definition: qep.h:119
QSignal sig
Definition: qep.h:123
Definition: qf.h:524
void QF_onStartup(void)
void QF_poolInit(void *const poolSto, uint_fast32_t const poolSize, uint_fast16_t const evtSize)
Definition: qf_dyn.c:107
void QF_bzero(void *const start, uint_fast16_t len)
Definition: qf_act.c:129
uint_fast16_t QF_getQueueMin(uint_fast8_t const prio)
Definition: qf_actq.c:376
void QF_remove_(QActive *const a)
Definition: qf_act.c:98
void QF_psInit(QSubscrList *const subscrSto, enum_t const maxSignal)
Definition: qf_ps.c:84
void QF_add_(QActive *const a)
Definition: qf_act.c:65
void QF_onCleanup(void)
bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate)
Definition: qf_time.c:202
QActive * QF_active_[QF_MAX_ACTIVE+1U]
Definition: qf_act.c:48
int_t QF_run(void)
Definition: qk.c:124
void QF_publish_(QEvt const *const e, void const *const sender, uint_fast8_t const qs_id)
Definition: qf_ps.c:119
void QF_gc(QEvt const *const e)
Definition: qf_dyn.c:241
uint_fast16_t QF_poolGetMaxBlockSize(void)
Definition: qf_dyn.c:362
void QF_tickX_(uint_fast8_t const tickRate, void const *const sender)
Definition: qf_time.c:86
QEvt * QF_newX_(uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)
Definition: qf_dyn.c:160
void QF_init(void)
Definition: qk.c:64
void QF_stop(void)
Definition: qk.c:98
uint_fast16_t QF_getPoolMin(uint_fast8_t const poolId)
void QF_deleteRef_(void const *const evtRef)
Definition: qf_dyn.c:342
QEvt const * QF_newRef_(QEvt const *const e, void const *const evtRef)
Definition: qf_dyn.c:305
uint8_t dummy
Definition: qf.h:525
Definition: qep.h:253
Definition: qf.h:378
void QMActive_ctor(QMActive *const me, QStateHandler initial)
Definition: qf_qmact.c:66
QActive super
Definition: qf.h:379
Definition: qf.h:894
QActive super
Definition: qf.h:895
void QTicker_ctor(QTicker *const me, uint_fast8_t tickRate)
Definition: qf_actq.c:419
Definition: qf.h:456
struct QTimeEvt *volatile next
Definition: qf.h:460
void *volatile act
Definition: qf.h:463
QTimeEvtCtr volatile ctr
Definition: qf.h:471
bool QTimeEvt_rearm(QTimeEvt *const me, QTimeEvtCtr const nTicks)
Definition: qf_time.c:444
QTimeEvtCtr interval
Definition: qf.h:480
QTimeEvtCtr QTimeEvt_currCtr(QTimeEvt const *const me)
Definition: qf_time.c:553
void QTimeEvt_ctorX(QTimeEvt *const me, QActive *const act, enum_t const sig, uint_fast8_t tickRate)
Definition: qf_time.c:239
bool QTimeEvt_wasDisarmed(QTimeEvt *const me)
Definition: qf_time.c:530
void QTimeEvt_armX(QTimeEvt *const me, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
Definition: qf_time.c:301
bool QTimeEvt_disarm(QTimeEvt *const me)
Definition: qf_time.c:380
QEvt super
Definition: qf.h:457