diff options
Diffstat (limited to 'c-user/task/directives.rst')
| -rw-r--r-- | c-user/task/directives.rst | 121 |
1 files changed, 71 insertions, 50 deletions
diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst index e544525..d976905 100644 --- a/c-user/task/directives.rst +++ b/c-user/task/directives.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically .. generated. If you find something that needs to be fixed or @@ -74,9 +74,9 @@ Creates a task. This parameter is the attribute set of the task. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the created task will be - stored in this object. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the created task will + be stored in this object. .. rubric:: DESCRIPTION: @@ -86,9 +86,9 @@ identifier is returned in ``id``. This identifier is used to access the task with other task related directives. The **initial priority** of the task is specified in ``initial_priority``. The -scheduler of the created task is the scheduler of the calling task at some -point during the task creation. The initial task priority specified in -``initial_priority`` shall be valid for this scheduler. +:term:`home scheduler` of the created task is the home scheduler of the calling +task at some time point during the task creation. The initial task priority +specified in ``initial_priority`` shall be valid for this scheduler. The **stack size** of the task is specified in ``stack_size``. If the requested stack size is less than the configured minimum stack size, then RTEMS @@ -332,12 +332,13 @@ Constructs a task from the specified task configuration. .. rubric:: PARAMETERS: ``config`` - This parameter is the task configuration. + This parameter is the pointer to an :ref:`InterfaceRtemsTaskConfig` object. + It configures the task. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the constructed task will - be stored in this object. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the constructed task + will be stored in this object. .. rubric:: RETURN VALUES: @@ -407,9 +408,9 @@ An application based solely on static allocation can avoid any runtime memory allocators. This can simplify the application architecture as well as any analysis that may be required. -The stack space estimate done by <rtems/confdefs.h> assumes that all tasks are -created by :ref:`InterfaceRtemsTaskCreate`. The estimate can be adjusted to -take user-provided task storage areas into account through the +The stack space estimate done by ``<rtems/confdefs.h>`` assumes that all tasks +are created by :ref:`InterfaceRtemsTaskCreate`. The estimate can be adjusted +to take user-provided task storage areas into account through the :ref:`CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE` application configuration option. @@ -475,17 +476,17 @@ Identifies a task by the object name. This parameter is the node or node set to search for a matching object. ``id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the object identifier of an object with the - specified name will be stored in this object. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the object identifier of an object with + the specified name will be stored in this object. .. rubric:: DESCRIPTION: This directive obtains a task identifier associated with the task name specified in ``name``. -A task may obtain its own identifier by specifying :c:macro:`RTEMS_SELF` for -the name. +A task may obtain its own identifier by specifying :c:macro:`RTEMS_WHO_AM_I` +for the name. The node to search is specified in ``node``. It shall be @@ -623,9 +624,9 @@ Starts the task. .. rubric:: DESCRIPTION: This directive readies the task, specified by ``id``, for execution based on -the priority and execution mode specified when the task was created. The entry -point of the task is given in ``entry_point``. The task's entry point argument -is contained in ``argument``. +the priority and execution mode specified when the task was created. The +:term:`task entry` point of the task is given in ``entry_point``. The task's +entry point argument is contained in ``argument``. .. rubric:: RETURN VALUES: @@ -805,14 +806,26 @@ specified by ``id``. :c:macro:`RTEMS_CALLED_FROM_ISR` The directive was called from within interrupt context. +:c:macro:`RTEMS_INCORRECT_STATE` + The task termination procedure was started, however, waiting for the + terminating task would have resulted in a deadlock. + :c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT` The task resided on a remote node. .. rubric:: NOTES: -RTEMS stops the execution of the task and reclaims the stack memory, any -allocated delay or timeout timers, the TCB, and, if the task is -:c:macro:`RTEMS_FLOATING_POINT`, its floating point context area. RTEMS +The task deletion is done in several steps. Firstly, the task is marked as +terminating. While the task life of the terminating task is protected, it +executes normally until it disables the task life protection or it deletes +itself. A terminating task will eventually stop its normal execution and start +its termination procedure. The procedure executes in the context of the +terminating task. The task termination procedure involves the destruction of +POSIX key values and running the task termination user extensions. Once +complete the execution of the task is stopped and task-specific resources are +reclaimed by the system, such as the stack memory, any allocated delay or +timeout timers, the :term:`TCB`, and, if the task is +:c:macro:`RTEMS_FLOATING_POINT`, its floating point context area. RTEMS explicitly does not reclaim the following resources: region segments, partition buffers, semaphores, timers, or rate monotonic periods. @@ -824,10 +837,13 @@ resources before deletion. A task can be directed to release its resources and delete itself by restarting it with a special argument or by sending it a message, an event, or a signal. -Deletion of the current task (:c:macro:`RTEMS_SELF`) will force RTEMS to select +Deletion of the calling task (:c:macro:`RTEMS_SELF`) will force RTEMS to select another task to execute. -The :term:`TCB` for the deleted task is reclaimed by RTEMS. +When a task deletes another task, the calling task waits until the task +termination procedure of the task being deleted has completed. The terminating +task inherits the :term:`eligible priorities <eligible priority>` of the +calling task. When a global task is deleted, the task identifier must be transmitted to every node in the system for deletion from the local copy of the global object table. @@ -1147,10 +1163,10 @@ Sets the real priority or gets the current priority of the task. :c:macro:`RTEMS_CURRENT_PRIORITY` to get the current priority. ``old_priority`` - This parameter is the pointer to an :c:type:`rtems_task_priority` object. - When the directive call is successful, the current or previous priority of - the task with respect to its :term:`home scheduler` will be stored in this - object. + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the current or previous + priority of the task with respect to its :term:`home scheduler` will be + stored in this object. .. rubric:: DESCRIPTION: @@ -1246,9 +1262,9 @@ Gets the current priority of the task with respect to the scheduler. This parameter is the scheduler identifier. ``priority`` - This parameter is the pointer to an :c:type:`rtems_task_priority` object. - When the directive call is successful, the current priority of the task - with respect to the specified scheduler will be stored in this object. + This parameter is the pointer to an :ref:`InterfaceRtemsTaskPriority` + object. When the directive call is successful, the current priority of the + task with respect to the specified scheduler will be stored in this object. .. rubric:: DESCRIPTION: @@ -1459,16 +1475,16 @@ The following constraints apply to this directive: \clearpage .. index:: rtems_task_wake_after() -.. index:: delay a task for an interval -.. index:: wake up after an interval +.. index:: delay a task for a count of clock ticks +.. index:: wake up after a count of clock ticks .. _InterfaceRtemsTaskWakeAfter: rtems_task_wake_after() ----------------------- -Wakes up after an interval in :term:`clock ticks <clock tick>` or yields the -processor. +Wakes up after a count of :term:`clock ticks <clock tick>` have occurred or +yields the processor. .. rubric:: CALLING SEQUENCE: @@ -1479,16 +1495,16 @@ processor. .. rubric:: PARAMETERS: ``ticks`` - This parameter is the interval in :term:`clock ticks <clock tick>` to delay + This parameter is the count of :term:`clock ticks <clock tick>` to delay the task or :c:macro:`RTEMS_YIELD_PROCESSOR` to yield the processor. .. rubric:: DESCRIPTION: -This directive blocks the calling task for the specified ``ticks`` of clock -ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. When the -requested interval has elapsed, the task is made ready. The clock tick -directives automatically updates the delay period. The calling task may give -up the processor and remain in the ready state by specifying a value of +This directive blocks the calling task for the specified ``ticks`` count of +clock ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. When +the requested count of ticks have occurred, the task is made ready. The clock +tick directives automatically update the delay period. The calling task may +give up the processor and remain in the ready state by specifying a value of :c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``. .. rubric:: RETURN VALUES: @@ -1500,7 +1516,12 @@ up the processor and remain in the ready state by specifying a value of Setting the system date and time with the :ref:`InterfaceRtemsClockSet` directive and similar directives which set :term:`CLOCK_REALTIME` have no -effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task. +effect on a :ref:`InterfaceRtemsTaskWakeAfter` blocked task. The delay until +first clock tick will never be a whole clock tick interval since this directive +will never execute exactly on a clock tick. Applications requiring use of a +clock (:term:`CLOCK_REALTIME` or :term:`CLOCK_MONOTONIC`) instead of clock +ticks should make use of `clock_nanosleep() +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_nanosleep.html>`_. .. rubric:: CONSTRAINTS: @@ -1615,9 +1636,9 @@ Gets the home scheduler of the task. may be used to specify the calling task. ``scheduler_id`` - This parameter is the pointer to an :c:type:`rtems_id` object. When the - directive call is successful, the identifier of the :term:`home scheduler` - of the task will be stored in this object. + This parameter is the pointer to an :ref:`InterfaceRtemsId` object. When + the directive call is successful, the identifier of the :term:`home + scheduler` of the task will be stored in this object. .. rubric:: DESCRIPTION: @@ -1976,7 +1997,7 @@ Gets the recommended task storage area size for the size and task attributes. .. code-block:: c - #define RTEMS_TASK_STORAGE_SIZE( size, attributes ) + size_t RTEMS_TASK_STORAGE_SIZE( size_t size, rtems_attribute attributes ); .. rubric:: PARAMETERS: |