From bcdca5db9d35138c9c97055b6e71621c451d9542 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 10 Nov 2016 11:34:32 +0100 Subject: 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(-) (limited to 'c-user') 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 + /* 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 -- cgit v1.2.3