looks good.
On Fri, Apr 23, 2021 at 1:15 PM Sebastian Huber <sebastian.hu...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel