QP/C 6.8.1
qf.h
Go to the documentation of this file.
1 
40 #ifndef QF_H
41 #define QF_H
42 
43 #ifndef QPSET_H
44 #include "qpset.h"
45 #endif
46 
47 /****************************************************************************/
48 #ifndef QF_EVENT_SIZ_SIZE
49 
50  #define QF_EVENT_SIZ_SIZE 2U
51 #endif
52 #if (QF_EVENT_SIZ_SIZE == 1U)
53  typedef uint8_t QEvtSize;
54 #elif (QF_EVENT_SIZ_SIZE == 2U)
55 
61  typedef uint16_t QEvtSize;
62 #elif (QF_EVENT_SIZ_SIZE == 4U)
63  typedef uint32_t QEvtSize;
64 #else
65  #error "QF_EVENT_SIZ_SIZE defined incorrectly, expected 1, 2, or 4"
66 #endif
67 
68 #ifndef QF_MAX_EPOOL
69 
70  #define QF_MAX_EPOOL 3U
71 #endif
72 
73 #ifndef QF_MAX_TICK_RATE
74 
77  #define QF_MAX_TICK_RATE 1U
78 #elif (QF_MAX_TICK_RATE > 15U)
79  #error "QF_MAX_TICK_RATE exceeds the maximum of 15"
80 #endif
81 
82 #ifndef QF_TIMEEVT_CTR_SIZE
83 
86  #define QF_TIMEEVT_CTR_SIZE 2
87 #endif
88 
89 /****************************************************************************/
90 struct QEQueue; /* forward declaration */
91 
92 /****************************************************************************/
116 typedef struct QActive {
117  QHsm super;
119 #ifdef QF_EQUEUE_TYPE
120 
132  QF_EQUEUE_TYPE eQueue;
133 #endif
134 
135 #ifdef QF_OS_OBJECT_TYPE
136 
144  QF_OS_OBJECT_TYPE osObject;
145 #endif
146 
147 #ifdef QF_THREAD_TYPE
148 
155  QF_THREAD_TYPE thread;
156 #endif
157 
159  uint8_t prio;
160 
161 #ifdef QXK_H /* QXK kernel used? */
162 
163  uint8_t startPrio;
164 #endif
165 
166 } QActive;
167 
169 typedef struct {
170  struct QHsmVtable super;
174  void (*start)(QActive * const me, uint_fast8_t prio,
175  QEvt const * * const qSto, uint_fast16_t const qLen,
176  void * const stkSto, uint_fast16_t const stkSize,
177  void const * const par);
178 
179 #ifdef Q_SPY
180 
182  bool (*post)(QActive * const me, QEvt const * const e,
183  uint_fast16_t const margin, void const * const sender);
184 #else
185  bool (*post)(QActive * const me, QEvt const * const e,
186  uint_fast16_t const margin);
187 #endif
188 
191  void (*postLIFO)(QActive * const me, QEvt const * const e);
192 
193 } QActiveVtable;
194 
195 /* QActive public operations... */
216 #define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, par_) do { \
217  Q_ASSERT((Q_HSM_UPCAST(me_))->vptr); \
218  (*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->start)( \
219  (QActive *)(me_), (prio_), \
220  (qSto_), (qLen_), (stkSto_), (stkLen_), (par_)); \
221 } while (false)
222 
223 #ifdef Q_SPY
224 
251  #define QACTIVE_POST(me_, e_, sender_) \
252  ((void)(*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)(\
253  (me_), (e_), QF_NO_MARGIN, (sender_)))
254 
291  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
292  ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)((me_),\
293  (e_), (margin_), (sender_)))
294 #else
295 
296  #define QACTIVE_POST(me_, e_, sender_) \
297  ((void)(*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)(\
298  (me_), (e_), QF_NO_MARGIN))
299 
300  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
301  ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->post)( \
302  (me_), (e_), (margin_)))
303 
304 #endif
305 
314 #define QACTIVE_POST_LIFO(me_, e_) \
315  ((*((QActiveVtable const *)((Q_HSM_UPCAST(me_))->vptr))->postLIFO)( \
316  (me_), (e_)))
317 
318 /* QActive protected operations... */
322 void QActive_ctor(QActive * const me, QStateHandler initial);
323 
324 #ifdef QF_ACTIVE_STOP
325 
335  void QActive_stop(QActive * const me);
336 #endif
337 
341 void QActive_subscribe(QActive const * const me, enum_t const sig);
342 
346 void QActive_unsubscribe(QActive const * const me, enum_t const sig);
347 
351 void QActive_unsubscribeAll(QActive const * const me);
352 
356 bool QActive_defer(QActive const * const me,
357  QEQueue * const eq, QEvt const * const e);
358 
362 bool QActive_recall(QActive * const me, QEQueue * const eq);
363 
367 uint_fast16_t QActive_flushDeferred(QActive const * const me,
368  QEQueue * const eq);
369 
373 void QActive_setAttr(QActive *const me, uint32_t attr1, void const *attr2);
374 
375 
376 /****************************************************************************/
400 typedef struct {
401  QActive super;
402 } QMActive;
403 
410 typedef QActiveVtable QMActiveVtable;
411 
412 /* QMActive protected operations... */
416 void QMActive_ctor(QMActive * const me, QStateHandler initial);
417 
418 
419 /****************************************************************************/
420 #if (QF_TIMEEVT_CTR_SIZE == 1U)
421  typedef uint8_t QTimeEvtCtr;
422 #elif (QF_TIMEEVT_CTR_SIZE == 2U)
423 
434  typedef uint16_t QTimeEvtCtr;
435 #elif (QF_TIMEEVT_CTR_SIZE == 4U)
436  typedef uint32_t QTimeEvtCtr;
437 #else
438  #error "QF_TIMEEVT_CTR_SIZE defined incorrectly, expected 1, 2, or 4"
439 #endif
440 
480 typedef struct QTimeEvt {
481  QEvt super; /*<! inherits ::QEvt */
482 
484  struct QTimeEvt * volatile next;
485 
487  void * volatile act;
488 
496  QTimeEvtCtr volatile ctr;
497 
505  QTimeEvtCtr interval;
506 } QTimeEvt;
507 
508 /* QTimeEvt public operations... */
509 
513 void QTimeEvt_ctorX(QTimeEvt * const me, QActive * const act,
514  enum_t const sig, uint_fast8_t tickRate);
515 
519 void QTimeEvt_armX(QTimeEvt * const me,
520  QTimeEvtCtr const nTicks, QTimeEvtCtr const interval);
521 
525 bool QTimeEvt_rearm(QTimeEvt * const me, QTimeEvtCtr const nTicks);
526 
530 bool QTimeEvt_disarm(QTimeEvt * const me);
531 
535 bool QTimeEvt_wasDisarmed(QTimeEvt * const me);
536 
540 QTimeEvtCtr QTimeEvt_currCtr(QTimeEvt const * const me);
541 
542 
543 /****************************************************************************/
544 /* QF facilities */
545 
555 typedef QPSet QSubscrList;
556 
557 /* public functions */
558 
560 void QF_init(void);
561 
563 void QF_psInit(QSubscrList * const subscrSto, enum_t const maxSignal);
564 
566 void QF_poolInit(void * const poolSto, uint_fast32_t const poolSize,
567  uint_fast16_t const evtSize);
568 
570 uint_fast16_t QF_poolGetMaxBlockSize(void);
571 
573 int_t QF_run(void);
574 
577 void QF_stop(void);
578 
586 void QF_onStartup(void);
587 
602 void QF_onCleanup(void);
603 
604 #ifdef Q_SPY
605 
607  void QF_publish_(QEvt const * const e, void const * const sender);
608 
632  #define QF_PUBLISH(e_, sender_) \
633  (QF_publish_((e_), (void const *)(sender_)))
634 #else
635 
636  void QF_publish_(QEvt const * const e);
637  #define QF_PUBLISH(e_, dummy_) (QF_publish_(e_))
638 
639 #endif
640 
641 #ifdef Q_SPY
642 
644  void QF_tickX_(uint_fast8_t const tickRate, void const * const sender);
645 
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 
690 #define QF_TICK(sender_) QF_TICK_X(0U, (sender_))
691 
693 bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate);
694 
696 void QF_add_(QActive * const a);
697 
699 void QF_remove_(QActive * const a);
700 
702 uint_fast16_t QF_getPoolMin(uint_fast8_t const poolId);
703 
706 uint_fast16_t QF_getQueueMin(uint_fast8_t const prio);
707 
709 QEvt *QF_newX_(uint_fast16_t const evtSize,
710  uint_fast16_t const margin, enum_t const sig);
711 
713 QEvt const *QF_newRef_(QEvt const * const e, void const * const evtRef);
714 
716 void QF_deleteRef_(void const * const evtRef);
717 
718 #ifdef Q_EVT_CTOR /* Shall the ctor for the ::QEvt class be provided? */
719 
720  #define Q_NEW(evtT_, sig_, ...) \
721  (evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
722  QF_NO_MARGIN, 0), (sig_), ##__VA_ARGS__))
723 
724  #define Q_NEW_X(e_, evtT_, margin_, sig_, ...) do { \
725  (e_) = (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
726  (margin_), 0); \
727  if ((e_) != (evtT_ *)0) { \
728  evtT_##_ctor((e_), (sig_), ##__VA_ARGS__); \
729  } \
730  } while (false)
731 
732 #else
733 
756  #define Q_NEW(evtT_, sig_) \
757  ((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
758  QF_NO_MARGIN, (sig_)))
759 
786  #define Q_NEW_X(e_, evtT_, margin_, sig_) ((e_) = \
787  (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), (margin_), (sig_)))
788 
789 #endif /* Q_EVT_CTOR */
790 
811 #define Q_NEW_REF(evtRef_, evtT_) \
812  ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))
813 
829 #define Q_DELETE_REF(evtRef_) do { \
830  QF_deleteRef_((evtRef_)); \
831  (evtRef_) = (void *)0; \
832 } while (false)
833 
835 void QF_gc(QEvt const * const e);
836 
838 void QF_bzero(void * const start, uint_fast16_t len);
839 
840 #ifndef QF_CRIT_EXIT_NOP
841 
852  #define QF_CRIT_EXIT_NOP() ((void)0)
853 #endif
854 
859 extern QActive *QF_active_[QF_MAX_ACTIVE + 1U];
860 
861 
862 /****************************************************************************/
873 typedef QActive QTicker;
874 
876 void QTicker_ctor(QTicker * const me, uint8_t tickRate);
877 
878 #endif /* QF_H */
879 
QTimeEvt::QTimeEvt_armX
void QTimeEvt_armX(QTimeEvt *const me, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
Arm a time event (one shot or periodic) for direct event posting.
Definition: qf_time.c:298
QF_bzero
void QF_bzero(void *const start, uint_fast16_t len)
Clear a specified region of memory to zero.
Definition: qf_act.c:144
QMActive::QMActive_ctor
void QMActive_ctor(QMActive *const me, QStateHandler initial)
protected "constructor" of an QMActive active object.
Definition: qf_qmact.c:67
QActive::prio
uint8_t prio
QF priority (1..QF_MAX_ACTIVE) of this active object.
Definition: qf.h:159
QTimeEvt::QTimeEvt_disarm
bool QTimeEvt_disarm(QTimeEvt *const me)
Disarm a time event.
Definition: qf_time.c:372
QF_onStartup
void QF_onStartup(void)
Startup QF callback.
uint8_t
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: 16bit/stdint.h:29
QTimeEvt
Time Event class.
Definition: qf.h:480
QF_poolInit
void QF_poolInit(void *const poolSto, uint_fast32_t const poolSize, uint_fast16_t const evtSize)
Event pool initialization for dynamic allocation of events.
Definition: qf_dyn.c:113
QEvt::sig
QSignal sig
signal of the event instance
Definition: qep.h:152
QStateHandler
QState(* QStateHandler)(void *const me, QEvt const *const e)
Pointer to a state-handler function.
Definition: qep.h:210
QTimeEvt::interval
QTimeEvtCtr interval
the interval for periodic time event (zero for one-shot time event)
Definition: qf.h:505
QTimeEvt::ctr
QTimeEvtCtr volatile ctr
the internal down-counter of the time event.
Definition: qf.h:496
QActiveVtable
Virtual table for the QActive class.
Definition: qf.h:169
QF_poolGetMaxBlockSize
uint_fast16_t QF_poolGetMaxBlockSize(void)
Obtain the block size of any registered event pools.
Definition: qf_dyn.c:338
QF_tickX_
void QF_tickX_(uint_fast8_t const tickRate, void const *const sender)
Processes all armed time events at every clock tick.
Definition: qf_time.c:79
QF_deleteRef_
void QF_deleteRef_(void const *const evtRef)
Internal QF implementation of deleting event reference.
Definition: qf_dyn.c:320
QActive::QActive_unsubscribe
void QActive_unsubscribe(QActive const *const me, enum_t const sig)
Un-subscribes from the delivery of signal sig to the AO me.
Definition: qf_ps.c:255
QActive::QActive_flushDeferred
uint_fast16_t QActive_flushDeferred(QActive const *const me, QEQueue *const eq)
Flush the specified deferred queue eq.
Definition: qf_defer.c:190
QTimeEvt::QTimeEvt_currCtr
QTimeEvtCtr QTimeEvt_currCtr(QTimeEvt const *const me)
Get the current value of the down-counter of a time event.
Definition: qf_time.c:535
QMActive::super
QActive super
inherits QActive
Definition: qf.h:401
QF_run
int_t QF_run(void)
Transfers control to QF to run the application.
Definition: qk.c:133
QF_onCleanup
void QF_onCleanup(void)
Cleanup QF callback.
QActive::QActive_ctor
void QActive_ctor(QActive *const me, QStateHandler initial)
protected "constructor" of an QActive active object
Definition: qf_qact.c:66
uint16_t
unsigned int uint16_t
exact-width 16-bit unsigned int
Definition: 16bit/stdint.h:30
QEQueue
Native QF Event Queue.
Definition: qequeue.h:130
QActive
Active Object base class (based on QHsm implementation)
Definition: qf.h:116
QTicker_ctor
void QTicker_ctor(QTicker *const me, uint8_t tickRate)
Constructor of the QTicker Active Object class.
Definition: qf_actq.c:439
QF_psInit
void QF_psInit(QSubscrList *const subscrSto, enum_t const maxSignal)
Publish-subscribe initialization.
Definition: qf_ps.c:87
QF_gc
void QF_gc(QEvt const *const e)
Recycle a dynamic event.
Definition: qf_dyn.c:230
uint_fast8_t
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: 16bit/stdint.h:36
QF_init
void QF_init(void)
QF initialization.
Definition: qk.c:72
QF_getQueueMin
uint_fast16_t QF_getQueueMin(uint_fast8_t const prio)
This function returns the minimum of free entries of the given event queue.
Definition: qf_actq.c:398
QTimeEvt::super
QEvt super
Definition: qf.h:481
QActive::QActive_recall
bool QActive_recall(QActive *const me, QEQueue *const eq)
Recall a deferred event from a given event queue eq.
Definition: qf_defer.c:119
bool
_Bool bool
standard Boolean data type
Definition: stdbool.h:19
QF_newX_
QEvt * QF_newX_(uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)
Internal QF implementation of creating new dynamic event.
Definition: qf_dyn.c:164
QActive::super
QHsm super
inherits QHsm
Definition: qf.h:117
QEvt
Event class.
Definition: qep.h:151
QTimeEvtCtr
uint8_t QTimeEvtCtr
Definition: qf.h:421
QMActive
QMActive active object base class (based on QMsm implementation)
Definition: qf.h:400
QF_noTimeEvtsActiveX
bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate)
Returns 'true' if there are no armed time events at a given tick rate.
Definition: qf_time.c:206
QF_stop
void QF_stop(void)
Function invoked by the application layer to stop the QF application and return control to the OS/Ker...
Definition: qk.c:107
QHsm
Hierarchical State Machine class.
Definition: qep.h:282
qpset.h
QP native, platform-independent priority sets of 32 or 64 elements.
QActive::QActive_defer
bool QActive_defer(QActive const *const me, QEQueue *const eq, QEvt const *const e)
Defer an event e to a given event queue eq.
Definition: qf_defer.c:78
QF_publish_
void QF_publish_(QEvt const *const e, void const *const sender)
Publish event to the framework.
Definition: qf_ps.c:121
QTimeEvt::next
struct QTimeEvt *volatile next
link to the next time event in the list
Definition: qf.h:484
QF_active_
QActive * QF_active_[QF_MAX_ACTIVE+1U]
array of registered active objects
Definition: qf_act.c:54
QActive::QActive_subscribe
void QActive_subscribe(QActive const *const me, enum_t const sig)
Subscribes for delivery of signal sig to the active object me.
Definition: qf_ps.c:206
QHsmVtable
Virtual table for the QHsm class.
Definition: qep.h:289
QF_OS_OBJECT_TYPE
#define QF_OS_OBJECT_TYPE
This macro defines the type of the OS-Object used for blocking the native QF event queue when the que...
Definition: macros.h:49
QActive::QActive_unsubscribeAll
void QActive_unsubscribeAll(QActive const *const me)
Un-subscribes from the delivery of all signals to the AO me.
Definition: qf_ps.c:304
QTimeEvt::QTimeEvt_wasDisarmed
bool QTimeEvt_wasDisarmed(QTimeEvt *const me)
Check the "was disarmed" status of a time event.
Definition: qf_time.c:513
QTicker
QActive QTicker
QTicker Active Object class.
Definition: qf.h:873
QF_newRef_
QEvt const * QF_newRef_(QEvt const *const e, void const *const evtRef)
Internal QF implementation of creating new event reference.
Definition: qf_dyn.c:286
uint_fast32_t
unsigned long uint_fast32_t
fast at-least 32-bit unsigned int
Definition: 16bit/stdint.h:40
enum_t
int enum_t
typedef for enumerations used for event signals
Definition: qep.h:79
int_t
int int_t
typedef for assertions-ids and line numbers in assertions.
Definition: qassert.h:86
QTimeEvt::QTimeEvt_rearm
bool QTimeEvt_rearm(QTimeEvt *const me, QTimeEvtCtr const nTicks)
Rearm a time event.
Definition: qf_time.c:433
QPSet
Priority Set of up to 32 elements.
Definition: qpset.h:68
QTimeEvt::act
void *volatile act
the active object that receives the time events
Definition: qf.h:487
QF_MAX_ACTIVE
#define QF_MAX_ACTIVE
The maximum number of active objects in the application.
Definition: qk/qf_port.h:58
QF_THREAD_TYPE
#define QF_THREAD_TYPE
This macro defines the type of the thread handle used for the active objects.
Definition: macros.h:53
QF_EQUEUE_TYPE
#define QF_EQUEUE_TYPE
Kernel-dependent type of the event queue used for QK threads.
Definition: qk.h:56
QF_add_
void QF_add_(QActive *const a)
Register an active object to be managed by the framework.
Definition: qf_act.c:70
QEvtSize
uint8_t QEvtSize
Definition: qf.h:53
QSubscrList
QPSet QSubscrList
Subscriber-List structure.
Definition: qf.h:555
QTimeEvt::QTimeEvt_ctorX
void QTimeEvt_ctorX(QTimeEvt *const me, QActive *const act, enum_t const sig, uint_fast8_t tickRate)
The extended "constructor" to initialize a Time Event.
Definition: qf_time.c:239
QActive::QActive_setAttr
void QActive_setAttr(QActive *const me, uint32_t attr1, void const *attr2)
Generic setting of additional attributes (useful in QP ports)
uint32_t
unsigned long int uint32_t
exact-width 32-bit unsigned int
Definition: 16bit/stdint.h:31
uint_fast16_t
unsigned int uint_fast16_t
fast at-least 16-bit unsigned int
Definition: 16bit/stdint.h:38
QMActiveVtable
QActiveVtable QMActiveVtable
Virtual Table for the QMActive class (inherited from QActiveVtable.
Definition: qf.h:410
QF_remove_
void QF_remove_(QActive *const a)
Remove the active object from the framework.
Definition: qf_act.c:103
QF_getPoolMin
uint_fast16_t QF_getPoolMin(uint_fast8_t const poolId)
Obtain the minimum of free entries of the given event pool.
Definition: qf_mem.c:290