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

4.104.114.84.95
Last change on this file since a3a7527 was a3a7527, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 27, 1998 at 1:04:02 PM

Attempting to add variable so that in C all constants start with RTEMS_
and all directives start with rtems_.

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