summaryrefslogtreecommitdiffstats
path: root/doc/user/task.t
diff options
context:
space:
mode:
authorJoel Sherrill <joel@rtems.org>2016-11-15 10:37:59 -0600
committerJoel Sherrill <joel@rtems.org>2017-01-11 12:13:21 -0600
commit48a7fa31f918a6fc88719b3c9393a9ba2829f42a (patch)
tree10bf638de133099fcabe5fe713ca98a546a27ab2 /doc/user/task.t
parentRemove obsolete __RTEMS_HAVE_SYS_CPUSET_H__ (diff)
downloadrtems-48a7fa31f918a6fc88719b3c9393a9ba2829f42a.tar.bz2
Remove texinfo format documentation. Replaced by Sphinx formatted documentation.
closes #2812.
Diffstat (limited to '')
-rw-r--r--doc/user/task.t1797
1 files changed, 0 insertions, 1797 deletions
diff --git a/doc/user/task.t b/doc/user/task.t
deleted file mode 100644
index c51fbf3491..0000000000
--- a/doc/user/task.t
+++ /dev/null
@@ -1,1797 +0,0 @@
-@c
-@c COPYRIGHT (c) 1988-2014.
-@c On-Line Applications Research Corporation (OAR).
-@c All rights reserved.
-
-@chapter Task Manager
-
-@cindex tasks
-
-@section Introduction
-
-The task manager provides a comprehensive set of directives to
-create, delete, and administer tasks. The directives provided
-by the task manager are:
-
-@itemize @bullet
-@item @code{@value{DIRPREFIX}task_create} - Create a task
-@item @code{@value{DIRPREFIX}task_ident} - Get ID of a task
-@item @code{@value{DIRPREFIX}task_self} - Obtain ID of caller
-@item @code{@value{DIRPREFIX}task_start} - Start a task
-@item @code{@value{DIRPREFIX}task_restart} - Restart a task
-@item @code{@value{DIRPREFIX}task_delete} - Delete a task
-@item @code{@value{DIRPREFIX}task_suspend} - Suspend a task
-@item @code{@value{DIRPREFIX}task_resume} - Resume a task
-@item @code{@value{DIRPREFIX}task_is_suspended} - Determine if a task is suspended
-@item @code{@value{DIRPREFIX}task_set_priority} - Set task priority
-@item @code{@value{DIRPREFIX}task_mode} - Change current task's mode
-@item @code{@value{DIRPREFIX}task_wake_after} - Wake up after interval
-@item @code{@value{DIRPREFIX}task_wake_when} - Wake up when specified
-@item @code{@value{DIRPREFIX}iterate_over_all_threads} - Iterate Over Tasks
-@item @code{@value{DIRPREFIX}task_variable_add} - Associate per task variable
-@item @code{@value{DIRPREFIX}task_variable_get} - Obtain value of a a per task variable
-@item @code{@value{DIRPREFIX}task_variable_delete} - Remove per task variable
-@end itemize
-
-@section Background
-
-@subsection Task Definition
-
-@cindex 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:
-
-@itemize @bullet
-@item a "dispatchable" unit.
-
-@item an entity to which the processor is allocated.
-
-@item an atomic unit of a real-time, multiprocessor system.
-
-@item single threads of execution which concurrently compete for resources.
-
-@item a sequence of closely related computations which can execute
-concurrently with other computational sequences.
-
-@end itemize
-
-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).
-
-@subsection 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.
-
-@subsection Task States
-
-@cindex task states
-
-A task may exist in one of the following five states:
-
-@itemize @bullet
-@item @b{executing} - Currently scheduled to the CPU
-@item @b{ready} - May be scheduled to the CPU
-@item @b{blocked} - Unable to be scheduled to the CPU
-@item @b{dormant} - Created task that is not started
-@item @b{non-existent} - Uncreated or deleted task
-@end itemize
-
-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.
-
-@subsection Task Priority
-
-@cindex task priority
-@cindex priority, task
-@findex 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
-@code{@value{DIRPREFIX}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.
-
-@subsection Task Mode
-
-@cindex task mode
-@findex rtems_task_mode
-
-A task's execution mode is a combination of the following
-four components:
-
-@itemize @bullet
-@item preemption
-@item ASR processing
-@item timeslicing
-@item interrupt level
-@end itemize
-
-It is used to modify RTEMS' scheduling process and to alter the
-execution environment of the task. The data type
-@code{@value{DIRPREFIX}task_mode} is used to manage the task
-execution mode.
-
-@cindex preemption
-
-The preemption component allows a task to determine when control of the
-processor is relinquished. If preemption is disabled
-(@code{@value{RPREFIX}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
-(@code{@value{RPREFIX}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.
-
-@cindex 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 (@code{@value{RPREFIX}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 (@code{@value{RPREFIX}NO_TIMESLICE}), then the task will be
-allowed to execute until a task of higher priority is made ready. If
-@code{@value{RPREFIX}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 (@code{@value{RPREFIX}ASR}), then signals
-sent to the task will be processed the next time the task executes. If
-signal processing is disabled (@code{@value{RPREFIX}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.
-
-@cindex interrupt level, task
-
-The interrupt level component is used to determine which
-interrupts will be enabled when the task is executing.
-@code{@value{RPREFIX}INTERRUPT_LEVEL(n)}
-specifies that the task will execute at interrupt level n.
-
-@itemize @bullet
-@item @code{@value{RPREFIX}PREEMPT} - enable preemption (default)
-@item @code{@value{RPREFIX}NO_PREEMPT} - disable preemption
-@item @code{@value{RPREFIX}NO_TIMESLICE} - disable timeslicing (default)
-@item @code{@value{RPREFIX}TIMESLICE} - enable timeslicing
-@item @code{@value{RPREFIX}ASR} - enable ASR processing (default)
-@item @code{@value{RPREFIX}NO_ASR} - disable ASR processing
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} - enable all interrupts (default)
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} - execute at interrupt level n
-@end itemize
-
-The set of default modes may be selected by specifying the
-@code{@value{RPREFIX}DEFAULT_MODES} constant.
-
-@subsection Accessing Task Arguments
-
-@cindex task arguments
-@cindex 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:
-
-@ifset is-C
-@findex rtems_task
-
-@example
-rtems_task user_task(
- rtems_task_argument argument
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure User_Task (
- Argument : in RTEMS.Task_Argument_Ptr
-);
-@end example
-@end ifset
-
-Application tasks requiring more information may view this
-single argument as an index into an array of parameter blocks.
-
-@subsection Floating Point Considerations
-
-@cindex floating point
-
-Creating a task with the @code{@value{RPREFIX}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
-@b{NOT} allocated for @code{@value{RPREFIX}NO_FLOATING_POINT} tasks. Saving
-and restoring the context of a @code{@value{RPREFIX}FLOATING_POINT} task
-takes longer than that of a @code{@value{RPREFIX}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
-@code{@value{RPREFIX}FLOATING_POINT} task is dispatched and that task was
-not the last task to utilize the coprocessor. In a system with only one
-@code{@value{RPREFIX}FLOATING_POINT} task, the state of the numeric
-coprocessor will never be saved or restored.
-
-Although the overhead imposed by @code{@value{RPREFIX}FLOATING_POINT} tasks
-is minimal, some applications may wish to completely avoid the overhead
-associated with @code{@value{RPREFIX}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
-@code{@value{RPREFIX}NO_FLOATING_POINT} task can utilize the numeric
-coprocessor without incurring the overhead of a
-@code{@value{RPREFIX}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 @code{@value{RPREFIX}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
-@code{@value{RPREFIX}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 @code{@value{RPREFIX}NO_FLOATING_POINT}
-whether created as @code{@value{RPREFIX}FLOATING_POINT} or
-@code{@value{RPREFIX}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 @code{@value{RPREFIX}FLOATING_POINT}
-attribute. The consequence of a @code{@value{RPREFIX}NO_FLOATING_POINT}
-task attempting to access the floating point unit is CPU dependent but will
-generally result in an exception condition.
-
-@subsection Per Task Variables
-
-@cindex 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
-@code{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.
-
-@b{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.
-
-@subsection Building a Task Attribute Set
-
-@cindex 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:
-
-@itemize @bullet
-@item @code{@value{RPREFIX}NO_FLOATING_POINT} - does not use coprocessor (default)
-@item @code{@value{RPREFIX}FLOATING_POINT} - uses numeric coprocessor
-@item @code{@value{RPREFIX}LOCAL} - local task (default)
-@item @code{@value{RPREFIX}GLOBAL} - global task
-@end itemize
-
-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 @code{@value{RPREFIX}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 @code{@value{RPREFIX}FLOATING_POINT} or
-@code{@value{RPREFIX}LOCAL @value{OR} @value{RPREFIX}FLOATING_POINT}.
-The attribute_set parameter can be set to
-@code{@value{RPREFIX}FLOATING_POINT} because @code{@value{RPREFIX}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
-@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}FLOATING_POINT}.
-
-@subsection Building a Mode and Mask
-
-@cindex 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:
-
-@ifset use-ascii
-@itemize @bullet
-@item @code{@value{RPREFIX}PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
-
-@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
-
-@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
-
-@item @code{@value{RPREFIX}TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
-
-@item @code{@value{RPREFIX}ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
-
-@item @code{@value{RPREFIX}NO_ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
-@end itemize
-@end ifset
-
-@ifset use-tex
-@sp 1
-@c this is temporary
-@itemize @bullet
-@item @code{@value{RPREFIX}PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
-
-@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
-
-@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
-
-@item @code{@value{RPREFIX}TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
-
-@item @code{@value{RPREFIX}ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
-
-@item @code{@value{RPREFIX}NO_ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
-
-@end itemize
-
-@tex
-@end tex
-@end ifset
-
-@ifset use-html
-@html
-<CENTER>
- <TABLE COLS=3 WIDTH="80%" BORDER=2>
-<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
- <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
- <TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}PREEMPT</TD>
- <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
- <TD ALIGN=center>enables preemption</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}NO_PREEMPT</TD>
- <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
- <TD ALIGN=center>disables preemption</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}NO_TIMESLICE</TD>
- <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
- <TD ALIGN=center>disables timeslicing</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}TIMESLICE</TD>
- <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
- <TD ALIGN=center>enables timeslicing</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}ASR</TD>
- <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
- <TD ALIGN=center>enables ASR processing</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}NO_ASR</TD>
- <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
- <TD ALIGN=center>disables ASR processing</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(0)</TD>
- <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
- <TD ALIGN=center>enables all interrupts</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(n)</TD>
- <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
- <TD ALIGN=center>sets interrupts level n</TD></TR>
- </TABLE>
-</CENTER>
-@end html
-@end ifset
-
-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 @code{@value{RPREFIX}DEFAULT_MODES} and the
-mask @code{@value{RPREFIX}ALL_MODE_MASKS} should be used.
-
-The following example demonstrates the mode and mask parameters used with
-the @code{@value{DIRPREFIX}task_mode}
-directive to place a task at interrupt level 3 and make it
-non-preemptible. The mode should be set to
-@code{@value{RPREFIX}INTERRUPT_LEVEL(3) @value{OR}
-@value{RPREFIX}NO_PREEMPT} to indicate the desired preemption mode and
-interrupt level, while the mask parameter should be set to
-@code{@value{RPREFIX}INTERRUPT_MASK @value{OR}
-@value{RPREFIX}NO_PREEMPT_MASK} to indicate that the calling task's
-interrupt level and preemption mode are being altered.
-
-@section Operations
-
-@subsection Creating Tasks
-
-The @code{@value{DIRPREFIX}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.
-
-@subsection 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 @code{@value{DIRPREFIX}task_create}
-directive, the task ID is
-stored in a user provided location. Second, the task ID may be
-obtained later using the @code{@value{DIRPREFIX}task_ident}
-directive. The task ID is
-used by other directives to manipulate this task.
-
-@subsection Starting and Restarting Tasks
-
-The @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}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.
-
-@subsection Suspending and Resuming Tasks
-
-The @code{@value{DIRPREFIX}task_suspend}
-directive is used to place either the caller or
-another task into a suspended state. The task remains suspended
-until a @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}task_is_suspended} can be used to
-determine if a task is currently suspended.
-
-@subsection Delaying the Currently Executing Task
-
-The @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}task_wake_after}
-directive with a delay
-interval of @code{@value{RPREFIX}YIELD_PROCESSOR} ticks will yield the
-processor to any other ready task of equal or greater priority and remain
-ready to execute.
-
-The @code{@value{DIRPREFIX}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.
-
-@subsection Changing Task Priority
-
-The @code{@value{DIRPREFIX}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
-@code{@value{RPREFIX}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 @code{@value{DIRPREFIX}task_restart}
-directive resets the priority of a task to its
-original value.
-
-@subsection Changing Task Mode
-
-The @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}task_restart}
-directive resets the mode of a task to its
-original value.
-
-@subsection Task Deletion
-
-RTEMS provides the @code{@value{DIRPREFIX}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
-@code{@value{DIRPREFIX}task_wake_after} and
-@code{@value{DIRPREFIX}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.
-
-@subsection Transition Advice for Obsolete Directives
-
-@subsubsection Notepads
-@ifset is-C
-@findex rtems_task_get_note
-@findex rtems_task_set_note
-@end ifset
-
-Task notepads and the associated directives
-@code{@value{DIRPREFIX}task_get_note} and
-@code{@value{DIRPREFIX}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.
-
-@section 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.
-
-@page
-
-@subsection TASK_CREATE - Create a task
-
-@cindex create a task
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_create
-@example
-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
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Create (
- Name : in RTEMS.Name;
- Initial_Priority : in RTEMS.Task_Priority;
- Stack_Size : in RTEMS.Unsigned32;
- Initial_Modes : in RTEMS.Mode;
- Attribute_Set : in RTEMS.Attribute;
- ID : out RTEMS.ID;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task created successfully@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
-@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
-@code{@value{RPREFIX}INVALID_PRIORITY} - invalid task priority@*
-@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@*
-@code{@value{RPREFIX}TOO_MANY} - too many tasks created@*
-@code{@value{RPREFIX}UNSATISFIED} - not enough memory for stack/FP context@*
-@code{@value{RPREFIX}TOO_MANY} - too many global objects
-
-@subheading 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
-@code{@value{RPREFIX}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 @code{@value{RPREFIX}NO_FLOATING_POINT} attribute.
-If the @code{@value{RPREFIX}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 @code{@value{DIRPREFIX}task_start}.
-
-@subheading 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:
-
-@itemize @bullet
-@item @code{@value{RPREFIX}MINIMUM_STACK_SIZE}
-is the minimum stack size @b{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
-@code{@value{RPREFIX}MINIMUM_STACK_SIZE} bytes in size. If the
-user configured minimum stack size is larger than the recommended
-minimum, then it will be used.
-
-@item @code{@value{RPREFIX}CONFIGURED_MINIMUM_STACK_SIZE}
-indicates that 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
-@code{@value{RPREFIX}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.
-
-@end itemize
-
-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:
-
-@itemize @bullet
-@item @code{@value{RPREFIX}NO_FLOATING_POINT} - does not use coprocessor (default)
-@item @code{@value{RPREFIX}FLOATING_POINT} - uses numeric coprocessor
-@item @code{@value{RPREFIX}LOCAL} - local task (default)
-@item @code{@value{RPREFIX}GLOBAL} - global task
-@end itemize
-
-The following task mode constants are defined by RTEMS:
-
-@itemize @bullet
-@item @code{@value{RPREFIX}PREEMPT} - enable preemption (default)
-@item @code{@value{RPREFIX}NO_PREEMPT} - disable preemption
-@item @code{@value{RPREFIX}NO_TIMESLICE} - disable timeslicing (default)
-@item @code{@value{RPREFIX}TIMESLICE} - enable timeslicing
-@item @code{@value{RPREFIX}ASR} - enable ASR processing (default)
-@item @code{@value{RPREFIX}NO_ASR} - disable ASR processing
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} - enable all interrupts (default)
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} - execute at interrupt level n
-@end itemize
-
-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.
-
-@page
-
-@subsection TASK_IDENT - Get ID of a task
-
-@cindex get ID of a task
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_ident
-@example
-rtems_status_code rtems_task_ident(
- rtems_name name,
- uint32_t node,
- rtems_id *id
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Ident (
- Name : in RTEMS.Name;
- Node : in RTEMS.Node;
- ID : out RTEMS.ID;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task identified successfully@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
-@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
-@code{@value{RPREFIX}INVALID_NODE} - invalid node id
-
-@subheading DESCRIPTION:
-This directive obtains the task id associated with the task name
-specified in name. A task may obtain its own id by specifying
-@code{@value{RPREFIX}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.
-
-@subheading NOTES:
-This directive will not cause the running task to be preempted.
-
-If node is @code{@value{RPREFIX}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.
-
-@page
-
-@subsection TASK_SELF - Obtain ID of caller
-
-@cindex obtain ID of caller
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_self
-@example
-rtems_id rtems_task_self(void);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-function Task_Self return RTEMS.ID;
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-Returns the object Id of the calling task.
-
-@subheading DESCRIPTION:
-This directive returns the Id of the calling task.
-
-@subheading NOTES:
-If called from an interrupt service routine, this directive
-will return the Id of the interrupted task.
-
-@page
-
-@subsection TASK_START - Start a task
-
-@cindex starting a task
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_start
-@example
-rtems_status_code rtems_task_start(
- rtems_id id,
- rtems_task_entry entry_point,
- rtems_task_argument argument
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Start (
- ID : in RTEMS.ID;
- Entry_Point : in RTEMS.Task_Entry;
- Argument : in RTEMS.Task_Argument;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - ask started successfully@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - invalid task entry point@*
-@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
-@code{@value{RPREFIX}INCORRECT_STATE} - task not in the dormant state@*
-@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot start remote task
-
-@subheading DESCRIPTION:
-This directive readies the task, specified by @code{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
-@code{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.
-
-@subheading 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 @code{@value{DIRPREFIX}task_start} directive.
-
-@page
-
-@subsection TASK_RESTART - Restart a task
-
-@cindex restarting a task
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_restart
-@example
-rtems_status_code rtems_task_restart(
- rtems_id id,
- rtems_task_argument argument
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Restart (
- ID : in RTEMS.ID;
- Argument : in RTEMS.Task_Argument;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task restarted successfully@*
-@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
-@code{@value{RPREFIX}INCORRECT_STATE} - task never started@*
-@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task
-
-@subheading 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 @code{@value{DIRPREFIX}task_start}
-of the task and any ensuing calls
-to @code{@value{DIRPREFIX}task_restart}
-of the task. This can be beneficial in deleting
-a task. Instead of deleting a task using
-the @code{@value{DIRPREFIX}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.
-
-@subheading NOTES:
-If id is @code{@value{RPREFIX}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 @code{@value{RPREFIX}GLOBAL} option.
-
-@page
-
-@subsection TASK_DELETE - Delete a task
-
-@cindex deleting a task
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_delete
-@example
-rtems_status_code rtems_task_delete(
- rtems_id id
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Delete (
- ID : in RTEMS.ID;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task deleted successfully@*
-@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
-@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task
-
-@subheading 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 @code{@value{RPREFIX}FLOATING_POINT}, its
-floating point context area. RTEMS does not reclaim the
-following resources: region segments, partition buffers,
-semaphores, timers, or rate monotonic periods.
-
-@subheading 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 (@code{@value{RPREFIX}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 @code{@value{RPREFIX}GLOBAL} option.
-
-@page
-
-@subsection TASK_SUSPEND - Suspend a task
-
-@cindex suspending a task
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_suspend
-@example
-rtems_status_code rtems_task_suspend(
- rtems_id id
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Suspend (
- ID : in RTEMS.ID;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task suspended successfully@*
-@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
-@code{@value{RPREFIX}ALREADY_SUSPENDED} - task already suspended
-
-@subheading 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 @code{@value{DIRPREFIX}task_resume}
-directive for this task and any blocked state
-has been removed.
-
-@subheading NOTES:
-The requesting task can suspend itself by specifying @code{@value{RPREFIX}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
-@code{@value{RPREFIX}ALREADY_SUSPENDED} status code is returned.
-
-@page
-
-@subsection TASK_RESUME - Resume a task
-
-@cindex resuming a task
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_resume
-@example
-rtems_status_code rtems_task_resume(
- rtems_id id
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Resume (
- ID : in RTEMS.ID;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task resumed successfully@*
-@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
-@code{@value{RPREFIX}INCORRECT_STATE} - task not suspended
-
-@subheading 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.
-
-@subheading 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
-@code{@value{RPREFIX}INCORRECT_STATE} status code is returned.
-
-@page
-
-@subsection TASK_IS_SUSPENDED - Determine if a task is Suspended
-
-@cindex is task suspended
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_is_suspended
-@example
-rtems_status_code rtems_task_is_suspended(
- rtems_id id
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Is_Suspended (
- ID : in RTEMS.ID;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task is NOT suspended@*
-@code{@value{RPREFIX}ALREADY_SUSPENDED} - task is currently suspended@*
-@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
-@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks
-
-@subheading DESCRIPTION:
-
-This directive returns a status code indicating whether or
-not the specified task is currently suspended.
-
-@subheading NOTES:
-
-This operation is not currently supported on remote tasks.
-
-@page
-
-@subsection TASK_SET_PRIORITY - Set task priority
-
-@findex rtems_task_set_priority
-@cindex current task priority
-@cindex set task priority
-@cindex get task priority
-@cindex obtain task priority
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-rtems_status_code rtems_task_set_priority(
- rtems_id id,
- rtems_task_priority new_priority,
- rtems_task_priority *old_priority
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Set_Priority (
- ID : in RTEMS.ID;
- New_Priority : in RTEMS.Task_Priority;
- Old_Priority : out RTEMS.Task_Priority;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task priority set successfully@*
-@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - invalid return argument pointer@*
-@code{@value{RPREFIX}INVALID_PRIORITY} - invalid task priority
-
-@subheading DESCRIPTION:
-This directive manipulates the priority of the task specified by
-id. An id of @code{@value{RPREFIX}SELF} is used to indicate
-the calling task. When new_priority is not equal to
-@code{@value{RPREFIX}CURRENT_PRIORITY}, the specified
-task's previous priority is returned in old_priority. When
-new_priority is @code{@value{RPREFIX}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.
-
-@subheading 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.
-
-@page
-
-@subsection TASK_MODE - Change the current task mode
-
-@cindex current task mode
-@cindex set task mode
-@cindex get task mode
-@cindex set task preemption mode
-@cindex get task preemption mode
-@cindex obtain task mode
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_mode
-@example
-rtems_status_code rtems_task_mode(
- rtems_mode mode_set,
- rtems_mode mask,
- rtems_mode *previous_mode_set
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Mode (
- Mode_Set : in RTEMS.Mode;
- Mask : in RTEMS.Mode;
- Previous_Mode_Set : in RTEMS.Mode;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - task mode set successfully@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{previous_mode_set} is NULL
-
-@subheading 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.
-
-@subheading 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
-@code{@value{RPREFIX}CURRENT_MODE}.
-
-To temporarily disable the processing of a valid ASR, a task
-should call this directive with the @code{@value{RPREFIX}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:
-
-@ifset use-ascii
-@itemize @bullet
-@item @code{@value{RPREFIX}PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
-
-@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
-
-@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
-
-@item @code{@value{RPREFIX}TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
-
-@item @code{@value{RPREFIX}ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
-
-@item @code{@value{RPREFIX}NO_ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
-
-@end itemize
-@end ifset
-
-@ifset use-tex
-@sp 1
-@c this is temporary
-@itemize @bullet
-@item @code{@value{RPREFIX}PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
-
-@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
-
-@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
-
-@item @code{@value{RPREFIX}TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
-
-@item @code{@value{RPREFIX}ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
-
-@item @code{@value{RPREFIX}NO_ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
-
-@end itemize
-
-@tex
-@end tex
-@end ifset
-
-@ifset use-html
-@html
-<CENTER>
- <TABLE COLS=3 WIDTH="80%" BORDER=2>
-<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
- <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
- <TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}PREEMPT</TD>
- <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
- <TD ALIGN=center>enables preemption</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}NO_PREEMPT</TD>
- <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
- <TD ALIGN=center>disables preemption</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}NO_TIMESLICE</TD>
- <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
- <TD ALIGN=center>disables timeslicing</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}TIMESLICE</TD>
- <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
- <TD ALIGN=center>enables timeslicing</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}ASR</TD>
- <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
- <TD ALIGN=center>enables ASR processing</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}NO_ASR</TD>
- <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
- <TD ALIGN=center>disables ASR processing</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(0)</TD>
- <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
- <TD ALIGN=center>enables all interrupts</TD></TR>
-<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(n)</TD>
- <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
- <TD ALIGN=center>sets interrupts level n</TD></TR>
- </TABLE>
-</CENTER>
-@end html
-@end ifset
-
-@page
-
-@subsection TASK_WAKE_AFTER - Wake up after interval
-
-@cindex delay a task for an interval
-@cindex wake up after an interval
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_wake_after
-@example
-rtems_status_code rtems_task_wake_after(
- rtems_interval ticks
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Wake_After (
- Ticks : in RTEMS.Interval;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - always successful
-
-@subheading 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 @code{@value{DIRPREFIX}clock_tick}
-directive automatically updates the delay period.
-
-@subheading NOTES:
-Setting the system date and time with the
-@code{@value{DIRPREFIX}clock_set} directive
-has no effect on a @code{@value{DIRPREFIX}task_wake_after} blocked task.
-
-A task may give up the processor and remain in the ready state
-by specifying a value of @code{@value{RPREFIX}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.
-
-@page
-
-@subsection TASK_WAKE_WHEN - Wake up when specified
-
-@cindex delay a task until a wall time
-@cindex wake up at a wall time
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_wake_when
-@example
-rtems_status_code rtems_task_wake_when(
- rtems_time_of_day *time_buffer
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Wake_When (
- Time_Buffer : in RTEMS.Time_Of_Day;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - awakened at date/time successfully@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL@*
-@code{@value{RPREFIX}INVALID_TIME_OF_DAY} - invalid time buffer@*
-@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set
-
-@subheading 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.
-
-@subheading NOTES:
-The ticks portion of time_buffer @value{STRUCTURE} is ignored. The
-timing granularity of this directive is a second.
-
-A clock tick is required to support the functionality of this directive.
-
-@page
-
-@subsection ITERATE_OVER_ALL_THREADS - Iterate Over Tasks
-
-@cindex iterate over all threads
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_iterate_over_all_threads
-@example
-typedef void (*rtems_per_thread_routine)(
- Thread_Control *the_thread
-);
-
-void rtems_iterate_over_all_threads(
- rtems_per_thread_routine routine
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-NOT SUPPORTED FROM Ada BINDING
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES: NONE
-
-
-@subheading DESCRIPTION:
-
-This directive iterates over all of the existant threads in the
-system and invokes @code{routine} on each of them. The user should
-be careful in accessing the contents of @code{the_thread}.
-
-This routine is intended for use in diagnostic utilities and is
-not intented for routine use in an operational system.
-
-@subheading NOTES:
-
-There is NO protection while this routine is called. Thus it is
-possible that @code{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.
-
-@page
-
-@subsection TASK_VARIABLE_ADD - Associate per task variable
-
-@cindex per-task variable
-@cindex task private variable
-@cindex task private data
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_variable_add
-@example
-rtems_status_code rtems_task_variable_add(
- rtems_id tid,
- void **task_variable,
- void (*dtor)(void *)
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-type Task_Variable_Dtor is access procedure (
- Argument : in RTEMS.Address;
-);
-
-procedure Task_Variable_Add (
- ID : in RTEMS.ID;
- Task_Variable : in RTEMS.Address;
- Dtor : in RTEMS.Task_Variable_Dtor;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
-@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
-@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
-@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
-
-@subheading 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.
-
-@subheading NOTES:
-
-This directive is deprecated and task variables will be removed.
-
-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.
-
-@page
-
-@subsection TASK_VARIABLE_GET - Obtain value of a per task variable
-
-@cindex get per-task variable
-@cindex obtain per-task variable
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_variable_get
-@example
-rtems_status_code rtems_task_variable_get(
- rtems_id tid,
- void **task_variable,
- void **task_variable_value
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Variable_Get (
- ID : in RTEMS.ID;
- Task_Variable : out RTEMS.Address;
- Task_Variable_Value : out RTEMS.Address;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - per task variable obtained successfully@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable_value} is NULL@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is not found@*
-@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
-@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
-
-@subheading 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.
-
-@subheading NOTES:
-
-This directive is deprecated and task variables will be removed.
-
-If you change memory which @code{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
-@code{task_variable_value} and data referenced by @code{task_variable_value}
-should be considered volatile.
-
-Per-task variables are disabled in SMP configurations and this service
-is not available.
-
-@page
-
-@subsection TASK_VARIABLE_DELETE - Remove per task variable
-
-@cindex per-task variable
-@cindex task private variable
-@cindex task private data
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_task_variable_delete
-@example
-rtems_status_code rtems_task_variable_delete(
- rtems_id id,
- void **task_variable
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Task_Variable_Delete (
- ID : in RTEMS.ID;
- Task_Variable : out RTEMS.Address;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - per task variable deleted successfully@*
-@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
-@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
-@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
-@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
-
-@subheading DESCRIPTION:
-This directive removes the given location from a task's context.
-
-@subheading NOTES:
-
-This directive is deprecated and task variables will be removed.
-
-Per-task variables are disabled in SMP configurations and this service
-is not available.
-