[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