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 eventflags |
---|
8 | @c manager. |
---|
9 | @c |
---|
10 | @c $Id$ |
---|
11 | @c |
---|
12 | |
---|
13 | @chapter Eventflags Manager |
---|
14 | |
---|
15 | @section Introduction |
---|
16 | |
---|
17 | The eventflag manager provides a high performance method of intertask communication and synchronization. The directives provided by the eventflag manager are: |
---|
18 | |
---|
19 | The services provided by the eventflags manager are: |
---|
20 | |
---|
21 | @itemize @bullet |
---|
22 | @item @code{cre_flg} - Create Eventflag |
---|
23 | @item @code{del_flg} - Delete Eventflag |
---|
24 | @item @code{set_flg} - Set Eventflag |
---|
25 | @item @code{clr_flg} - Clear Eventflag |
---|
26 | @item @code{wai_flg} - Wait on Eventflag |
---|
27 | @item @code{pol_flg} - Wait for Eventflag (Polling) |
---|
28 | @item @code{twai_flg} - Wait on Eventflag with Timeout |
---|
29 | @item @code{ref_flg} - Reference Eventflag Status |
---|
30 | @end itemize |
---|
31 | |
---|
32 | @section Background |
---|
33 | |
---|
34 | @subsection Event sets |
---|
35 | |
---|
36 | An eventflag is used by a task (or ISR) to inform another task of the |
---|
37 | occurrence of a significant situation. One word bit-field is associated with each eventflags. The application developer should remember the |
---|
38 | following key characteristics of event operations when utilizing the event |
---|
39 | manager: |
---|
40 | |
---|
41 | @itemize @bullet |
---|
42 | @item Events provide a simple synchronization facility. |
---|
43 | @item Events are aimed at tasks. |
---|
44 | @item Tasks can wait on more than one event simultaneously. |
---|
45 | @item Events are independent of one another. |
---|
46 | @item Events do not hold or transport data. |
---|
47 | @item Events are not queued. In other words, if an event is sent more than once to a task before being received, the second and subsequent send operations to that same task have no effect. |
---|
48 | @end itemize |
---|
49 | |
---|
50 | A pending event is an event that has been set. An |
---|
51 | event condition is used to specify the events which the task desires to |
---|
52 | receive and the algorithm which will be used to determine when the request |
---|
53 | is satisfied. An event condition is satisfied based upon one of two |
---|
54 | algorithms which are selected by the user. The @code{TWF_ORW} algorithm |
---|
55 | states that an event condition is satisfied when at least a single |
---|
56 | requested event is posted. The @code{TWF_ANDW} algorithm states that an |
---|
57 | event condition is satisfied when every requested event is posted. |
---|
58 | |
---|
59 | An eventflags or condition is built by a bitwise OR of the desired events. |
---|
60 | If an event is not explicitly specified in the set or condition, then it |
---|
61 | is not present. Events are specifically designed to be mutually exclusive, |
---|
62 | therefore bitwise OR and addition operations are equivalent as long as |
---|
63 | each event appears exactly once in the event set list. |
---|
64 | |
---|
65 | @subsection T_CFLG Structure |
---|
66 | |
---|
67 | The T_CFLG structire is used to define the characteristics of an eventflag |
---|
68 | and passed as an argument to the @code{cre_flg} service. The structure is |
---|
69 | defined as follows: |
---|
70 | |
---|
71 | @example |
---|
72 | |
---|
73 | /* |
---|
74 | * Create Eventflags (cre_flg) Structure |
---|
75 | */ |
---|
76 | |
---|
77 | typedef struct t_cflg @{ |
---|
78 | VP exinf; /* extended information */ |
---|
79 | ATR flgatr; /* eventflag attribute */ |
---|
80 | UINT iflgptn; /* initial eventflag */ |
---|
81 | /* additional implementation dependent information may be included */ |
---|
82 | @} T_CFLG; |
---|
83 | |
---|
84 | /* |
---|
85 | * flgatr - Eventflag Attribute Values |
---|
86 | */ |
---|
87 | |
---|
88 | |
---|
89 | /* multiple tasks are not allowed to wait (Wait Single Task)*/ |
---|
90 | |
---|
91 | #define TA_WSGL 0x00 |
---|
92 | |
---|
93 | /* multiple tasks are allowed to wait (Wait Multiple Task) */ |
---|
94 | |
---|
95 | #define TA_WMUL 0x08 |
---|
96 | |
---|
97 | /* wfmode */ |
---|
98 | #define TWF_ANDW 0x00 /* AND wait */ |
---|
99 | #define TWF_ORW 0x02 /* OR wait */ |
---|
100 | #define TWF_CLR 0x01 /* clear specification */ |
---|
101 | @end example |
---|
102 | |
---|
103 | where the meaning of each field is: |
---|
104 | |
---|
105 | @table @b |
---|
106 | |
---|
107 | @item exinf |
---|
108 | |
---|
109 | may be used freely by the user for including extended information about |
---|
110 | the eventflag to be created. Information set here may be accessed by |
---|
111 | @code{ref_flg}. If a larger region is desired for including user information, or |
---|
112 | if the user wishes to change the contents of this information, the usr |
---|
113 | should allocate memory area and set the address of this memory packet to |
---|
114 | @code{exinf}. The OS does not take care of the contents of @code{exinf}. This |
---|
115 | implementation does not use this field. |
---|
116 | |
---|
117 | @item flgatr |
---|
118 | |
---|
119 | is the attributes for this eventflag. The lower bits of flgatr represent |
---|
120 | system attributes, while the upper bits represent implementation-dependent |
---|
121 | attributes. |
---|
122 | |
---|
123 | @item iflgptn |
---|
124 | |
---|
125 | is the initial eventflag pattern. |
---|
126 | (CPU and/or implementation-dependent information may also be included) |
---|
127 | |
---|
128 | @end table |
---|
129 | |
---|
130 | @subsection T_RFLG Structure |
---|
131 | |
---|
132 | The T_RFLG structire is used to define the characteristics of an eventflag |
---|
133 | and passed as an argument to the @code{ref_flg} service. The structure is |
---|
134 | defined as follows: |
---|
135 | |
---|
136 | @example |
---|
137 | /* Reference Eventflags (ref_flg) Structure */ |
---|
138 | typedef struct t_rflg @{ |
---|
139 | VP exinf; /* extended information */ |
---|
140 | BOOL_ID wtsk; /* indicates whether or not there is a waiting task */ |
---|
141 | UINT flgptn; /* eventflag bit pattern */ |
---|
142 | /* additional implementation dependent information may be included */ |
---|
143 | @} T_RFLG; |
---|
144 | @end example |
---|
145 | |
---|
146 | @table @b |
---|
147 | |
---|
148 | @item exinf |
---|
149 | |
---|
150 | see @code{T_CFLG}. |
---|
151 | |
---|
152 | @item wtsk |
---|
153 | |
---|
154 | indicates whether or not there is a task waiting for the eventflag in |
---|
155 | question. If there is no waiting task, @code{wtsk} is returned as FALSE = 0. |
---|
156 | If there is a waiting task, @code{wtsk} is returned as a value other than 0. |
---|
157 | |
---|
158 | @item flgptn |
---|
159 | |
---|
160 | is the eventflag pattern. |
---|
161 | |
---|
162 | @end table |
---|
163 | |
---|
164 | @section Operations |
---|
165 | |
---|
166 | @section System Calls |
---|
167 | |
---|
168 | This section details the eventflags manager's services. A subsection is |
---|
169 | dedicated to each of this manager's services and describes the calling |
---|
170 | sequence, related constants, usage, and status codes. |
---|
171 | |
---|
172 | |
---|
173 | @c |
---|
174 | @c cre_flg |
---|
175 | @c |
---|
176 | |
---|
177 | @page |
---|
178 | @subsection cre_flg - Create Eventflag |
---|
179 | |
---|
180 | @subheading CALLING SEQUENCE: |
---|
181 | |
---|
182 | @ifset is-C |
---|
183 | @example |
---|
184 | ER cre_flg( |
---|
185 | ID flgid, |
---|
186 | T_CFLG *pk_cflg |
---|
187 | ); |
---|
188 | @end example |
---|
189 | @end ifset |
---|
190 | |
---|
191 | @ifset is-Ada |
---|
192 | @end ifset |
---|
193 | |
---|
194 | @subheading STATUS CODES: |
---|
195 | |
---|
196 | @code{E_OK} - Normal Completion |
---|
197 | |
---|
198 | @code{E_NOMEM} - Insufficient memory (Memory for control block cannot be |
---|
199 | allocated) |
---|
200 | |
---|
201 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
202 | |
---|
203 | @code{E_RSATR} - Reserved attribute (flgatr was invalid or could not be |
---|
204 | used) |
---|
205 | |
---|
206 | @code{E_OBJ} - Invalid object state (an eventflag of the same ID already |
---|
207 | exists) |
---|
208 | |
---|
209 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
210 | specified from a user task. This is implementation dependent.) |
---|
211 | |
---|
212 | @code{E_PAR} - Parameter error (pk_cflg is invalid) |
---|
213 | |
---|
214 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
215 | target node is specified. |
---|
216 | |
---|
217 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
218 | was issued from a task in dispatch disabled state or from a |
---|
219 | task-independent portion |
---|
220 | |
---|
221 | @code{EN_PAR}- A value outside the range supported by the target node |
---|
222 | and/or transmission packet format was specified as a parameter (a value |
---|
223 | outside supported range was specified for exinf, flgatr and/or iflgptn) |
---|
224 | |
---|
225 | @subheading DESCRIPTION: |
---|
226 | |
---|
227 | This system call creates the eventflag specified by @code{flgid}. |
---|
228 | Specifically, a control block for the eventflag to be created is allocated |
---|
229 | and the associated flag pattern is initialized using @code{iflgptn}. A |
---|
230 | single eventflag handles one word's worth of bits of the processor in |
---|
231 | question as a group. All operations are done in single word units. |
---|
232 | |
---|
233 | User eventflags have positive ID numbers, while system eventflags have |
---|
234 | negative ID numbers. User tasks (tasks having positive task IDs) cannot |
---|
235 | access system eventflags. An @code{E_OACV} error will result if a user |
---|
236 | task issues a system call on a system eventflag, but error detection is |
---|
237 | implementation dependent. |
---|
238 | |
---|
239 | Eventflags having ID numbers from -4 through 0 cannot be created. An |
---|
240 | @code{E_ID} error will result if a value in this range is specified for |
---|
241 | @code{flgid}. |
---|
242 | |
---|
243 | The system attribute part of @code{flgatr} may be specified as @code{TA_WSGL} |
---|
244 | (Wait Single Task) or @code{TA_WMUL} (Wait Multiple Tasks) |
---|
245 | |
---|
246 | @subheading NOTES: |
---|
247 | |
---|
248 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
249 | codes will be returned. |
---|
250 | |
---|
251 | All memory is preallocated for @code{RTEMS ITRON} objects. Thus, no |
---|
252 | dynamic memory allocation is performed by @code{cre_flg} and the |
---|
253 | @code{E_NOMEM} error can not be returned. |
---|
254 | |
---|
255 | @c |
---|
256 | @c del_flg |
---|
257 | @c |
---|
258 | |
---|
259 | @page |
---|
260 | @subsection del_flg - Delete Eventflag |
---|
261 | |
---|
262 | @subheading CALLING SEQUENCE: |
---|
263 | |
---|
264 | @ifset is-C |
---|
265 | @example |
---|
266 | ER del_flg( |
---|
267 | ID flgid |
---|
268 | ); |
---|
269 | @end example |
---|
270 | @end ifset |
---|
271 | |
---|
272 | @ifset is-Ada |
---|
273 | @end ifset |
---|
274 | |
---|
275 | @subheading STATUS CODES: |
---|
276 | |
---|
277 | @code{E_OK} - Normal Completion |
---|
278 | |
---|
279 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
280 | |
---|
281 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
282 | does not exist) |
---|
283 | |
---|
284 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
285 | specified from a user task. This is implementation dependent.) |
---|
286 | |
---|
287 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
288 | target node is specified. |
---|
289 | |
---|
290 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
291 | was issued from a task in dispatch disabled state or from a |
---|
292 | task-independent portion |
---|
293 | |
---|
294 | @subheading DESCRIPTION: |
---|
295 | |
---|
296 | This system call deletes the eventflag specified by @code{flgid}. |
---|
297 | |
---|
298 | Issuing this system call causes memory used for the control block of the |
---|
299 | associated eventflag to be released. After this system call is invoked, |
---|
300 | another eventflag having the same ID number can be created. |
---|
301 | |
---|
302 | This system call will complete normally even if there are tasks waiting |
---|
303 | for the eventflag. In that case, an @code{E_DLT} error will be returned |
---|
304 | to each waiting task. |
---|
305 | |
---|
306 | @subheading NOTES: |
---|
307 | |
---|
308 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
309 | codes will be returned. |
---|
310 | |
---|
311 | When an eventflag being waited for by more than one tasks is deleted, the |
---|
312 | order of tasks on the ready queue after the WAIT state is cleared is |
---|
313 | implementation dependent in the case of tasks having the same priority. |
---|
314 | |
---|
315 | @c |
---|
316 | @c set_flg |
---|
317 | @c |
---|
318 | |
---|
319 | @page |
---|
320 | @subsection set_flg - Set Eventflag |
---|
321 | |
---|
322 | @subheading CALLING SEQUENCE: |
---|
323 | |
---|
324 | @ifset is-C |
---|
325 | @example |
---|
326 | ER set_flg( |
---|
327 | ID flgid, |
---|
328 | UINT setptn |
---|
329 | ); |
---|
330 | @end example |
---|
331 | @end ifset |
---|
332 | |
---|
333 | @ifset is-Ada |
---|
334 | @end ifset |
---|
335 | |
---|
336 | @subheading STATUS CODES: |
---|
337 | |
---|
338 | @code{E_OK} - Normal Completion |
---|
339 | |
---|
340 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
341 | |
---|
342 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
343 | does not exist) |
---|
344 | |
---|
345 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
346 | specified from a user task. This is implementation dependent.) |
---|
347 | |
---|
348 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
349 | target node is specified. |
---|
350 | |
---|
351 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
352 | was issued from a task in dispatch disabled state or from a |
---|
353 | task-independent portion |
---|
354 | |
---|
355 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
356 | and/or transmission packet format was specified as a parameter (a value |
---|
357 | outside supported range was specified for setptn or clrptn) |
---|
358 | |
---|
359 | @subheading DESCRIPTION: |
---|
360 | |
---|
361 | The @code{set_flg} system call sets the bits specified by @code{setptn} of the |
---|
362 | one word eventflag specified by @code{flgid}. In other words, a logical |
---|
363 | sum is taken for the values of the eventflag specified by @code{flgid} with the |
---|
364 | value of @code{setptn}. |
---|
365 | |
---|
366 | If the eventflag value is changed by @code{set_flg} and the new eventflag |
---|
367 | value satisfies the condition to release the WAIT state of the task which |
---|
368 | issued @code{wai_flg} on the eventflag, the WAIT state of that task will |
---|
369 | be released and the task will be put into RUN or READY state (or SUSPEND |
---|
370 | state if the task was in WAIT-SUSPEND). |
---|
371 | |
---|
372 | Nothing will happen to the target eventflag if all bits of @code{setptn} |
---|
373 | are specified as 0 with @code{set_flg}. No error will result in either |
---|
374 | case. |
---|
375 | |
---|
376 | Multiple tasks can wait for a single eventflag if that eventflags has the |
---|
377 | @code{TA_WMUL} attribute. This means that even eventflags can make queues |
---|
378 | for tasks to wait on. When such eventflags are used, a single |
---|
379 | @code{set_flg} call may result in the release of multiple waiting tasks. |
---|
380 | In this case, the order of tasks on the ready queue after the WAIT state |
---|
381 | is cleared is preserved for tasks having the same priority. |
---|
382 | |
---|
383 | @subheading NOTES: |
---|
384 | |
---|
385 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
386 | codes will be returned. |
---|
387 | |
---|
388 | @c |
---|
389 | @c clr_flg |
---|
390 | @c |
---|
391 | |
---|
392 | @page |
---|
393 | @subsection clr_flg - Clear Eventflag |
---|
394 | |
---|
395 | @subheading CALLING SEQUENCE: |
---|
396 | |
---|
397 | @ifset is-C |
---|
398 | @example |
---|
399 | ER clr_flg( |
---|
400 | ID flgid, |
---|
401 | UINT clrptn |
---|
402 | ); |
---|
403 | @end example |
---|
404 | @end ifset |
---|
405 | |
---|
406 | @ifset is-Ada |
---|
407 | @end ifset |
---|
408 | |
---|
409 | @subheading STATUS CODES: |
---|
410 | |
---|
411 | |
---|
412 | @code{E_OK} - Normal Completion |
---|
413 | |
---|
414 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
415 | |
---|
416 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
417 | does not exist) |
---|
418 | |
---|
419 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
420 | specified from a user task. This is implementation dependent.) |
---|
421 | |
---|
422 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
423 | target node is specified. |
---|
424 | |
---|
425 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
426 | was issued from a task in dispatch disabled state or from a |
---|
427 | task-independent portion |
---|
428 | |
---|
429 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
430 | and/or transmission packet format was specified as a parameter (a value |
---|
431 | outside supported range was specified for setptn or clrptn) |
---|
432 | |
---|
433 | @subheading DESCRIPTION: |
---|
434 | |
---|
435 | The @code{clr_flg} system call clears the bits of the one word eventflag |
---|
436 | based on the corresponding zero bits of @code{clrptn}. In other words, a |
---|
437 | logical product is taken for the values of the eventflag specified by |
---|
438 | @code{flgid} with the value of @code{clrptn}. |
---|
439 | |
---|
440 | Issuing @code{clr_flg} never results in wait conditions being released on |
---|
441 | a task waiting for the specified eventflag. In other words, dispatching |
---|
442 | never occurs with @code{clr_flg}. |
---|
443 | |
---|
444 | Nothing will happen to the target eventflag if all bits of @code{clrptn} |
---|
445 | are specified as 1 with @code{clr_flg}. No error will result. |
---|
446 | |
---|
447 | @subheading NOTES: |
---|
448 | |
---|
449 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
450 | codes will be returned. |
---|
451 | |
---|
452 | @c |
---|
453 | @c wai_flg |
---|
454 | @c |
---|
455 | |
---|
456 | @page |
---|
457 | @subsection wai_flg - Wait on Eventflag |
---|
458 | |
---|
459 | @subheading CALLING SEQUENCE: |
---|
460 | |
---|
461 | @ifset is-C |
---|
462 | @example |
---|
463 | ER wai_flg( |
---|
464 | UINT *p_flgptn, |
---|
465 | ID flgid, |
---|
466 | UINT waiptn, |
---|
467 | UINT wfmode |
---|
468 | ); |
---|
469 | @end example |
---|
470 | @end ifset |
---|
471 | |
---|
472 | @ifset is-Ada |
---|
473 | @end ifset |
---|
474 | |
---|
475 | @subheading STATUS CODES: |
---|
476 | |
---|
477 | |
---|
478 | @code{E_OK} - Normal Completion |
---|
479 | |
---|
480 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
481 | |
---|
482 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
483 | does not exist) |
---|
484 | |
---|
485 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
486 | specified from a user task. This is implementation dependent.) |
---|
487 | |
---|
488 | @code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 |
---|
489 | or less) |
---|
490 | |
---|
491 | @code{E_OBJ} - Invalid object state (multiple tasks waiting for an |
---|
492 | eventflag with the TA_WSGL attribute) |
---|
493 | |
---|
494 | @code{E_DLT} - The object being waited for was deleted (the specified |
---|
495 | eventflag was deleted while waiting) |
---|
496 | |
---|
497 | @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received |
---|
498 | while waiting) |
---|
499 | |
---|
500 | @code{E_TMOUT} - Polling failure or timeout exceeded |
---|
501 | |
---|
502 | @code{E_CTX} - Context error (issued from task-independent portions or a |
---|
503 | task in dispatch disabled state) |
---|
504 | |
---|
505 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
506 | target node is specified. |
---|
507 | |
---|
508 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
509 | and/or transmission packet format was specified as a parameter (a value |
---|
510 | outside supported range was specified for waiptn and tmout) |
---|
511 | |
---|
512 | @code{EN_RPAR} - A value outside the range supported by the requesting |
---|
513 | node and/or transmission packet format was specified as a parameter (a |
---|
514 | value exceeding the range for the requesting node was specified for |
---|
515 | flgptn) |
---|
516 | |
---|
517 | @subheading DESCRIPTION: |
---|
518 | |
---|
519 | The @code{wai_flg} system call waits for the eventflag specified by |
---|
520 | @code{flgid} to be set to satisfy the wait release condition specified by |
---|
521 | @code{wfmode}. The Eventflags bit-pattern will be returned with a pointer @code{p_flgptn}. |
---|
522 | |
---|
523 | If the eventflag specified by @code{flgid} already satisfies the wait |
---|
524 | release conditions given by @code{wfmode}, the issuing task will continue |
---|
525 | execution without waiting. @code{wfmode} may be specified as follows. |
---|
526 | |
---|
527 | @example |
---|
528 | wfmode = TWF_ANDW (or TWF_ORW) | TWF_CLR(optional) |
---|
529 | @end example |
---|
530 | |
---|
531 | If @code{TWF_ORW} is specified, the issuing task will wait for any of the |
---|
532 | bits specified by @code{waiptn} to be set for the eventflag given by |
---|
533 | @code{flgid} (OR wait). If @code{TWF_ANDW} is specified, the issuing task |
---|
534 | will wait for all of the bits specified by @code{waiptn} to be set for the |
---|
535 | eventflag given by @code{flgid} (AND wait). |
---|
536 | |
---|
537 | If the @code{TWF_CLR} specification is not present, the eventflag value |
---|
538 | will remain unchanged even after the wait conditions have been satisfied |
---|
539 | and the task has been released from the WAIT state. If @code{TWF_CLR} is |
---|
540 | specified, all bits of the eventflag will be cleared to 0 once the wait |
---|
541 | conditions of the waiting task have been satisfied. |
---|
542 | |
---|
543 | The return parameter @code{flgptn} returns the value of the eventflag after the |
---|
544 | wait state of a task has been released due to this system call. If |
---|
545 | @code{TWF_CLR} was specified, the value before eventflag bits were cleared |
---|
546 | is returned. The value returned by @code{flgptn} fulfills the wait |
---|
547 | release conditions of this system call. |
---|
548 | |
---|
549 | An @code{E_PAR} parameter error will result if @code{waiptn} is 0. |
---|
550 | |
---|
551 | A task can not execute any of @code{wai_flg, twai_flg} or @code{pol_flg} |
---|
552 | on an eventflag having the @code{TA_WSGL} attribute if another task is |
---|
553 | already waiting for that eventflag. An @code{E_OBJ} error will be |
---|
554 | returned to a task which executes @code{wai_flg} at a later time |
---|
555 | regardless as to whether or not the task that executes @code{wai_flg} or |
---|
556 | @code{twai_flg} later will be placed in a WAIT state (conditions for |
---|
557 | releasing wait state be satisfied). An @code{E_OBJ} error will be |
---|
558 | returned even to tasks which just execute @code{pol_flg}, again regardless |
---|
559 | as to whether or not wait release conditions for that task were satisfied. |
---|
560 | |
---|
561 | On the other hand, multiple tasks can wait at the same time for the same |
---|
562 | eventflag if that eventflag has the @code{TA_WMUL} attribute. This means |
---|
563 | that event flags can make queues for tasks to wait on. When such |
---|
564 | eventflags are used, a single @code{set_flg} call may release multiple |
---|
565 | waiting tasks. |
---|
566 | |
---|
567 | The following processing takes place if a queue for allowing multiple |
---|
568 | tasks to wait has been created for an eventflag with the @code{TA_WMUL} |
---|
569 | attribute. |
---|
570 | |
---|
571 | @itemize @bullet |
---|
572 | |
---|
573 | @item The waiting order on the queue is FIFO. (However, depending on |
---|
574 | @code{waiptn} and @code{wfmode}, task at the head of the queue will not |
---|
575 | always be released from waiting.) |
---|
576 | |
---|
577 | @item If a task specifying that the eventflag be cleared is on the queue, |
---|
578 | the flag is cleared when that task is released from waiting. |
---|
579 | |
---|
580 | @item Since any tasks behind a task which clears the eventflag (by |
---|
581 | specifying @code{TWF_CLR}) will check the eventflag after it is cleared, |
---|
582 | they will not be released from waiting. |
---|
583 | |
---|
584 | @end itemize |
---|
585 | |
---|
586 | If multiple tasks having the same priority are released from waiting |
---|
587 | simultaneously due to @code{set_flg}, the order of tasks on the ready |
---|
588 | queue after release will be the same as their original order on the |
---|
589 | eventflag queue. |
---|
590 | |
---|
591 | @subheading NOTES: |
---|
592 | |
---|
593 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
594 | codes will be returned. |
---|
595 | |
---|
596 | |
---|
597 | @c |
---|
598 | @c pol_flg |
---|
599 | @c |
---|
600 | |
---|
601 | @page |
---|
602 | @subsection pol_flg - Wait for Eventflag (Polling) |
---|
603 | |
---|
604 | @subheading CALLING SEQUENCE: |
---|
605 | |
---|
606 | @ifset is-C |
---|
607 | @example |
---|
608 | ER pol_flg( |
---|
609 | UINT *p_flgptn, |
---|
610 | ID flgid, |
---|
611 | UINT waiptn, |
---|
612 | UINT wfmode |
---|
613 | ); |
---|
614 | @end example |
---|
615 | @end ifset |
---|
616 | |
---|
617 | @ifset is-Ada |
---|
618 | @end ifset |
---|
619 | |
---|
620 | @subheading STATUS CODES: |
---|
621 | |
---|
622 | |
---|
623 | @code{E_OK} - Normal Completion |
---|
624 | |
---|
625 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
626 | |
---|
627 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
628 | does not exist) |
---|
629 | |
---|
630 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
631 | specified from a user task. This is implementation dependent.) |
---|
632 | |
---|
633 | @code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 |
---|
634 | or less) |
---|
635 | |
---|
636 | @code{E_OBJ} - Invalid object state (multiple tasks waiting for an |
---|
637 | eventflag with the TA_WSGL attribute) |
---|
638 | |
---|
639 | @code{E_DLT} - The object being waited for was deleted (the specified |
---|
640 | eventflag was deleted while waiting) |
---|
641 | |
---|
642 | @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received |
---|
643 | while waiting) |
---|
644 | |
---|
645 | @code{E_TMOUT} - Polling failure or timeout exceeded |
---|
646 | |
---|
647 | @code{E_CTX} - Context error (issued from task-independent portions or a |
---|
648 | task in dispatch disabled state) |
---|
649 | |
---|
650 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
651 | target node is specified. |
---|
652 | |
---|
653 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
654 | and/or transmission packet format was specified as a parameter (a value |
---|
655 | outside supported range was specified for waiptn and tmout) |
---|
656 | |
---|
657 | @code{EN_RPAR} - A value outside the range supported by the requesting |
---|
658 | node and/or transmission packet format was specified as a parameter (a |
---|
659 | value exceeding the range for the requesting node was specified for |
---|
660 | flgptn) |
---|
661 | |
---|
662 | @subheading DESCRIPTION: |
---|
663 | |
---|
664 | The @code{pol_flg} system call has the same function as @code{wai_flg} |
---|
665 | except for the waiting feature. @code{pol_flg} polls whether or not the |
---|
666 | task should wait if @code{wai_flg} is executed. The meanings of |
---|
667 | parameters to @code{pol_flg} are the same as for @code{wai_flg}. The |
---|
668 | specific operations by @code{pol_flg} are as follows. |
---|
669 | |
---|
670 | @itemize @bullet |
---|
671 | |
---|
672 | @item If the target eventflag already satisfies the conditions for |
---|
673 | releasing wait given by @code{wfmode}, processing is the same as |
---|
674 | @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified |
---|
675 | and the system call completes normally. |
---|
676 | |
---|
677 | @item If the target eventflag does not yet satisfy the conditions for |
---|
678 | releasing wait given by @code{wfmode}, an @code{E_TMOUT} error is returned to |
---|
679 | indicate polling failed and the system call finishes. Unlike |
---|
680 | @code{wai_flg}, the issuing task does not wait in this case. The eventflag |
---|
681 | is not cleared in this case even if @code{TWF_CLR} has been specified. |
---|
682 | |
---|
683 | @end itemize |
---|
684 | |
---|
685 | @subheading NOTES: |
---|
686 | |
---|
687 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
688 | codes will be returned. |
---|
689 | |
---|
690 | |
---|
691 | @c |
---|
692 | @c twai_flg |
---|
693 | @c |
---|
694 | |
---|
695 | @page |
---|
696 | @subsection twai_flg - Wait on Eventflag with Timeout |
---|
697 | |
---|
698 | @subheading CALLING SEQUENCE: |
---|
699 | |
---|
700 | @ifset is-C |
---|
701 | @example |
---|
702 | ER twai_flg( |
---|
703 | UINT *p_flgptn, |
---|
704 | ID flgid, |
---|
705 | UINT waiptn, |
---|
706 | UINT wfmode, |
---|
707 | TMO tmout |
---|
708 | ); |
---|
709 | @end example |
---|
710 | @end ifset |
---|
711 | |
---|
712 | @ifset is-Ada |
---|
713 | @end ifset |
---|
714 | |
---|
715 | @subheading STATUS CODES: |
---|
716 | |
---|
717 | |
---|
718 | @code{E_OK} - Normal Completion |
---|
719 | |
---|
720 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
721 | |
---|
722 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
723 | does not exist) |
---|
724 | |
---|
725 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
726 | specified from a user task. This is implementation dependent.) |
---|
727 | |
---|
728 | @code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 |
---|
729 | or less) |
---|
730 | |
---|
731 | @code{E_OBJ} - Invalid object state (multiple tasks waiting for an |
---|
732 | eventflag with the TA_WSGL attribute) |
---|
733 | |
---|
734 | @code{E_DLT} - The object being waited for was deleted (the specified |
---|
735 | eventflag was deleted while waiting) |
---|
736 | |
---|
737 | @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received |
---|
738 | while waiting) |
---|
739 | |
---|
740 | @code{E_TMOUT} - Polling failure or timeout exceeded |
---|
741 | |
---|
742 | @code{E_CTX} - Context error (issued from task-independent portions or a |
---|
743 | task in dispatch disabled state) |
---|
744 | |
---|
745 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
746 | target node is specified. |
---|
747 | |
---|
748 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
749 | and/or transmission packet format was specified as a parameter (a value |
---|
750 | outside supported range was specified for waiptn and tmout) |
---|
751 | |
---|
752 | @code{EN_RPAR} - A value outside the range supported by the requesting |
---|
753 | node and/or transmission packet format was specified as a parameter (a |
---|
754 | value exceeding the range for the requesting node was specified for |
---|
755 | flgptn) |
---|
756 | |
---|
757 | @subheading DESCRIPTION: |
---|
758 | |
---|
759 | The @code{twai_flg} system call has the same function as @code{wai_flg} |
---|
760 | with an additional timeout feature. A maximum wait time (timeout value) |
---|
761 | can be specified using the parameter @code{tmout}. When a timeout is specified, |
---|
762 | a timeout error, @code{E_TMOUT}, will result and the system call will |
---|
763 | finish if the period specified by @code{tmout} elapses without conditions for |
---|
764 | releasing wait being satisfied. |
---|
765 | |
---|
766 | Specifying @code{TMO_POL = 0} to @code{twai_flg} for @code{tmout} indicates that |
---|
767 | a timeout value of 0 be used, resulting in exactly the same processing as |
---|
768 | @code{pol_flg}. Specifying @code{TMO_FEVR = -1} to @code{twai_flg} for |
---|
769 | @code{tmout} indicates that an infinite timeout value be used, resulting in |
---|
770 | exactly the same processing as @code{wai_flg}. |
---|
771 | |
---|
772 | @subheading NOTES: |
---|
773 | |
---|
774 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
775 | codes will be returned. |
---|
776 | |
---|
777 | |
---|
778 | @code{Pol_flg} and @code{wai_flg} represent the same processing as |
---|
779 | specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to |
---|
780 | @code{twai_flg} for tmout. As such, only @code{twai_flg} is implemented |
---|
781 | in the kernel; @code{pol_flg} and @code{wai_flg} should be implemented as macros |
---|
782 | which call @code{twai_flg}. |
---|
783 | |
---|
784 | @c |
---|
785 | @c ref_flg |
---|
786 | @c |
---|
787 | |
---|
788 | @page |
---|
789 | @subsection ref_flg - Reference Eventflag Status |
---|
790 | |
---|
791 | @subheading CALLING SEQUENCE: |
---|
792 | |
---|
793 | @ifset is-C |
---|
794 | @example |
---|
795 | ER ref_flg( |
---|
796 | T_RFLG *pk_rflg, |
---|
797 | ID flgid ); |
---|
798 | @end example |
---|
799 | @end ifset |
---|
800 | |
---|
801 | @ifset is-Ada |
---|
802 | @end ifset |
---|
803 | |
---|
804 | @subheading STATUS CODES: |
---|
805 | |
---|
806 | |
---|
807 | @code{E_OK} - Normal Completion |
---|
808 | |
---|
809 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
810 | |
---|
811 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
812 | does not exist) |
---|
813 | |
---|
814 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
815 | specified from a user task. This is implementation dependent.) |
---|
816 | |
---|
817 | @code{E_PAR} - Parameter error (the packet address for the return |
---|
818 | parameters could not be used) |
---|
819 | |
---|
820 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
821 | target node is specified. |
---|
822 | |
---|
823 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
824 | was issued from a task in dispatch disabled state or from a |
---|
825 | task-independent portion |
---|
826 | |
---|
827 | @code{EN_RPAR} - A value outside the range supported by the requesting |
---|
828 | node and/or transmission packet format was returned as a parameter (a |
---|
829 | value outside supported range was specified for exinf, wtsk and/or flgptn) |
---|
830 | |
---|
831 | @subheading DESCRIPTION: |
---|
832 | |
---|
833 | This system call refers to the state of the eventflag specified by |
---|
834 | @code{flgid}, and returns its current flag pattern (@code{flgptn}), |
---|
835 | waiting task information (@code{wtsk}), and its extended information |
---|
836 | (@code{exinf}). |
---|
837 | |
---|
838 | Depending on the implementation, @code{wtsk} may be returned as the ID |
---|
839 | (non-zero) of the task waiting for the eventflag. If there are multiple |
---|
840 | tasks waiting for the eventflag (only when attribute is @code{TA_WMUL}), |
---|
841 | the ID of the task at the head of the queue is returned. |
---|
842 | |
---|
843 | An @code{E_NOEXS} error will result if the eventflag specified to |
---|
844 | @code{ref_flg} does not exist. |
---|
845 | |
---|
846 | @subheading NOTES: |
---|
847 | |
---|
848 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
849 | codes will be returned. |
---|
850 | |
---|
851 | Although both @code{ref_flg} and @code{pol_flg} can be used to find an |
---|
852 | eventflag's pattern (@code{flgptn}) without causing the issuing task to |
---|
853 | wait, @code{ref_flg} simply reads the eventflag's pattern (@code{flgptn}) |
---|
854 | while @code{pol_flg} functions is identical to @code{wai_flg} when wait |
---|
855 | release conditions are satisfied (it clears the eventflag if |
---|
856 | @code{TWF_CLR} is specified). |
---|
857 | |
---|
858 | Depending on the implementation, additional information besides |
---|
859 | @code{wtsk} and @code{flgptn} (such as eventflag attributes, |
---|
860 | @code{flgatr}) may also be referred. |
---|