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

4.104.114.84.95
Last change on this file since 0f8a69e7 was 0f8a69e7, checked in by Joel Sherrill <joel.sherrill@…>, on Jul 8, 1999 at 3:35:38 PM

Some cleanup to make it format better. Compensated for multiple services
on a single page.

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