QP/C  5.9.5
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 2
51 #endif
52 #if (QF_EVENT_SIZ_SIZE == 1)
53  typedef uint8_t QEvtSize;
54 #elif (QF_EVENT_SIZ_SIZE == 2)
55 
61  typedef uint16_t QEvtSize;
62 #elif (QF_EVENT_SIZ_SIZE == 4)
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 3
71 #endif
72 
73 #ifndef QF_MAX_TICK_RATE
74 
75  #define QF_MAX_TICK_RATE 1
76 #endif
77 
78 #ifndef QF_TIMEEVT_CTR_SIZE
79 
82  #define QF_TIMEEVT_CTR_SIZE 2
83 #endif
84 
85 /****************************************************************************/
86 struct QEQueue; /* forward declaration */
87 
88 /****************************************************************************/
110 typedef struct QActive {
113 #ifdef QF_EQUEUE_TYPE
114 
125  QF_EQUEUE_TYPE eQueue;
126 #endif
127 
128 #ifdef QF_OS_OBJECT_TYPE
129 
137  QF_OS_OBJECT_TYPE osObject;
138 #endif
139 
140 #ifdef QF_THREAD_TYPE
141 
148  QF_THREAD_TYPE thread;
149 #endif
150 
153 
154 } QActive;
155 
157 void QActive_ctor(QActive * const me, QStateHandler initial);
158 
160 typedef struct {
161  struct QHsmVtbl super;
165  void (*start)(QActive * const me, uint_fast8_t prio,
166  QEvt const *qSto[], uint_fast16_t qLen,
167  void *stkSto, uint_fast16_t stkSize,
168  QEvt const *ie);
169 
170 #ifdef Q_SPY
171 
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 
182  void (*postLIFO)(QActive * const me, QEvt const * const e);
183 
184 } QActiveVtbl;
185 
186 
205 #define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, param_) \
206  ((*((QActiveVtbl const *)((me_)->super.vptr))->start)( \
207  (me_), (prio_), (qSto_), (qLen_), (stkSto_), (stkLen_), (param_)))
208 
210 void QActive_start_(QActive * const me, uint_fast8_t prio,
211  QEvt const *qSto[], uint_fast16_t qLen,
212  void *stkSto, uint_fast16_t stkSize,
213  QEvt const *ie);
214 
215 #ifdef Q_SPY
216 
217  bool QActive_post_(QActive * const me, QEvt const * const e,
218  uint_fast16_t const margin,
219  void const * const sender);
220 
244  #define QACTIVE_POST(me_, e_, sender_) \
245  ((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
246  (e_), QF_NO_MARGIN, (sender_)))
247 
280  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
281  ((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
282  (e_), (margin_), (sender_)))
283 #else
284 
285  bool QActive_post_(QActive * const me, QEvt const * const e,
286  uint_fast16_t const margin);
287 
288  #define QACTIVE_POST(me_, e_, sender_) \
289  ((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
290  (e_), QF_NO_MARGIN))
291 
292  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
293  ((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
294  (e_), (margin_)))
295 
296 #endif
297 
299 void QActive_postLIFO_(QActive * const me, QEvt const * const e);
300 
307 #define QACTIVE_POST_LIFO(me_, e_) \
308  ((*((QActiveVtbl const *)((me_)->super.vptr))->postLIFO)((me_), (e_)))
309 
310 
311 /* protected functions for ::QActive ...*/
312 
315 void QActive_stop(QActive * const me);
316 
318 void QActive_subscribe(QActive const * const me, enum_t const sig);
319 
321 void QActive_unsubscribe(QActive const * const me, enum_t const sig);
322 
324 void QActive_unsubscribeAll(QActive const * const me);
325 
326 
328 bool QActive_defer(QActive const * const me,
329  QEQueue * const eq, QEvt const * const e);
330 
332 bool QActive_recall(QActive * const me, QEQueue * const eq);
333 
336  QEQueue * const eq);
337 
339 QEvt const *QActive_get_(QActive *const me);
340 
341 
342 /****************************************************************************/
371 
379 
381 void QMActive_ctor(QMActive * const me, QStateHandler initial);
382 
383 
384 /****************************************************************************/
385 #if (QF_TIMEEVT_CTR_SIZE == 1)
386  typedef uint8_t QTimeEvtCtr;
387 #elif (QF_TIMEEVT_CTR_SIZE == 2)
388 
400 #elif (QF_TIMEEVT_CTR_SIZE == 4)
401  typedef uint32_t QTimeEvtCtr;
402 #else
403  #error "QF_TIMEEVT_CTR_SIZE defined incorrectly, expected 1, 2, or 4"
404 #endif
405 
440 typedef struct QTimeEvt {
441  QEvt super; /*<! inherits ::QEvt */
442 
444  struct QTimeEvt * volatile next;
445 
447  void * volatile act;
448 
456  QTimeEvtCtr volatile ctr;
457 
466 } QTimeEvt;
467 
468 /* public functions */
469 
471 void QTimeEvt_ctorX(QTimeEvt * const me, QActive * const act,
472  enum_t const sig, uint_fast8_t tickRate);
473 
475 void QTimeEvt_armX(QTimeEvt * const me,
476  QTimeEvtCtr const nTicks, QTimeEvtCtr const interval);
477 
479 bool QTimeEvt_rearm(QTimeEvt * const me, QTimeEvtCtr const nTicks);
480 
482 bool QTimeEvt_disarm(QTimeEvt * const me);
483 
485 QTimeEvtCtr QTimeEvt_ctr(QTimeEvt const * const me);
486 
487 
488 /****************************************************************************/
489 /* QF facilities */
490 
501 
502 /* public functions */
503 
505 void QF_init(void);
506 
508 void QF_psInit(QSubscrList * const subscrSto, enum_t const maxSignal);
509 
511 void QF_poolInit(void * const poolSto, uint_fast32_t const poolSize,
512  uint_fast16_t const evtSize);
513 
516 
518 int_t QF_run(void);
519 
522 void QF_stop(void);
523 
531 void QF_onStartup(void);
532 
547 void QF_onCleanup(void);
548 
549 #ifdef Q_SPY
550 
552  void QF_publish_(QEvt const * const e, void const * const sender);
553 
576  #define QF_PUBLISH(e_, sender_) \
577  (QF_publish_((e_), (void const *)(sender_)))
578 #else
579 
580  void QF_publish_(QEvt const * const e);
581  #define QF_PUBLISH(e_, dummy_) (QF_publish_(e_))
582 
583 #endif
584 
585 #ifdef Q_SPY
586 
588  void QF_tickX_(uint_fast8_t const tickRate, void const * const sender);
589 
619  #define QF_TICK_X(tickRate_, sender_) (QF_tickX_((tickRate_), (sender_)))
620 
621 #else
622 
623  void QF_tickX_(uint_fast8_t const tickRate);
624  #define QF_TICK_X(tickRate_, dummy) (QF_tickX_(tickRate_))
625 
626 #endif
627 
631 #define QF_NO_MARGIN ((uint_fast16_t)0xFFFF)
632 
634 #define QF_TICK(sender_) QF_TICK_X((uint_fast8_t)0, (sender_))
635 
637 bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate);
638 
640 void QF_add_(QActive * const a);
641 
643 void QF_remove_(QActive * const a);
644 
647 
651 
653 QEvt *QF_newX_(uint_fast16_t const evtSize,
654  uint_fast16_t const margin, enum_t const sig);
655 
657 QEvt const *QF_newRef_(QEvt const * const e, QEvt const * const evtRef);
658 
659 #ifdef Q_EVT_CTOR /* Shall the ctor for the ::QEvt class be provided? */
660 
661  #define Q_NEW(evtT_, sig_, ...) \
662  (evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
663  QF_NO_MARGIN, (enum_t)0), (sig_), ##__VA_ARGS__))
664 
665  #define Q_NEW_X(e_, evtT_, margin_, sig_, ...) do { \
666  (e_) = (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
667  (margin_), (enum_t)0); \
668  if ((e_) != (evtT_ *)0) { \
669  evtT_##_ctor((e_), (sig_), ##__VA_ARGS__); \
670  } \
671  } while (0)
672 
673 #else
674 
697  #define Q_NEW(evtT_, sig_) \
698  ((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
699  QF_NO_MARGIN, (sig_)))
700 
727  #define Q_NEW_X(e_, evtT_, margin_, sig_) ((e_) = \
728  (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), (margin_), (sig_)))
729 
730 #endif /* Q_EVT_CTOR */
731 
752 #define Q_NEW_REF(evtRef_, evtT_) \
753  ((evtRef_) = (evtT_ const *)QF_newRef_(e, &(evtRef_)->super))
754 
770 #define Q_DELETE_REF(evtRef_) do { \
771  QF_gc(&(evtRef_)->super); \
772  (evtRef_) = (void *)0; \
773 } while (0)
774 
776 void QF_gc(QEvt const * const e);
777 
779 void QF_bzero(void * const start, uint_fast16_t len);
780 
781 #ifndef QF_CRIT_EXIT_NOP
782 
793  #define QF_CRIT_EXIT_NOP() ((void)0)
794 #endif
795 
800 extern QActive *QF_active_[QF_MAX_ACTIVE + 1];
801 
802 
803 /****************************************************************************/
814 typedef QActive QTicker;
815 
817 void QTicker_ctor(QTicker * const me, uint8_t tickRate);
818 
819 /****************************************************************************/
821 #define QF_getVersion() (QP_versionStr)
822 
823 #endif /* qf_h */
824 
825 
QState(* QStateHandler)(void *const me, QEvt const *const e)
Pointer to a state-handler function.
Definition: qep.h:211
bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate)
Returns &#39;true&#39; if there are no armed time events at a given tick rate.
Definition: qf_time.c:197
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:75
void *volatile act
the active object that receives the time events
Definition: qf.h:447
void QF_add_(QActive *const a)
Register an active object to be managed by the framework.
Definition: qf_act.c:69
uint_fast8_t prio
QF priority associated with the active object.
Definition: qf.h:152
uint16_t QEvtSize
The data type to store the block-size defined based on the macro QF_EVENT_SIZ_SIZE.
Definition: qf.h:61
QActive QTicker
QTicker Active Object class.
Definition: qf.h:814
void QActive_postLIFO_(QActive *const me, QEvt const *const e)
Implementation of the active object post LIFO operation.
Definition: qf_actq.c:200
void QF_publish_(QEvt const *const e, void const *const sender)
Publish event to the framework.
Definition: qf_ps.c:121
Time Event structure.
Definition: qf.h:440
Virtual table for the QHsm class.
Definition: qep.h:287
QEvt const * QActive_get_(QActive *const me)
Get an event from the event queue of an active object.
Definition: qf_actq.c:264
void QF_remove_(QActive *const a)
Remove the active object from the framework.
Definition: qf_act.c:109
QEvt const * QF_newRef_(QEvt const *const e, QEvt const *const evtRef)
Internal QF implementation of the event reference creator.
Definition: qf_dyn.c:270
unsigned short uint16_t
exact-width 16-bit unsigned int
Definition: stdint.h:29
Virtual table for the QActive class.
Definition: qf.h:160
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:28
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:232
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:112
void QActive_unsubscribeAll(QActive const *const me)
Un-subscribes from the delivery of all signals to the AO me.
Definition: qf_ps.c:297
#define QF_THREAD_TYPE
This macro defines the type of the thread handle used for the active objects.
Definition: macros.h:45
void QF_psInit(QSubscrList *const subscrSto, enum_t const maxSignal)
Publish-subscribe initialization.
Definition: qf_ps.c:85
uint_fast16_t QF_poolGetMaxBlockSize(void)
Obtain the block size of any registered event pools.
Definition: qf_dyn.c:291
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
QTimeEvtCtr QTimeEvt_ctr(QTimeEvt const *const me)
Get the current value of the down-counter of a time event.
Definition: qf_time.c:496
int_t QF_run(void)
Transfers control to QF to run the application.
Definition: qk.c:125
int enum_t
typedef for enumerations used for event signals
Definition: qep.h:75
QTimeEvtCtr interval
the interval for periodic time event (zero for one-shot time event)
Definition: qf.h:465
QActive QMActive
QMActive active object (based on QMsm implementation)
Definition: qf.h:370
struct QTimeEvt *volatile next
link to the next time event in the list
Definition: qf.h:444
void QF_onStartup(void)
Startup QF callback.
void QTicker_ctor(QTicker *const me, uint8_t tickRate)
Constructor of the QTicker Active Object class.
Definition: qf_actq.c:371
void QF_bzero(void *const start, uint_fast16_t len)
Clear a specified region of memory to zero.
Definition: qf_act.c:159
unsigned long uint_fast32_t
fast at-least 32-bit unsigned int
Definition: stdint.h:39
void QF_gc(QEvt const *const e)
Recycle a dynamic event.
Definition: qf_dyn.c:217
bool QActive_post_(QActive *const me, QEvt const *const e, uint_fast16_t const margin, void const *const sender)
Implementation of the active object post (FIFO) operation.
Definition: qf_actq.c:101
void QActive_stop(QActive *const me)
Stops execution of an active object and removes it from the framework&#39;s supervision.
Definition: qk.c:206
Event structure.
Definition: qep.h:152
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:292
Native QF Event Queue.
Definition: qequeue.h:130
unsigned long uint32_t
exact-width 32-bit unsigned int
Definition: stdint.h:30
Definition: qep.h:280
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:289
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:100
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:250
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:75
unsigned int uint_fast16_t
fast at-least 16-bit unsigned int
Definition: stdint.h:37
#define QF_MAX_ACTIVE
The maximum number of active objects in the application.
Definition: qf_port.h:58
void QActive_ctor(QActive *const me, QStateHandler initial)
protected "constructor" of an QActive active object
Definition: qf_qact.c:65
void QActive_start_(QActive *const me, uint_fast8_t prio, QEvt const *qSto[], uint_fast16_t qLen, void *stkSto, uint_fast16_t stkSize, QEvt const *ie)
Implementation of the active object start operation.
Definition: qk.c:162
Priority Set of up to 32 elements.
Definition: qpset.h:56
bool QTimeEvt_disarm(QTimeEvt *const me)
Disarm a time event.
Definition: qf_time.c:362
void QF_onCleanup(void)
Cleanup QF callback.
QHsm super
inherits QHsm
Definition: qf.h:111
QPSet QSubscrList
Subscriber-List structure.
Definition: qf.h:500
#define QF_EQUEUE_TYPE
This macro defines the type of the event queue used for the active objects.
Definition: qk.h:57
void QMActive_ctor(QMActive *const me, QStateHandler initial)
protected "constructor" of an QMActive active object.
Definition: qf_qmact.c:67
QP native, platform-independent priority sets of 32 or 64 elements.
int bool
standard Boolean data type
Definition: stdbool.h:16
uint_fast16_t QActive_flushDeferred(QActive const *const me, QEQueue *const eq)
Flush the specified deferred queue eq.
Definition: qf_defer.c:154
QEvt * QF_newX_(uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)
Internal QF implementation of the dynamic event allocator.
Definition: qf_dyn.c:152
int int_t
typedef for line numbers in assertions and return from QF_run()
Definition: qep.h:72
Active Object (based on QHsm implementation)
Definition: qf.h:110
bool QActive_recall(QActive *const me, QEQueue *const eq)
Recall a deferred event from a given event queue eq.
Definition: qf_defer.c:103
QActive * QF_active_[QF_MAX_ACTIVE+1]
array of registered active objects
Definition: qf_act.c:53
QActiveVtbl QMActiveVtbl
Virtual Table for the QMActive class (inherited from QActiveVtbl.
Definition: qf.h:378
QTimeEvtCtr volatile ctr
the internal down-counter of the time event.
Definition: qf.h:456
bool QTimeEvt_rearm(QTimeEvt *const me, QTimeEvtCtr const nTicks)
Rearm a time event.
Definition: qf_time.c:421
uint16_t QTimeEvtCtr
type of the Time Event counter, which determines the dynamic range of the time delays measured in clo...
Definition: qf.h:399
#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:41
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:205
void QF_init(void)
QF initialization.
Definition: qk.c:71
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:330