[rtems-docs commit] c-user: Move "Clustered Scheduler Configuration"

Sebastian Huber sebh at rtems.org
Thu Mar 12 09:32:37 UTC 2020


Module:    rtems-docs
Branch:    master
Commit:    020d2e7e85baeca0d8b6d73536f1d30376e34a12
Changeset: http://git.rtems.org/rtems-docs/commit/?id=020d2e7e85baeca0d8b6d73536f1d30376e34a12

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Mon Mar  9 08:55:20 2020 +0100

c-user: Move "Clustered Scheduler Configuration"

Update #3836.

---

 c-user/config/index.rst               | 217 +--------------------------------
 c-user/config/scheduler-clustered.rst | 219 ++++++++++++++++++++++++++++++++++
 2 files changed, 220 insertions(+), 216 deletions(-)

diff --git a/c-user/config/index.rst b/c-user/config/index.rst
index 1afc3ed..f8cbf78 100644
--- a/c-user/config/index.rst
+++ b/c-user/config/index.rst
@@ -23,222 +23,7 @@ Configuring a System
     bsp-related
     idle-task
     scheduler-general
-
-.. _ConfigurationSchedulersClustered:
-
-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
-systems tend to have several layers of data and instruction caches.  With
-clustered scheduling it is possible to honour the cache topology of a system
-and thus avoid expensive cache synchronization traffic.
-
-We have clustered scheduling in case the set of processors of a system is
-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.
-
-In order to use clustered scheduling the application designer has to answer two
-questions.
-
-#. How is the set of processors partitioned into clusters?
-
-#. Which scheduler algorithm is used for which cluster?
-
-The schedulers are statically configured.
-
-Configuration Step 1 - Scheduler Algorithms
--------------------------------------------
-
-Firstly, the application must select which scheduling algorithms are available
-with the following defines
-
-- :ref:`CONFIGURE_SCHEDULER_EDF_SMP <CONFIGURE_SCHEDULER_EDF_SMP>`,
-
-- :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP <CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP>`,
-
-- :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP <CONFIGURE_SCHEDULER_PRIORITY_SMP>`, and
-
-- :ref:`CONFIGURE_SCHEDULER_SIMPLE_SMP <CONFIGURE_SCHEDULER_SIMPLE_SMP>`.
-
-This is necessary to calculate the per-thread overhead introduced by the
-scheduler algorithms.  After these definitions the configuration file must
-``#include <rtems/scheduler.h>`` to have access to scheduler-specific
-configuration macros.
-
-It is possible to make more than one scheduler algorithm available to the
-application.  For example a :ref:`Simple Priority SMP Scheduler
-<SchedulerSMPPrioritySimple>` could be used in a partition for low latency
-tasks in addition to an :ref:`EDF SMP Scheduler <SchedulerSMPEDF>` for a
-general-purpose cluster.  Since the per-thread overhead depends on the
-scheduler algorithm only the scheduler algorithms used by the application
-should be configured.
-
-Configuration Step 2 - Schedulers
----------------------------------
-
-Each scheduler needs some data structures.  Use the following macros to create
-the scheduler data structures for a particular scheduler identified in the
-configuration by ``name``.
-
-- ``RTEMS_SCHEDULER_EDF_SMP(name, max_cpu_count)``,
-
-- ``RTEMS_SCHEDULER_PRIORITY_AFFINITY_SMP(name, prio_count)``,
-
-- ``RTEMS_SCHEDULER_PRIORITY_SMP(name, prio_count)``, and
-
-- ``RTEMS_SCHEDULER_SIMPLE_SMP(name)``.
-
-The ``name`` parameter is used as part of a designator for scheduler-specific
-data structures, so the usual C/C++ designator rules apply.  This ``name`` is
-not the scheduler object name.  Additional parameters are scheduler-specific.
-
-.. _ConfigurationSchedulerTable:
-
-Configuration Step 3 - Scheduler Table
---------------------------------------
-
-The schedulers are registered in the system via the scheduler table.  To
-populate the scheduler table define ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` to a
-list of the following scheduler table entry initializers
-
-- ``RTEMS_SCHEDULER_TABLE_EDF_SMP(name, obj_name)``,
-
-- ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP(name, obj_name)``,
-
-- ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP(name, obj_name)``, and
-
-- ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP(name, obj_name)``.
-
-The ``name`` parameter must correspond to the parameter defining the scheduler
-data structures of configuration step 2.  The ``obj_name`` determines the
-scheduler object name and can be used in :ref:`rtems_scheduler_ident()
-<rtems_scheduler_ident>` to get the scheduler object identifier.  The scheduler
-index is defined by the index of the scheduler table.  It is a configuration
-error to add a scheduler multiple times to the scheduler table.
-
-Configuration Step 4 - Processor to Scheduler Assignment
---------------------------------------------------------
-
-The last step is to define which processor uses which scheduler.  For this
-purpose a scheduler assignment table must be defined.  The entry count of this
-table must be equal to the configured maximum processors
-(:ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>`).  A
-processor assignment to a scheduler can be optional or mandatory.  The boot
-processor must have a scheduler assigned.  In case the system needs more
-mandatory processors than available then a fatal run-time error will occur.  To
-specify the scheduler assignments define
-``CONFIGURE_SCHEDULER_ASSIGNMENTS`` to a list of
-
-- ``RTEMS_SCHEDULER_ASSIGN(scheduler_index, attr)`` and
-
-- ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER``
-
-macros.  The ``scheduler_index`` parameter must be a valid index into the
-scheduler table defined by configuration step 3.  The ``attr`` parameter
-defines the scheduler assignment attributes.  By default, a scheduler
-assignment to a processor is optional.  For the scheduler assignment attribute
-use one of the mutually exclusive variants
-
-- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``,
-
-- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and
-
-- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``.
-
-It is possible to add/remove processors to/from schedulers at run-time, see
-:ref:`rtems_scheduler_add_processor() <rtems_scheduler_add_processor>` and
-:ref:`rtems_scheduler_remove_processor() <rtems_scheduler_remove_processor>`.
-
-Configuration Example
----------------------
-
-The following example shows a scheduler configuration for a hypothetical
-product using two chip variants.  One variant has four processors which is used
-for the normal product line and another provides eight processors for the
-high-performance product line.  The first processor performs hard-real time
-control of actuators and sensors.  The second processor is not used by RTEMS at
-all and runs a Linux instance to provide a graphical user interface.  The
-additional processors are used for a worker thread pool to perform data
-processing operations.
-
-The processors managed by RTEMS use two Deterministic Priority SMP schedulers
-capable of dealing with 256 priority levels.  The scheduler with index zero has
-the name ``"IO "``.  The scheduler with index one has the name ``"WORK"``.  The
-scheduler assignments of the first, third and fourth processor are mandatory,
-so the system must have at least four processors, otherwise a fatal run-time
-error will occur during system startup.  The processor assignments for the
-fifth up to the eighth processor are optional so that the same application can
-be used for the normal and high-performance product lines.  The second
-processor has no scheduler assigned and runs Linux.  A hypervisor will ensure
-that the two systems cannot interfere in an undesirable way.
-
-.. code-block:: c
-
-    #define CONFIGURE_MAXIMUM_PROCESSORS 8
-    #define CONFIGURE_MAXIMUM_PRIORITY 255
-
-    /* Configuration Step 1 - Scheduler Algorithms */
-    #define CONFIGURE_SCHEDULER_PRIORITY_SMP
-    #include <rtems/scheduler.h>
-
-    /* Configuration Step 2 - Schedulers */
-    RTEMS_SCHEDULER_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
-    RTEMS_SCHEDULER_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
-
-    /* Configuration Step 3 - Scheduler Table */
-    #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \
-      RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \
-        io, \
-         rtems_build_name('I', 'O', ' ', ' ') \
-      ), \
-      RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \
-        work, \
-        rtems_build_name('W', 'O', 'R', 'K') \
-      )
-
-    /* Configuration Step 4 - Processor to Scheduler Assignment */
-    #define CONFIGURE_SCHEDULER_ASSIGNMENTS \
-      RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
-      RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \
-      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
-      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
-      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
-      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
-      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
-      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
-
-Configuration Errors
---------------------
-
-In case one of the scheduler indices in ``CONFIGURE_SCHEDULER_ASSIGNMENTS``
-is invalid a link-time error will occur with an undefined reference to
-``RTEMS_SCHEDULER_INVALID_INDEX``.
-
-Some fatal errors may occur in case of scheduler configuration inconsistencies
-or a lack of processors on the system.  The fatal source is
-``RTEMS_FATAL_SOURCE_SMP``.
-
-- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot processor
-  must have a scheduler assigned.
-
-- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory
-  processor beyond the range of physically or virtually available processors.
-  The processor demand must be reduced for this system.
-
-- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a mandatory
-  processor failed during system initialization.  The system may not have this
-  processor at all or it could be a problem with a boot loader for example.
-  Check the ``CONFIGURE_SCHEDULER_ASSIGNMENTS`` definition.
-
-- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed
-  to start multitasking on a processor with no scheduler assigned.
+    scheduler-clustered
 
 Device Driver Configuration
 ===========================
