QXK/C (preemptive dual-mode kernel) platform-independent public interface. More...

#include "qequeue.h"
#include "qmpool.h"
#include "qpset.h"

Include dependency graph for qxk.h:

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

Data Structures
struct	QXK_PrivAttr
	attributes of the QXK kernel More...

Macros
#define	QF_EQUEUE_TYPE QEQueue
	Kernel-dependent type of the event queue used for QXK threads. More...

#define	QF_OS_OBJECT_TYPE void*
	Kernel-dependent OS-attribute of threads in QXK. More...

#define	QF_THREAD_TYPE void*
	Kernel-dependent type of the thread attribute in QXK. More...

#define	QXK_TLS(type_) ((type_)QXK_current()->thread)
	Access Thread-Local Storage (TLS) and cast it on the given `type_`. More...

#define	QXK_ISR_CONTEXT_() (QXK_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
	QXK Scheduler locking. More...

Functions
void	QXK_onContextSw (struct QActive prev, struct QActive next)
	QXK context switch callback (customized in BSPs for QXK) More...

void	QXK_onIdle (void)
	QXK idle callback (customized in BSPs for QXK) More...

uint_fast8_t	QXK_sched_ (void)
	QXK scheduler finds the highest-priority thread ready to run. More...

void	QXK_activate_ (void)
	QXK activator activates the next active object. More...

struct QActive *	QXK_current (void)
	return the currently executing active-object/thread More...

QSchedStatus	QXK_schedLock (uint_fast8_t ceiling)
	QXK Scheduler lock. More...

void	QXK_schedUnlock (QSchedStatus stat)
	QXK Scheduler unlock. More...

Variables
QXK_PrivAttr	QXK_attr_
	global attributes of the QXK kernel More...

Detailed Description

QXK/C (preemptive dual-mode kernel) platform-independent public interface.

Definition in file qxk.h.

Data Structure Documentation

◆ QXK_PrivAttr

struct QXK_PrivAttr

attributes of the QXK kernel

Definition at line 81 of file qxk.h.

Collaboration diagram for QXK_PrivAttr:

Data Fields
struct QActive *volatile	curr	current thread pointer (NULL=basic)
struct QActive *volatile	next	next thread pointer to execute
uint8_t volatile	actPrio	prio of the active AO
uint8_t volatile	lockPrio	lock prio (0 == no-lock)
uint8_t volatile	lockHolder	prio of the lock holder
uint8_t volatile	intNest	ISR nesting level.
struct QActive *	idleThread	pointer to the idle thread
QPSet	readySet	ready-set of basic and extended threads

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

#define QF_EQUEUE_TYPE QEQueue

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

Description: QXK uses the native QF event queue QEQueue.

Definition at line 57 of file qxk.h.

◆ QF_OS_OBJECT_TYPE

#define QF_OS_OBJECT_TYPE void*

Kernel-dependent OS-attribute of threads in QXK.

Description: QXK uses this member to store the private stack poiner for extended threads. (The private stack pointer is NULL for basic-threads).

Definition at line 65 of file qxk.h.

◆ QF_THREAD_TYPE

#define QF_THREAD_TYPE void*

Kernel-dependent type of the thread attribute in QXK.

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

Definition at line 72 of file qxk.h.

◆ QXK_TLS

#define QXK_TLS ( type_ ) ((type_)QXK_current()->thread)

Access Thread-Local Storage (TLS) and cast it on the given type_.

Definition at line 75 of file qxk.h.

◆ QXK_ISR_CONTEXT_

#define QXK_ISR_CONTEXT_ ( ) (QXK_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 171 of file qxk.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 178 of file qxk.h.

◆ QF_SCHED_LOCK_

#define QF_SCHED_LOCK_ ( prio_ )

Value:

        do {          \
        if (QXK_ISR_CONTEXT_()) {               \
            lockStat_ = 0xFFU;                  \
        } else {                                \
            lockStat_ = QXK_schedLock((prio_)); \
        }                                       \
    } while (false)

Internal macro for selective scheduler locking.

Definition at line 181 of file qxk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )

Value:

        do {     \
        if (lockStat_ != 0xFFU) {       \
            QXK_schedUnlock(lockStat_); \
        }                               \
    } while (false)

Internal macro for selective scheduler unlocking.

Definition at line 190 of file qxk.h.

◆ QACTIVE_EQUEUE_WAIT_

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

Definition at line 196 of file qxk.h.

◆ QACTIVE_EQUEUE_SIGNAL_

#define QACTIVE_EQUEUE_SIGNAL_ ( me_ )

Value:

        do {                          \
        QPSet_insert(&QXK_attr_.readySet, (uint_fast8_t)(me_)->prio); \
        if (!QXK_ISR_CONTEXT_()) {                                    \
            if (QXK_sched_() != 0U) {                    \
                QXK_activate_();                                      \
            }                                                         \
        }                                                             \
    } while (false)

Definition at line 199 of file qxk.h.

◆ QF_EPOOL_TYPE_

#define QF_EPOOL_TYPE_ QMPool

Definition at line 209 of file qxk.h.

◆ QF_EPOOL_INIT_

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

Definition at line 210 of file qxk.h.

◆ QF_EPOOL_EVENT_SIZE_

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

Definition at line 212 of file qxk.h.

◆ QF_EPOOL_GET_

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

Definition at line 213 of file qxk.h.

◆ QF_EPOOL_PUT_

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

Definition at line 214 of file qxk.h.

Typedef Documentation

◆ QSchedStatus

typedef uint_fast16_t QSchedStatus

QXK Scheduler locking.

The scheduler lock status

Definition at line 152 of file qxk.h.

