source: rtems-docs/c_user/task_manager.rst @ d389819

4.115am
Last change on this file since d389819 was d389819, checked in by Amar Takhar <amar@…>, on 01/18/16 at 05:37:40

Convert all Unicode to ASCII(128)

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