QP/C  6.3.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...
 

Macros

#define QF_EQUEUE_TYPE   QEQueue
 Kernel-dependent type of the event queue used for QK threads. More...
 
#define QF_THREAD_TYPE   void*
 Kernel-dependent type of the thread attribute in QK. 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 != (uint8_t)0)
 Internal macro that reports the execution context (ISR vs. More...
 
#define QF_SCHED_STAT_   QSchedStatus lockStat_;
 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(110, (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_)))
 

Typedefs

typedef uint_fast16_t QSchedStatus
 QK Scheduler locking. More...
 

Functions

void QK_onContextSw (struct QActive *prev, struct QActive *next)
 QK context switch callback (customized in BSPs for QK) More...
 
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...
 
QSchedStatus QK_schedLock (uint_fast8_t ceiling)
 QK Scheduler lock. More...
 
void QK_schedUnlock (QSchedStatus stat)
 QK Scheduler 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 68 of file qk.h.

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

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

#define QF_EQUEUE_TYPE   QEQueue

Kernel-dependent type of the event queue used for QK threads.

Description
QK uses the native QP event queue QEQueue.

Definition at line 56 of file qk.h.

◆ QF_THREAD_TYPE

#define QF_THREAD_TYPE   void*

Kernel-dependent type of the thread attribute in QK.

Description
QK uses this member to store the private Thread-Local Storage pointer.

Definition at line 63 of file qk.h.

◆ QK_ISR_CONTEXT_

#define QK_ISR_CONTEXT_ ( )    (QK_attr_.intNest != (uint8_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 160 of file qk.h.

◆ QF_SCHED_LOCK_

#define QF_SCHED_LOCK_ (   prio_)
Value:
do { \
if (QK_ISR_CONTEXT_()) { \
lockStat_ = (QSchedStatus)0xFF; \
} else { \
lockStat_ = QK_schedLock((prio_)); \
} \
} while (0)
#define QK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qk.h:160
uint_fast16_t QSchedStatus
QK Scheduler locking.
Definition: qk.h:138
QSchedStatus QK_schedLock(uint_fast8_t ceiling)
QK Scheduler lock.
Definition: qk.c:246

Internal macro for selective scheduler locking.

Definition at line 170 of file qk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )
Value:
do { \
if (lockStat_ != (QSchedStatus)0xFF) { \
QK_schedUnlock(lockStat_); \
} \
} while (0)
uint_fast16_t QSchedStatus
QK Scheduler locking.
Definition: qk.h:138

Internal macro for selective scheduler unlocking.

Definition at line 179 of file qk.h.

◆ QACTIVE_EQUEUE_SIGNAL_

#define QACTIVE_EQUEUE_SIGNAL_ (   me_)
Value:
do { \
QPSet_insert(&QK_attr_.readySet, (uint_fast8_t)(me_)->prio); \
if (!QK_ISR_CONTEXT_()) { \
if (QK_sched_() != (uint_fast8_t)0) { \
QK_activate_(); \
} \
} \
} while (0)
QPSet readySet
QK ready-set of AOs.
Definition: qk.h:74
#define QK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qk.h:160
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
uint_fast8_t QK_sched_(void)
QK scheduler finds the highest-priority thread ready to run.
Definition: qk.c:344

Definition at line 189 of file qk.h.

Typedef Documentation

◆ QSchedStatus

QK Scheduler locking.

The scheduler lock status

Definition at line 138 of file qk.h.

Function Documentation

◆ QK_onContextSw()

void QK_onContextSw ( struct QActive prev,
struct QActive next 
)

QK context switch callback (customized in BSPs for QK)

Description
This callback function provides a mechanism to perform additional custom operations when QK switches context from one thread to another.
Parameters
[in]prevpointer to the previous thread (active object) (prev==0 means that prev was the QK idle loop)
[in]nextpointer to the next thread (active object) (next==0) means that next is the QK idle loop)
Attention
QK_onContextSw() is invoked with interrupts disabled and must also return with interrupts disabled.
Note
This callback is enabled by defining the macro QK_ON_CONTEXT_SW.
#ifdef QK_ON_CONTEXT_SW
/* NOTE: the context-switch callback is called with interrupts DISABLED */
void QK_onContextSw(QActive *prev, QActive *next) {
(void)prev;
if (next != (QActive *)0) { /* next is not the QK idle loop? */
_impure_ptr = next->thread; /* switch to next TLS */
}
/* If you use QS software tracing, use the _NOCRIT() begin/end */
QS_BEGIN_NOCRIT(ON_CONTEXT_SW, (void *)1)
QS_OBJ(prev);
QS_OBJ(next);
}
#endif /* QK_ON_CONTEXT_SW */

◆ QK_onIdle()

void QK_onIdle ( void  )

QK idle callback (customized in BSPs for QK)

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

◆ 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 374 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 246 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 296 of file qk.c.