QP/C++  7.0.1
Real-Time Embedded Framework
qk.hpp
Go to the documentation of this file.
1//============================================================================
2// QP/C++ Real-Time Embedded Framework (RTEF)
3// Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
4//
5// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
6//
7// This software is dual-licensed under the terms of the open source GNU
8// General Public License version 3 (or any later version), or alternatively,
9// under the terms of one of the closed source Quantum Leaps commercial
10// licenses.
11//
12// The terms of the open source GNU General Public License version 3
13// can be found at: <www.gnu.org/licenses/gpl-3.0>
14//
15// The terms of the closed source Quantum Leaps commercial licenses
16// can be found at: <www.state-machine.com/licensing>
17//
18// Redistributions in source code must retain this top-level comment block.
19// Plagiarizing this software to sidestep the license obligations is illegal.
20//
21// Contact information:
22// <www.state-machine.com>
23// <info@state-machine.com>
24//============================================================================
30
31#ifndef QK_HPP
32#define QK_HPP
33
34#include "qequeue.hpp" // QK kernel uses the native QF event queue
35#include "qmpool.hpp" // QK kernel uses the native QF memory pool
36#include "qpset.hpp" // QK kernel uses the native QF priority set
37
38
39//============================================================================
40// QF configuration for QK -- data members of the QActive class...
41
42// QK event-queue used for AOs
43#define QF_EQUEUE_TYPE QEQueue
44
45// QK thread type used for AOs
46// QK uses this member to store the private Thread-Local Storage pointer.
47//
48#define QF_THREAD_TYPE void*
49
50
51//============================================================================
52namespace QP {
53 class QActive; // forward declaration
54} // namespace QP
55
57extern "C" {
58
59struct QK_Attr {
60 std::uint8_t volatile actPrio;
61 std::uint8_t volatile nextPrio;
62 std::uint8_t volatile lockPrio;
63 std::uint8_t volatile lockHolder;
64 std::uint8_t volatile intNest;
66};
67
69extern QK_Attr QK_attr_;
70
72std::uint_fast8_t QK_sched_(void) noexcept;
73
75// the currently executing AOs.
76void QK_activate_(void) noexcept;
77
78#ifdef QK_ON_CONTEXT_SW
79
101
102#endif // QK_ON_CONTEXT_SW
103
104} // extern "C"
105
106//============================================================================
107namespace QP {
108
110using QSchedStatus = std::uint_fast16_t;
111
112//============================================================================
123class QK {
124public:
125 // QK scheduler locking...
127 static QSchedStatus schedLock(std::uint_fast8_t const ceiling) noexcept;
128
130 static void schedUnlock(QSchedStatus const stat) noexcept;
131
143 static void onIdle(void);
144
146 static char const *getVersion(void) noexcept {
147 return versionStr;
148 }
149};
150
151} // namespace QP
152
153//============================================================================
154// interface used only inside QF, but not in applications
155
156#ifdef QP_IMPL
157
158 #ifndef QK_ISR_CONTEXT_
160 // (ISR vs. thread).
163 #define QK_ISR_CONTEXT_() (QK_attr_.intNest != 0U)
164 #endif // QK_ISR_CONTEXT_
165
166 // QK-specific scheduler locking
168 // that needs to be preserved to allow nesting of locks.
169 //
170 #define QF_SCHED_STAT_ QSchedStatus lockStat_;
171
173 #define QF_SCHED_LOCK_(prio_) do { \
174 if (QK_ISR_CONTEXT_()) { \
175 lockStat_ = 0xFFU; \
176 } else { \
177 lockStat_ = QK::schedLock((prio_)); \
178 } \
179 } while (false)
180
182 #define QF_SCHED_UNLOCK_() do { \
183 if (lockStat_ != 0xFFU) { \
184 QK::schedUnlock(lockStat_); \
185 } \
186 } while (false)
187
188 // QK-specific native event queue operations...
189 #define QACTIVE_EQUEUE_WAIT_(me_) \
190 Q_ASSERT_ID(110, (me_)->m_eQueue.m_frontEvt != nullptr)
191
192 #define QACTIVE_EQUEUE_SIGNAL_(me_) do { \
193 QK_attr_.readySet.insert( \
194 static_cast<std::uint_fast8_t>((me_)->m_prio)); \
195 if (!QK_ISR_CONTEXT_()) { \
196 if (QK_sched_() != 0U) { \
197 QK_activate_(); \
198 } \
199 } \
200 } while (false)
201
202 // QK-specific native QF event pool operations...
203 #define QF_EPOOL_TYPE_ QMPool
204 #define QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_) \
205 (p_).init((poolSto_), (poolSize_), (evtSize_))
206 #define QF_EPOOL_EVENT_SIZE_(p_) ((p_).m_blockSize)
207 #define QF_EPOOL_GET_(p_, e_, m_, qs_id_) \
208 ((e_) = static_cast<QEvt *>((p_).get((m_), (qs_id_))))
209 #define QF_EPOOL_PUT_(p_, e_, qs_id_) ((p_).put((e_), (qs_id_)))
210
211#endif // QP_IMPL
212
213#endif // QK_HPP
QActive active object (based on QP::QHsm implementation)
Definition: qf.hpp:136
QK services.
Definition: qk.hpp:123
static QSchedStatus schedLock(std::uint_fast8_t const ceiling) noexcept
QK selective scheduler lock.
Definition: qk.cpp:219
static void schedUnlock(QSchedStatus const stat) noexcept
QK selective scheduler unlock.
Definition: qk.cpp:269
static void onIdle(void)
QK idle callback (customized in BSPs for QK)
static char const * getVersion(void) noexcept
get the current QK version number string of the form X.Y.Z
Definition: qk.hpp:146
namespace associated with the QP/C++ framework
Definition: exa_native.dox:1
constexpr char const versionStr[]
the current QP version number string based on QP_VERSION_STR
Definition: qep.hpp:116
std::uint_fast16_t QSchedStatus
The scheduler lock status.
Definition: qk.hpp:110
platform-independent fast "raw" thread-safe event queue interface
std::uint8_t volatile lockPrio
lock prio (0 == no-lock)
Definition: qk.hpp:62
QK_Attr QK_attr_
global attributes of the QK kernel
Definition: qk.cpp:52
std::uint8_t volatile lockHolder
prio of the lock holder
Definition: qk.hpp:63
void QK_activate_(void) noexcept
QK activator activates the next active object. The activated AO preempts.
Definition: qk.cpp:348
std::uint8_t volatile actPrio
prio of the active AO
Definition: qk.hpp:60
QP::QPSet readySet
QK ready-set of AOs and "naked" threads.
Definition: qk.hpp:65
void QK_onContextSw(QP::QActive *prev, QP::QActive *next)
QK context switch callback (customized in BSPs for QK)
std::uint8_t volatile nextPrio
prio of the next AO to execute
Definition: qk.hpp:61
std::uint8_t volatile intNest
ISR nesting level.
Definition: qk.hpp:64
std::uint_fast8_t QK_sched_(void) noexcept
QK scheduler finds the highest-priority thread ready to run.
Definition: qk.cpp:321
attributes of the QK kernel (in C for easy access in assembly)
Definition: qk.hpp:59
platform-independent memory pool QP::QMPool interface.
platform-independent priority sets of 8 or 64 elements.
Priority Set of up to 32 elements *‍/.
Definition: qpset.hpp:68