score: Scheduler documentation

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 <rtems/score/schedulersmp.h>
 
 /**
- * @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