mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-15 16:37:33 +08:00
ba9dfcf92c
Introduce a background section. This makes it easier to automatically generate parts of the scheduling concepts documentation in the future. Update #3993.
425 lines
11 KiB
ReStructuredText
425 lines
11 KiB
ReStructuredText
.. 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.
|