QF active object framework.
More...
#include "qf.h"
|
#define | QF_LOG2(n_) ((uint_fast8_t)(32U - __builtin_clz((unsigned)(n_)))) |
|
QEvt * | QF_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) |
|
Definition at line 1409 of file qf.h.
◆ QF_init()
QF initialization
Initializes QF and must be called exactly once before any other QF function. Typcially, 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 171 of file qutest.c.
◆ QF_stop()
Function invoked by the application layer to stop the QF application and return control to the OS/Kernel.
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 185 of file qutest.c.
◆ QF_run()
Transfers control to QF to run the application.
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() does not return.
Definition at line 190 of file qutest.c.
◆ QF_getQueueMin()
uint_fast16_t QF_getQueueMin |
( |
uint_fast8_t const |
prio | ) |
|
|
static |
This function returns the minimum of free entries of the given event queue.
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] | 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 317 of file qf_actq.c.
◆ QF_onStartup()
void QF_onStartup |
( |
void |
| ) |
|
|
static |
Startup QF callback.
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()
void QF_onCleanup |
( |
void |
| ) |
|
|
static |
Cleanup QF callback.
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.
- See also
- QF_stop()
◆ 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.
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. |
- 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()
◆ QF_poolGetMaxBlockSize()
uint_fast16_t QF_poolGetMaxBlockSize |
( |
void |
| ) |
|
|
static |
Obtain the block size of any registered event pools.
Obtain the block size of any registered event pools
Definition at line 116 of file qf_dyn.c.
◆ QF_getPoolMin()
uint_fast16_t QF_getPoolMin |
( |
uint_fast8_t const |
poolId | ) |
|
|
static |
Obtain the minimum of free entries of the given event pool.
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] | poolId | event 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 122 of file qf_dyn.c.
◆ 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 dynamic event.
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 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 thorough the macros Q_NEW() or Q_NEW_X().
Definition at line 137 of file qf_dyn.c.
◆ QF_gc()
void QF_gc |
( |
QEvt const *const |
e | ) |
|
|
static |
Recycle a dynamic event
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] | 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 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 197 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.
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 246 of file qf_dyn.c.
◆ QF_deleteRef_()
void QF_deleteRef_ |
( |
void const *const |
evtRef | ) |
|
|
staticprivate |
Internal QF implementation of deleting event reference.
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 279 of file qf_dyn.c.
◆ QF_onContextSw()
QF context switch callback used in built-in kernels (QV, QK, QXK)
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.
- Note
- This callback is enabled by defining the macro QF_ON_CONTEXT_SW.
#ifdef QF_ON_CONTEXT_SW
(void)prev;
}
QS_OBJ(prev);
QS_OBJ(next);
}
#endif
#define QS_BEGIN_NOCRIT(rec_, qs_id_)
Active object class (based on the QHsm implementation strategy)
void QF_onContextSw(QActive *prev, QActive *next)
◆ QF_bzero()
void QF_bzero |
( |
void *const |
start, |
|
|
uint_fast16_t const |
len |
|
) |
| |
|
static |
Clear a specified region of memory to zero.
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.
◆ dummy
◆ QF_intLock_
uint_fast8_t volatile QF_intLock_ |
|
private |
Interrupt lock up-down counter (used in some QF ports )
Definition at line 1417 of file qf.h.
◆ QF_intNest_
uint_fast8_t volatile QF_intNest_ |
|
private |
Interrupt nesting up-down counter (used in some QF ports )
Definition at line 1423 of file qf.h.
◆ QF_readySet_
"Ready-set" of all threads used in the built-in kernels
Definition at line 62 of file qf_pkg.h.
The documentation for this class was generated from the following files: