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

4.8
Last change on this file since f3a4c7a was f3a4c7a, checked in by Joel Sherrill <joel.sherrill@…>, on 11/03/08 at 19:02:04

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

PR 1334/doc

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