QP/C 6.9.1
qxk.c File Reference

QXK preemptive dual-mode kernel core functions. More...

#include "qf_port.h"
#include "qxk_pkg.h"
#include "qassert.h"
#include "qs_port.h"
#include "qs_pkg.h"
Include dependency graph for qxk.c:

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 More...
 
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 **const qSto, uint_fast16_t const qLen, void *const stkSto, uint_fast16_t const stkSize, void const *const par)
 Implementation of the active object start operation. More...
 
QSchedStatus QXK_schedLock (uint_fast8_t ceiling)
 QXK Scheduler lock. More...
 
void QXK_schedUnlock (QSchedStatus stat)
 QXK Scheduler unlock. More...
 
uint_fast8_t QXK_sched_ (void)
 QXK scheduler finds the highest-priority thread ready to run. More...
 
void QXK_activate_ (void)
 QXK activator activates the next active object. More...
 
struct QActiveQXK_current (void)
 return the currently executing active-object/thread More...
 

Variables

QXK_PrivAttr QXK_attr_
 global attributes of the QXK kernel More...
 
static QActive l_idleThread
 

Detailed Description

QXK preemptive dual-mode kernel core functions.

Definition in file qxk.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 75 of file qxk.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.
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 115 of file qxk.c.

◆ initial_events()

static void initial_events ( void  )
static

process all events posted during initialization

Definition at line 123 of file qxk.c.

◆ QF_run()

int_t QF_run ( void  )

Transfers control to QF to run the application.

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 140 of file qxk.c.

◆ QActive_start_()

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

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 (used only when per-AO stack is needed)
[in]stkSizestack size [bytes]
[in]parpointer to an extra parameter (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:
#include "qpc.h"
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;
  • the stack storage must NOT be provided (because the QK kernel does not need per-AO stacks).

Definition at line 184 of file qxk.c.

◆ QXK_schedLock()

QSchedStatus QXK_schedLock ( uint_fast8_t  ceiling)

QXK Scheduler lock.

Description
This function locks the QXK scheduler to the specified ceiling.
Parameters
[in]ceilingpriority ceiling to which the QXK scheduler needs to be locked
Returns
The previous QXK Scheduler lock status, which is to be used to unlock the scheduler by restoring its previous lock status in QXK_schedUnlock().
Note
A QXK scheduler can be locked from both basic threads (AOs) and extended threads and the scheduler locks can nest.
QXK_schedLock() must be always followed by the corresponding QXK_schedUnlock().
Attention
QXK will fire an assertion if a thread holding the lock attempts to block.
See also
QXK_schedUnlock()
Usage
The following example shows how to lock and unlock the QXK scheduler:
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QSchedStatus lockStat;
lockStat = QXK_schedLock(N_PHILO); /* lock scheduler around shared seed */
/* "Super-Duper" Linear Congruential Generator (LCG) */
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QXK_schedLock(lockStat); /* unlock the scheduler */
return rnd;
}
Precondition
The QXK scheduler lock:
  • cannot be called from an ISR;

Definition at line 249 of file qxk.c.

◆ QXK_schedUnlock()

void QXK_schedUnlock ( QSchedStatus  stat)

QXK Scheduler unlock.

Description
This function unlocks the QXK scheduler to the previous status.
Parameters
[in]statprevious QXK Scheduler lock status returned from QXK_schedLock()
Note
A QXK scheduler can be locked from both basic threads (AOs) and extended threads and the scheduler locks can nest.
QXK_schedUnlock() must always follow the corresponding QXK_schedLock().
See also
QXK_schedLock()
Usage
The following example shows how to lock and unlock the QXK scheduler:
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QSchedStatus lockStat;
lockStat = QXK_schedLock(N_PHILO); /* lock scheduler around shared seed */
/* "Super-Duper" Linear Congruential Generator (LCG) */
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QXK_schedLock(lockStat); /* unlock the scheduler */
return rnd;
}
Precondition
The scheduler cannot be unlocked:
  • from the ISR context; and
  • the current lock priority must be greater than the previous

Definition at line 305 of file qxk.c.

◆ QXK_sched_()

uint_fast8_t QXK_sched_ ( void  )

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

Description
The QXK scheduler finds the priority of the highest-priority thread that is ready to run.
Returns
the 1-based priority of the the thread (basic or extended) run next, or zero if no eligible thread is found.
Attention
QXK_sched_() must be always called with interrupts disabled and returns with interrupts disabled.

Definition at line 353 of file qxk.c.

◆ QXK_activate_()

void QXK_activate_ ( void  )

QXK activator activates the next active object.

Attention
QXK_activate_() must be always called with interrupts disabled and returns with interrupts disabled.
Note
The activate function might enable interrupts internally, but it always returns with interrupts disabled.
Precondition
QXK_attr_.next must be valid

Definition at line 431 of file qxk.c.

◆ QXK_current()

struct QActive* QXK_current ( void  )

return the currently executing active-object/thread

Precondition
the QXK kernel must be running
Postcondition
the current thread must be valid

Definition at line 565 of file qxk.c.

Variable Documentation

◆ QXK_attr_

QXK_PrivAttr QXK_attr_

global attributes of the QXK kernel

Definition at line 59 of file qxk.c.

◆ l_idleThread

QActive l_idleThread
static

Definition at line 62 of file qxk.c.

qpc.h
QP/C public interface including backwards-compatibility layer.
QXK_schedLock
QSchedStatus QXK_schedLock(uint_fast8_t ceiling)
QXK Scheduler lock.
Definition: qxk.c:249
Q_DEFINE_THIS_FILE
#define Q_DEFINE_THIS_FILE
Define the file name (with __FILE__) for assertions in this file.
Definition: qassert.h:104
QActive::QACTIVE_START
#define QACTIVE_START(me_, prio_, qSto_, qLen_, stkSto_, stkLen_, par_)
Polymorphically start an active object.
Definition: qf.h:216
Q_DIM
#define Q_DIM(array_)
Helper macro to calculate static dimension of a 1-dim array_.
Definition: qassert.h:337
QActive
Active Object base class (based on QHsm implementation)
Definition: qf.h:116
uint_fast8_t
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: 16bit/stdint.h:36
QSchedStatus
uint_fast16_t QSchedStatus
QK Scheduler locking.
Definition: qk.h:132
QEvt
Event class.
Definition: qep.h:151
uint32_t
unsigned long int uint32_t
exact-width 32-bit unsigned int
Definition: 16bit/stdint.h:31