QP/C  5.8.2
qk.h File Reference

QK/C (preemptive non-blocking kernel) platform-independent public interface. More...

#include "qequeue.h"
#include "qmpool.h"
#include "qpset.h"

Go to the source code of this file.

Data Structures

struct  QK_Attr
 attributes of the QK kernel More...
 
struct  QMutex
 QK priority-ceiling mutex class. More...
 

Macros

#define QF_EQUEUE_TYPE   QEQueue
 This macro defines the type of the event queue used for the active objects. More...
 
#define QK_getVersion()   (QP_versionStr)
 get the current QK version number string of the form "X.Y.Z"
 
#define QK_ISR_CONTEXT_()   (QK_attr_.intNest != (uint_fast8_t)0)
 Internal macro that reports the execution context (ISR vs. More...
 
#define QF_SCHED_STAT_   QMutex schedLock_;
 Internal macro to represent the scheduler lock status that needs to be preserved to allow nesting of locks.
 
#define QF_SCHED_LOCK_(prio_)
 Internal macro for selective scheduler locking. More...
 
#define QF_SCHED_UNLOCK_()
 Internal macro for selective scheduler unlocking. More...
 
#define QACTIVE_EQUEUE_WAIT_(me_)   (Q_ASSERT_ID(0, (me_)->eQueue.frontEvt != (QEvt *)0))
 
#define QACTIVE_EQUEUE_SIGNAL_(me_)
 
#define QF_EPOOL_TYPE_   QMPool
 
#define QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_)   (QMPool_init(&(p_), (poolSto_), (poolSize_), (evtSize_)))
 
#define QF_EPOOL_EVENT_SIZE_(p_)   ((uint_fast16_t)(p_).blockSize)
 
#define QF_EPOOL_GET_(p_, e_, m_)   ((e_) = (QEvt *)QMPool_get(&(p_), (m_)))
 
#define QF_EPOOL_PUT_(p_, e_)   (QMPool_put(&(p_), (e_)))
 

Functions

void QK_onIdle (void)
 QK idle callback (customized in BSPs for QK) 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...
 
void QMutex_init (QMutex *const me, uint_fast8_t prio)
 The QMutex initialization. More...
 
void QMutex_lock (QMutex *const me)
 QMutex lock. More...
 
void QMutex_unlock (QMutex *const me)
 QMutex unlock. More...
 

Variables

QK_Attr QK_attr_
 global attributes of the QK kernel
 

Detailed Description

QK/C (preemptive non-blocking kernel) platform-independent public interface.

Definition in file qk.h.


Data Structure Documentation

◆ QK_Attr

struct QK_Attr

attributes of the QK kernel

Definition at line 61 of file qk.h.

Data Fields
uint_fast8_t volatile actPrio prio of the active AO
uint_fast8_t volatile intNest ISR nesting level.
uint_fast8_t volatile lockHolder prio of the AO holding the lock
uint_fast8_t volatile lockPrio lock prio (0 == no-lock)
uint_fast8_t volatile nextPrio prio of the next AO to execute
QPSet readySet QK ready-set of AOs.

◆ QMutex

struct QMutex

QK priority-ceiling mutex class.

Definition at line 100 of file qk.h.

Data Fields
uint_fast8_t lockPrio lock prio (priority ceiling)
uint_fast8_t prevPrio previoius lock prio

Macro Definition Documentation

◆ QACTIVE_EQUEUE_SIGNAL_

#define QACTIVE_EQUEUE_SIGNAL_ (   me_)
Value:
do { \
QPSet_insert(&QK_attr_.readySet, (me_)->prio); \
if (!QK_ISR_CONTEXT_()) { \
if (QK_sched_() != (uint_fast8_t)0) { \
QK_activate_(); \
} \
} \
} while (0)
#define QK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qk.h:128
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35
QK_Attr QK_attr_
global attributes of the QK kernel
Definition: qk.c:58
QPSet readySet
QK ready-set of AOs.
Definition: qk.h:69
uint_fast8_t QK_sched_(void)
QK scheduler finds the highest-priority thread ready to run.
Definition: qk.c:239

Definition at line 158 of file qk.h.

◆ QF_EQUEUE_TYPE

#define QF_EQUEUE_TYPE   QEQueue

This macro defines the type of the event queue used for the active objects.

Description
QK uses the native QF event queue QEQueue.

Definition at line 57 of file qk.h.

◆ QF_SCHED_LOCK_

#define QF_SCHED_LOCK_ (   prio_)
Value:
do { \
if (QK_ISR_CONTEXT_()) { \
schedLock_.lockPrio = (uint_fast8_t)0; \
} else { \
QMutex_init(&schedLock_, (prio_)); \
QMutex_lock(&schedLock_); \
} \
} while (0)
#define QK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qk.h:128
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35

Internal macro for selective scheduler locking.

Definition at line 138 of file qk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )
Value:
do { \
if (schedLock_.lockPrio != (uint_fast8_t)0) { \
QMutex_unlock(&schedLock_); \
} \
} while (0)
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35

