QP-nano  5.9.5
qfn.h File Reference

Public QF-nano interface. More...

Go to the source code of this file.

Data Structures

struct  QActive
 QActive active object (based on QHsm-implementation) More...
 
struct  QActiveVtbl
 Virtual table for the QActive class. More...
 
struct  QActiveCB
 QActive Control Block. More...
 

Macros

#define QF_TIMEEVT_CTR_SIZE   0
 macro to override the default QTimeEvtCtr size. More...
 
#define QF_MAX_TICK_RATE   1
 Default value of the macro configurable value in qpn_port.h.
 
#define QACTIVE_POST(me_, sig_)
 
#define QACTIVE_POST_X(me_, margin_, sig_)
 
#define QACTIVE_POST_ISR(me_, sig_)
 
#define QACTIVE_POST_X_ISR(me_, margin_, sig_)
 
#define QF_ROM_QUEUE_AT_(ao_, i_)   (((QEvt *)Q_ROM_PTR((ao_)->queue))[(i_)])
 This macro encapsulates accessing the active object queue at a given index, which violates MISRA-C 2004 rules 17.4(req) and 11.4(adv). More...
 
#define QF_ROM_ACTIVE_GET_(p_)   ((QActive *)Q_ROM_PTR(QF_active[(p_)].act))
 This macro encapsulates accessing the active object control block, which violates MISRA-C 2004 rule 11.4(adv). More...
 
#define QF_ACTIVE_CAST(a_)   ((QActive *)(a_))
 This macro encapsulates the upcast to QActive*. More...
 

Functions

void QActive_ctor (QActive *const me, QStateHandler initial)
 protected "constructor" of an QActive active object. More...
 
bool QActive_postX_ (QActive *const me, uint_fast8_t margin, enum_t const sig)
 
bool QActive_postXISR_ (QActive *const me, uint_fast8_t margin, enum_t const sig)
 
void QF_init (uint_fast8_t maxActive)
 QF-nano initialization. More...
 
void QF_stop (void)
 QF-nano termination. More...
 
void QF_onStartup (void)
 Startup QF-nano callback. More...
 
int_t QF_run (void)
 Transfers control to QF-nano to run the application. More...
 

Variables

QActiveCB const Q_ROM QF_active []
 
uint_fast8_t QF_maxActive_
 number of active objects in the application (# elements in QF_active[]) More...
 
uint_fast8_t volatile QF_readySet_
 Ready set of QF-nano. More...
 
uint8_t const Q_ROM QF_log2Lkup [16]
 Lookup table for (log2(n) + 1), where n is the index into the table. More...
 
uint8_t const Q_ROM QF_invPow2Lkup [9]
 Lookup table for ~(1 << (n - 1)), where n is the index into the table. More...
 

Detailed Description

Public QF-nano interface.

Definition in file qfn.h.


Data Structure Documentation

◆ QActive

struct QActive

QActive active object (based on QHsm-implementation)

Description
QActive is the base structure for derivation of active objects. Active objects in QF-nano are encapsulated tasks (each embedding a state machine and an event queue) 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.
Note
QActive is not intended to be instantiated directly, but rather serves as the base structure for derivation of active objects in the application code.
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.
/* PEdestrian Light CONtrolled (PELICAN) crossing active object */
typedef struct {
QActive super; /* inherits QActive */
uint8_t pedFlashCtr; /* pedestrian flash counter */
} Pelican;
/* the ctor */
void Pelican_ctor(Pelican * const me, uint8_t timeout) {
/* call the superclass' ctor... */
QActive_ctor(&me->super, Q_STATE_CAST(&Pelican_initial));
. . . /* initialize the added attributes */
}

Definition at line 120 of file qfn.h.

Data Fields
uint_fast8_t volatile head offset to where next event will be inserted into the buffer
uint_fast8_t volatile nUsed number of events currently present in the queue (events in the ring buffer + 1 event in the state machine)
uint_fast8_t prio priority of the active object (1..8)
QHsm super

derives from the QHsm base class

uint_fast8_t volatile tail offset of where next event will be extracted from the buffer

◆ QActiveCB

struct QActiveCB

QActive Control Block.

QActiveCB represents the read-only information that the QF-nano needs to manage the active object. QActiveCB objects are grouped in the array QF_active[], which typically can be placed in ROM.

Usage
The following example illustrates how to allocate and initialize the QActive control blocks in the array QF_active[].
#include "qpn.h" /* QP-nano API */
#include "bsp.h" /* Board Support Package (BSP) */
#include "pelican.h" /* Application interface */
/*..........................................................................*/
static QEvt l_pelicanQueue[2];
static QEvt l_pedQueue[1];
/* QF_active[] array defines all active object control blocks --------------*/
{ (QActive *)0, (QEvt *)0, 0 },
{ (QActive *)&AO_Pelican, l_pelicanQueue, Q_DIM(l_pelicanQueue) },
{ (QActive *)&AO_Ped, l_pedQueue, Q_DIM(l_pedQueue) }
};
/*..........................................................................*/
int_t main (void) {
Pelican_ctor(); /* instantiate the Pelican AO */
Ped_ctor(); /* instantiate the Ped AO */
QF_init(Q_DIM(QF_active)); /* initialize the QF-nano framework */
BSP_init(); /* initialize the Board Support Package */
return QF_run(); /* transfer control to QF-nano */
}

