Changeset 020d2e7 in rtems-docs


Ignore:
Timestamp:
Mar 9, 2020, 7:55:20 AM (4 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
5, master
Children:
41ac3da
Parents:
275f4a0
git-author:
Sebastian Huber <sebastian.huber@…> (03/09/20 07:55:20)
git-committer:
Sebastian Huber <sebastian.huber@…> (03/12/20 09:21:06)
Message:

c-user: Move "Clustered Scheduler Configuration"

Update #3836.

Location:
c-user/config
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed
  • c-user/config/index.rst

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