QXK Class Reference

The QXK kernel class. More...

#include <qxk.h>

Static Public Member Functions
void	QXK_onIdle (void)
QSchedStatus	QXK_schedLock (uint_fast8_t const ceiling)
void	QXK_schedUnlock (QSchedStatus const stat)
QActive *	QXK_current (void)
void	QXK_contextSw (QActive *const next)
void	QXK_onContextSw (QActive *prev, QActive *next)

Public Attributes
struct QActive *volatile	curr
struct QActive *volatile	next
struct QActive *volatile	prev
uint8_t volatile	actPrio
uint8_t volatile	lockCeil
uint8_t volatile	lockHolder

Static Private Member Functions
uint_fast8_t	QXK_sched_ (void)
void	QXK_activate_ (void)

Detailed Description

Note

The order and alignment of the data members in this struct might be important in QXK ports, where the members might be accessed in assembly.

Member Function Documentation

QXK_onIdle()

void QXK_onIdle ( void  )

static

QXK idle callback (customized in BSPs for QXK)

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_schedLock()

QSchedStatus QXK_schedLock ( uint_fast8_t const  ceiling )

static

QXK Scheduler lock

This function locks the QXK scheduler to the specified ceiling.

Parameters

[in]

ceiling

preemption 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;
}

QXK_schedUnlock()

void QXK_schedUnlock ( QSchedStatus const  stat )

static

QXK Scheduler unlock

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;
}

QXK_sched_()

uint_fast8_t QXK_sched_ ( void  )

staticprivate

QXK scheduler finds the highest-priority thread ready to run

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

Returns

the 1-based priority of the the thread (basic or extended) run next, or zero if no eligible thread is found.

Attention

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

QXK_activate_()

void QXK_activate_ ( void  )

staticprivate

QXK activator activates the next active object. The activated AO preempts the currently executing AOs.

QXK_activate_() activates ready-to run AOs that are above the initial active priority (QXK_attr_.actPrio).

Attention

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

QXK_current()

QActive * QXK_current ( void  )

static

obtain the currently executing active-object/thread

Returns

pointer to the currently executing active-object/thread

QXK_contextSw()

void QXK_contextSw ( QActive *const  next )

static

QXK context switch management

This function performs software tracing (if Q_SPY is defined) and calls QXK_onContextSw() (if QXK_ON_CONTEXT_SW is defined)

Parameters

[in]

next

pointer to the next thread (NULL for basic-thread)

Attention

QXK_contextSw() is invoked with interrupts disabled and must also return with interrupts disabled.

QXK_onContextSw()

void QXK_onContextSw ( QActive *  prev, QActive *  next  )

static

QXK context switch callback (customized in BSPs for QXK)

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 (NULL for idle thead)
[in]	next	pointer to the next thread (NULL for idle thead)

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, 0U)
        QS_OBJ(prev);
        QS_OBJ(next);
    QS_END_NOCRIT()
}
 
#endif /* QXK_ON_CONTEXT_SW */

Member Data Documentation

curr

struct QActive* volatile curr

current thread (NULL=basic)

next

struct QActive* volatile next

next thread to run

prev

struct QActive* volatile prev

previous thread

actPrio

uint8_t volatile actPrio

QF-prio of the active AO

lockCeil

uint8_t volatile lockCeil

lock-ceiling (0==no-lock)

lockHolder

uint8_t volatile lockHolder

prio of the lock holder

---

The documentation for this class was generated from the following file:

• qxk.h