QP/C  6.0.0
qk.c File Reference

QK preemptive kernel core functions. More...

#include "qf_port.h"
#include "qf_pkg.h"
#include "qassert.h"
#include "qs_port.h"

Go to the source code of this file.

Functions

void QF_init (void)
 QF initialization. More...
 
void QF_stop (void)
 Function invoked by the application layer to stop the QF application and return control to the OS/Kernel. More...
 
static void initial_events (void)
 process all events posted during initialization
 
int_t QF_run (void)
 Transfers control to QF to run the application. More...
 
void QActive_start_ (QActive *const me, uint_fast8_t prio, QEvt const *qSto[], uint_fast16_t qLen, void *stkSto, uint_fast16_t stkSize, QEvt const *ie)
 Implementation of the active object start operation. More...
 
void QActive_stop (QActive *const me)
 Stops execution of an active object and removes it from the framework's supervision. More...
 
QSchedStatus QK_schedLock (uint_fast8_t ceiling)
 QK Scheduler lock. More...
 
void QK_schedUnlock (QSchedStatus stat)
 QK Scheduler unlock. More...
 
uint_fast8_t QK_sched_ (void)
 QK scheduler finds the highest-priority thread ready to run. More...
 
void QK_activate_ (void)
 QK activator activates the next active object. More...
 

Variables

QK_Attr QK_attr_
 global attributes of the QK kernel
 

Detailed Description

QK preemptive kernel core functions.

Definition in file qk.c.

Function Documentation

◆ QF_init()

void QF_init ( void  )

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

Definition at line 71 of file qk.c.

◆ QF_stop()

void QF_stop ( void  )

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.
See also
QF_onCleanup()

Definition at line 100 of file qk.c.

◆ QF_run()

int_t QF_run ( void  )

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
In QK, the QF_run() function does not return.

Definition at line 125 of file qk.c.

◆ QActive_start_()

void QActive_start_ ( QActive *const  me,
uint_fast8_t  prio,
QEvt const *  qSto[],
uint_fast16_t  qLen,
void *  stkSto,
uint_fast16_t  stkSize,
QEvt const *  ie 
)

Implementation of the active object start operation.

Description
Starts execution of the AO and registers the AO with the framework. Also takes the top-most initial transition in the AO's state machine. This initial transition is taken in the callee's thread of execution.
Parameters
[in,out]mepointer (see Object Orientation)
[in]priopriority at which to start the active object
[in]qStopointer to the storage for the ring buffer of the event queue (used only with the built-in QEQueue)
[in]qLenlength of the event queue [events]
[in]stkStopointer to the stack storage (must be NULL in QK)
[in]stkSizestack size [bytes]
[in]iepointer to the initial event (might be NULL).
Note
This function should be called via the macro QACTIVE_START().
Usage
The following example shows starting an AO when a per-task stack is needed:
int main() {
static Philo l_philo[N]; /* N Philo active objects */
static QEvt const *l_philQueueSto[N][N]; /* storage for event queues */
static int l_philoStk[N][256]; /* stacks for the Philo active objects */
. . .
for (n = 0; n < N; ++n) {
TableEvt ie; /* initialization event for the Philo SM */
ie.philNum = n;
Philo_ctor(&l_philo[n]);
QACTIVE_START((QActive *)&l_philo[n], /* Philo pointer */
(uint_fast8_t)(n*10 + 1), /* priority */
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]), /* queue */
l_philoStk[n], sizeof(l_philoStk[n]), /* per AO stack */
&ie.super); /* initialization event */
}
. . .
}
Precondition
AO cannot be started from an ISR, the priority must be in range and the stack storage must not be provided, because the QK kernel does not need per-AO stacks.

Definition at line 162 of file qk.c.

◆ QActive_stop()

void QActive_stop ( QActive *const  me)

Stops execution of an active object and removes it from the framework's supervision.

Description
This function must be called from within the AO that needs to stop. In other words, an AO should stop itself rather than being stopped by someone else. This policy works best, because only the AO itself "knows" when it has reached the appropriate state for the shutdown.
Note
By the time the AO calls QActive_stop(), it should have unsubscribed from all events and no more events should be directly-posted to it.
Precondition
QActive_stop() must be called from the AO that wants to stop.

Definition at line 207 of file qk.c.

◆ QK_schedLock()

QSchedStatus QK_schedLock ( uint_fast8_t  ceiling)

QK Scheduler lock.

Description
This function locks the QK scheduler to the specified ceiling.
Parameters
[in]ceilingpriority ceiling to which the QK scheduler needs to be locked
Returns
The previous QK Scheduler lock status, which is to be used to unlock the scheduler by restoring its previous lock status in QK_schedUnlock().
Note
QK_schedLock() must be always followed by the corresponding QK_schedUnlock().
See also
QK_schedUnlock()
Usage
The following example shows how to lock and unlock the QK scheduler:
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QSchedStatus lockStat; /* <=== QK scheduler lock status */
lockStat = QK_schedLock(N_PHILO); /* <=== lock scheduler up to N_PHILO prio */
/* "Super-Duper" Linear Congruential Generator (LCG)
* LCG(2^32, 3*7*11*13*23, 0, seed)
*/
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QK_schedUnlock(lockStat); /* <=== unlock the scheduler */
return (rnd >> 8);
}
Precondition
The QK scheduler lock:
  • cannot be called from an ISR;

Definition at line 245 of file qk.c.

◆ QK_schedUnlock()

void QK_schedUnlock ( QSchedStatus  stat)

QK Scheduler unlock.

Description
This function unlocks the QK scheduler to the previous status.
Parameters
[in]statprevious QK Scheduler lock status returned from QK_schedLock()
Note
QK_schedUnlock() must always follow the corresponding QK_schedLock().
See also
QK_schedLock()
Usage
The following example shows how to lock and unlock the QK scheduler:
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QSchedStatus lockStat; /* <=== QK scheduler lock status */
lockStat = QK_schedLock(N_PHILO); /* <=== lock scheduler up to N_PHILO prio */
/* "Super-Duper" Linear Congruential Generator (LCG)
* LCG(2^32, 3*7*11*13*23, 0, seed)
*/
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QK_schedUnlock(lockStat); /* <=== unlock the scheduler */
return (rnd >> 8);
}
Precondition
The scheduler cannot be unlocked:
  • from the ISR context; and
  • the current lock priority must be greater than the previous

Definition at line 295 of file qk.c.

◆ QK_sched_()

uint_fast8_t QK_sched_ ( void  )

QK scheduler finds the highest-priority thread ready to run.

Description
The QK scheduler finds out the priority of the highest-priority AO that (1) has events to process and (2) has priority that is above the current priority.
Returns
the 1-based priority of the the active object, or zero if no eligible active object is ready to run.
Attention
QK_sched_() must be always called with interrupts disabled and returns with interrupts disabled.

Definition at line 343 of file qk.c.

◆ QK_activate_()

void QK_activate_ ( void  )

QK activator activates the next active object.

Description
QK_activate_() activates ready-to run AOs that are above the initial active priority (QK_attr_.actPrio).
Note
The activator might enable interrupts internally, but always returns with interrupts disabled.

Definition at line 373 of file qk.c.