X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/ff61dfa50589bc65bf5642feb80a0f23a237d76b..d41cd9a41aca81eaa21e65e6c53672fe604fa3d5:/LUFA/Scheduler/Scheduler.h diff --git a/LUFA/Scheduler/Scheduler.h b/LUFA/Scheduler/Scheduler.h index 71be82bee..78c84df8a 100644 --- a/LUFA/Scheduler/Scheduler.h +++ b/LUFA/Scheduler/Scheduler.h @@ -1,21 +1,21 @@ /* LUFA Library Copyright (C) Dean Camera, 2010. - + dean [at] fourwalledcubicle [dot] com - www.fourwalledcubicle.com + www.lufa-lib.org */ /* Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com) - Permission to use, copy, modify, distribute, and sell this + Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted - without fee, provided that the above copyright notice appear in + without fee, provided that the above copyright notice appear in all copies and that both that the copyright notice and this - permission notice and warranty disclaimer appear in supporting - documentation, and that the name of the author not be used in - advertising or publicity pertaining to distribution of the + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -36,14 +36,14 @@ * * \deprecated This module is deprecated and will be removed in a future library release. */ - + /** @defgroup Group_Scheduler Simple Task Scheduler - LUFA/Scheduler/Scheduler.h * * \deprecated This module is deprecated and will be removed in a future library release. * * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module: - * - LUFA/Scheduler/Scheduler.c + * - LUFA/Scheduler/Scheduler.c (Makefile source module name: LUFA_SRC_SCHEDULER) * * \section Module Description * Simple round-robbin cooperative scheduler for use in basic projects where non real-time tasks need @@ -51,45 +51,63 @@ * * For a task to yield it must return, thus each task should have persistent data marked with the static attribute. * + * Each LUFA scheduler task should be written similar to an ISR; it should execute quickly (so that no one task + * hogs the processor, preventing another from running before some sort of timeout is exceeded). Unlike normal RTOS + * tasks, each LUFA scheduler task is a regular function, and thus must be designed to be called, and designed to + * return to the calling scheduler function repeatedly. Data which must be preserved between task calls should be + * declared as global or (preferably) as a static local variable inside the task. + * + * The scheduler consists of a task list, listing all the tasks which can be executed by the scheduler. Once started, + * each task is then called one after another, unless the task is stopped by another running task or interrupt. + * * Usage Example: * \code * #include - * - * TASK(MyTask1); - * TASK(MyTask2); - * + * + * TASK(MyTask1); // Task prototype + * TASK(MyTask2); // Task prototype + * * TASK_LIST * { - * { .Task = MyTask1, .TaskStatus = TASK_RUN, .GroupID = 1 }, - * { .Task = MyTask2, .TaskStatus = TASK_RUN, .GroupID = 1 }, + * { .Task = MyTask1, .TaskStatus = TASK_RUN, .GroupID = 1 }, + * { .Task = MyTask2, .TaskStatus = TASK_RUN, .GroupID = 1 }, * } * * int main(void) * { - * Scheduler_Start(); + * Scheduler_Init(); + * + * // Other initialisation here + * + * Scheduler_Start(); * } * * TASK(MyTask1) * { - * // Implementation Here + * // Task implementation here * } * * TASK(MyTask2) * { - * // Implementation Here + * // Task implementation here * } * \endcode * + * If desired, the LUFA scheduler does not need to be used in a LUFA powered application. A more conventional + * approach to application design can be used, or a proper scheduling RTOS inserted in the place of the LUFA scheduler. + * In the case of the former the USB task must be run manually repeatedly to maintain USB communications, and in the + * case of the latter a proper RTOS task must be set up to do the same. + * * @{ */ - + #ifndef __SCHEDULER_H__ #define __SCHEDULER_H__ /* Includes: */ - #include + #include #include - + #include #include "../Common/Common.h" @@ -112,7 +130,7 @@ * \endcode */ #define TASK(name) void name (void) - + /** Defines a task list array, containing one or more task entries of the type TaskEntry_t. Each task list * should be encased in curly braces and ended with a comma. * @@ -125,46 +143,45 @@ * } * \endcode */ - #define TASK_LIST TaskEntry_t Scheduler_TaskList[] = - + #define TASK_LIST TaskEntry_t Scheduler_TaskList[] = + /** Constant, giving the maximum delay in scheduler ticks which can be stored in a variable of type - * SchedulerDelayCounter_t. + * \ref SchedulerDelayCounter_t. */ #define TASK_MAX_DELAY (MAX_DELAYCTR_COUNT - 1) - /** Task status mode constant, for passing to Scheduler_SetTaskMode() or Scheduler_SetGroupTaskMode(). */ + /** Task status mode constant, for passing to \ref Scheduler_SetTaskMode() or \ref Scheduler_SetGroupTaskMode(). */ #define TASK_RUN true - /** Task status mode constant, for passing to Scheduler_SetTaskMode() or Scheduler_SetGroupTaskMode(). */ + /** Task status mode constant, for passing to \ref Scheduler_SetTaskMode() or \ref Scheduler_SetGroupTaskMode(). */ #define TASK_STOP false - + /* Pseudo-Function Macros: */ #if defined(__DOXYGEN__) /** Starts the scheduler in its infinite loop, executing running tasks. This should be placed at the end * of the user application's main() function, as it can never return to the calling function. */ void Scheduler_Start(void); - - /** Initializes the scheduler so that the scheduler functions can be called before the scheduler itself + + /** Initialises the scheduler so that the scheduler functions can be called before the scheduler itself * is started. This must be executed before any scheduler function calls other than Scheduler_Start(), * and can be omitted if no such functions could be called before the scheduler is started. */ void Scheduler_Init(void); #else #define Scheduler_Start() Scheduler_GoSchedule(TOTAL_TASKS); - #define Scheduler_Init() Scheduler_InitScheduler(TOTAL_TASKS); #endif /* Type Defines: */ /** Type define for a pointer to a scheduler task. */ typedef void (*TaskPtr_t)(void); - + /** Type define for a variable which can hold a tick delay value for the scheduler up to the maximum delay * possible. */ typedef uint16_t SchedulerDelayCounter_t; - + /** \brief Scheduler Task List Entry Structure. * * Structure for holding a single task's information in the scheduler task list. @@ -174,7 +191,7 @@ TaskPtr_t Task; /**< Pointer to the task to execute. */ bool TaskStatus; /**< Status of the task (either TASK_RUN or TASK_STOP). */ uint8_t GroupID; /**< Group ID of the task so that its status can be changed as a group. */ - } TaskEntry_t; + } TaskEntry_t; /* Global Variables: */ /** Task entry list, containing the scheduler tasks, task statuses and group IDs. Each entry is of type @@ -182,9 +199,9 @@ * functions should be used instead of direct manipulation. */ exter TaskEntry_t Scheduler_TaskList[]; - + /** Contains the total number of tasks in the task list, irrespective of if the task's status is set to - * TASK_RUN or TASK_STOP. + * \ref TASK_RUN or \ref TASK_STOP. * * \note This value should be treated as read-only, and never altered in user-code. */ @@ -211,19 +228,19 @@ *DelayCounter = Scheduler_TickCounter; } } - + /* Function Prototypes: */ - /** Determines if the given tick delay has elapsed, based on the given . + /** Determines if the given tick delay has elapsed, based on the given delay period and tick counter value. * - * \param[in] Delay The delay to test for, measured in ticks - * \param[in] DelayCounter The counter which is storing the starting tick value for the delay + * \param[in] Delay The delay to test for, measured in ticks. + * \param[in] DelayCounter The counter which is storing the starting tick value for the delay. * - * \return Boolean true if the delay has elapsed, false otherwise + * \return Boolean true if the delay has elapsed, false otherwise. * * Usage Example: * \code * static SchedulerDelayCounter_t DelayCounter = 10000; // Force immediate run on start-up - * + * * // Task runs every 10000 ticks, 10 seconds for this demo * if (Scheduler_HasDelayElapsed(10000, &DelayCounter)) * { @@ -233,24 +250,26 @@ */ bool Scheduler_HasDelayElapsed(const uint16_t Delay, SchedulerDelayCounter_t* const DelayCounter) - ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(2); - + ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(2); + /** Sets the task mode for a given task. * - * \param[in] Task Name of the task whose status is to be changed - * \param[in] TaskStatus New task status for the task (TASK_RUN or TASK_STOP) + * \param[in] Task Name of the task whose status is to be changed. + * \param[in] TaskStatus New task status for the task (\ref TASK_RUN or \ref TASK_STOP). */ - void Scheduler_SetTaskMode(const TaskPtr_t Task, const bool TaskStatus); - + void Scheduler_SetTaskMode(const TaskPtr_t Task, + const bool TaskStatus); + /** Sets the task mode for a given task group ID, allowing for an entire group of tasks to have their * statuses changed at once. * - * \param[in] GroupID Value of the task group ID whose status is to be changed - * \param[in] TaskStatus New task status for tasks in the specified group (TASK_RUN or TASK_STOP) + * \param[in] GroupID Value of the task group ID whose status is to be changed. + * \param[in] TaskStatus New task status for tasks in the specified group (\ref TASK_RUN or \ref TASK_STOP). */ - void Scheduler_SetGroupTaskMode(const uint8_t GroupID, const bool TaskStatus); + void Scheduler_SetGroupTaskMode(const uint8_t GroupID, + const bool TaskStatus); - /* Private Interface - For use in library only: */ + /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Macros: */ #define TOTAL_TASKS (sizeof(Scheduler_TaskList) / sizeof(TaskEntry_t)) @@ -262,7 +281,7 @@ { Scheduler_TotalTasks = TotalTasks; } - + static inline void Scheduler_GoSchedule(const uint8_t TotalTasks) ATTR_NO_RETURN ATTR_ALWAYS_INLINE ATTR_DEPRECATED; static inline void Scheduler_GoSchedule(const uint8_t TotalTasks) { @@ -271,7 +290,7 @@ for (;;) { TaskEntry_t* CurrTask = &Scheduler_TaskList[0]; - + while (CurrTask != &Scheduler_TaskList[TotalTasks]) { if (CurrTask->TaskStatus == TASK_RUN) @@ -282,12 +301,13 @@ } } #endif - + /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif - + #endif /** @} */ +