QF Class Reference

QF services. More...

#include <qf.hpp>

Collaboration diagram for QF:

Static Public Member Functions
static char_t const *	getVersion (void) noexcept
	get the current QF version number string of the form X.Y.Z More...
static void	init (void)
	QF initialization. More...
static void	psInit (QSubscrList *const subscrSto, enum_t const maxSignal) noexcept
	Publish-subscribe initialization. More...
static void	poolInit (void *const poolSto, std::uint_fast32_t const poolSize, std::uint_fast16_t const evtSize) noexcept
	Event pool initialization for dynamic allocation of events. More...
static std::uint_fast16_t	poolGetMaxBlockSize (void) noexcept
	Obtain the block size of any registered event pools. More...
static int_t	run (void)
	Transfers control to QF to run the application. More...
static void	onStartup (void)
	Startup QF callback. More...
static void	onCleanup (void)
	Cleanup QF callback. More...
static void	stop (void)
	Function invoked by the application layer to stop the QF application and return control to the OS/Kernel. More...
static void	publish_ (QEvt const *const e, void const *const sender, std::uint_fast8_t const qs_id) noexcept
	Publish event to the framework. More...
static void	tickX_ (std::uint_fast8_t const tickRate, void const *const sender) noexcept
	Processes all armed time events at every clock tick. More...
static bool	noTimeEvtsActiveX (std::uint_fast8_t const tickRate) noexcept
	Returns true if all time events are inactive and false any time event is active. More...
static std::uint_fast16_t	getPoolMin (std::uint_fast8_t const poolId) noexcept
	This function returns the minimum of free entries of the given event pool. More...
static std::uint_fast16_t	getQueueMin (std::uint_fast8_t const prio) noexcept
	This function returns the minimum of free entries of the given event queue. More...
static QEvt *	newX_ (std::uint_fast16_t const evtSize, std::uint_fast16_t const margin, enum_t const sig) noexcept
	Internal QF implementation of creating new dynamic event. More...
static void	gc (QEvt const *const e) noexcept
	Recycle a dynamic event. More...
static QEvt const *	newRef_ (QEvt const *const e, QEvt const *const evtRef) noexcept
	Internal QF implementation of creating new event reference. More...
static void	deleteRef_ (QEvt const *const evtRef) noexcept
	Internal QF implementation of deleting event reference. More...
static void	remove_ (QActive *const a) noexcept
	Remove the active object from the framework. More...
static void	thread_ (QActive *act)
	Thread routine for executing an active object act. More...
static void	add_ (QActive *const a) noexcept
	Register an active object to be managed by the framework. More...
static void	bzero (void *const start, std::uint_fast16_t const len) noexcept
	Clear a specified region of memory to zero. More...

Static Public Attributes
static QActive *	active_ [QF_MAX_ACTIVE+1U]
	array of registered active objects More...

Static Private Attributes
static QTimeEvt	timeEvtHead_ [QF_MAX_TICK_RATE]
	heads of linked lists of time events, one for every clock tick rate More...

Friends
class	QActive
class	QTimeEvt
class	QS

Detailed Description

QF services.

Description

This class groups together QF services. It has only static members and should not be instantiated.

Definition at line 496 of file qf.hpp.

Member Function Documentation

getVersion()

static char_t const* getVersion ( void  )

inlinestaticnoexcept

get the current QF version number string of the form X.Y.Z

Definition at line 500 of file qf.hpp.

init()

void init ( void  )

static

QF initialization.

Description

Initializes QF and must be called exactly once before any other QF function. Typcially, QP::QF::init() is called from main() even before initializing the Board Support Package (BSP).

Note

QP::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).

Description

Initializes QF and must be called exactly once before any other QF function. Typcially, QP::QF::init() is called from main() even before initializing the Board Support Package (BSP).

Note

QP::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).

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

Clear 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 78 of file qk.cpp.

psInit()

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

staticnoexcept

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]	subscrSto	pointer to the array of subscriber lists
[in]	maxSignal	the 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 QP::QSubscrList, each bit in the bit mask corresponding to the unique priority of an active object. The size of the QP::QSubscrList bitmask 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

QP::QSubscrList

Usage

The following example shows the typical initialization sequence of QF:

#include "qpc.h"
#include "dpp.h"
#include "bsp.h"
 
