[PATCH 1/5] score: Scheduler documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue May 13 14:18:29 UTC 2014
---
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 2a1c433..768576f 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 74fa403..42e5730 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 b46c0fa..4393b7d 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 4f31722..c327fcc 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 bdd7e6f..fde0687 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 8506623..66de964 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 f436134..cc79c15 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 dcdc681..880115f 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
--
1.7.7
More information about the devel
mailing list