QXK

Preemptive Dual-Mode (Run-to-Completion/Blocking) RTOS Kernel. More...

Collaboration diagram for QXK:

Files
file	qpcpp.h
	QP/C++ public interface old-version for backwards-compatibility.
file	qpcpp.hpp
	QP/C++ public interface including backwards-compatibility layer.
file	qxk.hpp
	QXK/C++ preemptive extended (blocking) kernel, platform-independent public interface.
file	qxthread.hpp
	QXK/C++ extended (blocking) thread.
file	qxk.cpp
	QXK/C++ preemptive kernel core functions public interface.
file	qxk_mutex.cpp
	Priority-ceiling blocking mutex QP::QXMutex class definition.
file	qxk_sema.cpp
	QXK/C++ preemptive kernel counting semaphore implementation.
file	qxk_xthr.cpp
	QXK/C++ preemptive kernel extended (blocking) thread implementation.
file	qxk_pkg.hpp
	Internal (package scope) QXK/C++ interface.
file	qxk_port.hpp
	QXK/C++ port example, Generic C++ compiler.

Detailed Description

Preemptive Dual-Mode (Run-to-Completion/Blocking) RTOS Kernel.

QXK is a small, preemptive, priority-based, dual-mode blocking kernel that executes active objects like the QK kernel (basic threads), but can also execute traditional blocking threads (extended threads). In this respect, QXK behaves exactly like a conventional RTOS (Real-Time Operating System).

QXK has been designed specifically for mixing event-driven active objects with traditional blocking code, such as commercial middleware (TCP/IP stacks, UDP stacks, embedded file systems, etc.) or legacy software. To this end, QXK is not only more efficient than running QP on top of a traditional 3rd-party RTOS (because non-blocking basic threads take far less stack space and CPU cycles for context switch than the much heavier extended threads). But the biggest advantage of QXK is that it protects the application-level code from inadvertent mixing of blocking calls inside the event-driven active objects. Specifically, QXK "knows" the type of the thread context (extended/basic) and asserts internally if a blocking call (e.g., semaphore-wait or a time-delay) is attempted in a basic thread (active object). This is something that a QP port to a conventional 3rd-party RTOS cannot do, because such an RTOS runs all code (including active objects) in the context of havyweight extended threads.

Currently, the QXK kernel has been ported to the following CPUs:

• Cortex-M (M0/M0+/M1/M3/M4/M4F/M7)
  Supported toolchains include: ARM-KEIL MDK, IAR-ARM, GNU-ARM, TI-ARM.

Currently, the QXK kernel is illustrated by the following examples:

• DPP on EFM32-SLSTK3401A (ARM Cortex-M4F)
  Example illustrates: 6 active objects plus two extended threads, QXK blocking delay, QXK semaphore, QXK mutex, QXK blocking message queue.
• DPP on EK-TM4C123GXL (ARM Cortex-M4F)
  Example illustrates: 6 active objects plus two extended threads, QXK blocking delay, QXK semaphore, QXK mutex, QXK blocking message queue.
• DPP on NUCLEO-L053R8 (ARM Cortex-M0+)
  Example illustrates: 6 active objects plus two extended threads, QXK blocking delay, QXK semaphore, QXK mutex, QXK blocking message queue.

Basic Threads

QXK supports basic-threads (non-blocking, run-to-completion activations). The basic-threads all nest on the same stack (Main Stack Pointer in ARM Cortex-M), so the stack usage is reduced. The additional advantage of basic-threads is that switching from basic-thread to another basic-thread requires only activation of the basic-thread, which is much simpler and faster than full context-switch required for extended-threads that QXK also supports (see below).

Remarks

QXK adopts the "basic/exteded thread" terms from the OSEK/AUTOSAR Operating System specification. Other real-time kernels might use different terminology for similar concepts. For example, the Q-Kernel uses the term "fibers", while TI-RTOS uses the term "software interrupts" for concepts closely related to "basic threads".

Extended Threads

QXK supports extended-threads (blocking, typically structrued as endless loops). The extended-threads use private per-thread stacks, as in conventional RTOS kernels. Any switching from basic-to-extended thread or extended-to-extended thread requires full context switch.

Remarks

QXK is a unique dual-mode kernel on the market that supports interleaving the priorities of basic threads and extended threads. Other dual-mode kernels typically limit the priorities of basic threads to be always higher (more urgent) than any of the extended threads.

See also

QP::QXThread

Classes in QXK

The figure below shows the main classes introduced in the QXK kernel and their relation to the classes of the QP framework.

Classes of the QXK dual-mode kernel

• 0 The abstract QP::QActive class represents active objects in QP. This class contains the thread object of the underlying kernel (QXK thread-control-block in this case) as well as the event queue and the unique priority of the active object.

• 1 The QP::QXThread class represents the extended (blocking) threads of the QXK kernel. It inherits QP::QActive, so that extended-threads can be treated as active objects internally in the framework. However, the extended-threads do not implement state machines. Instead, the data fields used for storing the current state in active objects are re-used to store the private stack of the extended-thread. The QP::QXThread class also contains the timeEvt object (see QP::QTimeEvt) for generating timeouts when the extended-thread is blocked.

• 2 The QP::QXMutex class represents the priority-ceiling mutex of the QXK kernel. The mutex can block and can be used only in the extended-threads and the QXK kernel would assert if an active object (basic thread) would attempt to lock a mutex. The mutex is recursive, meaning that it can be locked multiple times from the same extended thread (but it needs to be unlocked equal number of times).

  NOTE: Both active objects and extended threads can use the non-blocking, selective QXK scheduler locking to protect shared resources.