namespace DPP {
 
//............................................................................
int_t main(void) {
    // statically allocated storage for various QP facilities
    static QP::QEvt const *tableQueueSto[N_PHILO];
    static QP::QEvt const *philoQueueSto[N_PHILO][N_PHILO];
    static QP::QSubscrList subscrSto[MAX_PUB_SIG];
    static QF_MPOOL_EL(TableEvt) smlPoolSto[2*N_PHILO];
 
    QP::QF::init();   // initialize the framework and the underlying RT kernel
 
    BSP::init(); // initialize the BSP
 
    // object dictionaries...
    QS_OBJ_DICTIONARY(AO_Table);
    QS_OBJ_DICTIONARY(AO_Philo[0]);
    QS_OBJ_DICTIONARY(AO_Philo[1]);
    QS_OBJ_DICTIONARY(AO_Philo[2]);
    QS_OBJ_DICTIONARY(AO_Philo[3]);
    QS_OBJ_DICTIONARY(AO_Philo[4]);
 
    QP::QF::psInit(subscrSto, Q_DIM(subscrSto)); // init publish-subscribe
 
    // initialize event pools...
    QP::QF::poolInit(smlPoolSto,
                     sizeof(smlPoolSto), sizeof(smlPoolSto[0]));
 
    // start the active objects...
    for (uint8_t n = 0U; n < N_PHILO; ++n) {
        AO_Philo[n]->start((uint8_t)(n + 1U),
                           philoQueueSto[n], Q_DIM(philoQueueSto[n]),
                           (void *)0, 0U);
    }
    AO_Table->start((uint8_t)(N_PHILO + 1U),
                    tableQueueSto, Q_DIM(tableQueueSto),
                    (void *)0, 0U);
 
    return QP::QF::run(); // run the QF application
}
 
} // namespace DPP

Definition at line 89 of file qf_ps.cpp.

poolInit()

void poolInit ( void *const  poolSto, std::uint_fast32_t const  poolSize, std::uint_fast16_t const  evtSize  )

staticnoexcept

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]	poolSto	pointer to the storage for the event pool
[in]	poolSize	size of the storage for the pool in bytes
[in]	evtSize	the block-size of the pool in bytes, which determines the maximum size of events that can be allocated from the pool

Note

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.

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 QP::QF::poolInit() and using up memory for the memory blocks is unnecessary.

See also

QF initialization example for QP::QF::init()

Precondition

cannot exceed the number of available memory pools

please initialize event pools in ascending order of evtSize

Definition at line 84 of file qf_dyn.cpp.

poolGetMaxBlockSize()

std::uint_fast16_t poolGetMaxBlockSize ( void  )

staticnoexcept

Obtain the block size of any registered event pools.

Description

Obtain the block size of any registered event pools

Definition at line 345 of file qf_dyn.cpp.

run()

int_t run ( void  )

static

Transfers control to QF to run the application.

Description

QP::QF::run() is typically called from your startup code after you initialize the QF and start at least one active object with QP::QActive::start().

Returns

In QK, the QP::QF::run() function does not return.

Description

QP::QF::run() is typically called from your startup code after you initialize the QF and start at least one active object with QP::QActive::start().

Returns

QP::QF::run() typically does not return in embedded applications. However, when QP runs on top of an operating system, QP::QF::run() might return and in this case the return represents the error code (0 for success). Typically the value returned from QP::QF::run() is subsequently passed on as return from main().

Note

This function is strongly platform-dependent and is not implemented in the QF, but either in the QF port or in the Board Support Package (BSP) for the given application. All QF ports must implement QP::QF::run().

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 137 of file qk.cpp.

onStartup()

static void onStartup ( void  )

static

Startup QF callback.

onCleanup()

static void onCleanup ( void  )

static

Cleanup QF callback.

stop()

void stop ( void  )

static

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.

Attention

After calling QF::stop() the application must terminate and cannot continue. In particular, QF::stop() is not intended to be followed by a call to QF::init() to "resurrect" the application.

See also

QP::QF::onCleanup()

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.

Attention

After calling QF::stop() the application must terminate and cannot continue. In particular, QF::stop() is not intended to be followed by a call to QF::init() to "resurrect" the application.

See also

QF::onCleanup()

Definition at line 111 of file qk.cpp.

publish_()

void publish_ ( QEvt const *const  e, void const *const  sender, std::uint_fast8_t const  qs_id  )

staticnoexcept

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.

Precondition

the published signal must be within the configured range

Definition at line 121 of file qf_ps.cpp.

tickX_()

void tickX_ ( std::uint_fast8_t const  tickRate, void const *const  sender  )

staticnoexcept

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]	tickRate	system clock tick rate serviced in this call [1..15].
[in]	sender	pointer to a sender object (used in QS only).

Note

this function should be called only via the macro TICK_X()

the calls to QP::QF::tickX_() with different tickRate parameter can preempt each other. For example, higher clock tick rates might be serviced from interrupts while others from tasks (active objects).

See also

QP::QTimeEvt.

Definition at line 78 of file qf_time.cpp.

noTimeEvtsActiveX()