Internal macro for selective scheduler unlocking.

Definition at line 148 of file qk.h.

◆ QK_ISR_CONTEXT_

#define QK_ISR_CONTEXT_ ( )    (QK_attr_.intNest != (uint_fast8_t)0)

Internal macro that reports the execution context (ISR vs.

thread)

Returns
true if the code executes in the ISR context and false otherwise

Definition at line 128 of file qk.h.

Function Documentation

◆ QK_activate_()

void QK_activate_ ( void  )

QK activator activates the next active object.

The activated AO preempts the currently executing AOs.

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 269 of file qk.c.

◆ QK_onIdle()

void QK_onIdle ( void  )

QK idle callback (customized in BSPs for QK)

QK_onIdle() is called continuously by the QK idle loop. This callback gives the application an opportunity to enter a power-saving CPU mode, or perform some other idle processing.

Note
QK_onIdle() is invoked with interrupts enabled and must also return with interrupts enabled.
See also
QV_onIdle()

◆ 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 239 of file qk.c.

◆ QMutex_init()

void QMutex_init ( QMutex *const  me,
uint_fast8_t  prio 
)

The QMutex initialization.

Description
Initializes QK priority-ceiling mutex to the specified ceiling priority.
Parameters
[in,out]mepointer (see Object Orientation)
[in]prioceiling priority of the mutex
Note
A mutex must be initialized before it can be locked or unlocked.
See also
QMutex_lock(), QMutex_unlock()
Usage
The following example shows how to initialize, lock and unlock QK mutex:
QMutex l_rndMutex; /* mutex to protect the random number generator */
void BSP_randomSeed(uint32_t seed) {
QMutex_init(&l_rndMutex, N_PHILO); /* ceiling == max Philo priority */
l_rnd = seed;
}
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QMutex_lock(&l_rndMutex); /* <== lock the shared random seed */
/* "Super-Duper" Linear Congruential Generator (LCG) */
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}

Definition at line 78 of file qk_mutex.c.

◆ QMutex_lock()

void QMutex_lock ( QMutex *const  me)

QMutex lock.

Description
This function locks the QK mutex.
Parameters
[in,out]mepointer (see Object Orientation)
Note
A mutex must be initialized before it can be locked or unlocked.
QMutex_lock() must be always followed by the corresponding QMutex_unlock().
See also
QMutex_init(), QMutex_unlock()
Usage
The following example shows how to initialize, lock and unlock QK mutex:
QMutex l_rndMutex; /* mutex to protect the random number generator */
void BSP_randomSeed(uint32_t seed) {
QMutex_init(&l_rndMutex, N_PHILO); /* ceiling == max Philo priority */
l_rnd = seed;
}
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QMutex_lock(&l_rndMutex); /* <== lock the shared random seed */
/* "Super-Duper" Linear Congruential Generator (LCG) */
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}
Precondition
scheduler cannot be locked from the ISR context and the mutex must be unused

Definition at line 103 of file qk_mutex.c.

◆ QMutex_unlock()

void QMutex_unlock ( QMutex *const  me)

QMutex unlock.

Description
This function unlocks the QK mutex.
Parameters
[in]mepointer (see Object Orientation)
Note
A mutex must be initialized before it can be locked or unlocked.
QMutex_unlock() must always follow the corresponding QMutex_lock().
See also
QMutex_init(), QMutex_lock()
Usage
The following example shows how to initialize, lock and unlock QK mutex:
QMutex l_rndMutex; /* mutex to protect the random number generator */
void BSP_randomSeed(uint32_t seed) {
QMutex_init(&l_rndMutex, N_PHILO); /* ceiling == max Philo priority */
l_rnd = seed;
}
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QMutex_lock(&l_rndMutex); /* <== lock the shared random seed */
/* "Super-Duper" Linear Congruential Generator (LCG) */
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}
Precondition
scheduler cannot be unlocked from the ISR context and the mutex must NOT be unused

Definition at line 146 of file qk_mutex.c.