From 020d2e7e85baeca0d8b6d73536f1d30376e34a12 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 9 Mar 2020 08:55:20 +0100 Subject: 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(-) create mode 100644 c-user/config/scheduler-clustered.rst (limited to 'c-user') 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 `, - -- :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP `, - -- :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP `, and - -- :ref:`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 `` 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 -` could be used in a partition for low latency -tasks in addition to an :ref:`EDF SMP Scheduler ` 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() -` 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 `). 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() ` and -:ref:`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 - - /* 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 `, + +- :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP `, + +- :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP `, and + +- :ref:`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 `` 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 +` could be used in a partition for low latency +tasks in addition to an :ref:`EDF SMP Scheduler ` 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() +` 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 `). 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() ` and +:ref:`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 + + /* 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. -- cgit v1.2.3