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