From ae68ff085724dd35d60151bd153e80b8b0776873 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 27 May 1997 12:40:11 +0000 Subject: Initial revision --- doc/user/task.t | 1313 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1313 insertions(+) create mode 100644 doc/user/task.t (limited to 'doc/user/task.t') diff --git a/doc/user/task.t b/doc/user/task.t new file mode 100644 index 0000000000..730bb73ad2 --- /dev/null +++ b/doc/user/task.t @@ -0,0 +1,1313 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Task Manager, Task Manager Introduction, SHUTDOWN_EXECUTIVE - Shutdown RTEMS, Top +@end ifinfo + +@chapter Task Manager + +@ifinfo +@menu +* Task Manager Introduction:: +* Task Manager Background:: +* Task Manager Operations:: +* Task Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Task Manager Introduction, Task Manager Background, Task Manager, Task Manager +@end ifinfo +@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{task_create} - Create a task +@item @code{task_ident} - Get ID of a task +@item @code{task_start} - Start a task +@item @code{task_restart} - Restart a task +@item @code{task_delete} - Delete a task +@item @code{task_suspend} - Suspend a task +@item @code{task_resume} - Resume a task +@item @code{task_set_priority} - Set task priority +@item @code{task_mode} - Change current task's mode +@item @code{task_get_note} - Get task notepad entry +@item @code{task_set_note} - Set task notepad entry +@item @code{task_wake_after} - Wake up after interval +@item @code{task_wake_when} - Wake up when specified +@end itemize + +@ifinfo +@node Task Manager Background, Task Definition, Task Manager Introduction, Task Manager +@end ifinfo + +@section Background + +@ifinfo +@menu +* Task Definition:: +* Task Control Block:: +* Task States:: +* Task Priority:: +* Task Mode:: +* Accessing Task Arguments:: +* Floating Point Considerations:: +* Building a Task's Attribute Set:: +* Building a Mode and Mask:: +@end menu + +@end ifinfo + +@ifinfo +@node Task Definition, Task Control Block, Task Manager Background, Task Manager Background +@end ifinfo + +@subsection 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). + +@ifinfo +@node Task Control Block, Task States, Task Definition, Task Manager Background +@end ifinfo +@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, set of notepad locations, 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. + +@ifinfo +@node Task States, Task Priority, Task Control Block, Task Manager Background +@end ifinfo +@subsection Task States + +A task may exist in one of the following five states: + +@itemize @bullet +@item @code{executing} - Currently scheduled to the CPU +@item @code{ready} - May be scheduled to the CPU +@item @code{blocked} - Unable to be scheduled to the CPU +@item @code{dormant} - Created task that is not started +@item @code{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. + +@ifinfo +@node Task Priority, Task Mode, Task States, Task Manager Background +@end ifinfo +@subsection 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. 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. + +@ifinfo +@node Task Mode, Accessing Task Arguments, Task Priority, Task Manager Background +@end ifinfo +@subsection Task Mode + +A task's 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 preemption component allows a task to determine when control +of the processor is relinquished. If preemption is disabled +(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 (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. + +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 (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 (NO_TIMESLICE), then the task will be allowed to +execute until a task of higher priority is made ready. If +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 (ASR), then signals sent to the +task will be processed the next time the task executes. If +signal processing is disabled (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. + +The interrupt level component is used to determine which +interrupts will be enabled when the task is executing. +INTERRUPT_LEVEL(n) specifies that the task will execute at +interrupt level n. + +@itemize @bullet +@item @code{PREEMPT} - enable preemption (default) +@item @code{NO_PREEMPT} - disable preemption +@item @code{NO_TIMESLICE} - disable timeslicing (default) +@item @code{TIMESLICE} - enable timeslicing +@item @code{ASR} - enable ASR processing (default) +@item @code{NO_ASR} - disable ASR processing +@item @code{INTERRUPT_LEVEL(0)} - enable all interrupts (default) +@item @code{INTERRUPT_LEVEL(n)} - execute at interrupt level n +@end itemize + +@ifinfo +@node Accessing Task Arguments, Floating Point Considerations, Task Mode, Task Manager Background +@end ifinfo +@subsection Accessing Task Arguments + +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: + +@example +rtems_task user_task( + rtems_task_argument argument +); +@end example + +Application tasks requiring more information may view this +single argument as an index into an array of parameter blocks. + +@ifinfo +@node Floating Point Considerations, Building a Task's Attribute Set, Accessing Task Arguments, Task Manager Background +@end ifinfo +@subsection Floating Point Considerations + +Creating a task with the FLOATING_POINT 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 NO_FLOATING_POINT tasks. +Saving and restoring the context of a FLOATING_POINT task takes +longer than that of a 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 FLOATING_POINT task is +dispatched and that task was not the last task to utilize the +coprocessor. In a system with only one FLOATING_POINT task, the +state of the numeric coprocessor will never be saved or +restored. + +Although the overhead imposed by FLOATING_POINT tasks is +minimal, some applications may wish to completely avoid the +overhead associated with 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 NO_FLOATING_POINT task can utilize the numeric +coprocessor without incurring the overhead of a 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 +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 +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 +NO_FLOATING_POINT whether created as FLOATING_POINT or +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 +FLOATING_POINT attribute. The consequence of a +NO_FLOATING_POINT task attempting to access the floating point +unit is CPU dependent but will i general result in an exception +condition. + +@ifinfo +@node Building a Task's Attribute Set, Building a Mode and Mask, Floating Point Considerations, Task Manager Background +@end ifinfo +@subsection Building a Task's Attribute Set + +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{NO_FLOATING_POINT} - does not use coprocessor (default) +@item @code{FLOATING_POINT} - uses numeric coprocessor +@item @code{LOCAL} - local task (default) +@item @code{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 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 FLOATING_POINT or LOCAL | +FLOATING_POINT. The attribute_set parameter can be set to +FLOATING_POINT because 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 GLOBAL | +FLOATING_POINT. + +@ifinfo +@node Building a Mode and Mask, Task Manager Operations, Building a Task's Attribute Set, Task Manager Background +@end ifinfo +@subsection Building a Mode and Mask + +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 PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n +@end itemize +@end ifset + +@ifset use-tex +@sp 1 +@c this is temporary +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize + +@tex +@end tex +@end ifset + +@ifset use-html +@html +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode ConstantMask ConstantDescription
PREEMPTPREEMPT_MASKenables preemption
NO_PREEMPTPREEMPT_MASKdisables preemption
NO_TIMESLICETIMESLICE_MASKdisables timeslicing
TIMESLICETIMESLICE_MASKenables timeslicing
ASRASR_MASKenables ASR processing
NO_ASRASR_MASKdisables ASR processing
INTERRUPT_LEVEL(0)INTERRUPT_MASKenables all interrupts
INTERRUPT_LEVEL(n)INTERRUPT_MASKsets interrupts level n
+
+@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 DEFAULT_MODES and the mask ALL_MODE_MASKS +should be used. + +The following example demonstrates the mode and mask parameters +used with the task_mode directive to place a task at interrupt +level 3 and make it non-preemptible. The mode should be set to +INTERRUPT_LEVEL(3) | NO_PREEMPT to indicate the desired +preemption mode and interrupt level, while the mask parameter +should be set to INTERRUPT_MASK | NO_PREEMPT_MASK to indicate +that the calling task's interrupt level and preemption mode are +being altered. + +@ifinfo +@node Task Manager Operations, Creating Tasks, Building a Mode and Mask, Task Manager +@end ifinfo + +@section Operations + +@ifinfo +@menu +* Creating Tasks:: +* Obtaining Task IDs:: +* Starting and Restarting Tasks:: +* Suspending and Resuming Tasks:: +* Delaying the Currently Executing Task:: +* Changing Task Priority:: +* Changing Task Mode:: +* Notepad Locations:: +* Task Deletion:: +@end menu +@end ifinfo + +@ifinfo +@node Creating Tasks, Obtaining Task IDs, Task Manager Operations, Task Manager Operations +@end ifinfo +@subsection Creating Tasks + +The 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. + +@ifinfo +@node Obtaining Task IDs, Starting and Restarting Tasks, Creating Tasks, Task Manager Operations +@end ifinfo +@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 task_create directive, the task ID is +stored in a user provided location. Second, the task ID may be +obtained later using the task_ident directive. The task ID is +used by other directives to manipulate this task. + +@ifinfo +@node Starting and Restarting Tasks, Suspending and Resuming Tasks, Obtaining Task IDs, Task Manager Operations +@end ifinfo +@subsection Starting and Restarting Tasks + +The 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 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 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. + +@ifinfo +@node Suspending and Resuming Tasks, Delaying the Currently Executing Task, Starting and Restarting Tasks, Task Manager Operations +@end ifinfo +@subsection Suspending and Resuming Tasks + +The task_suspend directive is used to place either the caller or +another task into a suspended state. The task remains suspended +until a 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 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. + +@ifinfo +@node Delaying the Currently Executing Task, Changing Task Priority, Suspending and Resuming Tasks, Task Manager Operations +@end ifinfo +@subsection Delaying the Currently Executing Task + +The 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 task_wake_after directive +with a delay interval of YIELD_PROCESSOR ticks will yield the +processor to any other ready task of equal or greater priority +and remain ready to execute. + +The 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. + +@ifinfo +@node Changing Task Priority, Changing Task Mode, Delaying the Currently Executing Task, Task Manager Operations +@end ifinfo +@subsection Changing Task Priority + +The 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 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 task_restart directive resets the priority of a task to its +original value. + +@ifinfo +@node Changing Task Mode, Notepad Locations, Changing Task Priority, Task Manager Operations +@end ifinfo +@subsection Changing Task Mode + +The 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 task_restart directive resets the mode of a task to its +original value. + +@ifinfo +@node Notepad Locations, Task Deletion, Changing Task Mode, Task Manager Operations +@end ifinfo +@subsection 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, task_set_note and +task_get_note, that enable a user to access and change the +notepad locations. The task_set_note directive enables the user +to set a task's notepad entry to a specified note. The +task_get_note directive allows the user to obtain the note +contained in any one of the sixteen notepads of a specified task. + +@ifinfo +@node Task Deletion, Task Manager Directives, Notepad Locations, Task Manager Operations +@end ifinfo +@subsection Task Deletion + +RTEMS provides the 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 task_wake_after and +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. + +@ifinfo +@node Task Manager Directives, TASK_CREATE - Create a task, Task Deletion, Task Manager +@end ifinfo + +@section Directives + +@ifinfo +@menu +* TASK_CREATE - Create a task:: +* TASK_IDENT - Get ID of a task:: +* TASK_START - Start a task:: +* TASK_RESTART - Restart a task:: +* TASK_DELETE - Delete a task:: +* TASK_SUSPEND - Suspend a task:: +* TASK_RESUME - Resume a task:: +* TASK_SET_PRIORITY - Set task priority:: +* TASK_MODE - Change current task's mode:: +* TASK_GET_NOTE - Get task notepad entry:: +* TASK_SET_NOTE - Set task notepad entry:: +* TASK_WAKE_AFTER - Wake up after interval:: +* TASK_WAKE_WHEN - Wake up when specified:: +@end menu +@end ifinfo + +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 + +@ifinfo +@node TASK_CREATE - Create a task, TASK_IDENT - Get ID of a task, Task Manager Directives, Task Manager Directives +@end ifinfo +@subsection TASK_CREATE - Create a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_create( + rtems_name name, + rtems_task_priority initial_priority, + rtems_unsigned32 stack_size, + rtems_mode initial_modes, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_SIZE} - stack too small@* +@code{INVALID_PRIORITY} - invalid task priority@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many tasks created@* +@code{UNSATISFIED} - not enough memory for stack/FP context@* +@code{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 +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 NO_FLOATING_POINT attribute. If the 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 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. + +RTEMS supports a maximum of 256 interrupt levels which are +mapped onto the interrupt levels actually supported by the +target processor. + +The requested stack size should be at least MINIMUM_STACK_SIZE +bytes. The value of MINIMUM_STACK_SIZE is processor dependent. +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{NO_FLOATING_POINT} - does not use coprocessor (default) +@item @code{FLOATING_POINT} - uses numeric coprocessor +@item @code{LOCAL} - local task (default) +@item @code{GLOBAL} - global task +@end itemize + +The following task mode constants are defined by RTEMS: + +@itemize @bullet +@item @code{PREEMPT} - enable preemption (default) +@item @code{NO_PREEMPT} - disable preemption +@item @code{NO_TIMESLICE} - disable timeslicing (default) +@item @code{TIMESLICE} - enable timeslicing +@item @code{ASR} - enable ASR processing (default) +@item @code{NO_ASR} - disable ASR processing +@item @code{INTERRUPT_LEVEL(0)} - enable all interrupts (default) +@item @code{INTERRUPT_LEVEL(n)} - execute at interrupt level n +@end itemize + +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 + +@ifinfo +@node TASK_IDENT - Get ID of a task, TASK_START - Start a task, TASK_CREATE - Create a task, Task Manager Directives +@end ifinfo +@subsection TASK_IDENT - Get ID of a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task identified successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{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 +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 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 + +@ifinfo +@node TASK_START - Start a task, TASK_RESTART - Restart a task, TASK_IDENT - Get ID of a task, Task Manager Directives +@end ifinfo +@subsection TASK_START - Start a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - ask started successfully@* +@code{INVALID_ADDRESS} - invalid task entry point@* +@code{INVALID_ID} - invalid task id@* +@code{INCORRECT_STATE} - task not in the dormant state@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot start remote task + +@subheading DESCRIPTION: +This directive readies the task, specified by tid, 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. + +@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 task_start directive. + +@page + +@ifinfo +@node TASK_RESTART - Restart a task, TASK_DELETE - Delete a task, TASK_START - Start a task, Task Manager Directives +@end ifinfo +@subsection TASK_RESTART - Restart a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{INCORRECT_STATE} - task never started@* +@code{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. This new argument may be used to distinguish +between the initial task_start of the task and any ensuing calls +to task_restart of the task. This can be beneficial in deleting +a task. Instead of deleting a task using the 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 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 GLOBAL option. + +@page + +@ifinfo +@node TASK_DELETE - Delete a task, TASK_SUSPEND - Suspend a task, TASK_RESTART - Restart a task, Task Manager Directives +@end ifinfo +@subsection TASK_DELETE - Delete a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{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 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 (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 GLOBAL option. + +@page + +@ifinfo +@node TASK_SUSPEND - Suspend a task, TASK_RESUME - Resume a task, TASK_DELETE - Delete a task, Task Manager Directives +@end ifinfo +@subsection TASK_SUSPEND - Suspend a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_suspend( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{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 task_resume directive for this task and any blocked state +has been removed. + +@subheading NOTES: +The requesting task can suspend itself by specifying 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. + +@page + +@ifinfo +@node TASK_RESUME - Resume a task, TASK_SET_PRIORITY - Set task priority, TASK_SUSPEND - Suspend a task, Task Manager Directives +@end ifinfo +@subsection TASK_RESUME - Resume a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_resume( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{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. + +@page + +@ifinfo +@node TASK_SET_PRIORITY - Set task priority, TASK_MODE - Change current task's mode, TASK_RESUME - Resume a task, Task Manager Directives +@end ifinfo +@subsection TASK_SET_PRIORITY - Set task priority + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_set_priority( + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task priority set successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_PRIORITY} - invalid task priority + +@subheading DESCRIPTION: +This directive manipulates the priority of the task specified by +id. An id of SELF is used to indicate the calling task. When +new_priority is not equal to CURRENT_PRIORITY, the specified +task's previous priority is returned in old_priority. When +new_priority is 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. + +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 + +@ifinfo +@node TASK_MODE - Change current task's mode, TASK_GET_NOTE - Get task notepad entry, TASK_SET_PRIORITY - Set task priority, Task Manager Directives +@end ifinfo +@subsection TASK_MODE - Change current task's mode + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_mode( + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task mode set successfully + +@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 enabled. + +A task can obtain its current execution mode, without modifying +it, by calling this directive with a mask value of CURRENT_MODE. + +To temporarily disable the processing of a valid ASR, a task +should call this directive with the 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 PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize +@end ifset + +@ifset use-tex +@sp 1 +@c this is temporary +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize + +@tex +@end tex +@end ifset + +@ifset use-html +@html +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode ConstantMask ConstantDescription
PREEMPTPREEMPT_MASKenables preemption
NO_PREEMPTPREEMPT_MASKdisables preemption
NO_TIMESLICETIMESLICE_MASKdisables timeslicing
TIMESLICETIMESLICE_MASKenables timeslicing
ASRASR_MASKenables ASR processing
NO_ASRASR_MASKdisables ASR processing
INTERRUPT_LEVEL(0)INTERRUPT_MASKenables all interrupts
INTERRUPT_LEVEL(n)INTERRUPT_MASKsets interrupts level n
+
+@end html +@end ifset + +@page + +@ifinfo +@node TASK_GET_NOTE - Get task notepad entry, TASK_SET_NOTE - Set task notepad entry, TASK_MODE - Change current task's mode, Task Manager Directives +@end ifinfo +@subsection TASK_GET_NOTE - Get task notepad entry + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_get_note( + rtems_id id, + rtems_unsigned32 notepad, + rtems_unsigned32 *note +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - note obtained successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_NUMBER} - invalid notepad location + +@subheading DESCRIPTION: +This directive returns the note contained in the notepad +location of the task specified by id. + +@subheading NOTES: +This directive will not cause the running task to be preempted. + +If id is set to SELF, the calling task accesses its own notepad. + +@c This version of the paragraph avoids the overfull hbox error. +@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the +@c sixteen notepad locations. + +The sixteen notepad locations can be accessed using the constants +NOTEPAD_0 through 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. + +@page + +@ifinfo +@node TASK_SET_NOTE - Set task notepad entry, TASK_WAKE_AFTER - Wake up after interval, TASK_GET_NOTE - Get task notepad entry, Task Manager Directives +@end ifinfo +@subsection TASK_SET_NOTE - Set task notepad entry + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_set_note( + rtems_id id, + rtems_unsigned32 notepad, + rtems_unsigned32 note +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task's note set successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_NUMBER} - invalid notepad location + +@subheading DESCRIPTION: +This directive sets the notepad entry for the task specified by +id to the value note. + +@subheading NOTES: +If id is set to SELF, the calling task accesses its own notepad +locations. + +This directive will not cause the running task to be preempted. + +@c This version of the paragraph avoids the overfull hbox error. +@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the +@c sixteen notepad locations. + +The sixteen notepad locations can be accessed using the constants +NOTEPAD_0 through NOTEPAD_15. + +Setting a notepad location of a global task which does not +reside on the local node will generate a request to the remote +node to set the specified notepad entry. + +@page + +@ifinfo +@node TASK_WAKE_AFTER - Wake up after interval, TASK_WAKE_WHEN - Wake up when specified, TASK_SET_NOTE - Set task notepad entry, Task Manager Directives +@end ifinfo +@subsection TASK_WAKE_AFTER - Wake up after interval + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_wake_after( + rtems_interval ticks +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{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 clock_tick directive automatically +updates the delay period. + +@subheading NOTES: +Setting the system date and time with the clock_set directive +has no effect on a task_wake_after blocked task. + +A task may give up the processor and remain in the ready state +by specifying a value of YIELD_PROCESSOR in ticks. + +The maximum timer interval that can be specified is the maximum +value which can be represented by the rtems_unsigned32 type. + +@page + +@ifinfo +@node TASK_WAKE_WHEN - Wake up when specified, Interrupt Manager, TASK_WAKE_AFTER - Wake up after interval, Task Manager Directives +@end ifinfo +@subsection TASK_WAKE_WHEN - Wake up when specified + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_task_wake_when( + rtems_time_of_day *time_buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - awakened at date/time successfully@* +@code{INVALID_TIME_OF_DAY} - invalid time buffer@* +@code{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 structure is ignored. The +timing granularity of this directive is a second. -- cgit v1.2.3