source: rtems/doc/itron3.0/eventflags.t @ 1baa059

4.104.114.84.95
Last change on this file since 1baa059 was 1baa059, checked in by Joel Sherrill <joel.sherrill@…>, on 11/09/99 at 16:40:44

Converted from DOS to UNIX filemode.

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