QP/C  7.3.3
Real-Time Embedded Framework
Loading...
Searching...
No Matches
QF Class Reference

QF Active Object Framework (QF namespace emulated as a "class" in C) More...

Static Public Member Functions

void QF_init (void)
 
void QF_stop (void)
 
int_t QF_run (void)
 
uint_fast16_t QF_getQueueMin (uint_fast8_t const prio)
 
void QF_onStartup (void)
 
void QF_onCleanup (void)
 
void QF_onContextSw (QActive *prev, QActive *next)
 
void QF_poolInit (void *const poolSto, uint_fast32_t const poolSize, uint_fast16_t const evtSize)
 
uint_fast16_t QF_poolGetMaxBlockSize (void)
 
uint_fast16_t QF_getPoolMin (uint_fast8_t const poolNum)
 
void QF_gc (QEvt const *const e)
 
void QF_gcFromISR (QEvt const *const e)
 
static void QF_psInit (QSubscrList *const subscrSto, enum_t const maxSignal)
 

Static Private Member Functions

QEvtQF_newX_ (uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)
 
QEvt const * QF_newRef_ (QEvt const *const e, void const *const evtRef)
 
void QF_deleteRef_ (void const *const evtRef)
 
void QF_bzero_ (void *const start, uint_fast16_t const len)
 

Private Attributes

QF_Attr QF_priv_
 

Detailed Description

QF Active Object Framework (QF namespace emulated as a "class" in C)

Member Function Documentation

◆ QF_init()

QF::QF_init ( void  )
static

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

Definition at line 172 of file qutest.c.

◆ QF_stop()

QF::QF_stop ( void  )
static

Invoked by the application layer to stop the QF framework and return control to the OS/Kernel (used in some QF ports).

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.

Definition at line 186 of file qutest.c.

◆ QF_run()

QF::QF_run ( void  )
static

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
Typically in embedded systems QF_run() does not return, but in case QF runs on top of a General-Purpose OS (GPOS), QF_run() returns the error status with value 0 representing success.

Definition at line 191 of file qutest.c.

◆ QF_getQueueMin()

QF::QF_getQueueMin ( uint_fast8_t const  prio)
static

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 QActive_register_() 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 354 of file qf_actq.c.

◆ QF_onStartup()

QF::QF_onStartup ( void  )
static

Startup QF callback.

Description
The purpose of the QF_onStartup() callback is to configure and enable hardware interrupts. The callback is invoked from QF_run(), right before starting the underlying real-time kernel. By that time, the application is considered ready to receive and service interrupts.

This function is application-specific and is not implemented in QF, but rather in the Board Support Package (BSP) for the given application.

◆ QF_onCleanup()

QF::QF_onCleanup ( void  )
static

Cleanup QF callback.

Description
QF_onCleanup() is called in some QF ports before QF returns to the underlying real-time kernel or operating system.

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.

◆ QF_onContextSw()

QF::QF_onContextSw ( QActive prev,
QActive next 
)
static

QF context switch callback used in built-in kernels (QV, QK, QXK)

Description
This callback function provides a mechanism to perform additional custom operations when one of the built-in kernels switches context from one thread to another.
Parameters
[in]prevpointer to the previous thread (active object) (prev==0 means that prev was the idle loop)
[in]nextpointer to the next thread (active object) (next==0) means that next is the idle loop)
Attention
QF_onContextSw() is invoked with interrupts disabled and must also return with interrupts disabled.
Usage
This callback is enabled by defining the macro QF_ON_CONTEXT_SW.
#ifdef QF_ON_CONTEXT_SW
// NOTE: the context-switch callback is called with interrupts DISABLED
void QF_onContextSw(QActive *prev, QActive *next) {
if (next != (QActive *)0) {
MPU->CTRL = 0U; // disable the MPU
MPU_Region const * const region = (MPU_Region const *)next->thread;
MPU->RBAR = region[0].RBAR;
MPU->RASR = region[0].RASR;
MPU->RBAR = region[1].RBAR;
MPU->RASR = region[1].RASR;
MPU->RBAR = region[2].RBAR;
MPU->RASR = region[2].RASR;
MPU->CTRL = MPU_CTRL_ENABLE_Msk // enable the MPU
| MPU_CTRL_PRIVDEFENA_Msk; // enable background region
__ISB();
__DSB();
}
}
#endif // QF_ON_CONTEXT_SW
void QF_onContextSw(QActive *prev, QActive *next)
Active object class (based on the QHsm implementation strategy)
Definition qp.h:800
QACTIVE_THREAD_TYPE thread
Definition qp.h:812

