From bcdca5db9d35138c9c97055b6e71621c451d9542 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Thu, 10 Nov 2016 11:34:32 +0100
Subject: c-user: Document scheduler add/remove processor

---
 c-user/symmetric_multiprocessing_services.rst | 116 ++++++++++++++++++++++----
 1 file changed, 100 insertions(+), 16 deletions(-)

(limited to 'c-user/symmetric_multiprocessing_services.rst')

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
-- 
cgit v1.2.3