QP/C  6.0.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
 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 != (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_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 61 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

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.

◆ 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 124 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:124
uint_fast16_t QSchedStatus
QK Scheduler locking.
Definition: qk.h:102
QSchedStatus QK_schedLock(uint_fast8_t ceiling)
QK Scheduler lock.
Definition: qk.c:245

Internal macro for selective scheduler locking.

Definition at line 134 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:102

Internal macro for selective scheduler unlocking.

Definition at line 143 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:69
#define QK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qk.h:124
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:343

Definition at line 153 of file qk.h.

Typedef Documentation

◆ QSchedStatus

QK Scheduler locking.

The scheduler lock status

Definition at line 102 of file qk.h.

Function Documentation

◆ 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 343 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 373 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.