doc/html/ref/kernel-flags.html

   1 <!-- 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 >