QP/C  5.9.3
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...
 
struct  QXMutex
 QXK priority-ceiling mutex class. More...
 

Macros

#define QF_EQUEUE_TYPE   QEQueue
 This macro defines the type of the event queue used for the active objects. More...
 
#define QF_THREAD_TYPE   void*
 OS-dependent representation of the private thread. More...
 
#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_   QXMutex schedLock_;
 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(0, (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_)))
 

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...
 
void QXMutex_init (QXMutex *const me, uint_fast8_t prio)
 The QXMutex initialization. More...
 
void QXMutex_lock (QXMutex *const me)
 QXMutex lock. More...
 
void QXMutex_unlock (QXMutex *const me)
 QXMutex 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 69 of file qxk.h.

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

◆ QXMutex

struct QXMutex

QXK priority-ceiling mutex class.

Definition at line 109 of file qxk.h.

Data Fields
uint_fast8_t lockPrio lock prio (priority ceiling)
uint_fast8_t prevHolder priority of the thread holding the lock
uint_fast8_t prevPrio previoius lock prio

Macro Definition Documentation

◆ 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:78
#define QXK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qxk.h:138
uint_fast8_t QXK_sched_(void)
QXK scheduler finds the highest-priority thread ready to run.
Definition: qxk.c:247
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35

Definition at line 167 of file qxk.h.

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

#define QF_SCHED_LOCK_ (   prio_)
Value:
do { \
if (QXK_ISR_CONTEXT_()) { \
schedLock_.lockPrio = (uint_fast8_t)0; \
} else { \
QXMutex_init(&schedLock_, (prio_)); \
QXMutex_lock(&schedLock_); \
} \
} while (0)
#define QXK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qxk.h:138
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35

Internal macro for selective scheduler locking.

Definition at line 148 of file qxk.h.

◆ QF_SCHED_UNLOCK_

#define QF_SCHED_UNLOCK_ ( )
Value:
do { \
if (schedLock_.lockPrio != (uint_fast8_t)0) { \
QXMutex_unlock(&schedLock_); \
} \
} while (0)
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: stdint.h:35

Internal macro for selective scheduler unlocking.

Definition at line 158 of file qxk.h.

◆ QF_THREAD_TYPE

#define QF_THREAD_TYPE   void*

OS-dependent representation of the private thread.

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.

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

Function Documentation

◆ 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 325 of file qxk.c.

◆ 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 247 of file qxk.c.

◆ QXMutex_init()

void QXMutex_init ( QXMutex *const  me,
uint_fast8_t  prio 
)

The QXMutex initialization.

Description
Initializes QXK priority-ceiling mutex to the specified ceiling priority.
Parameters
[in,out]mepointer (see Object Orientation)
[in]prioceiling priority of the mutex
Note
A mutex must be initialized before it can be locked or unlocked.
See also
QXMutex_lock(), QXMutex_unlock()
Usage
The following example shows how to initialize, lock and unlock QXK mutex:
QXMutex l_rndMutex; /* mutex to protect the random number generator */
void BSP_randomSeed(uint32_t seed) {
QXMutex_init(&l_rndMutex, N_PHILO); /* <== initialize the mutex */
l_rnd = seed;
}
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QXMutex_lock(&l_rndMutex); /* <== lock the shared random seed */
/* "Super-Duper" Linear Congruential Generator (LCG) */
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QXMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}

Definition at line 78 of file qxk_mutex.c.

◆ QXMutex_lock()

void QXMutex_lock ( QXMutex *const  me)

QXMutex lock.

Description
This function locks the QXK mutex.
Parameters
[in,out]mepointer (see Object Orientation)
Note
A mutex must be initialized before it can be locked or unlocked.
A QXK mutex can be used from both basic threads (AOs) and extended threads.
QXMutex_lock() must be always followed by the corresponding QXMutex_unlock().
Attention
QXK will fire an assertion if a thread holding the mutex attempts to block.
See also
QXMutex_init(), QXMutex_unlock()
Usage
The following example shows how to initialize, lock and unlock QXK mutex:
QXMutex l_rndMutex; /* mutex to protect the random number generator */
void BSP_randomSeed(uint32_t seed) {
QXMutex_init(&l_rndMutex, N_PHILO); /* <== initialize the mutex */
l_rnd = seed;
}
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QXMutex_lock(&l_rndMutex); /* <== lock the shared random seed */
/* "Super-Duper" Linear Congruential Generator (LCG) */
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QXMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}
Precondition
scheduler cannot be locked from the ISR context and the mutex must be unused

Definition at line 110 of file qxk_mutex.c.

◆ QXMutex_unlock()

void QXMutex_unlock ( QXMutex *const  me)

QXMutex unlock.

Description
This function unlocks the QXK mutex.
Parameters
[in]mepointer (see Object Orientation)
Note
A mutex must be initialized before it can be locked or unlocked.
A QXK mutex can be used from both basic threads (AOs) and extended threads.
QXMutex_unlock() must always follow the corresponding QXMutex_lock().
Attention
QXK will fire an assertion if a thread holding the mutex attempts to block.
See also
QXMutex_init(), QXMutex_lock()
Usage
The following example shows how to initialize, lock and unlock QXK mutex:
QXMutex l_rndMutex; /* mutex to protect the random number generator */
void BSP_randomSeed(uint32_t seed) {
QXMutex_init(&l_rndMutex, N_PHILO); /* <== initialize the mutex */
l_rnd = seed;
}
uint32_t BSP_random(void) { /* a very cheap pseudo-random-number generator */
uint32_t rnd;
QXMutex_lock(&l_rndMutex); /* <== lock the shared random seed */
/* "Super-Duper" Linear Congruential Generator (LCG) */
rnd = l_rnd * (3U*7U*11U*13U*23U);
l_rnd = rnd; /* set for the next time */
QXMutex_unlock(&l_rndMutex); /* <== unlock the shared random seed */
return rnd;
}
Precondition
scheduler cannot be unlocked from the ISR context and the mutex must NOT be unused

Definition at line 166 of file qxk_mutex.c.