Definition at line 370 of file qfn.h.

Data Fields
QActive * act pointer to the active object structure
uint8_t qlen the length of the queue ring buffer
QEvt * queue pointer to the event queue buffer

Macro Definition Documentation

◆ QACTIVE_POST

#define QACTIVE_POST (   me_,
  sig_ 
)
Value:
((void)(*((QActiveVtbl const *)( \
QF_ACTIVE_CAST((me_))->super.vptr))->post)( \
QF_ACTIVE_CAST((me_)), (uint_fast8_t)0, (enum_t)(sig_)))
Virtual table for the QActive class.
Definition: qfn.h:145
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
int enum_t
typedef for enumerations used for event signals
Definition: qepn.h:77
#define QF_ACTIVE_CAST(a_)
This macro encapsulates the upcast to QActive*.
Definition: qfn.h:429

Definition at line 280 of file qfn.h.

◆ QACTIVE_POST_ISR

#define QACTIVE_POST_ISR (   me_,
  sig_ 
)
Value:
((void)(*((QActiveVtbl const*)( \
QF_ACTIVE_CAST((me_))->super.vptr))->postISR)( \
QF_ACTIVE_CAST((me_)), (uint_fast8_t)0, (enum_t)(sig_)))
Virtual table for the QActive class.
Definition: qfn.h:145
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
int enum_t
typedef for enumerations used for event signals
Definition: qepn.h:77
#define QF_ACTIVE_CAST(a_)
This macro encapsulates the upcast to QActive*.
Definition: qfn.h:429

Definition at line 292 of file qfn.h.

◆ QACTIVE_POST_X

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

Definition at line 285 of file qfn.h.

◆ QACTIVE_POST_X_ISR

#define QACTIVE_POST_X_ISR (   me_,
  margin_,
  sig_ 
)
Value:
((*((QActiveVtbl const *)( \
QF_ACTIVE_CAST((me_))->super.vptr))->postISR)( \
QF_ACTIVE_CAST((me_)), (margin_), (enum_t)(sig_)))
Virtual table for the QActive class.
Definition: qfn.h:145
int enum_t
typedef for enumerations used for event signals
Definition: qepn.h:77
#define QF_ACTIVE_CAST(a_)
This macro encapsulates the upcast to QActive*.
Definition: qfn.h:429

Definition at line 297 of file qfn.h.

◆ QF_ACTIVE_CAST

#define QF_ACTIVE_CAST (   a_)    ((QActive *)(a_))

This macro encapsulates the upcast to QActive*.

