source: rtems/doc/user/task.t @ 22cce675

4.11
Last change on this file since 22cce675 was 22cce675, checked in by Sebastian Huber <sebastian.huber@…>, on Dec 12, 2014 at 11:53:07 AM

doc: Clarify rtems_task_set_priority()

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