Function Documentation

◆ QXK_onContextSw()

void QXK_onContextSw	(	struct QActive *	prev,
		struct QActive *	next
	)

QXK context switch callback (customized in BSPs for QXK)

Description: This callback function provides a mechanism to perform additional custom operations when QXK switches context from one thread to another.

Parameters

[in]	prev	pointer to the previous thread (active object) (prev==0 means that `prev` was the QXK idle thread)
[in]	next	pointer to the next thread (active object) (next==0) means that `next` is the QXK idle thread)

Attention: QXK_onContextSw() is invoked with interrupts disabled and must also return with interrupts disabled.

Note: This callback is enabled by defining the macro QXK_ON_CONTEXT_SW.

#ifdef QXK_ON_CONTEXT_SW
/* NOTE: the context-switch callback is called with interrupts DISABLED */
void QXK_onContextSw(QActive *prev, QActive *next) {
    (void)prev;
    if (next != (QActive *)0) { /* next is not the QXK idle thread? */
        _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 /* QXK_ON_CONTEXT_SW */

◆ QXK_onIdle()

void QXK_onIdle ( void )

QXK idle callback (customized in BSPs for QXK)

Description: QXK_onIdle() is called continuously by the QXK idle thread. This callback gives the application an opportunity to enter a power-saving CPU mode, or perform some other idle processing.

Note: QXK_onIdle() is invoked with interrupts enabled and must also return with interrupts enabled.

◆ QXK_sched_()

uint_fast8_t QXK_sched_ ( void )

QXK scheduler finds the highest-priority thread ready to run.

Description: The QXK scheduler finds the priority of the highest-priority thread that is ready to run.

Returns: the 1-based priority of the the active object to run next, or zero if no eligible active object is found.

Attention: QXK_sched_() must be always called with interrupts disabled and returns with interrupts disabled.

Definition at line 347 of file qxk.c.

◆ QXK_activate_()

void QXK_activate_ ( void )

QXK activator activates the next active object.

The activated AO preempts the currently executing AOs.

Attention: QXK_activate_() must be always called with interrupts disabled and returns with interrupts disabled.

Note: The activate function might enable interrupts internally, but it always returns with interrupts disabled.

Precondition: QXK_attr_.next must be valid

Definition at line 426 of file qxk.c.

◆ QXK_current()

struct QActive* QXK_current ( void )

return the currently executing active-object/thread

Precondition: the QXK kernel must be running

Postcondition: the current thread must be valid

Definition at line 559 of file qxk.c.

◆ QXK_schedLock()

QSchedStatus QXK_schedLock ( uint_fast8_t ceiling )

QXK Scheduler lock.

Description: This function locks the QXK scheduler to the specified ceiling.

Parameters

[in] ceiling priority ceiling to which the QXK scheduler needs to be locked

Returns: The previous QXK Scheduler lock status, which is to be used to unlock the scheduler by restoring its previous lock status in QXK_schedUnlock().

Note: A QXK scheduler can be locked from both basic threads (AOs) and extended threads and the scheduler locks can nest.; QXK_schedLock() must be always followed by the corresponding QXK_schedUnlock().

Attention: QXK will fire an assertion if a thread holding the lock attempts to block.

See also: QXK_schedUnlock()

Usage: The following example shows how to lock and unlock the QXK scheduler:
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */

uint32_t rnd;

QSchedStatus lockStat;

lockStat = QXK_schedLock(N_PHILO); /* lock scheduler around shared seed */

/* "Super-Duper" Linear Congruential Generator (LCG) */

rnd = l_rnd * (3U*7U*11U*13U*23U);

l_rnd = rnd; /* set for the next time */

QXK_schedLock(lockStat); /* unlock the scheduler */

return rnd;

}

Precondition

The QXK scheduler lock:

cannot be called from an ISR;

Definition at line 244 of file qxk.c.

◆ QXK_schedUnlock()

void QXK_schedUnlock ( QSchedStatus stat )

QXK Scheduler unlock.

Description: This function unlocks the QXK scheduler to the previous status.

Parameters

[in] stat previous QXK Scheduler lock status returned from QXK_schedLock()

Note: A QXK scheduler can be locked from both basic threads (AOs) and extended threads and the scheduler locks can nest.; QXK_schedUnlock() must always follow the corresponding QXK_schedLock().

See also: QXK_schedLock()

Usage: The following example shows how to lock and unlock the QXK scheduler:
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */

uint32_t rnd;

QSchedStatus lockStat;

lockStat = QXK_schedLock(N_PHILO); /* lock scheduler around shared seed */

/* "Super-Duper" Linear Congruential Generator (LCG) */

rnd = l_rnd * (3U*7U*11U*13U*23U);

l_rnd = rnd; /* set for the next time */

QXK_schedLock(lockStat); /* unlock the scheduler */

return rnd;

}

Precondition

The scheduler cannot be unlocked:

from the ISR context; and
the current lock priority must be greater than the previous

Definition at line 300 of file qxk.c.

Variable Documentation

◆ QXK_attr_

QXK_PrivAttr QXK_attr_

global attributes of the QXK kernel

Definition at line 59 of file qxk.c.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Data Structure Documentation

◆ QXK_PrivAttr

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

◆ QF_OS_OBJECT_TYPE

◆ QF_THREAD_TYPE

◆ QXK_TLS

◆ QXK_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

◆ QXK_onContextSw()

◆ QXK_onIdle()

◆ QXK_sched_()

◆ QXK_activate_()

◆ QXK_current()

◆ QXK_schedLock()

◆ QXK_schedUnlock()

Variable Documentation

◆ QXK_attr_