source: rtems/doc/itron3.0/tasksync.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: 18.4 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-dependent synchronization
8@c  manager.
9@c
10@c  $Id$
11@c
12
13@chapter Task-Dependent Synchronization Manager
14
15@section Introduction
16
17The task-dependent synchronization manager is designed to utilize those synchronization
18functions already supported by tasks.  This includes functions that suspend tasks for a while and associated functions that release SUSPEND state, and synchronization functions which make tasks wait and wake them up.
19
20The services provided by the task-dependent synchronization manager are:
21
22@itemize @bullet
23@item @code{sus_tsk} - Suspend Other Task
24@item @code{rsm_tsk} - Resume Suspended Task
25@item @code{frsm_tsk} - Forcibly Resume Suspended Task
26@item @code{slp_tsk} - Sleep Task
27@item @code{tslp_tsk} - Sleep Task with Timeout
28@item @code{wup_tsk} - Wakeup Other Task
29@item @code{can_wup} - Cancel Wakeup Request
30@end itemize
31
32@section Operations
33@subsection Suspend Other Task
34This call stops the execution of a task by putting it into a SUSPEND state.  This call is not able to specify itself, since this would end the flow of execution altogether.  If the task is already in a WAIT state, then SUSPEND is added to become WAIT-SUSPEND.  These modes are turned on and off separately, without affecting one another.  Furthermore, SUSPEND states can be nested, and tasks in a SUSPEND state are allocated resources as normal.
35
36@subsection Resume Suspended Task
37This operation restarts the execution of a task that was previously stopped by the SUSPEND OTHER TASK call.  Obviously, a task cannot specify itself using this call.  Since SUSPEND states can be nested, one call to RESUME releases only one SUSPEND.  Thus, it takes as many RESUMES as SUSPENDS to return the task to execution.
38
39@subsection Forcibly Resume Suspended Task
40This call has the same functionality as the previously mentioned Resume Suspended Task with one exception.  This call releases all nested SUSPENDS at once, which guarantees the task will return to execution.
41
42@subsection Sleep Task
43The Sleep Task operation causes the specified task to sleep until a Wakeup Task function is called.  This puts the task in a WAIT state.  WAIT states can not be nested, but can be combined with SUSPEND states as mentioned earlier. 
44
45@subsection Sleep Task with Timeout
46This function is identical to the Sleep Task function with an added timeout attribute.  If the timeout mark is reached before a Wakeup call is recieved, an error is generated.
47
48@subsection Wakeup Other Task
49The Wakeup Other Task call is used to release the WAIT state of a task.  These calls can be previously queued using the wupcnt value so that when the matching Sleep Task is executed, there will be no delay.
50
51@subsection Cancel Wakeup Request
52This function call resets the value of wupcnt to zero, thereby canceling all associated wakeup requests.  A call to self is acceptable for this operation, and may even be useful for monitoring certain situations.
53
54@section System Calls
55
56This section details the task-dependent synchronization manager's services. A subsection is dedicated to each of this manager's services and describes the calling sequence, related constants, usage, and status codes.
57
58
59@c
60@c  sus_tsk
61@c
62
63@page
64@subsection sus_tsk - Suspend Other Task
65
66@subheading CALLING SEQUENCE:
67
68@ifset is-C
69@example
70ER sus_tsk(
71  ID tskid
72);
73@end example
74@end ifset
75
76@ifset is-Ada
77@end ifset
78
79@subheading STATUS CODES:
80
81@code{E_OK} - Normal Completion
82
83@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
84
85@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
86
87@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
88
89@code{E_OBJ} - Invalid object state (the specified task is in DORMANT state or the issuing task specified itself)
90
91@code{E_QOVR} - Queuing or nesting overflow (the number of nesting levels given by suscnt went over the maximum allowed)
92
93@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
94
95@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
96
97@subheading DESCRIPTION:
98This system call suspends the execution of the task specified by tskid by putting it into SUSPEND state.
99
100SUSPEND state is released by issuing the rsm_tsk or frsm_tsk system call. If 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.
101
102Since SUSPEND state indicates the suspension of execution by a system call issued from another task, a task may not specify itself to this system call. An E_OBJ error will result if a task specifies itself.
103
104If more than one sus_tsk call is issued to a task, that task will be put in multiple SUSPEND states.  This is called suspend request nesting.  When this is done, rsm_tsk must be issued the same number of times which sus_tsk was issued (suscnt) in order to return the task to its original state before the suspension.  This means it is possible to nest the pairs of sus_tsk and rsm_tsk.
105
106The maximum number of times suspend requests may be nested, and even whether or not suspend request nesting (the ability to issue sus_tsk on the same task more than once) is even allowed, is implementation dependent.  Suspend request nesting is considered an extended function [level X] for which compatibility and connectivity are not guaranteed.
107
108An E_QOVR error will result if sus_tsk is issued more than once on the same task on a system which does not support suspend request nesting or if it is issued more than the maximum number of times allowed.
109
110@subheading NOTES:
111A task which is suspended in addition to waiting for resources (such as waiting for a semaphore) can be allocated resources (such as semaphore counts) based on the same conditions as tasks which are not suspended.  Even when suspended, the allocation of resources is not delayed in any way.  Conditions concerning resource allocation and release of the wait state remain unchanged. In other words, SUSPEND state is completely independent of other processing and task states.  If it is desirable to delay the allocation of resources to a task which is suspended, the user should use chg_pri in conjunction with sus_tsk and rsm_tsk.
112
113@c
114@c  rsm_tsk
115@c
116
117@page
118@subsection rsm_tsk - Resume Suspended Task
119
120@subheading CALLING SEQUENCE:
121
122@ifset is-C
123@example
124ER rsm_tsk(
125  ID tskid
126);
127@end example
128@end ifset
129
130@ifset is-Ada
131@end ifset
132
133@subheading STATUS CODES:
134
135@code{E_OK} - Normal Completion
136
137@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
138
139@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
140
141@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
142
143@code{E_OBJ} - Invalid object state (the target task is not in SUSPEND state (including when it is DORMANT or when the issuing task specifies itself))
144
145@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
146
147@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
148
149@subheading DESCRIPTION:
150This system call releases SUSPEND state of the task specified by tskid.  Specifically, it causes 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.
151If 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.
152
153A task cannot specify itself to this system call.  An E_OBJ error will result if a task specifies itself.
154
155Rsm_tsk only releases one suspend request from the suspend request nest (suscnt).  Accordingly, if more than one sus_tsk has been issued on the task in question (suscnt >= 2), that task will remain suspended even after the execution of rsm_tsk is completed.
156
157@subheading NOTES:
158It is implementation dependent which location in the ready queue a task returns to after the task which has been suspended from RUN or READY state is resumed by rsm_tsk.
159
160@c
161@c  frsm_tsk
162@c
163
164@page
165@subsection frsm_tsk - Forcibly Resume Suspended Task
166
167@subheading CALLING SEQUENCE:
168
169@ifset is-C
170@example
171ER ercd =frsm_tsk(
172  ID tskid
173);
174@end example
175@end ifset
176
177@ifset is-Ada
178@end ifset
179
180@subheading STATUS CODES:
181
182@code{E_OK} - Normal Completion
183
184@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
185
186@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
187
188@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
189
190@code{E_OBJ} - Invalid object state (the target task is not in SUSPEND state (including when it is DORMANT or when the issuing task specifies itself))
191
192@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
193
194@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
195
196@subheading DESCRIPTION:
197This system call releases SUSPEND state of the task specified by tskid.  Specifically, it causes 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.  If 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.
198
199A task cannot specify itself to this system call.  An E_OBJ error will result if a task specifies itself.
200
201Frsm_tsk will clear all suspend requests (suscnt = 0) even if more than one sus_tsk has been issued (suscnt >= 2) on the same task.  In other words, SUSPEND state is guaranteed to be released, and execution will resume unless the task in question had been in combined WAIT-SUSPEND state.
202
203@subheading NOTES:
204It is implementation dependent which location in the ready queue a task returns to after the task which has been suspended from RUN or READY state is resumed by frsm_tsk.
205
206
207@c
208@c  slp_tsk
209@c
210
211@page
212@subsection slp_tsk - Sleep Task Sleep Task with Timeout
213
214@subheading CALLING SEQUENCE:
215
216@ifset is-C
217@example
218ER slp_tsk( void );
219@end example
220@end ifset
221
222@ifset is-Ada
223@end ifset
224
225@subheading STATUS CODES:
226
227@code{E_OK} - Normal Completion
228
229@code{E_PAR} - Parameter error (a timeout value -2 or less was specified)
230
231@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting) 
232
233@code{E_TMOUT} - Polling failure or timeout exceeded
234
235@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
236
237@subheading DESCRIPTION:
238
239This system call puts the issuing task (which was in RUN state) into WAIT state, causing the issuing task to sleep until wup_tsk is invoked.
240
241@subheading NOTES:
242Since the slp_tsk system call causes the issuing task to enter WAIT state, slp_tsk calls may not be nested.  It is possible, however, for another task to execute a sus_tsk on a task which has put itself in WAIT state using slp_tsk.  If this happens, the task will enter the combined WAIT-SUSPEND state.
243
244No polling function for slp_tsk is provided.  A similar function can be implemented if necessary using can_wup.
245
246@c
247@c  tslp_tsk
248@c
249
250@page
251@subsection tslp_tsk - Sleep Task with Timeout
252
253@subheading CALLING SEQUENCE:
254
255@ifset is-C
256@example
257ER ercd =tslp_tsk(
258  TMO tmout
259);
260@end example
261@end ifset
262
263@ifset is-Ada
264@end ifset
265
266@subheading STATUS CODES:
267
268@code{E_OK} - Normal Completion
269
270@code{E_PAR} - Parameter error (a timeout value -2 or less was specified)
271
272@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting) 
273
274@code{E_TMOUT} - Polling failure or timeout exceeded
275
276@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
277
278@subheading DESCRIPTION:
279The tslp_tsk system call is the same as slp_tsk but with an additional timeout feature.  If a wup_tsk is issued before the period of time specified by tmout elapses, tslp_tsk will complete normally.  An E_TMOUT error will result if no wup_tsk is issued before the time specified by tmout expires.  Specifying tmout = TMO_FEVR = -1 can be used to set the timeout period to forever (no timeout).  In this case, tslp_tsk will function exactly the same as slp_tsk causing the issuing task to wait forever for wup_tsk to be issued.
280
281@subheading NOTES:
282Since the tslp_tsk system call causes the issuing task to enter WAIT state, tslp_tsk calls may not be nested.  It is possible, however, for another task to execute a sus_tsk on a task which has put itself in WAIT state using tslp_tsk.  If this happens, the task will enter the combined WAIT-SUSPEND state.
283
284If you simply wish to delay a task (make it wait for a while), use dly_tsk rather than tslp_tsk.
285
286@c
287@c  wup_tsk
288@c
289
290@page
291@subsection wup_tsk - Wakeup Other Task
292
293@subheading CALLING SEQUENCE:
294
295@ifset is-C
296@example
297ER wup_tsk(
298  ID tskid
299);
300@end example
301@end ifset
302
303@ifset is-Ada
304@end ifset
305
306@subheading STATUS CODES:
307
308@code{E_OK} - Normal Completion
309
310@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
311
312@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
313
314@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
315
316@code{E_OBJ} - Invalid object state (the specified task is in DORMANT state or the issuing task specified itself)
317
318@code{E_QOVR} - Queuing or nesting overflow (wakeup request queuing count will exceed the maximum value allowed for wupcnt)
319
320@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
321
322@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
323
324@subheading DESCRIPTION:
325This system call releases the WAIT state of the task specified by tskid caused by the execution of slp_tsk or tslp_tsk.
326
327A task cannot specify itself in this system call.  An E_OBJ error will result if a task specifies itself.
328
329If the specified task is not in the WAIT state caused by a slp_tsk or tslp_tsk, the wakeup request based on the wup_tsk call will be queued. In other words, a record will be kept that a wup_tsk has been issued for the specified task and no WAIT state will result even if slp_tsk or tslp_tsk is executed by the task later.  This is called queuing for wakeup request.
330
331@subheading NOTES:
332Wakeup requests are queued as follows.  A wakeup request queuing count (wupcnt) is kept in the TCB for each task.  Initially (when sta_tsk is executed) the value of wupcnt is 0.  Executing wup_tsk on a task which is not waiting for a wakeup increments the wakeup request queuing count by one for the specified task.  If slp_tsk or tslp_tsk is executed on that task, its wakeup request queuing count will be decremented by one.  If the task with wakeup request queuing count = 0 executes slp_tsk or tslp_tsk, that task will be put in WAIT state rather than decrementing the wakeup request queuing count.
333
334It is always possible to queue at least one wup_tsk (wupcnt = 1); the maximum allowable number for the wakeup request queuing count (wupcnt) is implementation dependent, and may be any number higher than or equal to one. In other words, while the first wup_tsk issued to a task which is not waiting for a wakeup will not result in an error, it is implementation dependent whether or not any further wup_tsk calls on the same task will result in an error.  The ability to queue more than one wakeup request is considered an extended function [level X] for which compatibility and connectivity are not guaranteed.
335
336An E_QOVR error will result if wup_tsk is issued more than the maximum value allowed for the wakeup request queuing count (wupcnt).
337
338
339@c
340@c  can_wup
341@c
342
343@page
344@subsection can_wup - Cancel Wakeup Request
345
346@subheading CALLING SEQUENCE:
347
348@ifset is-C
349@example
350ER can_wup(
351  INT *p_wupcnt,
352  ID tskid
353);
354@end example
355@end ifset
356
357@ifset is-Ada
358@end ifset
359
360@subheading STATUS CODES:
361
362@code{E_OK} - Normal Completion
363
364@code{E_ID} - Invalid ID Number (tskid was invalid or could not be used)
365
366@code{E_NOEXS} - Object does not exist (the task specified by tskid does not exist)
367
368@code{E_OACV} - Object access violation (A tskid less than -4 was specified from a user task.  This is implementation dependent.)
369
370@code{E_OBJ} - Invalid object state (the target task is in DORMANT state)
371
372@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
373
374@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
375
376@code{EN_RPAR} - A value outside the range supported by the issuing node and/or transmission packet format was returned as a return parameter (a value outside supported range was returned for wupcnt)
377
378@subheading DESCRIPTION:
379This system call returns the wakeup request queuing count (wupcnt) for the task specified by tskid while canceling all associated wakeup requests. Specifically, it resets the wakeup request queuing count (wupcnt) to 0.
380
381A 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.
382
383@subheading NOTES:
384An EN_RPAR error will result if the number of bits used on the target node is larger than that used on the requesting node, and if a value not supported by the requesting node is returned for wupcnt.
385
386This system call can be used to determine whether or not processing has ended within a certain period when a task should periodically waken up by wup_tsk and do some processing.  In other words, if a task monitoring the progress of its processing issues can_wup before issuing a slp_tsk after finishing processing associated with a previous wakeup request, and if wupcnt, one of can_wup's return parameters, is equal to or greater than one, it indicates that the processing for the previous wakeup request does not complete within a required time.  This allows the monitoring task to take actions against processing delays.
387
388
Note: See TracBrowser for help on using the repository browser.