QP/C  6.0.0
qf.h File Reference

QF/C platform-independent public interface. More...

#include "qpset.h"

Go to the source code of this file.

Data Structures

struct  QActive
 Active Object (based on QHsm implementation) More...
 
struct  QActiveVtbl
 Virtual table for the QActive class. More...
 
struct  QTimeEvt
 Time Event structure. More...
 

Macros

#define QF_EVENT_SIZ_SIZE   2
 Default value of the macro configurable value in qf_port.h.
 
#define QF_MAX_EPOOL   3
 Default value of the macro configurable value in qf_port.h.
 
#define QF_MAX_TICK_RATE   1
 Default value of the macro configurable value in qf_port.h.
 
#define QF_TIMEEVT_CTR_SIZE   2
 macro to override the default QTimeEvtCtr size. More...
 
#define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, param_)
 Polymorphically start an active object. More...
 
#define QACTIVE_POST(me_, e_, sender_)
 Polymorphically posts an event to an active object (FIFO) with delivery guarantee. More...
 
#define QACTIVE_POST_X(me_, e_, margin_, sender_)
 Polymorphically posts an event to an active object (FIFO) without delivery guarantee. More...
 
#define QACTIVE_POST_LIFO(me_, e_)   ((*((QActiveVtbl const *)((me_)->super.vptr))->postLIFO)((me_), (e_)))
 Polymorphically posts an event to an active object using the Last-In-First-Out (LIFO) policy. More...
 
#define QF_PUBLISH(e_, sender_)   (QF_publish_((e_), (void const *)(sender_)))
 Invoke the event publishing facility QF_publish_(). More...
 
#define QF_TICK_X(tickRate_, sender_)   (QF_tickX_((tickRate_), (sender_)))
 Invoke the system clock tick processing QF_tickX_(). More...
 
#define QF_NO_MARGIN   ((uint_fast16_t)0xFFFF)
 special value of margin that causes asserting failure in case event allocation or event posting fails
 
#define QF_TICK(sender_)   QF_TICK_X((uint_fast8_t)0, (sender_))
 Invoke the system clock tick processing for rate 0.
 
#define Q_NEW(evtT_, sig_)
 Allocate a dynamic event. More...
 
#define Q_NEW_X(e_, evtT_, margin_, sig_)
 Allocate a dynamic event (non-asserting version). More...
 
#define Q_NEW_REF(evtRef_, evtT_)   ((evtRef_) = (evtT_ const *)QF_newRef_(e, &(evtRef_)->super))
 Create a new reference of the current event e More...
 
#define Q_DELETE_REF(evtRef_)
 Delete the event reference. More...
 
#define QF_CRIT_EXIT_NOP()   ((void)0)
 No-operation for exiting a critical section. More...
 
#define QF_getVersion()   (QP_versionStr)
 get the current QF version number string of the form "X.Y.Z"
 

Typedefs

typedef uint16_t QEvtSize
 The data type to store the block-size defined based on the macro QF_EVENT_SIZ_SIZE. More...
 
typedef QActive QMActive
 QMActive active object (based on QMsm implementation) More...
 
