1 /*****************************************************************************
2 * Product: QF-nano public interface
3 * Last Updated for Version: 4.0.01
4 * Date of the Last Update: Jun 08, 2008
6 * Q u a n t u m L e a P s
7 * ---------------------------
8 * innovating embedded systems
10 * Copyright (C) 2002-2008 Quantum Leaps, LLC. All rights reserved.
12 * This software may be distributed and modified under the terms of the GNU
13 * General Public License version 2 (GPL) as published by the Free Software
14 * Foundation and appearing in the file GPL.TXT included in the packaging of
15 * this file. Please note that GPL Section 2[b] requires that all works based
16 * on this software must also be made publicly available under the terms of
17 * the GPL ("Copyleft").
19 * Alternatively, this software may be distributed and modified under the
20 * terms of Quantum Leaps commercial licenses, which expressly supersede
21 * the GPL and are specifically designed for licensees interested in
22 * retaining the proprietary status of their code.
24 * Contact information:
25 * Quantum Leaps Web site: http://www.quantum-leaps.com
27 *****************************************************************************/
33 * \ingroup qepn qfn qkn
34 * \brief Public QF-nano interface.
36 * This header file must be included in all modules that use QP-nano.
37 * Typically, this header file is included indirectly through the
38 * header file qpn_port.h.
41 /****************************************************************************/
42 #if (QF_MAX_ACTIVE < 1) || (8 < QF_MAX_ACTIVE)
43 #error "QF_MAX_ACTIVE not defined or out of range. Valid range is 1..8."
45 #if (defined QF_FSM_ACTIVE) && (defined Q_NFSM)
46 #error "QF_FSM_ACTIVE and Q_NFSM cannot be defined at the same time."
48 #if (!defined QF_FSM_ACTIVE) && (defined Q_NHSM)
49 #error "Q_NHSM defined without defining QF_FSM_ACTIVE."
53 /****************************************************************************/
54 /* default macros for accessing data in ROM */
56 /** \brief Macro to access a byte allocated in ROM
58 * Some compilers for Harvard-architecture MCUs, such as gcc for AVR, do
59 * not generate correct code for accessing data allocated in the program
60 * space (ROM). The workaround for such compilers is to explictly add
61 * assembly code to access each data element allocated in the program
62 * space. The macro Q_ROM_BYTE() retrieves a byte from the given ROM
65 * The Q_ROM_BYTE() macro should be defined in the qpn_port.h header file
66 * for each compiler that cannot handle correctly data allocated in ROM
67 * (such as the gcc). If the macro is left undefined, the default
68 * definition simply returns the argument and lets the compiler synthesize
71 #define Q_ROM_BYTE(rom_var_) (rom_var_)
74 /** \brief Macro to access a pointer allocated in ROM
76 * Some compilers for Harvard-architecture MCUs, such as gcc for AVR, do
77 * not generate correct code for accessing data allocated in the program
78 * space (ROM). The workaround for such compilers is to explictly add
79 * assembly code to access each data element allocated in the program
80 * space. The macro Q_ROM_PTR() retrieves an object-pointer from the given
81 * ROM address. Please note that the pointer can be pointing to the object
84 * The Q_ROM_PTR() macro should be defined in the qpn_port.h header file
85 * for each compiler that cannot handle correctly data allocated in ROM
86 * (such as the gcc). If the macro is left undefined, the default
87 * definition simply returns the argument and lets the compiler synthesize
90 #define Q_ROM_PTR(rom_var_) (rom_var_)
93 #ifndef QF_TIMEEVT_CTR_SIZE
94 /** \brief macro to override the default QTimeEvtCtr size.
95 * Valid values 0, 1, 2, or 4; default 0
97 #define QF_TIMEEVT_CTR_SIZE 0
99 #if (QF_TIMEEVT_CTR_SIZE == 0)
100 #elif (QF_TIMEEVT_CTR_SIZE == 1)
101 typedef uint8_t QTimeEvtCtr;
102 #elif (QF_TIMEEVT_CTR_SIZE == 2)
103 /** \brief type of the Time Event counter, which determines the dynamic
104 * range of the time delays measured in clock ticks.
106 * This typedef is configurable via the preprocessor switch
107 * #QF_TIMEEVT_CTR_SIZE. The other possible values of this type are
109 * none when (QF_TIMEEVT_CTR_SIZE not defined or == 0), \n
110 * uint8_t when (QF_TIMEEVT_CTR_SIZE == 1); \n
111 * uint16_t when (QF_TIMEEVT_CTR_SIZE == 2); and \n
112 * uint32_t when (QF_TIMEEVT_CTR_SIZE == 4).
114 typedef uint16_t QTimeEvtCtr;
115 #elif (QF_TIMEEVT_CTR_SIZE == 4)
116 typedef uint32_t QTimeEvtCtr;
118 #error "QF_TIMER_SIZE defined incorrectly, expected 1, 2, or 4"
121 /****************************************************************************/
122 /** \brief Active Object struct
124 * QActive is the base structure for derivation of active objects. Active
125 * objects in QF-nano are encapsulated tasks (each embedding a state machine
126 * and an event queue) that communicate with one another asynchronously by
127 * sending and receiving events. Within an active object, events are
128 * processed sequentially in a run-to-completion (RTC) fashion, while QF
129 * encapsulates all the details of thread-safe event exchange and queuing.
131 * \note ::QActive is not intended to be instantiated directly, but rather
132 * serves as the base structure for derivation of active objects in the
135 * The following example illustrates how to derive an active object from
136 * QActive. Please note that the QActive member super_ is defined as the
137 * FIRST member of the derived struct.
138 * \include qfn_qactive.c
140 * \sa ::QActiveTag for the description of the data members \n \ref derivation
142 typedef struct QActiveTag {
144 #ifndef QF_FSM_ACTIVE
145 QHsm super; /**< derives from the ::QHsm base structure */
147 QFsm super; /**< derives from the ::QFsm base structure */
150 /** \brief priority of the active object (1..QF_MAX_ACTIVE)
154 /** \brief offset to where next event will be inserted into the buffer
158 /** \brief offset of where next event will be extracted from the buffer
162 /** \brief number of events currently present in the queue
163 * (events in the ring buffer + 1 event in the state machine)
167 #if (QF_TIMEEVT_CTR_SIZE != 0)
168 /** \brief Time Event tick counter for the active object
175 /** \brief Active object constructor.
177 * \a me pointer the active object structure derived from ::QActive.
178 * \a initial is the pointer to the initial state of the active object.
180 * \note Must be called exactly ONCE for each active object
181 * in the application before calling QF_run().
183 #ifndef QF_FSM_ACTIVE
184 #define QActive_ctor(me_, initial_) QHsm_ctor(&(me_)->super, initial_)
186 #define QActive_ctor(me_, initial_) QFsm_ctor(&(me_)->super, initial_)
190 #if (Q_PARAM_SIZE != 0)
191 /** \brief Posts an event \a e directly to the event queue of the acitve
192 * object \a prio using the First-In-First-Out (FIFO) policy. This
193 * function briefly locks and unlocks interrupts to protect the
196 * Direct event posting is the only asynchronous communication method
197 * available in QF-nano. The following example illustrates how the
198 * Ped active object posts directly the PED_WAITING event to the PELICAN
199 * crossing active object.
200 * \include qfn_post.c
202 * The producer of the event (Ped in this case) must only "know"
203 * a pointer recipient (&AO_Pelican), but the specific definition of
204 * the Pelican structure is not required.
206 * Direct event posting should not be confused with direct event
207 * dispatching. In contrast to asynchronous event posting through event
208 * queues, direct event dispatching is synchronous. Direct event
209 * dispatching occurs when you call QHsm_dispatch(), or QFsm_dispatch()
212 * \note This function is intended only to be used at the task level
213 * and shouln never be used inside ISRs.
215 void QActive_post(QActive *me, QSignal sig, QParam par);
217 /** \brief Posts an event \a e directly to the event queue of the acitve
218 * object \a prio using the First-In-First-Out (FIFO) policy. This
219 * function does NOT lock/unlock interrupts when nesting of interrupts
220 * is not allowed. Also, this function never calls the QK-nano scheduler,
221 * because synchronous task preemptions are never necessary inside ISRs.
223 * \note This function is intended only to be used inside ISRs and you
224 * should never use at the task level.
228 void QActive_postISR(QActive *me, QSignal sig, QParam par);
230 /** \brief Posts an event \a directly to the event queue of the active
231 * object \a prio using the Last-In-First-Out (LIFO) policy. This
232 * function briefly locks and unlocks interrupts to protect the
235 * The posted event will be the next event to be consumed by the task.
237 * \note This function is intended only to be used at the task level
238 * and should never be used inside ISRs.
240 void QActive_postLIFO(QActive *me, QSignal sig, QParam par);
242 /** \brief Posts an event \a e directly to the event queue of the acitve
243 * object \a prio using the Last-In-First-Out (LIFO) policy. This
244 * function does NOT lock/unlock interrupts when nesting of interrupts
245 * is not allowed. Also, this function never calls the QK-nano scheduler,
246 * because synchronous task preemptions are never necessary inside ISRs.
248 * The posted event will be the next event to be consumed by the task.
250 * \note This function is intended only to be used inside ISRs and you
251 * should never use at the task level.
255 void QActive_postISRLIFO(QActive *me, QSignal sig, QParam par);
257 void QActive_post(QActive *me, QSignal sig);
258 void QActive_postISR(QActive *me, QSignal sig);
259 void QActive_postLIFO(QActive *me, QSignal sig);
260 void QActive_postISRLIFO(QActive *me, QSignal sig);
263 #if (QF_TIMEEVT_CTR_SIZE != 0)
265 /** \brief Processes all armed time events at every clock tick.
267 * \note This function can be only calle from the ISR-level. You must also
268 * guarantee that QF_tick() runs to completion before it is called again.
270 * The following example illustrates the call to QF_tick():
271 * \include qfn_tick.c
275 #if (QF_TIMEEVT_CTR_SIZE == 1) /* single-byte tick counter? */
277 /** \brief Arm the QP-nano one-shot time event. Since the tick counter
278 * is a single byte in this case, the time event can be atomically
279 * armed without using a critical section.
281 * Arms the time event of the active object \param me_ to expire in
282 * \param tout_ clock ticks (one-shot time event). Upon the expiration,
283 * the time event posts the reserved signal Q_TIMEOUT_SIG directly
284 * into the event queue of the active object \param me_.
286 * After posting, the time event gets automatically disarmed.
288 * The time event can be disarmed (stoped) at any time by calling the
289 * QActive_disarm() function. Also, a one-shot time event can be re-armed
290 * to fire in a different number of clock ticks by calling
291 * QActive_arm() again.
293 * The following example shows how to arm a one-shot time event from
294 * a state machine of an active object:
297 #define QActive_arm(me_, tout_) ((me_)->tickCtr = (QTimeEvtCtr)(tout_))
299 /** \brief Disarm a time event. Since the tick counter
300 * is a single byte in this case, the time event can be atomically
301 * disarmed without using a critical section.
303 * The time event of the active object \param me_ gets disarmed (stopped).
305 * \note You should not assume that the Q_TIMEOUT_SIG event will not
306 * arrive after you disarm the time event. The timeout evetn could be
307 * already in the event queue.
309 #define QActive_disarm(me_) ((me_)->tickCtr = (QTimeEvtCtr)0)
311 #else /* multi-byte tick counter */
313 /** \brief Arm the QP-nano one-shot time event. Since the tick counter
314 * is a multi-byte variable in this case, the operation must be
315 * performed inside a critical section.
317 * Arms the time event of the active object \a me to expire in
318 * \a tout clock ticks (one-shot time event). Upon the expiration,
319 * the time event posts the reserved signal Q_TIMEOUT_SIG directly
320 * into the event queue of the active object \a me.
322 * After posting, the time event gets automatically disarmed.
324 * The time event can be disarmed (stoped) at any time by calling the
325 * QActive_disarm() function. Also, a one-shot time event can be re-armed
326 * to fire in a different number of clock ticks by calling
327 * QActive_arm() again.
329 * The following example shows how to arm a one-shot time event from
330 * a state machine of an active object:
333 void QActive_arm(QActive *me, QTimeEvtCtr tout);
335 /** \brief Disarm a time event. Since the tick counter
336 * is a multi-byte variable in this case, the operation must be
337 * performed inside a critical section.
339 * The time event of the active object \a me gets disarmed (stopped).
341 * \note You should not assume that the Q_TIMEOUT_SIG event will not
342 * arrive after you disarm the time event. The timeout evetn could be
343 * already in the event queue.
345 void QActive_disarm(QActive *me);
347 #endif /* (QF_TIMEEVT_CTR_SIZE == 1) */
349 #endif /* (QF_TIMEEVT_CTR_SIZE != 0) */
351 /* protected methods ...*/
353 /** \brief QF-nano termination.
355 * This function terminates QF and performs any necessary cleanup.
356 * In QF-nano this function is defined in the BSP. Many QF ports might not
357 * require implementing QF_stop() at all, because many embedded applications
358 * don't have anything to exit to.
362 /** \brief Startup QF-nano callback.
364 * The timeline for calling QF_onStartup() depends on the particular
365 * QF port. In most cases, QF_onStartup() is called from QF_run(), right
366 * before starting any multitasking kernel or the background loop.
368 * \sa QF initialization example for ::QActiveCB.
370 void QF_onStartup(void);
372 /** \brief Transfers control to QF to run the application.
374 * QF_run() implemetns the simple non-preemptive scheduler. QF_run() must be
375 * called from your startup code after you initialize the QF and define at
376 * least one active object control block in QF_active[].
378 * \note When the Quantum Kernel (QK) is used as the underlying real-time
379 * kernel for the QF, all platfrom dependencies are handled in the QK, so
380 * no porting of QF is necessary. In other words, you only need to recompile
381 * the QF platform-independent code with the compiler for your platform, but
382 * you don't need to provide any platform-specific implementation (so, no
383 * qf_port.c file is necessary). Moreover, QK implements the function QF_run()
384 * in a platform-independent way, in the modile qk.c.
389 #ifndef QK_PREEMPTIVE
390 /** \brief QF idle callback (customized in BSPs for QF)
392 * QF_onIdle() is called by the non-preemptive scheduler built into QF-nano
393 * when the QF-nano detects that no events are available for active objects
394 * (the idle condition). This callback gives the application an opportunity
395 * to enter a power-saving CPU mode, or perform some other idle processing.
397 * \note QF_onIdle() is invoked with interrupts LOCKED because the idle
398 * condition can be asynchronously changed at any time by an interrupt.
399 * QF_onIdle() MUST unlock the interrupts internally, but not before
400 * putting the CPU into the low-power mode. (Ideally, unlocking interrupts
401 * and low-power mode should happen atomically). At the very least, the
402 * function MUST unlock interrupts, otherwise interrups will be locked
405 * \note QF_onIdle() is not used in the PREEMPTIVE configuration. When
406 * QK_PREEMPTIVE macro is defined, the preemptive kernel QK-nano is used
407 * instead of the non-preemptive QF-nano scheduler. QK-nano uses a
408 * different idle callback \sa QK_onIdle().
410 void QF_onIdle(void);
413 /****************************************************************************/
414 /** \brief QActive Control Block
416 * QActiveCB represents the constant information that the QF-nano needs
417 * to manage the active object. QActiveCB objects are grouped in the
418 * array QF_active[], which typically can be placed in ROM.
420 * The following example illustrates how to allocate and initialize the
421 * QActive control blocks in the array QF_active[].
422 * \include qfn_main.c
424 typedef struct QActiveCBTag {
425 QActive *act; /**< \brief pointer to the active object structure */
426 QEvent *queue; /**< \brief pointer to the event queue buffer */
427 uint8_t end; /**< \brief the length of the ring buffer */
430 /** active object control blocks */
431 extern QActiveCB const Q_ROM Q_ROM_VAR QF_active[];
433 /** \brief Ready set of QF-nano.
435 * The QF-nano ready set keeps track of active objects that are ready to run.
436 * The ready set represents each active object as a bit, with the bits
437 * assigned according to priorities of the active objects. The bit is set
438 * if the corresponding active object is ready to run (i.e., has one or
439 * more events in its event queue) and zero if the event queue is empty.
440 * The QF-nano ready set is one byte-wide, which corresponds to 8 active
443 extern uint8_t volatile QF_readySet_;