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

Static Public Member Functions
void	QF_init (void)
	QF initialization.
void	QF_stop (void)
	Invoked by the application layer to stop the QF framework and return control to the OS/Kernel (used in some QF ports).
int_t	QF_run (void)
	Transfers control to QF to run the application.
void	QF_onStartup (void)
	Startup callback.
void	QF_onCleanup (void)
	Cleanup QF callback.
void	QF_onContextSw (QActive prev, QActive next)
	QF context switch callback used in built-in kernels (QV/QK/QXK).
void	QF_poolInit (void *const poolSto, uint_fast32_t const poolSize, uint_fast16_t const evtSize)
	Event pool initialization for dynamic allocation of events.
uint16_t	QF_poolGetMaxBlockSize (void)
	Obtain the block size of any registered event pools.
uint16_t	QF_getPoolUse (uint_fast8_t const poolNum)
uint16_t	QF_getPoolFree (uint_fast8_t const poolNum)
uint16_t	QF_getPoolMin (uint_fast8_t const poolNum)
	Obtain the minimum of free entries of the given event pool.
void	QF_gc (QEvt const *const e)
	Recycle a mutable (mutable) event.
void	QF_gcFromISR (QEvt const *const e)
static void	QF_psInit (QSubscrList *const subscrSto, enum_t const maxSignal)

Static Private Member Functions
QEvt *	QF_newX_ (uint_fast16_t const evtSize, uint_fast16_t const margin, enum_t const sig)
	Internal QF implementation of creating new mutable (dynamic) event.
QEvt const *	QF_newRef_ (QEvt const const e, void const const evtRef)
	Internal QF implementation of creating new event reference.
void	QF_deleteRef_ (void const *const evtRef)
	Internal QF implementation of deleting event reference.

Static 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()

void QF_init ( void )

static

QF initialization.

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

Backward Traceability

SDS_QP_QF: QF Active Object Framework
SDS_QA_START: QA Application startup sequence

Forward Traceability

Definition at line 138 of file qutest.c.

◆ QF_stop()

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

Details
This function stops the QF application. After calling this function, QF attempts to stop the application gracefully. This graceful shutdown might take some time to complete. The typical use of this function is for terminating the QF application to return to the operating system or for handling fatal errors that require shutting down (and possibly resetting) 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.

Backward Traceability

SDS_QP_QF: QF Active Object Framework

Forward Traceability

Definition at line 143 of file qutest.c.

◆ QF_run()

int_t QF_run ( void )

static

Transfers control to QF to run the application.

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

Backward Traceability

SDS_QP_QF: QF Active Object Framework
SDS_QA_START: QA Application startup sequence

Forward Traceability

Definition at line 215 of file qutest.c.

◆ QF_onStartup()

void QF_onStartup ( void )

static

Startup callback.

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

Backward Traceability

SDS_QP_QF: QF Active Object Framework
SDS_QA_START: QA Application startup sequence

Forward Traceability

◆ QF_onCleanup()

void QF_onCleanup ( void )

static

Cleanup QF callback.

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

Backward Traceability

SDS_QP_QF: QF Active Object Framework

Forward Traceability

◆ QF_onContextSw()

void QF_onContextSw	(	QActive *	prev,
		QActive *	next )

static

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

Details
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]	prev	pointer to the previous thread (active object) (prev==0 means that prev was the idle loop)
[in]	next	pointer 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

Backward Traceability

SDS_QP_QF: QF Active Object Framework

Forward Traceability

◆ QF_poolInit()

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

static

Event pool initialization for dynamic allocation of events.

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

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

Backward Traceability

SDS_QP_QF: QF Active Object Framework
SDS_QA_START: QA Application startup sequence

Forward Traceability

Definition at line 46 of file qf_dyn.c.

◆ QF_poolGetMaxBlockSize()

uint16_t QF_poolGetMaxBlockSize ( void )

static

Obtain the block size of any registered event pools.

Details
Obtain the block size of any registered event pools

Definition at line 87 of file qf_dyn.c.

◆ QF_getPoolUse()

uint16_t QF_getPoolUse ( uint_fast8_t const poolNum )

static

◆ QF_getPoolFree()

uint16_t QF_getPoolFree ( uint_fast8_t const poolNum )

static

◆ QF_getPoolMin()

uint16_t QF_getPoolMin ( uint_fast8_t const poolNum )

static

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

Details
This function obtains the minimum number of free blocks in the given event pool since a call to QF_poolInit() has initialized this pool.

Parameters

[in] poolNum event 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.

Backward Traceability

SDS_QP_QF: QF Active Object Framework

Forward Traceability

◆ QF_newX_()

QEvt * 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.

Details
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 unallocated 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]	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 != QF_NO_MARGIN 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 through the macros Q_NEW() or Q_NEW_X().

Backward Traceability

SDS_QP_QF: QF Active Object Framework

Forward Traceability

Definition at line 190 of file qf_dyn.c.

◆ QF_gc()

void QF_gc ( QEvt const *const e )

static

Recycle a mutable (mutable) event.

Details
This function implements a simple garbage collector for the mutable events. Only mutable events are candidates for recycling. (A mutable event 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_). It 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 initially 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 not need to call QF_gc() directly. The QF_gc() function is exposed only for exceptional 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.

Backward Traceability

SDS_QP_QF: QF Active Object Framework

Forward Traceability

DVR_QP_MC5_R11_8: MISRA-C:2025 Rule 11.8(Required): A cast shall not remove any 'const' or 'volatile' qualification from the type pointer to by a pointer

Definition at line 268 of file qf_dyn.c.

◆ QF_newRef_()

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

staticprivate

Internal QF implementation of creating new event reference.

Details
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 through the macro Q_NEW_REF().

Backward Traceability

SDS_QP_QF: QF Active Object Framework

Forward Traceability

Definition at line 325 of file qf_dyn.c.

◆ QF_deleteRef_()

void QF_deleteRef_ ( void const *const evtRef )

staticprivate

Internal QF implementation of deleting event reference.

Details
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 through the macro Q_DELETE_REF().

Backward Traceability

SDS_QP_QF: QF Active Object Framework

Forward Traceability

DVR_QP_MC5_R11_5: MISRA-C:2025 Rule 11.5(Advisory): A conversion should not be performed from pointer to void into pointer to object

Definition at line 367 of file qf_dyn.c.

◆ QF_gcFromISR()

void QF_gcFromISR ( QEvt const *const e )

static

◆ QF_psInit()

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

inlinestatic

Deprecated

Definition at line 184 of file qpc.h.

Member Data Documentation

◆ QF_priv_

QF_Attr QF_priv_

staticprivate

Definition at line 67 of file qp_pkg.h.

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


QP/C 8.1.1 Real-Time Event Framework

Static Public Member Functions

Static Private Member Functions

Static Private Attributes

Detailed Description

Member Function Documentation

◆ QF_init()

◆ QF_stop()

◆ QF_run()

◆ QF_onStartup()

◆ QF_onCleanup()

◆ QF_onContextSw()

◆ QF_poolInit()

◆ QF_poolGetMaxBlockSize()

◆ QF_getPoolUse()

◆ QF_getPoolFree()

◆ QF_getPoolMin()

◆ QF_newX_()

◆ QF_gc()

◆ QF_newRef_()

◆ QF_deleteRef_()

◆ QF_gcFromISR()

◆ QF_psInit()

Member Data Documentation

◆ QF_priv_