typedef QActiveVtbl QMActiveVtbl
 Virtual Table for the QMActive class (inherited from QActiveVtbl. More...
 
typedef uint16_t QTimeEvtCtr
 type of the Time Event counter, which determines the dynamic range of the time delays measured in clock ticks. More...
 
typedef QPSet QSubscrList
 Subscriber-List structure. More...
 
typedef QActive QTicker
 QTicker Active Object class. More...
 

Functions

void QActive_ctor (QActive *const me, QStateHandler initial)
 protected "constructor" of an QActive active object More...
 
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. More...
 
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. More...
 
void QActive_postLIFO_ (QActive *const me, QEvt const *const e)
 Implementation of the active object post LIFO operation. More...
 
void QActive_stop (QActive *const me)
 Stops execution of an active object and removes it from the framework's supervision. More...
 
void QActive_subscribe (QActive const *const me, enum_t const sig)
 Subscribes for delivery of signal sig to the active object me. More...
 
void QActive_unsubscribe (QActive const *const me, enum_t const sig)
 Un-subscribes from the delivery of signal sig to the AO me. More...
 
void QActive_unsubscribeAll (QActive const *const me)
 Un-subscribes from the delivery of all signals to the AO me. More...
 
bool QActive_defer (QActive const *const me, QEQueue *const eq, QEvt const *const e)
 Defer an event e to a given event queue eq. More...
 
bool QActive_recall (QActive *const me, QEQueue *const eq)
 Recall a deferred event from a given event queue eq. More...
 
uint_fast16_t QActive_flushDeferred (QActive const *const me, QEQueue *const eq)
 Flush the specified deferred queue eq. More...
 
QEvt const * QActive_get_ (QActive *const me)
 Get an event from the event queue of an active object. More...
 
void QMActive_ctor (QMActive *const me, QStateHandler initial)
 protected "constructor" of an QMActive active object. More...
 
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. More...
 
void QTimeEvt_armX (QTimeEvt *const me, QTimeEvtCtr const nTicks, QTimeEvtCtr const interval)
 Arm a time event (one shot or periodic) for direct event posting. More...
 
bool QTimeEvt_rearm (QTimeEvt *const me, QTimeEvtCtr const nTicks)
 Rearm a time event. More...
 
bool QTimeEvt_disarm (QTimeEvt *const me)
 Disarm a time event. More...
 
QTimeEvtCtr QTimeEvt_ctr (QTimeEvt const *const me)
 Get the current value of the down-counter of a time event. More...
 
void QF_init (void)
 QF initialization. More...
 
void QF_psInit (QSubscrList *const subscrSto, enum_t const maxSignal)
 Publish-subscribe initialization. More...
 
void QF_poolInit (void *const poolSto, uint_fast32_t const poolSize, uint_fast16_t const evtSize)
 Event pool initialization for dynamic allocation of events. More...
 
uint_fast16_t QF_poolGetMaxBlockSize (void)
 Obtain the block size of any registered event pools. More...
 
int_t QF_run (void)
 Transfers control to QF to run the application. More...
 
void QF_stop (void)
 Function invoked by the application layer to stop the QF application and return control to the OS/Kernel. More...
 
void QF_onStartup (void)
 Startup QF callback. More...
 
void QF_onCleanup (void)
 Cleanup QF callback. More...
 
void QF_publish_ (QEvt const *const e, void const *const sender)
 Publish event to the framework. More...
 
void QF_tickX_ (uint_fast8_t const tickRate, void const *const sender)
 Processes all armed time events at every clock tick. More...
 
bool QF_noTimeEvtsActiveX (uint_fast8_t const tickRate)
 Returns 'true' if there are no armed time events at a given tick rate. More...
 
void QF_add_ (QActive *const a)
 Register an active object to be managed by the framework. More...
 
void QF_remove_ (QActive *const a)
 Remove the active object from the framework. More...
 
uint_fast16_t QF_getPoolMin (uint_fast8_t const poolId)
 Obtain the minimum of free entries of the given event pool. More...
 
uint_fast16_t QF_getQueueMin (uint_fast8_t const prio)
 This function returns the minimum of free entries of the given event queue. More...
 
QEvtQF_newX_ (uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)
 Internal QF implementation of the dynamic event allocator. More...
 
QEvt const * QF_newRef_ (QEvt const *const e, QEvt const *const evtRef)
 Internal QF implementation of the event reference creator. More...
 
void QF_gc (QEvt const *const e)
 Recycle a dynamic event. More...
 
void QF_bzero (void *const start, uint_fast16_t len)
 Clear a specified region of memory to zero. More...
 
void QTicker_ctor (QTicker *const me, uint8_t tickRate)
 Constructor of the QTicker Active Object class. More...
 

Variables

QActiveQF_active_ [QF_MAX_ACTIVE+1]
 array of registered active objects More...
 

Detailed Description

QF/C platform-independent public interface.

Definition in file qf.h.


Data Structure Documentation

◆ QActive

struct QActive

Active Object (based on QHsm implementation)

Description
Active objects in QP are encapsulated state machines (each embedding an event queue and a thread) that communicate with one another asynchronously by sending and receiving events. Within an active object, events are processed sequentially in a run-to-completion (RTC) fashion, while QF encapsulates all the details of thread-safe event exchange and queuing.

QActive represents an active object that uses the QHsm-style implementation strategy for state machines. This strategy is tailored to manual coding, but it is also supported by the QM modeling tool. The resulting code is slower than in the QMsm style implementation strategy.
Usage
The following example illustrates how to derive an active object from QActive. Please note that the QActive member super is defined as the first member of the derived struct (see Object Orientation).
typedef struct {
QActive super; /* inherits QActive */
QTimeEvt timeEvt; /* to timeout thining or eating */
uint8_t num; /* this philosopher's number */
} Philo;

Definition at line 110 of file qf.h.

Data Fields
QHsm super inherits QHsm
uint_fast8_t prio QF priority (1..QF_MAX_ACTIVE) of this active object.

◆ QTimeEvt

struct QTimeEvt

Time Event structure.

Description
Time events are special QF events equipped with the notion of time passage. The basic usage model of the time events is as follows. An active object allocates one or more QTimeEvt objects (provides the storage for them). When the active object needs to arrange for a timeout, it arms one of its time events to fire either just once (one-shot) or periodically. Each time event times out independently from the others, so a QF application can make multiple parallel timeout requests (from the same or different active objects). When QF detects that the appropriate moment has arrived, it inserts the time event directly into the recipient's event queue. The recipient then processes the time event just like any other event.

Time events, as any other QF events derive from the QEvt base structure. Typically, you will use a time event as-is, but you can also further derive more specialized time events from it by adding some more data members and/or specialized functions that operate on the specialized time events.

Internally, the armed time events are organized into linked lists–one list for every supported ticking rate. These linked lists are scanned in every invocation of the QF_tickX_() function. Only armed (timing out) time events are in the list, so only armed time events consume CPU cycles.

See also
QTimeEvt for the description of the data members
Object Orientation
Note
QF manages the time events in the function QF_tickX_(), which must be called periodically, from the clock tick ISR or from the special QTicker active object.
Even though QTimeEvt is a subclass of QEvt, QTimeEvt instances can NOT be allocated dynamically from event pools. In other words, it is illegal to allocate QTimeEvt instances with the Q_NEW() or Q_NEW_X() macros.

Definition at line 453 of file qf.h.

Data Fields
QEvt super
struct QTimeEvt *volatile next link to the next time event in the list
void *volatile act the active object that receives the time events
QTimeEvtCtr volatile ctr the internal down-counter of the time event.
Description
The down-counter is decremented by 1 in every QF_tickX_() invocation. The time event fires (gets posted or published) when the down-counter reaches zero.
QTimeEvtCtr interval the interval for periodic time event (zero for one-shot time event)
Description
The value of the interval is re-loaded to the internal down-counter when the time event expires, so that the time event keeps timing out periodically.

Macro Definition Documentation

◆ QF_TIMEEVT_CTR_SIZE

#define QF_TIMEEVT_CTR_SIZE   2

macro to override the default QTimeEvtCtr size.

Valid values: 1, 2, or 4; default 2

Definition at line 82 of file qf.h.

◆ QACTIVE_START

#define QACTIVE_START (   me_,
  prio_,
  qSto_,
  qLen_,
  stkSto_,
  stkLen_,
  param_ 
)
Value:
((*((QActiveVtbl const *)((me_)->super.vptr))->start)( \
(me_), (prio_), (qSto_), (qLen_), (stkSto_), (stkLen_), (param_)))
Virtual table for the QActive class.
Definition: qf.h:166

Polymorphically start an active object.

Description
Starts execution of the AO and registers the AO with the framework.
Parameters
[in,out]me_pointer (see Object Orientation)
[in]prio_priority at which to start the active object
[in]qSto_pointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLen_length of the event queue (in events)
[in]stkSto_pointer to the stack storage (used only when per-AO stack is needed)
[in]stkSize_stack size (in bytes)
[in]param_pointer to the additional port-specific parameter(s) (might be NULL).
Usage
int main() {
static Philo l_philo[N]; /* N Philo active objects */
static QEvt const *l_philQueueSto[N][N]; /* storage for event queues */
static int l_philoStk[N][256]; /* stacks for the Philo active objects */
. . .
for (n = 0; n < N; ++n) {
TableEvt ie; /* initialization event for the Philo SM */
ie.philNum = n;
Philo_ctor(&l_philo[n]);
QACTIVE_START((QActive *)&l_philo[n], /* Philo pointer */
(uint_fast8_t)(n*10 + 1), /* priority */
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]), /* queue */
l_philoStk[n], sizeof(l_philoStk[n]), /* per AO stack */
&ie.super); /* initialization event */
}
. . .
}

Definition at line 211 of file qf.h.

◆ QACTIVE_POST

#define QACTIVE_POST (   me_,
  e_,
  sender_ 
)
Value:
((void)(*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
(e_), QF_NO_MARGIN, (sender_)))
Virtual table for the QActive class.
Definition: qf.h:166
#define QF_NO_MARGIN
special value of margin that causes asserting failure in case event allocation or event posting fails...
Definition: qf.h:645

Polymorphically posts an event to an active object (FIFO) with delivery guarantee.

Description
This macro asserts if the queue overflows and cannot accept the event.
Parameters
[in,out]me_pointer (see Object Orientation)
[in]e_pointer to the event to post
[in]sender_pointer to the sender object.
Note
The sendedr_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disenabled, the QACTIVE_POST() macro does not pass the sender_ argument, so the overhead of passing this extra argument is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, if QACTIVE_POST() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.
See also
QACTIVE_POST_X, QActive_post_().

Definition at line 252 of file qf.h.

◆ QACTIVE_POST_X

#define QACTIVE_POST_X (   me_,
  e_,
  margin_,
  sender_ 
)
Value:
((*((QActiveVtbl const *)((me_)->super.vptr))->post)((me_), \
(e_), (margin_), (sender_)))
Virtual table for the QActive class.
Definition: qf.h:166

Polymorphically posts an event to an active object (FIFO) without delivery guarantee.

