QP/C  5.9.7
qxk.h File Reference

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

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

Go to the source code of this file.

Data Structures

struct  QXK_Attr
 attributes of the QXK kernel More...
 

Macros

#define QF_EQUEUE_TYPE   QEQueue
 This macro defines the type of the event queue used for the active objects. More...
 
#define QF_OS_OBJECT_TYPE   void*
 Private OS-object attribute of active objects in QXK. More...
 
#define QF_THREAD_TYPE   void*
 Private thread attribute of active objects in QXK. More...
 
#define QXK_TLS(type_)   ((type_)QXK_current()->thread)
 Access Thread-Local Storage (TLS) and cast it on the given type_.
 
#define QXK_getVersion()   (QP_versionStr)
 get the current QXK version number string of the form "X.Y.Z"
 
#define QXK_ISR_CONTEXT_()   (QXK_attr_.intNest != (uint_fast8_t)0)
 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.
 
#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_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 QActiveQXK_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_Attr QXK_attr_
 global attributes of the QXK kernel
 

Detailed Description

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

Definition in file qxk.h.


Data Structure Documentation

◆ QXK_Attr

struct QXK_Attr

attributes of the QXK kernel

Definition at line 83 of file qxk.h.

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

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

#define QF_EQUEUE_TYPE   QEQueue

This macro defines the type of the event queue used for the active objects.

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*

Private OS-object attribute of active objects in QXK.

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

Definition at line 65 of file qxk.h.

◆ QF_THREAD_TYPE

#define QF_THREAD_TYPE   void*

Private thread attribute of active objects in QXK.

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

Definition at line 72 of file qxk.h.

◆ QXK_ISR_CONTEXT_

#define QXK_ISR_CONTEXT_ ( )    (QXK_attr_.intNest != (uint_fast8_t)0)

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 151 of file qxk.h.

◆ QF_SCHED_LOCK_

#define QF_SCHED_LOCK_ (   prio_)
Value:
do { \
if (QXK_ISR_CONTEXT_()) { \
lockStat_ = (QSchedStatus)0xFF; \
} else { \
lockStat_ = QXK_schedLock((prio_)); \
} \
} while (0)
uint_fast16_t QSchedStatus
QXK Scheduler locking.
Definition: qxk.h:129
#define QXK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qxk.h:151
QSchedStatus QXK_schedLock(uint_fast8_t ceiling)
QXK Scheduler lock.
Definition: qxk.c:267

Internal macro for selective scheduler locking.

Definition at line 161 of file qxk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )
Value:
do { \
if (lockStat_ != (QSchedStatus)0xFF) { \
QXK_schedUnlock(lockStat_); \
} \
} while (0)
uint_fast16_t QSchedStatus
QK Scheduler locking.
Definition: qk.h:102

Internal macro for selective scheduler unlocking.

Definition at line 170 of file qxk.h.

◆ QACTIVE_EQUEUE_SIGNAL_

#define QACTIVE_EQUEUE_SIGNAL_ (   me_)
Value:
do { \
QPSet_insert(&QXK_attr_.readySet, (me_)->prio); \
if (!QXK_ISR_CONTEXT_()) { \
if (QXK_sched_() != (uint_fast8_t)0) { \
QXK_activate_(); \
} \
} \
} while (0)
QXK_Attr QXK_attr_
global attributes of the QXK kernel
Definition: qxk.c:58
QPSet readySet
ready-set of basuc- and extended-threads
Definition: qxk.h:92
#define QXK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qxk.h:151
uint_fast8_t QXK_sched_(void)
QXK scheduler finds the highest-priority thread ready to run.
Definition: qxk.c:371
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35

Definition at line 179 of file qxk.h.

Typedef Documentation

◆ QSchedStatus

QXK Scheduler locking.

The scheduler lock status

Definition at line 129 of file qxk.h.

Function Documentation

◆ QXK_onIdle()

void QXK_onIdle ( void  )

QXK idle callback (customized in BSPs for QXK)

QXK_onIdle() is called continuously by the QXK idle loop. 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.
See also
QK_onIdle()

◆ 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 371 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.

Definition at line 449 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 555 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]ceilingpriority 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 267 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]statprevious 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 324 of file qxk.c.