Changeset c65aeed in rtems-docs


Ignore:
Timestamp:
Mar 7, 2018, 2:17:15 PM (14 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
bf78123
Parents:
464d541
git-author:
Sebastian Huber <sebastian.huber@…> (03/07/18 14:17:15)
git-committer:
Sebastian Huber <sebastian.huber@…> (03/07/18 14:34:43)
Message:

c-user: Rework clustered scheduling configuration

Location:
c-user
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • c-user/configuring_a_system.rst

    r464d541 rc65aeed  
    36253625
    36263626Clustered scheduling helps to control the worst-case latencies in a
    3627 multi-processor system.  The goal is to reduce the amount of shared state in
    3628 the system and thus prevention of lock contention.  Modern multi-processor
     3627multi-processor system (SMP).  The goal is to reduce the amount of shared state
     3628in the system and thus prevention of lock contention.  Modern multi-processor
    36293629systems tend to have several layers of data and instruction caches.  With
    36303630clustered scheduling it is possible to honour the cache topology of a system
     
    36343634partitioned into non-empty pairwise-disjoint subsets.  These subsets are called
    36353635clusters.  Clusters with a cardinality of one are partitions.  Each cluster is
    3636 owned by exactly one scheduler instance.  In order to use clustered scheduling
    3637 the application designer has to answer two questions.
     3636owned by exactly one scheduler instance.
     3637
     3638A clustered scheduler configuration is optional.  By default, all processors are
     3639managed by the :ref:`EDF SMP Scheduler <SchedulerSMPEDF>`.  In order to use
     3640clustered scheduling the application designer has to answer two questions.
    36383641
    36393642#. How is the set of processors partitioned into clusters?
    36403643
    3641 #. Which scheduler is used for which cluster?
    3642 
    3643 CONFIGURATION:
    3644     The schedulers in an SMP system are statically configured on RTEMS.
    3645     Firstly the application must select which scheduling algorithms are
    3646     available with the following defines
    3647 
    3648     - ``CONFIGURE_SCHEDULER_PRIORITY_SMP``,
    3649 
    3650     - ``CONFIGURE_SCHEDULER_SIMPLE_SMP``, and
    3651 
    3652     - ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``.
    3653 
    3654     This is necessary to calculate the per-thread overhead introduced by the
    3655     schedulers.  After these definitions the configuration file must ``#include
    3656     <rtems/scheduler.h>`` to have access to scheduler specific configuration
    3657     macros.  Each scheduler needs a context to store state information at
    3658     run-time.  To provide a context for each scheduler is the next step.  Use
    3659     the following macros to create scheduler contexts
    3660 
    3661     - ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)``,
    3662 
    3663     - ``RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)``, and
    3664 
    3665     - ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)``.
    3666 
    3667     The ``name`` parameter is used as part of a designator for a global
    3668     variable, so the usual C/C++ designator rules apply.  Additional parameters
    3669     are scheduler specific.  The schedulers are registered in the system via
    3670     the scheduler table.  To create the scheduler table define
    3671     ``CONFIGURE_SCHEDULER_CONTROLS`` to a list of the following scheduler
    3672     control initializers
    3673 
    3674     - ``RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)``,
    3675 
    3676     - ``RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)``, and
    3677 
    3678     - ``RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)``.
    3679 
    3680     The ``name`` parameter must correspond to the parameter defining the
    3681     scheduler context.  The ``obj_name`` determines the scheduler object name
    3682     and can be used in ``rtems_scheduler_ident()`` to get the scheduler object
    3683     identifier.
    3684 
    3685     The last step is to define which processor uses which scheduler.  For this
    3686     purpose a scheduler assignment table must be defined.  The entry count of
    3687     this table must be equal to the configured maximum processors
    3688     (``CONFIGURE_MAXIMUM_PROCESSORS``).  A processor assignment to a
    3689     scheduler can be optional or mandatory.  The boot processor must have a
    3690     scheduler assigned.  In case the system needs more mandatory processors
    3691     than available then a fatal run-time error will occur.  To specify the
    3692     scheduler assignments define ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` to a
    3693     list of ``RTEMS_SCHEDULER_ASSIGN(index, attr)`` and
    3694     ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER`` macros.  The ``index`` parameter
    3695     must be a valid index into the scheduler table.  The ``attr`` parameter
    3696     defines the scheduler assignment attributes.  By default a scheduler
    3697     assignment to a processor is optional.  For the scheduler assignment
    3698     attribute use one of the mutually exclusive variants
    3699 
    3700     - ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``,
    3701 
    3702     - ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and
    3703 
    3704     - ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``.
    3705 
    3706     It is possible to add/remove processors to/from scheduler instances at
    3707     run-time, see :ref:`rtems_scheduler_add_processor` and
    3708     :ref:`rtems_scheduler_remove_processor`.
    3709 
    3710 ERRORS:
    3711     In case one of the scheduler indices
    3712     in``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` is invalid a link-time error will
    3713     occur with an undefined reference to ``RTEMS_SCHEDULER_INVALID_INDEX``.
    3714 
    3715     Some fatal errors may occur in case of scheduler configuration
    3716     inconsistencies or a lack of processors on the system.  The fatal source is
    3717     ``RTEMS_FATAL_SOURCE_SMP``.  None of the errors is internal.
    3718 
    3719     - ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot
    3720       processor must have a scheduler assigned.
    3721 
    3722     - ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory
    3723       processor beyond the range of physically or virtually available
    3724       processors.  The processor demand must be reduced for this system.
    3725 
    3726     - ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a
    3727       mandatory processor failed during system initialization.  The system may
    3728       not have this processor at all or it could be a problem with a boot
    3729       loader for example.  Check the ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS``
    3730       definition.
    3731 
    3732     - ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not
    3733       allowed to start multitasking on a processor with no scheduler assigned.
    3734 
    3735 EXAMPLE:
    3736     The following example shows a scheduler configuration for a hypothetical
    3737     product using two chip variants.  One variant has four processors which is
    3738     used for the normal product line and another provides eight processors for
    3739     the high-performance product line.  The first processor performs hard-real
    3740     time control of actuators and sensors.  The second processor is not used by
    3741     RTEMS at all and runs a Linux instance to provide a graphical user
    3742     interface.  The additional processors are used for a worker thread pool to
    3743     perform data processing operations.
    3744 
    3745     The processors managed by RTEMS use two Deterministic Priority scheduler
    3746     instances capable of dealing with 256 priority levels.  The scheduler with
    3747     index zero has the name ``"IO "``.  The scheduler with index one has the
    3748     name ``"WORK"``.  The scheduler assignments of the first, third and fourth
    3749     processor are mandatory, so the system must have at least four processors,
    3750     otherwise a fatal run-time error will occur during system startup.  The
    3751     processor assignments for the fifth up to the eighth processor are optional
    3752     so that the same application can be used for the normal and
    3753     high-performance product lines.  The second processor has no scheduler
    3754     assigned and runs Linux.  A hypervisor will ensure that the two systems
    3755     cannot interfere in an undesirable way.
    3756 
    3757     .. code-block:: c
    3758 
    3759         #define CONFIGURE_MAXIMUM_PROCESSORS 8
    3760         #define CONFIGURE_MAXIMUM_PRIORITY 255
    3761 
    3762         /* Make the scheduler algorithm available */
    3763         #define CONFIGURE_SCHEDULER_PRIORITY_SMP
    3764         #include <rtems/scheduler.h>
    3765 
    3766         /* Create contexts for the two scheduler instances */
    3767         RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
    3768         RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
    3769 
    3770         /* Define the scheduler table */
    3771         #define CONFIGURE_SCHEDULER_CONTROLS \\
    3772             RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
    3773                 io, \
    3774                 rtems_build_name('I', 'O', ' ', ' ') \
    3775             ), \
    3776             RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
    3777                 work, \
    3778                 rtems_build_name('W', 'O', 'R', 'K') \
    3779             )
    3780 
    3781         /* Define the initial processor to scheduler assignments */
    3782         #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \
    3783             RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
    3784             RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \
    3785             RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
    3786             RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
    3787             RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
    3788             RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
    3789             RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
    3790             RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
     3644#. Which scheduler algorithm is used for which cluster?
     3645
     3646The schedulers are statically configured.
     3647
     3648Configuration Step 1 - Scheduler Algorithms
     3649-------------------------------------------
     3650
     3651Firstly, the application must select which scheduling algorithms are available
     3652with the following defines
     3653
     3654- ``CONFIGURE_SCHEDULER_EDF_SMP``,
     3655
     3656- ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP``,
     3657
     3658- ``CONFIGURE_SCHEDULER_PRIORITY_SMP``, and
     3659
     3660- ``CONFIGURE_SCHEDULER_SIMPLE_SMP``.
     3661
     3662This is necessary to calculate the per-thread overhead introduced by the
     3663schedulers.  After these definitions the configuration file must ``#include
     3664<rtems/scheduler.h>`` to have access to scheduler-specific configuration
     3665macros.
     3666
     3667Configuration Step 2 - Schedulers
     3668---------------------------------
     3669
     3670Each scheduler needs a context to store state information at run-time.  Use the
     3671following macros to create scheduler contexts
     3672
     3673- ``RTEMS_SCHEDULER_CONTEXT_EDF_SMP(name, max_cpu_count)``,
     3674
     3675- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP(name, prio_count)``,
     3676
     3677- ``RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(name, prio_count)``, and
     3678
     3679- ``RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP(name)``.
     3680
     3681The ``name`` parameter is used as part of a designator for a global variable,
     3682so the usual C/C++ designator rules apply.  This ``name`` is not the scheduler
     3683object name.  Additional parameters are scheduler-specific.
     3684
     3685.. _ConfigurationSchedulerTable:
     3686
     3687Configuration Step 3 - Scheduler Table
     3688--------------------------------------
     3689
     3690The schedulers are registered in the system via the scheduler table.
     3691To create the scheduler table define ``CONFIGURE_SCHEDULER_CONTROLS`` to a list
     3692of the following scheduler control initializers
     3693
     3694- ``RTEMS_SCHEDULER_CONTROL_EDF_SMP(name, obj_name)``,
     3695
     3696- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_AFFINITY_SMP(name, obj_name)``,
     3697
     3698- ``RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP(name, obj_name)``, and
     3699
     3700- ``RTEMS_SCHEDULER_CONTROL_SIMPLE_SMP(name, obj_name)``.
     3701
     3702The ``name`` parameter must correspond to the parameter defining the scheduler
     3703context.  The ``obj_name`` determines the scheduler object name and can be used
     3704in :ref:`rtems_scheduler_ident() <rtems_scheduler_ident>` to get the scheduler
     3705object identifier.  The scheduler index is defined by the index of the
     3706scheduler table.  It is a configuration error to add a scheduler multiple times
     3707to the scheduler table.
     3708
     3709Configuration Step 4 - Processor to Scheduler Assignment
     3710--------------------------------------------------------
     3711
     3712The last step is to define which processor uses which scheduler.  For this
     3713purpose a scheduler assignment table must be defined.  The entry count of this
     3714table must be equal to the configured maximum processors
     3715(:ref:`CONFIGURE_MAXIMUM_PROCESSORS <CONFIGURE_MAXIMUM_PROCESSORS>`).  A
     3716processor assignment to a scheduler can be optional or mandatory.  The boot
     3717processor must have a scheduler assigned.  In case the system needs more
     3718mandatory processors than available then a fatal run-time error will occur.  To
     3719specify the scheduler assignments define
     3720``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` to a list of
     3721
     3722- ``RTEMS_SCHEDULER_ASSIGN(scheduler_index, attr)`` and
     3723
     3724- ``RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER``
     3725
     3726macros.  The ``scheduler_index`` parameter must
     3727be a valid index into the scheduler table.  The ``attr`` parameter defines the
     3728scheduler assignment attributes.  By default, a scheduler assignment to a
     3729processor is optional.  For the scheduler assignment attribute use one of the
     3730mutually exclusive variants
     3731
     3732- ``RTEMS_SCHEDULER_ASSIGN_DEFAULT``,
     3733
     3734- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY``, and
     3735
     3736- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``.
     3737
     3738It is possible to add/remove processors to/from schedulers at run-time, see
     3739:ref:`rtems_scheduler_add_processor() <rtems_scheduler_add_processor>` and
     3740:ref:`rtems_scheduler_remove_processor() <rtems_scheduler_remove_processor>`.
     3741
     3742Configuration Example
     3743---------------------
     3744
     3745The following example shows a scheduler configuration for a hypothetical
     3746product using two chip variants.  One variant has four processors which is used
     3747for the normal product line and another provides eight processors for the
     3748high-performance product line.  The first processor performs hard-real time
     3749control of actuators and sensors.  The second processor is not used by RTEMS at
     3750all and runs a Linux instance to provide a graphical user interface.  The
     3751additional processors are used for a worker thread pool to perform data
     3752processing operations.
     3753
     3754The processors managed by RTEMS use two Deterministic Priority SMP schedulers
     3755capable of dealing with 256 priority levels.  The scheduler with index zero has
     3756the name ``"IO "``.  The scheduler with index one has the name ``"WORK"``.  The
     3757scheduler assignments of the first, third and fourth processor are mandatory,
     3758so the system must have at least four processors, otherwise a fatal run-time
     3759error will occur during system startup.  The processor assignments for the
     3760fifth up to the eighth processor are optional so that the same application can
     3761be used for the normal and high-performance product lines.  The second
     3762processor has no scheduler assigned and runs Linux.  A hypervisor will ensure
     3763that the two systems cannot interfere in an undesirable way.
     3764
     3765.. code-block:: c
     3766
     3767    #define CONFIGURE_MAXIMUM_PROCESSORS 8
     3768    #define CONFIGURE_MAXIMUM_PRIORITY 255
     3769
     3770    /* Configuration Step 1 - Scheduler Algorithms */
     3771    #define CONFIGURE_SCHEDULER_PRIORITY_SMP
     3772    #include <rtems/scheduler.h>
     3773
     3774    /* Configuration Step 2 - Schedulers */
     3775    RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
     3776    RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
     3777
     3778    /* Configuration Step 3 - Scheduler Table */
     3779    #define CONFIGURE_SCHEDULER_CONTROLS \\
     3780      RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
     3781        io, \
     3782         rtems_build_name('I', 'O', ' ', ' ') \
     3783      ), \
     3784      RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
     3785        work, \
     3786        rtems_build_name('W', 'O', 'R', 'K') \
     3787      )
     3788
     3789    /* Configuration Step 4 - Processor to Scheduler Assignment */
     3790    #define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \
     3791      RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
     3792      RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \
     3793      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
     3794      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
     3795      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
     3796      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
     3797      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
     3798      RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
     3799
     3800Configuration Errors
     3801--------------------
     3802
     3803In case one of the scheduler indices in ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS``
     3804is invalid a link-time error will occur with an undefined reference to
     3805``RTEMS_SCHEDULER_INVALID_INDEX``.
     3806
     3807Some fatal errors may occur in case of scheduler configuration inconsistencies
     3808or a lack of processors on the system.  The fatal source is
     3809``RTEMS_FATAL_SOURCE_SMP``.
     3810
     3811- ``SMP_FATAL_BOOT_PROCESSOR_NOT_ASSIGNED_TO_SCHEDULER`` - the boot processor
     3812  must have a scheduler assigned.
     3813
     3814- ``SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT`` - there exists a mandatory
     3815  processor beyond the range of physically or virtually available processors.
     3816  The processor demand must be reduced for this system.
     3817
     3818- ``SMP_FATAL_START_OF_MANDATORY_PROCESSOR_FAILED`` - the start of a mandatory
     3819  processor failed during system initialization.  The system may not have this
     3820  processor at all or it could be a problem with a boot loader for example.
     3821  Check the ``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` definition.
     3822
     3823- ``SMP_FATAL_MULTITASKING_START_ON_UNASSIGNED_PROCESSOR`` - it is not allowed
     3824  to start multitasking on a processor with no scheduler assigned.
    37913825
    37923826Device Driver Table
  • c-user/scheduling_concepts.rst

    r464d541 rc65aeed  
    565565DESCRIPTION:
    566566    Identifies a scheduler by its name.  The scheduler name is determined by
    567     the scheduler configuration.  See :ref:`ConfigurationSchedulersClustered`
    568     and :ref:`Configuring a Scheduler Name`.
     567    the scheduler configuration.  See :ref:`ConfigurationSchedulerTable`
     568    and :ref:`CONFIGURE_SCHEDULER_NAME`.
    569569
    570570NOTES:
Note: See TracChangeset for help on using the changeset viewer.