LUFA/Scheduler/Scheduler.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2011.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *  \brief Simple round-robbin pseudo-task scheduler.
  33  *
  34  *  Simple round-robbin cooperative scheduler for use in basic projects where non real-time tasks need
  35  *  to be executed. Each task is executed in sequence, and can be enabled or disabled individually or as a group.
  36  *
  37  *  \deprecated This module is deprecated and will be removed in a future library release.
  38  */
  39
  40 /** @defgroup Group_Scheduler Simple Task Scheduler - LUFA/Scheduler/Scheduler.h
  41  *
  42  *  \deprecated This module is deprecated and will be removed in a future library release.
  43  *
  44  *  \section Sec_Dependencies Module Source Dependencies
  45  *  The following files must be built with any user project that uses this module:
  46  *    - LUFA/Scheduler/Scheduler.c <i>(Makefile source module name: LUFA_SRC_SCHEDULER)</i>
  47  *
  48  *  \section Sec_ModDescription Module Description
  49  *  Simple round-robbin cooperative scheduler for use in basic projects where non real-time tasks need
  50  *  to be executed. Each task is executed in sequence, and can be enabled or disabled individually or as a group.
  51  *
  52  *  For a task to yield it must \c return, thus each task should have persistent data marked with the \c static keyword.
  53  *
  54  *  Each LUFA scheduler task should be written similar to an ISR; it should execute quickly (so that no one task
  55  *  hogs the processor, preventing another from running before some sort of timeout is exceeded). Unlike normal RTOS
  56  *  tasks, each LUFA scheduler task is a regular function, and thus must be designed to be called, and designed to
  57  *  return to the calling scheduler function repeatedly. Data which must be preserved between task calls should be
  58  *  declared as global or (preferably) as a \c static local variable inside the task.
  59  *
  60  *  The scheduler consists of a task list, listing all the tasks which can be executed by the scheduler. Once started,
  61  *  each task is then called one after another, unless the task is stopped by another running task or interrupt.
  62  *
  63  *  Usage Example:
  64  *  \code
  65  *      #include <LUFA/Scheduler/Scheduler.h>
  66  *
  67  *      TASK(MyTask1); // Task prototype
  68  *      TASK(MyTask2); // Task prototype
  69  *
  70  *      TASK_LIST
  71  *      {
  72  *          { .Task = MyTask1, .TaskStatus = TASK_RUN, .GroupID = 1  },
  73  *          { .Task = MyTask2, .TaskStatus = TASK_RUN, .GroupID = 1  },
  74  *      }
  75  *
  76  *      int main(void)
  77  *      {
  78  *          Scheduler_Init();
  79  *
  80  *          // Other initialisation here
  81  *
  82  *          Scheduler_Start();
  83  *      }
  84  *
  85  *      TASK(MyTask1)
  86  *      {
  87  *          // Task implementation here
  88  *      }
  89  *
  90  *      TASK(MyTask2)
  91  *      {
  92  *          // Task implementation here
  93  *      }
  94  *  \endcode
  95  *
  96  *  If desired, the LUFA scheduler <b>does not need to be used</b> in a LUFA powered application. A more conventional
  97  *  approach to application design can be used, or a proper scheduling RTOS inserted in the place of the LUFA scheduler.
  98  *  In the case of the former the USB task must be run manually repeatedly to maintain USB communications, and in the
  99  *  case of the latter a proper RTOS task must be set up to do the same.
 100  *
 101  *  @{
 102  */
 103
 104 #ifndef __SCHEDULER_H__
 105 #define __SCHEDULER_H__
 106
 107         /* Includes: */
 108                 #include <stdint.h>
 109                 #include <stdbool.h>
 110
 111                 #include <util/atomic.h>
 112
 113                 #include "../Common/Common.h"
 114
 115         /* Enable C linkage for C++ Compilers: */
 116                 #if defined(__cplusplus)
 117                         extern "C" {
 118                 #endif
 119
 120         /* Public Interface - May be used in end-application: */
 121                 /* Macros: */
 122                         /** Creates a new scheduler task body or prototype. Should be used in the form:
 123                          *  \code
 124                          *      TASK(TaskName); // Prototype
 125                          *
 126                          *      TASK(TaskName)
 127                          *      {
 128                          *           // Task body
 129                          *      }
 130                          *  \endcode
 131                          */
 132                         #define TASK(name)              void name (void)
 133
 134                         /** Defines a task list array, containing one or more task entries of the type \ref TaskEntry_t. Each task list
 135                          *  should be encased in curly braces and ended with a comma.
 136                          *
 137                          *  Usage Example:
 138                          *  \code
 139                          *      TASK_LIST
 140                          *      {
 141                          *           { .Task = MyTask1, .TaskStatus = TASK_RUN, .GroupID = 1 },
 142                          *           // More task entries here
 143                          *      }
 144                          *  \endcode
 145                          */
 146                         #define TASK_LIST               TaskEntry_t Scheduler_TaskList[] =
 147
 148                         /** Constant, giving the maximum delay in scheduler ticks which can be stored in a variable of type
 149                          *  \ref SchedulerDelayCounter_t.
 150                          */
 151                         #define TASK_MAX_DELAY          (MAX_DELAYCTR_COUNT - 1)
 152
 153                         /** Task status mode constant, for passing to \ref Scheduler_SetTaskMode() or \ref Scheduler_SetGroupTaskMode(). */
 154                         #define TASK_RUN                true
 155
 156                         /** Task status mode constant, for passing to \ref Scheduler_SetTaskMode() or \ref Scheduler_SetGroupTaskMode(). */
 157                         #define TASK_STOP               false
 158
 159                 /* Pseudo-Function Macros: */
 160                         #if defined(__DOXYGEN__)
 161                                 /** Starts the scheduler in its infinite loop, executing running tasks. This should be placed at the end
 162                                  *  of the user application's \c main() function, as it can never return to the calling function.
 163                                  */
 164                                 void Scheduler_Start(void);
 165
 166                                 /** Initialises the scheduler so that the scheduler functions can be called before the scheduler itself
 167                                  *  is started. This must be executed before any scheduler function calls other than \ref Scheduler_Start(),
 168                                  *  and can be omitted if no such functions could be called before the scheduler is started.
 169                                  */
 170                                 void Scheduler_Init(void);
 171                         #else
 172                                 #define Scheduler_Start()    Scheduler_GoSchedule(TOTAL_TASKS);
 173                                 #define Scheduler_Init()     Scheduler_InitScheduler(TOTAL_TASKS);
 174                         #endif
 175
 176                 /* Type Defines: */
 177                         /** Type define for a pointer to a scheduler task. */
 178                         typedef void (*TaskPtr_t)(void);
 179
 180                         /** Type define for a variable which can hold a tick delay value for the scheduler up to the maximum delay
 181                          *  possible.
 182                          */
 183                         typedef uint16_t SchedulerDelayCounter_t;
 184
 185                         /** \brief Scheduler Task List Entry Structure.
 186                          *
 187                          *  Structure for holding a single task's information in the scheduler task list.
 188                          */
 189                         typedef struct
 190                         {
 191                                 TaskPtr_t Task;       /**< Pointer to the task to execute. */
 192                                 bool      TaskStatus; /**< Status of the task (either TASK_RUN or TASK_STOP). */
 193                                 uint8_t   GroupID;    /**< Group ID of the task so that its status can be changed as a group. */
 194                         } TaskEntry_t;
 195
 196                 /* Global Variables: */
 197                         /** Task entry list, containing the scheduler tasks, task statuses and group IDs. Each entry is of type
 198                          *  \ref TaskEntry_t and can be manipulated as desired, although it is preferred that the proper Scheduler
 199                          *  functions should be used instead of direct manipulation.
 200                          */
 201                         exter TaskEntry_t Scheduler_TaskList[];
 202
 203                         /** Contains the total number of tasks in the task list, irrespective of if the task's status is set to
 204                          *  \ref TASK_RUN or \ref TASK_STOP.
 205                          *
 206                          *  \note This value should be treated as read-only, and never altered in user-code.
 207                          */
 208                         extern volatile uint8_t Scheduler_TotalTasks;
 209
 210                         /**  Contains the current scheduler tick count, for use with the delay functions. If the delay functions
 211                          *   are used in the user code, this should be incremented each tick period so that the delays can be
 212                          *   calculated.
 213                          */
 214                         extern volatile SchedulerDelayCounter_t Scheduler_TickCounter;
 215
 216                 /* Inline Functions: */
 217                         /** Resets the delay counter value to the current tick count. This should be called to reset the period
 218                          *  for a delay in a task which is dependant on the current tick value.
 219                          *
 220                          *  \param[out] DelayCounter  Counter which is storing the starting tick count for a given delay.
 221                          */
 222                         static inline void Scheduler_ResetDelay(SchedulerDelayCounter_t* const DelayCounter)
 223                                                                 ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 224                         static inline void Scheduler_ResetDelay(SchedulerDelayCounter_t* const DelayCounter)
 225                         {
 226                                 ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
 227                                 {
 228                                         *DelayCounter = Scheduler_TickCounter;
 229                                 }
 230                         }
 231
 232                 /* Function Prototypes: */
 233                         /** Determines if the given tick delay has elapsed, based on the given delay period and tick counter value.
 234                          *
 235                          *  \param[in] Delay         The delay to test for, measured in ticks.
 236                          *  \param[in] DelayCounter  The counter which is storing the starting tick value for the delay.
 237                          *
 238                          *  \return Boolean \c true if the delay has elapsed, \c false otherwise.
 239                          *
 240                          *  Usage Example:
 241                          *  \code
 242                          *      static SchedulerDelayCounter_t DelayCounter = 10000; // Force immediate run on start-up
 243                          *
 244                          *      // Task runs every 10000 ticks, 10 seconds for this demo
 245                          *      if (Scheduler_HasDelayElapsed(10000, &DelayCounter))
 246                          *      {
 247                          *           // Code to execute after delay interval elapsed here
 248                          *      }
 249                          *  \endcode
 250                          */
 251                         bool Scheduler_HasDelayElapsed(const uint16_t Delay,
 252                                                        SchedulerDelayCounter_t* const DelayCounter)
 253                                                        ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(2);
 254
 255                         /** Sets the task mode for a given task.
 256                          *
 257                          *  \param[in] Task        Name of the task whose status is to be changed.
 258                          *  \param[in] TaskStatus  New task status for the task (\ref TASK_RUN or \ref TASK_STOP).
 259                          */
 260                         void Scheduler_SetTaskMode(const TaskPtr_t Task,
 261                                                    const bool TaskStatus);
 262
 263                         /** Sets the task mode for a given task group ID, allowing for an entire group of tasks to have their
 264                          *  statuses changed at once.
 265                          *
 266                          *  \param[in] GroupID     Value of the task group ID whose status is to be changed.
 267                          *  \param[in] TaskStatus  New task status for tasks in the specified group (\ref TASK_RUN or \ref TASK_STOP).
 268                          */
 269                         void Scheduler_SetGroupTaskMode(const uint8_t GroupID,
 270                                                         const bool TaskStatus);
 271
 272         /* Private Interface - For use in library only: */
 273         #if !defined(__DOXYGEN__)
 274                 /* Macros: */
 275                         #define TOTAL_TASKS                       (sizeof(Scheduler_TaskList) / sizeof(TaskEntry_t))
 276                         #define MAX_DELAYCTR_COUNT                0xFFFF
 277
 278                 /* Inline Functions: */
 279                         static inline void Scheduler_InitScheduler(const uint8_t TotalTasks) ATTR_ALWAYS_INLINE;
 280                         static inline void Scheduler_InitScheduler(const uint8_t TotalTasks)
 281                         {
 282                                 Scheduler_TotalTasks = TotalTasks;
 283                         }
 284
 285                         static inline void Scheduler_GoSchedule(const uint8_t TotalTasks) ATTR_NO_RETURN ATTR_ALWAYS_INLINE ATTR_DEPRECATED;
 286                         static inline void Scheduler_GoSchedule(const uint8_t TotalTasks)
 287                         {
 288                                 Scheduler_InitScheduler(TotalTasks);
 289
 290                                 for (;;)
 291                                 {
 292                                         TaskEntry_t* CurrTask = &Scheduler_TaskList[0];
 293
 294                                         while (CurrTask != &Scheduler_TaskList[TotalTasks])
 295                                         {
 296                                                 if (CurrTask->TaskStatus == TASK_RUN)
 297                                                   CurrTask->Task();
 298
 299                                                 CurrTask++;
 300                                         }
 301                                 }
 302                         }
 303         #endif
 304
 305         /* Disable C linkage for C++ Compilers: */
 306                 #if defined(__cplusplus)
 307                         }
 308                 #endif
 309
 310 #endif
 311
 312 /** @} */
 313