bool noTimeEvtsActiveX ( std::uint_fast8_t const  tickRate )

staticnoexcept

Returns true if all time events are inactive and false any time event is active.

Description

Find out if any time events are armed at the given clock tick rate.

Parameters

[in]

tickRate

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

Definition at line 206 of file qf_time.cpp.

getPoolMin()

std::uint_fast16_t getPoolMin ( std::uint_fast8_t const  poolId )

staticnoexcept

This function returns 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 QP::QF::poolInit().

Parameters

[in]

poolId

event pool ID in the range 1..QF_maxPool_, where QF_maxPool_ is the number of event pools initialized with the function QP::QF::poolInit().

Returns

the minimum number of unused blocks in the given event pool.

Precondition

the poolId must be in range

Definition at line 303 of file qf_mem.cpp.

getQueueMin()

std::uint_fast16_t getQueueMin ( std::uint_fast8_t const  prio )

staticnoexcept

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

QP::QF::getQueueMin() 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 QP::QF::add_() function.)

Parameters

[in]

prio

Priority 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 378 of file qf_actq.cpp.

newX_()

QEvt * newX_ ( std::uint_fast16_t const  evtSize, std::uint_fast16_t const  margin, enum_t const  sig  )

staticnoexcept

Internal QF implementation of creating new dynamic event.

Description

Allocates an event dynamically from one of the QF event pools.

Parameters

[in]	evtSize	the size (in bytes) of the event to allocate
[in]	margin	the number of un-allocated events still available in a given event pool after the allocation completes The special value QP::QF_NO_MARGIN means that this function will assert if allocation fails.
[in]	sig	the 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 QP::QF::newX_() raises an assertion when the margin argument is QP::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 140 of file qf_dyn.cpp.

gc()

void gc ( QEvt const *const  e )

staticnoexcept

Recycle a dynamic event.

Description

This function implements a simple garbage collector for 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]

e

pointer 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 QP::QF::gc() directly. The QP::QF::gc() function is exposed only for special cases when your application sends dynamic events to the "raw" thread-safe queues (see QP::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 QP::QF::gc() explicitly.

Definition at line 219 of file qf_dyn.cpp.

newRef_()

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

staticnoexcept

Internal QF implementation of creating new event reference.

Description

Creates and returns a new reference to the current event e

Parameters

[in]	e	pointer to the current event
[in]	evtRef	the 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 291 of file qf_dyn.cpp.

deleteRef_()

void deleteRef_ ( QEvt const *const  evtRef )

staticnoexcept

Internal QF implementation of deleting event reference.

Description

Deletes an existing reference to the event e

Parameters

[in]

evtRef

the event reference

Note

The application code should not call this function directly. The only allowed use is thorough the macro Q_DELETE_REF().

Definition at line 327 of file qf_dyn.cpp.

remove_()

void remove_ ( QActive *const  a )

staticnoexcept

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 QP ports.

Parameters

[in]

a

pointer 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

QP::QF::add_()

Definition at line 103 of file qf_act.cpp.

thread_()

static void thread_ ( QActive *  act )

static

Thread routine for executing an active object act.

add_()

void add_ ( QActive *const  a )

staticnoexcept

Register an active object to be managed by the framework.

Description

This function adds a given active object to the active objects managed by the QF framework. It should not be called by the application directly, only through the function QP::QActive::start().

Parameters

[in]

a

pointer 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

QP::QF::remove_()

Definition at line 79 of file qf_act.cpp.

bzero()

void bzero ( void *const  start, std::uint_fast16_t const  len  )

staticnoexcept

Clear a specified region of memory to zero.

Description

Clears a memory buffer by writing zeros byte-by-byte.

Parameters

[in]	start	pointer to the beginning of a memory buffer.
[in]	len	length 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 129 of file qf_act.cpp.

Friends And Related Function Documentation

QActive

friend class QActive

friend

Definition at line 617 of file qf.hpp.

QTimeEvt

friend class QTimeEvt

friend

Definition at line 618 of file qf.hpp.

QS

friend class QS

friend

Definition at line 619 of file qf.hpp.

Field Documentation

active_

QActive * active_

static

array of registered active objects

Definition at line 580 of file qf.hpp.

timeEvtHead_

QTimeEvt timeEvtHead_

staticprivate

heads of linked lists of time events, one for every clock tick rate

Definition at line 615 of file qf.hpp.

---

The documentation for this class was generated from the following files:

• qf.hpp
• qf_act.cpp
• qf_actq.cpp
• qf_dyn.cpp
• qf_mem.cpp
• qf_ps.cpp
• qf_time.cpp
• qk.cpp
• qutest.cpp
• qv.cpp
• qxk.cpp