Changeset bcdca5d in rtems-docs

Timestamp:

Nov 10, 2016, 10:34:32 AM (4 years ago)

Author:

Sebastian Huber <sebastian.huber@…>

Branches:

5, am, master

Children:

6345b2d

Parents:

6297ad3

Message:

c-user: Document scheduler add/remove processor

Location:

c-user

Files:

• configuring_a_system.rst (modified) (2 diffs)
• symmetric_multiprocessing_services.rst (modified) (3 diffs)

c-user/configuring_a_system.rst

@@ -4041 +4041 @@
     - ``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
@@ -4092 +4096 @@
         #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 ===

c-user/symmetric_multiprocessing_services.rst

@@ -44 +44 @@
 
 - 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
@@ -741 +745 @@
 
      * - ``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:
@@ -780 +782 @@
 
      * - ``RTEMS_SUCCESSFUL``
-       - successful operation
+       - Successful operation.
+     * - ``RTEMS_INVALID_ID``
+       - Invalid scheduler instance identifier.
      * - ``RTEMS_INVALID_ADDRESS``
-       - ``cpuset`` is NULL
-     * - ``RTEMS_INVALID_ID``
-       - invalid scheduler id
+       - 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.
+
+.. 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.
+
+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