QP/C 6.9.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"
Include dependency graph for qk.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  QK_PrivAttr
 private attributes of the QK kernel More...
 

Macros

#define QF_EQUEUE_TYPE   QEQueue
 
#define QF_THREAD_TYPE   void*
 
#define QK_ISR_CONTEXT_()   (QK_attr_.intNest != 0U)
 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. More...
 
#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_, qs_id_)    ((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qs_id_)))
 
#define QF_EPOOL_PUT_(p_, e_, qs_id_)    (QMPool_put(&(p_), (e_), (qs_id_)))
 

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_PrivAttr QK_attr_
 global private attributes of the QK kernel More...
 

Detailed Description

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

Definition in file qk.h.


Data Structure Documentation

◆ QK_PrivAttr

struct QK_PrivAttr

private attributes of the QK kernel

Definition at line 62 of file qk.h.

Collaboration diagram for QK_PrivAttr:
Collaboration graph
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

Definition at line 52 of file qk.h.

◆ QF_THREAD_TYPE

#define QF_THREAD_TYPE   void*

Definition at line 57 of file qk.h.

◆ QK_ISR_CONTEXT_

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

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 150 of file qk.h.

◆ QF_SCHED_STAT_

#define QF_SCHED_STAT_   QSchedStatus lockStat_;

Internal macro to represent the scheduler lock status that needs to be preserved to allow nesting of locks.

Definition at line 157 of file qk.h.

◆ QF_SCHED_LOCK_

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

Internal macro for selective scheduler locking.

Definition at line 160 of file qk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )
Value:
do { \
if (lockStat_ != 0xFFU) { \
QK_schedUnlock(lockStat_); \
} \
} while (false)

Internal macro for selective scheduler unlocking.

Definition at line 169 of file qk.h.

◆ QACTIVE_EQUEUE_WAIT_

#define QACTIVE_EQUEUE_WAIT_ (   me_)     (Q_ASSERT_ID(110, (me_)->eQueue.frontEvt != (QEvt *)0))

Definition at line 176 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_() != 0U) { \
QK_activate_(); \
} \
} \
} while (false)
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: 16bit/stdint.h:36
QPSet readySet
QK ready-set of AOs.
Definition: qk.h:68
uint_fast8_t QK_sched_(void)
QK scheduler finds the highest-priority thread ready to run.
Definition: qk.c:329
QK_PrivAttr QK_attr_
global private attributes of the QK kernel
Definition: qk.c:59

Definition at line 179 of file qk.h.

◆ QF_EPOOL_TYPE_

#define QF_EPOOL_TYPE_   QMPool

Definition at line 189 of file qk.h.

◆ QF_EPOOL_INIT_

#define QF_EPOOL_INIT_ (   p_,
  poolSto_,
  poolSize_,
  evtSize_ 
)     (QMPool_init(&(p_), (poolSto_), (poolSize_), (evtSize_)))

Definition at line 190 of file qk.h.

◆ QF_EPOOL_EVENT_SIZE_

#define QF_EPOOL_EVENT_SIZE_ (   p_)    ((uint_fast16_t)(p_).blockSize)

Definition at line 192 of file qk.h.

◆ QF_EPOOL_GET_

#define QF_EPOOL_GET_ (   p_,
  e_,
  m_,
  qs_id_ 
)     ((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qs_id_)))

Definition at line 193 of file qk.h.

◆ QF_EPOOL_PUT_

#define QF_EPOOL_PUT_ (   p_,
  e_,
  qs_id_ 
)     (QMPool_put(&(p_), (e_), (qs_id_)))

Definition at line 195 of file qk.h.

Typedef Documentation

◆ QSchedStatus

QK Scheduler locking.

The scheduler lock status

Definition at line 132 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, QS_AP_ID + 1)
QS_OBJ(prev);
QS_OBJ(next);
}
#endif /* QK_ON_CONTEXT_SW */
void QK_onContextSw(struct QActive *prev, struct QActive *next)
QK context switch callback (customized in BSPs for QK)
#define QS_OBJ(obj_)
Output formatted object pointer to the QS record.
Definition: qs.h:672
#define QS_END_NOCRIT()
End a QS user record without exiting critical section.
Definition: qs.h:545
@ QS_AP_ID
offset for Application-specific IDs
Definition: qs.h:231
#define QS_BEGIN_NOCRIT(rec_, qs_id_)
Begin a QS user record without entering critical section.
Definition: qs.h:539
Active Object base class (based on QHsm implementation)
Definition: qf.h:116

◆ 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 329 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 359 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);
}
unsigned long int uint32_t
exact-width 32-bit unsigned int
Definition: 16bit/stdint.h:31
uint_fast16_t QSchedStatus
QK Scheduler locking.
Definition: qk.h:132
void QK_schedUnlock(QSchedStatus stat)
QK Scheduler unlock.
Definition: qk.c:280
Precondition
The QK scheduler lock:
  • cannot be called from an ISR;

Definition at line 230 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 280 of file qk.c.

Variable Documentation

◆ QK_attr_

QK_PrivAttr QK_attr_
extern

global private attributes of the QK kernel

Definition at line 59 of file qk.c.