Description
This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.
Parameters
[in,out]me_pointer (see Object Orientation)
[in]e_pointer to the event to post
[in]margin_the minimum free slots in the queue, which must still be available after posting the event. The special value QF_NO_MARGIN causes asserting failure in case event allocation fails.
[in]sender_pointer to the sender object.
Returns
'true' if the posting succeeded, and 'false' if the posting failed due to insufficient margin of free slots available in the queue.
Note
The sender_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the QACTIVE_POST() macro does not pass the sender_ argument, so the overhead of passing this extra argument is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, if QACTIVE_POST_X() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.
Usage
extern QActive *AO_Table;
. . .
/* typically inside a state machine action */
TableEvt *pe;
Q_NEW_X(pe, TableEvt, 5U, HUNGRY_SIG); /* dynamic alloc, margin==5 */
if (pe != (TableEvt *)0) {
pe->philNum = me->num;
QACTIVE_POST_X(AO_Table, &pe->super, 3U, me); /* margin==3 */
}
. . .

Definition at line 290 of file qf.h.

◆ QACTIVE_POST_LIFO

#define QACTIVE_POST_LIFO (   me_,
  e_ 
)    ((*((QActiveVtbl const *)((me_)->super.vptr))->postLIFO)((me_), (e_)))

Polymorphically posts an event to an active object using the Last-In-First-Out (LIFO) policy.

Parameters
[in,out]me_pointer (see Object Orientation)
[in]e_pointer to the event to post

Definition at line 317 of file qf.h.

◆ QF_PUBLISH

#define QF_PUBLISH (   e_,
  sender_ 
)    (QF_publish_((e_), (void const *)(sender_)))

Invoke the event publishing facility QF_publish_().

Description
This macro is the recommended way of publishing events, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.
Parameters
[in]e_pointer to the posted event
[in]sender_pointer to the sender object. This argument is actually only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the macro calls QF_publish_() without the sender_ parameter, so the overhead of passing this extra argument is entirely avoided.
Note
the pointer to the sender object is not necessarily a pointer to an active object. In fact, if QF_PUBLISH() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the publisher of the event.
See also
QF_publish_().

Definition at line 590 of file qf.h.

◆ QF_TICK_X

#define QF_TICK_X (   tickRate_,
  sender_ 
)    (QF_tickX_((tickRate_), (sender_)))

Invoke the system clock tick processing QF_tickX_().

Description
This macro is the recommended way of invoking clock tick processing, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.
Parameters
[in]tickRateclock tick rate to be serviced through this call
[in]senderpointer to the sender object. This argument is actually only used when QS software tracing is enabled (macro Q_SPY is defined)
Note
When QS software tracing is disabled, the macro calls QF_tickX_() without the sender parameter, so the overhead of passing this extra argument is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, when QF_TICK_X() is called from an interrupt, you would create a unique object just to unambiguously identify the ISR as the sender of the time events.
Usage
The following example shows how to invoke QF_TICK_X() for different system tick rates:
/* case 1: Interrupt Controller available,
* "unconditional interrupt unlocking" critical section policy
* (nesting of critical sections _not_ allowed)
*/
interrupt void ISR_timer() { /* entered with interrupts disabled in hardware */
QF_INT_ENABLE(); /* enable interrupts */
QF_TICK_X(0U, &l_ISR_timer); /*<-- QF tick processing for rate 0 */
QF_INT_DISABLE(); /* disable interrupts again */
/* send the EOI instruction to the Interrupt Controller */
}
/* case 2: Interrupt Controller not used,
* "saving and restoring interrupt status" critical section policy
* (nesting of critical sections allowed)
*/
interrupt void ISR_timer() {
QF_TICK_X(1U, &l_ISR_timer); /*<-- QF tick processing for rate 1 */
}
See also
QF_tickX_().

Definition at line 633 of file qf.h.

◆ Q_NEW

#define Q_NEW (   evtT_,
  sig_ 
)
Value:
((evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), \
QF_NO_MARGIN, (sig_)))
unsigned int uint_fast16_t
fast at-least 16-bit unsigned int
Definition: stdint.h:37
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
#define QF_NO_MARGIN
special value of margin that causes asserting failure in case event allocation or event posting fails...
Definition: qf.h:645

Allocate a dynamic event.

Description
The macro calls the internal QF function QF_newX_() with margin == QF_NO_MARGIN, which causes an assertion when the event cannot be successfully allocated.
Parameters
[in]evtT_event type (class name) of the event to allocate
[in]sig_signal to assign to the newly allocated event
Returns
a valid event pointer cast to the type evtT_.
Note
If #Q_EVT_CTOR is defined, the Q_NEW() macro becomes variadic and takes all the arguments needed by the constructor of the event class being allocated. The constructor is then called by means of the placement-new operator.
Usage
The following example illustrates dynamic allocation of an event:
extern QActive *AO_Table;
QState Philoso_hungry(Philo * const me, QEvt const * const e) {
QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
TableEvt *pe = Q_NEW(TableEvt, HUNGRY_SIG); /* dynamic alloc */
pe->philNum = me->num;
QACTIVE_POST(AO_Table, &pe->super, me); /* direct posting */
status = Q_HANDLED();
break;
}
. . .
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}

Definition at line 711 of file qf.h.

◆ Q_NEW_X

#define Q_NEW_X (   e_,
  evtT_,
  margin_,
  sig_ 
)
Value:
((e_) = \
(evtT_ *)QF_newX_((uint_fast16_t)sizeof(evtT_), (margin_), (sig_)))
unsigned int uint_fast16_t
fast at-least 16-bit unsigned int
Definition: stdint.h:37
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

Allocate a dynamic event (non-asserting version).

Description
This macro allocates a new event and sets the pointer e_, while leaving at least margin_ of events still available in the pool
Parameters
[in]evtT_event type (class name) of the event to allocate
[in]margin_number of events that must remain available in the given pool after this allocation. The special value QF_NO_MARGIN causes asserting failure in case event allocation or event posting fails.
[in]sig_signal to assign to the newly allocated event
Returns
an event pointer cast to the type evtT_ or NULL if the event cannot be allocated with the specified margin.
Note
If #Q_EVT_CTOR is defined, the Q_NEW_X() macro becomes variadic and takes all the arguments needed by the constructor of the event class being allocated. The constructor is then called and all the extra arguments are passed to it.
Usage
The following example illustrates dynamic allocation of an event:
extern QActive *AO_Table;
. . .
/* typically inside a state machine action */
TableEvt *pe;
Q_NEW_X(pe, TableEvt, 5U, HUNGRY_SIG); /* dynamic alloc, margin==5 */
if (pe != (TableEvt *)0) {
pe->philNum = me->num;
QACTIVE_POST_X(AO_Table, &pe->super, 3U, me); /* margin==3 */
}
. . .

Definition at line 741 of file qf.h.

◆ Q_NEW_REF

#define Q_NEW_REF (   evtRef_,
  evtT_ 
)    ((evtRef_) = (evtT_ const *)QF_newRef_(e, &(evtRef_)->super))

Create a new reference of the current event e

Description
The current event processed by an active object is available only for the duration of the run-to-completion (RTC) step. After that step, the current event is no longer available and the framework might recycle (garbage-collect) the event. The macro Q_NEW_REF() explicitly creates a new reference to the current event that can be stored and used beyond the current RTC step, until the reference is explicitly recycled by means of the macro Q_DELETE_REF().
Parameters
[in,out]evtRef_event reference to create
[in]evtT_event type (class name) of the event reference
Usage
The example defer in the directory examples/win32/defer illustrates the use of Q_NEW_REF()
See also
Q_DELETE_REF()

