From 5b1ff71ab76d892ac33651b69c89b7cd14ab3dee Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 13 May 2014 15:57:43 +0200 Subject: score: Scheduler documentation --- cpukit/score/include/rtems/score/scheduler.h | 62 ++++++++-------------- cpukit/score/include/rtems/score/schedulerimpl.h | 29 +++++++--- .../score/include/rtems/score/schedulerpriority.h | 2 +- .../rtems/score/schedulerpriorityaffinitysmp.h | 2 +- .../include/rtems/score/schedulerpriorityimpl.h | 2 +- .../include/rtems/score/schedulerprioritysmp.h | 2 +- .../include/rtems/score/schedulersimpleimpl.h | 2 +- .../score/include/rtems/score/schedulersimplesmp.h | 18 +++---- 8 files changed, 57 insertions(+), 62 deletions(-) diff --git a/cpukit/score/include/rtems/score/scheduler.h b/cpukit/score/include/rtems/score/scheduler.h index 2a1c4338a6..768576fef9 100644 --- a/cpukit/score/include/rtems/score/scheduler.h +++ b/cpukit/score/include/rtems/score/scheduler.h @@ -43,72 +43,59 @@ extern "C" { typedef struct Scheduler_Control Scheduler_Control; /** - * function jump table that holds pointers to the functions that - * implement specific schedulers. + * @brief The scheduler operations. */ typedef struct { - /** Implements the scheduling decision logic (policy). */ + /** @see _Scheduler_Handler_initialization() */ void ( *initialize )( const Scheduler_Control * ); - /** Implements the scheduling decision logic (policy). */ + /** @see _Scheduler_Schedule() */ void ( *schedule )( const Scheduler_Control *, Thread_Control *); - /** - * @brief Voluntarily yields the processor per the scheduling policy. - * - * @see _Scheduler_Yield(). - */ + /** @see _Scheduler_Yield() */ void ( *yield )( const Scheduler_Control *, Thread_Control *); - /** Removes the given thread from scheduling decisions. */ + /** @see _Scheduler_Block() */ void ( *block )( const Scheduler_Control *, Thread_Control * ); - /** Adds the given thread to scheduling decisions. */ + /** @see _Scheduler_Unblock() */ void ( *unblock )( const Scheduler_Control *, Thread_Control * ); - /** allocates the scheduler field of the given thread */ + /** @see _Scheduler_Allocate() */ bool ( *allocate )( const Scheduler_Control *, Thread_Control * ); - /** frees the scheduler field of the given thread */ + /** @see _Scheduler_Free() */ void ( *free )( const Scheduler_Control *, Thread_Control * ); - /** updates the scheduler field of the given thread -- primarily used - * when changing the thread's priority. */ + /** @see _Scheduler_Update() */ void ( *update )( const Scheduler_Control *, Thread_Control * ); - /** enqueue a thread as the last of its priority group */ + /** @see _Scheduler_Enqueue() */ void ( *enqueue )( const Scheduler_Control *, Thread_Control * ); - /** enqueue a thread as the first of its priority group */ + /** @see _Scheduler_Enqueue_first() */ void ( *enqueue_first )( const Scheduler_Control *, Thread_Control * ); - /** extract a thread from the ready set */ + /** @see _Scheduler_Extract() */ void ( *extract )( const Scheduler_Control *, Thread_Control * ); - /** - * Compares two priorities (returns >0 for higher priority, 0 for equal - * and <0 for lower priority). - */ + /** @see _Scheduler_Priority_compare() */ int ( *priority_compare )( Priority_Control, Priority_Control ); - /** This routine is called upon release of a new job. */ + /** @see _Scheduler_Release_job() */ void ( *release_job ) ( const Scheduler_Control *, Thread_Control *, uint32_t ); - /** perform scheduler update actions required at each clock tick */ + /** @see _Scheduler_Tick() */ void ( *tick )( const Scheduler_Control *, Thread_Control * ); - /** - * @brief Starts the idle thread for a particular processor. - * - * @see _Scheduler_Start_idle(). - */ + /** @see _Scheduler_Start_idle() */ void ( *start_idle )( const Scheduler_Control *, Thread_Control *, @@ -116,11 +103,7 @@ typedef struct { ); #if defined(__RTEMS_HAVE_SYS_CPUSET_H__) && defined(RTEMS_SMP) - /** - * @brief Obtain the processor affinity for a thread. - * - * @see _Scheduler_Get_affinity(). - */ + /** @see _Scheduler_Get_affinity() */ bool ( *get_affinity )( const Scheduler_Control *, Thread_Control *, @@ -128,11 +111,7 @@ typedef struct { cpu_set_t * ); - /** - * @brief Set the processor affinity for a thread. - * - * @see _Scheduler_Set_affinity(). - */ + /** @see _Scheduler_Set_affinity() */ bool ( *set_affinity )( const Scheduler_Control *, Thread_Control *, @@ -365,7 +344,10 @@ void _Scheduler_default_Start_idle( ); #endif -/* +/** + * @brief Indicates if thread priority queues are broken with the configured + * scheduler or not. + * * See also PR2174: Memory corruption with EDF scheduler and thread priority * queues. */ diff --git a/cpukit/score/include/rtems/score/schedulerimpl.h b/cpukit/score/include/rtems/score/schedulerimpl.h index 74fa403a59..42e57303b8 100644 --- a/cpukit/score/include/rtems/score/schedulerimpl.h +++ b/cpukit/score/include/rtems/score/schedulerimpl.h @@ -183,9 +183,10 @@ RTEMS_INLINE_ROUTINE void _Scheduler_Update( } /** - * @brief Scheduler enqueue. + * @brief Enqueues a thread as the last of its priority group. * - * This routine enqueue @a the_thread->scheduler + * @param[in] scheduler The scheduler instance. + * @param[in] the_thread The thread to enqueue. */ RTEMS_INLINE_ROUTINE void _Scheduler_Enqueue( const Scheduler_Control *scheduler, @@ -196,9 +197,10 @@ RTEMS_INLINE_ROUTINE void _Scheduler_Enqueue( } /** - * @brief Scheduler enqueue first. + * @brief Enqueues a thread as the first of its priority group. * - * This routine enqueue_first @a the_thread->scheduler + * @param[in] scheduler The scheduler instance. + * @param[in] the_thread The thread to enqueue. */ RTEMS_INLINE_ROUTINE void _Scheduler_Enqueue_first( const Scheduler_Control *scheduler, @@ -222,9 +224,20 @@ RTEMS_INLINE_ROUTINE void _Scheduler_Extract( } /** - * @brief Scheduler priority compare. + * @brief Compares two priority values. * - * This routine compares two priorities. + * @param[in] scheduler The scheduler instance. + * @param[in] p1 The first priority value. + * @param[in] p2 The second priority value. + * + * @retval negative The value @a p1 encodes a lower priority than @a p2 in the + * intuitive sense of priority. + * @retval 0 The priorities @a p1 and @a p2 are equal. + * @retval positive The value @a p1 encodes a higher priority than @a p2 in the + * intuitive sense of priority. + * + * @see _Scheduler_Is_priority_lower_than() and + * _Scheduler_Is_priority_higher_than(). */ RTEMS_INLINE_ROUTINE int _Scheduler_Priority_compare( const Scheduler_Control *scheduler, @@ -492,7 +505,7 @@ RTEMS_INLINE_ROUTINE void _Scheduler_Generic_block( } /** - * @brief Returns true if @p1 encodes a lower priority than @a p2 in the + * @brief Returns true if @a p1 encodes a lower priority than @a p2 in the * intuitive sense of priority. */ RTEMS_INLINE_ROUTINE bool _Scheduler_Is_priority_lower_than( @@ -505,7 +518,7 @@ RTEMS_INLINE_ROUTINE bool _Scheduler_Is_priority_lower_than( } /** - * @brief Returns true if @p1 encodes a higher priority than @a p2 in the + * @brief Returns true if @a p1 encodes a higher priority than @a p2 in the * intuitive sense of priority. */ RTEMS_INLINE_ROUTINE bool _Scheduler_Is_priority_higher_than( diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h index b46c0fa29a..4393b7ddb5 100644 --- a/cpukit/score/include/rtems/score/schedulerpriority.h +++ b/cpukit/score/include/rtems/score/schedulerpriority.h @@ -28,7 +28,7 @@ extern "C" { #endif /** - * @defgroup ScoreSchedulerDPS Deterministic Priority-based Scheduler + * @defgroup ScoreSchedulerDPS Deterministic Priority Scheduler * * @ingroup ScoreScheduler */ diff --git a/cpukit/score/include/rtems/score/schedulerpriorityaffinitysmp.h b/cpukit/score/include/rtems/score/schedulerpriorityaffinitysmp.h index 4f31722eb1..c327fccb6e 100644 --- a/cpukit/score/include/rtems/score/schedulerpriorityaffinitysmp.h +++ b/cpukit/score/include/rtems/score/schedulerpriorityaffinitysmp.h @@ -31,7 +31,7 @@ extern "C" { /** * @defgroup ScoreSchedulerPriorityAffinitySMP Deterministic Priority Affinity SMP Scheduler * - * @ingroup ScoreScheduler + * @ingroup ScoreSchedulerPrioritySMP * * This is an extension of the Deterministic Priority SMP Scheduler. which * is an implementation of the global fixed priority scheduler (G-FP). diff --git a/cpukit/score/include/rtems/score/schedulerpriorityimpl.h b/cpukit/score/include/rtems/score/schedulerpriorityimpl.h index bdd7e6fc5f..fde06872ca 100644 --- a/cpukit/score/include/rtems/score/schedulerpriorityimpl.h +++ b/cpukit/score/include/rtems/score/schedulerpriorityimpl.h @@ -31,7 +31,7 @@ extern "C" { #endif /** - * @addtogroup ScoreScheduler + * @addtogroup ScoreSchedulerDPS */ /**@{**/ diff --git a/cpukit/score/include/rtems/score/schedulerprioritysmp.h b/cpukit/score/include/rtems/score/schedulerprioritysmp.h index 8506623c8f..66de9645bd 100644 --- a/cpukit/score/include/rtems/score/schedulerprioritysmp.h +++ b/cpukit/score/include/rtems/score/schedulerprioritysmp.h @@ -34,7 +34,7 @@ extern "C" { /** * @defgroup ScoreSchedulerPrioritySMP Deterministic Priority SMP Scheduler * - * @ingroup ScoreScheduler + * @ingroup ScoreSchedulerSMP * * This is an implementation of the global fixed priority scheduler (G-FP). It * uses one ready chain per priority to ensure constant time insert operations. diff --git a/cpukit/score/include/rtems/score/schedulersimpleimpl.h b/cpukit/score/include/rtems/score/schedulersimpleimpl.h index f436134fc4..cc79c15376 100644 --- a/cpukit/score/include/rtems/score/schedulersimpleimpl.h +++ b/cpukit/score/include/rtems/score/schedulersimpleimpl.h @@ -28,7 +28,7 @@ extern "C" { #endif /** - * @addtogroup ScoreScheduler + * @addtogroup ScoreSchedulerSimple */ /**@{**/ diff --git a/cpukit/score/include/rtems/score/schedulersimplesmp.h b/cpukit/score/include/rtems/score/schedulersimplesmp.h index dcdc6819a5..880115faaf 100644 --- a/cpukit/score/include/rtems/score/schedulersimplesmp.h +++ b/cpukit/score/include/rtems/score/schedulersimplesmp.h @@ -3,7 +3,7 @@ * * @brief Simple SMP Scheduler API * - * @ingroup ScoreSchedulerSMP + * @ingroup ScoreSchedulerSMPSimple */ /* @@ -28,16 +28,16 @@ extern "C" { #include /** - * @defgroup ScoreSchedulerSMP Simple SMP Scheduler + * @defgroup ScoreSchedulerSMPSimple Simple Priority SMP Scheduler * - * @ingroup ScoreScheduler + * @ingroup ScoreSchedulerSMP * - * The Simple SMP Scheduler allocates a processor for the processor count - * highest priority ready threads. The thread priority and position in the - * ready chain are the only information to determine the scheduling decision. - * Threads with an allocated processor are in the scheduled chain. After - * initialization the scheduled chain has exactly processor count nodes. Each - * processor has exactly one allocated thread after initialization. All + * The Simple Priority SMP Scheduler allocates a processor for the processor + * count highest priority ready threads. The thread priority and position in + * the ready chain are the only information to determine the scheduling + * decision. Threads with an allocated processor are in the scheduled chain. + * After initialization the scheduled chain has exactly processor count nodes. + * Each processor has exactly one allocated thread after initialization. All * enqueue and extract operations may exchange threads with the scheduled * chain. One thread will be added and another will be removed. The scheduled * and ready chain is ordered according to the thread priority order. The -- cgit v1.2.3