source: rtems/doc/user/task.t @ 0660b4f8

4.104.114.84.9
Last change on this file since 0660b4f8 was 0660b4f8, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 16, 1999 at 7:50:56 PM

Changed copyright date to 1999.

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