source: rtems-docs/c-user/config/scheduler-clustered.rst @ 79fb6fd

5
Last change on this file since 79fb6fd was 79fb6fd, checked in by Sebastian Huber <sebastian.huber@…>, on 03/17/20 at 08:10:15

c-user: Canonicalize configuration option groups

Update #3836.

  • Property mode set to 100644
File size: 9.6 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
4
5.. _ConfigurationSchedulersClustered:
6
7Clustered Scheduler Configuration
8=================================
9
10This section describes configuration options related to clustered scheduling.
11A clustered scheduler configuration is optional.  It is an advanced
12configuration area and only necessary in specific circumstances.
13
14Clustered scheduling helps to control the worst-case latencies in a
15multiprocessor system (SMP).  The goal is to reduce the amount of shared state
16in the system and thus prevention of lock contention.  Modern multiprocessor
17systems tend to have several layers of data and instruction caches.  With
18clustered scheduling it is possible to honour the cache topology of a system
19and thus avoid expensive cache synchronization traffic.
20
21We have clustered scheduling in case the set of processors of a system is
22partitioned into non-empty pairwise-disjoint subsets.  These subsets are called
23clusters.  Clusters with a cardinality of one are partitions.  Each cluster is
24owned by exactly one scheduler.
25
26In order to use clustered scheduling the application designer has to answer two
27questions.
28
29#. How is the set of processors partitioned into clusters?
30
31#. Which scheduler algorithm is used for which cluster?
32
33The schedulers are statically configured.
34
35Configuration Step 1 - Scheduler Algorithms
36-------------------------------------------
37
38Firstly, the application must select which scheduling algorithms are available
39with the following defines
40
41- :ref:`CONFIGURE_SCHEDULER_EDF_SMP <CONFIGURE_SCHEDULER_EDF_SMP>`,
42
43- :ref:`CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP <CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP>`,
44
45- :ref:`CONFIGURE_SCHEDULER_PRIORITY_SMP <CONFIGURE_SCHEDULER_PRIORITY_SMP>`, and
46
47- :ref:`CONFIGURE_SCHEDULER_SIMPLE_SMP <CONFIGURE_SCHEDULER_SIMPLE_SMP>`.
48
49This is necessary to calculate the per-thread overhead introduced by the
50scheduler algorithms.  After these definitions the configuration file must
51``#include <rtems/scheduler.h>`` to have access to scheduler-specific
52configuration macros.
53
54It is possible to make more than one scheduler algorithm available to the
55application.  For example a :ref:`Simple Priority SMP Scheduler
56<SchedulerSMPPrioritySimple>` could be used in a partition for low latency
57tasks in addition to an :ref:`EDF SMP Scheduler <SchedulerSMPEDF>` for a
58general-purpose cluster.  Since the per-thread overhead depends on the
59scheduler algorithm only the scheduler algorithms used by the application
60should be configured.
61
62Configuration Step 2 - Schedulers
63---------------------------------
64
65Each scheduler needs some data structures.  Use the following macros to create
66the scheduler data structures for a particular scheduler identified in the
67configuration by ``name``.
68
69- ``RTEMS_SCHEDULER_EDF_SMP(name, max_cpu_count)``,
70
71- ``RTEMS_SCHEDULER_PRIORITY_AFFINITY_SMP(name, prio_count)``,
72
73- ``RTEMS_SCHEDULER_PRIORITY_SMP(name, prio_count)``, and
74
75- ``RTEMS_SCHEDULER_SIMPLE_SMP(name)``.
76
77The ``name`` parameter is used as part of a designator for scheduler-specific
78data structures, so the usual C/C++ designator rules apply.  This ``name`` is
79not the scheduler object name.  Additional parameters are scheduler-specific.
80
81.. _ConfigurationSchedulerTable:
82
83Configuration Step 3 - Scheduler Table
84--------------------------------------
85
86The schedulers are registered in the system via the scheduler table.  To
87populate the scheduler table define ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` to a
88list of the following scheduler table entry initializers
89
90- ``RTEMS_SCHEDULER_TABLE_EDF_SMP(name, obj_name)``,
91
92- ``RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP(name, obj_name)``,
93
94- ``RTEMS_SCHEDULER_TABLE_PRIORITY_SMP(name, obj_name)``, and
95
96- ``RTEMS_SCHEDULER_TABLE_SIMPLE_SMP(name, obj_name)``.
97
98The ``name`` parameter must correspond to the parameter defining the scheduler
99data structures of configuration step 2.  The ``obj_name`` determines the
100scheduler object name and can be used in :ref:`rtems_scheduler_ident()
101<rtems_scheduler_ident>` to get the scheduler object identifier.  The scheduler
102index is defined by the index of the scheduler table.  It is a configuration
103error to add a scheduler multiple times to the scheduler table.
104
105Configuration Step 4 - Processor to Scheduler Assignment
106--------------------------------------------------------
107
108The last step is to define which processor uses which scheduler.  For this
109purpose a scheduler assignment table must be defined.  The entry count of this
110table must be equal to the configured maximum processors
111(:ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>`).  A
112processor assignment to a scheduler can be optional or mandatory.  The boot
113processor must have a scheduler assigned.  In case the system needs more
114mandatory processors than available then a fatal run-time error will occur.  To
115specify the scheduler assignments define
116``CONFIGURE_SCHEDULER_ASSIGNMENTS`` to a list of
117
118- ``RTEMS_SCHEDULER_ASSIGN(scheduler_index, attr)`` and
119
120- ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER``
121
122macros.  The ``scheduler_index`` parameter must be a valid index into the
123scheduler table defined by configuration step 3.  The ``attr`` parameter
124defines the scheduler assignment attributes.  By default, a scheduler
125assignment to a processor is optional.  For the scheduler assignment attribute
126use one of the mutually exclusive variants
127
128- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``,
129
130- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and
131
132- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``.
133
134It is possible to add/remove processors to/from schedulers at run-time, see
135:ref:`rtems_scheduler_add_processor() <rtems_scheduler_add_processor>` and
136:ref:`rtems_scheduler_remove_processor() <rtems_scheduler_remove_processor>`.
137
138Configuration Example
139---------------------
140
141The following example shows a scheduler configuration for a hypothetical
142product using two chip variants.  One variant has four processors which is used
143for the normal product line and another provides eight processors for the
144high-performance product line.  The first processor performs hard-real time
145control of actuators and sensors.  The second processor is not used by RTEMS at
146all and runs a Linux instance to provide a graphical user interface.  The
147additional processors are used for a worker thread pool to perform data
148processing operations.
149
150The processors managed by RTEMS use two Deterministic Priority SMP schedulers
151capable of dealing with 256 priority levels.  The scheduler with index zero has
152the name ``"IO "``.  The scheduler with index one has the name ``"WORK"``.  The
153scheduler assignments of the first, third and fourth processor are mandatory,
154so the system must have at least four processors, otherwise a fatal run-time
155error will occur during system startup.  The processor assignments for the
156fifth up to the eighth processor are optional so that the same application can
157be used for the normal and high-performance product lines.  The second
158processor has no scheduler assigned and runs Linux.  A hypervisor will ensure
159that the two systems cannot interfere in an undesirable way.
160
161.. code-block:: c
162
163    #define CONFIGURE_MAXIMUM_PROCESSORS 8
164    #define CONFIGURE_MAXIMUM_PRIORITY 255
165
166    /* Configuration Step 1 - Scheduler Algorithms */
167    #define CONFIGURE_SCHEDULER_PRIORITY_SMP
168    #include <rtems/scheduler.h>
169
170    /* Configuration Step 2 - Schedulers */
171    RTEMS_SCHEDULER_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
172    RTEMS_SCHEDULER_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
173
174    /* Configuration Step 3 - Scheduler Table */
175    #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \
176      RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \
177        io, \
178         rtems_build_name('I', 'O', ' ', ' ') \
179      ), \
180      RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( \
181        work, \
182        rtems_build_name('W', 'O', 'R', 'K') \
183      )
184
185    /* Configuration Step 4 - Processor to Scheduler Assignment */
186    #define CONFIGURE_SCHEDULER_ASSIGNMENTS \
187      RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
188      RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \
189      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
190      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
191      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
192      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
193      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
194      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
195
196Configuration Errors
197--------------------
198
199In case one of the scheduler indices in ``CONFIGURE_SCHEDULER_ASSIGNMENTS``
200is invalid a link-time error will occur with an undefined reference to
201``RTEMS_SCHEDULER_INVALID_INDEX``.
202
203Some fatal errors may occur in case of scheduler configuration inconsistencies
204or a lack of processors on the system.  The fatal source is
205``RTEMS_FATAL_SOURCE_SMP``.
206
207- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot processor
208  must have a scheduler assigned.
209
210- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory
211  processor beyond the range of physically or virtually available processors.
212  The processor demand must be reduced for this system.
213
214- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a mandatory
215  processor failed during system initialization.  The system may not have this
216  processor at all or it could be a problem with a boot loader for example.
217  Check the ``CONFIGURE_SCHEDULER_ASSIGNMENTS`` definition.
218
219- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed
220  to start multitasking on a processor with no scheduler assigned.
Note: See TracBrowser for help on using the repository browser.