QP-nano  6.6.0
qkn.h File Reference

Public QK-nano interface. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  QK_Attr
 attributes of the QK kernel More...
 

Macros

#define QK_SCHEDULE_()
 

Typedefs

typedef uint_fast16_t QSchedStatus
 QK-nano Scheduler locking. More...
 

Functions

uint_fast8_t QK_sched_ (void)
 QK-nano scheduler finds the highest-priority thread ready to run. More...
 
void QK_activate_ (void)
 QK activator activates the next active object. More...
 
void QK_onContextSw (uint_fast8_t prev, uint_fast8_t next)
 QK-nano context switch callback (customized in BSPs for QK-nano) More...
 
void QK_onIdle (void)
 QK idle callback (customized in BSPs for QK) 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 More...
 

Detailed Description

Public QK-nano interface.

Definition in file qkn.h.


Data Structure Documentation

◆ QK_Attr

struct QK_Attr

attributes of the QK kernel

Definition at line 45 of file qkn.h.

Collaboration diagram for QK_Attr:
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 lock holder

Macro Definition Documentation

◆ QK_SCHEDULE_

#define QK_SCHEDULE_ ( )
Value:
do { \
if (QK_sched_() != (uint_fast8_t)0) { \
QK_activate_(); \
} \
} while(0)

Definition at line 70 of file qkn.h.

Typedef Documentation

◆ QSchedStatus

QK-nano Scheduler locking.

The scheduler lock status

Definition at line 130 of file qkn.h.

Function Documentation

◆ QK_sched_()

uint_fast8_t QK_sched_ ( void  )

QK-nano scheduler finds the highest-priority thread ready to run.

Description
The QK-nano 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 247 of file qkn.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 293 of file qkn.c.

◆ QK_onContextSw()

void QK_onContextSw ( uint_fast8_t  prev,
uint_fast8_t  next 
)

QK-nano context switch callback (customized in BSPs for QK-nano)

Description
This callback function provides a mechanism to perform additional custom operations when QK switches context from one thread to another.
Parameters
[in]prevpriority of the previous thread (active object) (prev==0 means that prev was the QK idle loop)
[in]nextpriority of 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)prev;
if (next != (uint_fast8_t)0) {
//_impure_ptr = &reentrant[next];
}
}
#endif /* QK_ON_CONTEXT_SW */

◆ QK_onIdle()

void QK_onIdle ( void  )

QK idle callback (customized in BSPs for QK)

QK_onIdle() is called continuously by the QK-nano 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. This is in contrast to the callback QF_onIdle(), which is used by the non-preemptive QF-nano scheduler.

◆ 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-nano 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);
}

Definition at line 161 of file qkn.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-nano 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 current lock priority must be greater than the previous

Definition at line 200 of file qkn.c.

Variable Documentation

◆ QK_attr_

QK_Attr QK_attr_

global attributes of the QK kernel

Definition at line 52 of file qkn.c.

QK_schedUnlock
void QK_schedUnlock(QSchedStatus stat)
QK Scheduler unlock.
Definition: qkn.c:200
QK_sched_
uint_fast8_t QK_sched_(void)
QK-nano scheduler finds the highest-priority thread ready to run.
Definition: qkn.c:247
QK_schedLock
QSchedStatus QK_schedLock(uint_fast8_t ceiling)
QK Scheduler lock.
Definition: qkn.c:161
QSchedStatus
uint_fast16_t QSchedStatus
QK-nano Scheduler locking.
Definition: qkn.h:130
uint_fast8_t
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:36
QK_onContextSw
void QK_onContextSw(uint_fast8_t prev, uint_fast8_t next)
QK-nano context switch callback (customized in BSPs for QK-nano)
uint32_t
unsigned long uint32_t
exact-width 32-bit unsigned int
Definition: stdint.h:31