[PATCH] c-user: Generate scheduling concepts documentation
Gedare Bloom
gedare at rtems.org
Mon Apr 26 19:15:19 UTC 2021
looks good.
On Fri, Apr 23, 2021 at 1:15 PM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> The documentation is a consolidation of the comments in Doxygen markup
> and the documentation sources in Sphinx markup. The documentation was
> transfered to interface specification items. The documentation source
> files were generated from the items by a script.
>
> Update #3993.
> ---
>
> Here is the updated document for review:
>
> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
>
> c-user/scheduling-concepts/directives.rst | 885 +++++++++++++-------
> c-user/scheduling-concepts/introduction.rst | 86 +-
> 2 files changed, 646 insertions(+), 325 deletions(-)
>
> diff --git a/c-user/scheduling-concepts/directives.rst b/c-user/scheduling-concepts/directives.rst
> index 5b1246f..f80c5bd 100644
> --- a/c-user/scheduling-concepts/directives.rst
> +++ b/c-user/scheduling-concepts/directives.rst
> @@ -1,424 +1,701 @@
> .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
> +.. Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de)
> +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
> +
> +.. This file is part of the RTEMS quality process and was automatically
> +.. generated. If you find something that needs to be fixed or
> +.. worded better please post a report or patch to an RTEMS mailing list
> +.. or raise a bug report:
> +..
> +.. https://www.rtems.org/bugs.html
> +..
> +.. For information on updating and regenerating please refer to the How-To
> +.. section in the Software Requirements Engineering chapter of the
> +.. RTEMS Software Engineering manual. The manual is provided as a part of
> +.. a release. For development sources please refer to the online
> +.. documentation at:
> +..
> +.. https://docs.rtems.org
> +
> +.. _SchedulerManagerDirectives:
>
> 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.
> +This section details the directives of the Scheduler Manager. A subsection is
> +dedicated to each of this manager's directives and lists the calling sequence,
> +parameters, description, return values, and notes of the directive.
> +
> +.. Generated from spec:/rtems/scheduler/if/ident
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> -.. _rtems_scheduler_ident:
> +.. index:: rtems_scheduler_ident()
>
> -SCHEDULER_IDENT - Get ID of a scheduler
> ----------------------------------------
> +.. _InterfaceRtemsSchedulerIdent:
> +
> +rtems_scheduler_ident()
> +-----------------------
> +
> +Identifies a scheduler by the object name.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id );
> +
> +.. rubric:: PARAMETERS:
> +
> +``name``
> + This parameter is the scheduler name to look up.
> +
> +``id``
> + This parameter is the pointer to an object identifier variable. When the
> + directive call is successful, the identifier of the scheduler will be
> + stored in this variable.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: DESCRIPTION:
>
> - rtems_status_code rtems_scheduler_ident(
> - rtems_name name,
> - rtems_id *id
> - );
> +This directive obtains a scheduler identifier associated with the scheduler
> +name specified in ``name``.
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +.. rubric:: RETURN VALUES:
>
> - * - ``RTEMS_SUCCESSFUL``
> - - Successful operation.
> - * - ``RTEMS_INVALID_ADDRESS``
> - - The ``id`` parameter is ``NULL``.
> - * - ``RTEMS_INVALID_NAME``
> - - Invalid scheduler name.
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
>
> -DESCRIPTION:
> - Identifies a scheduler by its name. The scheduler name is determined by
> - the scheduler configuration. See :ref:`ConfigurationSchedulerTable`
> - and :ref:`CONFIGURE_SCHEDULER_NAME`.
> +:c:macro:`RTEMS_INVALID_NAME`
> + There was no scheduler associated with the name.
>
> -NOTES:
> - None.
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``id`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +.. rubric:: NOTES:
> +
> +The scheduler name is determined by the scheduler configuration.
> +
> +The scheduler identifier is used with other scheduler related directives to
> +access the scheduler.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/ident-by-processor
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_ident_by_processor()
> +
> +.. _InterfaceRtemsSchedulerIdentByProcessor:
>
> -.. _rtems_scheduler_ident_by_processor:
> +rtems_scheduler_ident_by_processor()
> +------------------------------------
>
> -SCHEDULER_IDENT_BY_PROCESSOR - Get ID of a scheduler by processor
> ------------------------------------------------------------------
> +Identifies a scheduler by the processor index.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: CALLING SEQUENCE:
>
> - rtems_status_code rtems_scheduler_ident_by_processor(
> - uint32_t cpu_index,
> - rtems_id *id
> - );
> +.. code-block:: c
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> + rtems_status_code rtems_scheduler_ident_by_processor(
> + uint32_t cpu_index,
> + rtems_id *id
> + );
>
> - * - ``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.
> +.. rubric:: PARAMETERS:
>
> -DESCRIPTION:
> - Identifies a scheduler by a processor.
> +``cpu_index``
> + This parameter is the processor index to identify the scheduler.
>
> -NOTES:
> - None.
> +``id``
> + This parameter is the pointer to an object identifier variable. When the
> + directive call is successful, the identifier of the scheduler will be
> + stored in this variable.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``id`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_NAME`
> + The processor index was invalid.
> +
> +:c:macro:`RTEMS_INCORRECT_STATE`
> + The processor index was valid, however, the corresponding processor was not
> + owned by a scheduler.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/ident-by-processor-set
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_ident_by_processor_set()
> +
> +.. _InterfaceRtemsSchedulerIdentByProcessorSet:
> +
> +rtems_scheduler_ident_by_processor_set()
> +----------------------------------------
> +
> +Identifies a scheduler by the processor set.
> +
> +.. rubric:: 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
> + );
> +
> +.. rubric:: PARAMETERS:
> +
> +``cpusetsize``
> + This parameter is the size of the referenced processor set variable in
> + bytes. This value shall be positive.
> +
> +``cpuset``
> + This parameter is the pointer to a processor set variable. The referenced
> + processor set will be used to identify the scheduler.
>
> -.. _rtems_scheduler_ident_by_processor_set:
> +``id``
> + This parameter is the pointer to an object identifier variable. When the
> + directive call is successful, the identifier of the scheduler will be
> + stored in this variable.
>
> -SCHEDULER_IDENT_BY_PROCESSOR_SET - Get ID of a scheduler by processor set
> --------------------------------------------------------------------------
> +.. rubric:: DESCRIPTION:
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +The scheduler is selected according to the highest numbered online processor in
> +the specified processor set.
>
> - rtems_status_code rtems_scheduler_ident_by_processor_set(
> - size_t cpusetsize,
> - const cpu_set_t *cpuset,
> - rtems_id *id
> - );
> +.. rubric:: RETURN VALUES:
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
>
> - * - ``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.
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``id`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
>
> -DESCRIPTION:
> - Identifies a scheduler by a processor set. The scheduler is selected
> - according to the highest numbered online processor in the specified
> - processor set.
> +:c:macro:`RTEMS_INVALID_SIZE`
> + The processor set size was invalid.
>
> -NOTES:
> - None.
> +:c:macro:`RTEMS_INVALID_NAME`
> + The processor set contained no online processor.
> +
> +:c:macro:`RTEMS_INCORRECT_STATE`
> + The processor set was valid, however, the highest numbered online processor
> + in the processor set was not owned by a scheduler.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/get-maximum-priority
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_get_maximum_priority()
> +
> +.. _InterfaceRtemsSchedulerGetMaximumPriority:
> +
> +rtems_scheduler_get_maximum_priority()
> +--------------------------------------
> +
> +Gets the maximum task priority of the scheduler.
>
> -.. _rtems_scheduler_get_maximum_priority:
> +.. rubric:: CALLING SEQUENCE:
>
> -SCHEDULER_GET_MAXIMUM_PRIORITY - Get maximum task priority of a scheduler
> --------------------------------------------------------------------------
> +.. code-block:: c
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> + rtems_status_code rtems_scheduler_get_maximum_priority(
> + rtems_id scheduler_id,
> + rtems_task_priority *priority
> + );
>
> - rtems_status_code rtems_scheduler_get_maximum_priority(
> - rtems_id scheduler_id,
> - rtems_task_priority *priority
> - );
> +.. rubric:: PARAMETERS:
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +``scheduler_id``
> + This parameter is the scheduler identifier.
>
> - * - ``RTEMS_SUCCESSFUL``
> - - Successful operation.
> - * - ``RTEMS_INVALID_ID``
> - - Invalid scheduler instance identifier.
> - * - ``RTEMS_INVALID_ADDRESS``
> - - The ``priority`` parameter is ``NULL``.
> +``priority``
> + This parameter is the pointer to a task priority variable. The maximum
> + priority of the scheduler will be stored in this variable, if the operation
> + is successful.
>
> -DESCRIPTION:
> - Returns the maximum task priority of the specified scheduler instance in
> - ``priority``.
> +.. rubric:: RETURN VALUES:
>
> -NOTES:
> - None.
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no scheduler associated with the identifier specified by
> + ``scheduler_id``.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``priority`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/map-priority-to-posix
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_map_priority_to_posix()
>
> -.. _rtems_scheduler_map_priority_to_posix:
> +.. _InterfaceRtemsSchedulerMapPriorityToPosix:
> +
> +rtems_scheduler_map_priority_to_posix()
> +---------------------------------------
>
> -SCHEDULER_MAP_PRIORITY_TO_POSIX - Map task priority to POSIX thread prority
> ----------------------------------------------------------------------------
> +Maps a Classic API task priority to the corresponding POSIX thread priority.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: CALLING SEQUENCE:
>
> - rtems_status_code rtems_scheduler_map_priority_to_posix(
> - rtems_id scheduler_id,
> - rtems_task_priority priority,
> - int *posix_priority
> - );
> +.. code-block:: c
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> + rtems_status_code rtems_scheduler_map_priority_to_posix(
> + rtems_id scheduler_id,
> + rtems_task_priority priority,
> + int *posix_priority
> + );
>
> - * - ``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.
> +.. rubric:: PARAMETERS:
>
> -DESCRIPTION:
> - Maps a task priority to the corresponding POSIX thread priority.
> +``scheduler_id``
> + This parameter is the scheduler identifier.
>
> -NOTES:
> - None.
> +``priority``
> + This parameter is the Classic API task priority to map.
> +
> +``posix_priority``
> + This parameter is the pointer to a POSIX thread priority variable. When
> + the directive call is successful, the POSIX thread priority value
> + corresponding to the specified Classic API task priority value will be
> + stored in this variable.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``posix_priority`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no scheduler associated with the identifier specified by
> + ``scheduler_id``.
> +
> +:c:macro:`RTEMS_INVALID_PRIORITY`
> + The Classic API task priority was invalid.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/map-priority-from-posix
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_map_priority_from_posix()
> +
> +.. _InterfaceRtemsSchedulerMapPriorityFromPosix:
> +
> +rtems_scheduler_map_priority_from_posix()
> +-----------------------------------------
> +
> +Maps a POSIX thread priority to the corresponding Classic API task priority.
> +
> +.. rubric:: 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
> + );
> +
> +.. rubric:: PARAMETERS:
>
> -.. _rtems_scheduler_map_priority_from_posix:
> +``scheduler_id``
> + This parameter is the scheduler identifier.
>
> -SCHEDULER_MAP_PRIORITY_FROM_POSIX - Map POSIX thread prority to task priority
> ------------------------------------------------------------------------------
> +``posix_priority``
> + This parameter is the POSIX thread priority to map.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +``priority``
> + This parameter is the pointer to a Classic API task priority variable.
> + When the directive call is successful, the Classic API task priority value
> + corresponding to the specified POSIX thread priority value will be stored
> + in this variable.
>
> - rtems_status_code rtems_scheduler_map_priority_from_posix(
> - rtems_id scheduler_id,
> - int posix_priority,
> - rtems_task_priority *priority
> - );
> +.. rubric:: RETURN VALUES:
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
>
> - * - ``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.
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``priority`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
>
> -DESCRIPTION:
> - Maps a POSIX thread priority to the corresponding task priority.
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no scheduler associated with the identifier specified by
> + ``scheduler_id``.
>
> -NOTES:
> - None.
> +:c:macro:`RTEMS_INVALID_PRIORITY`
> + The POSIX thread priority was invalid.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/get-processor
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_get_processor()
> +
> +.. _InterfaceRtemsSchedulerGetProcessor:
> +
> +rtems_scheduler_get_processor()
> +-------------------------------
> +
> +Returns the index of the current processor.
> +
> +.. rubric:: CALLING SEQUENCE:
>
> -.. _rtems_scheduler_get_processor:
> +.. code-block:: c
>
> -SCHEDULER_GET_PROCESSOR - Get current processor index
> ------------------------------------------------------
> + uint32_t rtems_scheduler_get_processor( void );
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: DESCRIPTION:
>
> - uint32_t rtems_scheduler_get_processor( void );
> +Where the system was built with SMP support disabled, this directive evaluates
> +to a compile time constant of zero.
>
> -DIRECTIVE STATUS CODES:
> - This directive returns the index of the current processor.
> +Where the system was built with SMP support enabled, this directive returns the
> +index of the current processor. The set of processor indices is the range of
> +integers starting with zero up to
> +:ref:`InterfaceRtemsSchedulerGetProcessorMaximum` minus one.
>
> -DESCRIPTION:
> - In uniprocessor configurations, a value of zero will be returned.
> +.. rubric:: RETURN VALUES:
>
> - 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.
> +Returns the index of the current processor.
>
> - 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.
> +.. rubric:: NOTES:
>
> -NOTES:
> - None.
> +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.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/get-processor-maximum
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_get_processor_maximum()
> +
> +.. _InterfaceRtemsSchedulerGetProcessorMaximum:
> +
> +rtems_scheduler_get_processor_maximum()
> +---------------------------------------
> +
> +Returns the processor maximum supported by the system.
>
> -.. _rtems_scheduler_get_processor_maximum:
> +.. rubric:: CALLING SEQUENCE:
>
> -SCHEDULER_GET_PROCESSOR_MAXIMUM - Get processor maximum
> --------------------------------------------------------
> +.. code-block:: c
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> + uint32_t rtems_scheduler_get_processor_maximum( void );
>
> - uint32_t rtems_scheduler_get_processor_maximum( void );
> +.. rubric:: DESCRIPTION:
>
> -DIRECTIVE STATUS CODES:
> - This directive returns the processor maximum supported by the system.
> +Where the system was built with SMP support disabled, this directive evaluates
> +to a compile time constant of one.
>
> -DESCRIPTION:
> - In uniprocessor configurations, a value of one will be returned.
> +Where the system was built with SMP support enabled, this directive returns the
> +minimum of the processors (physically or virtually) available at the
> +:term:`target` and the configured processor maximum (see
> +:ref:`CONFIGURE_MAXIMUM_PROCESSORS`). 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 may be online
> +(online processors have a scheduler assigned).
>
> - 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).
> +.. rubric:: RETURN VALUES:
>
> -NOTES:
> - None.
> +Returns the processor maximum supported by the system.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/get-processor-set
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_get_processor_set()
> +
> +.. _InterfaceRtemsSchedulerGetProcessorSet:
> +
> +rtems_scheduler_get_processor_set()
> +-----------------------------------
> +
> +Gets the set of processors owned by the scheduler.
> +
> +.. rubric:: CALLING SEQUENCE:
>
> -.. _rtems_scheduler_get_processor_set:
> +.. code-block:: c
>
> -SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler
> ---------------------------------------------------------------
> + rtems_status_code rtems_scheduler_get_processor_set(
> + rtems_id scheduler_id,
> + size_t cpusetsize,
> + cpu_set_t *cpuset
> + );
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: PARAMETERS:
>
> - rtems_status_code rtems_scheduler_get_processor_set(
> - rtems_id scheduler_id,
> - size_t cpusetsize,
> - cpu_set_t *cpuset
> - );
> +``scheduler_id``
> + This parameter is the scheduler identifier.
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +``cpusetsize``
> + This parameter is the size of the referenced processor set variable in
> + bytes. This value shall be positive.
>
> - * - ``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.
> +``cpuset``
> + This parameter is the pointer to a processor set variable. When the
> + directive call is successful, the processor set of the scheduler will be
> + stored in this variable. A set bit in the processor set means that the
> + corresponding processor is owned by the scheduler, otherwise the bit is
> + cleared.
>
> -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.
> +.. rubric:: RETURN VALUES:
>
> -NOTES:
> - None.
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``cpuset`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no scheduler associated with the identifier specified by
> + ``scheduler_id``.
> +
> +:c:macro:`RTEMS_INVALID_NUMBER`
> + The provided processor set was too small for the set of processors owned by
> + the scheduler.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within any runtime context.
> +
> +* The directive will not cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/add-processor
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_scheduler_add_processor()
>
> -.. _rtems_scheduler_add_processor:
> +.. _InterfaceRtemsSchedulerAddProcessor:
>
> -SCHEDULER_ADD_PROCESSOR - Add processor to a scheduler
> -------------------------------------------------------
> +rtems_scheduler_add_processor()
> +-------------------------------
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +Adds the processor to the set of processors owned by the scheduler.
>
> - rtems_status_code rtems_scheduler_add_processor(
> - rtems_id scheduler_id,
> - uint32_t cpu_index
> - );
> +.. rubric:: CALLING SEQUENCE:
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +.. code-block:: c
>
> - * - ``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.
> + rtems_status_code rtems_scheduler_add_processor(
> + rtems_id scheduler_id,
> + uint32_t cpu_index
> + );
>
> -DESCRIPTION:
> - Adds a processor to the set of processors owned by the specified scheduler
> - instance.
> +.. rubric:: PARAMETERS:
>
> -NOTES:
> - Must be called from task context. This operation obtains and releases the
> - objects allocator lock.
> +``scheduler_id``
> + This parameter is the scheduler identifier.
> +
> +``cpu_index``
> + This parameter is the index of the processor to add.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive adds the processor specified by the ``cpu_index`` to the
> +scheduler specified by ``scheduler_id``.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no scheduler associated with the identifier specified by
> + ``scheduler_id``.
> +
> +:c:macro:`RTEMS_NOT_CONFIGURED`
> + The processor was not configured to be used by the application.
> +
> +:c:macro:`RTEMS_INCORRECT_STATE`
> + The processor was configured to be used by the application, however, it was
> + not online.
> +
> +:c:macro:`RTEMS_RESOURCE_IN_USE`
> + The processor was already assigned to a scheduler.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within device driver initialization context.
> +
> +* The directive may be called from within task context.
> +
> +* The directive may obtain and release the object allocator mutex. This may
> + cause the calling task to be preempted.
> +
> +.. Generated from spec:/rtems/scheduler/if/remove-processor
>
> .. 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.
> + \clearpage
> +
> +.. index:: rtems_scheduler_remove_processor()
> +
> +.. _InterfaceRtemsSchedulerRemoveProcessor:
> +
> +rtems_scheduler_remove_processor()
> +----------------------------------
> +
> +Removes the processor from the set of processors owned by the scheduler.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + rtems_status_code rtems_scheduler_remove_processor(
> + rtems_id scheduler_id,
> + uint32_t cpu_index
> + );
> +
> +.. rubric:: PARAMETERS:
> +
> +``scheduler_id``
> + This parameter is the scheduler identifier.
> +
> +``cpu_index``
> + This parameter is the index of the processor to remove.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive removes the processor specified by the ``cpu_index`` from the
> +scheduler specified by ``scheduler_id``.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no scheduler associated with the identifier specified by
> + ``scheduler_id``.
> +
> +:c:macro:`RTEMS_INVALID_NUMBER`
> + The processor was not owned by the scheduler.
> +
> +:c:macro:`RTEMS_RESOURCE_IN_USE`
> + The set of processors owned by the scheduler would have been empty after
> + the processor removal and there was at least one non-idle task that used
> + this scheduler as its :term:`home scheduler`.
> +
> +.. rubric:: NOTES:
> +
> +Removing a processor from a scheduler is a complex operation that involves all
> +tasks of the system.
> +
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may be called from within device driver initialization context.
> +
> +* The directive may be called from within task context.
> +
> +* The directive may obtain and release the object allocator mutex. This may
> + cause the calling task to be preempted.
> diff --git a/c-user/scheduling-concepts/introduction.rst b/c-user/scheduling-concepts/introduction.rst
> index 92da6de..31de1c1 100644
> --- a/c-user/scheduling-concepts/introduction.rst
> +++ b/c-user/scheduling-concepts/introduction.rst
> @@ -1,42 +1,86 @@
> .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
> +.. Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de)
> +.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
> +
> +.. This file is part of the RTEMS quality process and was automatically
> +.. generated. If you find something that needs to be fixed or
> +.. worded better please post a report or patch to an RTEMS mailing list
> +.. or raise a bug report:
> +..
> +.. https://www.rtems.org/bugs.html
> +..
> +.. For information on updating and regenerating please refer to the How-To
> +.. section in the Software Requirements Engineering chapter of the
> +.. RTEMS Software Engineering manual. The manual is provided as a part of
> +.. a release. For development sources please refer to the online
> +.. documentation at:
> +..
> +.. https://docs.rtems.org
> +
> +.. Generated from spec:/rtems/scheduler/if/group
> +
> +.. _SchedulerManagerIntroduction:
>
> Introduction
> ============
>
> +.. The following list was generated from:
> +.. spec:/rtems/scheduler/if/ident
> +.. spec:/rtems/scheduler/if/ident-by-processor
> +.. spec:/rtems/scheduler/if/ident-by-processor-set
> +.. spec:/rtems/scheduler/if/get-maximum-priority
> +.. spec:/rtems/scheduler/if/map-priority-to-posix
> +.. spec:/rtems/scheduler/if/map-priority-from-posix
> +.. spec:/rtems/scheduler/if/get-processor
> +.. spec:/rtems/scheduler/if/get-processor-maximum
> +.. spec:/rtems/scheduler/if/get-processor-set
> +.. spec:/rtems/scheduler/if/add-processor
> +.. spec:/rtems/scheduler/if/remove-processor
> +
> +The scheduling concepts relate to the allocation of processing time for tasks.
> +
> The concept of scheduling in real-time systems dictates the ability to provide
> -an immediate response to specific external events, particularly the necessity of
> -scheduling tasks to run within a specified time limit after the occurrence of
> -an event. For example, software embedded in life-support systems used to
> -monitor hospital patients must take instant action if a change in the patient's
> +an immediate response to specific external events, particularly the necessity
> +of scheduling tasks to run within a specified time limit after the occurrence
> +of an event. For example, software embedded in life-support systems used to
> +monitor hospital patients must take instant action if a change in the patient’s
> status is detected.
>
> The component of RTEMS responsible for providing this capability is
> -appropriately called the scheduler. The scheduler's sole purpose is to
> -allocate the all important resource of processor time to the various tasks
> -competing for attention.
> -
> -The directives provided by the scheduler manager are:
> +appropriately called the scheduler. The scheduler’s sole purpose is to allocate
> +the all important resource of processor time to the various tasks competing for
> +attention. The directives provided by the Scheduler Manager are:
>
> -- :ref:`rtems_scheduler_ident`
> +* :ref:`InterfaceRtemsSchedulerIdent` - Identifies a scheduler by the object
> + name.
>
> -- :ref:`rtems_scheduler_ident_by_processor`
> +* :ref:`InterfaceRtemsSchedulerIdentByProcessor` - Identifies a scheduler by
> + the processor index.
>
> -- :ref:`rtems_scheduler_ident_by_processor_set`
> +* :ref:`InterfaceRtemsSchedulerIdentByProcessorSet` - Identifies a scheduler by
> + the processor set.
>
> -- :ref:`rtems_scheduler_get_maximum_priority`
> +* :ref:`InterfaceRtemsSchedulerGetMaximumPriority` - Gets the maximum task
> + priority of the scheduler.
>
> -- :ref:`rtems_scheduler_map_priority_to_posix`
> +* :ref:`InterfaceRtemsSchedulerMapPriorityToPosix` - Maps a Classic API task
> + priority to the corresponding POSIX thread priority.
>
> -- :ref:`rtems_scheduler_map_priority_from_posix`
> +* :ref:`InterfaceRtemsSchedulerMapPriorityFromPosix` - Maps a POSIX thread
> + priority to the corresponding Classic API task priority.
>
> -- :ref:`rtems_scheduler_get_processor`
> +* :ref:`InterfaceRtemsSchedulerGetProcessor` - Returns the index of the current
> + processor.
>
> -- :ref:`rtems_scheduler_get_processor_maximum`
> +* :ref:`InterfaceRtemsSchedulerGetProcessorMaximum` - Returns the processor
> + maximum supported by the system.
>
> -- :ref:`rtems_scheduler_get_processor_set`
> +* :ref:`InterfaceRtemsSchedulerGetProcessorSet` - Gets the set of processors
> + owned by the scheduler.
>
> -- :ref:`rtems_scheduler_add_processor`
> +* :ref:`InterfaceRtemsSchedulerAddProcessor` - Adds the processor to the set of
> + processors owned by the scheduler.
>
> -- :ref:`rtems_scheduler_remove_processor`
> +* :ref:`InterfaceRtemsSchedulerRemoveProcessor` - Removes the processor from
> + the set of processors owned by the scheduler.
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list