c-user: Split up scheduling concepts

Introduce a background section.

This makes it easier to automatically generate parts of the scheduling
concepts documentation in the future.

Update #3993.

1 files changed, 424 insertions, 0 deletions

diff --git a/c-user/scheduling-concepts/directives.rst b/c-user/scheduling-concepts/directives.rst
new file mode 100644
index 0000000..5b1246f
--- /dev/null
+++ b/c-user/scheduling-concepts/directives.rst
@@ -0,0 +1,424 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Directives
+==========
+
+This section details the scheduler manager.  A subsection is dedicated to each
+of these services and describes the calling sequence, related constants, usage,
+and status codes.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_ident:
+
+SCHEDULER_IDENT - Get ID of a scheduler
+---------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_ident(
+            rtems_name  name,
+            rtems_id   *id
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ADDRESS``
+       - The ``id`` parameter is ``NULL``.
+     * - ``RTEMS_INVALID_NAME``
+       - Invalid scheduler name.
+
+DESCRIPTION:
+    Identifies a scheduler by its name.  The scheduler name is determined by
+    the scheduler configuration.  See :ref:`ConfigurationSchedulerTable`
+    and :ref:`CONFIGURE_SCHEDULER_NAME`.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_ident_by_processor:
+
+SCHEDULER_IDENT_BY_PROCESSOR - Get ID of a scheduler by processor
+-----------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_ident_by_processor(
+            uint32_t  cpu_index,
+            rtems_id *id
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ADDRESS``
+       - The ``id`` parameter is ``NULL``.
+     * - ``RTEMS_INVALID_NAME``
+       - Invalid processor index.
+     * - ``RTEMS_INCORRECT_STATE``
+       - The processor index is valid, however, this processor is not owned by
+         a scheduler.
+
+DESCRIPTION:
+    Identifies a scheduler by a processor.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_ident_by_processor_set:
+
+SCHEDULER_IDENT_BY_PROCESSOR_SET - Get ID of a scheduler by processor set
+-------------------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_ident_by_processor_set(
+            size_t           cpusetsize,
+            const cpu_set_t *cpuset,
+            rtems_id        *id
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ADDRESS``
+       - The ``id`` parameter is ``NULL``.
+     * - ``RTEMS_INVALID_SIZE``
+       - Invalid processor set size.
+     * - ``RTEMS_INVALID_NAME``
+       - The processor set contains no online processor.
+     * - ``RTEMS_INCORRECT_STATE``
+       - The processor set is valid, however, the highest numbered online
+         processor in the specified processor set is not owned by a scheduler.
+
+DESCRIPTION:
+    Identifies a scheduler by a processor set.  The scheduler is selected
+    according to the highest numbered online processor in the specified
+    processor set.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_get_maximum_priority:
+
+SCHEDULER_GET_MAXIMUM_PRIORITY - Get maximum task priority of a scheduler
+-------------------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_get_maximum_priority(
+            rtems_id             scheduler_id,
+            rtems_task_priority *priority
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ID``
+       - Invalid scheduler instance identifier.
+     * - ``RTEMS_INVALID_ADDRESS``
+       - The ``priority`` parameter is ``NULL``.
+
+DESCRIPTION:
+    Returns the maximum task priority of the specified scheduler instance in
+    ``priority``.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_map_priority_to_posix:
+
+SCHEDULER_MAP_PRIORITY_TO_POSIX - Map task priority to POSIX thread prority
+---------------------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_map_priority_to_posix(
+            rtems_id             scheduler_id,
+            rtems_task_priority  priority,
+            int                 *posix_priority
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ADDRESS``
+       - The ``posix_priority`` parameter is ``NULL``.
+     * - ``RTEMS_INVALID_ID``
+       - Invalid scheduler instance identifier.
+     * - ``RTEMS_INVALID_PRIORITY``
+       - Invalid task priority.
+
+DESCRIPTION:
+    Maps a task priority to the corresponding POSIX thread priority.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_map_priority_from_posix:
+
+SCHEDULER_MAP_PRIORITY_FROM_POSIX - Map POSIX thread prority to task priority
+-----------------------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_map_priority_from_posix(
+            rtems_id             scheduler_id,
+            int                  posix_priority,
+            rtems_task_priority *priority
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ADDRESS``
+       - The ``priority`` parameter is ``NULL``.
+     * - ``RTEMS_INVALID_ID``
+       - Invalid scheduler instance identifier.
+     * - ``RTEMS_INVALID_PRIORITY``
+       - Invalid POSIX thread priority.
+
+DESCRIPTION:
+    Maps a POSIX thread priority to the corresponding task priority.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_get_processor:
+
+SCHEDULER_GET_PROCESSOR - Get current processor index
+-----------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        uint32_t rtems_scheduler_get_processor( void );
+
+DIRECTIVE STATUS CODES:
+    This directive returns the index of the current processor.
+
+DESCRIPTION:
+    In uniprocessor configurations, a value of zero will be returned.
+
+    In SMP configurations, an architecture specific method is used to obtain the
+    index of the current processor in the system.  The set of processor indices
+    is the range of integers starting with zero up to the processor count minus
+    one.
+
+    Outside of sections with disabled thread dispatching the current processor
+    index may change after every instruction since the thread may migrate from
+    one processor to another.  Sections with disabled interrupts are sections
+    with thread dispatching disabled.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_get_processor_maximum:
+
+SCHEDULER_GET_PROCESSOR_MAXIMUM - Get processor maximum
+-------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        uint32_t rtems_scheduler_get_processor_maximum( void );
+
+DIRECTIVE STATUS CODES:
+    This directive returns the processor maximum supported by the system.
+
+DESCRIPTION:
+    In uniprocessor configurations, a value of one will be returned.
+
+    In SMP configurations, this directive returns the minimum of the processors
+    (physically or virtually) available by the platform and the configured
+    processor maximum.  Not all processors in the range from processor index
+    zero to the last processor index (which is the processor maximum minus one)
+    may be configured to be used by a scheduler or online (online processors
+    have a scheduler assigned).
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_get_processor_set:
+
+SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler
+--------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_get_processor_set(
+            rtems_id   scheduler_id,
+            size_t     cpusetsize,
+            cpu_set_t *cpuset
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ID``
+       - Invalid scheduler instance identifier.
+     * - ``RTEMS_INVALID_ADDRESS``
+       - The ``cpuset`` parameter is ``NULL``.
+     * - ``RTEMS_INVALID_NUMBER``
+       - The processor set buffer is too small for the set of processors owned
+         by the scheduler instance.
+
+DESCRIPTION:
+    Returns the processor set owned by the scheduler instance in ``cpuset``.  A
+    set bit in the processor set means that this processor is owned by the
+    scheduler instance and a cleared bit means the opposite.
+
+NOTES:
+    None.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_add_processor:
+
+SCHEDULER_ADD_PROCESSOR - Add processor to a scheduler
+------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_add_processor(
+            rtems_id scheduler_id,
+            uint32_t cpu_index
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ID``
+       - Invalid scheduler instance identifier.
+     * - ``RTEMS_NOT_CONFIGURED``
+       - The processor is not configured to be used by the application.
+     * - ``RTEMS_INCORRECT_STATE``
+       - The processor is configured to be used by the application, however, it
+         is not online.
+     * - ``RTEMS_RESOURCE_IN_USE``
+       - The processor is already assigned to a scheduler instance.
+
+DESCRIPTION:
+    Adds a processor to the set of processors owned by the specified scheduler
+    instance.
+
+NOTES:
+    Must be called from task context.  This operation obtains and releases the
+    objects allocator lock.
+
+.. raw:: latex
+
+   \clearpage
+
+.. _rtems_scheduler_remove_processor:
+
+SCHEDULER_REMOVE_PROCESSOR - Remove processor from a scheduler
+--------------------------------------------------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_scheduler_remove_processor(
+            rtems_id scheduler_id,
+            uint32_t cpu_index
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - Successful operation.
+     * - ``RTEMS_INVALID_ID``
+       - Invalid scheduler instance identifier.
+     * - ``RTEMS_INVALID_NUMBER``
+       - The processor is not owned by the specified scheduler instance.
+     * - ``RTEMS_RESOURCE_IN_USE``
+       - The set of processors owned by the specified scheduler instance would
+         be empty after the processor removal and there exists a non-idle task
+         that uses this scheduler instance as its home scheduler instance.
+     * - ``RTEMS_RESOURCE_IN_USE``
+       - A task with a restricted processor affinity exists that uses this
+         scheduler instance as its home scheduler instance and it would be no
+         longer possible to allocate a processor for this task after the
+         removal of this processor.
+
+DESCRIPTION:
+    Removes a processor from set of processors owned by the specified scheduler
+    instance.
+
+NOTES:
+    Must be called from task context.  This operation obtains and releases the
+    objects allocator lock.  Removing a processor from a scheduler is a complex
+    operation that involves all tasks of the system.