LUFA/Scheduler/Scheduler.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2009.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6       www.fourwalledcubicle.com
   7 */
   8
   9 /*
  10   Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, and distribute this software
  13   and its documentation for any purpose and without fee is hereby
  14   granted, provided that the above copyright notice appear in all
  15   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  *
  33  *  Simple round-robbin cooperative scheduler for use in basic projects where non real-time tasks need
  34  *  to be executed. Each task is executed in sequence, and can be enabled or disabled individually or as a group.
  35  *
  36  *  For a task to yield it must return, thus each task should have persistent data marked with the static attribute.
  37  *
  38  *  Usage Example:
  39  *  \code
  40  *      #include <LUFA/Scheduler/Scheduler.h>
  41  *
  42  *      TASK(MyTask1);
  43  *      TASK(MyTask2);
  44  *
  45  *      TASK_LIST
  46  *      {
  47  *              { Task: MyTask1, TaskStatus: TASK_RUN, GroupID: 1  },
  48  *              { Task: MyTask2, TaskStatus: TASK_RUN, GroupID: 1  },
  49  *      }
  50  *
  51  *      int main(void)
  52  *      {
  53  *              Scheduler_Start();
  54  *      }
  55  *
  56  *      TASK(MyTask1)
  57  *      {
  58  *              // Implementation Here
  59  *      }
  60  *
  61  *      TASK(MyTask2)
  62  *      {
  63  *              // Implementation Here
  64  *      }
  65  *  \endcode
  66  */
  67
  68 /** @defgroup Group_Scheduler Simple Task Scheduler - LUFA/Scheduler/Scheduler.h
  69  *
  70  *  Simple round-robbin task scheduler. See Scheduler.h description for more details.
  71  *
  72  *  @{
  73  */
  74
  75 #ifndef __SCHEDULER_H__
  76 #define __SCHEDULER_H__
  77
  78         /* Includes: */
  79                 #include <avr/io.h>
  80                 #include <stdbool.h>
  81
  82                 #include <util/atomic.h>
  83
  84                 #include "../Common/Common.h"
  85
  86         /* Enable C linkage for C++ Compilers: */
  87                 #if defined(__cplusplus)
  88                         extern "C" {
  89                 #endif
  90
  91         /* Public Interface - May be used in end-application: */
  92                 /* Macros: */
  93                         /** Creates a new scheduler task body or prototype. Should be used in the form:
  94                          *  \code
  95                          *      TASK(TaskName); // Prototype
  96                          *
  97                          *      TASK(TaskName)
  98                          *      {
  99                          *           // Task body
 100                          *      }
 101                          *  \endcode
 102                          */
 103                         #define TASK(name)                        void name (void)
 104
 105                         /** Defines a task list array, containing one or more task entries of the type TaskEntry_t. Each task list
 106                          *  should be encased in curly braces and ended with a comma.
 107                          *
 108                          *  Usage Example:
 109                          *  \code
 110                          *      TASK_LIST
 111                          *      {
 112                          *           { Task: MyTask1, TaskStatus: TASK_RUN, GroupID: 1 },
 113                          *           // More task entries here
 114                          *      }
 115                          *  \endcode
 116                          */
 117                         #define TASK_LIST                         TaskEntry_t Scheduler_TaskList[] =
 118
 119                         /** Constant, giving the maximum delay in scheduler ticks which can be stored in a variable of type
 120                          *  SchedulerDelayCounter_t.
 121                          */
 122                         #define TASK_MAX_DELAY                    (MAX_DELAYCTR_COUNT - 1)
 123
 124                         /** Task status mode constant, for passing to Scheduler_SetTaskMode() or Scheduler_SetGroupTaskMode(). */
 125                         #define TASK_RUN                          true
 126
 127                         /** Task status mode constant, for passing to Scheduler_SetTaskMode() or Scheduler_SetGroupTaskMode(). */
 128                         #define TASK_STOP                         false
 129
 130                 /* Psuedo-Functions: */
 131                         #if defined(__DOXYGEN__)
 132                                 /** Starts the scheduler in its infinite loop, executing running tasks. This should be placed at the end
 133                                  *  of the user application's main() function, as it can never return to the calling function.
 134                                  */
 135                                 void Scheduler_Start(void);
 136
 137                                 /** Initializes the scheduler so that the scheduler functions can be called before the scheduler itself
 138                                  *  is started. This must be executed before any scheduler function calls other than Scheduler_Start(),
 139                                  *  and can be omitted if no such functions could be called before the scheduler is started.
 140                                  */
 141                                 void Scheduler_Init(void);
 142                         #else
 143                                 #define Scheduler_Start()                 Scheduler_GoSchedule(TOTAL_TASKS);
 144
 145                                 #define Scheduler_Init()                  Scheduler_InitScheduler(TOTAL_TASKS);
 146                         #endif
 147
 148                 /* Type Defines: */
 149                         /** Type define for a pointer to a scheduler task. */
 150                         typedef void (*TaskPtr_t)(void);
 151
 152                         /** Type define for a variable which can hold a tick delay value for the scheduler up to the maximum delay
 153                          *  possible.
 154                          */
 155                         typedef uint16_t SchedulerDelayCounter_t;
 156
 157                         /** Structure for holding a single task's information in the scheduler task list. */
 158                         typedef struct
 159                         {
 160                                 TaskPtr_t Task;       /**< Pointer to the task to execute. */
 161                                 bool      TaskStatus; /**< Status of the task (either TASK_RUN or TASK_STOP). */
 162                                 uint8_t   GroupID;    /**< Group ID of the task so that its status can be changed as a group. */
 163                         } TaskEntry_t;
 164
 165                 /* Global Variables: */
 166                         /** Task entry list, containing the scheduler tasks, task statuses and group IDs. Each entry is of type
 167                          *  TaskEntry_t and can be manipulated as desired, although it is preferential that the proper Scheduler
 168                          *  functions should be used instead of direct manipulation.
 169                          */
 170                         extern          TaskEntry_t               Scheduler_TaskList[];
 171
 172                         /** Contains the total number of tasks in the task list, irrespective of if the task's status is set to
 173                          *  TASK_RUN or TASK_STOP.
 174                          *
 175                          *  \note This value should be treated as read-only, and never altered in user-code.
 176                          */
 177                         extern volatile uint8_t                   Scheduler_TotalTasks;
 178
 179                         /**  Contains the current scheduler tick count, for use with the delay functions. If the delay functions
 180                          *   are used in the user code, this should be incremented each tick period so that the delays can be
 181                          *   calculated.
 182                          */
 183                         extern volatile SchedulerDelayCounter_t   Scheduler_TickCounter;
 184
 185                 /* Inline Functions: */
 186                         /** Resets the delay counter value to the current tick count. This should be called to reset the period
 187                          *  for a delay in a task which is dependant on the current tick value.
 188                          *
 189                          *  \param DelayCounter  Counter which is storing the starting tick count for a given delay.
 190                          */
 191                         static inline void Scheduler_ResetDelay(SchedulerDelayCounter_t* const DelayCounter)
 192                                                                 ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;
 193                         static inline void Scheduler_ResetDelay(SchedulerDelayCounter_t* const DelayCounter)
 194                         {
 195                                 ATOMIC_BLOCK(ATOMIC_RESTORESTATE)
 196                                 {
 197                                         *DelayCounter = Scheduler_TickCounter;
 198                                 }
 199                         }
 200
 201                 /* Function Prototypes: */
 202                         /** Determines if the given tick delay has elapsed, based on the given .
 203                          *
 204                          *  \param Delay         The delay to test for, measured in ticks
 205                          *  \param DelayCounter  The counter which is storing the starting tick value for the delay
 206                          *
 207                          *  \return Boolean true if the delay has elapsed, false otherwise
 208                          *
 209                          *  Usage Example:
 210                          *  \code
 211                          *      static SchedulerDelayCounter_t DelayCounter = 10000; // Force immediate run on start-up
 212                          *
 213                          *      // Task runs every 10000 ticks, 10 seconds for this demo
 214                          *      if (Scheduler_HasDelayElapsed(10000, &DelayCounter))
 215                          *      {
 216                          *           // Code to execute after delay interval elapsed here
 217                          *      }
 218                          *  \endcode
 219                          */
 220                         bool Scheduler_HasDelayElapsed(const uint16_t Delay,
 221                                                        SchedulerDelayCounter_t* const DelayCounter)
 222                                                                                    ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(2);
 223
 224                         /** Sets the task mode for a given task.
 225                          *
 226                          *  \param Task        Name of the task whose status is to be changed
 227                          *  \param TaskStatus  New task status for the task (TASK_RUN or TASK_STOP)
 228                          */
 229                         void Scheduler_SetTaskMode(const TaskPtr_t Task, const bool TaskStatus);
 230
 231                         /** Sets the task mode for a given task group ID, allowing for an entire group of tasks to have their
 232                          *  statuses changed at once.
 233                          *
 234                          *  \param GroupID     Value of the task group ID whose status is to be changed
 235                          *  \param TaskStatus  New task status for tasks in the specified group (TASK_RUN or TASK_STOP)
 236                          */
 237                         void Scheduler_SetGroupTaskMode(const uint8_t GroupID, const bool TaskStatus);
 238
 239         /* Private Interface - For use in library only: */
 240         #if !defined(__DOXYGEN__)
 241                 /* Macros: */
 242                         #define TOTAL_TASKS                       (sizeof(Scheduler_TaskList) / sizeof(TaskEntry_t))
 243                         #define MAX_DELAYCTR_COUNT                0xFFFF
 244
 245                 /* Inline Functions: */
 246                         static inline void Scheduler_InitScheduler(const uint8_t TotalTasks) ATTR_ALWAYS_INLINE;
 247                         static inline void Scheduler_InitScheduler(const uint8_t TotalTasks)
 248                         {
 249                                 Scheduler_TotalTasks = TotalTasks;
 250                         }
 251
 252                         static inline void Scheduler_GoSchedule(const uint8_t TotalTasks) ATTR_NO_RETURN ATTR_ALWAYS_INLINE;
 253                         static inline void Scheduler_GoSchedule(const uint8_t TotalTasks)
 254                         {
 255                                 Scheduler_InitScheduler(TotalTasks);
 256
 257                                 for (;;)
 258                                 {
 259                                         TaskEntry_t* CurrTask = &Scheduler_TaskList[0];
 260
 261                                         while (CurrTask != &Scheduler_TaskList[TotalTasks])
 262                                         {
 263                                                 if (CurrTask->TaskStatus == TASK_RUN)
 264                                                   CurrTask->Task();
 265
 266                                                 CurrTask++;
 267                                         }
 268                                 }
 269                         }
 270         #endif
 271
 272         /* Disable C linkage for C++ Compilers: */
 273                 #if defined(__cplusplus)
 274                         }
 275                 #endif
 276
 277 #endif
 278
 279 /** @} */