c-user: Clarify scheduler configuration

c-user/configuring_a_system.rst

@@ -1452,7 +1452,7 @@ DEFAULT VALUE:
 
 DESCRIPTION:
     ``CONFIGURE_MAXIMUM_PROCESSORS`` must be set to the maximum number of
-    processors an applicaiton intends to use.  The number of acually available
+    processors an application intends to use.  The number of actually available
     processors depends on the hardware and may be less.  It is recommended to
     use the smallest value suitable for the application in order to save
     memory.  Each processor needs an idle thread and interrupt stack for
@@ -3285,7 +3285,17 @@ General Scheduler Configuration
 ===============================
 
 This section defines the configuration parameters related to selecting a
-scheduling algorithm for an application.  For the :ref:`schedulers built into
+scheduling algorithm for an application.  A scheduler configuration is optional
+and only necessary in very specific circumstances.  A normal application
+configuration does not need any of the configuration options described in this
+section.  By default, the :ref:`Deterministic Priority Scheduler
+<SchedulerPriority>` algorithm is used in uniprocessor configurations.  In case
+SMP is enabled and the configured maximum processors
+(:ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>`) is greater
+than one, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler
+<SchedulerSMPEDF>` is selected as the default scheduler algorithm.
+
+For the :ref:`schedulers built into
 RTEMS <SchedulingConcepts>`, the configuration is straightforward.  All that is
 required is to define the configuration macro which specifies which scheduler
 you want for in your application.
@@ -3318,6 +3328,9 @@ DESCRIPTION:
     <SchedulerCBS>` algorithm is made available to the application.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     In case no explicit :ref:`clustered scheduler configuration
     <ConfigurationSchedulersClustered>` is present, then it is used as the
     scheduler for exactly one processor.
@@ -3346,6 +3359,9 @@ DESCRIPTION:
     <SchedulerEDF>` algorithm is made available to the application.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     In case no explicit :ref:`clustered scheduler configuration
     <ConfigurationSchedulersClustered>` is present, then it is used as the
     scheduler for exactly one processor.
@@ -3374,6 +3390,9 @@ DESCRIPTION:
     <SchedulerSMPEDF>` algorithm is made available to the application.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     This scheduler algorithm is only available when RTEMS is built with SMP
     support enabled.
 
@@ -3381,9 +3400,9 @@ NOTES:
     <ConfigurationSchedulersClustered>` is present, then it is used as the
     scheduler for up to 32 processors.
 
-    This scheduler algorithm is the default in SMP configurations and is only
+    This scheduler algorithm is the default in SMP configurations if
-    selected when :ref:`CONFIGURE_MAXIMUM_PROCESSORS
+    :ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>` is
-    <CONFIGURE_MAXIMUM_PROCESSORS>` is greater than one.
+    greater than one.
 
 .. index:: CONFIGURE_SCHEDULER_NAME
 
@@ -3418,7 +3437,8 @@ DESCRIPTION:
     the scheduler is determined by the configuration.
 
 NOTES:
-    None.
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
 
 .. index:: CONFIGURE_SCHEDULER_PRIORITY
 
@@ -3445,6 +3465,9 @@ DESCRIPTION:
     <SchedulerPriority>` algorithm is made available to the application.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     In case no explicit :ref:`clustered scheduler configuration
     <ConfigurationSchedulersClustered>` is present, then it is used as the
     scheduler for exactly one processor.
@@ -3478,6 +3501,9 @@ DESCRIPTION:
     application.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     This scheduler algorithm is only available when RTEMS is built with SMP
     support enabled.
 
@@ -3509,6 +3535,9 @@ DESCRIPTION:
     <SchedulerSMPPriority>` algorithm is made available to the application.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     This scheduler algorithm is only available when RTEMS is built with SMP
     support enabled.
 
