stepper_controller/arduino/include/qfn.h

   1 /*****************************************************************************
   2 * Product: QF-nano public interface
   3 * Last Updated for Version: 4.0.01
   4 * Date of the Last Update:  Jun 08, 2008
   5 *
   6 *                    Q u a n t u m     L e a P s
   7 *                    ---------------------------
   8 *                    innovating embedded systems
   9 *
  10 * Copyright (C) 2002-2008 Quantum Leaps, LLC. All rights reserved.
  11 *
  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").
  18 *
  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.
  23 *
  24 * Contact information:
  25 * Quantum Leaps Web site:  http://www.quantum-leaps.com
  26 * e-mail:                  [email protected]
  27 *****************************************************************************/
  28 #ifndef qfn_h
  29 #define qfn_h
  30
  31 /**
  32 * \file
  33 * \ingroup qepn qfn qkn
  34 * \brief Public QF-nano interface.
  35 *
  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.
  39 */
  40
  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."
  44 #endif
  45 #if (defined QF_FSM_ACTIVE) && (defined Q_NFSM)
  46     #error "QF_FSM_ACTIVE and Q_NFSM cannot be defined at the same time."
  47 #endif
  48 #if (!defined QF_FSM_ACTIVE) && (defined Q_NHSM)
  49     #error "Q_NHSM defined without defining QF_FSM_ACTIVE."
  50 #endif
  51
  52
  53 /****************************************************************************/
  54 /* default macros for accessing data in ROM */
  55 #ifndef Q_ROM_BYTE
  56     /** \brief Macro to access a byte allocated in ROM
  57     *
  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
  63     * address.
  64     *
  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
  69     * the correct code.
  70     */
  71     #define Q_ROM_BYTE(rom_var_)   (rom_var_)
  72 #endif
  73 #ifndef Q_ROM_PTR
  74     /** \brief Macro to access a pointer allocated in ROM
  75     *
  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
  82     * in RAM or ROM.
  83     *
  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
  88     * the correct code.
  89     */
  90     #define Q_ROM_PTR(rom_var_)    (rom_var_)
  91 #endif
  92
  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
  96     */
  97     #define QF_TIMEEVT_CTR_SIZE 0
  98 #endif
  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.
 105     *
 106     * This typedef is configurable via the preprocessor switch
 107     * #QF_TIMEEVT_CTR_SIZE. The other possible values of this type are
 108     * as follows: \n
 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).
 113     */
 114     typedef uint16_t QTimeEvtCtr;
 115 #elif (QF_TIMEEVT_CTR_SIZE == 4)
 116     typedef uint32_t QTimeEvtCtr;
 117 #else
 118     #error "QF_TIMER_SIZE defined incorrectly, expected 1, 2, or 4"
 119 #endif
 120
 121 /****************************************************************************/
 122 /** \brief Active Object struct
 123 *
 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.
 130 *
 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
 133 * application code.
 134 *
 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
 139 *
 140 * \sa ::QActiveTag for the description of the data members \n \ref derivation
 141 */
 142 typedef struct QActiveTag {
 143
 144 #ifndef QF_FSM_ACTIVE
 145     QHsm super;                 /**< derives from the ::QHsm base structure */
 146 #else
 147     QFsm super;                 /**< derives from the ::QFsm base structure */
 148 #endif
 149
 150     /** \brief priority of the active object (1..QF_MAX_ACTIVE)
 151     */
 152     uint8_t prio;
 153
 154     /** \brief offset to where next event will be inserted into the buffer
 155     */
 156     uint8_t head;
 157
 158     /** \brief offset of where next event will be extracted from the buffer
 159     */
 160     uint8_t tail;
 161
 162     /** \brief number of events currently present in the queue
 163     * (events in the ring buffer + 1 event in the state machine)
 164     */
 165     uint8_t nUsed;
 166
 167 #if (QF_TIMEEVT_CTR_SIZE != 0)
 168     /** \brief Time Event tick counter for the active object
 169     */
 170     QTimeEvtCtr tickCtr;
 171 #endif
 172 } QActive;
 173
 174
 175 /** \brief Active object constructor.
 176 *
 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.
 179 *
 180 * \note Must be called exactly ONCE for each active object
 181 * in the application before calling QF_run().
 182 */
 183 #ifndef QF_FSM_ACTIVE
 184     #define QActive_ctor(me_, initial_)  QHsm_ctor(&(me_)->super, initial_)
 185 #else
 186     #define QActive_ctor(me_, initial_)  QFsm_ctor(&(me_)->super, initial_)
 187 #endif
 188
 189
 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
 194     * queue integrity.
 195     *
 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
 201     *
 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.
 205     *
 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()
 210     * function.
 211     *
 212     * \note This function is intended only to be used at the task level
 213     * and shouln never be used inside ISRs.
 214     */
 215     void QActive_post(QActive *me, QSignal sig, QParam par);
 216
 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.
 222     *
 223     * \note This function is intended only to be used inside ISRs and you
 224     * should never use at the task level.
 225     *
 226     * \sa QF_post()
 227     */
 228     void QActive_postISR(QActive *me, QSignal sig, QParam par);
 229
 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
 233     * queue integrity.
 234     *
 235     * The posted event will be the next event to be consumed by the task.
 236     *
 237     * \note This function is intended only to be used at the task level
 238     * and should never be used inside ISRs.
 239     */
 240     void QActive_postLIFO(QActive *me, QSignal sig, QParam par);
 241
 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.
 247     *
 248     * The posted event will be the next event to be consumed by the task.
 249     *
 250     * \note This function is intended only to be used inside ISRs and you
 251     * should never use at the task level.
 252     *
 253     * \sa QF_postLIFO()
 254     */
 255     void QActive_postISRLIFO(QActive *me, QSignal sig, QParam par);
 256 #else
 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);
 261 #endif
 262
 263 #if (QF_TIMEEVT_CTR_SIZE != 0)
 264
 265     /** \brief Processes all armed time events at every clock tick.
 266     *
 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.
 269     *
 270     * The following example illustrates the call to QF_tick():
 271     * \include qfn_tick.c
 272     */
 273     void QF_tick(void);
 274
 275 #if (QF_TIMEEVT_CTR_SIZE == 1)                 /* single-byte tick counter? */
 276
 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.
 280     *
 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_.
 285     *
 286     * After posting, the time event gets automatically disarmed.
 287     *
 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.
 292     *
 293     * The following example shows how to arm a one-shot time event from
 294     * a state machine of an active object:
 295     * \include qfn_arm.c
 296     */
 297     #define QActive_arm(me_, tout_) ((me_)->tickCtr = (QTimeEvtCtr)(tout_))
 298
 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.
 302     *
 303     * The time event of the active object \param me_ gets disarmed (stopped).
 304     *
 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.
 308     */
 309     #define QActive_disarm(me_)     ((me_)->tickCtr = (QTimeEvtCtr)0)
 310
 311 #else                                            /* multi-byte tick counter */
 312
 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.
 316     *
 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.
 321     *
 322     * After posting, the time event gets automatically disarmed.
 323     *
 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.
 328     *
 329     * The following example shows how to arm a one-shot time event from
 330     * a state machine of an active object:
 331     * \include qfn_arm.c
 332     */
 333     void QActive_arm(QActive *me, QTimeEvtCtr tout);
 334
 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.
 338     *
 339     * The time event of the active object \a me gets disarmed (stopped).
 340     *
 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.
 344     */
 345     void QActive_disarm(QActive *me);
 346
 347 #endif                                        /* (QF_TIMEEVT_CTR_SIZE == 1) */
 348
 349 #endif                                        /* (QF_TIMEEVT_CTR_SIZE != 0) */
 350
 351 /* protected methods ...*/
 352
 353 /** \brief QF-nano termination.
 354 *
 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.
 359 */
 360 void QF_stop(void);
 361
 362 /** \brief Startup QF-nano callback.
 363 *
 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.
 367 *
 368 * \sa QF initialization example for ::QActiveCB.
 369 */
 370 void QF_onStartup(void);
 371
 372 /** \brief Transfers control to QF to run the application.
 373 *
 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[].
 377 *
 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.
 385 */
 386 void QF_run(void);
 387
 388
 389 #ifndef QK_PREEMPTIVE
 390     /** \brief QF idle callback (customized in BSPs for QF)
 391     *
 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.
 396     *
 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
 403     * permanently.
 404     *
 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().
 409     */
 410 void QF_onIdle(void);
 411 #endif
 412
 413 /****************************************************************************/
 414 /** \brief QActive Control Block
 415 *
 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.
 419 *
 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
 423 */
 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 */
 428 } QActiveCB;
 429
 430                                            /** active object control blocks */
 431 extern QActiveCB const Q_ROM Q_ROM_VAR QF_active[];
 432
 433 /** \brief Ready set of QF-nano.
 434 *
 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
 441 * objects maximum.
 442 */
 443 extern uint8_t volatile QF_readySet_;
 444
 445 #endif                                                             /* qfn_h */