◆ QF_poolInit()

QF::QF_poolInit ( void *const  poolSto,
uint_fast32_t const  poolSize,
uint_fast16_t const  evtSize 
)
static

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.
Precondition qf_dyn:200
  • the number of event-pools initialized so far must not exceed the maximum QF_MAX_EPOOL
Precondition qf_dyn:201
  • except the first event-pool 0, the event-size of the previously initialized event pool must not exceed the next event size.

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.

Remarks
Many RTOSes provide fixed block-size heaps, a.k.a. memory pools that can be adapted for QF event-pools. In case the pools from the RTOS are not used, QF provides a native memory pool implementation (QMPool). The macro QF_EPOOL_TYPE_ determines the type of event pool used by a particular QF port.
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 mutable events. In that case calling QF_poolInit() and using up memory for the memory blocks is unnecessary.

◆ QF_poolGetMaxBlockSize()

QF::QF_poolGetMaxBlockSize ( void  )
static

Obtain the block size of any registered event pools.

Description
Obtain the block size of any registered event pools

Definition at line 106 of file qf_dyn.c.

◆ QF_getPoolMin()

QF::QF_getPoolMin ( uint_fast8_t const  poolNum)
static

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]poolNumevent pool ID in the range 1..max_pool, where max_pool 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 qf_dyn:400
  • the poolNum must be in range

Definition at line 120 of file qf_dyn.c.

◆ QF_newX_()

QF::QF_newX_ ( uint_fast16_t const  evtSize,
uint_fast16_t const  margin,
enum_t const  sig 
)
staticprivate

Internal QF implementation of creating new mutable (dynamic) event.

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 != QF_NO_MARGIN and the event cannot be allocated with the specified margin still available in the given pool.
Precondition qf_dyn:300
  • the event size must fit one of the initialized event pools
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 138 of file qf_dyn.c.

◆ QF_gc()

QF::QF_gc ( QEvt const *const  e)
static

Recycle a mutable (mutable) event

Description
This function implements a simple garbage collector for the mutable events. Only mutable events are candidates for recycling. (A mutable event is one that is allocated from an event-pool, which is determined as non-zero QEvt_getPoolId_(e)) 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 mutable 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 mutable 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.
Traceability

Definition at line 218 of file qf_dyn.c.

◆ QF_newRef_()

QF::QF_newRef_ ( QEvt const *const  e,
void const *const  evtRef 
)
staticprivate

Internal QF implementation of creating new event reference.

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
Precondition qf_dyn:500
  • the event must be from a pool (mutable event)
  • the provided event reference must not be already in use
Note
The application code should not call this function directly. The only allowed use is thorough the macro Q_NEW_REF().

Definition at line 275 of file qf_dyn.c.

◆ QF_deleteRef_()

QF::QF_deleteRef_ ( void const *const  evtRef)
staticprivate

Internal QF implementation of deleting event reference.

Description
Deletes an existing reference to the event e
Parameters
[in]evtRefthe event reference
Note
The application code should not call this function directly. The only allowed use is thorough the macro Q_DELETE_REF().
Traceability

Definition at line 311 of file qf_dyn.c.

◆ QF_gcFromISR()

void QF_gcFromISR ( QEvt const *const  e)
static

◆ QF_bzero_()

void QF_bzero_ ( void *const  start,
uint_fast16_t const  len 
)
staticprivate

Definition at line 74 of file qf_act.c.

◆ QF_psInit()

static void QF_psInit ( QSubscrList *const  subscrSto,
enum_t const  maxSignal 
)
inlinestatic
Deprecated:

Definition at line 118 of file qpc.h.

Member Data Documentation

◆ QF_priv_

QF_Attr QF_priv_
private

Definition at line 71 of file qp_pkg.h.


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