This macro encapsulates up-casting a pointer to a subclass of QActive to the base class QActive, which violates MISRA-C 2004 rule 11.4(adv). This macro helps to localize this deviation.

Definition at line 429 of file qfn.h.

◆ QF_ROM_ACTIVE_GET_

#define QF_ROM_ACTIVE_GET_ (   p_)    ((QActive *)Q_ROM_PTR(QF_active[(p_)].act))

This macro encapsulates accessing the active object control block, which violates MISRA-C 2004 rule 11.4(adv).

This macro helps to localize this deviation.

Definition at line 421 of file qfn.h.

◆ QF_ROM_QUEUE_AT_

#define QF_ROM_QUEUE_AT_ (   ao_,
  i_ 
)    (((QEvt *)Q_ROM_PTR((ao_)->queue))[(i_)])

This macro encapsulates accessing the active object queue at a given index, which violates MISRA-C 2004 rules 17.4(req) and 11.4(adv).

This macro helps to localize this deviation.

Definition at line 415 of file qfn.h.

◆ QF_TIMEEVT_CTR_SIZE

#define QF_TIMEEVT_CTR_SIZE   0

macro to override the default QTimeEvtCtr size.

Description
This header file must be included in all modules that use QP-nano. Typically, this header file is included indirectly through the header file qpn_port.h.

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

Definition at line 55 of file qfn.h.

Function Documentation

◆ QActive_ctor()

void QActive_ctor ( QActive *const  me,
QStateHandler  initial 
)

protected "constructor" of an QActive active object.

Note
QActive 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 QHsm_ctor() avoids pulling in the code for QHsm.

Definition at line 98 of file qfn.c.

◆ QActive_postX_()

bool QActive_postX_ ( QActive *const  me,
uint_fast8_t  margin,
enum_t const  sig 
)
Description
Direct event posting is the simplest asynchronous communication method available in QF-nano.
Attention
This function should be called only via the macro QACTIVE_POST() or QACTIVE_POST_X(). This function should be only used in the task context.
Parameters
[in,out]mepointer (see Object Orientation)
[in]marginnumber of required free slots in the queue after posting the event.
[in]sigsignal of the event to be posted
[in]parparameter of the event to be posted
Note
The zero 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
/* "extended" event posting from the interrupt context (QACTIVE_POST_X_ISR) */
void SysTick_Handler(void) {
. . .
if (!QACTIVE_POST_X_ISR((QActive *)&AO_Cruncher,
5U, /* margin of free slots in the queue */
ECHO_SIG, 0U)) /* signal and parameter */
{
/* event posting failed... */
}
}
/* "extended" event posting from the task context (QACTIVE_POST_X())... */
static QState Ship_flying(Ship * const me) {
QState status_;
switch (Q_SIG(me)) {
case TIME_TICK_SIG: {
. . .
if ((me->score % 10) == 0) { /* is the score "round"? */
if (!QACTIVE_POST_X((QActive *)&AO_Tunnel,
4U, /* margin of free slots in the queue */
SCORE_SIG, me->score)) /* signal and parameter */
{
/* event posting failed... */
}
}
status_ = Q_HANDLED();
break;
}
. . .
}
return status_;
}

Definition at line 148 of file qfn.c.

◆ QActive_postXISR_()

