c-user: Document scheduler add/remove processor

2025-05-14 17:39:19 +08:00 · 2016-11-10 11:34:32 +01:00 · 2016-11-10 11:34:32 +01:00 · bcdca5db9d
commit bcdca5db9d
parent 6297ad31d0
2 changed files with 125 additions and 33 deletions
--- 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 ===

--- 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