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

Last change on this file since f1fcb459 was f1fcb459, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 25, 2003 at 2:15:45 PM

2003-11-25 Joel Sherrill <joel@…>

PR 528/rtems_misc

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