• 3 The QP::QXSemaphore class represents the counting semaphore of the QXK kernel. The semaphore can be waited on only in the extended threads and the QXK kernel would assert if an active object thread would attempt to wait on a semaphore. On the other hand, a semaphore can be signaled from anywhere in the code, including active objects and ISRs.

Note

The main takeaway from the QXK class diagram is QXK's optimal, tight integration with the QP framework. The QXK kernel reuses all mechanisms already provided in QP, thus avoiding any code duplication, inefficient layers of indirection, and additional licensing costs, which are inevitable when using 3rd-party RTOS kernels to run QP applications.

QXK Feature Summary

As you can see in the list below, QXK provides most features you might expect of a traditional blocking RTOS kernel and is recommended as the preferred RTOS kernel for QP applications that need to mix active objects with traditional blocking code.

• >Preemptive, priority-based scheduling of up to 64 threads. Each thread must be assigned its own unique priority (1 .. QF_MAX_ACTIVE);

  NOTE: QXK always executes the highest-priority thread that is ready to run (is not blocked). The scheduling algorithm used in QXK meets all the requirement of the Rate Monotonic Scheduling (a.k.a. Rate Monotonic Analysis — RMA) and can be used in hard real-time systems.

• >QXK distinguishes between two types of threads:

  • basic threads of active objects that are made ready-to-run by events posted to the active objects. Such basic threads are non-blocking, run-to-completion activations that cannot block in the middle of the RTC step. QXK asserts when a basic thread attempts to use a blocking mechanism, such as a time-delay or a semaphore-wait. All basic threads share the common stack.
  • extended threads that can block anywhere in their thread-handler function, whereas QXK provides a typical assortments of blocking primitives for extended-threads, such as time-delay, blocking message queue, counting semaphore, or a mutex. Each extended thread must be provided with its own private stack.

• >Tightly integrated mechanisms for communication between event-driven active objects and extended blocking threads:

  • Basic threads (Active Objects) can signal semaphores and send messages to extended threads.
  • Extended threads can post or publish events to active objects or other extended threads;
  • Extended threads can subscribe to events and thus can receive events published in the system.

• >Priority-Ceiling, recursive Mutexes with optional timeout;

  NOTE: Priority-ceiling protocol implemented in QXK is immune to priority-inversions, but requires a unique QP thread priority level (the ceiling priority) to be assigned to the mutex. This ceiling priority is unavailable to QP threads.
  

  NOTE: A QXK mutex can be configured not to use the priority-ceiling protocol (when initialized with a zero priority-ceiling). In that case, the mutex does not require a separate priority level.

• >Counting Semaphores with optional timeout that can block multiple extended-threads;

• >Blocking "zero-copy" message queue with optional timeout bound to each extended-thread;

• >Deterministic fixed-size memory pools for dynamic memory management available both to extended-threads and active objects;

• >Interrupt management, including "zero-latency", kernel-unaware interrupts that are never disabled;

  NOTE: This feature is only supported on CPUs that allow selective interrupt disabling, such as ARM Cortex-M3/M4 (but not ARM Cortex-M0/M0+);

• > Thread-Local Storage for all threads (basic threads and extended threads).

Thread Local Storage

Thread-local storage (TLS) is a programming method that uses static or global memory local to a thread. TLS is specifically useful for writing library-type code, which is used in a multithreaded environment and needs to access per-thread data in an independent way.

TLS is used in some places where ordinary, single-threaded programs would use static or global variables, but where this would be inappropriate in multithreaded cases. An example of such situations is where library-type functions use a global variable to set an error condition (for example the global variable errno used by many functions of the C library). If errno were simply a global variable, a call of a system function on one thread may overwrite the value previously set by a call of a system function on a different thread, possibly before following code on that different thread could check for the error condition. The solution is to have errno be a variable that looks like it is global, but in fact exists once per thread—i.e., it lives in thread-local storage. A second use case would be multiple threads accumulating information into a global variable. To avoid a race condition, every access to this global variable would have to be protected by a mutual-exclusion mechanism. Alternatively, each thread might accumulate into a thread-local variable (that, by definition, cannot be read from or written to from other threads, implying that there can be no race conditions). Threads then only have to synchronize a final accumulation from their own thread-local variable into a single, truly global variable.

The TLS implementations vary, but many systems, including QXK, implement TLS by providing a pointer-sized variable thread-local. This pointer can be set to arbitrarily sized memory blocks in a thread-local manner, by allocating such a memory block (statically or dynamically) and storing the memory address of that block in the thread-local variable.

Typical usage of TLS in QXK is illustrated in the example qpcpp/examples/arm-cm/dpp_efm32-slstk3401a/qxk/, test.cpp, and consists:

• define the TLS structure

  struct TLS_test {
      uint32_t foo;
      uint8_t bar[10];
  };

• allocate the TLS storage for all participating threads (extended or basic threads)

  static TLS_test l_tls1;
  static TLS_test l_tls2;

• initialize the TLS per-thread pointer in each thread routine (for extended threads) or the top-most initial transition (for basic threads of active objects):

  static void Thread1_run(QP::QXThread * const me) {
      me->m_thread = &l_tls1; // initialize the TLS for Thread1
      . . .
  }
  . . .
  static void Thread2_run(QP::QXThread * const me) {
      me->m_thread = &l_tls2; // initialize the TLS for Thread2
      . . .
  }

• access the TLS from your code:

  void lib_fun(uint32_t x) {
      QXK_TLS(TLS_test *)->foo = x;
  }

See also

• QXK_current()
• QXK_TLS()