[rtems-docs commit] c-user: Move some task directives
Sebastian Huber
sebh at rtems.org
Wed Feb 1 12:08:09 UTC 2017
Module: rtems-docs
Branch: master
Commit: a2389124d70f5afa1c7ca59490d3c76f77bb70ae
Changeset: http://git.rtems.org/rtems-docs/commit/?id=a2389124d70f5afa1c7ca59490d3c76f77bb70ae
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Feb 1 13:07:25 2017 +0100
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 <rtems.h>
- #include <assert.h>
-
- 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 <rtems.h>
- #include <assert.h>
-
- 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 <rtems.h>
+ #include <assert.h>
+
+ 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 <rtems.h>
+ #include <assert.h>
+
+ 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
More information about the vc
mailing list