Definition at line 766 of file qf.h.

◆ Q_DELETE_REF

#define Q_DELETE_REF (   evtRef_)
Value:
do { \
QF_gc(&(evtRef_)->super); \
(evtRef_) = (void *)0; \
} while (0)

Delete the event reference.

Description
Every event reference created with the macro Q_NEW_REF() needs to be eventually deleted by means of the macro Q_DELETE_REF() to avoid leaking the event.
Parameters
[in,out]evtRef_event reference to delete
Usage
The example defer in the directory examples/win32/defer illustrates the use of Q_DELETE_REF()
See also
Q_NEW_REF()

Definition at line 784 of file qf.h.

◆ QF_CRIT_EXIT_NOP

#define QF_CRIT_EXIT_NOP ( )    ((void)0)

No-operation for exiting a critical section.

Description
In some QF ports the critical section exit takes effect only on the next machine instruction. If this next instruction is another entry to a critical section, the critical section won't be really exited, but rather the two adjacent critical sections would be merged. The QF_CRIT_EXIT_NOP() macro contains minimal code required to prevent such merging of critical sections in QF ports, in which it can occur.

Definition at line 807 of file qf.h.

Typedef Documentation

◆ QEvtSize

typedef uint16_t QEvtSize

The data type to store the block-size defined based on the macro QF_EVENT_SIZ_SIZE.

The dynamic range of this data type determines the maximum block size that can be managed by the pool.

Definition at line 61 of file qf.h.

◆ QMActive

typedef QActive QMActive

QMActive active object (based on QMsm implementation)

Description
QMActive represents an active object that uses the QMsm style state machine implementation strategy. This strategy requires the use of the QM modeling tool to generate state machine code automatically, but the code is faster than in the QHsm style implementation strategy and needs less run-time support (smaller event-processor).
Note
QMActive is not intended to be instantiated directly, but rather serves as the base class for derivation of active objects in the application.
QMActive inherits QActive exactly, without adding any new attributes (or operations) and therefore, QMActive is typedef'ed as QActive. QMActive is not intended to be instantiated directly, but rather serves as the base class for derivation of active objects in the application.
See also
QActive
Usage
The following example illustrates how to derive an active object from QMActive. Please note that the QActive member super is defined as the first member of the derived struct (see Object Orientation).
typedef struct {
QMActive super; /* inherits QMActive */
QTimeEvt timeEvt; /* to timeout thining or eating */
uint8_t num; /* this philosopher's number */
} Philo;

Definition at line 380 of file qf.h.

◆ QMActiveVtbl

Virtual Table for the QMActive class (inherited from QActiveVtbl.

Note
QMActive inherits QActive exactly, without adding any new virtual functions and therefore, QMActiveVtbl is typedef'ed as QActiveVtbl.

Definition at line 388 of file qf.h.

◆ QTimeEvtCtr

type of the Time Event counter, which determines the dynamic range of the time delays measured in clock ticks.

Description
This typedef is configurable via the preprocessor switch QF_TIMEEVT_CTR_SIZE. The other possible values of this type are as follows:
uint8_t when (QF_TIMEEVT_CTR_SIZE == 1), and
uint32_t when (QF_TIMEEVT_CTR_SIZE == 4).

Definition at line 409 of file qf.h.

◆ QSubscrList

typedef QPSet QSubscrList

Subscriber-List structure.

Description
This data type represents a set of active objects that subscribe to a given signal. The set is represented as a priority-set, where each bit corresponds to the unique priority of an active object.
See also
QSubscrList for the description of the data members

Definition at line 513 of file qf.h.

◆ QTicker

typedef QActive QTicker

QTicker Active Object class.

Description
The QTicker is an efficient active object specialized to process QF system clock tick at a specified tick frequency [0..QF_MAX_TICK_RATE]. Placing system clock tick processing in an active object allows you to remove the non-deterministic QF::TICK_X() processing from the interrupt level and move it into the thread-level, where you can prioritize it as low as you wish.

Definition at line 828 of file qf.h.

Function Documentation

◆ QActive_ctor()

void QActive_ctor ( QActive *const  me,
QStateHandler  initial 
)

protected "constructor" of an QActive active object

Description
Performs the first step of active object initialization by assigning the virtual pointer and calling the superclass constructor.
Parameters
[in,out]mepointer (see Object Orientation)
[in]initialpointer to the event to be dispatched to the MSM
Note
Must be called only once before QMSM_INIT().
See also
QMsm_ctor() and QHsm_ctor()

Definition at line 65 of file qf_qact.c.

◆ QActive_start_()

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.

Description
Starts execution of the AO and registers the AO with the framework. Also takes the top-most initial transition in the AO's state machine. This initial transition is taken in the callee's thread of execution.
Parameters
[in,out]mepointer (see Object Orientation)
[in]priopriority at which to start the active object
[in]qStopointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLenlength of the event queue [events]
[in]stkStopointer to the stack storage (must be NULL in QK)
[in]stkSizestack size [bytes]
[in]iepointer to the initial event (might be NULL).
Note
This function should be called via the macro QACTIVE_START().
Usage
The following example shows starting an AO when a per-task stack is needed:
int main() {
static Philo l_philo[N]; /* N Philo active objects */
static QEvt const *l_philQueueSto[N][N]; /* storage for event queues */
static int l_philoStk[N][256]; /* stacks for the Philo active objects */
. . .
for (n = 0; n < N; ++n) {
TableEvt ie; /* initialization event for the Philo SM */
ie.philNum = n;
Philo_ctor(&l_philo[n]);
QACTIVE_START((QActive *)&l_philo[n], /* Philo pointer */
(uint_fast8_t)(n*10 + 1), /* priority */
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]), /* queue */
l_philoStk[n], sizeof(l_philoStk[n]), /* per AO stack */
&ie.super); /* initialization event */
}
. . .
}
Description
Starts execution of the AO and registers the AO with the framework. Also takes the top-most initial transition in the AO's state machine. This initial transition is taken in the callee's thread of execution.
Parameters
[in,out]mepointer (see Object Orientation)
[in]priopriority at which to start the active object
[in]qStopointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLenlength of the event queue [events]
[in]stkStopointer to the stack storage (must be NULL in QV)
[in]stkSizestack size [bytes]
[in]iepointer to the initial event (might be NULL).
Note
This function should be called via the macro QACTIVE_START().
Usage
The following example shows starting an AO when a per-task stack is needed:
int main() {
static Philo l_philo[N]; /* N Philo active objects */
static QEvt const *l_philQueueSto[N][N]; /* storage for event queues */
static int l_philoStk[N][256]; /* stacks for the Philo active objects */
. . .
for (n = 0; n < N; ++n) {
TableEvt ie; /* initialization event for the Philo SM */
ie.philNum = n;
Philo_ctor(&l_philo[n]);
QACTIVE_START((QActive *)&l_philo[n], /* Philo pointer */
(uint_fast8_t)(n*10 + 1), /* priority */
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]), /* queue */
l_philoStk[n], sizeof(l_philoStk[n]), /* per AO stack */
&ie.super); /* initialization event */
}
. . .
}
Description
Starts execution of the AO and registers the AO with the framework. Also takes the top-most initial transition in the AO's state machine. This initial transition is taken in the callee's thread of execution.
Parameters
[in,out]mepointer (see Object Orientation)
[in]priopriority at which to start the active object
[in]qStopointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLenlength of the event queue [events]
[in]stkStopointer to the stack storage (used only when per-AO stack is needed)
[in]stkSizestack size [bytes]
[in]iepointer to the initial event (might be NULL).
Note
This function should be called via the macro QACTIVE_START().
Usage
The following example shows starting an AO when a per-task stack is needed:
int main() {
static Philo l_philo[N]; /* N Philo active objects */
static QEvt const *l_philQueueSto[N][N]; /* storage for event queues */
static int l_philoStk[N][256]; /* stacks for the Philo active objects */
. . .
for (n = 0; n < N; ++n) {
TableEvt ie; /* initialization event for the Philo SM */
ie.philNum = n;
Philo_ctor(&l_philo[n]);
QACTIVE_START((QActive *)&l_philo[n], /* Philo pointer */
(uint_fast8_t)(n*10 + 1), /* priority */
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]), /* queue */
l_philoStk[n], sizeof(l_philoStk[n]), /* per AO stack */
&ie.super); /* initialization event */
}
. . .
}
Precondition
AO cannot be started from an ISR, the priority must be in range and the stack storage must not be provided, because the QK kernel does not need per-AO stacks.
The priority must be in range and the stack storage must not be provided, because the QV kernel does not need per-AO stacks.
AO cannot be started:
  • from an ISR;
  • the priority must be in range;
  • the stack storage must NOT be provided (because the QK kernel does not need per-AO stacks).

