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

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

Added copyright.

  • Property mode set to 100644
File size: 26.4 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1999.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  This is the chapter from the RTEMS ITRON User's Guide that
7@c  documents the services provided by the eventflags
8@c  manager.
9@c
10@c  $Id$
11@c
12
13@chapter Eventflags Manager
14
15@section Introduction
16
17The eventflag manager provides a high performance method of intertask communication and synchronization. The directives provided by the eventflag manager are:
18
19The 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
36An eventflag is used by a task (or ISR) to inform another task of the
37occurrence of a significant situation. One word bit-field is associated with each eventflags. The application developer should remember the
38following key characteristics of event operations when utilizing the event
39manager:
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
50A pending event is an event that has been set. An
51event condition is used to specify the events which the task desires to
52receive and the algorithm which will be used to determine when the request
53is satisfied. An event condition is satisfied based upon one of two
54algorithms which are selected by the user. The @code{TWF_ORW} algorithm
55states that an event condition is satisfied when at least a single
56requested event is posted. The @code{TWF_ANDW} algorithm states that an
57event condition is satisfied when every requested event is posted.
58
59An eventflags or condition is built by a bitwise OR of the desired events.
60If an event is not explicitly specified in the set or condition, then it
61is not present. Events are specifically designed to be mutually exclusive,
62therefore bitwise OR and addition operations are equivalent as long as
63each event appears exactly once in the event set list.
64
65@subsection T_CFLG Structure
66
67The T_CFLG structire is used to define the characteristics of an eventflag
68and passed as an argument to the @code{cre_flg} service. The structure is
69defined as follows:
70
71@example
72
73/*
74 * Create Eventflags (cre_flg) Structure
75 */
76
77typedef 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
103where the meaning of each field is:
104
105@table @b
106
107@item exinf
108
109may be used freely by the user for including extended information about
110the 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
112if the user wishes to change the contents of this information, the usr
113should 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
115implementation does not use this field.
116
117@item flgatr
118
119is the attributes for this eventflag. The lower bits of flgatr represent
120system attributes, while the upper bits represent implementation-dependent
121attributes.
122
123@item iflgptn
124
125is 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
132The T_RFLG structire is used to define the characteristics of an eventflag
133and passed as an argument to the @code{ref_flg} service. The structure is
134defined as follows:
135
136@example
137/* Reference Eventflags (ref_flg) Structure */
138typedef 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
150see @code{T_CFLG}.
151
152@item wtsk
153
154indicates whether or not there is a task waiting for the eventflag in
155question.  If there is no waiting task, @code{wtsk} is returned as FALSE = 0. 
156If there is a waiting task, @code{wtsk} is returned as a value other than 0.
157
158@item flgptn
159
160is the eventflag pattern.
161
162@end table
163
164@section Operations
165
166@section System Calls
167
168This section details the eventflags manager's services. A subsection is
169dedicated to each of this manager's services and describes the calling
170sequence, 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
184ER 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
199allocated)
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
204used)
205
206@code{E_OBJ} - Invalid object state (an eventflag of the same ID already
207exists)
208
209@code{E_OACV} - Object access violation (A flgid less than -4 was
210specified 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
215target node is specified.
216
217@code{EN_CTXID} - Specified an object on another node when the system call
218was issued from a task in dispatch disabled state or from a
219task-independent portion
220
221@code{EN_PAR}- A value outside the range supported by the target node
222and/or transmission packet format was specified as a parameter (a value
223outside supported range was specified for exinf, flgatr and/or iflgptn)
224
225@subheading DESCRIPTION:
226
227This system call creates the eventflag specified by @code{flgid}. 
228Specifically, a control block for the eventflag to be created is allocated
229and the associated flag pattern is initialized using @code{iflgptn}.  A
230single eventflag handles one word's worth of bits of the processor in
231question as a group.  All operations are done in single word units.
232
233User eventflags have positive ID numbers, while system eventflags have
234negative ID numbers.  User tasks (tasks having positive task IDs) cannot
235access system eventflags. An @code{E_OACV} error will result if a user
236task issues a system call on a system eventflag, but error detection is
237implementation dependent.
238
239Eventflags 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
243The 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
248Multiprocessing is not supported. Thus none of the "@code{EN_}" status
249codes will be returned.
250
251All memory is preallocated for @code{RTEMS ITRON} objects. Thus, no
252dynamic 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
266ER 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
282does not exist)
283
284@code{E_OACV} - Object access violation (A flgid less than -4 was
285specified from a user task.  This is implementation dependent.)
286
287@code{EN_OBJNO} - An object number which could not be accessed on the
288target node is specified.
289
290@code{EN_CTXID} - Specified an object on another node when the system call
291was issued from a task in dispatch disabled state or from a
292task-independent portion
293
294@subheading DESCRIPTION:
295
296This system call deletes the eventflag specified by @code{flgid}.
297
298Issuing this system call causes memory used for the control block of the
299associated eventflag to be released.  After this system call is invoked,
300another eventflag having the same ID number can be created.
301
302This system call will complete normally even if there are tasks waiting
303for the eventflag.  In that case, an @code{E_DLT} error will be returned
304to each waiting task.
305
306@subheading NOTES:
307
308Multiprocessing is not supported. Thus none of the "@code{EN_}" status
309codes will be returned.
310
311When an eventflag being waited for by more than one tasks is deleted, the
312order of tasks on the ready queue after the WAIT state is cleared is
313implementation 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
326ER 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
343does not exist)
344
345@code{E_OACV} - Object access violation (A flgid less than -4 was
346specified from a user task. This is implementation dependent.)
347
348@code{EN_OBJNO} - An object number which could not be accessed on the
349target node is specified.
350
351@code{EN_CTXID} - Specified an object on another node when the system call
352was issued from a task in dispatch disabled state or from a
353task-independent portion
354
355@code{EN_PAR} - A value outside the range supported by the target node
356and/or transmission packet format was specified as a parameter (a value
357outside supported range was specified for setptn or clrptn)
358
359@subheading DESCRIPTION:
360
361The @code{set_flg} system call sets the bits specified by @code{setptn} of the
362one word eventflag specified by @code{flgid}.  In other words, a logical
363sum is taken for the values of the eventflag specified by @code{flgid} with the
364value of @code{setptn}.
365
366If the eventflag value is changed by @code{set_flg} and the new eventflag
367value satisfies the condition to release the WAIT state of the task which
368issued @code{wai_flg} on the eventflag, the WAIT state of that task will
369be released and the task will be put into RUN or READY state (or SUSPEND
370state if the task was in WAIT-SUSPEND).
371
372Nothing will happen to the target eventflag if all bits of @code{setptn}
373are specified as 0 with @code{set_flg}. No error will result in either
374case.
375
376Multiple 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
378for 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.
380In this case, the order of tasks on the ready queue after the WAIT state
381is cleared is preserved for tasks having the same priority.
382
383@subheading NOTES:
384
385Multiprocessing is not supported. Thus none of the "@code{EN_}" status
386codes 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
399ER 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
417does not exist)
418
419@code{E_OACV} - Object access violation (A flgid less than -4 was
420specified from a user task. This is implementation dependent.)
421
422@code{EN_OBJNO} - An object number which could not be accessed on the
423target node is specified.
424
425@code{EN_CTXID} - Specified an object on another node when the system call
426was issued from a task in dispatch disabled state or from a
427task-independent portion
428
429@code{EN_PAR} - A value outside the range supported by the target node
430and/or transmission packet format was specified as a parameter (a value
431outside supported range was specified for setptn or clrptn)
432
433@subheading DESCRIPTION:
434
435The @code{clr_flg} system call clears the bits of the one word eventflag
436based on the corresponding zero bits of @code{clrptn}.  In other words, a
437logical product is taken for the values of the eventflag specified by
438@code{flgid} with the value of @code{clrptn}.
439
440Issuing @code{clr_flg} never results in wait conditions being released on
441a task waiting for the specified eventflag.  In other words, dispatching
442never occurs with @code{clr_flg}.
443
444Nothing will happen to the target eventflag if all bits of @code{clrptn}
445are specified as 1 with @code{clr_flg}. No error will result.
446
447@subheading NOTES:
448
449Multiprocessing is not supported. Thus none of the "@code{EN_}" status
450codes 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
463ER 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
483does not exist)
484
485@code{E_OACV} - Object access violation (A flgid less than -4 was
486specified from a user task.  This is implementation dependent.)
487
488@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2
489or less)
490
491@code{E_OBJ} - Invalid object state (multiple tasks waiting for an
492eventflag with the TA_WSGL attribute)
493
494@code{E_DLT} - The object being waited for was deleted (the specified
495eventflag was deleted while waiting)
496
497@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
498while 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
503task in dispatch disabled state)
504
505@code{EN_OBJNO} - An object number which could not be accessed on the
506target node is specified.
507
508@code{EN_PAR} - A value outside the range supported by the target node
509and/or transmission packet format was specified as a parameter (a value
510outside supported range was specified for waiptn and tmout)
511
512@code{EN_RPAR} - A value outside the range supported by the requesting
513node and/or transmission packet format was specified as a parameter (a
514value exceeding the range for the requesting node was specified for
515flgptn)
516
517@subheading DESCRIPTION:
518
519The @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
523If the eventflag specified by @code{flgid} already satisfies the wait
524release conditions given by @code{wfmode}, the issuing task will continue
525execution 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
531If @code{TWF_ORW} is specified, the issuing task will wait for any of the
532bits 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
534will wait for all of the bits specified by @code{waiptn} to be set for the
535eventflag given by @code{flgid} (AND wait).
536
537If the @code{TWF_CLR} specification is not present, the eventflag value
538will remain unchanged even after the wait conditions have been satisfied
539and the task has been released from the WAIT state.  If @code{TWF_CLR} is
540specified, all bits of the eventflag will be cleared to 0 once the wait
541conditions of the waiting task have been satisfied.
542
543The return parameter @code{flgptn} returns the value of the eventflag after the
544wait 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
546is returned.  The value returned by @code{flgptn} fulfills the wait
547release conditions of this system call.
548
549An @code{E_PAR} parameter error will result if @code{waiptn} is 0.
550
551A task can not execute any of @code{wai_flg, twai_flg} or @code{pol_flg}
552on an eventflag having the @code{TA_WSGL} attribute if another task is
553already waiting for that eventflag.  An @code{E_OBJ} error will be
554returned to a task which executes @code{wai_flg} at a later time
555regardless 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
557releasing wait state be satisfied).  An @code{E_OBJ} error will be
558returned even to tasks which just execute @code{pol_flg}, again regardless
559as to whether or not wait release conditions for that task were satisfied.
560
561On the other hand, multiple tasks can wait at the same time for the same
562eventflag if that eventflag has the @code{TA_WMUL} attribute.  This means
563that event flags can make queues for tasks to wait on.  When such
564eventflags are used, a single @code{set_flg} call may release multiple
565waiting tasks.
566
567The following processing takes place if a queue for allowing multiple
568tasks to wait has been created for an eventflag with the @code{TA_WMUL}
569attribute.
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
575always be released from waiting.)
576
577@item If a task specifying that the eventflag be cleared is on the queue,
578the flag is cleared when that task is released from waiting.
579
580@item Since any tasks behind a task which clears the eventflag (by
581specifying @code{TWF_CLR}) will check the eventflag after it is cleared,
582they will not be released from waiting.
583
584@end itemize
585
586If multiple tasks having the same priority are released from waiting
587simultaneously due to @code{set_flg}, the order of tasks on the ready
588queue after release will be the same as their original order on the
589eventflag queue.
590
591@subheading NOTES:
592 
593Multiprocessing is not supported. Thus none of the "@code{EN_}" status
594codes 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
608ER 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
628does not exist)
629
630@code{E_OACV} - Object access violation (A flgid less than -4 was
631specified from a user task.  This is implementation dependent.)
632
633@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2
634or less)
635
636@code{E_OBJ} - Invalid object state (multiple tasks waiting for an
637eventflag with the TA_WSGL attribute)
638
639@code{E_DLT} - The object being waited for was deleted (the specified
640eventflag was deleted while waiting)
641
642@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
643while 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
648task in dispatch disabled state)
649
650@code{EN_OBJNO} - An object number which could not be accessed on the
651target node is specified.
652
653@code{EN_PAR} - A value outside the range supported by the target node
654and/or transmission packet format was specified as a parameter (a value
655outside supported range was specified for waiptn and tmout)
656
657@code{EN_RPAR} - A value outside the range supported by the requesting
658node and/or transmission packet format was specified as a parameter (a
659value exceeding the range for the requesting node was specified for
660flgptn)
661
662@subheading DESCRIPTION:
663
664The @code{pol_flg} system call has the same function as @code{wai_flg}
665except for the waiting feature. @code{pol_flg} polls whether or not the
666task should wait if @code{wai_flg} is executed. The meanings of
667parameters to @code{pol_flg} are the same as for @code{wai_flg}.  The
668specific operations by @code{pol_flg} are as follows.
669
670@itemize @bullet
671
672@item If the target eventflag already satisfies the conditions for
673releasing wait given by @code{wfmode}, processing is the same as
674@code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified
675and the system call completes normally.
676
677@item If the target eventflag does not yet satisfy the conditions for
678releasing wait given by @code{wfmode}, an @code{E_TMOUT} error is returned to
679indicate polling failed and the system call finishes. Unlike
680@code{wai_flg}, the issuing task does not wait in this case. The eventflag
681is not cleared in this case even if @code{TWF_CLR} has been specified.
682
683@end itemize
684
685@subheading NOTES:
686 
687Multiprocessing is not supported. Thus none of the "@code{EN_}" status
688codes 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
702ER 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
723does not exist)
724
725@code{E_OACV} - Object access violation (A flgid less than -4 was
726specified from a user task.  This is implementation dependent.)
727
728@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2
729or less)
730
731@code{E_OBJ} - Invalid object state (multiple tasks waiting for an
732eventflag with the TA_WSGL attribute)
733
734@code{E_DLT} - The object being waited for was deleted (the specified
735eventflag was deleted while waiting)
736
737@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
738while 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
743task in dispatch disabled state)
744
745@code{EN_OBJNO} - An object number which could not be accessed on the
746target node is specified.
747
748@code{EN_PAR} - A value outside the range supported by the target node
749and/or transmission packet format was specified as a parameter (a value
750outside supported range was specified for waiptn and tmout)
751
752@code{EN_RPAR} - A value outside the range supported by the requesting
753node and/or transmission packet format was specified as a parameter (a
754value exceeding the range for the requesting node was specified for
755flgptn)
756
757@subheading DESCRIPTION:
758
759The @code{twai_flg} system call has the same function as @code{wai_flg}
760with an additional timeout feature.  A maximum wait time (timeout value)
761can be specified using the parameter @code{tmout}. When a timeout is specified,
762a timeout error, @code{E_TMOUT}, will result and the system call will
763finish if the period specified by @code{tmout} elapses without conditions for
764releasing wait being satisfied.
765
766Specifying @code{TMO_POL = 0} to @code{twai_flg} for @code{tmout} indicates that
767a 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
770exactly the same processing as @code{wai_flg}.
771
772@subheading NOTES:
773 
774Multiprocessing is not supported. Thus none of the "@code{EN_}" status
775codes will be returned.
776
777
778@code{Pol_flg} and @code{wai_flg} represent the same processing as
779specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to
780@code{twai_flg} for tmout.  As such, only @code{twai_flg} is implemented
781in the kernel; @code{pol_flg} and @code{wai_flg} should be implemented as macros
782which 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
795ER 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
812does not exist)
813
814@code{E_OACV} - Object access violation (A flgid less than -4 was
815specified from a user task.  This is implementation dependent.)
816
817@code{E_PAR} - Parameter error (the packet address for the return
818parameters could not be used)
819
820@code{EN_OBJNO} - An object number which could not be accessed on the
821target node is specified.
822
823@code{EN_CTXID} - Specified an object on another node when the system call
824was issued from a task in dispatch disabled state or from a
825task-independent portion
826
827@code{EN_RPAR} - A value outside the range supported by the requesting
828node and/or transmission packet format was returned as a parameter (a
829value outside supported range was specified for exinf, wtsk and/or flgptn)
830
831@subheading DESCRIPTION:
832
833This system call refers to the state of the eventflag specified by
834@code{flgid}, and returns its current flag pattern (@code{flgptn}),
835waiting task information (@code{wtsk}), and its extended information
836(@code{exinf}).
837
838Depending 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
840tasks waiting for the eventflag (only when attribute is @code{TA_WMUL}),
841the ID of the task at the head of the queue is returned.
842
843An @code{E_NOEXS} error will result if the eventflag specified to
844@code{ref_flg} does not exist.
845
846@subheading NOTES:
847
848Multiprocessing is not supported. Thus none of the "@code{EN_}" status
849codes will be returned.
850
851Although both @code{ref_flg} and @code{pol_flg} can be used to find an
852eventflag's pattern (@code{flgptn}) without causing the issuing task to
853wait, @code{ref_flg} simply reads the eventflag's pattern (@code{flgptn})
854while @code{pol_flg} functions is identical to @code{wai_flg} when wait
855release conditions are satisfied (it clears the eventflag if
856@code{TWF_CLR} is specified).
857
858Depending on the implementation, additional information besides
859@code{wtsk} and @code{flgptn} (such as eventflag attributes,
860@code{flgatr}) may also be referred.
Note: See TracBrowser for help on using the repository browser.