doc/html/ref/kernel-alarms.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 >Alarms</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="Clocks"
  26 HREF="kernel-clocks.html"><LINK
  27 REL="NEXT"
  28 TITLE="Mutexes"
  29 HREF="kernel-mutexes.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-clocks.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-mutexes.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-ALARMS">Alarms</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN1016"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >cyg_alarm_create, cyg_alarm_delete, cyg_alarm_initialize, cyg_alarm_enable, cyg_alarm_disable&nbsp;--&nbsp;Run an alarm function when a number of events have occurred</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN1023"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN1024"><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_alarm_create</CODE
 119 >(cyg_handle_t counter, cyg_alarm_t* alarmfn, cyg_addrword_t data, cyg_handle_t* handle, cyg_alarm* alarm);</CODE
 120 ></P
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >void cyg_alarm_delete</CODE
 126 >(cyg_handle_t alarm);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >void cyg_alarm_initialize</CODE
 133 >(cyg_handle_t alarm, cyg_tick_count_t trigger, cyg_tick_count_t interval);</CODE
 134 ></P
 135 ><P
 136 ><CODE
 137 ><CODE
 138 CLASS="FUNCDEF"
 139 >void cyg_alarm_enable</CODE
 140 >(cyg_handle_t alarm);</CODE
 141 ></P
 142 ><P
 143 ><CODE
 144 ><CODE
 145 CLASS="FUNCDEF"
 146 >void cyg_alarm_disable</CODE
 147 >(cyg_handle_t alarm);</CODE
 148 ></P
 149 ><P
 150 ></P
 151 ></DIV
 152 ></DIV
 153 ><DIV
 154 CLASS="REFSECT1"
 155 ><A
 156 NAME="KERNEL-ALARMS-DESCRIPTION"
 157 ></A
 158 ><H2
 159 >Description</H2
 160 ><P
 161 >Kernel alarms are used together with counters and allow for action to
 162 be taken when a certain number of events have occurred. If the counter
 163 is associated with a clock then the alarm action happens when the
 164 appropriate number of clock ticks have occurred, in other words after
 165 a certain period of time.
 166       </P
 167 ><P
 168 >Setting up an alarm involves a two-step process. First the alarm must
 169 be created with a call to <TT
 170 CLASS="FUNCTION"
 171 >cyg_alarm_create</TT
 172 >. This
 173 takes five arguments. The first identifies the counter to which the
 174 alarm should be attached. If the alarm should be attached to the
 175 system's real-time clock then <TT
 176 CLASS="FUNCTION"
 177 >cyg_real_time_clock</TT
 178 >
 179 and <TT
 180 CLASS="FUNCTION"
 181 >cyg_clock_to_counter</TT
 182 > can be used to get hold
 183 of the appropriate handle. The next two arguments specify the action
 184 to be taken when the alarm is triggered, in the form of a function
 185 pointer and some data. This function should take the form:
 186       </P
 187 ><TABLE
 188 BORDER="5"
 189 BGCOLOR="#E0E0F0"
 190 WIDTH="70%"
 191 ><TR
 192 ><TD
 193 ><PRE
 194 CLASS="PROGRAMLISTING"
 195 >void
 196 alarm_handler(cyg_handle_t alarm, cyg_addrword_t data)
 197 {
 198     &#8230;
 199 }
 200       </PRE
 201 ></TD
 202 ></TR
 203 ></TABLE
 204 ><P
 205 >The data argument passed to the alarm function corresponds to the
 206 third argument passed to <TT
 207 CLASS="FUNCTION"
 208 >cyg_alarm_create</TT
 209 >.
 210 The fourth argument to <TT
 211 CLASS="FUNCTION"
 212 >cyg_alarm_create</TT
 213 > is used
 214 to return a handle to the newly-created alarm object, and the final
 215 argument provides the memory needed for the alarm object and thus
 216 avoids any need for dynamic memory allocation within the kernel.
 217       </P
 218 ><P
 219 >Once an alarm has been created a further call to
 220 <TT
 221 CLASS="FUNCTION"
 222 >cyg_alarm_initialize</TT
 223 > is needed to activate it.
 224 The first argument specifies the alarm. The second argument indicates
 225 the number of events, for example clock ticks, that need to occur
 226 before the alarm triggers. If the third argument is 0 then the alarm
 227 will only trigger once. A non-zero value specifies that the alarm
 228 should trigger repeatedly, with an interval of the specified number of
 229 events.
 230       </P
 231 ><P
 232 >Alarms can be temporarily disabled and reenabled using
 233 <TT
 234 CLASS="FUNCTION"
 235 >cyg_alarm_disable</TT
 236 > and
 237 <TT
 238 CLASS="FUNCTION"
 239 >cyg_alarm_enable</TT
 240 >. Alternatively another call to
 241 <TT
 242 CLASS="FUNCTION"
 243 >cyg_alarm_initialize</TT
 244 > can be used to modify the
 245 behaviour of an existing alarm. If an alarm is no longer required then
 246 the associated resources can be released using
 247 <TT
 248 CLASS="FUNCTION"
 249 >cyg_alarm_delete</TT
 250 >.
 251       </P
 252 ><P
 253 >The alarm function is invoked when a counter tick occurs, in other
 254 words when there is a call to <TT
 255 CLASS="FUNCTION"
 256 >cyg_counter_tick</TT
 257 >,
 258 and will happen in the same context. If the alarm is associated with
 259 the system's real-time clock then this will be DSR context, following
 260 a clock interrupt. If the alarm is associated with some other
 261 application-specific counter then the details will depend on how that
 262 counter is updated.
 263       </P
 264 ><P
 265 >If two or more alarms are registered for precisely the same counter tick,
 266 the order of execution of the alarm functions is unspecified.
 267       </P
 268 ></DIV
 269 ><DIV
 270 CLASS="REFSECT1"
 271 ><A
 272 NAME="KERNEL-ALARMS-CONTEXT"
 273 ></A
 274 ><H2
 275 >Valid contexts</H2
 276 ><P
 277 ><TT
 278 CLASS="FUNCTION"
 279 >cyg_alarm_create</TT
 280 >
 281 <TT
 282 CLASS="FUNCTION"
 283 >cyg_alarm_initialize</TT
 284 > is typically called during
 285 system initialization but may also be called in thread context. The
 286 same applies to <TT
 287 CLASS="FUNCTION"
 288 >cyg_alarm_delete</TT
 289 >.
 290 <TT
 291 CLASS="FUNCTION"
 292 >cyg_alarm_initialize</TT
 293 >,
 294 <TT
 295 CLASS="FUNCTION"
 296 >cyg_alarm_disable</TT
 297 > and
 298 <TT
 299 CLASS="FUNCTION"
 300 >cyg_alarm_enable</TT
 301 > may be called during
 302 initialization or from thread or DSR context, but
 303 <TT
 304 CLASS="FUNCTION"
 305 >cyg_alarm_enable</TT
 306 > and
 307 <TT
 308 CLASS="FUNCTION"
 309 >cyg_alarm_initialize</TT
 310 > may be expensive operations
 311 and should only be called when necessary.
 312       </P
 313 ></DIV
 314 ><DIV
 315 CLASS="NAVFOOTER"
 316 ><HR
 317 ALIGN="LEFT"
 318 WIDTH="100%"><TABLE
 319 SUMMARY="Footer navigation table"
 320 WIDTH="100%"
 321 BORDER="0"
 322 CELLPADDING="0"
 323 CELLSPACING="0"
 324 ><TR
 325 ><TD
 326 WIDTH="33%"
 327 ALIGN="left"
 328 VALIGN="top"
 329 ><A
 330 HREF="kernel-clocks.html"
 331 ACCESSKEY="P"
 332 >Prev</A
 333 ></TD
 334 ><TD
 335 WIDTH="34%"
 336 ALIGN="center"
 337 VALIGN="top"
 338 ><A
 339 HREF="ecos-ref.html"
 340 ACCESSKEY="H"
 341 >Home</A
 342 ></TD
 343 ><TD
 344 WIDTH="33%"
 345 ALIGN="right"
 346 VALIGN="top"
 347 ><A
 348 HREF="kernel-mutexes.html"
 349 ACCESSKEY="N"
 350 >Next</A
 351 ></TD
 352 ></TR
 353 ><TR
 354 ><TD
 355 WIDTH="33%"
 356 ALIGN="left"
 357 VALIGN="top"
 358 >Clocks</TD
 359 ><TD
 360 WIDTH="34%"
 361 ALIGN="center"
 362 VALIGN="top"
 363 ><A
 364 HREF="kernel.html"
 365 ACCESSKEY="U"
 366 >Up</A
 367 ></TD
 368 ><TD
 369 WIDTH="33%"
 370 ALIGN="right"
 371 VALIGN="top"
 372 >Mutexes</TD
 373 ></TR
 374 ></TABLE
 375 ></DIV
 376 ></BODY
 377 ></HTML
 378 >