From 275f4a049c2f21dd3aab33201c4b76a5ece1ed6d Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 9 Mar 2020 08:54:45 +0100 Subject: c-user: Move "General Scheduler Configuration" Update #3836. --- c-user/config/scheduler-general.rst | 389 ++++++++++++++++++++++++++++++++++++ 1 file changed, 389 insertions(+) create mode 100644 c-user/config/scheduler-general.rst (limited to 'c-user/config/scheduler-general.rst') diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst new file mode 100644 index 0000000..05fce6e --- /dev/null +++ b/c-user/config/scheduler-general.rst @@ -0,0 +1,389 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2010 Gedare Bloom +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +General Scheduler Configuration +=============================== + +This section defines the configuration parameters related to selecting a +scheduling algorithm for an application. A scheduler configuration is optional +and only necessary in very specific circumstances. A normal application +configuration does not need any of the configuration options described in this +section. By default, the :ref:`Deterministic Priority Scheduler +` algorithm is used in uniprocessor configurations. In case +SMP is enabled and the configured maximum processors +(:ref:`CONFIGURE_MAXIMUM_PROCESSORS `) is greater +than one, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler +` is selected as the default scheduler algorithm. + +For the :ref:`schedulers built into +RTEMS `, the configuration is straightforward. All that is +required is to define the configuration macro which specifies which scheduler +you want for in your application. + +The pluggable scheduler interface also enables the user to provide their own +scheduling algorithm. If you choose to do this, you must define multiple +configuration macros. + +.. index:: CONFIGURE_SCHEDULER_CBS + +.. _CONFIGURE_SCHEDULER_CBS: + +CONFIGURE_SCHEDULER_CBS +----------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_CBS`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Constant Bandwidth Server (CBS) Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for exactly one processor. + +.. index:: CONFIGURE_SCHEDULER_EDF + +.. _CONFIGURE_SCHEDULER_EDF: + +CONFIGURE_SCHEDULER_EDF +----------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_EDF`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Earliest Deadline First (EDF) Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for exactly one processor. + +.. index:: CONFIGURE_SCHEDULER_EDF_SMP + +.. _CONFIGURE_SCHEDULER_EDF_SMP: + +CONFIGURE_SCHEDULER_EDF_SMP +--------------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_EDF_SMP`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + This scheduler algorithm is only available when RTEMS is built with SMP + support enabled. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for up to 32 processors. + + This scheduler algorithm is the default in SMP configurations if + :ref:`CONFIGURE_MAXIMUM_PROCESSORS ` is + greater than one. + +.. index:: CONFIGURE_SCHEDULER_NAME + +.. _CONFIGURE_SCHEDULER_NAME: + +CONFIGURE_SCHEDULER_NAME +------------------------ + +CONSTANT: + ``CONFIGURE_SCHEDULER_NAME`` + +DATA TYPE: + RTEMS Name (``rtems_name``). + +RANGE: + Any value. + +DEFAULT VALUE: + The default name is + + - ``"MEDF"`` for the :ref:`EDF SMP Scheduler `, + - ``"MPA "`` for the :ref:`Arbitrary Processor Affinity Priority SMP Scheduler `, + - ``"MPD "`` for the :ref:`Deterministic Priority SMP Scheduler `, + - ``"MPS "`` for the :ref:`Simple Priority SMP Scheduler `, + - ``"UCBS"`` for the :ref:`Uniprocessor CBS Scheduler `, + - ``"UEDF"`` for the :ref:`Uniprocessor EDF Scheduler `, + - ``"UPD "`` for the :ref:`Uniprocessor Deterministic Priority Scheduler `, and + - ``"UPS "`` for the :ref:`Uniprocessor Simple Priority Scheduler `. + +DESCRIPTION: + Schedulers can be identified via ``rtems_scheduler_ident``. The name of + the scheduler is determined by the configuration. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + +.. index:: CONFIGURE_SCHEDULER_PRIORITY + +.. _CONFIGURE_SCHEDULER_PRIORITY: + +CONFIGURE_SCHEDULER_PRIORITY +---------------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_PRIORITY`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is defined by default. This is the default scheduler and specifying + this configuration parameter is redundant. + +DESCRIPTION: + If defined, then the :ref:`Deterministic Priority Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for exactly one processor. + + This scheduler algorithm is the default when + :ref:`CONFIGURE_MAXIMUM_PROCESSORS ` is + exactly one. + + The memory allocated for this scheduler depends on the + :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. index:: CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP + +.. _CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP: + +CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP +----------------------------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Arbitrary Processor Affinity SMP Scheduler + ` algorithm is made available to the + application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + This scheduler algorithm is only available when RTEMS is built with SMP + support enabled. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for up to 32 processors. + + The memory allocated for this scheduler depends on the + :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. index:: CONFIGURE_SCHEDULER_PRIORITY_SMP + +.. _CONFIGURE_SCHEDULER_PRIORITY_SMP: + +CONFIGURE_SCHEDULER_PRIORITY_SMP +-------------------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_PRIORITY_SMP`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Deterministic Priority SMP Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + This scheduler algorithm is only available when RTEMS is built with SMP + support enabled. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for up to 32 processors. + + The memory allocated for this scheduler depends on the + :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option. + +.. index:: CONFIGURE_SCHEDULER_SIMPLE + +.. _CONFIGURE_SCHEDULER_SIMPLE: + +CONFIGURE_SCHEDULER_SIMPLE +-------------------------- + +CONSTANT: + ``CONFIGURE_SCHEDULER_SIMPLE`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Simple Priority Scheduler + ` algorithm is made available to the application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for exactly one processor. + +.. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP + +.. _CONFIGURE_SCHEDULER_SIMPLE_SMP: + +CONFIGURE_SCHEDULER_SIMPLE_SMP +------------------------------ + +CONSTANT: + ``CONFIGURE_SCHEDULER_SIMPLE_SMP`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + If defined, then the :ref:`Simple Priority SMP Scheduler + ` algorithm is made available to the + application. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + This scheduler algorithm is only available when RTEMS is built with SMP + support enabled. + + In case no explicit :ref:`clustered scheduler configuration + ` is present, then it is used as the + scheduler for up to 32 processors. + +.. index:: CONFIGURE_SCHEDULER_USER + +.. _CONFIGURE_SCHEDULER_USER: + +CONFIGURE_SCHEDULER_USER +------------------------ + +CONSTANT: + ``CONFIGURE_SCHEDULER_USER`` + +DATA TYPE: + Boolean feature macro. + +RANGE: + Defined or undefined. + +DEFAULT VALUE: + This is not defined by default. + +DESCRIPTION: + RTEMS allows the application to provide its own task/thread scheduling + algorithm. In order to do this, one must define + ``CONFIGURE_SCHEDULER_USER`` to indicate the application provides its own + scheduling algorithm. If ``CONFIGURE_SCHEDULER_USER`` is defined then the + following additional macros must be defined: + + - ``CONFIGURE_SCHEDULER`` must be defined to a static definition of + the scheduler data structures of the user scheduler. + + - ``CONFIGURE_SCHEDULER_TABLE_ENTRIES`` must be defined to a scheduler + table entry initializer for the user scheduler. + + - ``CONFIGURE_SCHEDULER_USER_PER_THREAD`` must be defined to the type of + the per-thread information of the user scheduler. + +NOTES: + This scheduler configuration option is an advanced configuration option. + Think twice before you use it. + + At this time, the mechanics and requirements for writing a new scheduler + are evolving and not fully documented. It is recommended that you look at + the existing Deterministic Priority Scheduler in + ``cpukit/score/src/schedulerpriority*.c`` for guidance. For guidance on + the configuration macros, please examine ``cpukit/sapi/include/confdefs.h`` + for how these are defined for the Deterministic Priority Scheduler. -- cgit v1.2.3