Definition at line 162 of file qk.c.

◆ QActive_post_()

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.

Description
Direct event posting is the simplest asynchronous communication method available in QF.
Parameters
[in,out]mepointer (see Object Orientation)
[in]epointer to the event to be posted
[in]marginnumber of required free slots in the queue after posting the event. The special value QF_NO_MARGIN means that this function will assert if posting fails.
Returns
'true' (success) if the posting succeeded (with the provided margin) and 'false' (failure) when the posting fails.
Attention
This function should be called only via the macro QACTIVE_POST() or QACTIVE_POST_X().
Note
The QF_NO_MARGIN value of the margin parameter is special and denotes situation when the post() operation is assumed to succeed (event delivery guarantee). An assertion fires, when the event cannot be delivered in this case.
Usage
extern QActive *AO_Table;
QState Philoso_hungry(Philo * const me, QEvt const * const e) {
QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
TableEvt *pe = Q_NEW(TableEvt, HUNGRY_SIG); /* dynamic alloc */
pe->philNum = me->num;
QACTIVE_POST(AO_Table, &pe->super, me); /* direct posting */
status = Q_HANDLED();
break;
}
. . .
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}
See also
QActive_post_(), QActive_postLIFO()
Precondition
event pointer must be valid
event pointer must be valid
Note
assert if event cannot be posted while dropping events is not acceptable

Definition at line 93 of file qf_actq.c.

◆ QActive_postLIFO_()

void QActive_postLIFO_ ( QActive *const  me,
QEvt const *const  e 
)

Implementation of the active object post LIFO operation.

Description
posts an event to the event queue of the active object me using the Last-In-First-Out (LIFO) policy.
Note
The LIFO policy should be used only for self-posting and with caution, because it alters order of events in the queue.
Parameters
[in]mepointer (see Object Orientation)

Definition at line 199 of file qf_actq.c.

◆ QActive_stop()

void QActive_stop ( QActive *const  me)

Stops execution of an active object and removes it from the framework's supervision.

Description
This function must be called from within the AO that needs to stop. In other words, an AO should stop itself rather than being stopped by someone else. This policy works best, because only the AO itself "knows" when it has reached the appropriate state for the shutdown.
Note
By the time the AO calls QActive_stop(), it should have unsubscribed from all events and no more events should be directly-posted to it.
Precondition
QActive_stop() must be called from the AO that wants to stop.
QActive_stop() must be called from the AO that wants to stop.

Definition at line 207 of file qk.c.

◆ QActive_subscribe()

void QActive_subscribe ( QActive const *const  me,
enum_t const  sig 
)

Subscribes for delivery of signal sig to the active object me.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Subscribing to an event means that the framework will start posting all published events with a given signal sig to the event queue of the active object me.
Parameters
[in,out]mepointer (see Object Orientation)
[in]sigevent signal to subscribe
Usage
The following example shows how the Table active object subscribes to three signals in the initial transition:
QState Table_initial(Table * const me, QEvt const * const e) {
(void)e; /* suppress the compiler warning */
QActive_subscribe(&me->super, HUNGRY_SIG); /* subscribe to HUNGRY */
QActive_subscribe(&me->super, DONE_SIG); /*... to DONE */
QActive_subscribe(&me->super, TERMINATE_SIG); /*...and to TERMINATE */
for (n = 0; n < N; ++n) {
me->fork[n] = FREE;
me->isHungry[n] = 0;
}
return Q_TRAN(&Table_serving);
}
See also
QF_publish_(), QActive_unsubscribe(), and QActive_unsubscribeAll()

Definition at line 205 of file qf_ps.c.

◆ 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.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from an event means that the framework will stop posting published events with a given signal sig to the event queue of the active object me.
Parameters
[in]mepointer (see Object Orientation)
[in]sigevent signal to unsubscribe
Note
Due to the latency of event queues, an active object should NOT assume that a given signal sig will never be dispatched to the state machine of the active object after un-subscribing from that signal. The event might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events.
Un-subscribing from a signal that has never been subscribed in the first place is considered an error and QF will raise an assertion.
See also
QF_publish_(), QActive_subscribe(), and QActive_unsubscribeAll()
Precondition
the singal and the prioriy must be in ragne, the AO must also be registered with the framework

Definition at line 250 of file qf_ps.c.

◆ QActive_unsubscribeAll()

void QActive_unsubscribeAll ( QActive const *const  me)

Un-subscribes from the delivery of all signals to the AO me.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from all events means that the framework will stop posting any published events to the event queue of the active object me.
Parameters
[in]mepointer (see Object Orientation)
Note
Due to the latency of event queues, an active object should NOT assume that no events will ever be dispatched to the state machine of the active object after un-subscribing from all events. The events might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events. Also, the alternative event-delivery mechanisms, such as direct event posting or time events, can be still delivered to the event queue of the active object.
See also
QF_publish_(), QActive_subscribe(), and QActive_unsubscribe()

Definition at line 297 of file qf_ps.c.

◆ 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.

Description
This function is part of the event deferral support. An active object uses this function to defer an event e to the QF-supported native event queue eq. QF correctly accounts for another outstanding reference to the event and will not recycle the event at the end of the RTC step. Later, the active object might recall one event at a time from the event queue.
Parameters
[in,out]mepointer (see Object Orientation)
[in]eqpointer to a "raw" thread-safe queue to recall an event from.
[in]epointer to the event to be deferred
Returns
'true' (success) when the event could be deferred and 'false' (failure) if event deferral failed due to overflowing the queue.

An active object can use multiple event queues to defer events of different kinds.

See also
QActive_recall(), QEQueue, QActive_flushDeferred()

Definition at line 75 of file qf_defer.c.

