From a2389124d70f5afa1c7ca59490d3c76f77bb70ae Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 1 Feb 2017 13:07:25 +0100 Subject: c-user: Move some task directives --- c-user/symmetric_multiprocessing_services.rst | 237 -------------------------- c-user/task_manager.rst | 234 +++++++++++++++++++++++++ 2 files changed, 234 insertions(+), 237 deletions(-) diff --git a/c-user/symmetric_multiprocessing_services.rst b/c-user/symmetric_multiprocessing_services.rst index 5637063..4f1e5bb 100644 --- a/c-user/symmetric_multiprocessing_services.rst +++ b/c-user/symmetric_multiprocessing_services.rst @@ -48,14 +48,6 @@ The application level services currently provided are: - 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 - -- rtems_task_get_affinity_ - Get task processor affinity - -- rtems_task_set_affinity_ - Set task processor affinity - Background ========== @@ -583,37 +575,6 @@ the heir thread must be used during interrupt processing. For this purpose a temporary per-processor stack is set up which may be used by the interrupt prologue before the stack is switched to the interrupt stack. -Operations -========== - -Setting Affinity to a Single Processor --------------------------------------- - -On some embedded applications targeting SMP systems, it may be beneficial to -lock individual tasks to specific processors. In this way, one can designate a -processor for I/O tasks, another for computation, etc.. The following -illustrates the code sequence necessary to assign a task an affinity for -processor with index ``processor_index``. - -.. code-block:: c - - #include - #include - - void pin_to_processor(rtems_id task_id, int processor_index) - { - rtems_status_code sc; - cpu_set_t cpuset; - CPU_ZERO(&cpuset); - CPU_SET(processor_index, &cpuset); - sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset); - assert(sc == RTEMS_SUCCESSFUL); - } - -It is important to note that the ``cpuset`` is not validated until the -``rtems_task_set_affinity`` call is made. At that point, it is validated -against the current system configuration. - Directives ========== @@ -840,201 +801,3 @@ 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 --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_scheduler( - rtems_id task_id, - rtems_id *scheduler_id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``scheduler_id`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - -DESCRIPTION: - Returns the scheduler identifier of a task identified by ``task_id`` in - ``scheduler_id``. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_task_set_scheduler: -.. _TASK_SET_SCHEDULER - Set scheduler of a task: - -TASK_SET_SCHEDULER - Set scheduler of a task --------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_scheduler( - rtems_id task_id, - rtems_id scheduler_id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ID`` - - invalid task or scheduler id - * - ``RTEMS_INCORRECT_STATE`` - - the task is in the wrong state to perform a scheduler change - -DESCRIPTION: - Sets the scheduler of a task identified by ``task_id`` to the scheduler - identified by ``scheduler_id``. The scheduler of a task is initialized to - the scheduler of the task that created it. - -NOTES: - None. - -EXAMPLE: - .. code-block:: c - :linenos: - - #include - #include - - void task(rtems_task_argument arg); - - void example(void) - { - rtems_status_code sc; - rtems_id task_id; - rtems_id scheduler_id; - rtems_name scheduler_name; - - scheduler_name = rtems_build_name('W', 'O', 'R', 'K'); - - sc = rtems_scheduler_ident(scheduler_name, &scheduler_id); - assert(sc == RTEMS_SUCCESSFUL); - - sc = rtems_task_create( - rtems_build_name('T', 'A', 'S', 'K'), - 1, - RTEMS_MINIMUM_STACK_SIZE, - RTEMS_DEFAULT_MODES, - RTEMS_DEFAULT_ATTRIBUTES, - &task_id - ); - assert(sc == RTEMS_SUCCESSFUL); - - sc = rtems_task_set_scheduler(task_id, scheduler_id); - assert(sc == RTEMS_SUCCESSFUL); - - sc = rtems_task_start(task_id, task, 0); - assert(sc == RTEMS_SUCCESSFUL); - } - -.. raw:: latex - - \clearpage - -.. _rtems_task_get_affinity: - -TASK_GET_AFFINITY - Get task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_get_affinity( - rtems_id id, - size_t cpusetsize, - cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - the affinity set buffer is too small for the current processor affinity - set of the task - -DESCRIPTION: - Returns the current processor affinity set of the task in ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - None. - -.. raw:: latex - - \clearpage - -.. _rtems_task_set_affinity: - -TASK_SET_AFFINITY - Set task processor affinity ------------------------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_task_set_affinity( - rtems_id id, - size_t cpusetsize, - const cpu_set_t *cpuset - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - successful operation - * - ``RTEMS_INVALID_ADDRESS`` - - ``cpuset`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid task id - * - ``RTEMS_INVALID_NUMBER`` - - invalid processor affinity set - -DESCRIPTION: - Sets the processor affinity set for the task specified by ``cpuset``. A - set bit in the affinity set means that the task can execute on this - processor and a cleared bit means the opposite. - -NOTES: - This function will not change the scheduler of the task. The intersection - of the processor affinity set and the set of processors owned by the - scheduler of the task must be non-empty. It is not an error if the - processor affinity set contains processors that are not part of the set of - processors owned by the scheduler instance of the task. A task will simply - not run under normal circumstances on these processors since the scheduler - ignores them. Some locking protocols may temporarily use processors that - are not included in the processor affinity set of the task. It is also not - an error if the processor affinity set contains processors that are not - part of the system. diff --git a/c-user/task_manager.rst b/c-user/task_manager.rst index 176e565..b246e57 100644 --- a/c-user/task_manager.rst +++ b/c-user/task_manager.rst @@ -43,6 +43,14 @@ and administer tasks. The directives provided by the task manager are: - rtems_task_wake_when_ - Wake up when specified +- rtems_task_get_scheduler_ - Get scheduler of a task + +- rtems_task_set_scheduler_ - Set scheduler of a task + +- rtems_task_get_affinity_ - Get task processor affinity + +- rtems_task_set_affinity_ - Set task processor affinity + - rtems_task_iterate_ - Iterate Over Tasks Background @@ -511,6 +519,34 @@ delete itself by sending a "delete self" message, event, or signal, or by restarting the task with special arguments which instruct the task to delete itself. +Setting Affinity to a Single Processor +-------------------------------------- + +On some embedded applications targeting SMP systems, it may be beneficial to +lock individual tasks to specific processors. In this way, one can designate a +processor for I/O tasks, another for computation, etc.. The following +illustrates the code sequence necessary to assign a task an affinity for +processor with index ``processor_index``. + +.. code-block:: c + + #include + #include + + void pin_to_processor(rtems_id task_id, int processor_index) + { + rtems_status_code sc; + cpu_set_t cpuset; + CPU_ZERO(&cpuset); + CPU_SET(processor_index, &cpuset); + sc = rtems_task_set_affinity(task_id, sizeof(cpuset), &cpuset); + assert(sc == RTEMS_SUCCESSFUL); + } + +It is important to note that the ``cpuset`` is not validated until the +``rtems_task_set_affinity`` call is made. At that point, it is validated +against the current system configuration. + Transition Advice for Obsolete Notepads --------------------------------------- @@ -1354,6 +1390,204 @@ NOTES: \clearpage +.. _rtems_task_get_scheduler: + +TASK_GET_SCHEDULER - Get scheduler of a task +-------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_get_scheduler( + rtems_id task_id, + rtems_id *scheduler_id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``scheduler_id`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + +DESCRIPTION: + Returns the scheduler identifier of a task identified by ``task_id`` in + ``scheduler_id``. + +NOTES: + None. + +.. raw:: latex + + \clearpage + +.. _rtems_task_set_scheduler: +.. _TASK_SET_SCHEDULER - Set scheduler of a task: + +TASK_SET_SCHEDULER - Set scheduler of a task +-------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_set_scheduler( + rtems_id task_id, + rtems_id scheduler_id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ID`` + - invalid task or scheduler id + * - ``RTEMS_INCORRECT_STATE`` + - the task is in the wrong state to perform a scheduler change + +DESCRIPTION: + Sets the scheduler of a task identified by ``task_id`` to the scheduler + identified by ``scheduler_id``. The scheduler of a task is initialized to + the scheduler of the task that created it. + +NOTES: + None. + +EXAMPLE: + .. code-block:: c + :linenos: + + #include + #include + + void task(rtems_task_argument arg); + + void example(void) + { + rtems_status_code sc; + rtems_id task_id; + rtems_id scheduler_id; + rtems_name scheduler_name; + + scheduler_name = rtems_build_name('W', 'O', 'R', 'K'); + + sc = rtems_scheduler_ident(scheduler_name, &scheduler_id); + assert(sc == RTEMS_SUCCESSFUL); + + sc = rtems_task_create( + rtems_build_name('T', 'A', 'S', 'K'), + 1, + RTEMS_MINIMUM_STACK_SIZE, + RTEMS_DEFAULT_MODES, + RTEMS_DEFAULT_ATTRIBUTES, + &task_id + ); + assert(sc == RTEMS_SUCCESSFUL); + + sc = rtems_task_set_scheduler(task_id, scheduler_id); + assert(sc == RTEMS_SUCCESSFUL); + + sc = rtems_task_start(task_id, task, 0); + assert(sc == RTEMS_SUCCESSFUL); + } + +.. raw:: latex + + \clearpage + +.. _rtems_task_get_affinity: + +TASK_GET_AFFINITY - Get task processor affinity +----------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_get_affinity( + rtems_id id, + size_t cpusetsize, + cpu_set_t *cpuset + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``cpuset`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - the affinity set buffer is too small for the current processor affinity + set of the task + +DESCRIPTION: + Returns the current processor affinity set of the task in ``cpuset``. A + set bit in the affinity set means that the task can execute on this + processor and a cleared bit means the opposite. + +NOTES: + None. + +.. raw:: latex + + \clearpage + +.. _rtems_task_set_affinity: + +TASK_SET_AFFINITY - Set task processor affinity +----------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_task_set_affinity( + rtems_id id, + size_t cpusetsize, + const cpu_set_t *cpuset + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - successful operation + * - ``RTEMS_INVALID_ADDRESS`` + - ``cpuset`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid task id + * - ``RTEMS_INVALID_NUMBER`` + - invalid processor affinity set + +DESCRIPTION: + Sets the processor affinity set for the task specified by ``cpuset``. A + set bit in the affinity set means that the task can execute on this + processor and a cleared bit means the opposite. + +NOTES: + This function will not change the scheduler of the task. The intersection + of the processor affinity set and the set of processors owned by the + scheduler of the task must be non-empty. It is not an error if the + processor affinity set contains processors that are not part of the set of + processors owned by the scheduler instance of the task. A task will simply + not run under normal circumstances on these processors since the scheduler + ignores them. Some locking protocols may temporarily use processors that + are not included in the processor affinity set of the task. It is also not + an error if the processor affinity set contains processors that are not + part of the system. + +.. raw:: latex + + \clearpage + .. _rtems_task_iterate: TASK_ITERATE - Iterate Over Tasks -- cgit v1.2.3