source: rtems/doc/itron3.0/eventflags.t @ a5f5acad

4.104.114.84.95
Last change on this file since a5f5acad was a5f5acad, checked in by Joel Sherrill <joel.sherrill@…>, on 11/10/99 at 13:38:34

Updated to include more documentation from CS595.

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