source: rtems/doc/itron3.0/task.t @ 10122b7

4.104.114.84.95
Last change on this file since 10122b7 was 10122b7, checked in by Joel Sherrill <joel.sherrill@…>, on May 20, 1999 at 9:55:30 PM

Initial revision

  • Property mode set to 100644
File size: 37.7 KB
Line 
1@c
2@c  This is the chapter from the RTEMS ITRON User's Guide that
3@c  documents the services provided by the task
4@c  manager.
5@c
6@c  $Id$
7@c
8
9@chapter Task Manager
10
11@section Introduction
12
13The task manager is used to directly control and access the state of tasks.  Included among these are functions for creating, deleting, starting and terminating tasks, for releasing the WAIT state of tasks, for enabling/disabling task dispatching, for changing task priority levels, for rotatingtasks on the ready queue, and for accessing task state.
14
15The services provided by the task manager are:
16
17@itemize @bullet
18@item @code{cre_tsk} - Create Task
19@item @code{del_tsk} - Delete Task
20@item @code{sta_tsk} - Start Task
21@item @code{ext_tsk} - Exit Issuing Task
22@item @code{exd_tsk} - Exit and Delete Task
23@item @code{ter_tsk} - Terminate Other Task
24@item @code{dis_dsp} - Disable Dispatch
25@item @code{ena_dsp} - Enable Dispatch
26@item @code{chg_pri} - Change Task Priority
27@item @code{rot_rdq} - Rotate Tasks on the Ready Queue
28@item @code{rel_wai} - Release Wait of Other Task
29@item @code{get_tid} - Get Task Identifier
30@item @code{ref_tsk} - Reference Task Status
31@end itemize
32
33@section Background
34
35@subsection Task Definition
36Many definitions of a task have been proposed in computer literature. Unfortunately, none of these definitions encompasses all facets of the concept in a manner which is operating system independent. Several of the more common definitions are provided to enable each user to select a definition which best matches their own experience and understanding of the task concept:
37
38@itemize @bullet
39@item a "dispatchable" unit.
40@item an entity to which the processor is allocated.
41@item an atomic unit of a real-time, multiprocessor system.
42@item single threads of execution which concurrently compete for resources.
43@item a sequence of closely related computations which can execute concurrently with other computational sequences.
44@item From our implementation perspective, a task is the smallest thread of execution which can compete on its own for system resources. A task is manifested by the existence of a task control block (TCB).
45@end itemize
46
47@subsection Task Manager Task Control Block
48 The Task Control Block (TCB) is a defined data structure which contains all the information that is pertinent to the execution of a task. During system initialization, implementation reserves a TCB for each task configured. A TCB is allocated upon creation of the task and is returned to the TCB free list upon deletion of the task.
49
50The TCB's elements are modified as a result of system calls made by the application in response to external and internal stimuli. The TCB contains a task's name, ID, current priority, current and starting states, TCB user extension pointer, scheduling control structures, as well as data required by a blocked task.
51
52A task's context is stored in the TCB when a task switch occurs. When the task regains control of the processor, its context is restored from the TCB. When a task is restarted, the initial state of the task is restored from the starting context area in the task's TCB.
53
54@subsection T_CTSK Structure
55The T_CTSK structure contains detailed information necessary to create the task. Such task attributes, start address, priority and stack size. 
56
57@example
58typedef struct t_ctsk @{
59  VP    exinf;     /* extended information */
60  ATR   tskatr;    /* task attributes */
61  FP    task;      /* task start address */
62  PRI   itskpri;   /* initial task priority */
63  INT   stksz;     /* stack size */
64  /* additional information may be included depending on the implementation */
65@} T_CTSK;
66
67@end example
68
69@subsection Task Manager Task States
70A task may exist in one of the following five states:
71
72@itemize @bullet
73@item RUN - Currently scheduled to the CPU
74@item READY - May be scheduled to the CPU
75@item Wait - Unable to be scheduled to the CPU
76@itemize @bullet
77@item (Specific) WAIT - The task is issued a command to wait on a condition
78@item SUSPEND - Another task suspended execution of the task
79@item WAIT-SUSPEND - Both the WAIT and SUSPEND states apply
80@end itemize
81@item DORMANT - Created task that is not started
82@item NON-EXISTENT - Uncreated or deleted task
83@end itemize
84
85An active task may occupy the RUN, READY, Wait or DORMANT state, otherwise the task is considered NON-EXISTENT. One or more tasks may be active in the system simultaneously. Multiple tasks communicate, synchronize, and compete for system resources with each other via system calls. The multiple tasks appear to execute in parallel, but actually each is dispatched to the CPU for periods of time determined by the scheduling algorithm. The scheduling of a task is based on its current state and priority.
86
87@subsection Task Manager Task Priority
88A task's priority determines its importance in relation to the other tasks executing on the same processor. Our implementation supports 255 levels of priority ranging from 1 to 255. Tasks of numerically smaller priority values are more important tasks than tasks of numerically larger priority values. For example, a task at priority level 5 is of higher privilege than a task at priority level 10. There is no limit to the number of tasks assigned to the same priority.
89
90Each task has a priority associated with it at all times. The initial value of this priority is assigned at task creation time. The priority of a task may be changed at any subsequent time.
91
92Priorities are used by the scheduler to determine which ready task will be allowed to execute. In general, the higher the logical priority of a task, the more likely it is to receive processor execution time.
93
94@section Operations
95
96@subsection Task Manager Creating Tasks
97The cre_tsk directive creates a task specified by tskid. Specifically, a TCB (Task Control Block) is allocated for the task to be created, and initialized according to accompanying parameter values of itskpri, task, stksz, etc.  A stack area is also allocated for the task based on the parameter stksz.
98
99@subsection Task Manager Starting and Restarting Tasks
100The sta_tsk directive starts the task specified by tskid.  Specifically, it changes the state of the task specified by tskid from DORMANT into RUN/READY.  This enables the task to compete, based on its current priority, for the processor and other system resources. Any actions, such as suspension or change of priority, performed on a task prior to starting it are nullified when the task is started.
101
102Stacd can be used to specify parameters to be passed to the task when it is started.  This parameter can be read by the task being started, and may be used for transmitting simple messages.
103
104The task priority on starting the task is given by the initial task priority parameter (itskpri) specified when the task was created.
105
106Start request is not queued in this this system call.  In other words, if this system call is issued when the target task is not in DORMANT state, the system call will be ignored, and an E_OBJ error returned to the issuing task.
107
108If cre_tsk [level EN] is not implemented on a system, tasks are created statically when the system is started.  Parameters required for creating a task, such as task starting address (task) and initial task priority (itskpri) are also specified statically at system startup.
109
110@subsection Task Manager Suspending and Resuming Tasks
111The sus_tsk directive suspends the execution of the task specified by tskid by putting it into SUSPEND state. SUSPEND state is released by issuing the rsm_tsk or frsm_tsk system call.
112
113If the task specified to sus_tsk is already in WAIT state, it will be put in the combined WAIT-SUSPEND state by the execution of sus_tsk.  If wait conditions for the task are later fulfilled, it will enter SUSPEND state. If rsm_tsk is issued on the task, it will return to the WAIT state before the suspension.
114
115Both rsm_tsk and fsm_tsk system calls release SUSPEND state of the task specified by tskid.  Specifically, they cause SUSPEND state to be released and the execution of the specified task to resume when the task has been suspended by the prior execution of sus_tsk.
116
117If the specified task is in WAIT-SUSPEND state, the execution of rsm_tsk only releases the SUSPEND state, and the task will become WAIT state.
118 
119@subsection Task Manager Changing Task Priority
120The chg_pri system call changes the current priority of the task specified by tskid to the value specified by tskpri.
121
122A task may specify itself by specifying tskid = TSK_SELF = 0.  Note, however, that an E_ID error will result if tskid = TSK_SELF = 0 is specified to a system call issued from a task-independent portion.
123
124The priority set by this system call remains in effect until the task exits.  Once a task enters DORMANT state, its priority prior to exiting is lost.  When a task which enters DORMANT state restarts, the initial task priority (itskpri) specified at task creation or at system startup will be used.
125
126@subsection Task Manager Task Deletion
127The del_tsk system call deletes the task specified by tskid.  Specifically, it changes the state of the task specified by tskid from DORMANT into NON-EXISTENT (a virtual state not existing on the system), and then clears the TCB and releases stack. An E_OBJ error results if this system call is used on a task which is not DORMANT.
128
129After deletion, another task having the same ID number can be created.
130
131The exd_tsk system call causes the issuing task to exit and then delete itself.
132
133When a task exits, that task does not automatically release all the resources (memory blocks, semaphores, etc.) which it had secured prior to the call.  It is the user's responsibility to see to it that all resources are released beforehand.
134
135@section System Calls
136
137This section details the task manager's services.
138A subsection is dedicated to each of this manager's services and describes the calling sequence, related constants, usage, and status codes.
139
140
141@c
142@c  cre_tsk
143@c
144
145@page
146@subsection cre_tsk - Create Task
147
148@subheading CALLING SEQUENCE:
149
150@ifset is-C
151@example
152ER cre_tsk(
153  ID tskid,
154  T_CTSK *pk_ctsk
155);
156@end example
157@end ifset
158
159@ifset is-Ada
160@end ifset
161
162@subheading STATUS CODES:
163
164@code{E_OK} - Normal Completion
165
166@code{E_NOMEM} - Insufficient memory (Memory for control block and/or user stack cannot be allocated)
167
168@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
169
170@code{E_RSATR} - Reserved attribute (tskatr was invalid or could not be used)
171
172@code{E_OBJ} - Invalid object state (a task of the same ID already exists)
173
174@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
175
176@code{E_PAR} -  Parameter error (pk_ctsk, task, itskpri and/or stksz is invalid)
177
178@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
179
180@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
181
182@code{EN_PAR} -  A value outside the range supported by the target node and/or transmission packet format was specified as a parameter (a value outside supported range was specified for exinf, tskatr, task, itskpri and/or stksz)
183
184@subheading DESCRIPTION:
185This system call creates the task specified by tskid.  Specifically, a TCB (Task Control Block) is allocated for the task to be created, and initialized according to accompanying parameter values of itskpri, task, tksz, etc.  A stack area is also allocated for the task based on the parameter stksz.
186
187@subheading NOTES:
188User tasks have positive ID numbers, while system tasks have negative ID numbers.  User tasks cannot access system objects (objects having negative ID numbers).
189 
190The new task created by this system call will be put in DORMANT state.
191
192Extended information (exinf) has been added.  This allows the user to include additional information about task attributes.  If a larger region is desired for including user information, the user should allocate memory area and set the address of the memory packet to exinf.
193
194Multiprocessing is not supported. Thus none of the "EN_" status codes will be returned.
195
196
197@c
198@c  del_tsk
199@c
200
201@page
202@subsection del_tsk - Delete Task
203
204@subheading CALLING SEQUENCE:
205
206@ifset is-C
207@example
208ER del_tsk(
209  ID tskid
210);
211@end example
212@end ifset
213
214@ifset is-Ada
215@end ifset
216
217@subheading STATUS CODES:
218
219@code{E_OK} - Normal Completion
220
221@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
222
223@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
224
225@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
226
227@code{E_OBJ} -  Invalid object state (the target task is not in DORMANT state)
228
229@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
230
231@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
232
233@subheading DESCRIPTION:
234This system call deletes the task specified by tskid.  Specifically, it changes the state of the task specified by tskid from DORMANT into NON-EXISTENT (a virtual state not existing on the system), and then clears the TCB and releases stack. An E_OBJ error results if this system call is used on a task which is not DORMANT.
235
236After deletion, another task having the same ID number can be created.
237
238@subheading NOTES:
239A task cannot delete itself by this system call.  An E_OBJ error will result if a task specifies itself, since such a task cannot be DORMANT. Use the exd_tsk system call rather than this one when a task needs to delete itself.
240
241
242@c
243@c  sta_tsk
244@c
245
246@page
247@subsection sta_tsk - Start Task
248
249@subheading CALLING SEQUENCE:
250
251@ifset is-C
252@example
253ER sta_tsk(
254  ID tskid,
255  INT stacd
256);
257@end example
258@end ifset
259
260@ifset is-Ada
261@end ifset
262
263@subheading STATUS CODES:
264
265@code{E_OK} - Normal Completion
266
267@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
268
269@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
270
271@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
272
273@code{E_OBJ} - Invalid object state (the target task is not in DORMANT state)
274
275@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
276
277@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
278
279@code{EN_PAR} - A value outside the range supported by the target node and/or transmission packet format was specified as a parameter (a value outside supported range was specified for stacd)
280
281@subheading DESCRIPTION:
282This system call starts the task specified by tskid.  Specifically, it changes the state of the task specified by tskid from DORMANT into RUN/READY.
283
284Stacd can be used to specify parameters to be passed to the task when it is started.  This parameter can be read by the task being started, and may be used for transmitting simple messages.
285
286The task priority on starting the task is given by the initial task priority parameter (itskpri) specified when the task was created.
287
288Start request is not queued in this this system call.  In other words, if this system call is issued when the target task is not in DORMANT state, the system call will be ignored, and an E_OBJ error returned to the issuing task.
289
290If cre_tsk [level EN] is not implemented on a system, tasks are created statically when the system is started.  Parameters required for creating a task, such as task starting address (task) and initial task priority (itskpri) are also specified statically at system startup.
291
292@subheading NOTES:
293
294
295@c
296@c  ext_tsk
297@c
298
299@page
300@subsection ext_tsk - Exit Issuing Task
301
302@subheading CALLING SEQUENCE:
303
304@ifset is-C
305@example
306void ext_tsk(void);
307@end example
308@end ifset
309
310@ifset is-Ada
311@end ifset
312
313@subheading STATUS CODES:
314
315@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
316
317 * System call may detect this error.  The error is not returned to the context issuing the system call.  Error codes therefore cannot be returned directly as a return parameter of the system call.  The behavior on error detection is implementation dependent.
318
319
320@subheading DESCRIPTION:
321This system call causes the issuing task to exit, changing the state of the task into the DORMANT state.
322
323@subheading NOTES:
324When a task exits due to ext_tsk, that task does not automatically release all the resources (memory blocks, semaphores, etc.) which it had obtained prior to the system call.  It is the user's responsibility that all resources are released beforehand.
325
326Ext_tsk is a system call which does not return to the issuing context. Accordingly, even if an error code is returned on detection of some error, it is normal for tasks making this system call not to perform any error checking, and it is in fact possible that a program could run out of control.  For this reason, even if an error is detected upon issuing this system call, the error is not returned to the task which issued the system call.  If information on detected errors is required it should be left in a messagebuffer used as an error log.
327
328In principle, information concerning a task recorded in the TCB, such as task priority, is reset whenever a task is placed in DORMANT state.  For example, its task priority after being restarted would be reset to the initial task priority (itskpri) specified by cre_tsk when it was first created, even if a task's priority was changed using chg_pri, then that task exits using ext_tsk, but later started by sta_tsk.  Task priority does not return to what it was when ext_tsk was executed.
329
330
331@c
332@c  exd_tsk
333@c
334
335@page
336@subsection exd_tsk - Exit and Delete Issuing Task
337
338@subsection exd_tsk - Exit and Delete Task
339
340@ifset is-C
341@example
342void exd_tsk(void);
343@end example
344void exd_tsk(
345
346);
347
348@ifset is-Ada
349@end ifset
350
351@subheading STATUS CODES:
352
353@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
354
355 * System call may detect the following error.  The error is not returned to the context issuing the system call even.  Error codes therefore cannot be returned directly as a return parameter of the system call.  The behavior on error detection is implementation dependent.
356
357@subheading DESCRIPTION:
358This system call causes the issuing task to exit and then delete itself.  In other words the state of the issuing task changes into the NON-EXISTENT (a virtual state not existing on the system).
359
360@subheading NOTES:
361When a task exits with exd_tsk, that task does not automatically release all the resources (memory blocks, semaphores, etc.) which it had secured prior to the call.  It is the user's responsibility to see to it that all resources are released beforehand.
362
363Exd_tsk is a system call which does not return any parameters to the original issuing context.  Accordingly, even if an error code is returned on detection of some error, it is normal for tasks making this system call not to perform any error checking, and it is in fact possible that a program could run out of control.  For this reason, even if an error is detected upon making this system call, it is supposed that the error is not returned to the task which issued the system call.  If information on detected errors is required it should be left in a messagebuffer used as an error log.
364
365
366@c
367@c  ter_tsk
368@c
369
370@page
371@subsection ter_tsk - Terminate Other Task
372
373@subheading CALLING SEQUENCE:
374
375@ifset is-C
376@example
377ER ter_tsk(
378  ID tskid
379);
380@end example
381@end ifset
382
383@ifset is-Ada
384@end ifset
385
386@subheading STATUS CODES:
387
388@code{E_OK} - Normal Completion
389
390@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
391
392@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
393
394@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
395
396@code{E_OBJ} - Invalid object state (the target task is already in DORMANT state or a task invalidly specified itself)
397
398@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
399
400@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
401
402@subheading DESCRIPTION:
403This system call forcibly terminates the task specified by tskid.  That is, it changes the state of the task specified by tskid into DORMANT.
404
405Even if the target task is in wait state (including SUSPEND state), its wait state will be released and then it will be terminated.  If the target task is on a queue of some sort (such as waiting for a semaphore), it will be removed from that queue by ter_tsk.
406
407A task cannot specify the issuing task in this system call.  An E_OBJ error will result if a task specifies itself.
408
409There is an intermediate state waiting for the response (TR packet or TA packet) from the target node after executing the system call to access the other node and making a request (sending a TP packet) to the node. This state is called the "connection function response wait (TTW_NOD)" state. The ter_tsk system call may specify tasks which are in the connection function response wait state.  Tasks which are waiting for objects (such as a semaphore) on another node may also be specified to this system call. In such cases, ter_tsk will halt any system calls accessing other nodes which have been issued by the task to be terminated.
410
411@subheading NOTES:
412When a task is terminated by ter_tsk, that task does not automatically release all the resources (memory blocks, semaphores, etc.) which it had obtained prior to the call.  It is the user's responsibility to see to it that all resources are released beforehand.
413
414In principle, information concerning a task recorded in the TCB, such as task priority, is reset whenever a task is placed in DORMANT state.  For example, its task priority after being restarted would be reset to the initial task priority (itskpri) specified by cre_tsk when it was first created, even if a task's priority was changed using chg_pri, then that task is terminated by ter_tsk, but later started by sta_tsk.  Task priority does not return to what it was when ter_tsk was executed.
415
416
417@c
418@c  dis_dsp
419@c
420
421@page
422@subsection dis_dsp - Disable Dispatch
423
424@subheading CALLING SEQUENCE:
425
426@ifset is-C
427@example
428ER dis_dsp(void);
429@end example
430ER dis_dsp(
431
432);
433
434@ifset is-Ada
435@end ifset
436
437@subheading STATUS CODES:
438
439@code{E_OK} - Normal Completion
440
441@code{E_CTX} - Context error (issued from task-independent portions or issued after execution of loc_cpu)
442
443@subheading DESCRIPTION:
444This system call disables task dispatching.  Dispatching will remain disabled after this call is issued until a subsequent call to ena_dsp is issued. The status of the issuing task will not be allowed to be changed to READY from the RUN.  It cannot be changed into WAIT, either.  However, since external interrupt is not disabled, interrupt handlers are allowed to run even when dispatching has been disabled.  While an executing task may be preempted by an interrupt handler with dispatching disabled, there is no possibility that it will be preempted by another task.
445
446The following operations occur during the time dispatching is disabled.
447@itemize @bullet
448@item Even in a situation where normally a task issuing dis_dsp should be preempted by a system call issued by an interrupt handler or by the task issuing dis_dsp, the task that should normally be executed is not dispatched.  Instead, dispatching of this task is delayed until dispatch disabled state is cleared by ena_dsp.
449
450@item If an interrupt handler invoked during dispatch disabled state issues sus_tsk for a running task (one that executed dis_dsp) to put it in SUSPEND state, or ter_tsk to put it in DORMANT state, the task transition is delayed until dispatch disabled state is cleared.
451
452@item An E_CTX error will result if the task which has executed dis_dsp issues any system calls (such as slp_tsk or wai_sem) capable of putting an issuing task into WAIT state.
453
454@item An EN_CTXID error will result if a task which has executed dis_dsp attempts to operate on objects on another node (that is, if the ID parameter of the system call issued refers to an object on another node).
455
456@item TSS_DDSP will be returned as sysstat if system status is referenced using ref_sys.
457@end itemize
458No error will result if a task already in dispatch disable state issues dis_dsp.  It only keeps dispatch disabled state.  No matter how many times dis_dsp has been issued, a single ena_dsp enables dispatching again.  It is therefore for the user to determine what to do with nested pairs of dis_dsp and ena_dsp.
459
460An E_CTX error will result if dis_dsp is issued when both interrupt and dispatching are disabled with loc_cpu.  (For details, see the description of loc_cpu.)
461
462@subheading NOTES:
463A running task cannot enter DORMANT or NON-EXISTENT state while dispatching is disabled.  An E_CTX error will result if an running task issues either ext_tsk or exd_tsk while interrupt and dispatching are disabled.  Note however that since both ext_tsk and exd_tsk are system calls which do not return to their original contexts, error notification using return parameters of these system calls is not possible.  If information on detected errors is required it should be left in a messagebuffer used as an error log.
464
465Only if the system is not a multiprocessor configuration, system can take advantage of the dispatch disabled state for exclusive inter-task control.
466
467
468@c
469@c  ena_dsp
470@c
471
472@page
473@subsection ena_dsp - Enable Dispatch
474
475@subheading CALLING SEQUENCE:
476
477@ifset is-C
478@example
479ER ena_dsp(void);
480@end example
481ER ena_dsp(
482
483);
484
485@ifset is-Ada
486@end ifset
487
488@subheading STATUS CODES:
489
490@code{E_OK} - Normal Completion
491
492@code{E_CTX} - Context error (issued from task-independent portions or issued after execution of loc_cpu)
493
494@subheading DESCRIPTION:
495This system call enables task dispatching, that is, it finishes dispatch disabled state caused by the execution of dis_dsp.
496
497No error will result if a task which is not in dispatch disabled state issues ena_dsp.  In this case, dispatching will just remain enabled.
498
499An E_CTX error will result if ena_dsp is issued when both interrupt and dispatching are disabled with loc_cpu.  (For details, see the description of loc_cpu.)
500
501@subheading NOTES:
502
503
504@c
505@c  chg_pri
506@c
507
508@page
509@subsection chg_pri - Change Task Priority
510
511@subheading CALLING SEQUENCE:
512
513@ifset is-C
514@example
515ER chg_pri(
516  ID tskid,
517  PRI tskpri
518);
519@end example
520@end ifset
521
522@ifset is-Ada
523@end ifset
524
525@subheading STATUS CODES:
526
527@code{E_OK} - Normal Completion
528
529@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
530
531@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
532
533@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
534
535@code{E_PAR} - Parameter error (the value of tskpri is invalid or may not be used)
536
537@code{E_OBJ} - Invalid object state (the target task is in DORMANT state)
538
539@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
540
541@code{EN_CTXID} = Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
542
543@code{EN_PAR} - A value outside the range supported by the target node and/or transmission packet format was specified as a parameter (a value outside supported range was specified for tskpri)
544
545@subheading DESCRIPTION:
546This system call changes the current priority of the task specified by tskid to the value specified by tskpri.
547
548Under uITRON 3.0 specification, at least any value of 1 through 8 can be specified as task priority.  The smaller the value, the higher the priority.  Priority levels -4 through 0 are reserved, and they may not be used.  Priority levels outside this range (including negative values) may also be specified depending on the implementation; this is considered an extended function [level X] for which compatibility and connectivity are not guaranteed.  In general, negative priority levels are reserved for use by the system.
549
550A task may specify itself by specifying tskid = TSK_SELF = 0.  Note, however, that an E_ID error will result if tskid = TSK_SELF = 0 is specified to a system call issued from a task-independent portion.  The priority set by this system call remains in effect until the task exits.  Once a task enters DORMANT state, its priority prior to exiting is lost.  When a task which enters DORMANT state restarts, the initial task priority (itskpri) specified at task creation or at system startup will be used.
551
552If the target task is linked to ready queue or any other queue, this system call may result in the re-ordering of the queues.  If chg_pri is executed on a task waiting on the ready queue (including tasks in RUN state) or other priority-based queue, the target task will be moved to the end of the part of the queue for the associated priority.  If the priority specified is the same as the current priority, the task will still be moved behind other tasks of the same priority.  It is therefore possible for a task to relinquish its execution privileges using chg_pri on itself by specifying its current priority.
553
554@subheading NOTES:
555Depending on the implementation, specifying tskpri = TPRI_INI = 0 may cause a task's priority to be reset to the initial task priority (itskpri) which was defined when it was first created or when the system started.  This feature is used in some implementations in order to reset the task priority to its original value after setting it to a higher value for indivisible processing.  This feature is an extended function [level X] for which compatibility and connectivity are not guaranteed.
556
557
558@c
559@c  rot_rdq
560@c
561
562@page
563@subsection rot_rdq - Rotate Tasks on the Ready Queue
564
565@subheading CALLING SEQUENCE:
566
567@ifset is-C
568@example
569ER rot_rdq(
570  PRI tskpri
571);
572@end example
573@end ifset
574
575@ifset is-Ada
576@end ifset
577
578@subheading STATUS CODES:
579
580@code{E_OK} - Normal Completion
581
582@code{E_PAR} - Parameter error (the value of tskpri is invalid)
583
584@subheading DESCRIPTION:
585This system call rotates tasks on the ready queue associated with the priority level specified by tskpri.  Specifically, the task at the head of the ready queue of the priority level in question is moved to the end of the ready queue, thus switching the execution of tasks having the same priority.  Round robin scheduling may be implemented by periodically issuing this system call in a given period of time.
586
587When rot_rdq is issued by task portions with tskpri = TPRI_RUN = 0, the ready queue with the priority level of the issuing task is rotated.
588
589When TPRI_RUN or a task's own priority level are specified for tskpri to rot_rdq, the task issuing the system call will be placed on the end of its ready queue.  In other words, task can issue rot_rdq to relinquishing its execution privileges.  The concept of "ready queue" envisioned in the description of this system call is one which includes the task in RUN state.
590
591This system call does nothing if there are no tasks on the ready queue of the specified priority.  No error will result.
592
593This system call cannot rotate ready queues on other nodes.
594
595@subheading NOTES:
596Depending on the implementation, it may be possible to issue rot_rdq(tskpri = TPRI_RUN) from task-independent portions, such as a cyclic handler.  In this case the ready queue including the running task, or the ready queue including the highest priority task, is rotated.  Normally these two are the same, but not always, as when task dispatching is delayed.  In that case it is implementation dependent whether to rotate the ready queue including the running task or the ready queue including the highest priority task.  Note that this is an extended function [Level X] for which compatibility and connectivity are not guaranteed.
597
598
599@c
600@c  rel_wai
601@c
602
603@page
604@subsection rel_wai - Release Wait of Other Task
605
606@subheading CALLING SEQUENCE:
607
608@ifset is-C
609@example
610ER rel_wai(
611  ID tskid
612);
613@end example
614@end ifset
615
616@ifset is-Ada
617@end ifset
618
619@subheading STATUS CODES:
620
621@code{E_OK} - Normal Completion
622
623@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
624
625@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
626
627@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
628
629@code{E_OBJ} - Invalid object state (the target task is not in WAIT state (including when it is in DORMANT state or when the issuing task specifies itself))
630
631@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
632
633@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
634
635@subheading DESCRIPTION:
636This system call forcibly releases WAIT state (not including SUSPEND state)
637of the task specified by tskid.
638
639An E_RLWAI error is returned to the task whose WAIT state has been released using rel_wai. 
640
641Wait release requests by rel_wai are not queued.  In other words, if the task specified by tskid is already in WAIT state, the WAIT state is released, otherwise an E_OBJ error will be returned to the issuer.  An E_OBJ error will also result when a task specifies itself to this system call.
642
643Rel_wai does not release SUSPEND state.  If rel_wai is issued on a task in WAIT-SUSPEND state, WAIT will be released but SUSPEND will continue for that task. When SUSPEND should also be released, the frsm_tsk system call must be issued separately.
644
645@subheading NOTES:
646A function similar to timeout can be implemented using an alarm handler which issues this system call on tasks specified time after they have entered WAIT state.
647
648Rel_wai and wup_tsk differ in the following points.
649@itemize @bullet
650@item Wup_tsk can only release the WAIT state by slp_tsk or tslp_tsk, while rel_wai can release WAIT states caused by these and other calls (including wai_flg, wai_sem, rcv_msg, get_blk, etc.).
651@item As seen from the target task, releasing WAIT state with wup_tsk results in a normal completion (E_OK), whereas releasing WAIT state with rel_wai results in an error (E_RLWAI).
652@item When wup_tsk is used, a request is queued even if neither slp_tsk nor tslp_tsk have been executed on the target task yet.  When rel_wai is used to the task which is not in WAIT state, an E_OBJ error will result.
653@end itemize
654
655
656@c
657@c  get_tid
658@c
659
660@page
661@subsection get_tid - Get Task Identifier
662
663@subheading CALLING SEQUENCE:
664
665@ifset is-C
666@example
667ER get_tid(
668  ID *p_tskid
669);
670@end example
671@end ifset
672
673@ifset is-Ada
674@end ifset
675
676@subheading STATUS CODES:
677
678@code{E_OK} - Normal Completion
679
680@subheading DESCRIPTION:
681This system call gets the ID of the issuing task.
682
683If this system call is issued from a task-independent portion, tskid will be FALSE=0.
684
685@subheading NOTES:
686
687
688@c
689@c  ref_tsk
690@c
691
692@page
693@subsection ref_tsk - Reference Task Status
694
695@subheading CALLING SEQUENCE:
696
697@ifset is-C
698@example
699ER ref_tsk(
700  T_RTSK *pk_rtsk,
701  ID tskid
702);
703@end example
704@end ifset
705
706@ifset is-Ada
707@end ifset
708
709@subheading STATUS CODES:
710
711@code{E_OK} - Normal Completion
712
713@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
714
715@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
716
717@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
718
719@code{E_PAR} - Parameter error (the packet address for return parameters cannot be used)
720
721@code{EN_OBJNO} -  An object number which could not be accessed on the target node is specified.
722
723@code{EN_CTXID} - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion
724
725@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was returned as a return parameter (a value outside supported range was returned for exinf, tskpri and/or tskstat)
726
727@subheading DESCRIPTION:
728This system call refers to the state of the task specified by tskid, and returns its current priority (tskpri), its task state (tskstat), and its extended information (exinf).
729
730Tskstat may take the following values.
731
732    tskstat:
733@itemize @bullet
734@item   TTS_RUN H'0...01        RUN state (currently running)
735@item   TTS_RDY H'0...02        READY state (ready to run)
736@item   TTS_WAI H'0...04        WAIT state (waiting for something)
737@item   TTS_SUS H'0...08        SUSPEND state (forcibly made to wait)
738@item   TTS_WAS H'0...0c        WAIT-SUSPEND state
739@item   TTS_DMT H'0...10        DORMANT state
740@end itemize
741
742Since these task states are expressed by bit correspondences they are convenient when looking for OR conditions (such as whether a task is in RUN or READY state).  TTS_WAS is a combination of both TTS_SUS and TTS_WAI, TTS_SUS does not combine with any of the other states (TTS_RUN, TTS_RDY or TTS_DMT).
743
744A task may specify itself by specifying tskid = TSK_SELF = 0.  Note, however, that an E_ID error will result if tskid = TSK_SELF = 0 is specified when this system call is issued from a task-independent portion.
745
746An E_NOEXS error will result if the task specified to ref_tsk does not exist.
747
748Tskstat will be TTS_RUN if ref_tsk is executed specifying a task which has been interrupted by an interrupt handler.
749
750@subheading NOTES:
751The values of TTS_RUN, TTS_RDY, TTS_WAI, etc. as return values for tskstat are not necessarily the same value to be entered in the TCB.  The way in which task state is represented in the TCB is implementation dependent.  When ref_tsk is executed, the internal representation of task state may simply be converted to the standard values TTS_RUN, TTS_RDY, TTS_WAI, etc.
752
753Depending on the implementation, the following additional information can also be referenced in addition to exinf, tskpri and tskstat.
754
755@itemize @bullet
756@item tskwait Reason for wait
757@item wid     Wait object ID
758@item wupcnt  Number of queued wakeup requests
759@item suscnt  Number of nested SUSPEND requests
760@item tskatr  Task attributes
761@item task    Task starting address
762@item itskpri Initial task priority
763@item stksz   Stack size
764@end itemize
765
766
767
768
769
Note: See TracBrowser for help on using the repository browser.