source: rtems/doc/user/task.t @ 3ac68119

4.11
Last change on this file since 3ac68119 was 3ac68119, checked in by Gedare Bloom <gedare@…>, on Mar 6, 2015 at 5:41:49 PM

cpukit: deprecate notepads

Deprecate Classic API Notepads. Mark task_set/get_note() with
the deprecated attribute, and also mark the notepads field.

Replace disable with enable option for notepads in confdefs.h,
and make notepads disabled by default. The previous option
CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS is now unused and
will emit a compile-time warning. A new option
CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS is available to turn
on notepads, but it also will emit a compile-time warning
to indicate that notepads are deprecated.

Closes #2265

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