source: rtems/doc/user/task.t @ cf404563

4.11
Last change on this file since cf404563 was cf404563, checked in by Gedare Bloom <gedare@…>, on Mar 10, 2015 at 7:28:19 PM

cpukit: deprecate task variables. closes #2293.

  • Property mode set to 100644
File size: 65.5 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2014.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5
6@chapter Task Manager
7
8@cindex tasks
9
10@section Introduction
11
12The task manager provides a comprehensive set of directives to
13create, delete, and administer tasks.  The directives provided
14by the task manager are:
15
16@itemize @bullet
17@item @code{@value{DIRPREFIX}task_create} - Create a task
18@item @code{@value{DIRPREFIX}task_ident} - Get ID of a task
19@item @code{@value{DIRPREFIX}task_self} - Obtain ID of caller
20@item @code{@value{DIRPREFIX}task_start} - Start a task
21@item @code{@value{DIRPREFIX}task_restart} - Restart a task
22@item @code{@value{DIRPREFIX}task_delete} - Delete a task
23@item @code{@value{DIRPREFIX}task_suspend} - Suspend a task
24@item @code{@value{DIRPREFIX}task_resume} - Resume a task
25@item @code{@value{DIRPREFIX}task_is_suspended} - Determine if a task is suspended
26@item @code{@value{DIRPREFIX}task_set_priority} - Set task priority
27@item @code{@value{DIRPREFIX}task_mode} - Change current task's mode
28@item @code{@value{DIRPREFIX}task_get_note} - Get task notepad entry
29@item @code{@value{DIRPREFIX}task_set_note} - Set task notepad entry
30@item @code{@value{DIRPREFIX}task_wake_after} - Wake up after interval
31@item @code{@value{DIRPREFIX}task_wake_when} - Wake up when specified 
32@item @code{@value{DIRPREFIX}iterate_over_all_threads} - Iterate Over Tasks
33@item @code{@value{DIRPREFIX}task_variable_add} - Associate per task variable
34@item @code{@value{DIRPREFIX}task_variable_get} - Obtain value of a a per task variable
35@item @code{@value{DIRPREFIX}task_variable_delete} - Remove per task variable
36@end itemize
37
38@section Background
39
40@subsection Task Definition
41
42@cindex task, definition
43
44Many definitions of a task have been proposed in computer literature.
45Unfortunately, none of these definitions encompasses all facets of the
46concept in a manner which is operating system independent.  Several of the
47more common definitions are provided to enable each user to select a
48definition which best matches their own experience and understanding of the
49task concept:
50
51@itemize @bullet
52@item a "dispatchable" unit.
53
54@item an entity to which the processor is allocated.
55
56@item an atomic unit of a real-time, multiprocessor system.
57
58@item single threads of execution which concurrently compete for resources.
59
60@item a sequence of closely related computations which can execute
61concurrently with other computational sequences.
62
63@end itemize
64
65From RTEMS' perspective, a task is the smallest thread of
66execution which can compete on its own for system resources.  A
67task is manifested by the existence of a task control block
68(TCB).
69
70@subsection Task Control Block
71
72The Task Control Block (TCB) is an RTEMS defined data structure
73which contains all the information that is pertinent to the
74execution of a task.  During system initialization, RTEMS
75reserves a TCB for each task configured.  A TCB is allocated
76upon creation of the task and is returned to the TCB free list
77upon deletion of the task.
78
79The TCB's elements are modified as a result of system calls made
80by the application in response to external and internal stimuli.
81TCBs are the only RTEMS internal data structure that can be
82accessed by an application via user extension routines.  The TCB
83contains a task's name, ID, current priority, current and
84starting states, execution mode, set of notepad locations, TCB
85user extension pointer, scheduling control structures, as well
86as data required by a blocked task.
87
88A task's context is stored in the TCB when a task switch occurs.
89When the task regains control of the processor, its context is
90restored from the TCB.  When a task is restarted, the initial
91state of the task is restored from the starting context area in
92the task's TCB.
93
94@subsection Task States
95
96@cindex task states
97
98A task may exist in one of the following five states:
99
100@itemize @bullet
101@item @b{executing} - Currently scheduled to the CPU
102@item @b{ready} - May be scheduled to the CPU
103@item @b{blocked} - Unable to be scheduled to the CPU
104@item @b{dormant} - Created task that is not started
105@item @b{non-existent} - Uncreated or deleted task
106@end itemize
107
108An active task may occupy the executing, ready, blocked or
109dormant state, otherwise the task is considered non-existent.
110One or more tasks may be active in the system simultaneously.
111Multiple tasks communicate, synchronize, and compete for system
112resources with each other via system calls.  The multiple tasks
113appear to execute in parallel, but actually each is dispatched
114to the CPU for periods of time determined by the RTEMS
115scheduling algorithm.  The scheduling of a task is based on its
116current state and priority.
117
118@subsection Task Priority
119
120@cindex task priority
121@cindex priority, task
122@findex rtems_task_priority
123
124A task's priority determines its importance in relation to the
125other tasks executing on the same processor.  RTEMS supports 255
126levels of priority ranging from 1 to 255.  The data type
127@code{@value{DIRPREFIX}task_priority} is used to store task
128priorities.
129
130Tasks of numerically
131smaller priority values are more important tasks than tasks of
132numerically larger priority values.  For example, a task at
133priority level 5 is of higher privilege than a task at priority
134level 10.  There is no limit to the number of tasks assigned to
135the same priority.
136
137Each task has a priority associated with it at all times.  The
138initial value of this priority is assigned at task creation
139time.  The priority of a task may be changed at any subsequent
140time.
141
142Priorities are used by the scheduler to determine which ready
143task will be allowed to execute.  In general, the higher the
144logical priority of a task, the more likely it is to receive
145processor execution time.
146
147@subsection Task Mode
148
149@cindex task mode
150@findex rtems_task_mode
151
152A task's execution mode is a combination of the following
153four components:
154
155@itemize @bullet
156@item preemption
157@item ASR processing
158@item timeslicing
159@item interrupt level
160@end itemize
161
162It is used to modify RTEMS' scheduling process and to alter the
163execution environment of the task.  The data type
164@code{@value{DIRPREFIX}task_mode} is used to manage the task
165execution mode.
166
167@cindex preemption
168
169The preemption component allows a task to determine when control of the
170processor is relinquished.  If preemption is disabled
171(@code{@value{RPREFIX}NO_PREEMPT}), the task will retain control of the
172processor as long as it is in the executing state -- even if a higher
173priority task is made ready.  If preemption is enabled
174(@code{@value{RPREFIX}PREEMPT})  and a higher priority task is made ready,
175then the processor will be taken away from the current task immediately and
176given to the higher priority task.
177
178@cindex timeslicing
179
180The timeslicing component is used by the RTEMS scheduler to determine how
181the processor is allocated to tasks of equal priority.  If timeslicing is
182enabled (@code{@value{RPREFIX}TIMESLICE}), then RTEMS will limit the amount
183of time the task can execute before the processor is allocated to another
184ready task of equal priority. The length of the timeslice is application
185dependent and specified in the Configuration Table.  If timeslicing is
186disabled (@code{@value{RPREFIX}NO_TIMESLICE}), then the task will be
187allowed to execute until a task of higher priority is made ready.  If
188@code{@value{RPREFIX}NO_PREEMPT} is selected, then the timeslicing
189component is ignored by the scheduler.
190
191The asynchronous signal processing component is used to determine when
192received signals are to be processed by the task.
193If signal processing is enabled (@code{@value{RPREFIX}ASR}), then signals
194sent to the task will be processed the next time the task executes.  If
195signal processing is disabled (@code{@value{RPREFIX}NO_ASR}), then all
196signals received by the task will remain posted until signal processing is
197enabled.  This component affects only tasks which have established a
198routine to process asynchronous signals.
199
200@cindex interrupt level, task
201
202The interrupt level component is used to determine which
203interrupts will be enabled when the task is executing.
204@code{@value{RPREFIX}INTERRUPT_LEVEL(n)}
205specifies that the task will execute at interrupt level n.
206
207@itemize  @bullet
208@item @code{@value{RPREFIX}PREEMPT} - enable preemption (default)
209@item @code{@value{RPREFIX}NO_PREEMPT} - disable preemption
210@item @code{@value{RPREFIX}NO_TIMESLICE} - disable timeslicing (default)
211@item @code{@value{RPREFIX}TIMESLICE} - enable timeslicing
212@item @code{@value{RPREFIX}ASR} - enable ASR processing (default)
213@item @code{@value{RPREFIX}NO_ASR} - disable ASR processing
214@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} - enable all interrupts (default)
215@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} - execute at interrupt level n
216@end itemize
217
218The set of default modes may be selected by specifying the
219@code{@value{RPREFIX}DEFAULT_MODES} constant.
220
221@subsection Accessing Task Arguments
222
223@cindex task arguments
224@cindex task prototype
225
226All RTEMS tasks are invoked with a single argument which is
227specified when they are started or restarted.  The argument is
228commonly used to communicate startup information to the task.
229The simplest manner in which to define a task which accesses it
230argument is:
231
232@ifset is-C
233@findex rtems_task
234
235@example
236rtems_task user_task(
237  rtems_task_argument argument
238);
239@end example
240@end ifset
241
242@ifset is-Ada
243@example
244procedure User_Task (
245  Argument : in    RTEMS.Task_Argument_Ptr
246);
247@end example
248@end ifset
249
250Application tasks requiring more information may view this
251single argument as an index into an array of parameter blocks.
252
253@subsection Floating Point Considerations
254
255@cindex floating point
256
257Creating a task with the @code{@value{RPREFIX}FLOATING_POINT} attribute
258flag results
259in additional memory being allocated for the TCB to store the state of the
260numeric coprocessor during task switches.  This additional memory is
261@b{NOT} allocated for @code{@value{RPREFIX}NO_FLOATING_POINT} tasks. Saving
262and restoring the context of a @code{@value{RPREFIX}FLOATING_POINT} task
263takes longer than that of a @code{@value{RPREFIX}NO_FLOATING_POINT} task
264because of the relatively large amount of time required for the numeric
265coprocessor to save or restore its computational state.
266
267Since RTEMS was designed specifically for embedded military applications
268which are floating point intensive, the executive is optimized to avoid
269unnecessarily saving and restoring the state of the numeric coprocessor.
270The state of the numeric coprocessor is only saved when a
271@code{@value{RPREFIX}FLOATING_POINT} task is dispatched and that task was
272not the last task to utilize the coprocessor.  In a system with only one
273@code{@value{RPREFIX}FLOATING_POINT} task, the state of the numeric
274coprocessor will never be saved or restored.
275
276Although the overhead imposed by @code{@value{RPREFIX}FLOATING_POINT} tasks
277is minimal, some applications may wish to completely avoid the overhead
278associated with @code{@value{RPREFIX}FLOATING_POINT} tasks and still
279utilize a numeric coprocessor.  By preventing a task from being preempted
280while performing a sequence of floating point operations, a
281@code{@value{RPREFIX}NO_FLOATING_POINT} task can utilize the numeric
282coprocessor without incurring the overhead of a
283@code{@value{RPREFIX}FLOATING_POINT} context switch.  This approach also
284avoids the allocation of a floating point context area.  However, if this
285approach is taken by the application designer, NO tasks should be created
286as @code{@value{RPREFIX}FLOATING_POINT} tasks.  Otherwise, the floating
287point context will not be correctly maintained because RTEMS assumes that
288the state of the numeric coprocessor will not be altered by
289@code{@value{RPREFIX}NO_FLOATING_POINT} tasks.
290
291If the supported processor type does not have hardware floating
292capabilities or a standard numeric coprocessor, RTEMS will not provide
293built-in support for hardware floating point on that processor.  In this
294case, all tasks are considered @code{@value{RPREFIX}NO_FLOATING_POINT}
295whether created as @code{@value{RPREFIX}FLOATING_POINT} or
296@code{@value{RPREFIX}NO_FLOATING_POINT} tasks.  A floating point emulation
297software library must be utilized for floating point operations.
298
299On some processors, it is possible to disable the floating point unit
300dynamically.  If this capability is supported by the target processor, then
301RTEMS will utilize this capability to enable the floating point unit only
302for tasks which are created with the @code{@value{RPREFIX}FLOATING_POINT}
303attribute.  The consequence of a @code{@value{RPREFIX}NO_FLOATING_POINT}
304task attempting to access the floating point unit is CPU dependent but will
305generally result in an exception condition.
306
307@subsection Per Task Variables
308
309@cindex per task variables
310
311Per task variables are deprecated, see the warning below.
312
313Per task variables are used to support global variables whose value
314may be unique to a task. After indicating that a variable should be
315treated as private (i.e. per-task) the task can access and modify the
316variable, but the modifications will not appear to other tasks, and
317other tasks' modifications to that variable will not affect the value
318seen by the task.  This is accomplished by saving and restoring the
319variable's value each time a task switch occurs to or from the calling task.
320
321The value seen by other tasks, including those which have not added the
322variable to their set and are thus accessing the variable as a common
323location shared among tasks, cannot be affected by a task once it has
324added a variable to its local set.  Changes made to the variable by
325other tasks will not affect the value seen by a task which has added the
326variable to its private set.
327
328This feature can be used when a routine is to be spawned repeatedly as
329several independent tasks.  Although each task will have its own stack,
330and thus separate stack variables, they will all share the same static and
331global variables.  To make a variable not shareable (i.e. a "global" variable
332that is specific to a single task), the tasks can call
333@code{rtems_task_variable_add} to make a separate copy of the variable
334for each task, but all at the same physical address.
335
336Task variables increase the context switch time to and from the
337tasks that own them so it is desirable to minimize the number of
338task variables.  One efficient method is to have a single task
339variable that is a pointer to a dynamically allocated structure
340containing the task's private "global" data.
341
342A critical point with per-task variables is that each task must separately
343request that the same global variable is per-task private.
344
345@b{WARNING}: Per-Task variables are inherently broken on SMP systems. They
346only work correctly when there is one task executing in the system and
347that task is the logical owner of the value in the per-task variable's
348location. There is no way for a single memory image to contain the
349correct value for each task executing on each core. Consequently,
350per-task variables are disabled in SMP configurations of RTEMS.
351Instead the application developer should
352consider the use of POSIX Keys or Thread Local Storage (TLS). POSIX Keys
353are not enabled in all RTEMS configurations.
354
355@subsection Building a Task Attribute Set
356
357@cindex task attributes, building
358
359In general, an attribute set is built by a bitwise OR of the
360desired components.  The set of valid task attribute components
361is listed below:
362
363@itemize @bullet
364@item @code{@value{RPREFIX}NO_FLOATING_POINT} - does not use coprocessor (default)
365@item @code{@value{RPREFIX}FLOATING_POINT} - uses numeric coprocessor
366@item @code{@value{RPREFIX}LOCAL} - local task (default)
367@item @code{@value{RPREFIX}GLOBAL} - global task
368@end itemize
369
370Attribute values are specifically designed to be mutually
371exclusive, therefore bitwise OR and addition operations are
372equivalent as long as each attribute appears exactly once in the
373component list.  A component listed as a default is not required
374to appear in the component list, although it is a good
375programming practice to specify default components.  If all
376defaults are desired, then @code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be used.
377
378This example demonstrates the attribute_set parameter needed to
379create a local task which utilizes the numeric coprocessor.  The
380attribute_set parameter could be @code{@value{RPREFIX}FLOATING_POINT} or
381@code{@value{RPREFIX}LOCAL @value{OR} @value{RPREFIX}FLOATING_POINT}. 
382The attribute_set parameter can be set to
383@code{@value{RPREFIX}FLOATING_POINT} because @code{@value{RPREFIX}LOCAL} is the default for all created
384tasks.  If the task were global and used the numeric
385coprocessor, then the attribute_set parameter would be
386@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}FLOATING_POINT}.
387
388@subsection Building a Mode and Mask
389
390@cindex task mode, building
391
392In general, a mode and its corresponding mask is built by a
393bitwise OR of the desired components.  The set of valid mode
394constants and each mode's corresponding mask constant is
395listed below:
396
397@ifset use-ascii
398@itemize @bullet
399@item @code{@value{RPREFIX}PREEMPT} is masked by
400@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
401
402@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
403@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
404
405@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
406@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
407
408@item @code{@value{RPREFIX}TIMESLICE} is masked by
409@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
410
411@item @code{@value{RPREFIX}ASR} is masked by
412@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
413
414@item @code{@value{RPREFIX}NO_ASR} is masked by
415@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
416
417@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
418@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
419
420@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
421@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
422@end itemize
423@end ifset
424
425@ifset use-tex
426@sp 1
427@c this is temporary
428@itemize @bullet
429@item @code{@value{RPREFIX}PREEMPT} is masked by
430@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
431
432@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
433@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
434
435@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
436@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
437
438@item @code{@value{RPREFIX}TIMESLICE} is masked by
439@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
440
441@item @code{@value{RPREFIX}ASR} is masked by
442@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
443
444@item @code{@value{RPREFIX}NO_ASR} is masked by
445@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
446
447@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
448@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
449
450@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
451@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
452 
453@end itemize
454
455@tex
456@end tex
457@end ifset
458
459@ifset use-html
460@html
461<CENTER>
462  <TABLE COLS=3 WIDTH="80%" BORDER=2>
463<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
464    <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
465    <TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
466<TR><TD ALIGN=center>@value{RPREFIX}PREEMPT</TD>
467    <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
468    <TD ALIGN=center>enables preemption</TD></TR>
469<TR><TD ALIGN=center>@value{RPREFIX}NO_PREEMPT</TD>
470    <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
471    <TD ALIGN=center>disables preemption</TD></TR>
472<TR><TD ALIGN=center>@value{RPREFIX}NO_TIMESLICE</TD>
473    <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
474    <TD ALIGN=center>disables timeslicing</TD></TR>
475<TR><TD ALIGN=center>@value{RPREFIX}TIMESLICE</TD>
476    <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
477    <TD ALIGN=center>enables timeslicing</TD></TR>
478<TR><TD ALIGN=center>@value{RPREFIX}ASR</TD>
479    <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
480    <TD ALIGN=center>enables ASR processing</TD></TR>
481<TR><TD ALIGN=center>@value{RPREFIX}NO_ASR</TD>
482    <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
483    <TD ALIGN=center>disables ASR processing</TD></TR>
484<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(0)</TD>
485    <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
486    <TD ALIGN=center>enables all interrupts</TD></TR>
487<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(n)</TD>
488    <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
489    <TD ALIGN=center>sets interrupts level n</TD></TR>
490  </TABLE>
491</CENTER>
492@end html
493@end ifset
494
495Mode values are specifically designed to be mutually exclusive, therefore
496bitwise OR and addition operations are equivalent as long as each mode
497appears exactly once in the component list.  A mode component listed as a
498default is not required to appear in the mode component list, although it
499is a good programming practice to specify default components.  If all
500defaults are desired, the mode @code{@value{RPREFIX}DEFAULT_MODES} and the
501mask @code{@value{RPREFIX}ALL_MODE_MASKS} should be used.
502
503The following example demonstrates the mode and mask parameters used with
504the @code{@value{DIRPREFIX}task_mode}
505directive to place a task at interrupt level 3 and make it
506non-preemptible.  The mode should be set to
507@code{@value{RPREFIX}INTERRUPT_LEVEL(3)  @value{OR}
508@value{RPREFIX}NO_PREEMPT} to indicate the desired preemption mode and
509interrupt level, while the mask parameter should be set to
510@code{@value{RPREFIX}INTERRUPT_MASK @value{OR}
511@value{RPREFIX}NO_PREEMPT_MASK} to indicate that the calling task's
512interrupt level and preemption mode are being altered.
513
514@section Operations
515
516@subsection Creating Tasks
517
518The @code{@value{DIRPREFIX}task_create}
519directive creates a task by allocating a task
520control block, assigning the task a user-specified name,
521allocating it a stack and floating point context area, setting a
522user-specified initial priority, setting a user-specified
523initial mode, and assigning it a task ID.  Newly created tasks
524are initially placed in the dormant state.  All RTEMS tasks
525execute in the most privileged mode of the processor.
526
527@subsection Obtaining Task IDs
528
529When a task is created, RTEMS generates a unique task ID and
530assigns it to the created task until it is deleted.  The task ID
531may be obtained by either of two methods.  First, as the result
532of an invocation of the @code{@value{DIRPREFIX}task_create}
533directive, the task ID is
534stored in a user provided location.  Second, the task ID may be
535obtained later using the @code{@value{DIRPREFIX}task_ident}
536directive.  The task ID is
537used by other directives to manipulate this task.
538
539@subsection Starting and Restarting Tasks
540
541The @code{@value{DIRPREFIX}task_start}
542directive is used to place a dormant task in the
543ready state.  This enables the task to compete, based on its
544current priority, for the processor and other system resources.
545Any actions, such as suspension or change of priority, performed
546on a task prior to starting it are nullified when the task is
547started.
548
549With the @code{@value{DIRPREFIX}task_start}
550directive the user specifies the task's
551starting address and argument.  The argument is used to
552communicate some startup information to the task.  As part of
553this directive, RTEMS initializes the task's stack based upon
554the task's initial execution mode and start address.  The
555starting argument is passed to the task in accordance with the
556target processor's calling convention.
557
558The @code{@value{DIRPREFIX}task_restart}
559directive restarts a task at its initial
560starting address with its original priority and execution mode,
561but with a possibly different argument.  The new argument may be
562used to distinguish between the original invocation of the task
563and subsequent invocations.  The task's stack and control block
564are modified to reflect their original creation values.
565Although references to resources that have been requested are
566cleared, resources allocated by the task are NOT automatically
567returned to RTEMS.  A task cannot be restarted unless it has
568previously been started (i.e. dormant tasks cannot be
569restarted).  All restarted tasks are placed in the ready state.
570
571@subsection Suspending and Resuming Tasks
572
573The @code{@value{DIRPREFIX}task_suspend}
574directive is used to place either the caller or
575another task into a suspended state.  The task remains suspended
576until a @code{@value{DIRPREFIX}task_resume}
577directive is issued.  This implies that a
578task may be suspended as well as blocked waiting either to
579acquire a resource or for the expiration of a timer.
580
581The @code{@value{DIRPREFIX}task_resume}
582directive is used to remove another task from
583the suspended state. If the task is not also blocked, resuming
584it will place it in the ready state, allowing it to once again
585compete for the processor and resources.  If the task was
586blocked as well as suspended, this directive clears the
587suspension and leaves the task in the blocked state.
588
589Suspending a task which is already suspended or resuming a
590task which is not suspended is considered an error.
591The @code{@value{DIRPREFIX}task_is_suspended} can be used to
592determine if a task is currently suspended.
593
594@subsection Delaying the Currently Executing Task
595
596The @code{@value{DIRPREFIX}task_wake_after} directive creates a sleep timer
597which allows a task to go to sleep for a specified interval.  The task is
598blocked until the delay interval has elapsed, at which time the task is
599unblocked.  A task calling the @code{@value{DIRPREFIX}task_wake_after}
600directive with a delay
601interval of @code{@value{RPREFIX}YIELD_PROCESSOR} ticks will yield the
602processor to any other ready task of equal or greater priority and remain
603ready to execute.
604
605The @code{@value{DIRPREFIX}task_wake_when}
606directive creates a sleep timer which allows
607a task to go to sleep until a specified date and time.  The
608calling task is blocked until the specified date and time has
609occurred, at which time the task is unblocked.
610
611@subsection Changing Task Priority
612
613The @code{@value{DIRPREFIX}task_set_priority}
614directive is used to obtain or change the
615current priority of either the calling task or another task.  If
616the new priority requested is
617@code{@value{RPREFIX}CURRENT_PRIORITY} or the task's
618actual priority, then the current priority will be returned and
619the task's priority will remain unchanged.  If the task's
620priority is altered, then the task will be scheduled according
621to its new priority.
622
623The @code{@value{DIRPREFIX}task_restart}
624directive resets the priority of a task to its
625original value.
626
627@subsection Changing Task Mode
628
629The @code{@value{DIRPREFIX}task_mode}
630directive is used to obtain or change the current
631execution mode of the calling task.  A task's execution mode is
632used to enable preemption, timeslicing, ASR processing, and to
633set the task's interrupt level. 
634
635The @code{@value{DIRPREFIX}task_restart}
636directive resets the mode of a task to its
637original value.
638
639@subsection Notepad Locations
640
641RTEMS provides sixteen notepad locations for each task.  Each
642notepad location may contain a note consisting of four bytes of
643information.  RTEMS provides two directives,
644@code{@value{DIRPREFIX}task_set_note} and
645@code{@value{DIRPREFIX}task_get_note}, that enable a user
646to access and change the
647notepad locations.  The @code{@value{DIRPREFIX}task_set_note}
648directive enables the user
649to set a task's notepad entry to a specified note.  The
650@code{@value{DIRPREFIX}task_get_note}
651directive allows the user to obtain the note
652contained in any one of the sixteen notepads of a specified task.
653Notepads are deprecated and will be removed.
654
655@subsection Task Deletion
656
657RTEMS provides the @code{@value{DIRPREFIX}task_delete}
658directive to allow a task to
659delete itself or any other task.  This directive removes all
660RTEMS references to the task, frees the task's control block,
661removes it from resource wait queues, and deallocates its stack
662as well as the optional floating point context.  The task's name
663and ID become inactive at this time, and any subsequent
664references to either of them is invalid.  In fact, RTEMS may
665reuse the task ID for another task which is created later in the
666application.
667
668Unexpired delay timers (i.e. those used by
669@code{@value{DIRPREFIX}task_wake_after} and
670@code{@value{DIRPREFIX}task_wake_when}) and
671timeout timers associated with the task are
672automatically deleted, however, other resources dynamically
673allocated by the task are NOT automatically returned to RTEMS.
674Therefore, before a task is deleted, all of its dynamically
675allocated resources should be deallocated by the user.  This may
676be accomplished by instructing the task to delete itself rather
677than directly deleting the task.  Other tasks may instruct a
678task to delete itself by sending a "delete self" message, event,
679or signal, or by restarting the task with special arguments
680which instruct the task to delete itself.
681
682@section Directives
683
684This section details the task manager's directives.  A
685subsection is dedicated to each of this manager's directives and
686describes the calling sequence, related constants, usage, and
687status codes.
688
689@page
690
691@subsection TASK_CREATE - Create a task
692
693@cindex create a task
694
695@subheading CALLING SEQUENCE:
696
697@ifset is-C
698@findex rtems_task_create
699@example
700rtems_status_code rtems_task_create(
701  rtems_name           name,
702  rtems_task_priority  initial_priority,
703  size_t               stack_size,
704  rtems_mode           initial_modes,
705  rtems_attribute      attribute_set,
706  rtems_id            *id
707);
708@end example
709@end ifset
710
711@ifset is-Ada
712@example
713procedure Task_Create (
714   Name             : in     RTEMS.Name;
715   Initial_Priority : in     RTEMS.Task_Priority;
716   Stack_Size       : in     RTEMS.Unsigned32;
717   Initial_Modes    : in     RTEMS.Mode;
718   Attribute_Set    : in     RTEMS.Attribute;
719   ID               :    out RTEMS.ID;
720   Result           :    out RTEMS.Status_Codes
721);
722@end example
723@end ifset
724
725@subheading DIRECTIVE STATUS CODES:
726@code{@value{RPREFIX}SUCCESSFUL} - task created successfully@*
727@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
728@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
729@code{@value{RPREFIX}INVALID_PRIORITY} - invalid task priority@*
730@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@*
731@code{@value{RPREFIX}TOO_MANY} - too many tasks created@*
732@code{@value{RPREFIX}UNSATISFIED} - not enough memory for stack/FP context@*
733@code{@value{RPREFIX}TOO_MANY} - too many global objects
734
735@subheading DESCRIPTION:
736This directive creates a task which resides on the local node.
737It allocates and initializes a TCB, a stack, and an optional
738floating point context area.  The mode parameter contains values
739which sets the task's initial execution mode.  The
740@code{@value{RPREFIX}FLOATING_POINT} attribute should be
741specified if the created task
742is to use a numeric coprocessor.  For performance reasons, it is
743recommended that tasks not using the numeric coprocessor should
744specify the @code{@value{RPREFIX}NO_FLOATING_POINT} attribute. 
745If the @code{@value{RPREFIX}GLOBAL}
746attribute is specified, the task can be accessed from remote
747nodes.  The task id, returned in id, is used in other task
748related directives to access the task.  When created, a task is
749placed in the dormant state and can only be made ready to
750execute using the directive @code{@value{DIRPREFIX}task_start}.
751
752@subheading NOTES:
753This directive will not cause the calling task to be preempted.
754
755Valid task priorities range from a high of 1 to a low of 255.
756
757If the requested stack size is less than the configured
758minimum stack size, then RTEMS will use the configured
759minimum as the stack size for this task.  In addition
760to being able to specify the task stack size as a integer,
761there are two constants which may be specified:
762
763@itemize @bullet
764@item @code{@value{RPREFIX}MINIMUM_STACK_SIZE}
765is the minimum stack size @b{RECOMMENDED} for use on this processor.
766This value is selected by the RTEMS developers conservatively to
767minimize the risk of blown stacks for most user applications.
768Using this constant when specifying the task stack size, indicates
769that the stack size will be at least
770@code{@value{RPREFIX}MINIMUM_STACK_SIZE} bytes in size.  If the
771user configured minimum stack size is larger than the recommended
772minimum, then it will be used.
773
774@item @code{@value{RPREFIX}CONFIGURED_MINIMUM_STACK_SIZE}
775indicates that this task is to be created with a stack size
776of the minimum stack size that was configured by the application.
777If not explicitly configured by the application, the default
778configured minimum stack size is the processor dependent value
779@code{@value{RPREFIX}MINIMUM_STACK_SIZE}.  Since this uses
780the configured minimum stack size value, you may get a stack
781size that is smaller or larger than the recommended minimum.  This
782can be used to provide large stacks for all tasks on complex
783applications or small stacks on applications that are trying
784to conserve memory.
785
786@end itemize
787
788Application developers should consider the stack usage of the
789device drivers when calculating the stack size required for
790tasks which utilize the driver.
791
792The following task attribute constants are defined by RTEMS:
793
794@itemize @bullet
795@item @code{@value{RPREFIX}NO_FLOATING_POINT} - does not use coprocessor (default)
796@item @code{@value{RPREFIX}FLOATING_POINT} - uses numeric coprocessor
797@item @code{@value{RPREFIX}LOCAL} - local task (default)
798@item @code{@value{RPREFIX}GLOBAL} - global task
799@end itemize
800
801The following task mode constants are defined by RTEMS:
802
803@itemize  @bullet
804@item @code{@value{RPREFIX}PREEMPT} - enable preemption (default)
805@item @code{@value{RPREFIX}NO_PREEMPT} - disable preemption
806@item @code{@value{RPREFIX}NO_TIMESLICE} - disable timeslicing (default)
807@item @code{@value{RPREFIX}TIMESLICE} - enable timeslicing
808@item @code{@value{RPREFIX}ASR} - enable ASR processing (default)
809@item @code{@value{RPREFIX}NO_ASR} - disable ASR processing
810@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} - enable all interrupts (default)
811@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} - execute at interrupt level n
812@end itemize
813
814The interrupt level portion of the task execution mode
815supports a maximum of 256 interrupt levels.  These levels are
816mapped onto the interrupt levels actually supported by the
817target processor in a processor dependent fashion.
818
819Tasks should not be made global unless remote tasks must
820interact with them.  This avoids the system overhead incurred by
821the creation of a global task.  When a global task is created,
822the task's name and id must be transmitted to every node in the
823system for insertion in the local copy of the global object
824table.
825
826The total number of global objects, including tasks, is limited
827by the maximum_global_objects field in the Configuration Table.
828
829@page
830
831@subsection TASK_IDENT - Get ID of a task
832
833@cindex get ID of a task
834
835@subheading CALLING SEQUENCE:
836
837@ifset is-C
838@findex rtems_task_ident
839@example
840rtems_status_code rtems_task_ident(
841  rtems_name  name,
842  uint32_t    node,
843  rtems_id   *id
844);
845@end example
846@end ifset
847
848@ifset is-Ada
849@example
850procedure Task_Ident (
851   Name   : in     RTEMS.Name;
852   Node   : in     RTEMS.Node;
853   ID     :    out RTEMS.ID;
854   Result :    out RTEMS.Status_Codes
855);
856@end example
857@end ifset
858
859@subheading DIRECTIVE STATUS CODES:
860@code{@value{RPREFIX}SUCCESSFUL} - task identified successfully@*
861@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
862@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
863@code{@value{RPREFIX}INVALID_NODE} - invalid node id
864
865@subheading DESCRIPTION:
866This directive obtains the task id associated with the task name
867specified in name.  A task may obtain its own id by specifying
868@code{@value{RPREFIX}SELF} or its own task name in name.  If the task name is not
869unique, then the task id returned will match one of the tasks
870with that name.  However, this task id is not guaranteed to
871correspond to the desired task.  The task id, returned in id, is
872used in other task related directives to access the task.
873
874@subheading NOTES:
875This directive will not cause the running task to be preempted.
876
877If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched with the
878local node being searched first.  All other nodes are searched
879with the lowest numbered node searched first.
880
881If node is a valid node number which does not represent the
882local node, then only the tasks exported by the designated node
883are searched.
884
885This directive does not generate activity on remote nodes.  It
886accesses only the local copy of the global object table.
887
888@page
889
890@subsection TASK_SELF - Obtain ID of caller
891
892@cindex obtain ID of caller
893
894@subheading CALLING SEQUENCE:
895
896@ifset is-C
897@findex rtems_task_self
898@example
899rtems_id rtems_task_self(void);
900@end example
901@end ifset
902
903@ifset is-Ada
904@example
905function Task_Self return RTEMS.ID;
906@end example
907@end ifset
908
909@subheading DIRECTIVE STATUS CODES:
910Returns the object Id of the calling task.
911
912@subheading DESCRIPTION:
913This directive returns the Id of the calling task.
914
915@subheading NOTES:
916If called from an interrupt service routine, this directive
917will return the Id of the interrupted task.
918
919@page
920
921@subsection TASK_START - Start a task
922
923@cindex starting a task
924
925@subheading CALLING SEQUENCE:
926
927@ifset is-C
928@findex rtems_task_start
929@example
930rtems_status_code rtems_task_start(
931  rtems_id            id,
932  rtems_task_entry    entry_point,
933  rtems_task_argument argument
934);
935@end example
936@end ifset
937
938@ifset is-Ada
939@example
940procedure Task_Start (
941   ID          : in     RTEMS.ID;
942   Entry_Point : in     RTEMS.Task_Entry;
943   Argument    : in     RTEMS.Task_Argument;
944   Result      :    out RTEMS.Status_Codes
945);
946@end example
947@end ifset
948
949@subheading DIRECTIVE STATUS CODES:
950@code{@value{RPREFIX}SUCCESSFUL} - ask started successfully@*
951@code{@value{RPREFIX}INVALID_ADDRESS} - invalid task entry point@*
952@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
953@code{@value{RPREFIX}INCORRECT_STATE} - task not in the dormant state@*
954@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot start remote task
955
956@subheading DESCRIPTION:
957This directive readies the task, specified by @code{id}, for execution
958based on the priority and execution mode specified when the task
959was created.  The starting address of the task is given in
960@code{entry_point}.  The task's starting argument is contained in
961argument.  This argument can be a single value or used as an index into an
962array of parameter blocks.  The type of this numeric argument is an unsigned
963integer type with the property that any valid pointer to void can be converted
964to this type and then converted back to a pointer to void.  The result will
965compare equal to the original pointer.
966
967@subheading NOTES:
968The calling task will be preempted if its preemption mode is
969enabled and the task being started has a higher priority.
970
971Any actions performed on a dormant task such as suspension or
972change of priority are nullified when the task is initiated via
973the @code{@value{DIRPREFIX}task_start} directive.
974
975@page
976
977@subsection TASK_RESTART - Restart a task
978
979@cindex restarting a task
980
981@subheading CALLING SEQUENCE:
982
983@ifset is-C
984@findex rtems_task_restart
985@example
986rtems_status_code rtems_task_restart(
987  rtems_id            id,
988  rtems_task_argument argument
989);
990@end example
991@end ifset
992
993@ifset is-Ada
994@example
995procedure Task_Restart (
996   ID       : in     RTEMS.ID;
997   Argument : in     RTEMS.Task_Argument;
998   Result   :    out RTEMS.Status_Codes
999);
1000@end example
1001@end ifset
1002
1003@subheading DIRECTIVE STATUS CODES:
1004@code{@value{RPREFIX}SUCCESSFUL} - task restarted successfully@*
1005@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1006@code{@value{RPREFIX}INCORRECT_STATE} - task never started@*
1007@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task
1008
1009@subheading DESCRIPTION:
1010This directive resets the task specified by id to begin
1011execution at its original starting address.  The task's priority
1012and execution mode are set to the original creation values.  If
1013the task is currently blocked, RTEMS automatically makes the
1014task ready.  A task can be restarted from any state, except the
1015dormant state.
1016
1017The task's starting argument is contained in argument.  This argument can be a
1018single value or an index into an array of parameter blocks.  The type of this
1019numeric argument is an unsigned integer type with the property that any valid
1020pointer to void can be converted to this type and then converted back to a
1021pointer to void.  The result will compare equal to the original pointer.  This
1022new argument may be used to distinguish
1023between the initial @code{@value{DIRPREFIX}task_start}
1024of the task and any ensuing calls
1025to @code{@value{DIRPREFIX}task_restart}
1026of the task.  This can be beneficial in deleting
1027a task.  Instead of deleting a task using
1028the @code{@value{DIRPREFIX}task_delete}
1029directive, a task can delete another task by restarting that
1030task, and allowing that task to release resources back to RTEMS
1031and then delete itself.
1032
1033@subheading NOTES:
1034If id is @code{@value{RPREFIX}SELF}, the calling task will be restarted and will not
1035return from this directive.
1036
1037The calling task will be preempted if its preemption mode is
1038enabled and the task being restarted has a higher priority.
1039
1040The task must reside on the local node, even if the task was
1041created with the @code{@value{RPREFIX}GLOBAL} option.
1042
1043@page
1044
1045@subsection TASK_DELETE - Delete a task
1046
1047@cindex deleting a task
1048
1049@subheading CALLING SEQUENCE:
1050
1051@ifset is-C
1052@findex rtems_task_delete
1053@example
1054rtems_status_code rtems_task_delete(
1055  rtems_id id
1056);
1057@end example
1058@end ifset
1059
1060@ifset is-Ada
1061@example
1062procedure Task_Delete (
1063   ID     : in     RTEMS.ID;
1064   Result :    out RTEMS.Status_Codes
1065);
1066@end example
1067@end ifset
1068
1069@subheading DIRECTIVE STATUS CODES:
1070@code{@value{RPREFIX}SUCCESSFUL} - task deleted successfully@*
1071@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1072@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task
1073
1074@subheading DESCRIPTION:
1075This directive deletes a task, either the calling task or
1076another task, as specified by id.  RTEMS stops the execution of
1077the task and reclaims the stack memory, any allocated delay or
1078timeout timers, the TCB, and, if the task is @code{@value{RPREFIX}FLOATING_POINT}, its
1079floating point context area.  RTEMS does not reclaim the
1080following resources: region segments, partition buffers,
1081semaphores, timers, or rate monotonic periods.
1082
1083@subheading NOTES:
1084A task is responsible for releasing its resources back to RTEMS
1085before deletion.  To insure proper deallocation of resources, a
1086task should not be deleted unless it is unable to execute or
1087does not hold any RTEMS resources.  If a task holds RTEMS
1088resources, the task should be allowed to deallocate its
1089resources before deletion.  A task can be directed to release
1090its resources and delete itself by restarting it with a special
1091argument or by sending it a message, an event, or a signal.
1092
1093Deletion of the current task (@code{@value{RPREFIX}SELF}) will force RTEMS to select
1094another task to execute.
1095
1096When a global task is deleted, the task id must be transmitted
1097to every node in the system for deletion from the local copy of
1098the global object table.
1099
1100The task must reside on the local node, even if the task was
1101created with the @code{@value{RPREFIX}GLOBAL} option.
1102
1103@page
1104
1105@subsection TASK_SUSPEND - Suspend a task
1106
1107@cindex suspending a task
1108
1109@subheading CALLING SEQUENCE:
1110
1111@ifset is-C
1112@findex rtems_task_suspend
1113@example
1114rtems_status_code rtems_task_suspend(
1115  rtems_id id
1116);
1117@end example
1118@end ifset
1119
1120@ifset is-Ada
1121@example
1122procedure Task_Suspend (
1123   ID     : in     RTEMS.ID;
1124   Result :    out RTEMS.Status_Codes
1125);
1126@end example
1127@end ifset
1128
1129@subheading DIRECTIVE STATUS CODES:
1130@code{@value{RPREFIX}SUCCESSFUL} - task suspended successfully@*
1131@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1132@code{@value{RPREFIX}ALREADY_SUSPENDED} - task already suspended
1133
1134@subheading DESCRIPTION:
1135This directive suspends the task specified by id from further
1136execution by placing it in the suspended state.  This state is
1137additive to any other blocked state that the task may already be
1138in.  The task will not execute again until another task issues
1139the @code{@value{DIRPREFIX}task_resume}
1140directive for this task and any blocked state
1141has been removed.
1142
1143@subheading NOTES:
1144The requesting task can suspend itself by specifying @code{@value{RPREFIX}SELF} as id.
1145In this case, the task will be suspended and a successful
1146return code will be returned when the task is resumed.
1147
1148Suspending a global task which does not reside on the local node
1149will generate a request to the remote node to suspend the
1150specified task.
1151
1152If the task specified by id is already suspended, then the
1153@code{@value{RPREFIX}ALREADY_SUSPENDED} status code is returned.
1154
1155@page
1156
1157@subsection TASK_RESUME - Resume a task
1158
1159@cindex resuming a task
1160
1161@subheading CALLING SEQUENCE:
1162
1163@ifset is-C
1164@findex rtems_task_resume
1165@example
1166rtems_status_code rtems_task_resume(
1167  rtems_id id
1168);
1169@end example
1170@end ifset
1171
1172@ifset is-Ada
1173@example
1174procedure Task_Resume (
1175   ID     : in     RTEMS.ID;
1176   Result :    out RTEMS.Status_Codes
1177);
1178@end example
1179@end ifset
1180
1181@subheading DIRECTIVE STATUS CODES:
1182@code{@value{RPREFIX}SUCCESSFUL} - task resumed successfully@*
1183@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1184@code{@value{RPREFIX}INCORRECT_STATE} - task not suspended
1185
1186@subheading DESCRIPTION:
1187This directive removes the task specified by id from the
1188suspended state.  If the task is in the ready state after the
1189suspension is removed, then it will be scheduled to run.  If the
1190task is still in a blocked state after the suspension is
1191removed, then it will remain in that blocked state.
1192
1193@subheading NOTES:
1194The running task may be preempted if its preemption mode is
1195enabled and the local task being resumed has a higher priority.
1196
1197Resuming a global task which does not reside on the local node
1198will generate a request to the remote node to resume the
1199specified task.
1200
1201If the task specified by id is not suspended, then the
1202@code{@value{RPREFIX}INCORRECT_STATE} status code is returned.
1203
1204@page
1205
1206@subsection TASK_IS_SUSPENDED - Determine if a task is Suspended
1207
1208@cindex is task suspended
1209
1210@subheading CALLING SEQUENCE:
1211
1212@ifset is-C
1213@findex rtems_task_is_suspended
1214@example
1215rtems_status_code rtems_task_is_suspended(
1216  rtems_id id
1217);
1218@end example
1219@end ifset
1220
1221@ifset is-Ada
1222@example
1223procedure Task_Is_Suspended (
1224   ID     : in     RTEMS.ID;
1225   Result :    out RTEMS.Status_Codes
1226);
1227@end example
1228@end ifset
1229
1230@subheading DIRECTIVE STATUS CODES:
1231@code{@value{RPREFIX}SUCCESSFUL} - task is NOT suspended@*
1232@code{@value{RPREFIX}ALREADY_SUSPENDED} - task is currently suspended@*
1233@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1234@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks
1235
1236@subheading DESCRIPTION:
1237
1238This directive returns a status code indicating whether or
1239not the specified task is currently suspended.
1240
1241@subheading NOTES:
1242
1243This operation is not currently supported on remote tasks.
1244
1245@page
1246
1247@subsection TASK_SET_PRIORITY - Set task priority
1248
1249@findex rtems_task_set_priority
1250@cindex current task priority
1251@cindex set task priority
1252@cindex get task priority
1253@cindex obtain task priority
1254
1255@subheading CALLING SEQUENCE:
1256
1257@ifset is-C
1258@example
1259rtems_status_code rtems_task_set_priority(
1260  rtems_id             id,
1261  rtems_task_priority  new_priority,
1262  rtems_task_priority *old_priority
1263);
1264@end example
1265@end ifset
1266
1267@ifset is-Ada
1268@example
1269procedure Task_Set_Priority (
1270   ID           : in     RTEMS.ID;
1271   New_Priority : in     RTEMS.Task_Priority;
1272   Old_Priority :    out RTEMS.Task_Priority;
1273   Result       :    out RTEMS.Status_Codes
1274);
1275@end example
1276@end ifset
1277
1278@subheading DIRECTIVE STATUS CODES:
1279@code{@value{RPREFIX}SUCCESSFUL} - task priority set successfully@*
1280@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1281@code{@value{RPREFIX}INVALID_ADDRESS} - invalid return argument pointer@*
1282@code{@value{RPREFIX}INVALID_PRIORITY} - invalid task priority
1283
1284@subheading DESCRIPTION:
1285This directive manipulates the priority of the task specified by
1286id.  An id of @code{@value{RPREFIX}SELF} is used to indicate
1287the calling task.  When new_priority is not equal to
1288@code{@value{RPREFIX}CURRENT_PRIORITY}, the specified
1289task's previous priority is returned in old_priority.  When
1290new_priority is @code{@value{RPREFIX}CURRENT_PRIORITY},
1291the specified task's current
1292priority is returned in old_priority.  Valid priorities range
1293from a high of 1 to a low of 255.
1294
1295@subheading NOTES:
1296The calling task may be preempted if its preemption mode is
1297enabled and it lowers its own priority or raises another task's
1298priority.
1299
1300In case the new priority equals the current priority of the task, then nothing
1301happens.
1302
1303Setting the priority of a global task which does not reside on
1304the local node will generate a request to the remote node to
1305change the priority of the specified task.
1306
1307If the task specified by id is currently holding any binary
1308semaphores which use the priority inheritance algorithm, then
1309the task's priority cannot be lowered immediately.  If the
1310task's priority were lowered immediately, then priority
1311inversion results.  The requested lowering of the task's
1312priority will occur when the task has released all priority
1313inheritance binary semaphores.  The task's priority can be
1314increased regardless of the task's use of priority inheritance
1315binary semaphores.
1316
1317@page
1318
1319@subsection TASK_MODE - Change the current task mode
1320
1321@cindex current task mode
1322@cindex set task mode
1323@cindex get task mode
1324@cindex set task preemption mode
1325@cindex get task preemption mode
1326@cindex obtain task mode
1327
1328@subheading CALLING SEQUENCE:
1329
1330@ifset is-C
1331@findex rtems_task_mode
1332@example
1333rtems_status_code rtems_task_mode(
1334  rtems_mode  mode_set,
1335  rtems_mode  mask,
1336  rtems_mode *previous_mode_set
1337);
1338@end example
1339@end ifset
1340
1341@ifset is-Ada
1342@example
1343procedure Task_Mode (
1344   Mode_Set          : in     RTEMS.Mode;
1345   Mask              : in     RTEMS.Mode;
1346   Previous_Mode_Set : in     RTEMS.Mode;
1347   Result            :    out RTEMS.Status_Codes
1348);
1349@end example
1350@end ifset
1351
1352@subheading DIRECTIVE STATUS CODES:
1353@code{@value{RPREFIX}SUCCESSFUL} - task mode set successfully@*
1354@code{@value{RPREFIX}INVALID_ADDRESS} - @code{previous_mode_set} is NULL
1355
1356@subheading DESCRIPTION:
1357This directive manipulates the execution mode of the calling
1358task.  A task's execution mode enables and disables preemption,
1359timeslicing, asynchronous signal processing, as well as
1360specifying the current interrupt level.  To modify an execution
1361mode, the mode class(es) to be changed must be specified in the
1362mask parameter and the desired mode(s) must be specified in the
1363mode parameter. 
1364
1365@subheading NOTES:
1366The calling task will be preempted if it enables preemption and
1367a higher priority task is ready to run.
1368
1369Enabling timeslicing has no effect if preemption is disabled.  For
1370a task to be timesliced, that task must have both preemption and
1371timeslicing enabled.
1372
1373A task can obtain its current execution mode, without modifying
1374it, by calling this directive with a mask value of
1375@code{@value{RPREFIX}CURRENT_MODE}.
1376
1377To temporarily disable the processing of a valid ASR, a task
1378should call this directive with the @code{@value{RPREFIX}NO_ASR}
1379indicator specified in mode.
1380
1381The set of task mode constants and each mode's corresponding
1382mask constant is provided in the following table:
1383
1384@ifset use-ascii
1385@itemize @bullet
1386@item @code{@value{RPREFIX}PREEMPT} is masked by
1387@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
1388
1389@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
1390@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
1391
1392@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
1393@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
1394
1395@item @code{@value{RPREFIX}TIMESLICE} is masked by
1396@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
1397
1398@item @code{@value{RPREFIX}ASR} is masked by
1399@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
1400
1401@item @code{@value{RPREFIX}NO_ASR} is masked by
1402@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
1403
1404@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
1405@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
1406
1407@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
1408@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
1409 
1410@end itemize
1411@end ifset
1412 
1413@ifset use-tex
1414@sp 1
1415@c this is temporary
1416@itemize @bullet
1417@item @code{@value{RPREFIX}PREEMPT} is masked by
1418@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
1419
1420@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
1421@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
1422
1423@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
1424@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
1425
1426@item @code{@value{RPREFIX}TIMESLICE} is masked by
1427@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
1428
1429@item @code{@value{RPREFIX}ASR} is masked by
1430@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
1431
1432@item @code{@value{RPREFIX}NO_ASR} is masked by
1433@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
1434
1435@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
1436@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
1437
1438@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
1439@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
1440 
1441@end itemize
1442 
1443@tex
1444@end tex
1445@end ifset
1446 
1447@ifset use-html
1448@html
1449<CENTER>
1450  <TABLE COLS=3 WIDTH="80%" BORDER=2>
1451<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
1452    <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
1453    <TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
1454<TR><TD ALIGN=center>@value{RPREFIX}PREEMPT</TD>
1455    <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
1456    <TD ALIGN=center>enables preemption</TD></TR>
1457<TR><TD ALIGN=center>@value{RPREFIX}NO_PREEMPT</TD>
1458    <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
1459    <TD ALIGN=center>disables preemption</TD></TR>
1460<TR><TD ALIGN=center>@value{RPREFIX}NO_TIMESLICE</TD>
1461    <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
1462    <TD ALIGN=center>disables timeslicing</TD></TR>
1463<TR><TD ALIGN=center>@value{RPREFIX}TIMESLICE</TD>
1464    <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
1465    <TD ALIGN=center>enables timeslicing</TD></TR>
1466<TR><TD ALIGN=center>@value{RPREFIX}ASR</TD>
1467    <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
1468    <TD ALIGN=center>enables ASR processing</TD></TR>
1469<TR><TD ALIGN=center>@value{RPREFIX}NO_ASR</TD>
1470    <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
1471    <TD ALIGN=center>disables ASR processing</TD></TR>
1472<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(0)</TD>
1473    <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
1474    <TD ALIGN=center>enables all interrupts</TD></TR>
1475<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(n)</TD>
1476    <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
1477    <TD ALIGN=center>sets interrupts level n</TD></TR>
1478  </TABLE>
1479</CENTER>
1480@end html
1481@end ifset
1482
1483@page
1484
1485@subsection TASK_GET_NOTE - Get task notepad entry
1486
1487@cindex get task notepad entry
1488
1489@subheading CALLING SEQUENCE:
1490
1491@ifset is-C
1492@findex rtems_task_get_note
1493@example
1494rtems_status_code rtems_task_get_note(
1495  rtems_id  id,
1496  uint32_t  notepad,
1497  uint32_t *note
1498);
1499@end example
1500@end ifset
1501
1502@ifset is-Ada
1503@example
1504procedure Task_Get_Note (
1505   ID      : in     RTEMS.ID;
1506   Notepad : in     RTEMS.Notepad_Index;
1507   Note    :    out RTEMS.Unsigned32;
1508   Result  :    out RTEMS.Status_Codes
1509);
1510@end example
1511@end ifset
1512
1513@subheading DIRECTIVE STATUS CODES:
1514@code{@value{RPREFIX}SUCCESSFUL} - note obtained successfully@*
1515@code{@value{RPREFIX}INVALID_ADDRESS} - @code{note} is NULL@*
1516@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1517@code{@value{RPREFIX}INVALID_NUMBER} - invalid notepad location
1518
1519@subheading DESCRIPTION:
1520This directive returns the note contained in the notepad
1521location of the task specified by id.
1522
1523@subheading NOTES:
1524This directive is deprecated and will be removed.
1525
1526This directive will not cause the running task to be preempted.
1527
1528If id is set to @code{@value{RPREFIX}SELF},
1529the calling task accesses its own notepad.
1530
1531@c This version of the paragraph avoids the overfull hbox error.
1532@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
1533@c sixteen notepad locations.
1534
1535The sixteen notepad locations can be accessed using the constants
1536@code{@value{RPREFIX}NOTEPAD_0} through @code{@value{RPREFIX}NOTEPAD_15}.
1537
1538Getting a note of a global task which does not reside on the
1539local node will generate a request to the remote node to obtain
1540the notepad entry of the specified task.
1541
1542@page
1543
1544@subsection TASK_SET_NOTE - Set task notepad entry
1545
1546@cindex set task notepad entry
1547
1548@subheading CALLING SEQUENCE:
1549
1550@ifset is-C
1551@findex rtems_task_set_note
1552@example
1553rtems_status_code rtems_task_set_note(
1554  rtems_id  id,
1555  uint32_t  notepad,
1556  uint32_t  note
1557);
1558@end example
1559@end ifset
1560
1561@ifset is-Ada
1562@example
1563procedure Task_Set_Note (
1564   ID      : in     RTEMS.ID;
1565   Notepad : in     RTEMS.Notepad_Index;
1566   Note    : in     RTEMS.Unsigned32;
1567   Result  :    out RTEMS.Status_Codes
1568);
1569@end example
1570@end ifset
1571
1572@subheading DIRECTIVE STATUS CODES:
1573@code{@value{RPREFIX}SUCCESSFUL} - task's note set successfully@*
1574@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1575@code{@value{RPREFIX}INVALID_NUMBER} - invalid notepad location
1576
1577@subheading DESCRIPTION:
1578This directive is deprecated and will be removed.
1579
1580This directive sets the notepad entry for the task specified by
1581id to the value note.
1582
1583@subheading NOTES:
1584If id is set to @code{@value{RPREFIX}SELF}, the calling
1585task accesses its own notepad locations.
1586
1587This directive will not cause the running task to be preempted.
1588
1589@c This version of the paragraph avoids the overfull hbox error.
1590@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
1591@c sixteen notepad locations.
1592
1593The sixteen notepad locations can be accessed using the constants
1594@code{@value{RPREFIX}NOTEPAD_0} through @code{@value{RPREFIX}NOTEPAD_15}.
1595
1596Setting a notepad location of a global task which does not
1597reside on the local node will generate a request to the remote
1598node to set the specified notepad entry.
1599
1600@page
1601
1602@subsection TASK_WAKE_AFTER - Wake up after interval
1603
1604@cindex delay a task for an interval
1605@cindex wake up after an interval
1606
1607@subheading CALLING SEQUENCE:
1608
1609@ifset is-C
1610@findex rtems_task_wake_after
1611@example
1612rtems_status_code rtems_task_wake_after(
1613  rtems_interval ticks
1614);
1615@end example
1616@end ifset
1617
1618@ifset is-Ada
1619@example
1620procedure Task_Wake_After (
1621   Ticks  : in     RTEMS.Interval;
1622   Result :    out RTEMS.Status_Codes
1623);
1624@end example
1625@end ifset
1626
1627@subheading DIRECTIVE STATUS CODES:
1628@code{@value{RPREFIX}SUCCESSFUL} - always successful
1629
1630@subheading DESCRIPTION:
1631This directive blocks the calling task for the specified number
1632of system clock ticks.  When the requested interval has elapsed,
1633the task is made ready.  The @code{@value{DIRPREFIX}clock_tick}
1634directive automatically updates the delay period.
1635
1636@subheading NOTES:
1637Setting the system date and time with the
1638@code{@value{DIRPREFIX}clock_set} directive
1639has no effect on a @code{@value{DIRPREFIX}task_wake_after} blocked task.
1640
1641A task may give up the processor and remain in the ready state
1642by specifying a value of @code{@value{RPREFIX}YIELD_PROCESSOR} in ticks.
1643
1644The maximum timer interval that can be specified is the maximum
1645value which can be represented by the uint32_t type.
1646
1647A clock tick is required to support the functionality of this directive.
1648
1649@page
1650
1651@subsection TASK_WAKE_WHEN - Wake up when specified
1652
1653@cindex delay a task until a wall time
1654@cindex wake up at a wall time
1655
1656@subheading CALLING SEQUENCE:
1657
1658@ifset is-C
1659@findex rtems_task_wake_when
1660@example
1661rtems_status_code rtems_task_wake_when(
1662  rtems_time_of_day *time_buffer
1663);
1664@end example
1665@end ifset
1666
1667@ifset is-Ada
1668@example
1669procedure Task_Wake_When (
1670   Time_Buffer : in     RTEMS.Time_Of_Day;
1671   Result      :    out RTEMS.Status_Codes
1672);
1673@end example
1674@end ifset
1675
1676@subheading DIRECTIVE STATUS CODES:
1677@code{@value{RPREFIX}SUCCESSFUL} - awakened at date/time successfully@*
1678@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL@*
1679@code{@value{RPREFIX}INVALID_TIME_OF_DAY} - invalid time buffer@*
1680@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set
1681
1682@subheading DESCRIPTION:
1683This directive blocks a task until the date and time specified
1684in time_buffer.  At the requested date and time, the calling
1685task will be unblocked and made ready to execute.
1686
1687@subheading NOTES:
1688The ticks portion of time_buffer @value{STRUCTURE} is ignored.  The
1689timing granularity of this directive is a second.
1690
1691A clock tick is required to support the functionality of this directive.
1692
1693@page
1694
1695@subsection ITERATE_OVER_ALL_THREADS - Iterate Over Tasks
1696
1697@cindex iterate over all threads
1698@subheading CALLING SEQUENCE:
1699
1700@ifset is-C
1701@findex rtems_iterate_over_all_threads
1702@example
1703typedef void (*rtems_per_thread_routine)(
1704  Thread_Control *the_thread
1705);
1706
1707void rtems_iterate_over_all_threads(
1708  rtems_per_thread_routine routine
1709);
1710@end example
1711@end ifset
1712
1713@ifset is-Ada
1714@example
1715NOT SUPPORTED FROM Ada BINDING
1716@end example
1717@end ifset
1718
1719@subheading DIRECTIVE STATUS CODES: NONE
1720
1721
1722@subheading DESCRIPTION:
1723
1724This directive iterates over all of the existant threads in the
1725system and invokes @code{routine} on each of them.  The user should
1726be careful in accessing the contents of @code{the_thread}.
1727
1728This routine is intended for use in diagnostic utilities and is
1729not intented for routine use in an operational system.
1730
1731@subheading NOTES:
1732
1733There is NO protection while this routine is called.  Thus it is
1734possible that @code{the_thread} could be deleted while this is operating.
1735By not having protection, the user is free to invoke support routines
1736from the C Library which require semaphores for data structures.
1737
1738@page
1739
1740@subsection TASK_VARIABLE_ADD - Associate per task variable
1741
1742@cindex per-task variable
1743@cindex task private variable
1744@cindex task private data
1745
1746@subheading CALLING SEQUENCE:
1747
1748@ifset is-C
1749@findex rtems_task_variable_add
1750@example
1751rtems_status_code rtems_task_variable_add(
1752  rtems_id  tid,
1753  void    **task_variable,
1754  void    (*dtor)(void *)
1755);
1756@end example
1757@end ifset
1758
1759@ifset is-Ada
1760@example
1761type Task_Variable_Dtor is access procedure (
1762   Argument : in     RTEMS.Address;
1763);
1764
1765procedure Task_Variable_Add (
1766   ID            : in     RTEMS.ID;
1767   Task_Variable : in     RTEMS.Address;
1768   Dtor          : in     RTEMS.Task_Variable_Dtor;
1769   Result        :    out RTEMS.Status_Codes
1770);
1771@end example
1772@end ifset
1773
1774@subheading DIRECTIVE STATUS CODES:
1775@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
1776@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
1777@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1778@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
1779@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
1780
1781@subheading DESCRIPTION:
1782This directive adds the memory location specified by the
1783ptr argument to the context of the given task.  The variable will
1784then be private to the task.  The task can access and modify the
1785variable, but the modifications will not appear to other tasks, and
1786other tasks' modifications to that variable will not affect the value
1787seen by the task.  This is accomplished by saving and restoring the
1788variable's value each time a task switch occurs to or from the calling task.
1789If the dtor argument is non-NULL it specifies the address of a `destructor'
1790function which will be called when the task is deleted.  The argument
1791passed to the destructor function is the task's value of the variable.
1792
1793@subheading NOTES:
1794
1795This directive is deprecated and task variables will be removed.
1796
1797Task variables increase the context switch time to and from the
1798tasks that own them so it is desirable to minimize the number of
1799task variables.  One efficient method
1800is to have a single task variable that is a pointer to a dynamically
1801allocated structure containing the task's private `global' data.
1802In this case the destructor function could be `free'.
1803
1804Per-task variables are disabled in SMP configurations and this service
1805is not available.
1806
1807@page
1808
1809@subsection TASK_VARIABLE_GET - Obtain value of a per task variable
1810
1811@cindex get per-task variable
1812@cindex obtain per-task variable
1813
1814@subheading CALLING SEQUENCE:
1815
1816@ifset is-C
1817@findex rtems_task_variable_get
1818@example
1819rtems_status_code rtems_task_variable_get(
1820  rtems_id  tid,
1821  void    **task_variable,
1822  void    **task_variable_value
1823);
1824@end example
1825@end ifset
1826
1827@ifset is-Ada
1828@example
1829procedure Task_Variable_Get (
1830   ID                  : in     RTEMS.ID;
1831   Task_Variable       :    out RTEMS.Address;
1832   Task_Variable_Value :    out RTEMS.Address;
1833   Result              :    out RTEMS.Status_Codes
1834);
1835@end example
1836@end ifset
1837
1838@subheading DIRECTIVE STATUS CODES:
1839@code{@value{RPREFIX}SUCCESSFUL} - per task variable obtained successfully@*
1840@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
1841@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable_value} is NULL@*
1842@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is not found@*
1843@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
1844@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
1845
1846@subheading DESCRIPTION:
1847This directive looks up the private value of a task variable for a
1848specified task and stores that value in the location pointed to by
1849the result argument.  The specified task is usually not the calling
1850task, which can get its private value by directly accessing the variable.
1851
1852@subheading NOTES:
1853
1854This directive is deprecated and task variables will be removed.
1855
1856If you change memory which @code{task_variable_value} points to,
1857remember to declare that memory as volatile, so that the compiler
1858will optimize it correctly.  In this case both the pointer
1859@code{task_variable_value} and data referenced by @code{task_variable_value}
1860should be considered volatile.
1861
1862Per-task variables are disabled in SMP configurations and this service
1863is not available.
1864
1865@page
1866
1867@subsection TASK_VARIABLE_DELETE - Remove per task variable
1868
1869@cindex per-task variable
1870@cindex task private variable
1871@cindex task private data
1872
1873@subheading CALLING SEQUENCE:
1874
1875@ifset is-C
1876@findex rtems_task_variable_delete
1877@example
1878rtems_status_code rtems_task_variable_delete(
1879  rtems_id  id,
1880  void    **task_variable
1881);
1882@end example
1883@end ifset
1884
1885@ifset is-Ada
1886@example
1887procedure Task_Variable_Delete (
1888   ID                  : in     RTEMS.ID;
1889   Task_Variable       :    out RTEMS.Address;
1890   Result              :    out RTEMS.Status_Codes
1891);
1892@end example
1893@end ifset
1894
1895@subheading DIRECTIVE STATUS CODES:
1896@code{@value{RPREFIX}SUCCESSFUL} - per task variable deleted successfully@*
1897@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1898@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
1899@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
1900@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
1901
1902@subheading DESCRIPTION:
1903This directive removes the given location from a task's context.
1904
1905@subheading NOTES:
1906
1907This directive is deprecated and task variables will be removed.
1908
1909Per-task variables are disabled in SMP configurations and this service
1910is not available.
1911
Note: See TracBrowser for help on using the repository browser.