QP/C  7.2.2
Real-Time Embedded Framework
Loading...
Searching...
No Matches
qf_pkg.h
Go to the documentation of this file.
1/*$file${include::qf_pkg.h} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv*/
2/*
3* Model: qpc.qm
4* File: ${include::qf_pkg.h}
5*
6* This code has been generated by QM 5.2.5 <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 : 2023-12-31
14* License scope:
15*
16* Copyright (C) 2005 Quantum Leaps, LLC <state-machine.com>.
17*
18* SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
19*
20* This software is dual-licensed under the terms of the open source GNU
21* General Public License version 3 (or any later version), or alternatively,
22* under the terms of one of the closed source Quantum Leaps commercial
23* licenses.
24*
25* The terms of the open source GNU General Public License version 3
26* can be found at: <www.gnu.org/licenses/gpl-3.0>
27*
28* The terms of the closed source Quantum Leaps commercial licenses
29* can be found at: <www.state-machine.com/licensing>
30*
31* Redistributions in source code must retain this top-level comment block.
32* Plagiarizing this software to sidestep the license obligations is illegal.
33*
34* Contact information:
35* <www.state-machine.com/licensing>
36* <info@state-machine.com>
37*/
38/*$endhead${include::qf_pkg.h} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
39/*! @file
40* @brief Internal (package scope) QF/C interface.
41*
42* @trace
43* - @tr{DVP-QP-MC3-D04_08}
44*/
45#ifndef QF_PKG_H_
46#define QF_PKG_H_
47
48/*==========================================================================*/
49/*$declare${QF::QF-pkg} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv*/
50
51/*${QF::QF-pkg::ePool_[QF_MAX_EPOOL]} ......................................*/
52#if (QF_MAX_EPOOL > 0U)
53/*! array of event pools managed by QF */
55#endif /* (QF_MAX_EPOOL > 0U) */
56
57/*${QF::QF-pkg::maxPool_} ..................................................*/
58/*! number of initialized event pools */
59extern uint_fast8_t QF_maxPool_;
60
61/*${QF::QF-pkg::readySet_} .................................................*/
62/*! "Ready-set" of all threads used in the built-in kernels
63* @static @private @memberof QF
64*/
66
67/*${QF::QF-pkg::readySet_rmc_} .............................................*/
68#ifndef QP_NSSM
69/*! Redundant Mirror Copy (RMC) of QF_readySet_ (Software Self-Monitoring (SSM))
70* @static @private @memberof QF
71*/
73#endif /* ndef QP_NSSM */
74
75/*${QF::QF-pkg::bzero} .....................................................*/
76/*! Clear a specified region of memory to zero.
77* @static @public @memberof QF
78*
79* @details
80* Clears a memory buffer by writing zeros byte-by-byte.
81*
82* @param[in] start pointer to the beginning of a memory buffer.
83* @param[in] len length of the memory buffer to clear (in bytes)
84*
85* @note The main application of this function is clearing the internal QF
86* variables upon startup. This is done to avoid problems with non-standard
87* startup code provided with some compilers and toolsets (e.g., TI DSPs or
88* Microchip MPLAB), which does not zero the uninitialized variables, as
89* required by the ANSI C standard.
90*
91* @trace
92* - @tr{DVR-QP-MC3-R11_05}
93*/
95 void * const start,
96 uint_fast16_t const len);
97/*$enddecl${QF::QF-pkg} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/
98
99/*==========================================================================*/
100/* QF-specific critical section */
101#ifndef QF_CRIT_STAT_TYPE
102 /*! This is an internal macro for defining the critical section
103 * status type. */
104 /**
105 * @details
106 * The purpose of this macro is to enable writing the same code for the
107 * case when critical section status type is defined and when it is not.
108 * If the macro #QF_CRIT_STAT_TYPE is defined, this internal macro
109 * provides the definition of the critical section status variable.
110 * Otherwise this macro is empty.
111 * @sa #QF_CRIT_STAT_TYPE
112 */
113 #define QF_CRIT_STAT_
114
115 /*! This is an internal macro for entering a critical section. */
116 /**
117 * @details
118 * The purpose of this macro is to enable writing the same code for the
119 * case when critical section status type is defined and when it is not.
120 * If the macro #QF_CRIT_STAT_TYPE is defined, this internal macro
121 * invokes QF_CRIT_ENTRY() passing the key variable as the parameter.
122 * Otherwise QF_CRIT_ENTRY() is invoked with a dummy parameter.
123 * @sa QF_CRIT_ENTRY()
124 *
125 * @trace
126 * - @tr{DVP-QP-MC3-D04_09A}
127 */
128 #define QF_CRIT_E_() QF_CRIT_ENTRY(dummy)
129
130 /*! This is an internal macro for exiting a critical section. */
131 /**
132 * @details
133 * The purpose of this macro is to enable writing the same code for the
134 * case when critical section status type is defined and when it is not.
135 * If the macro #QF_CRIT_STAT_TYPE is defined, this internal macro
136 * invokes #QF_CRIT_EXIT passing the key variable as the parameter.
137 * Otherwise #QF_CRIT_EXIT is invoked with a dummy parameter.
138 * @sa #QF_CRIT_EXIT
139 *
140 * @trace
141 * - @tr{DVP-QP-MC3-D04_09A}
142 */
143 #define QF_CRIT_X_() QF_CRIT_EXIT(dummy)
144
145#elif (!defined QF_CRIT_STAT_)
146 #define QF_CRIT_STAT_ QF_CRIT_STAT_TYPE critStat_;
147 #define QF_CRIT_E_() QF_CRIT_ENTRY(critStat_)
148 #define QF_CRIT_X_() QF_CRIT_EXIT(critStat_)
149#endif
150
151/*==========================================================================*/
152/* Assertions inside the critical section */
153#ifndef QP_NSSM
154
155 /*! General-purpose assertion invoked inside a critical section,
156 * when QP Software Self-Monitoring (SSM) is enabled
157 *
158 * @trace
159 * - @tr{DVP-QP-MC3-D04_09A}
160 */
161 #define Q_ASSERT_CRIT_(id_, test_) do { \
162 if ((test_)) {} else { \
163 QF_CRIT_X_(); \
164 Q_onAssert(&Q_this_module_[0], (int_t)(id_)); \
165 } \
166 } while (false)
167
168 /*! Precondition assertion invoked inside a critical section
169 *
170 * @trace
171 * - @tr{DVP-QP-MC3-D04_09A}
172 */
173 #define Q_REQUIRE_CRIT_(id_, test_) Q_ASSERT_CRIT_((id_), (test_))
174
175 /*! Error assertion invoked inside a critical section
176 *
177 * @trace
178 * - @tr{DVP-QP-MC3-D04_09A}
179 */
180 #define Q_ERROR_CRIT_(id_) do { \
181 QF_CRIT_X_(); \
182 Q_onAssert(&Q_this_module_[0], (int_t)(id_)); \
183 } while (false)
184
185#else /* QP Software Self-Monitoring (SSM) disabled */
186 #define Q_ASSERT_CRIT_(id_, test_) ((void)0)
187 #define Q_REQUIRE_CRIT_(id_, test_) ((void)0)
188 #define Q_ERROR_CRIT_(id_) ((void)0)
189#endif /* QP_NSSM */
190
191/*==========================================================================*/
192
193/* The following bitmasks are for the fields of the @c refCtr_ attribute
194* of the QTimeEvt struct (inherited from QEvt). This attribute is NOT used
195* for reference counting in time events, because the @c poolId_ attribute
196* is zero ("immutable events").
197*/
198#define QTE_IS_LINKED (1U << 7U)
199#define QTE_WAS_DISARMED (1U << 6U)
200#define QTE_TICK_RATE 0x0FU
201
202/*! @brief structure representing a free block in the Native QF Memory Pool */
203typedef struct QFreeBlock {
204 struct QFreeBlock * volatile next;
205} QFreeBlock;
206
207/* internal helper macros ==================================================*/
208
209/*! increment the refCtr of a const event (requires casting `const` away)
210* @private @memberof QEvt
211*
212* @trace
213* - @tr{DVR-QP-MC3-R11_08}
214*/
215static inline void QEvt_refCtr_inc_(QEvt const *me) {
216 ++((QEvt *)me)->refCtr_;
217}
218
219/*! decrement the refCtr of a const event (requires casting `const` away)
220* @private @memberof QEvt
221*
222* @trace
223* - @tr{DVR-QP-MC3-R11_08}
224*/
225static inline void QEvt_refCtr_dec_(QEvt const *me) {
226 --((QEvt *)me)->refCtr_;
227}
228
229#endif /* QF_PKG_H_ */
struct QFreeBlock *volatile next
Definition: qf_pkg.h:204
QF_EPOOL_TYPE_ QF_ePool_[QF_MAX_EPOOL]
uint_fast8_t QF_maxPool_
structure representing a free block in the Native QF Memory Pool
Definition: qf_pkg.h:203
#define QF_MAX_EPOOL
Definition: qf_port.h:111
#define QF_EPOOL_TYPE_
Definition: qk.h:286
Event class.
Definition: qep.h:171
static void QEvt_refCtr_dec_(QEvt const *me)
Definition: qf_pkg.h:225
static void QEvt_refCtr_inc_(QEvt const *me)
Definition: qf_pkg.h:215
void QF_bzero(void *const start, uint_fast16_t const len)
QPSet QF_readySet_rmc_
Definition: qf_pkg.h:72
QPSet QF_readySet_
Definition: qf_pkg.h:65
Priority Set of up to QF_MAX_ACTIVE elements.
Definition: qf.h:234