diff --git a/c-user/config/scheduler-clustered.rst b/c-user/config/scheduler-clustered.rst
new file mode 100644
index 0000000..0ea2f67
--- /dev/null
+++ b/c-user/config/scheduler-clustered.rst
@@ -0,0 +1,219 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+.. _ConfigurationSchedulersClustered:
+
+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
+systems tend to have several layers of data and instruction caches.  With
+clustered scheduling it is possible to honour the cache topology of a system
+and thus avoid expensive cache synchronization traffic.
+
+We have clustered scheduling in case the set of processors of a system is
+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.
+
+In order to use clustered scheduling the application designer has to answer two
+questions.
+
+#. How is the set of processors partitioned into clusters?
+
+#. Which scheduler algorithm is used for which cluster?
+
+The schedulers are statically configured.
+
+Configuration Step 1 - Scheduler Algorithms
+-------------------------------------------
+
+Firstly, the application must select which scheduling algorithms are available
+with the following defines
+
+- :ref:`CONFIGURE_SCHEDULER_EDF_SMP <CONFIGURE_SCHEDULER_EDF_SMP>`,
+
+- :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP <CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP>`,
+
+- :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP <CONFIGURE_SCHEDULER_PRIORITY_SMP>`, and
+
+- :ref:`CONFIGURE_SCHEDULER_SIMPLE_SMP <CONFIGURE_SCHEDULER_SIMPLE_SMP>`.
+
+This is necessary to calculate the per-thread overhead introduced by the
+scheduler algorithms.  After these definitions the configuration file must
+``#include <rtems/scheduler.h>`` to have access to scheduler-specific
+configuration macros.
+
+It is possible to make more than one scheduler algorithm available to the
+application.  For example a :ref:`Simple Priority SMP Scheduler
+<SchedulerSMPPrioritySimple>` could be used in a partition for low latency
+tasks in addition to an :ref:`EDF SMP Scheduler <SchedulerSMPEDF>` for a
+general-purpose cluster.  Since the per-thread overhead depends on the
+scheduler algorithm only the scheduler algorithms used by the application
+should be configured.
+
+Configuration Step 2 - Schedulers
+---------------------------------
+
+Each scheduler needs some data structures.  Use the following macros to create
+the scheduler data structures for a particular scheduler identified in the
+configuration by ``name``.
+
+- ``RTEMS_SCHEDULER_EDF_SMP(name, max_cpu_count)``,
+
+- ``RTEMS_SCHEDULER_PRIORITY_AFFINITY_SMP(name, prio_count)``,
+
+- ``RTEMS_SCHEDULER_PRIORITY_SMP(name, prio_count)``, and
+
+- ``RTEMS_SCHEDULER_SIMPLE_SMP(name)``.
+
+The ``name`` parameter is used as part of a designator for scheduler-specific
+data structures, so the usual C/C++ designator rules apply.  This ``name`` is
+not the scheduler object name.  Additional parameters are scheduler-specific.
+
+.. _ConfigurationSchedulerTable:
+
+Configuration Step 3 - Scheduler Table
+--------------------------------------
+
+The schedulers are registered in the system via the scheduler table.  To
+populate the scheduler table define ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` to a
+list of the following scheduler table entry initializers
+
+- ``RTEMS_SCHEDULER_TABLE_EDF_SMP(name, obj_name)``,
+
+- ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP(name, obj_name)``,
+
+- ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP(name, obj_name)``, and
+
+- ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP(name, obj_name)``.
+
+The ``name`` parameter must correspond to the parameter defining the scheduler
+data structures of configuration step 2.  The ``obj_name`` determines the
+scheduler object name and can be used in :ref:`rtems_scheduler_ident()
+<rtems_scheduler_ident>` to get the scheduler object identifier.  The scheduler
+index is defined by the index of the scheduler table.  It is a configuration
+error to add a scheduler multiple times to the scheduler table.
+
+Configuration Step 4 - Processor to Scheduler Assignment
+--------------------------------------------------------
+
+The last step is to define which processor uses which scheduler.  For this
+purpose a scheduler assignment table must be defined.  The entry count of this
+table must be equal to the configured maximum processors
+(:ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>`).  A
+processor assignment to a scheduler can be optional or mandatory.  The boot
+processor must have a scheduler assigned.  In case the system needs more
+mandatory processors than available then a fatal run-time error will occur.  To
+specify the scheduler assignments define
+``CONFIGURE_SCHEDULER_ASSIGNMENTS`` to a list of
+
+- ``RTEMS_SCHEDULER_ASSIGN(scheduler_index, attr)`` and
+
+- ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER``
+
+macros.  The ``scheduler_index`` parameter must be a valid index into the
+scheduler table defined by configuration step 3.  The ``attr`` parameter
+defines the scheduler assignment attributes.  By default, a scheduler
+assignment to a processor is optional.  For the scheduler assignment attribute
+use one of the mutually exclusive variants
+
+- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``,
+
+- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and
+
+- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``.
+
+It is possible to add/remove processors to/from schedulers at run-time, see
+:ref:`rtems_scheduler_add_processor() <rtems_scheduler_add_processor>` and
+:ref:`rtems_scheduler_remove_processor() <rtems_scheduler_remove_processor>`.
+
+Configuration Example
+---------------------
+
+The following example shows a scheduler configuration for a hypothetical
+product using two chip variants.  One variant has four processors which is used
+for the normal product line and another provides eight processors for the
+high-performance product line.  The first processor performs hard-real time
+control of actuators and sensors.  The second processor is not used by RTEMS at
+all and runs a Linux instance to provide a graphical user interface.  The
+additional processors are used for a worker thread pool to perform data
+processing operations.
+
+The processors managed by RTEMS use two Deterministic Priority SMP schedulers
+capable of dealing with 256 priority levels.  The scheduler with index zero has
+the name ``"IO "``.  The scheduler with index one has the name ``"WORK"``.  The
+scheduler assignments of the first, third and fourth processor are mandatory,
+so the system must have at least four processors, otherwise a fatal run-time
+error will occur during system startup.  The processor assignments for the
+fifth up to the eighth processor are optional so that the same application can
+be used for the normal and high-performance product lines.  The second
+processor has no scheduler assigned and runs Linux.  A hypervisor will ensure
+that the two systems cannot interfere in an undesirable way.
+
+.. code-block:: c
+
+    #define CONFIGURE_MAXIMUM_PROCESSORS 8
+    #define CONFIGURE_MAXIMUM_PRIORITY 255
+
+    /* Configuration Step 1 - Scheduler Algorithms */
+    #define CONFIGURE_SCHEDULER_PRIORITY_SMP
+    #include <rtems/scheduler.h>
+
+    /* Configuration Step 2 - Schedulers */
+    RTEMS_SCHEDULER_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
+    RTEMS_SCHEDULER_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
+
+    /* Configuration Step 3 - Scheduler Table */
+    #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \
+      RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \
+        io, \
+         rtems_build_name('I', 'O', ' ', ' ') \
+      ), \
+      RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \
+        work, \
+        rtems_build_name('W', 'O', 'R', 'K') \
+      )
+
+    /* Configuration Step 4 - Processor to Scheduler Assignment */
+    #define CONFIGURE_SCHEDULER_ASSIGNMENTS \
+      RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
+      RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \
+      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
+      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
+      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
+      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
+      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
+      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
+
+Configuration Errors
+--------------------
+
+In case one of the scheduler indices in ``CONFIGURE_SCHEDULER_ASSIGNMENTS``
+is invalid a link-time error will occur with an undefined reference to
+``RTEMS_SCHEDULER_INVALID_INDEX``.
+
+Some fatal errors may occur in case of scheduler configuration inconsistencies
+or a lack of processors on the system.  The fatal source is
+``RTEMS_FATAL_SOURCE_SMP``.
+
+- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot processor
+  must have a scheduler assigned.
+
+- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory
+  processor beyond the range of physically or virtually available processors.
+  The processor demand must be reduced for this system.
+
+- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a mandatory
+  processor failed during system initialization.  The system may not have this
+  processor at all or it could be a problem with a boot loader for example.
+  Check the ``CONFIGURE_SCHEDULER_ASSIGNMENTS`` definition.
+
+- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed
+  to start multitasking on a processor with no scheduler assigned.



More information about the vc mailing list