QP/C  7.3.3
Real-Time Embedded Framework
Loading...
Searching...
No Matches
qk.c
Go to the documentation of this file.
1//$file${src::qk::qk.c} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
2//
3// Model: qpc.qm
4// File: ${src::qk::qk.c}
5//
6// This code has been generated by QM 6.1.1 <www.state-machine.com/qm>.
7// DO NOT EDIT THIS FILE MANUALLY. All your changes will be lost.
8//
9// This code is covered by the following QP license:
10// License # : LicenseRef-QL-dual
11// Issued to : Any user of the QP/C real-time embedded framework
12// Framework(s) : qpc
13// Support ends : 2024-12-31
14// License scope:
15//
16// Copyright (C) 2005 Quantum Leaps, LLC <state-machine.com>.
17//
18// Q u a n t u m L e a P s
19// ------------------------
20// Modern Embedded Software
21//
22// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
23//
24// This software is dual-licensed under the terms of the open source GNU
25// General Public License version 3 (or any later version), or alternatively,
26// under the terms of one of the closed source Quantum Leaps commercial
27// licenses.
28//
29// The terms of the open source GNU General Public License version 3
30// can be found at: <www.gnu.org/licenses/gpl-3.0>
31//
32// The terms of the closed source Quantum Leaps commercial licenses
33// can be found at: <www.state-machine.com/licensing>
34//
35// Redistributions in source code must retain this top-level comment block.
36// Plagiarizing this software to sidestep the license obligations is illegal.
37//
38// Contact information:
39// <www.state-machine.com/licensing>
40// <info@state-machine.com>
41//
42//$endhead${src::qk::qk.c} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
43#define QP_IMPL // this is QP implementation
44#include "qp_port.h" // QP port
45#include "qp_pkg.h" // QP package-scope internal interface
46#include "qsafe.h" // QP Functional Safety (FuSa) Subsystem
47#ifdef Q_SPY // QS software tracing enabled?
48 #include "qs_port.h" // QS port
49 #include "qs_pkg.h" // QS facilities for pre-defined trace records
50#else
51 #include "qs_dummy.h" // disable the QS software tracing
52#endif // Q_SPY
53
54// protection against including this source file in a wrong project
55#ifndef QK_H_
56 #error "Source file included in a project NOT based on the QK kernel"
57#endif // QK_H_
58
59Q_DEFINE_THIS_MODULE("qk")
60
61//$skip${QP_VERSION} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
62// Check for the minimum required QP version
63#if (QP_VERSION < 730U) || (QP_VERSION != ((QP_RELEASE^4294967295U) % 0x3E8U))
64#error qpc version 7.3.0 or higher required
65#endif
66//$endskip${QP_VERSION} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
67
68//$define${QK::QK-base} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
69
70//${QK::QK-base::priv_} ......................................................
71QK_Attr QK_priv_;
72
73//${QK::QK-base::schedLock} ..................................................
74//! @static @public @memberof QK
75QSchedStatus QK_schedLock(uint_fast8_t const ceiling) {
78 QF_MEM_SYS();
79
81 Q_REQUIRE_INCRIT(102, QK_priv_.lockCeil
82 == (uint_fast8_t)(~QK_priv_.lockCeil_dis));
83
84 // first store the previous lock prio
85 QSchedStatus stat;
86 if (ceiling > QK_priv_.lockCeil) { // raising the lock ceiling?
87 QS_BEGIN_PRE_(QS_SCHED_LOCK, QK_priv_.actPrio)
88 QS_TIME_PRE_(); // timestamp
89 // the previous lock ceiling & new lock ceiling
90 QS_2U8_PRE_((uint8_t)QK_priv_.lockCeil, (uint8_t)ceiling);
91 QS_END_PRE_()
92
93 // previous status of the lock
94 stat = (QSchedStatus)QK_priv_.lockCeil;
95
96 // new status of the lock
97 QK_priv_.lockCeil = ceiling;
98 #ifndef Q_UNSAFE
99 QK_priv_.lockCeil_dis = (uint_fast8_t)(~ceiling);
100 #endif
101 }
102 else {
103 stat = 0xFFU; // scheduler not locked
104 }
105
106 QF_MEM_APP();
107 QF_CRIT_EXIT();
108
109 return stat; // return the status to be saved in a stack variable
110}
111
112//${QK::QK-base::schedUnlock} ................................................
113//! @static @public @memberof QK
114void QK_schedUnlock(QSchedStatus const prevCeil) {
115 // has the scheduler been actually locked by the last QK_schedLock()?
116 if (prevCeil != 0xFFU) {
119 QF_MEM_SYS();
120
121 Q_REQUIRE_INCRIT(202, QK_priv_.lockCeil
122 == (uint_fast8_t)(~QK_priv_.lockCeil_dis));
124 && (QK_priv_.lockCeil > prevCeil));
125
126 QS_BEGIN_PRE_(QS_SCHED_UNLOCK, QK_priv_.actPrio)
127 QS_TIME_PRE_(); // timestamp
128 // current lock ceiling (old), previous lock ceiling (new)
129 QS_2U8_PRE_((uint8_t)QK_priv_.lockCeil, (uint8_t)prevCeil);
130 QS_END_PRE_()
131
132 // restore the previous lock ceiling
133 QK_priv_.lockCeil = prevCeil;
134 #ifndef Q_UNSAFE
135 QK_priv_.lockCeil_dis = (uint_fast8_t)(~prevCeil);
136 #endif
137
138 // find if any AOs should be run after unlocking the scheduler
139 if (QK_sched_() != 0U) { // preemption needed?
140 QK_activate_(); // activate any unlocked AOs
141 }
142
143 QF_MEM_APP();
144 QF_CRIT_EXIT();
145 }
146}
147
148//${QK::QK-base::sched_} .....................................................
149//! @static @private @memberof QK
150uint_fast8_t QK_sched_(void) {
151 // NOTE: this function is entered with interrupts DISABLED
152
153 Q_REQUIRE_INCRIT(402, QPSet_verify_(&QK_priv_.readySet,
154 &QK_priv_.readySet_dis));
155 uint_fast8_t p;
156 if (QPSet_isEmpty(&QK_priv_.readySet)) {
157 p = 0U; // no activation needed
158 }
159 else {
160 // find the highest-prio AO with non-empty event queue
161 p = QPSet_findMax(&QK_priv_.readySet);
162
163 Q_ASSERT_INCRIT(412,
164 QK_priv_.actThre == (uint_fast8_t)(~QK_priv_.actThre_dis));
165
166 // is the AO's prio. below the active preemption-threshold?
167 if (p <= QK_priv_.actThre) {
168 p = 0U; // no activation needed
169 }
170 else {
171 Q_ASSERT_INCRIT(422, QK_priv_.lockCeil
172 == (uint_fast8_t)(~QK_priv_.lockCeil_dis));
173
174 // is the AO's prio. below the lock-ceiling?
175 if (p <= QK_priv_.lockCeil) {
176 p = 0U; // no activation needed
177 }
178 else {
179 Q_ASSERT_INCRIT(432, QK_priv_.nextPrio
180 == (uint_fast8_t)(~QK_priv_.nextPrio_dis));
181 QK_priv_.nextPrio = p; // next AO to run
182 #ifndef Q_UNSAFE
183 QK_priv_.nextPrio_dis = (uint_fast8_t)(~QK_priv_.nextPrio);
184 #endif
185 }
186 }
187 }
188
189 return p;
190}
191
192//${QK::QK-base::activate_} ..................................................
193//! @static @private @memberof QK
194void QK_activate_(void) {
195 // NOTE: this function is entered with interrupts DISABLED
196
197 uint_fast8_t const prio_in = QK_priv_.actPrio; // save initial prio.
198 uint_fast8_t p = QK_priv_.nextPrio; // next prio to run
199
201 (prio_in == (uint_fast8_t)(~QK_priv_.actPrio_dis))
202 && (p == (uint_fast8_t)(~QK_priv_.nextPrio_dis)));
203 Q_REQUIRE_INCRIT(510, (prio_in <= QF_MAX_ACTIVE)
204 && (0U < p) && (p <= QF_MAX_ACTIVE));
205
206 #if (defined QF_ON_CONTEXT_SW) || (defined Q_SPY)
207 uint_fast8_t pprev = prio_in;
208 #endif // QF_ON_CONTEXT_SW || Q_SPY
209
210 QK_priv_.nextPrio = 0U; // clear for the next time
211 #ifndef Q_UNSAFE
212 QK_priv_.nextPrio_dis = (uint_fast8_t)(~0U);
213 #endif
214
215 uint_fast8_t pthre_in;
216 QActive *a;
217 if (prio_in == 0U) { // preempting the idle thread?
218 pthre_in = 0U;
219 }
220 else {
221 a = QActive_registry_[prio_in];
222 Q_ASSERT_INCRIT(510, a != (QActive *)0);
223
224 pthre_in = (uint_fast8_t)a->pthre;
225 Q_ASSERT_INCRIT(511, pthre_in ==
226 (uint_fast8_t)(~(uint_fast8_t)a->pthre_dis & 0xFFU));
227 }
228
229 // loop until no more ready-to-run AOs of higher pthre than the initial
230 do {
231 a = QActive_registry_[p]; // obtain the pointer to the AO
232 Q_ASSERT_INCRIT(520, a != (QActive *)0); // the AO must be registered
233 uint_fast8_t const pthre = (uint_fast8_t)a->pthre;
234 Q_ASSERT_INCRIT(522, pthre ==
235 (uint_fast8_t)(~(uint_fast8_t)a->pthre_dis & 0xFFU));
236
237 // set new active prio. and preemption-threshold
238 QK_priv_.actPrio = p;
239 QK_priv_.actThre = pthre;
240 #ifndef Q_UNSAFE
241 QK_priv_.actPrio_dis = (uint_fast8_t)(~p);
242 QK_priv_.actThre_dis = (uint_fast8_t)(~pthre);
243 #endif
244
245 #if (defined QF_ON_CONTEXT_SW) || (defined Q_SPY)
246 if (p != pprev) { // changing threads?
247
248 QS_BEGIN_PRE_(QS_SCHED_NEXT, p)
249 QS_TIME_PRE_(); // timestamp
250 QS_2U8_PRE_(p, // prio. of the scheduled AO
251 pprev); // previous prio.
252 QS_END_PRE_()
253
254 #ifdef QF_ON_CONTEXT_SW
255 QF_onContextSw(QActive_registry_[pprev], a);
256 #endif // QF_ON_CONTEXT_SW
257
258 pprev = p; // update previous prio.
259 }
260 #endif // QF_ON_CONTEXT_SW || Q_SPY
261
262 QF_INT_ENABLE(); // unconditionally enable interrupts
263
264 QEvt const * const e = QActive_get_(a);
265 // NOTE QActive_get_() performs QF_MEM_APP() before return
266
267 // dispatch event (virtual call)
268 (*a->super.vptr->dispatch)(&a->super, e, p);
269 #if (QF_MAX_EPOOL > 0U)
270 QF_gc(e);
271 #endif
272
273 // determine the next highest-prio. AO ready to run...
274 QF_INT_DISABLE(); // unconditionally disable interrupts
275 QF_MEM_SYS();
276
277 // internal integrity check (duplicate inverse storage)
278 Q_ASSERT_INCRIT(532, QPSet_verify_(&QK_priv_.readySet,
279 &QK_priv_.readySet_dis));
280
281 if (a->eQueue.frontEvt == (QEvt *)0) { // empty queue?
282 QPSet_remove(&QK_priv_.readySet, p);
283 #ifndef Q_UNSAFE
284 QPSet_update_(&QK_priv_.readySet, &QK_priv_.readySet_dis);
285 #endif
286 }
287
288 if (QPSet_isEmpty(&QK_priv_.readySet)) {
289 p = 0U; // no activation needed
290 }
291 else {
292 // find new highest-prio AO ready to run...
293 p = QPSet_findMax(&QK_priv_.readySet);
294
295 // is the new prio. below the initial preemption-threshold?
296 if (p <= pthre_in) {
297 p = 0U; // no activation needed
298 }
299 else {
300 Q_ASSERT_INCRIT(542, QK_priv_.lockCeil
301 == (uint_fast8_t)(~QK_priv_.lockCeil_dis));
302
303 // is the AO's prio. below the lock preemption-threshold?
304 if (p <= QK_priv_.lockCeil) {
305 p = 0U; // no activation needed
306 }
307 else {
309 }
310 }
311 }
312 } while (p != 0U);
313
314 // restore the active prio. and preemption-threshold
315 QK_priv_.actPrio = prio_in;
316 QK_priv_.actThre = pthre_in;
317 #ifndef Q_UNSAFE
318 QK_priv_.actPrio_dis = (uint_fast8_t)(~QK_priv_.actPrio);
319 QK_priv_.actThre_dis = (uint_fast8_t)(~QK_priv_.actThre);
320 #endif
321
322 #if (defined QF_ON_CONTEXT_SW) || (defined Q_SPY)
323 if (prio_in != 0U) { // resuming an active object?
324 a = QActive_registry_[prio_in]; // pointer to preempted AO
325
326 QS_BEGIN_PRE_(QS_SCHED_NEXT, prio_in)
327 QS_TIME_PRE_(); // timestamp
328 // prio. of the resumed AO, previous prio.
329 QS_2U8_PRE_(prio_in, pprev);
330 QS_END_PRE_()
331 }
332 else { // resuming prio.==0 --> idle
333 a = (QActive *)0; // QK idle loop
334
335 QS_BEGIN_PRE_(QS_SCHED_IDLE, pprev)
336 QS_TIME_PRE_(); // timestamp
337 QS_U8_PRE_(pprev); // previous prio.
338 QS_END_PRE_()
339 }
340
341 #ifdef QF_ON_CONTEXT_SW
342 QF_onContextSw(QActive_registry_[pprev], a);
343 #endif // QF_ON_CONTEXT_SW
344
345 #endif // QF_ON_CONTEXT_SW || Q_SPY
346}
347//$enddef${QK::QK-base} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
348
349//$define${QK::QF-cust} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
350
351//${QK::QF-cust::init} .......................................................
352//! @static @public @memberof QF
353void QF_init(void) {
354 QF_bzero_(&QF_priv_, sizeof(QF_priv_));
355 QF_bzero_(&QK_priv_, sizeof(QK_priv_));
356 QF_bzero_(&QActive_registry_[0], sizeof(QActive_registry_));
357
358 // setup the QK scheduler as initially locked and not running
359 QK_priv_.lockCeil = (QF_MAX_ACTIVE + 1U); // scheduler locked
360
361 #ifndef Q_UNSAFE
362 QPSet_update_(&QK_priv_.readySet, &QK_priv_.readySet_dis);
363 QK_priv_.actPrio_dis = (uint_fast8_t)(~0U);
364 QK_priv_.nextPrio_dis = (uint_fast8_t)(~0U);
365 QK_priv_.actThre_dis = (uint_fast8_t)(~0U);
366 QK_priv_.lockCeil_dis = (uint_fast8_t)(~QK_priv_.lockCeil);
367 #endif
368
369 for (uint_fast8_t tickRate = 0U;
370 tickRate < Q_DIM(QTimeEvt_timeEvtHead_);
371 ++tickRate)
372 {
373 QTimeEvt_ctorX(&QTimeEvt_timeEvtHead_[tickRate],
374 (QActive *)0, (enum_t)Q_USER_SIG, tickRate);
375 }
376
377 #ifdef QK_INIT
378 QK_INIT(); // port-specific initialization of the QK kernel
379 #endif
380}
381
382//${QK::QF-cust::stop} .......................................................
383//! @static @public @memberof QF
384void QF_stop(void) {
385 QF_onCleanup(); // application-specific cleanup callback
386 // nothing else to do for the preemptive QK kernel
387}
388
389//${QK::QF-cust::run} ........................................................
390//! @static @public @memberof QF
391int_t QF_run(void) {
392 #ifdef Q_SPY
393 // produce the QS_QF_RUN trace record
395 QF_MEM_SYS();
396 QS_beginRec_((uint_fast8_t)QS_QF_RUN);
397 QS_endRec_();
398 QF_MEM_APP();
400 #endif // Q_SPY
401
402 QF_onStartup(); // application-specific startup callback
403
405 QF_MEM_SYS();
406
407 #ifdef QK_START
408 QK_START(); // port-specific startup of the QK kernel
409 #endif
410
411 QK_priv_.lockCeil = 0U; // unlock the QK scheduler
412 #ifndef Q_UNSAFE
413 QK_priv_.lockCeil_dis = (uint_fast8_t)(~0U);
414 #endif
415
416 // activate AOs to process events posted so far
417 if (QK_sched_() != 0U) {
418 QK_activate_();
419 }
420
421 QF_MEM_APP();
423
424 for (;;) { // QK idle loop...
425 QK_onIdle(); // application-specific QK on-idle callback
426 }
427
428 #ifdef __GNUC__
429 return 0;
430 #endif
431}
432//$enddef${QK::QF-cust} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
433
434//$define${QK::QActive} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
435
436//${QK::QActive} .............................................................
437
438//${QK::QActive::start_} .....................................................
439//! @public @memberof QActive
440void QActive_start_(QActive * const me,
441 QPrioSpec const prioSpec,
442 QEvt const * * const qSto,
443 uint_fast16_t const qLen,
444 void * const stkSto,
445 uint_fast16_t const stkSize,
446 void const * const par)
447{
448 Q_UNUSED_PAR(stkSto); // not needed in QK
449 Q_UNUSED_PAR(stkSize); // not needed in QK
450
453 QF_MEM_SYS();
454
456 && (stkSto == (void *)0));
457 QF_MEM_APP();
458 QF_CRIT_EXIT();
459
460 me->prio = (uint8_t)(prioSpec & 0xFFU); // QF-prio. of the AO
461 me->pthre = (uint8_t)(prioSpec >> 8U); // preemption-threshold
462 QActive_register_(me); // make QF aware of this active object
463
464 QEQueue_init(&me->eQueue, qSto, qLen); // init the built-in queue
465
466 // top-most initial tran. (virtual call)
467 (*me->super.vptr->init)(&me->super, par, me->prio);
468 QS_FLUSH(); // flush the trace buffer to the host
469
470 // See if this AO needs to be scheduled if QK is already running
472 QF_MEM_SYS();
473 if (QK_sched_() != 0U) { // activation needed?
474 QK_activate_();
475 }
476 QF_MEM_APP();
477 QF_CRIT_EXIT();
478}
479//$enddef${QK::QActive} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
QF_Attr QF_priv_
Definition qf_act.c:70
QActive * QActive_registry_[QF_MAX_ACTIVE+1U]
Definition qf_act.c:64
uint_fast8_t QSchedStatus
Definition qk.h:60
int int_t
Definition qp.h:106
#define QF_MEM_APP()
Definition qp.h:1284
#define Q_UNUSED_PAR(par_)
Definition qp.h:532
@ Q_USER_SIG
offset for the user signals (QP Application)
Definition qp.h:260
#define QF_MEM_SYS()
Definition qp.h:1279
int enum_t
Definition qp.h:109
#define Q_DIM(array_)
Definition qp.h:535
uint16_t QPrioSpec
Definition qp.h:619
#define QF_MAX_ACTIVE
Definition qp_config.h:112
Internal (package scope) QP/C interface.
Sample QP/C port.
#define QK_ISR_CONTEXT_()
Definition qp_port.h:105
#define QF_INT_DISABLE()
Disable interrupts.
Definition qp_port.h:37
#define QF_INT_ENABLE()
Enable interrupts.
Definition qp_port.h:40
@ QS_QF_RUN
QF_run() was entered.
Definition qs.h:179
#define QS_TIME_PRE_()
Definition qs.h:450
@ QS_SCHED_IDLE
scheduler restored the idle task
Definition qs.h:156
@ QS_SCHED_LOCK
scheduler was locked
Definition qs.h:153
@ QS_SCHED_UNLOCK
scheduler was unlocked
Definition qs.h:154
#define QS_FLUSH()
Definition qs.h:363
@ QS_SCHED_NEXT
scheduler started next task
Definition qs.h:155
QS/C package-scope interface.
Sample QS/C port.
QP Functional Safety (FuSa) Subsystem.
#define QF_CRIT_ENTRY()
Definition qsafe.h:58
#define Q_ASSERT_INCRIT(id_, expr_)
Definition qsafe.h:72
#define QF_CRIT_EXIT()
Definition qsafe.h:62
#define Q_REQUIRE_INCRIT(id_, expr_)
Definition qsafe.h:136
#define QF_CRIT_STAT
Definition qsafe.h:54
int_t QF_run(void)
Definition qutest.c:191
void QF_init(void)
Definition qutest.c:172
void QF_stop(void)
Definition qutest.c:186
Active object class (based on the QHsm implementation strategy)
Definition qp.h:800
uint8_t prio
Definition qp.h:805
uint8_t pthre
Definition qp.h:808
uint8_t pthre_dis
Definition qp.h:832
QACTIVE_EQUEUE_TYPE eQueue
Definition qp.h:822
QAsm super
Definition qp.h:802
struct QAsmVtable const * vptr
Definition qp.h:281
void(* init)(QAsm *const me, void const *const e, uint_fast8_t const qsId)
Definition qp.h:299
void(* dispatch)(QAsm *const me, QEvt const *const e, uint_fast8_t const qsId)
Definition qp.h:301
Event class.
Definition qp.h:147
Private attributes of the QK kernel.
Definition qk.h:67