OpenCores
URL https://opencores.org/ocsvn/or1k_old/or1k_old/trunk

Subversion Repositories or1k_old

[/] [or1k_old/] [trunk/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-flags.html] - Blame information for rev 1782

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 1254 phoenix 
<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
2 
<!-- This material may be distributed only subject to the terms      -->
3 
<!-- and conditions set forth in the Open Publication License, v1.0  -->
4 
<!-- or later (the latest version is presently available at          -->
5 
<!-- http://www.opencontent.org/openpub/).                           -->
6 
<!-- Distribution of the work or derivative of the work in any       -->
7 
<!-- standard (paper) book form is prohibited unless prior           -->
8 
<!-- permission is obtained from the copyright holder.               -->
9 
<HTML
10 
><HEAD
11 
><TITLE
12 
>Event Flags</TITLE
13 
><meta name="MSSmartTagsPreventParsing" content="TRUE">
14 
<META
15 
NAME="GENERATOR"
16 
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
17 
"><LINK
18 
REL="HOME"
19 
TITLE="eCos Reference Manual"
20 
HREF="ecos-ref.html"><LINK
21 
REL="UP"
22 
TITLE="The eCos Kernel"
23 
HREF="kernel.html"><LINK
24 
REL="PREVIOUS"
25 
TITLE="Mail boxes"
26 
HREF="kernel-mail-boxes.html"><LINK
27 
REL="NEXT"
28 
TITLE="Spinlocks"
29 
HREF="kernel-spinlocks.html"></HEAD
30 
><BODY
31 
CLASS="REFENTRY"
32 
BGCOLOR="#FFFFFF"
33 
TEXT="#000000"
34 
LINK="#0000FF"
35 
VLINK="#840084"
36 
ALINK="#0000FF"
37 
><DIV
38 
CLASS="NAVHEADER"
39 
><TABLE
40 
SUMMARY="Header navigation table"
41 
WIDTH="100%"
42 
BORDER="0"
43 
CELLPADDING="0"
44 
CELLSPACING="0"
45 
><TR
46 
><TH
47 
COLSPAN="3"
48 
ALIGN="center"
49 
>eCos Reference Manual</TH
50 
></TR
51 
><TR
52 
><TD
53 
WIDTH="10%"
54 
ALIGN="left"
55 
VALIGN="bottom"
56 
><A
57 
HREF="kernel-mail-boxes.html"
58 
ACCESSKEY="P"
59 
>Prev</A
60 
></TD
61 
><TD
62 
WIDTH="80%"
63 
ALIGN="center"
64 
VALIGN="bottom"
65 
></TD
66 
><TD
67 
WIDTH="10%"
68 
ALIGN="right"
69 
VALIGN="bottom"
70 
><A
71 
HREF="kernel-spinlocks.html"
72 
ACCESSKEY="N"
73 
>Next</A
74 
></TD
75 
></TR
76 
></TABLE
77 
><HR
78 
ALIGN="LEFT"
79 
WIDTH="100%"></DIV
80 
><H1
81 
><A
82 
NAME="KERNEL-FLAGS">Event Flags</H1
83 
><DIV
84 
CLASS="REFNAMEDIV"
85 
><A
86 
NAME="AEN1555"
87 
></A
88 
><H2
89 
>Name</H2
90 
>cyg_flag_init, cyg_flag_destroy, cyg_flag_setbits, cyg_flag_maskbits, cyg_flag_wait, cyg_flag_timed_wait, cyg_flag_poll, cyg_flag_peek, cyg_flag_waiting&nbsp;--&nbsp;Synchronization primitive</DIV
91 
><DIV
92 
CLASS="REFSYNOPSISDIV"
93 
><A
94 
NAME="AEN1566"><H2
95 
>Synopsis</H2
96 
><DIV
97 
CLASS="FUNCSYNOPSIS"
98 
><A
99 
NAME="AEN1567"><P
100 
></P
101 
><TABLE
102 
BORDER="5"
103 
BGCOLOR="#E0E0F0"
104 
WIDTH="70%"
105 
><TR
106 
><TD
107 
><PRE
108 
CLASS="FUNCSYNOPSISINFO"
109 
>#include &lt;cyg/kernel/kapi.h&gt;
110 
        </PRE
111 
></TD
112 
></TR
113 
></TABLE
114 
><P
115 
><CODE
116 
><CODE
117 
CLASS="FUNCDEF"
118 
>void cyg_flag_init</CODE
119 
>(cyg_flag_t* flag);</CODE
120 
></P
121 
><P
122 
><CODE
123 
><CODE
124 
CLASS="FUNCDEF"
125 
>void cyg_flag_destroy</CODE
126 
>(cyg_flag_t* flag);</CODE
127 
></P
128 
><P
129 
><CODE
130 
><CODE
131 
CLASS="FUNCDEF"
132 
>void cyg_flag_setbits</CODE
133 
>(cyg_flag_t* flag, cyg_flag_value_t value);</CODE
134 
></P
135 
><P
136 
><CODE
137 
><CODE
138 
CLASS="FUNCDEF"
139 
>void cyg_flag_maskbits</CODE
140 
>(cyg_flag_t* flag, cyg_flag_value_t value);</CODE
141 
></P
142 
><P
143 
><CODE
144 
><CODE
145 
CLASS="FUNCDEF"
146 
>cyg_flag_value_t cyg_flag_wait</CODE
147 
>(cyg_flag_t* flag, cyg_flag_value_t pattern, cyg_flag_mode_t mode);</CODE
148 
></P
149 
><P
150 
><CODE
151 
><CODE
152 
CLASS="FUNCDEF"
153 
>cyg_flag_value_t cyg_flag_timed_wait</CODE
154 
>(cyg_flag_t* flag, cyg_flag_value_t pattern, cyg_flag_mode_t mode, cyg_tick_count_t abstime);</CODE
155 
></P
156 
><P
157 
><CODE
158 
><CODE
159 
CLASS="FUNCDEF"
160 
>cyg_flag_value_t cyg_flag_poll</CODE
161 
>(cyg_flag_t* flag, cyg_flag_value_t pattern, cyg_flag_mode_t mode);</CODE
162 
></P
163 
><P
164 
><CODE
165 
><CODE
166 
CLASS="FUNCDEF"
167 
>cyg_flag_value_t cyg_flag_peek</CODE
168 
>(cyg_flag_t* flag);</CODE
169 
></P
170 
><P
171 
><CODE
172 
><CODE
173 
CLASS="FUNCDEF"
174 
>cyg_bool_t cyg_flag_waiting</CODE
175 
>(cyg_flag_t* flag);</CODE
176 
></P
177 
><P
178 
></P
179 
></DIV
180 
></DIV
181 
><DIV
182 
CLASS="REFSECT1"
183 
><A
184 
NAME="KERNEL-FLAGS-DESCRIPTION"
185 
></A
186 
><H2
187 
>Description</H2
188 
><P
189 
>Event flags allow a consumer thread to wait for one of several
190 
different types of event to occur. Alternatively it is possible to
191 
wait for some combination of events. The implementation is relatively
192 
straightforward. Each event flag contains a 32-bit integer.
193 
Application code associates these bits with specific events, so for
194 
example bit 0 could indicate that an I/O operation has completed and
195 
data is available, while bit 1 could indicate that the user has
196 
pressed a start button. A producer thread or a DSR can cause one or
197 
more of the bits to be set, and a consumer thread currently waiting
198 
for these bits will be woken up.
199 
      </P
200 
><P
201 
>Unlike semaphores no attempt is made to keep track of event counts. It
202 
does not matter whether a given event occurs once or multiple times
203 
before being consumed, the corresponding bit in the event flag will
204 
change only once. However semaphores cannot easily be used to handle
205 
multiple event sources. Event flags can often be used as an
206 
alternative to condition variables, although they cannot be used for
207 
completely arbitrary conditions and they only support the equivalent
208 
of condition variable broadcasts, not signals.
209 
      </P
210 
><P
211 
>Before an event flag can be used it must be initialized by a call to
212 
<TT
213 
CLASS="FUNCTION"
214 
>cyg_flag_init</TT
215 
>. This takes a pointer to a
216 
<SPAN
217 
CLASS="STRUCTNAME"
218 
>cyg_flag_t</SPAN
219 
> data structure, which can be part of a
220 
larger structure. All 32 bits in the event flag will be set to 0,
221 
indicating that no events have yet occurred. If an event flag is no
222 
longer required it can be cleaned up with a call to
223 
<TT
224 
CLASS="FUNCTION"
225 
>cyg_flag_destroy</TT
226 
>, allowing the memory for the
227 
<TT
228 
CLASS="STRUCTFIELD"
229 
><I
230 
>cyg_flag_t</I
231 
></TT
232 
> structure to be re-used.
233 
      </P
234 
><P
235 
>A consumer thread can wait for one or more events by calling
236 
<TT
237 
CLASS="FUNCTION"
238 
>cyg_flag_wait</TT
239 
>. This takes three arguments. The
240 
first identifies a particular event flag. The second is some
241 
combination of bits, indicating which events are of interest. The
242 
final argument should be one of the following:
243 
      </P
244 
><P
245 
></P
246 
><DIV
247 
CLASS="VARIABLELIST"
248 
><DL
249 
><DT
250 
><TT
251 
CLASS="LITERAL"
252 
>CYG_FLAG_WAITMODE_AND</TT
253 
></DT
254 
><DD
255 
><P
256 
>The call to <TT
257 
CLASS="FUNCTION"
258 
>cyg_flag_wait</TT
259 
> will block until all
260 
the specified event bits are set. The event flag is not cleared when
261 
the wait succeeds, in other words all the bits remain set.
262 
          </P
263 
></DD
264 
><DT
265 
><TT
266 
CLASS="LITERAL"
267 
>CYG_FLAG_WAITMODE_OR</TT
268 
></DT
269 
><DD
270 
><P
271 
>The call will block until at least one of the specified event bits is
272 
set. The event flag is not cleared on return.
273 
          </P
274 
></DD
275 
><DT
276 
><TT
277 
CLASS="LITERAL"
278 
>CYG_FLAG_WAITMODE_AND | CYG_FLAG_WAITMODE_CLR</TT
279 
></DT
280 
><DD
281 
><P
282 
>The call will block until all the specified event bits are set, and
283 
the entire event flag is cleared when the call succeeds. Note that
284 
if this mode of operation is used then a single event flag cannot be
285 
used to store disjoint sets of events, even though enough bits might
286 
be available. Instead each disjoint set of events requires its own
287 
event flag.
288 
          </P
289 
></DD
290 
><DT
291 
><TT
292 
CLASS="LITERAL"
293 
>CYG_FLAG_WAITMODE_OR | CYG_FLAG_WAITMODE_CLR</TT
294 
></DT
295 
><DD
296 
><P
297 
>The call will block until at least one of the specified event bits is
298 
set, and the entire flag is cleared when the call succeeds.
299 
          </P
300 
></DD
301 
></DL
302 
></DIV
303 
><P
304 
>A call to <TT
305 
CLASS="FUNCTION"
306 
>cyg_flag_wait</TT
307 
> normally blocks until the
308 
required condition is satisfied. It will return the value of the event
309 
flag at the point that the operation succeeded, which may be a
310 
superset of the requested events. If
311 
<TT
312 
CLASS="FUNCTION"
313 
>cyg_thread_release</TT
314 
> is used to unblock a thread
315 
that is currently in a wait operation, the
316 
<TT
317 
CLASS="FUNCTION"
318 
>cyg_flag_wait</TT
319 
> call will instead return 0.
320 
      </P
321 
><P
322 
><TT
323 
CLASS="FUNCTION"
324 
>cyg_flag_timed_wait</TT
325 
> is a variant of
326 
<TT
327 
CLASS="FUNCTION"
328 
>cyg_flag_wait</TT
329 
> which adds a timeout: the wait
330 
operation must succeed within the specified number of ticks, or it
331 
will fail with a return value of 0. <TT
332 
CLASS="FUNCTION"
333 
>cyg_flag_poll</TT
334 
>
335 
is a non-blocking variant: if the wait operation can succeed
336 
immediately it acts like <TT
337 
CLASS="FUNCTION"
338 
>cyg_flag_wait</TT
339 
>, otherwise
340 
it returns immediately with a value of 0.
341 
      </P
342 
><P
343 
><TT
344 
CLASS="FUNCTION"
345 
>cyg_flag_setbits</TT
346 
> is called by a producer thread
347 
or from inside a DSR when an event occurs. The specified bits are or'd
348 
into the current event flag value. This may cause a waiting thread to
349 
be woken up, if its condition is now satisfied.
350 
      </P
351 
><P
352 
><TT
353 
CLASS="FUNCTION"
354 
>cyg_flag_maskbits</TT
355 
> can be used to clear one or
356 
more bits in the event flag. This can be called from a producer when a
357 
particular condition is no longer satisfied, for example when the user
358 
is no longer pressing a particular button. It can also be used by a
359 
consumer thread if <TT
360 
CLASS="LITERAL"
361 
>CYG_FLAG_WAITMODE_CLR</TT
362 
> was not
363 
used as part of the wait operation, to indicate that some but not all
364 
of the active events have been consumed. If there are multiple
365 
consumer threads performing wait operations without using
366 
<TT
367 
CLASS="FUNCTION"
368 
>CYG_FLAG_WAITMODE_CLR</TT
369 
> then typically some
370 
additional synchronization such as a mutex is needed to prevent
371 
multiple threads consuming the same event.
372 
      </P
373 
><P
374 
>Two additional functions are provided to query the current state of an
375 
event flag. <TT
376 
CLASS="FUNCTION"
377 
>cyg_flag_peek</TT
378 
> returns the current
379 
value of the event flag, and <TT
380 
CLASS="FUNCTION"
381 
>cyg_flag_waiting</TT
382 
> can
383 
be used to find out whether or not there are any threads currently
384 
blocked on the event flag. Both of these functions must be used with
385 
care because other threads may be operating on the event flag.
386 
      </P
387 
></DIV
388 
><DIV
389 
CLASS="REFSECT1"
390 
><A
391 
NAME="KERNEL-FLAGS-CONTEXT"
392 
></A
393 
><H2
394 
>Valid contexts</H2
395 
><P
396 
><TT
397 
CLASS="FUNCTION"
398 
>cyg_flag_init</TT
399 
> is typically called during system
400 
initialization but may also be called in thread context. The same
401 
applies to <TT
402 
CLASS="FUNCTION"
403 
>cyg_flag_destroy</TT
404 
>.
405 
<TT
406 
CLASS="FUNCTION"
407 
>cyg_flag_wait</TT
408 
> and
409 
<TT
410 
CLASS="FUNCTION"
411 
>cyg_flag_timed_wait</TT
412 
> may only be called from
413 
thread context. The remaining functions may be called from thread or
414 
DSR context.
415 
      </P
416 
></DIV
417 
><DIV
418 
CLASS="NAVFOOTER"
419 
><HR
420 
ALIGN="LEFT"
421 
WIDTH="100%"><TABLE
422 
SUMMARY="Footer navigation table"
423 
WIDTH="100%"
424 
BORDER="0"
425 
CELLPADDING="0"
426 
CELLSPACING="0"
427 
><TR
428 
><TD
429 
WIDTH="33%"
430 
ALIGN="left"
431 
VALIGN="top"
432 
><A
433 
HREF="kernel-mail-boxes.html"
434 
ACCESSKEY="P"
435 
>Prev</A
436 
></TD
437 
><TD
438 
WIDTH="34%"
439 
ALIGN="center"
440 
VALIGN="top"
441 
><A
442 
HREF="ecos-ref.html"
443 
ACCESSKEY="H"
444 
>Home</A
445 
></TD
446 
><TD
447 
WIDTH="33%"
448 
ALIGN="right"
449 
VALIGN="top"
450 
><A
451 
HREF="kernel-spinlocks.html"
452 
ACCESSKEY="N"
453 
>Next</A
454 
></TD
455 
></TR
456 
><TR
457 
><TD
458 
WIDTH="33%"
459 
ALIGN="left"
460 
VALIGN="top"
461 
>Mail boxes</TD
462 
><TD
463 
WIDTH="34%"
464 
ALIGN="center"
465 
VALIGN="top"
466 
><A
467 
HREF="kernel.html"
468 
ACCESSKEY="U"
469 
>Up</A
470 
></TD
471 
><TD
472 
WIDTH="33%"
473 
ALIGN="right"
474 
VALIGN="top"
475 
>Spinlocks</TD
476 
></TR
477 
></TABLE
478 
></DIV
479 
></BODY
480 
></HTML
481 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.