diff options
Diffstat (limited to 'c-user/task')
| -rw-r--r-- | c-user/task/background.rst | 54 | ||||
| -rw-r--r-- | c-user/task/deprecated-directives.rst | 2 | ||||
| -rw-r--r-- | c-user/task/directives.rst | 111 | ||||
| -rw-r--r-- | c-user/task/index.rst | 4 | ||||
| -rw-r--r-- | c-user/task/introduction.rst | 8 | ||||
| -rw-r--r-- | c-user/task/operations.rst | 18 | ||||
| -rw-r--r-- | c-user/task/removed-directives.rst | 10 |
7 files changed, 140 insertions, 67 deletions
diff --git a/c-user/task/background.rst b/c-user/task/background.rst index da6cabf..c7645b1 100644 --- a/c-user/task/background.rst +++ b/c-user/task/background.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Background @@ -233,6 +233,58 @@ the task will execute at interrupt level n. The set of default modes may be selected by specifying the ``RTEMS_DEFAULT_MODES`` constant. +.. index:: task life states + +Task Life States +---------------- + +Independent of the task state with respect to the scheduler, the task life is +determined by several orthogonal states: + +* *protected* or *unprotected* + +* *deferred life changes* or *no deferred life changes* + +* *restarting* or *not restarting* + +* *terminating* or *not terminating* + +* *detached* or *not detached* + +While the task life is *protected*, asynchronous task restart and termination +requests are blocked. A task may still restart or terminate itself. All tasks +are created with an unprotected task life. The task life protection is used by +the system to prevent system resources being affected by asynchronous task +restart and termination requests. The task life protection can be enabled +(``PTHREAD_CANCEL_DISABLE``) or disabled (``PTHREAD_CANCEL_ENABLE``) for the +calling task through the ``pthread_setcancelstate()`` directive. + +While *deferred life changes* are enabled, asynchronous task restart and +termination requests are delayed until the task performs a life change itself +or calls ``pthread_testcancel()``. Cancellation points are not implemented in +RTEMS. Deferred task life changes can be enabled (``PTHREAD_CANCEL_DEFERRED``) +or disabled (``PTHREAD_CANCEL_ASYNCHRONOUS``) for the calling task through the +``pthread_setcanceltype()`` directive. Classic API tasks are created with +deferred life changes disabled. POSIX threads are created with deferred life +changes enabled. + +A task is made *restarting* by issuing a task restart request through the +:ref:`InterfaceRtemsTaskRestart` directive. + +A task is made *terminating* by issuing a task termination request through the +:ref:`InterfaceRtemsTaskExit`, :ref:`InterfaceRtemsTaskDelete`, +``pthread_exit()``, and ``pthread_cancel()`` directives. + +When a *detached* task terminates, the termination procedure completes without +the need for another task to join with the terminated task. Classic API tasks +are created as not detached. The detached state of created POSIX threads is +determined by the thread attributes. They are created as not detached by +default. The calling task is made detached through the ``pthread_detach()`` +directive. The :ref:`InterfaceRtemsTaskExit` directive and self deletion +though :ref:`InterfaceRtemsTaskDelete` directive make the calling task +detached. In contrast, the ``pthread_exit()`` directive does not change the +detached state of the calling task. + .. index:: task arguments .. index:: task prototype diff --git a/c-user/task/deprecated-directives.rst b/c-user/task/deprecated-directives.rst index 107c5e0..949d499 100644 --- a/c-user/task/deprecated-directives.rst +++ b/c-user/task/deprecated-directives.rst @@ -9,7 +9,7 @@ Deprecated Directives \clearpage -.. index:: rtems_iterate_over_all_threads +.. index:: rtems_iterate_over_all_threads() .. _rtems_iterate_over_all_threads: diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst index 64b591d..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: @@ -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,9 +476,9 @@ 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: @@ -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: diff --git a/c-user/task/index.rst b/c-user/task/index.rst index afe8b76..f5e8a64 100644 --- a/c-user/task/index.rst +++ b/c-user/task/index.rst @@ -1,10 +1,10 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: tasks -.. _RTEMSAPIClassicTask: +.. _RTEMSAPIClassicTasks: Task Manager ************ diff --git a/c-user/task/introduction.rst b/c-user/task/introduction.rst index 5d6eba4..f174b42 100644 --- a/c-user/task/introduction.rst +++ b/c-user/task/introduction.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 @@ -84,8 +84,8 @@ and administer tasks. The directives provided by the Task Manager are: * :ref:`InterfaceRtemsTaskMode` - Gets and optionally sets the mode of the calling task. -* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after an interval in - :term:`clock ticks <clock tick>` or yields the processor. +* :ref:`InterfaceRtemsTaskWakeAfter` - Wakes up after a count of :term:`clock + ticks <clock tick>` have occurred or yields the processor. * :ref:`InterfaceRtemsTaskWakeWhen` - Wakes up when specified. diff --git a/c-user/task/operations.rst b/c-user/task/operations.rst index 58174d6..438eea5 100644 --- a/c-user/task/operations.rst +++ b/c-user/task/operations.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Operations @@ -75,9 +75,9 @@ Delaying the Currently Executing Task ------------------------------------- The ``rtems_task_wake_after`` directive creates a sleep timer which allows a -task to go to sleep for a specified interval. The task is blocked until the -delay interval has elapsed, at which time the task is unblocked. A task -calling the ``rtems_task_wake_after`` directive with a delay interval of +task to go to sleep for a specified count of clock ticks. The task is blocked +until the count of clock ticks has elapsed, at which time the task is unblocked. +A task calling the ``rtems_task_wake_after`` directive with a delay of ``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready task of equal or greater priority and remain ready to execute. @@ -160,8 +160,8 @@ 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. -.. index:: rtems_task_get_note -.. index:: rtems_task_set_note +.. index:: rtems_task_get_note() +.. index:: rtems_task_set_note() Transition Advice for Removed Notepads --------------------------------------- @@ -177,9 +177,9 @@ over the key (e.g. notepad index) selection. For most applications, POSIX Keys should be used. These are available in all RTEMS build configurations. It is also possible that thread-local storage (TLS) is an option for some use cases. -.. index:: rtems_task_variable_add -.. index:: rtems_task_variable_get -.. index:: rtems_task_variable_delete +.. index:: rtems_task_variable_add() +.. index:: rtems_task_variable_get() +.. index:: rtems_task_variable_delete() Transition Advice for Removed Task Variables --------------------------------------------- diff --git a/c-user/task/removed-directives.rst b/c-user/task/removed-directives.rst index 8c8aae9..677e810 100644 --- a/c-user/task/removed-directives.rst +++ b/c-user/task/removed-directives.rst @@ -10,7 +10,7 @@ Removed Directives \clearpage .. index:: get task notepad entry -.. index:: rtems_task_get_note +.. index:: rtems_task_get_note() .. _rtems_task_get_note: @@ -64,7 +64,7 @@ NOTES: \clearpage .. index:: set task notepad entry -.. index:: rtems_task_set_note +.. index:: rtems_task_set_note() .. _rtems_task_set_note: @@ -119,7 +119,7 @@ NOTES: .. index:: per-task variable .. index:: task private variable .. index:: task private data -.. index:: rtems_task_variable_add +.. index:: rtems_task_variable_add() .. _rtems_task_variable_add: @@ -182,7 +182,7 @@ NOTES: .. index:: get per-task variable .. index:: obtain per-task variable -.. index:: rtems_task_variable_get +.. index:: rtems_task_variable_get() .. _rtems_task_variable_get: @@ -241,7 +241,7 @@ NOTES: .. index:: per-task variable .. index:: task private variable .. index:: task private data -.. index:: rtems_task_variable_delete +.. index:: rtems_task_variable_delete() .. _rtems_task_variable_delete: |