bool QActive_postXISR_ ( QActive *const  me,
uint_fast8_t  margin,
enum_t const  sig 
)
Description
Direct event posting is the simplest asynchronous communication method available in QF-nano.
Attention
This function should be called only via the macro QACTIVE_POST_ISR() or QACTIVE_POST_X_ISR(). This function should be only used in the ISR context.
Parameters
[in,out]mepointer (see Object Orientation)
[in]marginnumber of required free slots in the queue after posting the event.
[in]sigsignal of the event to be posted
[in]parparameter of the event to be posted
Note
The zero 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
/* "extended" event posting from the interrupt context (QACTIVE_POST_X_ISR) */
void SysTick_Handler(void) {
. . .
if (!QACTIVE_POST_X_ISR((QActive *)&AO_Cruncher,
5U, /* margin of free slots in the queue */
ECHO_SIG, 0U)) /* signal and parameter */
{
/* event posting failed... */
}
}
/* "extended" event posting from the task context (QACTIVE_POST_X())... */
static QState Ship_flying(Ship * const me) {
QState status_;
switch (Q_SIG(me)) {
case TIME_TICK_SIG: {
. . .
if ((me->score % 10) == 0) { /* is the score "round"? */
if (!QACTIVE_POST_X((QActive *)&AO_Tunnel,
4U, /* margin of free slots in the queue */
SCORE_SIG, me->score)) /* signal and parameter */
{
/* event posting failed... */
}
}
status_ = Q_HANDLED();
break;
}
. . .
}
return status_;
}

Definition at line 226 of file qfn.c.

◆ QF_init()

void QF_init ( uint_fast8_t  maxActive)

QF-nano initialization.

Description
The function QF_init() initializes the number of active objects to be managed by the framework and clears the internal QF-nano variables as well as all registered active objects to zero, which is needed in case when the startup code does not clear the uninitialized data (in violation of the C Standard).
Note
The intended use of the function is to call as follows: QF_init(Q_DIM(QF_active));
Precondition
the number of active objects must be in range

Definition at line 297 of file qfn.c.

◆ QF_onStartup()

void QF_onStartup ( void  )

Startup QF-nano callback.

Description
The time line 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.
See also
QF initialization example for QActiveCB.

◆ QF_run()

int_t QF_run ( void  )

Transfers control to QF-nano 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(). This implementation of QF_run() is for the preemptive QK-nano kernel.
Returns
QF_run() typically does not return in embedded applications. However, when QP runs on top of an operating system, QF_run() might return and in this case the return represents the error code (0 for success). Typically the value returned from QF_run() is subsequently passed on as return from main().
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(). This implementation of QF_run() is for the cooperative Vanilla kernel.
Returns
QF_run() typically does not return in embedded applications. However, when QP runs on top of an operating system, QF_run() might return and in this case the return represents the error code (0 for success). Typically the value returned from QF_run() is subsequently passed on as return from main().
Precondition
the number of active objects must be initialized by calling: QF_init(Q_DIM(QF_active));

Definition at line 128 of file qkn.c.

◆ QF_stop()

void QF_stop ( void  )

QF-nano termination.

Description
This function terminates QF and performs any necessary cleanup. In QF-nano this function is defined in the BSP. Many QF ports might not require implementing QF_stop() at all, because many embedded applications don't have anything to exit to.

Variable Documentation

◆ QF_active

QActiveCB const Q_ROM QF_active[]

active object control blocks

◆ QF_invPow2Lkup

uint8_t const Q_ROM QF_invPow2Lkup[9]

Lookup table for ~(1 << (n - 1)), where n is the index into the table.

◆ QF_log2Lkup

uint8_t const Q_ROM QF_log2Lkup[16]

Lookup table for (log2(n) + 1), where n is the index into the table.

This lookup delivers the 1-based number of the most significant 1-bit of a nibble.

Definition at line 89 of file qfn.c.

◆ QF_maxActive_

uint_fast8_t QF_maxActive_

number of active objects in the application (# elements in QF_active[])

Description
This variable stores the number of active objects in the application. This is the number of elements (dimension of) the QF_active[] array.

Definition at line 53 of file qfn.c.

◆ QF_readySet_

uint_fast8_t volatile QF_readySet_

Ready set of QF-nano.

Description
The QF-nano ready set keeps track of active objects that are ready to run. The ready set represents each active object as a bit, with the bits assigned according to priorities of the active objects. The bit is set if the corresponding active object is ready to run (i.e., has one or more events in its event queue) and zero if the event queue is empty. The QF-nano ready set is one byte-wide, which corresponds to 8 active objects maximum.

Definition at line 65 of file qfn.c.