source: rtems/doc/itron3.0/task.t @ 086a898a

4.104.114.84.95
Last change on this file since 086a898a was 086a898a, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 16, 1999 at 7:47:37 PM

Added copyright.

  • Property mode set to 100644
File size: 37.8 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1999.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  This is the chapter from the RTEMS ITRON User's Guide that
7@c  documents the services provided by the task
8@c  manager.
9@c
10@c  $Id$
11@c
12
13@chapter Task Manager
14
15@section Introduction
16
17The 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.
18
19The services provided by the task manager are:
20
21@itemize @bullet
22@item @code{cre_tsk} - Create Task
23@item @code{del_tsk} - Delete Task
24@item @code{sta_tsk} - Start Task
25@item @code{ext_tsk} - Exit Issuing Task
26@item @code{exd_tsk} - Exit and Delete Issuing Task
27@item @code{ter_tsk} - Terminate Other Task
28@item @code{dis_dsp} - Disable Dispatch
29@item @code{ena_dsp} - Enable Dispatch
30@item @code{chg_pri} - Change Task Priority
31@item @code{rot_rdq} - Rotate Tasks on the Ready Queue
32@item @code{rel_wai} - Release Wait of Other Task
33@item @code{get_tid} - Get Task Identifier
34@item @code{ref_tsk} - Reference Task Status
35@end itemize
36
37@section Background
38
39@subsection Task Definition
40Many 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:
41
42@itemize @bullet
43@item a "dispatchable" unit.
44@item an entity to which the processor is allocated.
45@item an atomic unit of a real-time, multiprocessor system.
46@item single threads of execution which concurrently compete for resources.
47@item a sequence of closely related computations which can execute concurrently with other computational sequences.
48@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).
49@end itemize
50
51@subsection Task Manager Task Control Block
52 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.
53
54The 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.
55
56A 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.
57
58@subsection T_CTSK Structure
59The T_CTSK structure contains detailed information necessary to create the task. Such task attributes, start address, priority and stack size. 
60
61@example
62typedef struct t_ctsk @{
63  VP    exinf;     /* extended information */
64  ATR   tskatr;    /* task attributes */
65  FP    task;      /* task start address */
66  PRI   itskpri;   /* initial task priority */
67  INT   stksz;     /* stack size */
68  /* additional implementation dependent information may be included */
69@} T_CTSK;
70
71@end example
72
73@subsection Task Manager Task States
74A task may exist in one of the following five states:
75
76@itemize @bullet
77@item RUN - Currently scheduled to the CPU
78@item READY - May be scheduled to the CPU
79@item Wait - Unable to be scheduled to the CPU
80@itemize @bullet
81@item (Specific) WAIT - The task is issued a command to wait on a condition
82@item SUSPEND - Another task suspended execution of the task
83@item WAIT-SUSPEND - Both the WAIT and SUSPEND states apply
84@end itemize
85@item DORMANT - Created task that is not started
86@item NON-EXISTENT - Uncreated or deleted task
87@end itemize
88
89An 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.
90
91@subsection Task Manager Task Priority
92A 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.
93
94Each 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.
95
96Priorities 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.
97
98@section Operations
99
100@subsection Task Manager Creating Tasks
101The 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.
102
103@subsection Task Manager Starting and Restarting Tasks
104The 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.
105
106Stacd 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.
107
108The task priority on starting the task is given by the initial task priority parameter (itskpri) specified when the task was created.
109
110Start 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.
111
112If 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.
113
114@subsection Task Manager Suspending and Resuming Tasks
115The 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.
116
117If 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.
118
119Both 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.
120
121If 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.
122 
123@subsection Task Manager Changing Task Priority
124The chg_pri system call changes the current priority of the task specified by tskid to the value specified by tskpri.
125
126A 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.
127
128The 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.
129
130@subsection Task Manager Task Deletion
131The 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.
132
133After deletion, another task having the same ID number can be created.
134
135The exd_tsk system call causes the issuing task to exit and then delete itself.
136
137When 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.
138
139@section System Calls
140
141This section details the task manager's services.
142A subsection is dedicated to each of this manager's services and describes the calling sequence, related constants, usage, and status codes.
143
144
145@c
146@c  cre_tsk
147@c
148
149@page
150@subsection cre_tsk - Create Task
151
152@subheading CALLING SEQUENCE:
153
154@ifset is-C
155@example
156ER cre_tsk(
157  ID tskid,
158  T_CTSK *pk_ctsk
159);
160@end example
161@end ifset
162
163@ifset is-Ada
164@end ifset
165
166@subheading STATUS CODES:
167
168@code{E_OK} - Normal Completion
169
170@code{E_NOMEM} - Insufficient memory (Memory for control block and/or user stack cannot be allocated)
171
172@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
173
174@code{E_RSATR} - Reserved attribute (tskatr was invalid or could not be used)
175
176@code{E_OBJ} - Invalid object state (a task of the same ID already exists)
177
178@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
179
180@code{E_PAR} -  Parameter error (pk_ctsk, task, itskpri and/or stksz is invalid)
181
182@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
183
184@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
185
186@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)
187
188@subheading DESCRIPTION:
189This 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.
190
191@subheading NOTES:
192User tasks have positive ID numbers, while system tasks have negative ID numbers.  User tasks cannot access system objects (objects having negative ID numbers).
193 
194The new task created by this system call will be put in DORMANT state.
195
196Extended 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.
197
198Multiprocessing is not supported. Thus none of the "EN_" status codes will be returned.
199
200
201@c
202@c  del_tsk
203@c
204
205@page
206@subsection del_tsk - Delete Task
207
208@subheading CALLING SEQUENCE:
209
210@ifset is-C
211@example
212ER del_tsk(
213  ID tskid
214);
215@end example
216@end ifset
217
218@ifset is-Ada
219@end ifset
220
221@subheading STATUS CODES:
222
223@code{E_OK} - Normal Completion
224
225@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
226
227@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
228
229@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
230
231@code{E_OBJ} -  Invalid object state (the target task is not in DORMANT state)
232
233@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
234
235@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
236
237@subheading DESCRIPTION:
238This 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.
239
240After deletion, another task having the same ID number can be created.
241
242@subheading NOTES:
243A 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.
244
245
246@c
247@c  sta_tsk
248@c
249
250@page
251@subsection sta_tsk - Start Task
252
253@subheading CALLING SEQUENCE:
254
255@ifset is-C
256@example
257ER sta_tsk(
258  ID tskid,
259  INT stacd
260);
261@end example
262@end ifset
263
264@ifset is-Ada
265@end ifset
266
267@subheading STATUS CODES:
268
269@code{E_OK} - Normal Completion
270
271@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
272
273@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
274
275@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
276
277@code{E_OBJ} - Invalid object state (the target task is not in DORMANT state)
278
279@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
280
281@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
282
283@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)
284
285@subheading DESCRIPTION:
286This system call starts the task specified by tskid.  Specifically, it changes the state of the task specified by tskid from DORMANT into RUN/READY.
287
288Stacd 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.
289
290The task priority on starting the task is given by the initial task priority parameter (itskpri) specified when the task was created.
291
292Start 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.
293
294If 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.
295
296@subheading NOTES:
297
298
299@c
300@c  ext_tsk
301@c
302
303@page
304@subsection ext_tsk - Exit Issuing Task
305
306@subheading CALLING SEQUENCE:
307
308@ifset is-C
309@example
310void ext_tsk(void);
311@end example
312@end ifset
313
314@ifset is-Ada
315@end ifset
316
317@subheading STATUS CODES:
318
319@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
320
321 * 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.
322
323
324@subheading DESCRIPTION:
325This system call causes the issuing task to exit, changing the state of the task into the DORMANT state.
326
327@subheading NOTES:
328When 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.
329
330Ext_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.
331
332In 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.
333
334
335@c
336@c  exd_tsk
337@c
338
339@page
340@subsection exd_tsk - Exit and Delete Issuing Task
341
342@subheading CALLING SEQUENCE:
343
344@ifset is-C
345@example
346void exd_tsk(void);
347@end example
348@end ifset
349
350@ifset is-Ada
351@end ifset
352
353@subheading STATUS CODES:
354
355@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
356
357 * 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.
358
359@subheading DESCRIPTION:
360This 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).
361
362@subheading NOTES:
363When 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.
364
365Exd_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.
366
367
368@c
369@c  ter_tsk
370@c
371
372@page
373@subsection ter_tsk - Terminate Other Task
374
375@subheading CALLING SEQUENCE:
376
377@ifset is-C
378@example
379ER ter_tsk(
380  ID tskid
381);
382@end example
383@end ifset
384
385@ifset is-Ada
386@end ifset
387
388@subheading STATUS CODES:
389
390@code{E_OK} - Normal Completion
391
392@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
393
394@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
395
396@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
397
398@code{E_OBJ} - Invalid object state (the target task is already in DORMANT state or a task invalidly specified itself)
399
400@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
401
402@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
403
404@subheading DESCRIPTION:
405This system call forcibly terminates the task specified by tskid.  That is, it changes the state of the task specified by tskid into DORMANT.
406
407Even 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.
408
409A task cannot specify the issuing task in this system call.  An E_OBJ error will result if a task specifies itself.
410
411There 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.
412
413@subheading NOTES:
414When 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.
415
416In 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.
417
418
419@c
420@c  dis_dsp
421@c
422
423@page
424@subsection dis_dsp - Disable Dispatch
425
426@subheading CALLING SEQUENCE:
427
428@ifset is-C
429@example
430ER dis_dsp(void);
431@end example
432@end ifset
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
481@end ifset
482
483@ifset is-Ada
484@end ifset
485
486@subheading STATUS CODES:
487
488@code{E_OK} - Normal Completion
489
490@code{E_CTX} - Context error (issued from task-independent portions or issued after execution of loc_cpu)
491
492@subheading DESCRIPTION:
493This system call enables task dispatching, that is, it finishes dispatch disabled state caused by the execution of dis_dsp.
494
495No error will result if a task which is not in dispatch disabled state issues ena_dsp.  In this case, dispatching will just remain enabled.
496
497An 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.)
498
499@subheading NOTES:
500
501
502@c
503@c  chg_pri
504@c
505
506@page
507@subsection chg_pri - Change Task Priority
508
509@subheading CALLING SEQUENCE:
510
511@ifset is-C
512@example
513ER chg_pri(
514  ID tskid,
515  PRI tskpri
516);
517@end example
518@end ifset
519
520@ifset is-Ada
521@end ifset
522
523@subheading STATUS CODES:
524
525@code{E_OK} - Normal Completion
526
527@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
528
529@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
530
531@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
532
533@code{E_PAR} - Parameter error (the value of tskpri is invalid or may not be used)
534
535@code{E_OBJ} - Invalid object state (the target task is in DORMANT state)
536
537@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
538
539@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
540
541@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)
542
543@subheading DESCRIPTION:
544This system call changes the current priority of the task specified by tskid to the value specified by tskpri.
545
546Under 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.
547
548A 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.
549
550If 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.
551
552@subheading NOTES:
553Depending 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.
554
555
556@c
557@c  rot_rdq
558@c
559
560@page
561@subsection rot_rdq - Rotate Tasks on the Ready Queue
562
563@subheading CALLING SEQUENCE:
564
565@ifset is-C
566@example
567ER rot_rdq(
568  PRI tskpri
569);
570@end example
571@end ifset
572
573@ifset is-Ada
574@end ifset
575
576@subheading STATUS CODES:
577
578@code{E_OK} - Normal Completion
579
580@code{E_PAR} - Parameter error (the value of tskpri is invalid)
581
582@subheading DESCRIPTION:
583This 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.
584
585When 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.
586
587When 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.
588
589This system call does nothing if there are no tasks on the ready queue of the specified priority.  No error will result.
590
591This system call cannot rotate ready queues on other nodes.
592
593@subheading NOTES:
594Depending 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.
595
596
597@c
598@c  rel_wai
599@c
600
601@page
602@subsection rel_wai - Release Wait of Other Task
603
604@subheading CALLING SEQUENCE:
605
606@ifset is-C
607@example
608ER rel_wai(
609  ID tskid
610);
611@end example
612@end ifset
613
614@ifset is-Ada
615@end ifset
616
617@subheading STATUS CODES:
618
619@code{E_OK} - Normal Completion
620
621@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
622
623@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
624
625@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
626
627@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))
628
629@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
630
631@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
632
633@subheading DESCRIPTION:
634This system call forcibly releases WAIT state (not including SUSPEND state)
635of the task specified by tskid.
636
637An E_RLWAI error is returned to the task whose WAIT state has been released using rel_wai. 
638
639Wait 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.
640
641Rel_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.
642
643@subheading NOTES:
644A 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.
645
646Rel_wai and wup_tsk differ in the following points.
647@itemize @bullet
648@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.).
649@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).
650@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.
651@end itemize
652
653
654@c
655@c  get_tid
656@c
657
658@page
659@subsection get_tid - Get Task Identifier
660
661@subheading CALLING SEQUENCE:
662
663@ifset is-C
664@example
665ER get_tid(
666  ID *p_tskid
667);
668@end example
669@end ifset
670
671@ifset is-Ada
672@end ifset
673
674@subheading STATUS CODES:
675
676@code{E_OK} - Normal Completion
677
678@subheading DESCRIPTION:
679This system call gets the ID of the issuing task.
680
681If this system call is issued from a task-independent portion, tskid will be FALSE=0.
682
683@subheading NOTES:
684
685
686@c
687@c  ref_tsk
688@c
689
690@page
691@subsection ref_tsk - Reference Task Status
692
693@subheading CALLING SEQUENCE:
694
695@ifset is-C
696@example
697ER ref_tsk(
698  T_RTSK *pk_rtsk,
699  ID tskid
700);
701@end example
702@end ifset
703
704@ifset is-Ada
705@end ifset
706
707@subheading STATUS CODES:
708
709@code{E_OK} - Normal Completion
710
711@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
712
713@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
714
715@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
716
717@code{E_PAR} - Parameter error (the packet address for return parameters cannot be used)
718
719@code{EN_OBJNO} -  An object number which could not be accessed on the target node is specified.
720
721@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
722
723@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)
724
725@subheading DESCRIPTION:
726This 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).
727
728Tskstat may take the following values.
729
730    tskstat:
731@itemize @bullet
732@item   TTS_RUN H'0...01        RUN state (currently running)
733@item   TTS_RDY H'0...02        READY state (ready to run)
734@item   TTS_WAI H'0...04        WAIT state (waiting for something)
735@item   TTS_SUS H'0...08        SUSPEND state (forcibly made to wait)
736@item   TTS_WAS H'0...0c        WAIT-SUSPEND state
737@item   TTS_DMT H'0...10        DORMANT state
738@end itemize
739
740Since 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).
741
742A 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.
743
744An E_NOEXS error will result if the task specified to ref_tsk does not exist.
745
746Tskstat will be TTS_RUN if ref_tsk is executed specifying a task which has been interrupted by an interrupt handler.
747
748@subheading NOTES:
749The 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.
750
751Depending on the implementation, the following additional information can also be referenced in addition to exinf, tskpri and tskstat.
752
753@itemize @bullet
754@item tskwait Reason for wait
755@item wid     Wait object ID
756@item wupcnt  Number of queued wakeup requests
757@item suscnt  Number of nested SUSPEND requests
758@item tskatr  Task attributes
759@item task    Task starting address
760@item itskpri Initial task priority
761@item stksz   Stack size
762@end itemize
763
764
765
766
767
Note: See TracBrowser for help on using the repository browser.