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

4.104.114.9
Last change on this file since d5671b1 was d5671b1, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 29, 2008 at 9:37:00 PM

2008-01-29 Joel Sherrill <joel.sherrill@…>

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