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:

Data Structures
struct	QK_PrivAttr
	private 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_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_) ((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_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 68 of file qk.h.

Collaboration diagram for QK_PrivAttr:

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 57 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 64 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 157 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 164 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)

Internal macro for selective scheduler locking.

Definition at line 167 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 176 of file qk.h.

◆ QACTIVE_EQUEUE_WAIT_

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

Definition at line 183 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)

Definition at line 186 of file qk.h.

◆ QF_EPOOL_TYPE_

#define QF_EPOOL_TYPE_ QMPool

Definition at line 196 of file qk.h.

◆ QF_EPOOL_INIT_

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

Definition at line 197 of file qk.h.

◆ QF_EPOOL_EVENT_SIZE_

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

Definition at line 199 of file qk.h.

◆ QF_EPOOL_GET_

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

Definition at line 200 of file qk.h.

◆ QF_EPOOL_PUT_

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

Definition at line 201 of file qk.h.

Typedef Documentation

◆ QSchedStatus

typedef uint_fast16_t 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]	prev	pointer to the previous thread (active object) (prev==0 means that `prev` was the QK idle loop)
[in]	next	pointer 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);
    QS_END_NOCRIT()
}
#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 323 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 353 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] ceiling priority 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 225 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] stat previous 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 275 of file qk.c.

Variable Documentation

◆ QK_attr_

QK_PrivAttr QK_attr_

global private attributes of the QK kernel

Definition at line 59 of file qk.c.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Data Structure Documentation

◆ QK_PrivAttr

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

◆ QF_THREAD_TYPE

◆ QK_ISR_CONTEXT_

◆ QF_SCHED_STAT_

◆ QF_SCHED_LOCK_

◆ QF_SCHED_UNLOCK_

◆ QACTIVE_EQUEUE_WAIT_

◆ QACTIVE_EQUEUE_SIGNAL_

◆ QF_EPOOL_TYPE_

◆ QF_EPOOL_INIT_

◆ QF_EPOOL_EVENT_SIZE_

◆ QF_EPOOL_GET_

◆ QF_EPOOL_PUT_

Typedef Documentation

◆ QSchedStatus

Function Documentation

◆ QK_onContextSw()

◆ QK_onIdle()

◆ QK_sched_()

◆ QK_activate_()

◆ QK_schedLock()

◆ QK_schedUnlock()

Variable Documentation

◆ QK_attr_