@@ -3540,6 +3569,9 @@ DESCRIPTION:
     <SchedulerPrioritySimple>` algorithm is made available to the application.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     In case no explicit :ref:`clustered scheduler configuration
     <ConfigurationSchedulersClustered>` is present, then it is used as the
     scheduler for exactly one processor.
@@ -3569,6 +3601,9 @@ DESCRIPTION:
     application.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     This scheduler algorithm is only available when RTEMS is built with SMP
     support enabled.
 
@@ -3612,6 +3647,9 @@ DESCRIPTION:
       the per-thread information of the user scheduler.
 
 NOTES:
+    This scheduler configuration option is an advanced configuration option.
+    Think twice before you use it.
+
     At this time, the mechanics and requirements for writing a new scheduler
     are evolving and not fully documented.  It is recommended that you look at
     the existing Deterministic Priority Scheduler in
@@ -3624,6 +3662,9 @@ NOTES:
 Clustered Scheduler Configuration
 =================================
 
+A clustered scheduler configuration is optional.  It is an advanced
+configuration area and only necessary in specific circumstances.
+
 Clustered scheduling helps to control the worst-case latencies in a
 multiprocessor system (SMP).  The goal is to reduce the amount of shared state
 in the system and thus prevention of lock contention.  Modern multiprocessor
@@ -3636,9 +3677,7 @@ partitioned into non-empty pairwise-disjoint subsets.  These subsets are called
 clusters.  Clusters with a cardinality of one are partitions.  Each cluster is
 owned by exactly one scheduler.
 
-A clustered scheduler configuration is optional.  By default, up to 32
+In order to use clustered scheduling the application designer has to answer two
-processors are managed by the :ref:`EDF SMP Scheduler <SchedulerSMPEDF>`.  In
-order to use clustered scheduling the application designer has to answer two
 questions.
 
 #. How is the set of processors partitioned into clusters?

c-user/scheduling_concepts.rst

@@ -239,20 +239,27 @@ allowed to run.
 Earliest Deadline First SMP Scheduler
 -------------------------------------
 
-A job-level fixed-priority scheduler using the Earliest Deadline First (EDF)
+This is a job-level fixed-priority scheduler using the Earliest Deadline First
-method.  By convention, the maximum priority level is
+(EDF) method.  By convention, the maximum priority level is
-:math:`min(INT\_MAX, 2^{62} - 1)` for background tasks.  The tasks with an
+:math:`min(INT\_MAX, 2^{62} - 1)` for background tasks.  Tasks without an
-active deadline have a higher priority than the background tasks.  This
+active deadline are background tasks.  In case deadlines are not used, then the
-scheduler supports task processor affinities of one-to-one and one-to-all, e.g.
+EDF scheduler behaves exactly like a fixed-priority scheduler.  The tasks with
-a task can execute on exactly one processor or all processors managed by the
+an active deadline have a higher priority than the background tasks.  This
-scheduler instance.  This is the default scheduler in SMP configurations if
+scheduler supports :ref:`task processor affinities <rtems_task_set_affinity>`
-more than one processor is configured.  The processor affinity set of a task
+of one-to-one and one-to-all, e.g.  a task can execute on exactly one processor
-must contain all online processors to select the one-to-all affinity.  This is
+or all processors managed by the scheduler instance.  The processor affinity
-to avoid pathological cases if processors are added/removed to/from the
+set of a task must contain all online processors to select the one-to-all
-scheduler instance at run-time.  In case the processor affinity set contains
+affinity.  This is to avoid pathological cases if processors are added/removed
-not all online processors, then a one-to-one affinity will be used selecting
+to/from the scheduler instance at run-time.  In case the processor affinity set
-the processor with the largest index within the set of processors currently
+contains not all online processors, then a one-to-one affinity will be used
-owned by the scheduler instance.
+selecting the processor with the largest index within the set of processors
+currently owned by the scheduler instance.  This scheduler algorithm supports
+:ref:`thread pinning <ThreadPinning>`.  The ready queues use a red-black tree
+with the task priority as the key.
+
+This scheduler algorithm is the default scheduler in SMP configurations if more
+than one processor is configured (:ref:`CONFIGURE_MAXIMUM_PROCESSORS
+<CONFIGURE_MAXIMUM_PROCESSORS>`).
 
 .. _SchedulerSMPPriority:
 

c-user/symmetric_multiprocessing_services.rst

@@ -810,6 +810,8 @@ RTEMS provides two means for per-processor data:
    This API is not intended for general application use.  Please ask on the
    development mailing list in case you want to use it.
 
+.. _ThreadPinning:
+
 Thread Pinning
 --------------