source: rtems/doc/user/task.t @ 30d11766

4.115
Last change on this file since 30d11766 was 30d11766, checked in by Joel Sherrill <joel.sherrill@…>, on 03/11/14 at 20:08:54

stackchk.t task.t: Change can not to cannot for consistency

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