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