stepper_controller/arduino/include/qkn.h

   1 /*****************************************************************************
   2 * Product: QK-nano public interface
   3 * Last Updated for Version: 4.0.02
   4 * Date of the Last Update:  Aug 11, 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 qkn_h
  29 #define qkn_h
  30
  31 /**
  32 * \file
  33 * \ingroup qepn qfn qkn
  34 * \brief Public QP-nano interface.
  35 *
  36 * This header file must be included in all modules that use QP-nano with
  37 * preemptive kernel option. Typically, this header file is included
  38 * indirectly through the header file qpn.h.
  39 */
  40
  41 /** \brief Preprocessor switch for configuring preemptive real-time kernel
  42 * (QK-nano). The macro is automatically defined by including the qkn.h file
  43 * in qpn_port.h.
  44 *
  45 * \note If defined, this macro eliminates the code for the non-preemptive
  46 * scheduler provided in QF-nano. Instead, the fully preemptive QK-nano
  47 * real-time kernel is used.
  48 */
  49 #define QK_PREEMPTIVE   1
  50
  51 /** \brief QK-nano initialization.
  52 *
  53 * This function is optional and might be used in some QK-nano ports.
  54 * When the function is defined, it must called exactly once before any
  55 * other QK function, typically from the BSP initialization function.
  56 */
  57 void QK_init(void);
  58
  59 /** \brief The QK scheduler
  60 *
  61 * \note The QK scheduler must be always called with interrupts locked.
  62 * The scheduler might unlock the interrupts internally, but always returns
  63 * with interrupts locked.
  64 */
  65 void QK_schedule_(void) Q_REENTRANT;
  66
  67 /** \brief QK idle callback (customized in BSPs for QK)
  68 *
  69 * QK_onIdle() is called continously by the QK-nano idle loop. This callback
  70 * gives the application an opportunity to enter a power-saving CPU mode,
  71 * or perform some other idle processing.
  72 *
  73 * \note QK_onIdle() is invoked with interrupts unlocked and must also
  74 * return with interrupts unlocked. This is in contrast to the callback
  75 * QF_onIdle(), which is used by the non-preemptive QF-nano scheduler.
  76 */
  77 void QK_onIdle(void);
  78
  79 extern uint8_t volatile QK_currPrio_;              /**< current QK priority */
  80
  81 #ifndef QF_ISR_NEST
  82     /** \brief The macro to invoke the QK scheduler in the QK_ISR_EXIT()
  83     */
  84     #define QK_SCHEDULE_() \
  85         if (QF_readySet_ != (uint8_t)0) { \
  86             QK_schedule_(); \
  87         } else ((void)0)
  88 #else
  89     #define QK_SCHEDULE_() \
  90         if ((QF_readySet_ != (uint8_t)0) && (QK_intNest_ == (uint8_t)0)) { \
  91             QK_schedule_(); \
  92         } else ((void)0)
  93
  94     extern uint8_t volatile QK_intNest_;       /**< interrupt nesting level */
  95 #endif
  96
  97
  98 #ifdef QK_MUTEX
  99
 100     /** \brief QK Mutex type.
 101     *
 102     * QMutex represents the priority-ceiling mutex available in QK.
 103     * \sa QK_mutexLock()
 104     * \sa QK_mutexUnlock()
 105     */
 106     typedef uint8_t QMutex;
 107
 108     /** \brief QK priority-ceiling mutex lock
 109     *
 110     * Lock the QK scheduler up to the priority level \a prioCeiling.
 111     *
 112     * \note This function should be always paired with QK_mutexUnlock().
 113     * The code between QK_mutexLock() and QK_mutexUnlock() should be kept
 114     * to the minimum.
 115     */
 116     QMutex QK_mutexLock(uint8_t prioCeiling);
 117
 118     /** \brief QK priority-ceiling mutex unlock
 119     *
 120     * \note This function should be always paired with QK_mutexLock().
 121     * The code between QK_mutexLock() and QK_mutexUnlock() should be kept
 122     * to the minimum.
 123     */
 124     void QK_mutexUnlock(QMutex mutex);
 125
 126 #endif                                                          /* QK_MUTEX */
 127
 128 #endif                                                             /* qkn_h */