summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2020-07-03 12:41:47 +0200
committerSebastian Huber <sebastian.huber@embedded-brains.de>2020-09-18 18:52:49 +0200
commit96ea30f0c984e5df6cf9ed52d85d38cdd676f499 (patch)
tree045b6e1a2f649344606579d4f76e0e8061277858
parent031f8124f2eba54e1e295a71f31c676e69066b77 (diff)
score: Improve Scheduler Handler documentation
-rw-r--r--cpukit/include/rtems/score/scheduler.h23
-rw-r--r--cpukit/include/rtems/score/schedulerimpl.h29
2 files changed, 38 insertions, 14 deletions
diff --git a/cpukit/include/rtems/score/scheduler.h b/cpukit/include/rtems/score/scheduler.h
index 9a6515ba1e..101ea7a5c1 100644
--- a/cpukit/include/rtems/score/scheduler.h
+++ b/cpukit/include/rtems/score/scheduler.h
@@ -30,12 +30,7 @@ extern "C" {
struct Per_CPU_Control;
/**
- * @defgroup RTEMSScoreScheduler Scheduler Handler
- *
- * @ingroup RTEMSScore
- *
- * This handler encapsulates functionality related to managing sets of threads
- * that are ready for execution.
+ * @addtogroup RTEMSScoreScheduler
*
* @{
*/
@@ -300,22 +295,24 @@ struct _Scheduler_Control {
};
/**
- * @brief Registered schedulers.
+ * @brief This table contains the configured schedulers.
*
- * Application provided via <rtems/confdefs.h>.
+ * The table is defined by <rtems/confdefs.h> through the
+ * #CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option.
*
* @see _Scheduler_Count.
*/
extern const Scheduler_Control _Scheduler_Table[];
/**
- * @brief Count of registered schedulers.
+ * @brief This constant contains the count of configured schedulers.
*
- * Application provided via <rtems/confdefs.h> on SMP configurations.
+ * In SMP configurations, the constant is defined by <rtems/confdefs.h> through
+ * the count of entries of the #CONFIGURE_SCHEDULER_TABLE_ENTRIES application
+ * configuration option.
*
- * It is very important that this is a compile-time constant on uni-processor
- * configurations (in this case RTEMS_SMP is not defined) so that the compiler
- * can optimize the some loops away
+ * In uniprocessor configurations, this is a compile time constant set to one.
+ * This is important so that the compiler can optimize some loops away.
*
* @see _Scheduler_Table.
*/
diff --git a/cpukit/include/rtems/score/schedulerimpl.h b/cpukit/include/rtems/score/schedulerimpl.h
index e7fbb8b166..aa52104aca 100644
--- a/cpukit/include/rtems/score/schedulerimpl.h
+++ b/cpukit/include/rtems/score/schedulerimpl.h
@@ -34,7 +34,34 @@ extern "C" {
#endif
/**
- * @addtogroup RTEMSScoreScheduler
+ * @defgroup RTEMSScoreScheduler Scheduler Handler
+ *
+ * @ingroup RTEMSScore
+ *
+ * @brief This handler encapsulates functionality related to managing sets of
+ * threads that are ready for execution.
+ *
+ * Schedulers are used by the system to manage sets of threads that are ready
+ * for execution. A scheduler consists of
+ *
+ * * a scheduler algorithm implementation,
+ *
+ * * a scheduler index and an associated name, and
+ *
+ * * a set of processors owned by the scheduler (may be empty, but never
+ * overlaps with a set owned by another scheduler).
+ *
+ * Each thread uses exactly one scheduler as its home scheduler. Threads may
+ * temporarily use another scheduler due to actions of locking protocols.
+ *
+ * All properties of a scheduler can be configured and controlled by the user.
+ * Some properties are fixed at link time (defined by application configuration
+ * options), other properties can be changed at runtime through directive
+ * calls.
+ *
+ * The scheduler index, name, and initial processor set are defined for a
+ * particular application by the application configuration. The schedulers are
+ * registered in the ::_Scheduler_Table which has ::_Scheduler_Count entries.
*
* @{
*/