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/index.rst | 387 +---------------------------------- c-user/config/scheduler-general.rst | 389 ++++++++++++++++++++++++++++++++++++ 2 files changed, 390 insertions(+), 386 deletions(-) create mode 100644 c-user/config/scheduler-general.rst diff --git a/c-user/config/index.rst b/c-user/config/index.rst index 912d8b3..1afc3ed 100644 --- a/c-user/config/index.rst +++ b/c-user/config/index.rst @@ -1,6 +1,5 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2010 Gedare Bloom .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) .. index:: configuring a system @@ -23,391 +22,7 @@ Configuring a System bdbuf bsp-related idle-task - -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. + scheduler-general .. _ConfigurationSchedulersClustered: 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