source: rtems/doc/user/task.t @ 6f645ff

4.104.114.84.95
Last change on this file since 6f645ff was 6f645ff, checked in by Joel Sherrill <joel.sherrill@…>, on 02/29/00 at 14:07:38

Eric Norum spotted this sentence where it said preemption had to be
disabled for timeslicing to happen. This was wrong.

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