diff options
| -rw-r--r-- | c-user/scheduling-concepts/directives.rst | 885 | ||||
| -rw-r--r-- | 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..b1c485f 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. - * - ``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. |