[rtems-docs commit] c-user: Document scheduler add/remove processor
Sebastian Huber
sebh at rtems.org
Thu Nov 10 10:35:00 UTC 2016
Module: rtems-docs
Branch: master
Commit: bcdca5db9d35138c9c97055b6e71621c451d9542
Changeset: http://git.rtems.org/rtems-docs/commit/?id=bcdca5db9d35138c9c97055b6e71621c451d9542
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Thu Nov 10 11:34:32 2016 +0100
c-user: Document scheduler add/remove processor
---
c-user/configuring_a_system.rst | 42 ++++++----
c-user/symmetric_multiprocessing_services.rst | 116 ++++++++++++++++++++++----
2 files changed, 125 insertions(+), 33 deletions(-)
diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst
index 585014c..01a2e2e 100644
--- a/c-user/configuring_a_system.rst
+++ b/c-user/configuring_a_system.rst
@@ -4040,6 +4040,10 @@ CONFIGURATION:
- ``RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL``.
+ It is possible to add/remove processors to/from scheduler instances at
+ run-time, see :ref:`rtems_scheduler_add_processor` and
+ :ref:`rtems_scheduler_remove_processor`.
+
ERRORS:
In case one of the scheduler indices
in``CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS`` is invalid a link-time error will
@@ -4091,32 +4095,36 @@ EXAMPLE:
#define CONFIGURE_SMP_MAXIMUM_PROCESSORS 8
#define CONFIGURE_MAXIMUM_PRIORITY 255
+
/* Make the scheduler algorithm available */
#define CONFIGURE_SCHEDULER_PRIORITY_SMP
#include <rtems/scheduler.h>
+
/* Create contexts for the two scheduler instances */
RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(io, CONFIGURE_MAXIMUM_PRIORITY + 1);
RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP(work, CONFIGURE_MAXIMUM_PRIORITY + 1);
+
/* Define the scheduler table */
#define CONFIGURE_SCHEDULER_CONTROLS \\
- RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
- io, \
- rtems_build_name('I', 'O', ' ', ' ') \
- ), \
- RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
- work, \
- rtems_build_name('W', 'O', 'R', 'K') \
- )
- /* Define the processor to scheduler assignments */
+ RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
+ io, \
+ rtems_build_name('I', 'O', ' ', ' ') \
+ ), \
+ RTEMS_SCHEDULER_CONTROL_PRIORITY_SMP( \
+ work, \
+ rtems_build_name('W', 'O', 'R', 'K') \
+ )
+
+ /* Define the initial processor to scheduler assignments */
#define CONFIGURE_SMP_SCHEDULER_ASSIGNMENTS \
- RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
- RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
- RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
+ RTEMS_SCHEDULER_ASSIGN(0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
+ RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER, \
+ RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
+ RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY), \
+ RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
+ RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
+ RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL), \
+ RTEMS_SCHEDULER_ASSIGN(1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL)
.. COMMENT: === SMP Specific Configuration Parameters ===
diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst
index 6a47204..1fcc361 100644
--- a/c-user/symmetric_multiprocessing_services.rst
+++ b/c-user/symmetric_multiprocessing_services.rst
@@ -44,6 +44,10 @@ The application level services currently provided are:
- rtems_scheduler_get_processor_set_ - Get processor set of a scheduler
+- rtems_scheduler_add_processor_ - Add processor to a scheduler
+
+- rtems_scheduler_remove_processor_ - Remove processor from a scheduler
+
- rtems_task_get_scheduler_ - Get scheduler of a task
- rtems_task_set_scheduler_ - Set scheduler of a task
@@ -740,18 +744,16 @@ DIRECTIVE STATUS CODES:
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- - successful operation
+ - Successful operation.
* - ``RTEMS_INVALID_ADDRESS``
- - ``id`` is NULL
+ - The ``id`` parameter is ``NULL``.
* - ``RTEMS_INVALID_NAME``
- - invalid scheduler name
- * - ``RTEMS_UNSATISFIED``
- - a scheduler with this name exists, but the processor set of this scheduler
- is empty
+ - Invalid scheduler name.
DESCRIPTION:
Identifies a scheduler by its name. The scheduler name is determined by
- the scheduler configuration. See :ref:`Configuring a System`.
+ the scheduler configuration. See :ref:`Configuring Clustered Schedulers`
+ and :ref:`Configuring a Scheduler Name`.
NOTES:
None.
@@ -779,19 +781,19 @@ DIRECTIVE STATUS CODES:
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- - successful operation
- * - ``RTEMS_INVALID_ADDRESS``
- - ``cpuset`` is NULL
+ - Successful operation.
* - ``RTEMS_INVALID_ID``
- - invalid scheduler id
+ - Invalid scheduler instance identifier.
+ * - ``RTEMS_INVALID_ADDRESS``
+ - The ``cpuset`` parameter is ``NULL``.
* - ``RTEMS_INVALID_NUMBER``
- - the affinity set buffer is too small for set of processors owned by
- the scheduler
+ - 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 in ``cpuset``. A set bit
- in the processor set means that this processor is owned by the scheduler
- and a cleared bit means the opposite.
+ 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.
@@ -800,6 +802,88 @@ NOTES:
\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.
+
+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.
+
+.. raw:: latex
+
+ \clearpage
+
.. _rtems_task_get_scheduler:
TASK_GET_SCHEDULER - Get scheduler of a task
More information about the vc
mailing list