QP/C  5.8.2
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 {
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 
159 
161 typedef struct {
162  struct QHsmVtbl super;
166  void (*start)(QActive * const me, uint_fast8_t prio,
167  QEvt const *qSto[], uint_fast16_t qLen,
168  void *stkSto, uint_fast16_t stkSize,
169  QEvt const *ie);
170 
171 #ifdef Q_SPY
172 
174  bool (*post)(QActive * const me, QEvt const * const e,
175  uint_fast16_t const margin, void const * const sender);
176 #else
177  bool (*post)(QActive * const me, QEvt const * const e,
178  uint_fast16_t const margin);
179 #endif
180 
183  void (*postLIFO)(QActive * const me, QEvt const * const e);
184 
185 } QActiveVtbl;
186 
187 
206 #define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, param_) \
207  ((*((QActiveVtbl const *)((me_)->super.vptr))->start)( \
208  (me_), (prio_), (qSto_), (qLen_), (stkSto_), (stkLen_), (param_)))
209 
211 void QActive_start_(QActive * const me, uint_fast8_t prio,
212  QEvt const *qSto[], uint_fast16_t qLen,
213  void *stkSto, uint_fast16_t stkSize,
214  QEvt const *ie);
215 
216 #ifdef Q_SPY
217 
218  bool QActive_post_(QActive * const me, QEvt const * const e,
219  uint_fast16_t const margin,
220  void const * const sender);
221 
245  #define QACTIVE_POST(me_, e_, sender_) \
246  ((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
247  (e_), (uint_fast16_t)0, (sender_)))
248 
279  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
280  ((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
281  (e_), (margin_), (sender_)))
282 #else
283 
284  bool QActive_post_(QActive * const me, QEvt const * const e,
285  uint_fast16_t const margin);
286 
287  #define QACTIVE_POST(me_, e_, sender_) \
288  ((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
289  (e_), (uint_fast16_t)0))
290 
291  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
292  ((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
293  (e_), (margin_)))
294 
295 #endif
296 
298 void QActive_postLIFO_(QActive * const me, QEvt const * const e);
299 
306 #define QACTIVE_POST_LIFO(me_, e_) \
307  ((*((QActiveVtbl const *)((me_)->super.vptr))->postLIFO)((me_), (e_)))
308 
309 
310 /* protected functions for ::QActive ...*/
311 
314 void QActive_stop(QActive * const me);
315 
317 void QActive_subscribe(QActive const * const me, enum_t const sig);
318 
320 void QActive_unsubscribe(QActive const * const me, enum_t const sig);
321 
323 void QActive_unsubscribeAll(QActive const * const me);
324 
325 
327 bool QActive_defer(QActive const * const me,
328  QEQueue * const eq, QEvt const * const e);
329 
331 bool QActive_recall(QActive * const me, QEQueue * const eq);
332 
335  QEQueue * const eq);
336 
338 QEvt const *QActive_get_(QActive *const me);
339 
340 
341 /****************************************************************************/
370 
378 
380 void QMActive_ctor(QMActive * const me, QStateHandler initial);
381 
382 
383 /****************************************************************************/
384 #if (QF_TIMEEVT_CTR_SIZE == 1)
385  typedef uint8_t QTimeEvtCtr;
386 #elif (QF_TIMEEVT_CTR_SIZE == 2)
387 
399 #elif (QF_TIMEEVT_CTR_SIZE == 4)
400  typedef uint32_t QTimeEvtCtr;
401 #else
402  #error "QF_TIMEEVT_CTR_SIZE defined incorrectly, expected 1, 2, or 4"
403 #endif
404 
439 typedef struct QTimeEvt {
440  QEvt super; /*<! inherits ::QEvt */
441 
443  struct QTimeEvt * volatile next;
444 
446  void * volatile act;
447 
455  QTimeEvtCtr volatile ctr;
456 
465 } QTimeEvt;
466 
467 /* public functions */
468 
470 void QTimeEvt_ctorX(QTimeEvt * const me, QActive * const act,
471  enum_t const sig, uint_fast8_t tickRate);
472 
474 void QTimeEvt_armX(QTimeEvt * const me,
475  QTimeEvtCtr const nTicks, QTimeEvtCtr const interval);
476 
478 bool QTimeEvt_rearm(QTimeEvt * const me, QTimeEvtCtr const nTicks);
479 
481 bool QTimeEvt_disarm(QTimeEvt * const me);
482 
484 QTimeEvtCtr QTimeEvt_ctr(QTimeEvt const * const me);
485 
486 
487 /****************************************************************************/
488 /* QF facilities */
489 
500 
501 /* public functions */
502 
504 void QF_init(void);
505 
507 void QF_psInit(QSubscrList * const subscrSto, enum_t const maxSignal);
508 
510 void QF_poolInit(void * const poolSto, uint_fast32_t const poolSize,
511  uint_fast16_t const evtSize);
512 
515 
517 int_t QF_run(void);
518 
521 void QF_stop(void);
522 
530 void QF_onStartup(void);
531 
546 void QF_onCleanup(void);
547 
548 #ifdef Q_SPY
549 
551  void QF_publish_(QEvt const * const e, void const * const sender);
552 
575  #define QF_PUBLISH(e_, sender_) \
576  (QF_publish_((e_), (void const *)(sender_)))
577 #else
578 
579  void QF_publish_(QEvt const * const e);
580  #define QF_PUBLISH(e_, dummy_) (QF_publish_(e_))
581 
582 #endif
583 
584 #ifdef Q_SPY
585 
587  void QF_tickX_(uint_fast8_t const tickRate, void const * const sender);
588 
618  #define QF_TICK_X(tickRate_, sender_) (QF_tickX_((tickRate_), (sender_)))
619 
620 #else
621 
622  void QF_tickX_(uint_fast8_t const tickRate);
623  #define QF_TICK_X(tickRate_, dummy) (QF_tickX_(tickRate_))
624 
625 #endif
626 
628 #define QF_TICK(sender_) QF_TICK_X((uint_fast8_t)0, (sender_))
629 
631 bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate);
632 
634 void QF_add_(QActive * const a);
635 
637 void QF_remove_(QActive * const a);
638 
641 
645 
647 QEvt *QF_newX_(uint_fast16_t const evtSize,
648  uint_fast16_t const margin, enum_t const sig);
649 
651 QEvt const *QF_newRef_(QEvt const * const e, QEvt const * const evtRef);
652 
653 #ifdef Q_EVT_CTOR /* Shall the ctor for the ::QEvt class be provided? */
654 
655  #define Q_NEW(evtT_, sig_, ...) \
656  (evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
657  (uint_fast16_t)0, (enum_t)0), (sig_), ##__VA_ARGS__))
658 
659  #define Q_NEW_X(e_, evtT_, margin_, sig_, ...) do { \
660  (e_) = (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
661  (margin_), (enum_t)0); \
662  if ((e_) != (evtT_ *)0) { \
663  evtT_##_ctor((e_), (sig_), ##__VA_ARGS__); \
664  } \
665  } while (0)
666 
667 #else
668 
691  #define Q_NEW(evtT_, sig_) \
692  ((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
693  (uint_fast16_t)0, (sig_)))
694 
719  #define Q_NEW_X(e_, evtT_, margin_, sig_) ((e_) = \
720  (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), (margin_), (sig_)))
721 
722 #endif /* Q_EVT_CTOR */
723 
744 #define Q_NEW_REF(evtRef_, evtT_) \
745  ((evtRef_) = (evtT_ const *)QF_newRef_(e, &(evtRef_)->super))
746 
762 #define Q_DELETE_REF(evtRef_) do { \
763  QF_gc(&(evtRef_)->super); \
764  (evtRef_) = (void *)0; \
765 } while (0)
766 
768 void QF_gc(QEvt const * const e);
769 
771 void QF_bzero(void * const start, uint_fast16_t len);
772 
773 #ifndef QF_CRIT_EXIT_NOP
774 
785  #define QF_CRIT_EXIT_NOP() ((void)0)
786 #endif
787 
792 extern QActive *QF_active_[QF_MAX_ACTIVE + 1];
793 
794 
795 /****************************************************************************/
806 typedef QActive QTicker;
807 
809 void QTicker_ctor(QTicker * const me, uint8_t tickRate);
810 
811 /****************************************************************************/
813 #define QF_getVersion() (QP_versionStr)
814 
815 #endif /* qf_h */
816 
817 
QState(* QStateHandler)(void *const me, QEvt const *const e)
Pointer to a state-handler function.
Definition: qep.h:212
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:196
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:446
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:806
void QActive_postLIFO_(QActive *const me, QEvt const *const e)
Implementation of the active object post LIFO operation.
Definition: qf_actq.c:198
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:439
Virtual table for the QHsm class.
Definition: qep.h:288
QEvt const * QActive_get_(QActive *const me)
Get an event from the event queue of an active object.
Definition: qf_actq.c:262
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:264
unsigned short uint16_t
exact-width 16-bit unsigned int
Definition: stdint.h:29
Virtual table for the QActive class.
Definition: qf.h:161
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:231
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:285
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:495
int_t QF_run(void)
Transfers control to QF to run the application.
Definition: qk.c:130
int enum_t
typedef for enumerations used for event signals
Definition: qep.h:76
QTimeEvtCtr interval
the interval for periodic time event (zero for one-shot time event)
Definition: qf.h:464
QActive QMActive
QMActive active object (based on QMsm implementation)
Definition: qf.h:369
struct QTimeEvt *volatile next
link to the next time event in the list
Definition: qf.h:443
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:358
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:211
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:103
void QActive_stop(QActive *const me)
Stops execution of an active object and removes it from the framework&#39;s supervision.
Definition: qk.c:209
Event structure.
Definition: qep.h:153
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:291
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:281
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:288
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:105
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:70
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:169
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:361
void QF_onCleanup(void)
Cleanup QF callback.
QHsm super
inherits QHsm
Definition: qf.h:111
QPSet QSubscrList
Subscriber-List structure.
Definition: qf.h:499
#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:149
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:150
int int_t
typedef for line numbers in assertions and return from QF_run()
Definition: qep.h:73
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:98
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:377
QTimeEvtCtr volatile ctr
the internal down-counter of the time event.
Definition: qf.h:455
bool QTimeEvt_rearm(QTimeEvt *const me, QTimeEvtCtr const nTicks)
Rearm a time event.
Definition: qf_time.c:420
uint16_t QTimeEvtCtr
type of the Time Event counter, which determines the dynamic range of the time delays measured in clo...
Definition: qf.h:398
#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:327