◆ QActive_recall()

bool QActive_recall ( QActive *const  me,
QEQueue *const  eq 
)

Recall a deferred event from a given event queue eq.

Description
This function is part of the event deferral support. An active object uses this function to recall a deferred event from a given QF event queue. Recalling an event means that it is removed from the deferred event queue eq and posted (LIFO) to the event queue of the active object.
Parameters
[in,out]mepointer (see Object Orientation)
[in]eqpointer to a "raw" thread-safe queue to recall an event from.
Returns
'true' if an event has been recalled and 'false' if not.
Note
An active object can use multiple event queues to defer events of different kinds.
See also
QActive_recall(), QEQueue, QActive_postLIFO_()

Definition at line 103 of file qf_defer.c.

◆ QActive_flushDeferred()

uint_fast16_t QActive_flushDeferred ( QActive const *const  me,
QEQueue *const  eq 
)

Flush the specified deferred queue eq.

Description
This function is part of the event deferral support. An active object can use this function to flush a given QF event queue. The function makes sure that the events are not leaked.
Parameters
[in,out]mepointer (see Object Orientation)
[in]eqpointer to a "raw" thread-safe queue to flush.
Returns
the number of events actually flushed from the queue.
See also
QActive_defer(), QActive_recall(), QEQueue

Definition at line 154 of file qf_defer.c.

◆ QActive_get_()

QEvt const* QActive_get_ ( QActive *const  me)

Get an event from the event queue of an active object.

Description
The behavior of this function depends on the kernel/OS used in the QF port. For built-in kernels (QV or QK) the function can be called only when the queue is not empty, so it doesn't block. For a blocking kernel/OS the function can block and wait for delivery of an event.
Parameters
[in,out]mepointer (see Object Orientation)
Returns
a pointer to the received event. The returned pointer is guaranteed to be valid (can't be NULL).
Note
This function is used internally by a QF port to extract events from the event queue of an active object. This function depends on the event queue implementation and is sometimes customized in the QF port (file qf_port.h). Depending on the definition of the macro QACTIVE_EQUEUE_WAIT_(), the function might block the calling thread when no events are available.

Definition at line 272 of file qf_actq.c.

◆ QMActive_ctor()

void QMActive_ctor ( QMActive *const  me,
QStateHandler  initial 
)

protected "constructor" of an QMActive active object.

Description
Performs the first step of active object initialization by assigning the virtual pointer and calling the superclass constructor.
Parameters
[in,out]mepointer (see Object Orientation)
[in]initialpointer to the event to be dispatched to the MSM
Note
Must be called only ONCE before QMSM_INIT().
See also
QHsm_ctor() and QFsm_ctor()
Note
QMActive inherits QActive, so by the Object Orientation convention it should call the constructor of the superclass, i.e., QActive_ctor(). However, this would pull in the QActiveVtbl, which in turn will pull in the code for QHsm_init_() and QHsm_dispatch_() implemetations, which is expensive. To avoid this code size penalty, in case QHsm is not used in a given project, the call to QMsm_ctor() avoids pulling in the code for QHsm.

Definition at line 67 of file qf_qmact.c.

◆ 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.

Description
When creating a time event, you must commit it to a specific active object act, tick rate tickRate and event signal sig. You cannot change these attributes later.
Parameters
[in,out]mepointer (see Object Orientation)
[in]actpointer to the active object associated with this time event. The time event will post itself to this AO.
[in]sigsignal to associate with this time event.
[in]tickRatesystem tick rate to associate with this time event.
Note
You should call the constructor exactly once for every Time Event object before arming the Time Event. The ideal place for initializing the time event(s) associated with a given AO is the AO's constructor.
Precondition
The signal must be valid and the tick rate in range
The signal must be valid and the tick rate in range

Definition at line 232 of file qf_time.c.

◆ 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.

Description
Arms a time event to fire in a specified number of clock ticks and with a specified interval. If the interval is zero, the time event is armed for one shot ('one-shot' time event). The time event gets directly posted (using the FIFO policy) into the event queue of the host active object.
Parameters
[in,out]mepointer (see Object Orientation)
[in]nTicksnumber of clock ticks (at the associated rate) to rearm the time event with.
[in]intervalinterval (in clock ticks) for periodic time event.
Note
After posting, a one-shot time event gets automatically disarmed while a periodic time event (interval != 0) is automatically re-armed.
A time event can be disarmed at any time by calling the QTimeEvt_disarm() function. Also, a time event can be re-armed to fire in a different number of clock ticks by calling the QTimeEvt_rearm() function.
Usage
The following example shows how to arm a one-shot time event from a state machine of an active object:
QState Philo_eating(Philo * const me, QEvt const * const e) {
QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
QTimeEvt_armX(&me->timeEvt, EAT_TIME, 0U); /* one shot */
status = Q_HANDLED();
break;
}
case Q_EXIT_SIG: {
TableEvt *pe;
QTimeEvt_disarm(&me->timeEvt);
pe = Q_NEW(TableEvt, DONE_SIG);
pe->philNum = me->num;
QF_PUBLISH((QEvt *)pe, me);
status = Q_HANDLED();
break;
}
case TIMEOUT_SIG: {
status = Q_TRAN(&Philosopher_thinking);
break;
}
default: {
status = Q_SUPER(&QHsm_top);
break;
}
}
return status;
}
Precondition
the host AO must be valid, time evnet must be disarmed, number of clock ticks cannot be zero, and the signal must be valid.
the host AO must be valid, time evnet must be disarmed, number of clock ticks cannot be zero, and the signal must be valid.

Definition at line 292 of file qf_time.c.

◆ QTimeEvt_rearm()

bool QTimeEvt_rearm ( QTimeEvt *const  me,
QTimeEvtCtr const  nTicks 
)

Rearm a time event.

Description
Rearms a time event with a new number of clock ticks. This function can be used to adjust the current period of a periodic time event or to prevent a one-shot time event from expiring (e.g., a watchdog time event). Rearming a periodic timer leaves the interval unchanged and is a convenient method to adjust the phasing of a periodic time event.
Parameters
[in,out]mepointer (see Object Orientation)
[in]nTicksnumber of clock ticks (at the associated rate) to rearm the time event with.
Returns
'true' if the time event was running as it was re-armed. The 'false' return means that the time event was not truly rearmed because it was not running. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case the 'false' return means that the time event has already been posted or published and should be expected in the active object's state machine.
Precondition
AO must be valid, tick rate must be in range, nTicks must not be zero, and the signal of this time event must be valid
AO must be valid, tick rate must be in range, nTicks must not be zero, and the signal of this time event must be valid

Definition at line 421 of file qf_time.c.

◆ QTimeEvt_disarm()

bool QTimeEvt_disarm ( QTimeEvt *const  me)

Disarm a time event.

Description
Disarm the time event so it can be safely reused.
Parameters
[in,out]mepointer (see Object Orientation)
Returns
'true' if the time event was truly disarmed, that is, it was running. The return of 'false' means that the time event was not truly disarmed because it was not running. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case the 'false' return means that the time event has already been posted or published and should be expected in the active object's state machine.
Note
there is no harm in disarming an already disarmed time event

Definition at line 362 of file qf_time.c.

◆ QTimeEvt_ctr()

