summaryrefslogtreecommitdiffstats
path: root/c-user/task_manager.rst
diff options
context:
space:
mode:
Diffstat (limited to 'c-user/task_manager.rst')
-rw-r--r--c-user/task_manager.rst1650
1 files changed, 1650 insertions, 0 deletions
diff --git a/c-user/task_manager.rst b/c-user/task_manager.rst
new file mode 100644
index 0000000..449ca3c
--- /dev/null
+++ b/c-user/task_manager.rst
@@ -0,0 +1,1650 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
+Task Manager
+############
+
+.. index:: tasks
+
+Introduction
+============
+
+The task manager provides a comprehensive set of directives to create, delete,
+and administer tasks. The directives provided by the task manager are:
+
+- rtems_task_create_ - Create a task
+
+- rtems_task_ident_ - Get ID of a task
+
+- rtems_task_self_ - Obtain ID of caller
+
+- rtems_task_start_ - Start a task
+
+- rtems_task_restart_ - Restart a task
+
+- rtems_task_delete_ - Delete a task
+
+- rtems_task_suspend_ - Suspend a task
+
+- rtems_task_resume_ - Resume a task
+
+- rtems_task_is_suspended_ - Determine if a task is suspended
+
+- rtems_task_set_priority_ - Set task priority
+
+- rtems_task_mode_ - Change current task's mode
+
+- rtems_task_get_note_ - Get task notepad entry
+
+- rtems_task_set_note_ - Set task notepad entry
+
+- rtems_task_wake_after_ - Wake up after interval
+
+- rtems_task_wake_when_ - Wake up when specified
+
+- rtems_iterate_over_all_threads_ - Iterate Over Tasks
+
+- rtems_task_variable_add_ - Associate per task variable
+
+- rtems_task_variable_get_ - Obtain value of a a per task variable
+
+- rtems_task_variable_delete_ - Remove per task variable
+
+Background
+==========
+
+Task Definition
+---------------
+.. index:: task, definition
+
+Many definitions of a task have been proposed in computer literature.
+Unfortunately, none of these definitions encompasses all facets of the concept
+in a manner which is operating system independent. Several of the more common
+definitions are provided to enable each user to select a definition which best
+matches their own experience and understanding of the task concept:
+
+- a "dispatchable" unit.
+
+- an entity to which the processor is allocated.
+
+- an atomic unit of a real-time, multiprocessor system.
+
+- single threads of execution which concurrently compete for resources.
+
+- a sequence of closely related computations which can execute concurrently
+ with other computational sequences.
+
+From RTEMS' perspective, a task is the smallest thread of execution which can
+compete on its own for system resources. A task is manifested by the existence
+of a task control block (TCB).
+
+Task Control Block
+------------------
+
+The Task Control Block (TCB) is an RTEMS defined data structure which contains
+all the information that is pertinent to the execution of a task. During
+system initialization, RTEMS reserves a TCB for each task configured. A TCB is
+allocated upon creation of the task and is returned to the TCB free list upon
+deletion of the task.
+
+The TCB's elements are modified as a result of system calls made by the
+application in response to external and internal stimuli. TCBs are the only
+RTEMS internal data structure that can be accessed by an application via user
+extension routines. The TCB contains a task's name, ID, current priority,
+current and starting states, execution mode, TCB user extension pointer,
+scheduling control structures, as well as data required by a blocked task.
+
+A task's context is stored in the TCB when a task switch occurs. When the task
+regains control of the processor, its context is restored from the TCB. When a
+task is restarted, the initial state of the task is restored from the starting
+context area in the task's TCB.
+
+Task States
+-----------
+.. index:: task states
+
+A task may exist in one of the following five states:
+
+- *executing* - Currently scheduled to the CPU
+
+- *ready* - May be scheduled to the CPU
+
+- *blocked* - Unable to be scheduled to the CPU
+
+- *dormant* - Created task that is not started
+
+- *non-existent* - Uncreated or deleted task
+
+An active task may occupy the executing, ready, blocked or dormant state,
+otherwise the task is considered non-existent. One or more tasks may be active
+in the system simultaneously. Multiple tasks communicate, synchronize, and
+compete for system resources with each other via system calls. The multiple
+tasks appear to execute in parallel, but actually each is dispatched to the CPU
+for periods of time determined by the RTEMS scheduling algorithm. The
+scheduling of a task is based on its current state and priority.
+
+Task Priority
+-------------
+.. index:: task priority
+.. index:: priority, task
+.. index:: rtems_task_priority
+
+A task's priority determines its importance in relation to the other tasks
+executing on the same processor. RTEMS supports 255 levels of priority ranging
+from 1 to 255. The data type ``rtems_task_priority`` is used to store task
+priorities.
+
+Tasks of numerically smaller priority values are more important tasks than
+tasks of numerically larger priority values. For example, a task at priority
+level 5 is of higher privilege than a task at priority level 10. There is no
+limit to the number of tasks assigned to the same priority.
+
+Each task has a priority associated with it at all times. The initial value of
+this priority is assigned at task creation time. The priority of a task may be
+changed at any subsequent time.
+
+Priorities are used by the scheduler to determine which ready task will be
+allowed to execute. In general, the higher the logical priority of a task, the
+more likely it is to receive processor execution time.
+
+Task Mode
+---------
+.. index:: task mode
+.. index:: rtems_task_mode
+
+A task's execution mode is a combination of the following four components:
+
+- preemption
+
+- ASR processing
+
+- timeslicing
+
+- interrupt level
+
+It is used to modify RTEMS' scheduling process and to alter the execution
+environment of the task. The data type ``rtems_task_mode`` is used to manage
+the task execution mode.
+
+.. index:: preemption
+
+The preemption component allows a task to determine when control of the
+processor is relinquished. If preemption is disabled (``RTEMS_NO_PREEMPT``),
+the task will retain control of the processor as long as it is in the executing
+state - even if a higher priority task is made ready. If preemption is enabled
+(``RTEMS_PREEMPT``) and a higher priority task is made ready, then the
+processor will be taken away from the current task immediately and given to the
+higher priority task.
+
+.. index:: timeslicing
+
+The timeslicing component is used by the RTEMS scheduler to determine how the
+processor is allocated to tasks of equal priority. If timeslicing is enabled
+(``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can
+execute before the processor is allocated to another ready task of equal
+priority. The length of the timeslice is application dependent and specified in
+the Configuration Table. If timeslicing is disabled (``RTEMS_NO_TIMESLICE``),
+then the task will be allowed to execute until a task of higher priority is
+made ready. If ``RTEMS_NO_PREEMPT`` is selected, then the timeslicing component
+is ignored by the scheduler.
+
+The asynchronous signal processing component is used to determine when received
+signals are to be processed by the task. If signal processing is enabled
+(``RTEMS_ASR``), then signals sent to the task will be processed the next time
+the task executes. If signal processing is disabled (``RTEMS_NO_ASR``), then
+all signals received by the task will remain posted until signal processing is
+enabled. This component affects only tasks which have established a routine to
+process asynchronous signals.
+
+.. index:: interrupt level, task
+
+The interrupt level component is used to determine which interrupts will be
+enabled when the task is executing. ``RTEMS_INTERRUPT_LEVEL(n)`` specifies that
+the task will execute at interrupt level n.
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_PREEMPT``
+ - enable preemption (default)
+ * - ``RTEMS_NO_PREEMPT``
+ - disable preemption
+ * - ``RTEMS_NO_TIMESLICE``
+ - disable timeslicing (default)
+ * - ``RTEMS_TIMESLICE``
+ - enable timeslicing
+ * - ``RTEMS_ASR``
+ - enable ASR processing (default)
+ * - ``RTEMS_NO_ASR``
+ - disable ASR processing
+ * - ``RTEMS_INTERRUPT_LEVEL(0)``
+ - enable all interrupts (default)
+ * - ``RTEMS_INTERRUPT_LEVEL(n)``
+ - execute at interrupt level n
+
+The set of default modes may be selected by specifying the
+``RTEMS_DEFAULT_MODES`` constant.
+
+Accessing Task Arguments
+------------------------
+.. index:: task arguments
+.. index:: task prototype
+
+All RTEMS tasks are invoked with a single argument which is specified when they
+are started or restarted. The argument is commonly used to communicate startup
+information to the task. The simplest manner in which to define a task which
+accesses it argument is:
+
+.. index:: rtems_task
+
+.. code-block:: c
+
+ rtems_task user_task(
+ rtems_task_argument argument
+ );
+
+Application tasks requiring more information may view this single argument as
+an index into an array of parameter blocks.
+
+Floating Point Considerations
+-----------------------------
+.. index:: floating point
+
+Creating a task with the ``RTEMS_FLOATING_POINT`` attribute flag results in
+additional memory being allocated for the TCB to store the state of the numeric
+coprocessor during task switches. This additional memory is *NOT* allocated for
+``RTEMS_NO_FLOATING_POINT`` tasks. Saving and restoring the context of a
+``RTEMS_FLOATING_POINT`` task takes longer than that of a
+``RTEMS_NO_FLOATING_POINT`` task because of the relatively large amount of time
+required for the numeric coprocessor to save or restore its computational
+state.
+
+Since RTEMS was designed specifically for embedded military applications which
+are floating point intensive, the executive is optimized to avoid unnecessarily
+saving and restoring the state of the numeric coprocessor. The state of the
+numeric coprocessor is only saved when a ``RTEMS_FLOATING_POINT`` task is
+dispatched and that task was not the last task to utilize the coprocessor. In
+a system with only one ``RTEMS_FLOATING_POINT`` task, the state of the numeric
+coprocessor will never be saved or restored.
+
+Although the overhead imposed by ``RTEMS_FLOATING_POINT`` tasks is minimal,
+some applications may wish to completely avoid the overhead associated with
+``RTEMS_FLOATING_POINT`` tasks and still utilize a numeric coprocessor. By
+preventing a task from being preempted while performing a sequence of floating
+point operations, a ``RTEMS_NO_FLOATING_POINT`` task can utilize the numeric
+coprocessor without incurring the overhead of a ``RTEMS_FLOATING_POINT``
+context switch. This approach also avoids the allocation of a floating point
+context area. However, if this approach is taken by the application designer,
+NO tasks should be created as ``RTEMS_FLOATING_POINT`` tasks. Otherwise, the
+floating point context will not be correctly maintained because RTEMS assumes
+that the state of the numeric coprocessor will not be altered by
+``RTEMS_NO_FLOATING_POINT`` tasks.
+
+If the supported processor type does not have hardware floating capabilities or
+a standard numeric coprocessor, RTEMS will not provide built-in support for
+hardware floating point on that processor. In this case, all tasks are
+considered ``RTEMS_NO_FLOATING_POINT`` whether created as
+``RTEMS_FLOATING_POINT`` or ``RTEMS_NO_FLOATING_POINT`` tasks. A floating
+point emulation software library must be utilized for floating point
+operations.
+
+On some processors, it is possible to disable the floating point unit
+dynamically. If this capability is supported by the target processor, then
+RTEMS will utilize this capability to enable the floating point unit only for
+tasks which are created with the ``RTEMS_FLOATING_POINT`` attribute. The
+consequence of a ``RTEMS_NO_FLOATING_POINT`` task attempting to access the
+floating point unit is CPU dependent but will generally result in an exception
+condition.
+
+Per Task Variables
+------------------
+.. index:: per task variables
+
+Per task variables are deprecated, see the warning below.
+
+Per task variables are used to support global variables whose value may be
+unique to a task. After indicating that a variable should be treated as private
+(i.e. per-task) the task can access and modify the variable, but the
+modifications will not appear to other tasks, and other tasks' modifications to
+that variable will not affect the value seen by the task. This is accomplished
+by saving and restoring the variable's value each time a task switch occurs to
+or from the calling task.
+
+The value seen by other tasks, including those which have not added the
+variable to their set and are thus accessing the variable as a common location
+shared among tasks, cannot be affected by a task once it has added a variable
+to its local set. Changes made to the variable by other tasks will not affect
+the value seen by a task which has added the variable to its private set.
+
+This feature can be used when a routine is to be spawned repeatedly as several
+independent tasks. Although each task will have its own stack, and thus
+separate stack variables, they will all share the same static and global
+variables. To make a variable not shareable (i.e. a "global" variable that is
+specific to a single task), the tasks can call ``rtems_task_variable_add`` to
+make a separate copy of the variable for each task, but all at the same
+physical address.
+
+Task variables increase the context switch time to and from the tasks that own
+them so it is desirable to minimize the number of task variables. One
+efficient method is to have a single task variable that is a pointer to a
+dynamically allocated structure containing the task's private "global" data.
+
+A critical point with per-task variables is that each task must separately
+request that the same global variable is per-task private.
+
+.. warning:
+
+ Per-Task variables are inherently broken on SMP systems. They only work
+ correctly when there is one task executing in the system and that task is the
+ logical owner of the value in the per-task variable's location. There is no
+ way for a single memory image to contain the correct value for each task
+ executing on each core. Consequently, per-task variables are disabled in SMP
+ configurations of RTEMS. Instead the application developer should consider
+ the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys are not
+ enabled in all RTEMS configurations.
+
+Building a Task Attribute Set
+-----------------------------
+.. index:: task attributes, building
+
+In general, an attribute set is built by a bitwise OR of the desired
+components. The set of valid task attribute components is listed below:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_NO_FLOATING_POINT``
+ - does not use coprocessor (default)
+ * - ``RTEMS_FLOATING_POINT``
+ - uses numeric coprocessor
+ * - ``RTEMS_LOCAL``
+ - local task (default)
+ * - ``RTEMS_GLOBAL``
+ - global task
+
+Attribute values are specifically designed to be mutually exclusive, therefore
+bitwise OR and addition operations are equivalent as long as each attribute
+appears exactly once in the component list. A component listed as a default is
+not required to appear in the component list, although it is a good programming
+practice to specify default components. If all defaults are desired, then
+``RTEMS_DEFAULT_ATTRIBUTES`` should be used.
+
+This example demonstrates the attribute_set parameter needed to create a local
+task which utilizes the numeric coprocessor. The attribute_set parameter could
+be ``RTEMS_FLOATING_POINT`` or ``RTEMS_LOCAL | RTEMS_FLOATING_POINT``. The
+attribute_set parameter can be set to ``RTEMS_FLOATING_POINT`` because
+``RTEMS_LOCAL`` is the default for all created tasks. If the task were global
+and used the numeric coprocessor, then the attribute_set parameter would be
+``RTEMS_GLOBAL | RTEMS_FLOATING_POINT``.
+
+Building a Mode and Mask
+------------------------
+.. index:: task mode, building
+
+In general, a mode and its corresponding mask is built by a bitwise OR of the
+desired components. The set of valid mode constants and each mode's
+corresponding mask constant is listed below:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_PREEMPT``
+ - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
+ * - ``RTEMS_NO_PREEMPT``
+ - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
+ * - ``RTEMS_NO_TIMESLICE``
+ - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
+ * - ``RTEMS_TIMESLICE``
+ - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
+ * - ``RTEMS_ASR``
+ - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
+ * - ``RTEMS_NO_ASR``
+ - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
+ * - ``RTEMS_INTERRUPT_LEVEL(0)``
+ - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
+ * - ``RTEMS_INTERRUPT_LEVEL(n)``
+ - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
+
+Mode values are specifically designed to be mutually exclusive, therefore
+bitwise OR and addition operations are equivalent as long as each mode appears
+exactly once in the component list. A mode component listed as a default is
+not required to appear in the mode component list, although it is a good
+programming practice to specify default components. If all defaults are
+desired, the mode ``RTEMS_DEFAULT_MODES`` and the mask ``RTEMS_ALL_MODE_MASKS``
+should be used.
+
+The following example demonstrates the mode and mask parameters used with the
+``rtems_task_mode`` directive to place a task at interrupt level 3 and make it
+non-preemptible. The mode should be set to ``RTEMS_INTERRUPT_LEVEL(3) |
+RTEMS_NO_PREEMPT`` to indicate the desired preemption mode and interrupt level,
+while the mask parameter should be set to ``RTEMS_INTERRUPT_MASK |
+RTEMS_NO_PREEMPT_MASK`` to indicate that the calling task's interrupt level and
+preemption mode are being altered.
+
+Operations
+==========
+
+Creating Tasks
+--------------
+
+The ``rtems_task_create`` directive creates a task by allocating a task control
+block, assigning the task a user-specified name, allocating it a stack and
+floating point context area, setting a user-specified initial priority, setting
+a user-specified initial mode, and assigning it a task ID. Newly created tasks
+are initially placed in the dormant state. All RTEMS tasks execute in the most
+privileged mode of the processor.
+
+Obtaining Task IDs
+------------------
+
+When a task is created, RTEMS generates a unique task ID and assigns it to the
+created task until it is deleted. The task ID may be obtained by either of two
+methods. First, as the result of an invocation of the ``rtems_task_create``
+directive, the task ID is stored in a user provided location. Second, the task
+ID may be obtained later using the ``rtems_task_ident`` directive. The task ID
+is used by other directives to manipulate this task.
+
+Starting and Restarting Tasks
+-----------------------------
+
+The ``rtems_task_start`` directive is used to place a dormant task in the ready
+state. This enables the task to compete, based on its current priority, for
+the processor and other system resources. Any actions, such as suspension or
+change of priority, performed on a task prior to starting it are nullified when
+the task is started.
+
+With the ``rtems_task_start`` directive the user specifies the task's starting
+address and argument. The argument is used to communicate some startup
+information to the task. As part of this directive, RTEMS initializes the
+task's stack based upon the task's initial execution mode and start address.
+The starting argument is passed to the task in accordance with the target
+processor's calling convention.
+
+The ``rtems_task_restart`` directive restarts a task at its initial starting
+address with its original priority and execution mode, but with a possibly
+different argument. The new argument may be used to distinguish between the
+original invocation of the task and subsequent invocations. The task's stack
+and control block are modified to reflect their original creation values.
+Although references to resources that have been requested are cleared,
+resources allocated by the task are NOT automatically returned to RTEMS. A
+task cannot be restarted unless it has previously been started (i.e. dormant
+tasks cannot be restarted). All restarted tasks are placed in the ready state.
+
+Suspending and Resuming Tasks
+-----------------------------
+
+The ``rtems_task_suspend`` directive is used to place either the caller or
+another task into a suspended state. The task remains suspended until a
+``rtems_task_resume`` directive is issued. This implies that a task may be
+suspended as well as blocked waiting either to acquire a resource or for the
+expiration of a timer.
+
+The ``rtems_task_resume`` directive is used to remove another task from the
+suspended state. If the task is not also blocked, resuming it will place it in
+the ready state, allowing it to once again compete for the processor and
+resources. If the task was blocked as well as suspended, this directive clears
+the suspension and leaves the task in the blocked state.
+
+Suspending a task which is already suspended or resuming a task which is not
+suspended is considered an error. The ``rtems_task_is_suspended`` can be used
+to determine if a task is currently suspended.
+
+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
+``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready
+task of equal or greater priority and remain ready to execute.
+
+The ``rtems_task_wake_when`` directive creates a sleep timer which allows a
+task to go to sleep until a specified date and time. The calling task is
+blocked until the specified date and time has occurred, at which time the task
+is unblocked.
+
+Changing Task Priority
+----------------------
+
+The ``rtems_task_set_priority`` directive is used to obtain or change the
+current priority of either the calling task or another task. If the new
+priority requested is ``RTEMS_CURRENT_PRIORITY`` or the task's actual priority,
+then the current priority will be returned and the task's priority will remain
+unchanged. If the task's priority is altered, then the task will be scheduled
+according to its new priority.
+
+The ``rtems_task_restart`` directive resets the priority of a task to its
+original value.
+
+Changing Task Mode
+------------------
+
+The ``rtems_task_mode`` directive is used to obtain or change the current
+execution mode of the calling task. A task's execution mode is used to enable
+preemption, timeslicing, ASR processing, and to set the task's interrupt level.
+
+The ``rtems_task_restart`` directive resets the mode of a task to its original
+value.
+
+Notepad Locations
+-----------------
+
+RTEMS provides sixteen notepad locations for each task. Each notepad
+location may contain a note consisting of four bytes of information.
+RTEMS provides two directives, ``rtems_task_set_note`` and
+``rtems_task_get_note``, that enable a user to access and change
+the notepad locations. The ``rtems_task_set_note`` directive
+enables the user to set a task's notepad entry to a specified note.
+The ``rtems_task_get_note`` directive allows the user to obtain the note
+contained in any one of the sixteen notepads of a specified task.
+
+Task Deletion
+-------------
+
+RTEMS provides the ``rtems_task_delete`` directive to allow a task to delete
+itself or any other task. This directive removes all RTEMS references to the
+task, frees the task's control block, removes it from resource wait queues, and
+deallocates its stack as well as the optional floating point context. The
+task's name and ID become inactive at this time, and any subsequent references
+to either of them is invalid. In fact, RTEMS may reuse the task ID for another
+task which is created later in the application.
+
+Unexpired delay timers (i.e. those used by ``rtems_task_wake_after`` and
+``rtems_task_wake_when``) and timeout timers associated with the task are
+automatically deleted, however, other resources dynamically allocated by the
+task are NOT automatically returned to RTEMS. Therefore, before a task is
+deleted, all of its dynamically allocated resources should be deallocated by
+the user. This may be accomplished by instructing the task to delete itself
+rather than directly deleting the task. Other tasks may instruct a task to
+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.
+
+Transition Advice for Obsolete Directives
+-----------------------------------------
+
+Notepads
+~~~~~~~~
+.. index:: rtems_task_get_note
+.. index:: rtems_task_set_note
+
+Task notepads and the associated directives ``rtems_task_get_note`` and
+``rtems_task_set_note`` were removed after the 4.11 Release Series. These were
+never thread-safe to access and subject to conflicting use of the notepad index
+by libraries which were designed independently.
+
+It is recommended that applications be modified to use services which are
+thread safe and not subject to issues with multiple applications conflicting
+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 is an option for some use cases.
+
+Directives
+==========
+
+This section details the task manager's directives. A subsection is dedicated
+to each of this manager's directives and describes the calling sequence,
+related constants, usage, and status codes.
+
+.. _rtems_task_create:
+
+TASK_CREATE - Create a task
+---------------------------
+.. index:: create a task
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_create
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_create(
+ rtems_name name,
+ rtems_task_priority initial_priority,
+ size_t stack_size,
+ rtems_mode initial_modes,
+ rtems_attribute attribute_set,
+ rtems_id *id
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task created successfully
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``id`` is NULL
+ * - ``RTEMS_INVALID_NAME``
+ - invalid task name
+ * - ``RTEMS_INVALID_PRIORITY``
+ - invalid task priority
+ * - ``RTEMS_MP_NOT_CONFIGURED``
+ - multiprocessing not configured
+ * - ``RTEMS_TOO_MANY``
+ - too many tasks created
+ * - ``RTEMS_UNSATISFIED``
+ - not enough memory for stack/FP context
+ * - ``RTEMS_TOO_MANY``
+ - too many global objects
+
+**DESCRIPTION:**
+
+This directive creates a task which resides on the local node. It allocates
+and initializes a TCB, a stack, and an optional floating point context area.
+The mode parameter contains values which sets the task's initial execution
+mode. The ``RTEMS_FLOATING_POINT`` attribute should be specified if the
+created task is to use a numeric coprocessor. For performance reasons, it is
+recommended that tasks not using the numeric coprocessor should specify the
+``RTEMS_NO_FLOATING_POINT`` attribute. If the ``RTEMS_GLOBAL`` attribute is
+specified, the task can be accessed from remote nodes. The task id, returned
+in id, is used in other task related directives to access the task. When
+created, a task is placed in the dormant state and can only be made ready to
+execute using the directive ``rtems_task_start``.
+
+**NOTES:**
+
+This directive will not cause the calling task to be preempted.
+
+Valid task priorities range from a high of 1 to a low of 255.
+
+If the requested stack size is less than the configured minimum stack size,
+then RTEMS will use the configured minimum as the stack size for this task. In
+addition to being able to specify the task stack size as a integer, there are
+two constants which may be specified:
+
+``RTEMS_MINIMUM_STACK_SIZE``
+ The minimum stack size *RECOMMENDED* for use on this processor. This value
+ is selected by the RTEMS developers conservatively to minimize the risk of
+ blown stacks for most user applications. Using this constant when specifying
+ the task stack size, indicates that the stack size will be at least
+ ``RTEMS_MINIMUM_STACK_SIZE`` bytes in size. If the user configured minimum
+ stack size is larger than the recommended minimum, then it will be used.
+
+``RTEMS_CONFIGURED_MINIMUM_STACK_SIZE``
+ Indicates this task is to be created with a stack size of the minimum stack
+ size that was configured by the application. If not explicitly configured by
+ the application, the default configured minimum stack size is the processor
+ dependent value ``RTEMS_MINIMUM_STACK_SIZE``. Since this uses the configured
+ minimum stack size value, you may get a stack size that is smaller or larger
+ than the recommended minimum. This can be used to provide large stacks for
+ all tasks on complex applications or small stacks on applications that are
+ trying to conserve memory.
+
+Application developers should consider the stack usage of the device drivers
+when calculating the stack size required for tasks which utilize the driver.
+
+The following task attribute constants are defined by RTEMS:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_NO_FLOATING_POINT``
+ - does not use coprocessor (default)
+ * - ``RTEMS_FLOATING_POINT``
+ - uses numeric coprocessor
+ * - ``RTEMS_LOCAL``
+ - local task (default)
+ * - ``RTEMS_GLOBAL``
+ - global task
+
+The following task mode constants are defined by RTEMS:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_PREEMPT``
+ - enable preemption (default)
+ * - ``RTEMS_NO_PREEMPT``
+ - disable preemption
+ * - ``RTEMS_NO_TIMESLICE``
+ - disable timeslicing (default)
+ * - ``RTEMS_TIMESLICE``
+ - enable timeslicing
+ * - ``RTEMS_ASR``
+ - enable ASR processing (default)
+ * - ``RTEMS_NO_ASR``
+ - disable ASR processing
+ * - ``RTEMS_INTERRUPT_LEVEL(0)``
+ - enable all interrupts (default)
+ * - ``RTEMS_INTERRUPT_LEVEL(n)``
+ - execute at interrupt level n
+
+The interrupt level portion of the task execution mode supports a maximum of
+256 interrupt levels. These levels are mapped onto the interrupt levels
+actually supported by the target processor in a processor dependent fashion.
+
+Tasks should not be made global unless remote tasks must interact with them.
+This avoids the system overhead incurred by the creation of a global task.
+When a global task is created, the task's name and id must be transmitted to
+every node in the system for insertion in the local copy of the global object
+table.
+
+The total number of global objects, including tasks, is limited by the
+maximum_global_objects field in the Configuration Table.
+
+.. _rtems_task_ident:
+
+TASK_IDENT - Get ID of a task
+-----------------------------
+.. index:: get ID of a task
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_ident
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_ident(
+ rtems_name name,
+ uint32_t node,
+ rtems_id *id
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task identified successfully
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``id`` is NULL
+ * - ``RTEMS_INVALID_NAME``
+ - invalid task name
+ * - ``RTEMS_INVALID_NODE``
+ - invalid node id
+
+**DESCRIPTION:**
+
+This directive obtains the task id associated with the task name specified in
+name. A task may obtain its own id by specifying ``RTEMS_SELF`` or its own
+task name in name. If the task name is not unique, then the task id returned
+will match one of the tasks with that name. However, this task id is not
+guaranteed to correspond to the desired task. The task id, returned in id, is
+used in other task related directives to access the task.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the local
+node being searched first. All other nodes are searched with the lowest
+numbered node searched first.
+
+If node is a valid node number which does not represent the local node, then
+only the tasks exported by the designated node are searched.
+
+This directive does not generate activity on remote nodes. It accesses only
+the local copy of the global object table.
+
+.. _rtems_task_self:
+
+TASK_SELF - Obtain ID of caller
+-------------------------------
+.. index:: obtain ID of caller
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_self
+
+.. code-block:: c
+
+ rtems_id rtems_task_self(void);
+
+**DIRECTIVE STATUS CODES:**
+
+Returns the object Id of the calling task.
+
+**DESCRIPTION:**
+
+This directive returns the Id of the calling task.
+
+**NOTES:**
+
+If called from an interrupt service routine, this directive will return the Id
+of the interrupted task.
+
+.. _rtems_task_start:
+
+TASK_START - Start a task
+-------------------------
+.. index:: starting a task
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_start
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_start(
+ rtems_id id,
+ rtems_task_entry entry_point,
+ rtems_task_argument argument
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - ask started successfully
+ * - ``RTEMS_INVALID_ADDRESS``
+ - invalid task entry point
+ * - ``RTEMS_INVALID_ID``
+ - invalid task id
+ * - ``RTEMS_INCORRECT_STATE``
+ - task not in the dormant state
+ * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
+ - cannot start remote task
+
+**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
+starting address of the task is given in ``entry_point``. The task's starting
+argument is contained in argument. This argument can be a single value or used
+as an index into an array of parameter blocks. The type of this numeric
+argument is an unsigned integer type with the property that any valid pointer
+to void can be converted to this type and then converted back to a pointer to
+void. The result will compare equal to the original pointer.
+
+**NOTES:**
+
+The calling task will be preempted if its preemption mode is enabled and the
+task being started has a higher priority.
+
+Any actions performed on a dormant task such as suspension or change of
+priority are nullified when the task is initiated via the ``rtems_task_start``
+directive.
+
+.. _rtems_task_restart:
+
+TASK_RESTART - Restart a task
+-----------------------------
+.. index:: restarting a task
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_restart
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_restart(
+ rtems_id id,
+ rtems_task_argument argument
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task restarted successfully
+ * - ``RTEMS_INVALID_ID``
+ - task id invalid
+ * - ``RTEMS_INCORRECT_STATE``
+ - task never started
+ * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
+ - cannot restart remote task
+
+**DESCRIPTION:**
+
+This directive resets the task specified by id to begin execution at its
+original starting address. The task's priority and execution mode are set to
+the original creation values. If the task is currently blocked, RTEMS
+automatically makes the task ready. A task can be restarted from any state,
+except the dormant state.
+
+The task's starting argument is contained in argument. This argument can be a
+single value or an index into an array of parameter blocks. The type of this
+numeric argument is an unsigned integer type with the property that any valid
+pointer to void can be converted to this type and then converted back to a
+pointer to void. The result will compare equal to the original pointer. This
+new argument may be used to distinguish between the initial
+``rtems_task_start`` of the task and any ensuing calls to
+``rtems_task_restart`` of the task. This can be beneficial in deleting a task.
+Instead of deleting a task using the ``rtems_task_delete`` directive, a task
+can delete another task by restarting that task, and allowing that task to
+release resources back to RTEMS and then delete itself.
+
+**NOTES:**
+
+If id is ``RTEMS_SELF``, the calling task will be restarted and will not return
+from this directive.
+
+The calling task will be preempted if its preemption mode is enabled and the
+task being restarted has a higher priority.
+
+The task must reside on the local node, even if the task was created with the
+``RTEMS_GLOBAL`` option.
+
+.. _rtems_task_delete:
+
+TASK_DELETE - Delete a task
+---------------------------
+.. index:: deleting a task
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_delete
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_delete(
+ rtems_id id
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task deleted successfully
+ * - ``RTEMS_INVALID_ID``
+ - task id invalid
+ * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
+ - cannot restart remote task
+
+**DESCRIPTION:**
+
+This directive deletes a task, either the calling task or another task, as
+specified by id. 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
+``RTEMS_FLOATING_POINT``, its floating point context area. RTEMS does not
+reclaim the following resources: region segments, partition buffers,
+semaphores, timers, or rate monotonic periods.
+
+**NOTES:**
+
+A task is responsible for releasing its resources back to RTEMS before
+deletion. To insure proper deallocation of resources, a task should not be
+deleted unless it is unable to execute or does not hold any RTEMS resources.
+If a task holds RTEMS resources, the task should be allowed to deallocate its
+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 (``RTEMS_SELF``) will force RTEMS to select
+another task to execute.
+
+When a global task is deleted, the task id must be transmitted to every node in
+the system for deletion from the local copy of the global object table.
+
+The task must reside on the local node, even if the task was created with the
+``RTEMS_GLOBAL`` option.
+
+.. _rtems_task_suspend:
+
+TASK_SUSPEND - Suspend a task
+-----------------------------
+.. index:: suspending a task
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_suspend
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_suspend(
+ rtems_id id
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task suspended successfully
+ * - ``RTEMS_INVALID_ID``
+ - task id invalid
+ * - ``RTEMS_ALREADY_SUSPENDED``
+ - task already suspended
+
+**DESCRIPTION:**
+
+This directive suspends the task specified by id from further execution by
+placing it in the suspended state. This state is additive to any other blocked
+state that the task may already be in. The task will not execute again until
+another task issues the ``rtems_task_resume`` directive for this task and any
+blocked state has been removed.
+
+**NOTES:**
+
+The requesting task can suspend itself by specifying ``RTEMS_SELF`` as id. In
+this case, the task will be suspended and a successful return code will be
+returned when the task is resumed.
+
+Suspending a global task which does not reside on the local node will generate
+a request to the remote node to suspend the specified task.
+
+If the task specified by id is already suspended, then the
+``RTEMS_ALREADY_SUSPENDED`` status code is returned.
+
+.. _rtems_task_resume:
+
+TASK_RESUME - Resume a task
+---------------------------
+.. index:: resuming a task
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_resume
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_resume(
+ rtems_id id
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task resumed successfully
+ * - ``RTEMS_INVALID_ID``
+ - task id invalid
+ * - ``RTEMS_INCORRECT_STATE``
+ - task not suspended
+
+**DESCRIPTION:**
+
+This directive removes the task specified by id from the suspended state. If
+the task is in the ready state after the suspension is removed, then it will be
+scheduled to run. If the task is still in a blocked state after the suspension
+is removed, then it will remain in that blocked state.
+
+**NOTES:**
+
+The running task may be preempted if its preemption mode is enabled and the
+local task being resumed has a higher priority.
+
+Resuming a global task which does not reside on the local node will generate a
+request to the remote node to resume the specified task.
+
+If the task specified by id is not suspended, then the
+``RTEMS_INCORRECT_STATE`` status code is returned.
+
+.. _rtems_task_is_suspended:
+
+TASK_IS_SUSPENDED - Determine if a task is Suspended
+----------------------------------------------------
+.. index:: is task suspended
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_is_suspended
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_is_suspended(
+ rtems_id id
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task is NOT suspended
+ * - ``RTEMS_ALREADY_SUSPENDED``
+ - task is currently suspended
+ * - ``RTEMS_INVALID_ID``
+ - task id invalid
+ * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
+ - not supported on remote tasks
+
+**DESCRIPTION:**
+
+This directive returns a status code indicating whether or not the specified
+task is currently suspended.
+
+**NOTES:**
+
+This operation is not currently supported on remote tasks.
+
+.. _rtems_task_set_priority:
+
+TASK_SET_PRIORITY - Set task priority
+-------------------------------------
+.. index:: rtems_task_set_priority
+.. index:: current task priority
+.. index:: set task priority
+.. index:: get task priority
+.. index:: obtain task priority
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_set_priority(
+ rtems_id id,
+ rtems_task_priority new_priority,
+ rtems_task_priority *old_priority
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task priority set successfully
+ * - ``RTEMS_INVALID_ID``
+ - invalid task id
+ * - ``RTEMS_INVALID_ADDRESS``
+ - invalid return argument pointer
+ * - ``RTEMS_INVALID_PRIORITY``
+ - invalid task priority
+
+**DESCRIPTION:**
+
+This directive manipulates the priority of the task specified by id. An id of
+``RTEMS_SELF`` is used to indicate the calling task. When new_priority is not
+equal to ``RTEMS_CURRENT_PRIORITY``, the specified task's previous priority is
+returned in old_priority. When new_priority is ``RTEMS_CURRENT_PRIORITY``, the
+specified task's current priority is returned in old_priority. Valid
+priorities range from a high of 1 to a low of 255.
+
+**NOTES:**
+
+The calling task may be preempted if its preemption mode is enabled and it
+lowers its own priority or raises another task's priority.
+
+In case the new priority equals the current priority of the task, then nothing
+happens.
+
+Setting the priority of a global task which does not reside on the local node
+will generate a request to the remote node to change the priority of the
+specified task.
+
+If the task specified by id is currently holding any binary semaphores which
+use the priority inheritance algorithm, then the task's priority cannot be
+lowered immediately. If the task's priority were lowered immediately, then
+priority inversion results. The requested lowering of the task's priority will
+occur when the task has released all priority inheritance binary semaphores.
+The task's priority can be increased regardless of the task's use of priority
+inheritance binary semaphores.
+
+.. _rtems_task_mode:
+
+TASK_MODE - Change the current task mode
+----------------------------------------
+.. index:: current task mode
+.. index:: set task mode
+.. index:: get task mode
+.. index:: set task preemption mode
+.. index:: get task preemption mode
+.. index:: obtain task mode
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_mode
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_mode(
+ rtems_mode mode_set,
+ rtems_mode mask,
+ rtems_mode *previous_mode_set
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - task mode set successfully
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``previous_mode_set`` is NULL
+
+**DESCRIPTION:**
+
+This directive manipulates the execution mode of the calling task. A task's
+execution mode enables and disables preemption, timeslicing, asynchronous
+signal processing, as well as specifying the current interrupt level. To
+modify an execution mode, the mode class(es) to be changed must be specified in
+the mask parameter and the desired mode(s) must be specified in the mode
+parameter.
+
+**NOTES:**
+
+The calling task will be preempted if it enables preemption and a higher
+priority task is ready to run.
+
+Enabling timeslicing has no effect if preemption is disabled. For a task to be
+timesliced, that task must have both preemption and timeslicing enabled.
+
+A task can obtain its current execution mode, without modifying it, by calling
+this directive with a mask value of ``RTEMS_CURRENT_MODE``.
+
+To temporarily disable the processing of a valid ASR, a task should call this
+directive with the ``RTEMS_NO_ASR`` indicator specified in mode.
+
+The set of task mode constants and each mode's corresponding mask constant is
+provided in the following table:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_PREEMPT``
+ - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
+ * - ``RTEMS_NO_PREEMPT``
+ - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
+ * - ``RTEMS_NO_TIMESLICE``
+ - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
+ * - ``RTEMS_TIMESLICE``
+ - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
+ * - ``RTEMS_ASR``
+ - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
+ * - ``RTEMS_NO_ASR``
+ - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
+ * - ``RTEMS_INTERRUPT_LEVEL(0)``
+ - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
+ * - ``RTEMS_INTERRUPT_LEVEL(n)``
+ - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
+
+.. _rtems_task_get_note:
+
+TASK_GET_NOTE - Get task notepad entry
+--------------------------------------
+.. index:: get task notepad entry
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_get_note
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_get_note(
+ rtems_id id,
+ uint32_t notepad,
+ uint32_t *note
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - note value obtained successfully
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``note`` parameter is NULL
+ * - ``RTEMS_INVALID_ID``
+ - invalid task id
+ * - ``RTEMS_INVALID_NUMBER``
+ - invalid notepad location
+
+**DESCRIPTION:**
+
+This directive returns the note contained in the notepad location of
+the task specified by id.
+
+**NOTES:**
+
+This directive will not cause the running task to be preempted.
+
+If id is set to ``RTEMS_SELF``, the calling task accesses its own notepad.
+
+The sixteen notepad locations can be accessed using the constants
+``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``.
+
+Getting a note of a global task which does not reside on the
+local node will generate a request to the remote node to obtain
+the notepad entry of the specified task.
+
+.. _rtems_task_set_note:
+
+TASK_SET_NOTE - Set task notepad entry
+--------------------------------------
+.. index:: set task notepad entry
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_set_note
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_set_note(
+ rtems_id id,
+ uint32_t notepad,
+ uint32_t note
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - note set successfully
+ * - ``RTEMS_INVALID_ID``
+ - invalid task id
+ * - ``RTEMS_INVALID_NUMBER``
+ - invalid notepad location
+
+**DESCRIPTION:**
+
+This directive sets the notepad entry for the task specified by
+id to the value note.
+
+**NOTES:**
+
+If ``id`` is set to ``RTEMS_SELF``, the calling task accesses its own notepad.
+
+This directive will not cause the running task to be preempted.
+
+The sixteen notepad locations can be accessed using the constants
+``RTEMS_NOTEPAD_0`` through ``RTEMS_NOTEPAD_15``.
+
+Setting a note of a global task which does not reside on the
+local node will generate a request to the remote node to set
+the notepad entry of the specified task.
+
+.. _rtems_task_wake_after:
+
+TASK_WAKE_AFTER - Wake up after interval
+----------------------------------------
+.. index:: delay a task for an interval
+.. index:: wake up after an interval
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_wake_after
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_wake_after(
+ rtems_interval ticks
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - always successful
+
+**DESCRIPTION:**
+
+This directive blocks the calling task for the specified number of system clock
+ticks. When the requested interval has elapsed, the task is made ready. The
+``rtems_clock_tick`` directive automatically updates the delay period.
+
+**NOTES:**
+
+Setting the system date and time with the ``rtems_clock_set`` directive has no
+effect on a ``rtems_task_wake_after`` blocked task.
+
+A task may give up the processor and remain in the ready state by specifying a
+value of ``RTEMS_YIELD_PROCESSOR`` in ticks.
+
+The maximum timer interval that can be specified is the maximum value which can
+be represented by the uint32_t type.
+
+A clock tick is required to support the functionality of this directive.
+
+.. _rtems_task_wake_when:
+
+TASK_WAKE_WHEN - Wake up when specified
+---------------------------------------
+.. index:: delay a task until a wall time
+.. index:: wake up at a wall time
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_wake_when
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_wake_when(
+ rtems_time_of_day *time_buffer
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - awakened at date/time successfully
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``time_buffer`` is NULL
+ * - ``RTEMS_INVALID_TIME_OF_DAY``
+ - invalid time buffer
+ * - ``RTEMS_NOT_DEFINED``
+ - system date and time is not set
+
+**DESCRIPTION:**
+
+This directive blocks a task until the date and time specified in time_buffer.
+At the requested date and time, the calling task will be unblocked and made
+ready to execute.
+
+**NOTES:**
+
+The ticks portion of time_buffer structure is ignored. The timing granularity
+of this directive is a second.
+
+A clock tick is required to support the functionality of this directive.
+
+.. _rtems_iterate_over_all_threads:
+
+ITERATE_OVER_ALL_THREADS - Iterate Over Tasks
+---------------------------------------------
+.. index:: iterate over all threads
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_iterate_over_all_threads
+
+.. code-block:: c
+
+ typedef void (*rtems_per_thread_routine)(Thread_Control *the_thread);
+ void rtems_iterate_over_all_threads(
+ rtems_per_thread_routine routine
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+NONE
+
+**DESCRIPTION:**
+
+This directive iterates over all of the existant threads in the system and
+invokes ``routine`` on each of them. The user should be careful in accessing
+the contents of ``the_thread``.
+
+This routine is intended for use in diagnostic utilities and is not intented
+for routine use in an operational system.
+
+**NOTES:**
+
+There is NO protection while this routine is called. Thus it is possible that
+``the_thread`` could be deleted while this is operating. By not having
+protection, the user is free to invoke support routines from the C Library
+which require semaphores for data structures.
+
+.. _rtems_task_variable_add:
+
+TASK_VARIABLE_ADD - Associate per task variable
+-----------------------------------------------
+.. index:: per-task variable
+.. index:: task private variable
+.. index:: task private data
+
+.. warning::
+
+ This directive is deprecated and task variables will be removed.
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_variable_add
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_variable_add(
+ rtems_id tid,
+ void **task_variable,
+ void (*dtor)(void *)
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - per task variable added successfully
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``task_variable`` is NULL
+ * - ``RTEMS_INVALID_ID``
+ - invalid task id
+ * - ``RTEMS_NO_MEMORY``
+ - invalid task id
+ * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
+ - not supported on remote tasks
+
+**DESCRIPTION:**
+
+This directive adds the memory location specified by the ptr argument to the
+context of the given task. The variable will then be private to the task. The
+task can access and modify the variable, but the modifications will not appear
+to other tasks, and other tasks' modifications to that variable will not affect
+the value seen by the task. This is accomplished by saving and restoring the
+variable's value each time a task switch occurs to or from the calling task.
+If the dtor argument is non-NULL it specifies the address of a 'destructor'
+function which will be called when the task is deleted. The argument passed to
+the destructor function is the task's value of the variable.
+
+**NOTES:**
+
+Task variables increase the context switch time to and from the tasks that own
+them so it is desirable to minimize the number of task variables. One
+efficient method is to have a single task variable that is a pointer to a
+dynamically allocated structure containing the task's private 'global' data.
+In this case the destructor function could be 'free'.
+
+Per-task variables are disabled in SMP configurations and this service is not
+available.
+
+.. _rtems_task_variable_get:
+
+TASK_VARIABLE_GET - Obtain value of a per task variable
+-------------------------------------------------------
+.. index:: get per-task variable
+.. index:: obtain per-task variable
+
+.. warning::
+
+ This directive is deprecated and task variables will be removed.
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_variable_get
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_variable_get(
+ rtems_id tid,
+ void **task_variable,
+ void **task_variable_value
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - per task variable obtained successfully
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``task_variable`` is NULL
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``task_variable_value`` is NULL
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``task_variable`` is not found
+ * - ``RTEMS_NO_MEMORY``
+ - invalid task id
+ * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
+ - not supported on remote tasks
+
+**DESCRIPTION:**
+
+This directive looks up the private value of a task variable for a specified
+task and stores that value in the location pointed to by the result argument.
+The specified task is usually not the calling task, which can get its private
+value by directly accessing the variable.
+
+**NOTES:**
+
+If you change memory which ``task_variable_value`` points to, remember to
+declare that memory as volatile, so that the compiler will optimize it
+correctly. In this case both the pointer ``task_variable_value`` and data
+referenced by ``task_variable_value`` should be considered volatile.
+
+Per-task variables are disabled in SMP configurations and this service is not
+available.
+
+.. _rtems_task_variable_delete:
+
+TASK_VARIABLE_DELETE - Remove per task variable
+-----------------------------------------------
+.. index:: per-task variable
+.. index:: task private variable
+.. index:: task private data
+
+.. warning::
+
+ This directive is deprecated and task variables will be removed.
+
+**CALLING SEQUENCE:**
+
+.. index:: rtems_task_variable_delete
+
+.. code-block:: c
+
+ rtems_status_code rtems_task_variable_delete(
+ rtems_id id,
+ void **task_variable
+ );
+
+**DIRECTIVE STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``RTEMS_SUCCESSFUL``
+ - per task variable deleted successfully
+ * - ``RTEMS_INVALID_ID``
+ - invalid task id
+ * - ``RTEMS_NO_MEMORY``
+ - invalid task id
+ * - ``RTEMS_INVALID_ADDRESS``
+ - ``task_variable`` is NULL
+ * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
+ - not supported on remote tasks
+
+**DESCRIPTION:**
+
+This directive removes the given location from a task's context.
+
+**NOTES:**
+
+Per-task variables are disabled in SMP configurations and this service
+is not available.