diff options
Diffstat (limited to '')
| -rw-r--r-- | c-user/task/directives.rst | 84 |
1 files changed, 45 insertions, 39 deletions
diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst index 05b035c..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: @@ -1162,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: @@ -1261,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: @@ -1474,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: @@ -1494,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: @@ -1515,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: @@ -1630,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: |