QP/C  5.9.8
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 
126  QF_EQUEUE_TYPE eQueue;
127 #endif
128 
129 #ifdef QF_OS_OBJECT_TYPE
130 
138  QF_OS_OBJECT_TYPE osObject;
139 #endif
140 
141 #ifdef QF_THREAD_TYPE
142 
149  QF_THREAD_TYPE thread;
150 #endif
151 
154 
155 #ifdef qxk_h /* QXK kernel used? */
156 
157  uint_fast8_t startPrio;
158 #endif
159 
160 } QActive;
161 
163 void QActive_ctor(QActive * const me, QStateHandler initial);
164 
166 typedef struct {
167  struct QHsmVtbl super;
171  void (*start)(QActive * const me, uint_fast8_t prio,
172  QEvt const *qSto[], uint_fast16_t qLen,
173  void *stkSto, uint_fast16_t stkSize,
174  QEvt const *ie);
175 
176 #ifdef Q_SPY
177 
179  bool (*post)(QActive * const me, QEvt const * const e,
180  uint_fast16_t const margin, void const * const sender);
181 #else
182  bool (*post)(QActive * const me, QEvt const * const e,
183  uint_fast16_t const margin);
184 #endif
185 
188  void (*postLIFO)(QActive * const me, QEvt const * const e);
189 
190 } QActiveVtbl;
191 
192 
211 #define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, param_) \
212  ((*((QActiveVtbl const *)((me_)->super.vptr))->start)( \
213  (me_), (prio_), (qSto_), (qLen_), (stkSto_), (stkLen_), (param_)))
214 
216 void QActive_start_(QActive * const me, uint_fast8_t prio,
217  QEvt const *qSto[], uint_fast16_t qLen,
218  void *stkSto, uint_fast16_t stkSize,
219  QEvt const *ie);
220 
221 #ifdef Q_SPY
222 
223  bool QActive_post_(QActive * const me, QEvt const * const e,
224  uint_fast16_t const margin,
225  void const * const sender);
226 
252  #define QACTIVE_POST(me_, e_, sender_) \
253  ((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
254  (e_), QF_NO_MARGIN, (sender_)))
255 
290  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
291  ((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
292  (e_), (margin_), (sender_)))
293 #else
294 
295  bool QActive_post_(QActive * const me, QEvt const * const e,
296  uint_fast16_t const margin);
297 
298  #define QACTIVE_POST(me_, e_, sender_) \
299  ((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
300  (e_), QF_NO_MARGIN))
301 
302  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
303  ((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
304  (e_), (margin_)))
305 
306 #endif
307 
309 void QActive_postLIFO_(QActive * const me, QEvt const * const e);
310 
317 #define QACTIVE_POST_LIFO(me_, e_) \
318  ((*((QActiveVtbl const *)((me_)->super.vptr))->postLIFO)((me_), (e_)))
319 
320 
321 /* protected functions for ::QActive ...*/
322 
325 void QActive_stop(QActive * const me);
326 
328 void QActive_subscribe(QActive const * const me, enum_t const sig);
329 
331 void QActive_unsubscribe(QActive const * const me, enum_t const sig);
332 
334 void QActive_unsubscribeAll(QActive const * const me);
335 
336 
338 bool QActive_defer(QActive const * const me,
339  QEQueue * const eq, QEvt const * const e);
340 
342 bool QActive_recall(QActive * const me, QEQueue * const eq);
343 
346  QEQueue * const eq);
347 
349 QEvt const *QActive_get_(QActive *const me);
350 
351 
352 /****************************************************************************/
381 
389 
391 void QMActive_ctor(QMActive * const me, QStateHandler initial);
392 
393 
394 /****************************************************************************/
395 #if (QF_TIMEEVT_CTR_SIZE == 1)
396  typedef uint8_t QTimeEvtCtr;
397 #elif (QF_TIMEEVT_CTR_SIZE == 2)
398 
410 #elif (QF_TIMEEVT_CTR_SIZE == 4)
411  typedef uint32_t QTimeEvtCtr;
412 #else
413  #error "QF_TIMEEVT_CTR_SIZE defined incorrectly, expected 1, 2, or 4"
414 #endif
415 
453 typedef struct QTimeEvt {
454  QEvt super; /*<! inherits ::QEvt */
455 
457  struct QTimeEvt * volatile next;
458 
460  void * volatile act;
461 
469  QTimeEvtCtr volatile ctr;
470 
479 } QTimeEvt;
480 
481 /* public functions */
482 
484 void QTimeEvt_ctorX(QTimeEvt * const me, QActive * const act,
485  enum_t const sig, uint_fast8_t tickRate);
486 
488 void QTimeEvt_armX(QTimeEvt * const me,
489  QTimeEvtCtr const nTicks, QTimeEvtCtr const interval);
490 
492 bool QTimeEvt_rearm(QTimeEvt * const me, QTimeEvtCtr const nTicks);
493 
495 bool QTimeEvt_disarm(QTimeEvt * const me);
496 
498 QTimeEvtCtr QTimeEvt_ctr(QTimeEvt const * const me);
499 
500 
501 /****************************************************************************/
502 /* QF facilities */
503 
514 
515 /* public functions */
516 
518 void QF_init(void);
519 
521 void QF_psInit(QSubscrList * const subscrSto, enum_t const maxSignal);
522 
524 void QF_poolInit(void * const poolSto, uint_fast32_t const poolSize,
525  uint_fast16_t const evtSize);
526 
529 
531 int_t QF_run(void);
532 
535 void QF_stop(void);
536 
544 void QF_onStartup(void);
545 
560 void QF_onCleanup(void);
561 
562 #ifdef Q_SPY
563 
565  void QF_publish_(QEvt const * const e, void const * const sender);
566 
590  #define QF_PUBLISH(e_, sender_) \
591  (QF_publish_((e_), (void const *)(sender_)))
592 #else
593 
594  void QF_publish_(QEvt const * const e);
595  #define QF_PUBLISH(e_, dummy_) (QF_publish_(e_))
596 
597 #endif
598 
599 #ifdef Q_SPY
600 
602  void QF_tickX_(uint_fast8_t const tickRate, void const * const sender);
603 
633  #define QF_TICK_X(tickRate_, sender_) (QF_tickX_((tickRate_), (sender_)))
634 
635 #else
636 
637  void QF_tickX_(uint_fast8_t const tickRate);
638  #define QF_TICK_X(tickRate_, dummy) (QF_tickX_(tickRate_))
639 
640 #endif
641 
645 #define QF_NO_MARGIN ((uint_fast16_t)0xFFFF)
646 
648 #define QF_TICK(sender_) QF_TICK_X((uint_fast8_t)0, (sender_))
649 
651 bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate);
652 
654 void QF_add_(QActive * const a);
655 
657 void QF_remove_(QActive * const a);
658 
661 
665 
667 QEvt *QF_newX_(uint_fast16_t const evtSize,
668  uint_fast16_t const margin, enum_t const sig);
669 
671 QEvt const *QF_newRef_(QEvt const * const e, QEvt const * const evtRef);
672 
673 #ifdef Q_EVT_CTOR /* Shall the ctor for the ::QEvt class be provided? */
674 
675  #define Q_NEW(evtT_, sig_, ...) \
676  (evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
677  QF_NO_MARGIN, (enum_t)0), (sig_), ##__VA_ARGS__))
678 
679  #define Q_NEW_X(e_, evtT_, margin_, sig_, ...) do { \
680  (e_) = (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
681  (margin_), (enum_t)0); \
682  if ((e_) != (evtT_ *)0) { \
683  evtT_##_ctor((e_), (sig_), ##__VA_ARGS__); \
684  } \
685  } while (0)
686 
687 #else
688 
711  #define Q_NEW(evtT_, sig_) \
712  ((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
713  QF_NO_MARGIN, (sig_)))
714 
741  #define Q_NEW_X(e_, evtT_, margin_, sig_) ((e_) = \
742  (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), (margin_), (sig_)))
743 
744 #endif /* Q_EVT_CTOR */
745 
766 #define Q_NEW_REF(evtRef_, evtT_) \
767  ((evtRef_) = (evtT_ const *)QF_newRef_(e, &(evtRef_)->super))
768 
784 #define Q_DELETE_REF(evtRef_) do { \
785  QF_gc(&(evtRef_)->super); \
786  (evtRef_) = (void *)0; \
787 } while (0)
788 
790 void QF_gc(QEvt const * const e);
791 
793 void QF_bzero(void * const start, uint_fast16_t len);
794 
795 #ifndef QF_CRIT_EXIT_NOP
796 
807  #define QF_CRIT_EXIT_NOP() ((void)0)
808 #endif
809 
814 extern QActive *QF_active_[QF_MAX_ACTIVE + 1];
815 
816 
817 /****************************************************************************/
828 typedef QActive QTicker;
829 
831 void QTicker_ctor(QTicker * const me, uint8_t tickRate);
832 
833 /****************************************************************************/
835 #define QF_getVersion() (QP_versionStr)
836 
837 #endif /* qf_h */
838 
839 
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 QF_add_(QActive *const a)
Register an active object to be managed by the framework.
Definition: qf_act.c:69
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:828
void QActive_postLIFO_(QActive *const me, QEvt const *const e)
Implementation of the active object post LIFO operation.
Definition: qf_actq.c:193
void *volatile act
the active object that receives the time events
Definition: qf.h:460
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:453
Virtual table for the QHsm class.
Definition: qep.h:287
struct QTimeEvt *volatile next
link to the next time event in the list
Definition: qf.h:457
QEvt const * QActive_get_(QActive *const me)
Get an event from the event queue of an active object.
Definition: qf_actq.c:266
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:166
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
QActive QMActive
QMActive active object (based on QMsm implementation)
Definition: qf.h:380
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:374
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:93
void QActive_stop(QActive *const me)
Stops execution of an active object and removes it from the framework&#39;s supervision.
Definition: qk.c:207
Event structure.
Definition: qep.h:152
QHsm super
inherits QHsm
Definition: qf.h:111
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
QTimeEvtCtr interval
the interval for periodic time event (zero for one-shot time event)
Definition: qf.h:478
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.
QPSet QSubscrList
Subscriber-List structure.
Definition: qf.h:513
#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:388
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:409
QTimeEvtCtr volatile ctr
the internal down-counter of the time event.
Definition: qf.h:469
#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_fast8_t prio
QF priority (1..QF_MAX_ACTIVE) of this active object.
Definition: qf.h:153
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:333