QTimeEvtCtr QTimeEvt_ctr ( QTimeEvt const *const  me)

Get the current value of the down-counter of a time event.

Description
Useful for checking how many clock ticks (at the tick rate associated with the time event) remain until the time event expires.
Parameters
[in,out]mepointer (see Object Orientation)
Returns
For an armed time event, the function returns the current value of the down-counter of the given time event. If the time event is not armed, the function returns 0.

/note The function is thread-safe.

Definition at line 496 of file qf_time.c.

◆ QF_init()

void QF_init ( void  )

QF initialization.

Description
Initializes QF and must be called exactly once before any other QF function. Typically, QF_init() is called from main() even before initializing the Board Support Package (BSP).
Note
QF_init() clears the internal QF variables, so that the framework can start correctly even if the startup code fails to clear the uninitialized data (as is required by the C Standard).

Definition at line 71 of file qk.c.

◆ QF_psInit()

void QF_psInit ( QSubscrList *const  subscrSto,
enum_t const  maxSignal 
)

Publish-subscribe initialization.

Description
This function initializes the publish-subscribe facilities of QF and must be called exactly once before any subscriptions/publications occur in the application.
Parameters
[in]subscrStopointer to the array of subscriber lists
[in]maxSignalthe dimension of the subscriber array and at the same time the maximum signal that can be published or subscribed.

The array of subscriber-lists is indexed by signals and provides a mapping between the signals and subscriber-lists. The subscriber-lists are bitmasks of type QSubscrList, each bit in the bit mask corresponding to the unique priority of an active object. The size of the QSubscrList bit mask depends on the value of the QF_MAX_ACTIVE macro.

Note
The publish-subscribe facilities are optional, meaning that you might choose not to use publish-subscribe. In that case calling QF_psInit() and using up memory for the subscriber-lists is unnecessary.
See also
QSubscrList
Usage
The following example shows the typical initialization sequence of QF:
int main(void) {
static QEvt const *l_tableQueueSto[N_PHILO];
static QEvt const *l_philoQueueSto[N_PHILO][N_PHILO];
static QSubscrList l_subscrSto[MAX_PUB_SIG];
/* storage for event pools... */
static QF_MPOOL_EL(TableEvt) l_smlPoolSto[2*N_PHILO]; /* small pool */
Philo_ctor(); /* instantiate all Philosopher active objects */
Table_ctor(); /* instantiate the Table active object */
QF_init(); /* initialize the framework and the underlying RT kernel */
BSP_init(); /* initialize the BSP */
/* send object dictionaries for event pools... */
QS_OBJ_DICTIONARY(l_smlPoolSto);
/* init publish-subscribe... */
QF_psInit(l_subscrSto, Q_DIM(l_subscrSto));
/* initialize event pools... */
QF_poolInit(l_smlPoolSto, sizeof(l_smlPoolSto), sizeof(l_smlPoolSto[0]));
/* start the active objects... */
for (n = 0; n < N_PHILO; ++n) {
QACTIVE_START(AO_Philo[n], (uint8_t)(n + 1),
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]),
(void *)0, 0U, (QEvt *)0);
}
QACTIVE_START(AO_Table, (uint8_t)(N_PHILO + 1),
l_tableQueueSto, Q_DIM(l_tableQueueSto),
(void *)0, 0U, (QEvt *)0);
return QF_run(); /* run the QF application, QF_run() does not return */
}

Definition at line 85 of file qf_ps.c.

◆ 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.

Description
This function initializes one event pool at a time and must be called exactly once for each event pool before the pool can be used.
Parameters
[in]poolStopointer to the storage for the event pool
[in]poolSizesize of the storage for the pool in bytes
[in]evtSizethe block-size of the pool in bytes, which determines the maximum size of events that can be allocated from the pool.
Attention
You might initialize many event pools by making many consecutive calls to the QF_poolInit() function. However, for the simplicity of the internal implementation, you must initialize event pools in the ascending order of the event size.

Many RTOSes provide fixed block-size heaps, a.k.a. memory pools that can be adapted for QF event pools. In case such support is missing, QF provides a native QF event pool implementation. The macro QF_EPOOL_TYPE_ determines the type of event pool used by a particular QF port. See structure QMPool for more information.

Note
The actual number of events available in the pool might be actually less than (poolSize / evtSize) due to the internal alignment of the blocks that the pool might perform. You can always check the capacity of the pool by calling QF_getPoolMin().
The dynamic allocation of events is optional, meaning that you might choose not to use dynamic events. In that case calling QF_poolInit() and using up memory for the memory blocks is unnecessary.
See also
QF initialization example for QF_init()
Precondition
cannot exceed the number of available memory pools
please initialize event pools in ascending order of evtSize:

Definition at line 112 of file qf_dyn.c.

◆ QF_poolGetMaxBlockSize()

uint_fast16_t QF_poolGetMaxBlockSize ( void  )

Obtain the block size of any registered event pools.

Description
Obtain the block size of any registered event pools

Definition at line 291 of file qf_dyn.c.

◆ QF_run()

int_t QF_run ( void  )

Transfers control to QF to run the application.

Description
QF_run() is typically called from your startup code after you initialize the QF and start at least one active object with QActive_start().
Returns
In QK, the QF_run() function does not return.
Description
QF_run() is typically called from main() after you initialize the QF and start at least one active object with QACTIVE_START().
Returns
In QV, the QF_run() function does not return.
Description
QF_run() is typically called from main() after you initialize the QF and start at least one active object with QACTIVE_START().
Returns
In QXK, the QF_run() function does not return.

Definition at line 125 of file qk.c.

◆ QF_stop()

void QF_stop ( void  )

Function invoked by the application layer to stop the QF application and return control to the OS/Kernel.

Description
This function stops the QF application. After calling this function, QF attempts to gracefully stop the application. This graceful shutdown might take some time to complete. The typical use of this function is for terminating the QF application to return back to the operating system or for handling fatal errors that require shutting down (and possibly re-setting) the system.
See also
QF_onCleanup()

Definition at line 100 of file qk.c.

◆ QF_onStartup()

void QF_onStartup ( void  )

Startup QF callback.

Description
The timeline for calling QF_onStartup() depends on the particular QF port. In most cases, QF_onStartup() is called from QF_run(), right before starting any multitasking kernel or the background loop.

◆ QF_onCleanup()

void QF_onCleanup ( void  )

Cleanup QF callback.

Description
QF_onCleanup() is called in some QF ports before QF returns to the underlying operating system or RTOS.

This function is strongly platform-specific and is not implemented in the QF, but either in the QF port or in the Board Support Package (BSP) for the given application. Some QF ports might not require implementing QF_onCleanup() at all, because many embedded applications don't have anything to exit to.

See also
QF_stop()

◆ QF_publish_()

void QF_publish_ ( QEvt const *const  e,
void const *const  sender 
)

Publish event to the framework.

Description
This function posts (using the FIFO policy) the event e to all active objects that have subscribed to the signal e->sig, which is called multicasting. The multicasting performed in this function is very efficient based on reference-counting inside the published event ("zero-copy" event multicasting). This function is designed to be callable from any part of the system, including ISRs, device drivers, and active objects.
Note
To avoid any unexpected re-ordering of events posted into AO queues, the event multicasting is performed with scheduler locked. However, the scheduler is locked only up to the priority level of the highest- priority subscriber, so any AOs of even higher priority, which did not subscribe to this event are not affected.
Attention
this function should be called only via the macro QF_PUBLISH()
Precondition
the published signal must be within the configured range

