source: rtems/doc/user/task.t @ 1fa78236

4.104.115
Last change on this file since 1fa78236 was 1fa78236, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 7, 2008 at 3:02:55 PM

2008-11-07 Joel Sherrill <joel.sherrill@…>

PR 1334/doc

  • user/Makefile.am, user/concepts.t, user/init.t, user/overview.t, user/part.t, user/task.t: Correct typos and correctly document 4 parts of 32-bit object id.
  • user/ObjectId-32Bits.eps, user/ObjectId-32Bits.png: New files.
  • Property mode set to 100644
File size: 64.2 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@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 the configured
748minimum stack size, then RTEMS will use the configured
749minimum as the stack size for this task.  In addition
750to being able to specify the task stack size as a integer,
751there are two constants which may be specified:
752
753@itemize @bullet
754@item @code{@value{RPREFIX}MINIMUM_STACK_SIZE}
755is the minimum stack size @b{RECOMMENDED} for use on this processor.
756This value is selected by the RTEMS developers conservatively to
757minimize the risk of blown stacks for most user applications.
758Using this constant when specifying the task stack size, indicates
759that the stack size will be at least
760@code{@value{RPREFIX}MINIMUM_STACK_SIZE} bytes in size.  If the
761user configured minimum stack size is larger than the recommended
762minimum, then it will be used.
763
764@item @code{@value{RPREFIX}CONFIGURED_MINIMUM_STACK_SIZE}
765indicates that this task is to be created with a stack size
766of the minimum stack size that was configured by the application.
767If not explicitly configured by the application, the default
768configured minimum stack size is the processor dependent value
769@code{@value{RPREFIX}MINIMUM_STACK_SIZE}.  Since this uses
770the configured minimum stack size value, you may get a stack
771size that is smaller or larger than the recommended minimum.  This
772can be used to provide large stacks for all tasks on complex
773applications or small stacks on applications that are trying
774to conserve memory.
775
776@end itemize
777
778Application developers should consider the stack usage of the
779device drivers when calculating the stack size required for
780tasks which utilize the driver.
781
782The following task attribute constants are defined by RTEMS:
783
784@itemize @bullet
785@item @code{@value{RPREFIX}NO_FLOATING_POINT} - does not use coprocessor (default)
786@item @code{@value{RPREFIX}FLOATING_POINT} - uses numeric coprocessor
787@item @code{@value{RPREFIX}LOCAL} - local task (default)
788@item @code{@value{RPREFIX}GLOBAL} - global task
789@end itemize
790
791The following task mode constants are defined by RTEMS:
792
793@itemize  @bullet
794@item @code{@value{RPREFIX}PREEMPT} - enable preemption (default)
795@item @code{@value{RPREFIX}NO_PREEMPT} - disable preemption
796@item @code{@value{RPREFIX}NO_TIMESLICE} - disable timeslicing (default)
797@item @code{@value{RPREFIX}TIMESLICE} - enable timeslicing
798@item @code{@value{RPREFIX}ASR} - enable ASR processing (default)
799@item @code{@value{RPREFIX}NO_ASR} - disable ASR processing
800@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} - enable all interrupts (default)
801@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} - execute at interrupt level n
802@end itemize
803
804The interrupt level portion of the task execution mode
805supports a maximum of 256 interrupt levels.  These levels are
806mapped onto the interrupt levels actually supported by the
807target processor in a processor dependent fashion.
808
809Tasks should not be made global unless remote tasks must
810interact with them.  This avoids the system overhead incurred by
811the creation of a global task.  When a global task is created,
812the task's name and id must be transmitted to every node in the
813system for insertion in the local copy of the global object
814table.
815
816The total number of global objects, including tasks, is limited
817by the maximum_global_objects field in the Configuration Table.
818
819@page
820
821@subsection TASK_IDENT - Get ID of a task
822
823@cindex get ID of a task
824
825@subheading CALLING SEQUENCE:
826
827@ifset is-C
828@findex rtems_task_ident
829@example
830rtems_status_code rtems_task_ident(
831  rtems_name  name,
832  uint32_t    node,
833  rtems_id   *id
834);
835@end example
836@end ifset
837
838@ifset is-Ada
839@example
840procedure Task_Ident (
841   Name   : in     RTEMS.Name;
842   Node   : in     RTEMS.Node;
843   ID     :    out RTEMS.ID;
844   Result :    out RTEMS.Status_Codes
845);
846@end example
847@end ifset
848
849@subheading DIRECTIVE STATUS CODES:
850@code{@value{RPREFIX}SUCCESSFUL} - task identified successfully@*
851@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
852@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
853@code{@value{RPREFIX}INVALID_NODE} - invalid node id
854
855@subheading DESCRIPTION:
856This directive obtains the task id associated with the task name
857specified in name.  A task may obtain its own id by specifying
858@code{@value{RPREFIX}SELF} or its own task name in name.  If the task name is not
859unique, then the task id returned will match one of the tasks
860with that name.  However, this task id is not guaranteed to
861correspond to the desired task.  The task id, returned in id, is
862used in other task related directives to access the task.
863
864@subheading NOTES:
865This directive will not cause the running task to be preempted.
866
867If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched with the
868local node being searched first.  All other nodes are searched
869with the lowest numbered node searched first.
870
871If node is a valid node number which does not represent the
872local node, then only the tasks exported by the designated node
873are searched.
874
875This directive does not generate activity on remote nodes.  It
876accesses only the local copy of the global object table.
877
878@page
879
880@subsection TASK_SELF - Obtain ID of caller
881
882@cindex obtain ID of caller
883
884@subheading CALLING SEQUENCE:
885
886@ifset is-C
887@findex rtems_task_self
888@example
889rtems_id rtems_task_self(void);
890@end example
891@end ifset
892
893@ifset is-Ada
894@example
895function Task_Self return RTEMS.ID;
896@end example
897@end ifset
898
899@subheading DIRECTIVE STATUS CODES:
900Returns the object Id of the calling task.
901
902@subheading DESCRIPTION:
903This directive returns the Id of the calling task.
904
905@subheading NOTES:
906If called from an interrupt service routine, this directive
907will return the Id of the interrupted task.
908
909@page
910
911@subsection TASK_START - Start a task
912
913@cindex starting a task
914
915@subheading CALLING SEQUENCE:
916
917@ifset is-C
918@findex rtems_task_start
919@example
920rtems_status_code rtems_task_start(
921  rtems_id            id,
922  rtems_task_entry    entry_point,
923  rtems_task_argument argument
924);
925@end example
926@end ifset
927
928@ifset is-Ada
929@example
930procedure Task_Start (
931   ID          : in     RTEMS.ID;
932   Entry_Point : in     RTEMS.Task_Entry;
933   Argument    : in     RTEMS.Task_Argument;
934   Result      :    out RTEMS.Status_Codes
935);
936@end example
937@end ifset
938
939@subheading DIRECTIVE STATUS CODES:
940@code{@value{RPREFIX}SUCCESSFUL} - ask started successfully@*
941@code{@value{RPREFIX}INVALID_ADDRESS} - invalid task entry point@*
942@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
943@code{@value{RPREFIX}INCORRECT_STATE} - task not in the dormant state@*
944@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot start remote task
945
946@subheading DESCRIPTION:
947This directive readies the task, specified by @code{id}, for execution
948based on the priority and execution mode specified when the task
949was created.  The starting address of the task is given in
950@code{entry_point}.  The task's starting argument is contained in
951argument.  This argument can be a single value or used as an index into an
952array of parameter blocks.  The type of this numeric argument is an unsigned
953integer type with the property that any valid pointer to void can be converted
954to this type and then converted back to a pointer to void.  The result will
955compare equal to the original pointer.
956
957@subheading NOTES:
958The calling task will be preempted if its preemption mode is
959enabled and the task being started has a higher priority.
960
961Any actions performed on a dormant task such as suspension or
962change of priority are nullified when the task is initiated via
963the @code{@value{DIRPREFIX}task_start} directive.
964
965@page
966
967@subsection TASK_RESTART - Restart a task
968
969@cindex restarting a task
970
971@subheading CALLING SEQUENCE:
972
973@ifset is-C
974@findex rtems_task_restart
975@example
976rtems_status_code rtems_task_restart(
977  rtems_id            id,
978  rtems_task_argument argument
979);
980@end example
981@end ifset
982
983@ifset is-Ada
984@example
985procedure Task_Restart (
986   ID       : in     RTEMS.ID;
987   Argument : in     RTEMS.Task_Argument;
988   Result   :    out RTEMS.Status_Codes
989);
990@end example
991@end ifset
992
993@subheading DIRECTIVE STATUS CODES:
994@code{@value{RPREFIX}SUCCESSFUL} - task restarted successfully@*
995@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
996@code{@value{RPREFIX}INCORRECT_STATE} - task never started@*
997@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task
998
999@subheading DESCRIPTION:
1000This directive resets the task specified by id to begin
1001execution at its original starting address.  The task's priority
1002and execution mode are set to the original creation values.  If
1003the task is currently blocked, RTEMS automatically makes the
1004task ready.  A task can be restarted from any state, except the
1005dormant state.
1006
1007The task's starting argument is contained in argument.  This argument can be a
1008single value or an index into an array of parameter blocks.  The type of this
1009numeric argument is an unsigned integer type with the property that any valid
1010pointer to void can be converted to this type and then converted back to a
1011pointer to void.  The result will compare equal to the original pointer.  This
1012new argument may be used to distinguish
1013between the initial @code{@value{DIRPREFIX}task_start}
1014of the task and any ensuing calls
1015to @code{@value{DIRPREFIX}task_restart}
1016of the task.  This can be beneficial in deleting
1017a task.  Instead of deleting a task using
1018the @code{@value{DIRPREFIX}task_delete}
1019directive, a task can delete another task by restarting that
1020task, and allowing that task to release resources back to RTEMS
1021and then delete itself.
1022
1023@subheading NOTES:
1024If id is @code{@value{RPREFIX}SELF}, the calling task will be restarted and will not
1025return from this directive.
1026
1027The calling task will be preempted if its preemption mode is
1028enabled and the task being restarted has a higher priority.
1029
1030The task must reside on the local node, even if the task was
1031created with the @code{@value{RPREFIX}GLOBAL} option.
1032
1033@page
1034
1035@subsection TASK_DELETE - Delete a task
1036
1037@cindex deleting a task
1038
1039@subheading CALLING SEQUENCE:
1040
1041@ifset is-C
1042@findex rtems_task_delete
1043@example
1044rtems_status_code rtems_task_delete(
1045  rtems_id id
1046);
1047@end example
1048@end ifset
1049
1050@ifset is-Ada
1051@example
1052procedure Task_Delete (
1053   ID     : in     RTEMS.ID;
1054   Result :    out RTEMS.Status_Codes
1055);
1056@end example
1057@end ifset
1058
1059@subheading DIRECTIVE STATUS CODES:
1060@code{@value{RPREFIX}SUCCESSFUL} - task restarted successfully@*
1061@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1062@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task
1063
1064@subheading DESCRIPTION:
1065This directive deletes a task, either the calling task or
1066another task, as specified by id.  RTEMS stops the execution of
1067the task and reclaims the stack memory, any allocated delay or
1068timeout timers, the TCB, and, if the task is @code{@value{RPREFIX}FLOATING_POINT}, its
1069floating point context area.  RTEMS does not reclaim the
1070following resources: region segments, partition buffers,
1071semaphores, timers, or rate monotonic periods.
1072
1073@subheading NOTES:
1074A task is responsible for releasing its resources back to RTEMS
1075before deletion.  To insure proper deallocation of resources, a
1076task should not be deleted unless it is unable to execute or
1077does not hold any RTEMS resources.  If a task holds RTEMS
1078resources, the task should be allowed to deallocate its
1079resources before deletion.  A task can be directed to release
1080its resources and delete itself by restarting it with a special
1081argument or by sending it a message, an event, or a signal.
1082
1083Deletion of the current task (@code{@value{RPREFIX}SELF}) will force RTEMS to select
1084another task to execute.
1085
1086When a global task is deleted, the task id must be transmitted
1087to every node in the system for deletion from the local copy of
1088the global object table.
1089
1090The task must reside on the local node, even if the task was
1091created with the @code{@value{RPREFIX}GLOBAL} option.
1092
1093@page
1094
1095@subsection TASK_SUSPEND - Suspend a task
1096
1097@cindex suspending a task
1098
1099@subheading CALLING SEQUENCE:
1100
1101@ifset is-C
1102@findex rtems_task_suspend
1103@example
1104rtems_status_code rtems_task_suspend(
1105  rtems_id id
1106);
1107@end example
1108@end ifset
1109
1110@ifset is-Ada
1111@example
1112procedure Task_Suspend (
1113   ID     : in     RTEMS.ID;
1114   Result :    out RTEMS.Status_Codes
1115);
1116@end example
1117@end ifset
1118
1119@subheading DIRECTIVE STATUS CODES:
1120@code{@value{RPREFIX}SUCCESSFUL} - task restarted successfully@*
1121@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1122@code{@value{RPREFIX}ALREADY_SUSPENDED} - task already suspended
1123
1124@subheading DESCRIPTION:
1125This directive suspends the task specified by id from further
1126execution by placing it in the suspended state.  This state is
1127additive to any other blocked state that the task may already be
1128in.  The task will not execute again until another task issues
1129the @code{@value{DIRPREFIX}task_resume}
1130directive for this task and any blocked state
1131has been removed.
1132
1133@subheading NOTES:
1134The requesting task can suspend itself by specifying @code{@value{RPREFIX}SELF} as id.
1135In this case, the task will be suspended and a successful
1136return code will be returned when the task is resumed.
1137
1138Suspending a global task which does not reside on the local node
1139will generate a request to the remote node to suspend the
1140specified task.
1141
1142If the task specified by id is already suspended, then the
1143@code{@value{RPREFIX}ALREADY_SUSPENDED} status code is returned.
1144
1145@page
1146
1147@subsection TASK_RESUME - Resume a task
1148
1149@cindex resuming a task
1150
1151@subheading CALLING SEQUENCE:
1152
1153@ifset is-C
1154@findex rtems_task_resume
1155@example
1156rtems_status_code rtems_task_resume(
1157  rtems_id id
1158);
1159@end example
1160@end ifset
1161
1162@ifset is-Ada
1163@example
1164procedure Task_Resume (
1165   ID     : in     RTEMS.ID;
1166   Result :    out RTEMS.Status_Codes
1167);
1168@end example
1169@end ifset
1170
1171@subheading DIRECTIVE STATUS CODES:
1172@code{@value{RPREFIX}SUCCESSFUL} - task restarted successfully@*
1173@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1174@code{@value{RPREFIX}INCORRECT_STATE} - task not suspended
1175
1176@subheading DESCRIPTION:
1177This directive removes the task specified by id from the
1178suspended state.  If the task is in the ready state after the
1179suspension is removed, then it will be scheduled to run.  If the
1180task is still in a blocked state after the suspension is
1181removed, then it will remain in that blocked state.
1182
1183@subheading NOTES:
1184The running task may be preempted if its preemption mode is
1185enabled and the local task being resumed has a higher priority.
1186
1187Resuming a global task which does not reside on the local node
1188will generate a request to the remote node to resume the
1189specified task.
1190
1191If the task specified by id is not suspended, then the
1192@code{@value{RPREFIX}INCORRECT_STATE} status code is returned.
1193
1194@page
1195
1196@subsection TASK_IS_SUSPENDED - Determine if a task is Suspended
1197
1198@cindex is task suspended
1199
1200@subheading CALLING SEQUENCE:
1201
1202@ifset is-C
1203@findex rtems_task_is_suspended
1204@example
1205rtems_status_code rtems_task_is_suspended(
1206  rtems_id id
1207);
1208@end example
1209@end ifset
1210
1211@ifset is-Ada
1212@example
1213procedure Task_Is_Suspended (
1214   ID     : in     RTEMS.ID;
1215   Result :    out RTEMS.Status_Codes
1216);
1217@end example
1218@end ifset
1219
1220@subheading DIRECTIVE STATUS CODES:
1221@code{@value{RPREFIX}SUCCESSFUL} - task is NOT suspended@*
1222@code{@value{RPREFIX}ALREADY_SUSPENDED} - task is currently suspended@*
1223@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
1224@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks
1225
1226@subheading DESCRIPTION:
1227
1228This directive returns a status code indicating whether or
1229not the specified task is currently suspended.
1230
1231@subheading NOTES:
1232
1233This operation is not currently supported on remote tasks.
1234
1235@page
1236
1237@subsection TASK_SET_PRIORITY - Set task priority
1238
1239@findex rtems_task_set_priority
1240@cindex current task priority
1241@cindex set task priority
1242@cindex get task priority
1243@cindex obtain task priority
1244
1245@subheading CALLING SEQUENCE:
1246
1247@ifset is-C
1248@example
1249rtems_status_code rtems_task_set_priority(
1250  rtems_id             id,
1251  rtems_task_priority  new_priority,
1252  rtems_task_priority *old_priority
1253);
1254@end example
1255@end ifset
1256
1257@ifset is-Ada
1258@example
1259procedure Task_Set_Priority (
1260   ID           : in     RTEMS.ID;
1261   New_Priority : in     RTEMS.Task_Priority;
1262   Old_Priority :    out RTEMS.Task_Priority;
1263   Result       :    out RTEMS.Status_Codes
1264);
1265@end example
1266@end ifset
1267
1268@subheading DIRECTIVE STATUS CODES:
1269@code{@value{RPREFIX}SUCCESSFUL} - task priority set successfully@*
1270@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1271@code{@value{RPREFIX}INVALID_ADDRESS} - invalid return argument pointer@*
1272@code{@value{RPREFIX}INVALID_PRIORITY} - invalid task priority
1273
1274@subheading DESCRIPTION:
1275This directive manipulates the priority of the task specified by
1276id.  An id of @code{@value{RPREFIX}SELF} is used to indicate
1277the calling task.  When new_priority is not equal to
1278@code{@value{RPREFIX}CURRENT_PRIORITY}, the specified
1279task's previous priority is returned in old_priority.  When
1280new_priority is @code{@value{RPREFIX}CURRENT_PRIORITY},
1281the specified task's current
1282priority is returned in old_priority.  Valid priorities range
1283from a high of 1 to a low of 255.
1284
1285@subheading NOTES:
1286The calling task may be preempted if its preemption mode is
1287enabled and it lowers its own priority or raises another task's
1288priority.
1289
1290Setting the priority of a global task which does not reside on
1291the local node will generate a request to the remote node to
1292change the priority of the specified task.
1293
1294If the task specified by id is currently holding any binary
1295semaphores which use the priority inheritance algorithm, then
1296the task's priority cannot be lowered immediately.  If the
1297task's priority were lowered immediately, then priority
1298inversion results.  The requested lowering of the task's
1299priority will occur when the task has released all priority
1300inheritance binary semaphores.  The task's priority can be
1301increased regardless of the task's use of priority inheritance
1302binary semaphores.
1303
1304@page
1305
1306@subsection TASK_MODE - Change the current task mode
1307
1308@cindex current task mode
1309@cindex set task mode
1310@cindex get task mode
1311@cindex set task preemption mode
1312@cindex get task preemption mode
1313@cindex obtain task mode
1314
1315@subheading CALLING SEQUENCE:
1316
1317@ifset is-C
1318@findex rtems_task_mode
1319@example
1320rtems_status_code rtems_task_mode(
1321  rtems_mode  mode_set,
1322  rtems_mode  mask,
1323  rtems_mode *previous_mode_set
1324);
1325@end example
1326@end ifset
1327
1328@ifset is-Ada
1329@example
1330procedure Task_Mode (
1331   Mode_Set          : in     RTEMS.Mode;
1332   Mask              : in     RTEMS.Mode;
1333   Previous_Mode_Set : in     RTEMS.Mode;
1334   Result            :    out RTEMS.Status_Codes
1335);
1336@end example
1337@end ifset
1338
1339@subheading DIRECTIVE STATUS CODES:
1340@code{@value{RPREFIX}SUCCESSFUL} - task mode set successfully@*
1341@code{@value{RPREFIX}INVALID_ADDRESS} - @code{previous_mode_set} is NULL
1342
1343@subheading DESCRIPTION:
1344This directive manipulates the execution mode of the calling
1345task.  A task's execution mode enables and disables preemption,
1346timeslicing, asynchronous signal processing, as well as
1347specifying the current interrupt level.  To modify an execution
1348mode, the mode class(es) to be changed must be specified in the
1349mask parameter and the desired mode(s) must be specified in the
1350mode parameter. 
1351
1352@subheading NOTES:
1353The calling task will be preempted if it enables preemption and
1354a higher priority task is ready to run.
1355
1356Enabling timeslicing has no effect if preemption is disabled.  For
1357a task to be timesliced, that task must have both preemption and
1358timeslicing enabled.
1359
1360A task can obtain its current execution mode, without modifying
1361it, by calling this directive with a mask value of
1362@code{@value{RPREFIX}CURRENT_MODE}.
1363
1364To temporarily disable the processing of a valid ASR, a task
1365should call this directive with the @code{@value{RPREFIX}NO_ASR}
1366indicator specified in mode.
1367
1368The set of task mode constants and each mode's corresponding
1369mask constant is provided in the following table:
1370
1371@ifset use-ascii
1372@itemize @bullet
1373@item @code{@value{RPREFIX}PREEMPT} is masked by
1374@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
1375
1376@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
1377@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
1378
1379@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
1380@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
1381
1382@item @code{@value{RPREFIX}TIMESLICE} is masked by
1383@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
1384
1385@item @code{@value{RPREFIX}ASR} is masked by
1386@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
1387
1388@item @code{@value{RPREFIX}NO_ASR} is masked by
1389@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
1390
1391@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
1392@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
1393
1394@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
1395@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
1396 
1397@end itemize
1398@end ifset
1399 
1400@ifset use-tex
1401@sp 1
1402@c this is temporary
1403@itemize @bullet
1404@item @code{@value{RPREFIX}PREEMPT} is masked by
1405@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
1406
1407@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
1408@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
1409
1410@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
1411@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
1412
1413@item @code{@value{RPREFIX}TIMESLICE} is masked by
1414@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
1415
1416@item @code{@value{RPREFIX}ASR} is masked by
1417@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
1418
1419@item @code{@value{RPREFIX}NO_ASR} is masked by
1420@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
1421
1422@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
1423@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
1424
1425@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
1426@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
1427 
1428@end itemize
1429 
1430@tex
1431@end tex
1432@end ifset
1433 
1434@ifset use-html
1435@html
1436<CENTER>
1437  <TABLE COLS=3 WIDTH="80%" BORDER=2>
1438<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD>
1439    <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD>
1440    <TD ALIGN=center><STRONG>Description</STRONG></TD></TR>
1441<TR><TD ALIGN=center>@value{RPREFIX}PREEMPT</TD>
1442    <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
1443    <TD ALIGN=center>enables preemption</TD></TR>
1444<TR><TD ALIGN=center>@value{RPREFIX}NO_PREEMPT</TD>
1445    <TD ALIGN=center>@value{RPREFIX}PREEMPT_MASK</TD>
1446    <TD ALIGN=center>disables preemption</TD></TR>
1447<TR><TD ALIGN=center>@value{RPREFIX}NO_TIMESLICE</TD>
1448    <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
1449    <TD ALIGN=center>disables timeslicing</TD></TR>
1450<TR><TD ALIGN=center>@value{RPREFIX}TIMESLICE</TD>
1451    <TD ALIGN=center>@value{RPREFIX}TIMESLICE_MASK</TD>
1452    <TD ALIGN=center>enables timeslicing</TD></TR>
1453<TR><TD ALIGN=center>@value{RPREFIX}ASR</TD>
1454    <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
1455    <TD ALIGN=center>enables ASR processing</TD></TR>
1456<TR><TD ALIGN=center>@value{RPREFIX}NO_ASR</TD>
1457    <TD ALIGN=center>@value{RPREFIX}ASR_MASK</TD>
1458    <TD ALIGN=center>disables ASR processing</TD></TR>
1459<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(0)</TD>
1460    <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
1461    <TD ALIGN=center>enables all interrupts</TD></TR>
1462<TR><TD ALIGN=center>@value{RPREFIX}INTERRUPT_LEVEL(n)</TD>
1463    <TD ALIGN=center>@value{RPREFIX}INTERRUPT_MASK</TD>
1464    <TD ALIGN=center>sets interrupts level n</TD></TR>
1465  </TABLE>
1466</CENTER>
1467@end html
1468@end ifset
1469
1470@page
1471
1472@subsection TASK_GET_NOTE - Get task notepad entry
1473
1474@cindex get task notepad entry
1475
1476@subheading CALLING SEQUENCE:
1477
1478@ifset is-C
1479@findex rtems_task_get_note
1480@example
1481rtems_status_code rtems_task_get_note(
1482  rtems_id  id,
1483  uint32_t  notepad,
1484  uint32_t *note
1485);
1486@end example
1487@end ifset
1488
1489@ifset is-Ada
1490@example
1491procedure Task_Get_Note (
1492   ID      : in     RTEMS.ID;
1493   Notepad : in     RTEMS.Notepad_Index;
1494   Note    :    out RTEMS.Unsigned32;
1495   Result  :    out RTEMS.Status_Codes
1496);
1497@end example
1498@end ifset
1499
1500@subheading DIRECTIVE STATUS CODES:
1501@code{@value{RPREFIX}SUCCESSFUL} - note obtained successfully@*
1502@code{@value{RPREFIX}INVALID_ADDRESS} - @code{note} is NULL@*
1503@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1504@code{@value{RPREFIX}INVALID_NUMBER} - invalid notepad location
1505
1506@subheading DESCRIPTION:
1507This directive returns the note contained in the notepad
1508location of the task specified by id.
1509
1510@subheading NOTES:
1511This directive will not cause the running task to be preempted.
1512
1513If id is set to @code{@value{RPREFIX}SELF},
1514the calling task accesses its own notepad.
1515
1516@c This version of the paragraph avoids the overfull hbox error.
1517@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
1518@c sixteen notepad locations.
1519
1520The sixteen notepad locations can be accessed using the constants
1521@code{@value{RPREFIX}NOTEPAD_0} through @code{@value{RPREFIX}NOTEPAD_15}.
1522
1523Getting a note of a global task which does not reside on the
1524local node will generate a request to the remote node to obtain
1525the notepad entry of the specified task.
1526
1527@page
1528
1529@subsection TASK_SET_NOTE - Set task notepad entry
1530
1531@cindex set task notepad entry
1532
1533@subheading CALLING SEQUENCE:
1534
1535@ifset is-C
1536@findex rtems_task_set_note
1537@example
1538rtems_status_code rtems_task_set_note(
1539  rtems_id  id,
1540  uint32_t  notepad,
1541  uint32_t  note
1542);
1543@end example
1544@end ifset
1545
1546@ifset is-Ada
1547@example
1548procedure Task_Set_Note (
1549   ID      : in     RTEMS.ID;
1550   Notepad : in     RTEMS.Notepad_Index;
1551   Note    : in     RTEMS.Unsigned32;
1552   Result  :    out RTEMS.Status_Codes
1553);
1554@end example
1555@end ifset
1556
1557@subheading DIRECTIVE STATUS CODES:
1558@code{@value{RPREFIX}SUCCESSFUL} - task's note set successfully@*
1559@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1560@code{@value{RPREFIX}INVALID_NUMBER} - invalid notepad location
1561
1562@subheading DESCRIPTION:
1563This directive sets the notepad entry for the task specified by
1564id to the value note.
1565
1566@subheading NOTES:
1567If id is set to @code{@value{RPREFIX}SELF}, the calling
1568task accesses its own notepad locations.
1569
1570This directive will not cause the running task to be preempted.
1571
1572@c This version of the paragraph avoids the overfull hbox error.
1573@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the
1574@c sixteen notepad locations.
1575
1576The sixteen notepad locations can be accessed using the constants
1577@code{@value{RPREFIX}NOTEPAD_0} through @code{@value{RPREFIX}NOTEPAD_15}.
1578
1579Setting a notepad location of a global task which does not
1580reside on the local node will generate a request to the remote
1581node to set the specified notepad entry.
1582
1583@page
1584
1585@subsection TASK_WAKE_AFTER - Wake up after interval
1586
1587@cindex delay a task for an interval
1588@cindex wake up after an interval
1589
1590@subheading CALLING SEQUENCE:
1591
1592@ifset is-C
1593@findex rtems_task_wake_after
1594@example
1595rtems_status_code rtems_task_wake_after(
1596  rtems_interval ticks
1597);
1598@end example
1599@end ifset
1600
1601@ifset is-Ada
1602@example
1603procedure Task_Wake_After (
1604   Ticks  : in     RTEMS.Interval;
1605   Result :    out RTEMS.Status_Codes
1606);
1607@end example
1608@end ifset
1609
1610@subheading DIRECTIVE STATUS CODES:
1611@code{@value{RPREFIX}SUCCESSFUL} - always successful
1612
1613@subheading DESCRIPTION:
1614This directive blocks the calling task for the specified number
1615of system clock ticks.  When the requested interval has elapsed,
1616the task is made ready.  The @code{@value{DIRPREFIX}clock_tick}
1617directive automatically updates the delay period.
1618
1619@subheading NOTES:
1620Setting the system date and time with the
1621@code{@value{DIRPREFIX}clock_set} directive
1622has no effect on a @code{@value{DIRPREFIX}task_wake_after} blocked task.
1623
1624A task may give up the processor and remain in the ready state
1625by specifying a value of @code{@value{RPREFIX}YIELD_PROCESSOR} in ticks.
1626
1627The maximum timer interval that can be specified is the maximum
1628value which can be represented by the uint32_t type.
1629
1630A clock tick is required to support the functionality of this directive.
1631
1632@page
1633
1634@subsection TASK_WAKE_WHEN - Wake up when specified
1635
1636@cindex delay a task until a wall time
1637@cindex wake up at a wall time
1638
1639@subheading CALLING SEQUENCE:
1640
1641@ifset is-C
1642@findex rtems_task_wake_when
1643@example
1644rtems_status_code rtems_task_wake_when(
1645  rtems_time_of_day *time_buffer
1646);
1647@end example
1648@end ifset
1649
1650@ifset is-Ada
1651@example
1652procedure Task_Wake_When (
1653   Time_Buffer : in     RTEMS.Time_Of_Day;
1654   Result      :    out RTEMS.Status_Codes
1655);
1656@end example
1657@end ifset
1658
1659@subheading DIRECTIVE STATUS CODES:
1660@code{@value{RPREFIX}SUCCESSFUL} - awakened at date/time successfully@*
1661@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL@*
1662@code{@value{RPREFIX}INVALID_TIME_OF_DAY} - invalid time buffer@*
1663@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set
1664
1665@subheading DESCRIPTION:
1666This directive blocks a task until the date and time specified
1667in time_buffer.  At the requested date and time, the calling
1668task will be unblocked and made ready to execute.
1669
1670@subheading NOTES:
1671The ticks portion of time_buffer @value{STRUCTURE} is ignored.  The
1672timing granularity of this directive is a second.
1673
1674A clock tick is required to support the functionality of this directive.
1675
1676@page
1677
1678@subsection ITERATE_OVER_ALL_THREADS - Iterate Over Tasks
1679
1680@cindex iterate over all threads
1681@subheading CALLING SEQUENCE:
1682
1683@ifset is-C
1684@findex rtems_iterate_over_all_threads
1685@example
1686typedef void (*rtems_per_thread_routine)(
1687  Thread_Control *the_thread
1688);
1689
1690void rtems_iterate_over_all_threads(
1691  rtems_per_thread_routine routine
1692);
1693@end example
1694@end ifset
1695
1696@ifset is-Ada
1697@example
1698NOT SUPPORTED FROM Ada BINDING
1699@end example
1700@end ifset
1701
1702@subheading DIRECTIVE STATUS CODES: NONE
1703
1704
1705@subheading DESCRIPTION:
1706
1707This directive iterates over all of the existant threads in the
1708system and invokes @code{routine} on each of them.  The user should
1709be careful in accessing the contents of @code{the_thread}.
1710
1711This routine is intended for use in diagnostic utilities and is
1712not intented for routine use in an operational system.
1713
1714@subheading NOTES:
1715
1716There is NO protection while this routine is called.  Thus it is
1717possible that @code{the_thread} could be deleted while this is operating.
1718By not having protection, the user is free to invoke support routines
1719from the C Library which require semaphores for data structures.
1720
1721@page
1722
1723@subsection TASK_VARIABLE_ADD - Associate per task variable
1724
1725@cindex per-task variable
1726@cindex task private variable
1727@cindex task private data
1728
1729@subheading CALLING SEQUENCE:
1730
1731@ifset is-C
1732@findex rtems_task_variable_add
1733@example
1734rtems_status_code rtems_task_variable_add(
1735  rtems_id  tid,
1736  void    **task_variable,
1737  void    (*dtor)(void *)
1738);
1739@end example
1740@end ifset
1741
1742@ifset is-Ada
1743@example
1744type Task_Variable_Dtor is access procedure (
1745   Argument : in     RTEMS.Address;
1746);
1747
1748procedure Task_Variable_Add (
1749   ID            : in     RTEMS.ID;
1750   Task_Variable : in     RTEMS.Address;
1751   Dtor          : in     RTEMS.Task_Variable_Dtor;
1752   Result        :    out RTEMS.Status_Codes
1753);
1754@end example
1755@end ifset
1756
1757@subheading DIRECTIVE STATUS CODES:
1758@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
1759@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
1760@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1761@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
1762@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
1763
1764@subheading DESCRIPTION:
1765This directive adds the memory location specified by the
1766ptr argument to the context of the given task.  The variable will
1767then be private to the task.  The task can access and modify the
1768variable, but the modifications will not appear to other tasks, and
1769other tasks' modifications to that variable will not affect the value
1770seen by the task.  This is accomplished by saving and restoring the
1771variable's value each time a task switch occurs to or from the calling task.
1772If the dtor argument is non-NULL it specifies the address of a `destructor'
1773function which will be called when the task is deleted.  The argument
1774passed to the destructor function is the task's value of the variable.
1775
1776@subheading NOTES:
1777
1778Task variables increase the context switch time to and from the
1779tasks that own them so it is desirable to minimize the number of
1780task variables.  One efficient method
1781is to have a single task variable that is a pointer to a dynamically
1782allocated structure containing the task's private `global' data.
1783In this case the destructor function could be `free'.
1784
1785@page
1786
1787@subsection TASK_VARIABLE_GET - Obtain value of a per task variable
1788
1789@cindex get per-task variable
1790@cindex obtain per-task variable
1791
1792@subheading CALLING SEQUENCE:
1793
1794@ifset is-C
1795@findex rtems_task_variable_get
1796@example
1797rtems_status_code rtems_task_variable_get(
1798  rtems_id  tid,
1799  void    **task_variable,
1800  void    **task_variable_value
1801);
1802@end example
1803@end ifset
1804
1805@ifset is-Ada
1806@example
1807procedure Task_Variable_Get (
1808   ID                  : in     RTEMS.ID;
1809   Task_Variable       :    out RTEMS.Address;
1810   Task_Variable_Value :    out RTEMS.Address;
1811   Result              :    out RTEMS.Status_Codes
1812);
1813@end example
1814@end ifset
1815
1816@subheading DIRECTIVE STATUS CODES:
1817@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
1818@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
1819@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable_value} is NULL@*
1820@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is not found@*
1821@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
1822@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
1823
1824@subheading DESCRIPTION:
1825This directive looks up the private value of a task variable for a
1826specified task and stores that value in the location pointed to by
1827the result argument.  The specified task is usually not the calling
1828task, which can get its private value by directly accessing the variable.
1829
1830@subheading NOTES:
1831
1832If you change memory which @code{task_variable_value} points to,
1833remember to declare that memory as volatile, so that the compiler
1834will optimize it correctly.  In this case both the pointer
1835@code{task_variable_value} and data referenced by @code{task_variable_value}
1836should be considered volatile.
1837
1838@page
1839
1840@subsection TASK_VARIABLE_DELETE - Remove per task variable
1841
1842@cindex per-task variable
1843@cindex task private variable
1844@cindex task private data
1845
1846@subheading CALLING SEQUENCE:
1847
1848@ifset is-C
1849@findex rtems_task_variable_delete
1850@example
1851rtems_status_code rtems_task_variable_delete(
1852  rtems_id  id,
1853  void    **task_variable
1854);
1855@end example
1856@end ifset
1857
1858@ifset is-Ada
1859@example
1860procedure Task_Variable_Delete (
1861   ID                  : in     RTEMS.ID;
1862   Task_Variable       :    out RTEMS.Address;
1863   Result              :    out RTEMS.Status_Codes
1864);
1865@end example
1866@end ifset
1867
1868@subheading DIRECTIVE STATUS CODES:
1869@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
1870@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
1871@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
1872@code{@value{RPREFIX}INVALID_ADDRESS} - @code{task_variable} is NULL@*
1873@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks@*
1874
1875@subheading DESCRIPTION:
1876This directive removes the given location from a task's context.
1877
1878@subheading NOTES:
1879
1880NONE
Note: See TracBrowser for help on using the repository browser.