QP/C  6.5.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 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 
77  #define QF_MAX_TICK_RATE 1
78 #elif (QF_MAX_TICK_RATE > 15)
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 /****************************************************************************/
114 typedef struct QActive {
117 #ifdef QF_EQUEUE_TYPE
118 
130  QF_EQUEUE_TYPE eQueue;
131 #endif
132 
133 #ifdef QF_OS_OBJECT_TYPE
134 
142  QF_OS_OBJECT_TYPE osObject;
143 #endif
144 
145 #ifdef QF_THREAD_TYPE
146 
153  QF_THREAD_TYPE thread;
154 #endif
155 
158 
159 #ifdef qxk_h /* QXK kernel used? */
160 
161  uint8_t startPrio;
162 #endif
163 
164 } QActive;
165 
167 void QActive_ctor(QActive * const me, QStateHandler initial);
168 
170 typedef struct {
171  struct QHsmVtbl super;
175  void (*start)(QActive * const me, uint_fast8_t prio,
176  QEvt const *qSto[], uint_fast16_t qLen,
177  void *stkSto, uint_fast16_t stkSize,
178  QEvt const *ie);
179 
180 #ifdef Q_SPY
181 
183  bool (*post)(QActive * const me, QEvt const * const e,
184  uint_fast16_t const margin, void const * const sender);
185 #else
186  bool (*post)(QActive * const me, QEvt const * const e,
187  uint_fast16_t const margin);
188 #endif
189 
192  void (*postLIFO)(QActive * const me, QEvt const * const e);
193 
194 } QActiveVtbl;
195 
196 
215 #define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, par_) do { \
216  Q_ASSERT((me_)->super.vptr); \
217  (*((QActiveVtbl const *)((me_)->super.vptr))->start)( \
218  (me_), (prio_), (qSto_), (qLen_), (stkSto_), (stkLen_), (par_)); \
219 } while (0)
220 
221 #ifdef Q_SPY
222 
247  #define QACTIVE_POST(me_, e_, sender_) \
248  ((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
249  (e_), QF_NO_MARGIN, (sender_)))
250 
285  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
286  ((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
287  (e_), (margin_), (sender_)))
288 #else
289 
290  #define QACTIVE_POST(me_, e_, sender_) \
291  ((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
292  (e_), QF_NO_MARGIN))
293 
294  #define QACTIVE_POST_X(me_, e_, margin_, sender_) \
295  ((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
296  (e_), (margin_)))
297 
298 #endif
299 
306 #define QACTIVE_POST_LIFO(me_, e_) \
307  ((*((QActiveVtbl const *)((me_)->super.vptr))->postLIFO)((me_), (e_)))
308 
309 /* protected functions for ::QActive ...*/
310 
311 #ifdef QF_ACTIVE_STOP
312 
314  void QActive_stop(QActive * const me);
315 #endif
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 
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 void QActive_setAttr(QActive *const me, uint32_t attr1, void const *attr2);
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 
442 typedef struct QTimeEvt {
443  QEvt super; /*<! inherits ::QEvt */
444 
446  struct QTimeEvt * volatile next;
447 
449  void * volatile act;
450 
458  QTimeEvtCtr volatile ctr;
459 
468 } QTimeEvt;
469 
470 /* public functions */
471 
473 void QTimeEvt_ctorX(QTimeEvt * const me, QActive * const act,
474  enum_t const sig, uint_fast8_t tickRate);
475 
477 void QTimeEvt_armX(QTimeEvt * const me,
478  QTimeEvtCtr const nTicks, QTimeEvtCtr const interval);
479 
481 bool QTimeEvt_rearm(QTimeEvt * const me, QTimeEvtCtr const nTicks);
482 
484 bool QTimeEvt_disarm(QTimeEvt * const me);
485 
487 bool QTimeEvt_wasDisarmed(QTimeEvt * const me);
488 
490 QTimeEvtCtr QTimeEvt_currCtr(QTimeEvt const * const me);
491 
492 
493 /****************************************************************************/
494 /* QF facilities */
495 
506 
507 /* public functions */
508 
510 void QF_init(void);
511 
513 void QF_psInit(QSubscrList * const subscrSto, enum_t const maxSignal);
514 
516 void QF_poolInit(void * const poolSto, uint_fast32_t const poolSize,
517  uint_fast16_t const evtSize);
518 
521 
523 int_t QF_run(void);
524 
527 void QF_stop(void);
528 
536 void QF_onStartup(void);
537 
552 void QF_onCleanup(void);
553 
554 #ifdef Q_SPY
555 
557  void QF_publish_(QEvt const * const e, void const * const sender);
558 
582  #define QF_PUBLISH(e_, sender_) \
583  (QF_publish_((e_), (void const *)(sender_)))
584 #else
585 
586  void QF_publish_(QEvt const * const e);
587  #define QF_PUBLISH(e_, dummy_) (QF_publish_(e_))
588 
589 #endif
590 
591 #ifdef Q_SPY
592 
594  void QF_tickX_(uint_fast8_t const tickRate, void const * const sender);
595 
625  #define QF_TICK_X(tickRate_, sender_) (QF_tickX_((tickRate_), (sender_)))
626 
627 #else
628 
629  void QF_tickX_(uint_fast8_t const tickRate);
630  #define QF_TICK_X(tickRate_, dummy) (QF_tickX_(tickRate_))
631 
632 #endif
633 
637 #define QF_NO_MARGIN ((uint_fast16_t)0xFFFF)
638 
640 #define QF_TICK(sender_) QF_TICK_X((uint_fast8_t)0, (sender_))
641 
643 bool QF_noTimeEvtsActiveX(uint_fast8_t const tickRate);
644 
646 void QF_add_(QActive * const a);
647 
649 void QF_remove_(QActive * const a);
650 
653 
657 
659 QEvt *QF_newX_(uint_fast16_t const evtSize,
660  uint_fast16_t const margin, enum_t const sig);
661 
663 QEvt const *QF_newRef_(QEvt const * const e, void const * const evtRef);
664 
666 void QF_deleteRef_(void const * const evtRef);
667 
668 #ifdef Q_EVT_CTOR /* Shall the ctor for the ::QEvt class be provided? */
669 
670  #define Q_NEW(evtT_, sig_, ...) \
671  (evtT_##_ctor((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
672  QF_NO_MARGIN, (enum_t)0), (sig_), ##__VA_ARGS__))
673 
674  #define Q_NEW_X(e_, evtT_, margin_, sig_, ...) do { \
675  (e_) = (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
676  (margin_), (enum_t)0); \
677  if ((e_) != (evtT_ *)0) { \
678  evtT_##_ctor((e_), (sig_), ##__VA_ARGS__); \
679  } \
680  } while (0)
681 
682 #else
683 
706  #define Q_NEW(evtT_, sig_) \
707  ((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
708  QF_NO_MARGIN, (sig_)))
709 
736  #define Q_NEW_X(e_, evtT_, margin_, sig_) ((e_) = \
737  (evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), (margin_), (sig_)))
738 
739 #endif /* Q_EVT_CTOR */
740 
761 #define Q_NEW_REF(evtRef_, evtT_) \
762  ((evtRef_) = (evtT_ const *)QF_newRef_(e, (evtRef_)))
763 
779 #define Q_DELETE_REF(evtRef_) do { \
780  QF_deleteRef_((evtRef_)); \
781  (evtRef_) = (void *)0; \
782 } while (0)
783 
785 void QF_gc(QEvt const * const e);
786 
788 void QF_bzero(void * const start, uint_fast16_t len);
789 
790 #ifndef QF_CRIT_EXIT_NOP
791 
802  #define QF_CRIT_EXIT_NOP() ((void)0)
803 #endif
804 
809 extern QActive *QF_active_[QF_MAX_ACTIVE + 1];
810 
811 
812 /****************************************************************************/
823 typedef QActive QTicker;
824 
826 void QTicker_ctor(QTicker * const me, uint8_t tickRate);
827 
828 /****************************************************************************/
830 #define QF_getVersion() (QP_versionStr)
831 
832 #endif /* qf_h */
833 
QEvt const * QF_newRef_(QEvt const *const e, void const *const evtRef)
Internal QF implementation of creating new event reference.
Definition: qf_dyn.c:285
QState(* QStateHandler)(void *const me, QEvt const *const e)
Pointer to a state-handler function.
Definition: qep.h:209
uint8_t prio
QF priority (1..QF_MAX_ACTIVE) of this active object.
Definition: qf.h:157
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:204
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:78
QTimeEvtCtr QTimeEvt_currCtr(QTimeEvt const *const me)
Get the current value of the down-counter of a time event.
Definition: qf_time.c:535
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:823
void *volatile act
the active object that receives the time events
Definition: qf.h:449
void QF_publish_(QEvt const *const e, void const *const sender)
Publish event to the framework.
Definition: qf_ps.c:122
Time Event structure.
Definition: qf.h:442
Virtual table for the QHsm class.
Definition: qep.h:285
struct QTimeEvt *volatile next
link to the next time event in the list
Definition: qf.h:446
void QF_remove_(QActive *const a)
Remove the active object from the framework.
Definition: qf_act.c:102
void QActive_setAttr(QActive *const me, uint32_t attr1, void const *attr2)
Generic setting of additional attributes (useful in QP ports)
unsigned short uint16_t
exact-width 16-bit unsigned int
Definition: stdint.h:30
Virtual table for the QActive class.
Definition: qf.h:170
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: stdint.h:29
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:237
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:304
#define QF_THREAD_TYPE
This macro defines the type of the thread handle used for the active objects.
Definition: macros.h:53
void QF_psInit(QSubscrList *const subscrSto, enum_t const maxSignal)
Publish-subscribe initialization.
Definition: qf_ps.c:86
uint_fast16_t QF_poolGetMaxBlockSize(void)
Obtain the block size of any registered event pools.
Definition: qf_dyn.c:337
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:36
int_t QF_run(void)
Transfers control to QF to run the application.
Definition: qutest.c:70
int enum_t
typedef for enumerations used for event signals
Definition: qep.h:76
QActive QMActive
QMActive active object (based on QMsm implementation)
Definition: qf.h:369
bool QTimeEvt_wasDisarmed(QTimeEvt *const me)
Check the "was disarmed" status of a time event.
Definition: qf_time.c:513
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:437
void QF_bzero(void *const start, uint_fast16_t len)
Clear a specified region of memory to zero.
Definition: qf_act.c:144
unsigned long uint_fast32_t
fast at-least 32-bit unsigned int
Definition: stdint.h:40
void QF_gc(QEvt const *const e)
Recycle a dynamic event.
Definition: qf_dyn.c:229
Event structure.
Definition: qep.h:153
QHsm super
inherits QHsm
Definition: qf.h:115
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:296
Native QF Event Queue.
Definition: qequeue.h:130
unsigned long uint32_t
exact-width 32-bit unsigned int
Definition: stdint.h:31
Definition: qep.h:278
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
void QF_stop(void)
Function invoked by the application layer to stop the QF application and return control to the OS/Ker...
Definition: qutest.c:66
QTimeEvtCtr interval
the interval for periodic time event (zero for one-shot time event)
Definition: qf.h:467
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
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:77
unsigned int uint_fast16_t
fast at-least 16-bit unsigned int
Definition: stdint.h:38
#define QF_MAX_ACTIVE
The maximum number of active objects in the application.
Definition: qk/qf_port.h:58
void QActive_ctor(QActive *const me, QStateHandler initial)
protected "constructor" of an QActive active object
Definition: qf_qact.c:66
Priority Set of up to 32 elements.
Definition: qpset.h:63
bool QTimeEvt_disarm(QTimeEvt *const me)
Disarm a time event.
Definition: qf_time.c:371
void QF_onCleanup(void)
Cleanup QF callback.
QPSet QSubscrList
Subscriber-List structure.
Definition: qf.h:505
#define QF_EQUEUE_TYPE
Kernel-dependent type of the event queue used for QK threads.
Definition: qk.h:56
void QF_deleteRef_(void const *const evtRef)
Internal QF implementation of deleting event reference.
Definition: qf_dyn.c:319
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:187
int int_t
typedef for assertions-ids and line numbers in assertions.
Definition: qassert.h:86
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:163
Active Object (based on QHsm implementation)
Definition: qf.h:114
bool QActive_recall(QActive *const me, QEQueue *const eq)
Recall a deferred event from a given event queue eq.
Definition: qf_defer.c:118
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
bool QTimeEvt_rearm(QTimeEvt *const me, QTimeEvtCtr const nTicks)
Rearm a time event.
Definition: qf_time.c:431
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
QTimeEvtCtr volatile ctr
the internal down-counter of the time event.
Definition: qf.h:458
#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
QEvt super
Definition: qf.h:443
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:207
void QF_init(void)
QF initialization.
Definition: qutest.c:55
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:396