source: rtems/doc/user/task.t @ 1e524995

4.104.114.84.95
Last change on this file since 1e524995 was 1e524995, checked in by Joel Sherrill <joel.sherrill@…>, on Feb 6, 1998 at 2:14:30 PM

Updated copyrights

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