Definition at line 121 of file qf_ps.c.

◆ QF_tickX_()

void QF_tickX_ ( uint_fast8_t const  tickRate,
void const *const  sender 
)

Processes all armed time events at every clock tick.

Description
This function must be called periodically from a time-tick ISR or from a task so that QF can manage the timeout events assigned to the given system clock tick rate.
Parameters
[in]tickRatesystem clock tick rate serviced in this call.
Note
this function should be called only via the macro QF_TICK_X()
the calls to QF_tickX_() with different tickRate argument can preempt each other. For example, higher clock tick rates might be serviced from interrupts while others from tasks (active objects).
See also
QTimeEvt.

Definition at line 75 of file qf_time.c.

◆ QF_noTimeEvtsActiveX()

bool QF_noTimeEvtsActiveX ( uint_fast8_t const  tickRate)

Returns 'true' if there are no armed time events at a given tick rate.

Description
Find out if any time events are armed at the given clock tick rate.
Parameters
[in]tickRatesystem clock tick rate to find out about.
Returns
'true' if no time events are armed at the given tick rate and 'false' otherwise.
Note
This function should be called in critical section.
Precondition
the tick rate must be in range

Definition at line 197 of file qf_time.c.

◆ QF_add_()

void QF_add_ ( QActive *const  a)

Register an active object to be managed by the framework.

Description
This function removes a given active object from the active objects managed by the QF framework. It should not be called by the application directly, only through the function QActive_stop().
Parameters
[in]apointer to the active object to add to the framework.
Note
The priority of the active object a should be set before calling this function.
See also
QF_remove_()
Precondition
the priority of the active object must not be zero and cannot exceed the maximum QF_MAX_ACTIVE. Also, the priority of the active object must not be already in use. QF requires each active object to have a unique priority.

Definition at line 69 of file qf_act.c.

◆ QF_remove_()

void QF_remove_ ( QActive *const  a)

Remove the active object from the framework.

Description
This function removes a given active object from the active objects managed by the QF framework. It should not be called by the application directly, only through the function QActive_stop().
Parameters
[in]apointer to the active object to remove from the framework.
Note
The active object that is removed from the framework can no longer participate in the publish-subscribe event exchange.
See also
QF_add_()
Precondition
the priority of the active object must not be zero and cannot exceed the maximum QF_MAX_ACTIVE. Also, the priority of the active object must be already registered with the framework.

Definition at line 109 of file qf_act.c.

◆ QF_getPoolMin()

uint_fast16_t QF_getPoolMin ( uint_fast8_t const  poolId)

Obtain the minimum of free entries of the given event pool.

Description
This function obtains the minimum number of free blocks in the given event pool since this pool has been initialized by a call to QF_poolInit().
Parameters
[in]poolIdevent pool ID in the range 1..QF_maxPool_, where QF_maxPool_ is the number of event pools initialized with the function QF_poolInit().
Returns
the minimum number of unused blocks in the given event pool.
Precondition
the poolId must be in range

Definition at line 289 of file qf_mem.c.

◆ 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.

Description
Queries the minimum of free ever present in the given event queue of an active object with priority prio, since the active object was started.
Note
This function is available only when the native QF event queue implementation is used. Requesting the queue minimum of an unused priority level raises an assertion in the QF. (A priority level becomes used in QF after the call to the QF_add_() function.)
Parameters
[in]prioPriority of the active object, whose queue is queried
Returns
the minimum of free ever present in the given event queue of an active object with priority prio, since the active object was started.

Definition at line 339 of file qf_actq.c.

◆ QF_newX_()

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.

Description
Allocates an event dynamically from one of the QF event pools.
Parameters
[in]evtSizethe size (in bytes) of the event to allocate
[in]marginthe number of un-allocated events still available in a given event pool after the allocation completes. The special value QF_NO_MARGIN means that this function will assert if allocation fails.
[in]sigthe signal to be assigned to the allocated event
Returns
pointer to the newly allocated event. This pointer can be NULL only if margin!=0 and the event cannot be allocated with the specified margin still available in the given pool.
Note
The internal QF function QF_newX_() raises an assertion when the margin parameter is QF_NO_MARGIN and allocation of the event turns out to be impossible due to event pool depletion, or incorrect (too big) size of the requested event.
The application code should not call this function directly. The only allowed use is thorough the macros Q_NEW() or Q_NEW_X().

Definition at line 152 of file qf_dyn.c.

◆ QF_newRef_()

QEvt const* QF_newRef_ ( QEvt const *const  e,
QEvt const *const  evtRef 
)

Internal QF implementation of the event reference creator.

Description
Creates and returns a new reference to the current event e
Parameters
[in]epointer to the current event
[in]evtRefthe event reference
Returns
the newly created reference to the event e
Note
The application code should not call this function directly. The only allowed use is thorough the macro Q_NEW_REF().
Precondition
the event must be dynamic and the provided event reference must not be already in use

Definition at line 270 of file qf_dyn.c.

◆ QF_gc()

void QF_gc ( QEvt const *const  e)

Recycle a dynamic event.

Description
This function implements a simple garbage collector for the dynamic events. Only dynamic events are candidates for recycling. (A dynamic event is one that is allocated from an event pool, which is determined as non-zero e->poolId_ attribute.) Next, the function decrements the reference counter of the event (e->refCtr_), and recycles the event only if the counter drops to zero (meaning that no more references are outstanding for this event). The dynamic event is recycled by returning it to the pool from which it was originally allocated.
Parameters
[in]epointer to the event to recycle
Note
QF invokes the garbage collector at all appropriate contexts, when an event can become garbage (automatic garbage collection), so the application code should have no need to call QF_gc() directly. The QF_gc() function is exposed only for special cases when your application sends dynamic events to the "raw" thread-safe queues (see QEQueue). Such queues are processed outside of QF and the automatic garbage collection is NOT performed for these events. In this case you need to call QF_gc() explicitly.

Definition at line 217 of file qf_dyn.c.

◆ QF_bzero()

void QF_bzero ( void *const  start,
uint_fast16_t  len 
)

Clear a specified region of memory to zero.

Description
Clears a memory buffer by writing zeros byte-by-byte.
Parameters
[in]startpointer to the beginning of a memory buffer.
[in]lenlength of the memory buffer to clear (in bytes)
Note
The main application of this function is clearing the internal QF variables upon startup. This is done to avoid problems with non-standard startup code provided with some compilers and toolsets (e.g., TI DSPs or Microchip MPLAB), which does not zero the uninitialized variables, as required by the ANSI C standard.

Definition at line 159 of file qf_act.c.

◆ QTicker_ctor()

void QTicker_ctor ( QTicker *const  me,
uint8_t  tickRate 
)

Constructor of the QTicker Active Object class.

Constructor of the QTicker Active Object class.

Definition at line 380 of file qf_actq.c.

Variable Documentation

◆ QF_active_

QActive* QF_active_[QF_MAX_ACTIVE+1]

array of registered active objects

Note
Not to be used by Clients directly, only in ports of QF

Definition at line 53 of file qf_act.c.