QP/C 6.9.0
qxk.h File Reference

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:

Go to the source code of this file.

Data Structures

struct  QXK_PrivAttr
 attributes of the QXK kernel More...
 

Macros

#define QF_EQUEUE_TYPE   QEQueue
 
#define QF_OS_OBJECT_TYPE   void*
 
#define QF_THREAD_TYPE   void*
 
#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 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_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 70 of file qxk.h.

Collaboration diagram for QXK_PrivAttr:
Collaboration graph
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 all threads

Macro Definition Documentation

◆ QF_EQUEUE_TYPE

#define QF_EQUEUE_TYPE   QEQueue

Definition at line 53 of file qxk.h.

◆ QF_OS_OBJECT_TYPE

#define QF_OS_OBJECT_TYPE   void*

Definition at line 58 of file qxk.h.

◆ QF_THREAD_TYPE

#define QF_THREAD_TYPE   void*

Definition at line 61 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 64 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 160 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 167 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 170 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 179 of file qxk.h.

◆ QACTIVE_EQUEUE_WAIT_

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

Definition at line 185 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 188 of file qxk.h.

◆ QF_EPOOL_TYPE_

#define QF_EPOOL_TYPE_   QMPool

Definition at line 198 of file qxk.h.

◆ QF_EPOOL_INIT_

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

Definition at line 199 of file qxk.h.

◆ QF_EPOOL_EVENT_SIZE_

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

Definition at line 201 of file qxk.h.

◆ QF_EPOOL_GET_

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

Definition at line 202 of file qxk.h.

◆ QF_EPOOL_PUT_

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

Definition at line 203 of file qxk.h.

Typedef Documentation

◆ QSchedStatus

QXK Scheduler locking.

The scheduler lock status

Definition at line 141 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]prevpointer to the previous thread (active object) (prev==0 means that prev was the QXK idle thread)
[in]nextpointer 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);
}
#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 352 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 431 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 564 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 249 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 305 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.

QS_BEGIN_NOCRIT
#define QS_BEGIN_NOCRIT(rec_, obj_)
Begin a QS user record without entering critical section.
Definition: qs.h:654
QXK_schedLock
QSchedStatus QXK_schedLock(uint_fast8_t ceiling)
QXK Scheduler lock.
Definition: qxk.c:249
QXK_onContextSw
void QXK_onContextSw(struct QActive *prev, struct QActive *next)
QXK context switch callback (customized in BSPs for QXK)
QActive
Active Object base class (based on QHsm implementation)
Definition: qf.h:116
QXK_sched_
uint_fast8_t QXK_sched_(void)
QXK scheduler finds the highest-priority thread ready to run.
Definition: qxk.c:352
uint_fast8_t
unsigned int uint_fast8_t
fast at-least 8-bit unsigned int
Definition: 16bit/stdint.h:36
QXK_attr_
QXK_PrivAttr QXK_attr_
global attributes of the QXK kernel
Definition: qxk.c:59
QSchedStatus
uint_fast16_t QSchedStatus
QK Scheduler locking.
Definition: qk.h:132
QXK_ISR_CONTEXT_
#define QXK_ISR_CONTEXT_()
Internal macro that reports the execution context (ISR vs.
Definition: qxk.h:159
QS_OBJ
#define QS_OBJ(obj_)
Output formatted object pointer to the QS record.
Definition: qs.h:789
QS_END_NOCRIT
#define QS_END_NOCRIT()
End a QS user record without exiting critical section.
Definition: qs.h:664
QXK_PrivAttr::readySet
QPSet readySet
ready-set of all threads
Definition: qxk.h:78
uint32_t
unsigned long int uint32_t
exact-width 32-bit unsigned int
Definition: 16bit/stdint.h:31