doc/html/ref/kernel-counters.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 >Counters</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="Exception handling"
  26 HREF="kernel-exceptions.html"><LINK
  27 REL="NEXT"
  28 TITLE="Clocks"
  29 HREF="kernel-clocks.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-exceptions.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-clocks.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-COUNTERS">Counters</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN854"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >cyg_counter_create, cyg_counter_delete, cyg_counter_current_value, cyg_counter_set_value, cyg_counter_tick&nbsp;--&nbsp;Count event occurrences</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN861"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN862"><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_counter_create</CODE
 119 >(cyg_handle_t* handle, cyg_counter* counter);</CODE
 120 ></P
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >void cyg_counter_delete</CODE
 126 >(cyg_handle_t counter);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >cyg_tick_count_t cyg_counter_current_value</CODE
 133 >(cyg_handle_t counter);</CODE
 134 ></P
 135 ><P
 136 ><CODE
 137 ><CODE
 138 CLASS="FUNCDEF"
 139 >void cyg_counter_set_value</CODE
 140 >(cyg_handle_t counter, cyg_tick_count_t new_value);</CODE
 141 ></P
 142 ><P
 143 ><CODE
 144 ><CODE
 145 CLASS="FUNCDEF"
 146 >void cyg_counter_tick</CODE
 147 >(cyg_handle_t counter);</CODE
 148 ></P
 149 ><P
 150 ></P
 151 ></DIV
 152 ></DIV
 153 ><DIV
 154 CLASS="REFSECT1"
 155 ><A
 156 NAME="KERNEL-COUNTERS-DESCRIPTION"
 157 ></A
 158 ><H2
 159 >Description</H2
 160 ><P
 161 >Kernel counters can be used to keep track of how many times a
 162 particular event has occurred. Usually this event is an external
 163 signal of some sort. The most common use of counters is in the
 164 implementation of clocks, but they can be useful with other event
 165 sources as well. Application code can attach <A
 166 HREF="kernel-alarms.html"
 167 >alarms</A
 168 > to counters, causing a function
 169 to be called when some number of events have occurred.
 170       </P
 171 ><P
 172 >A new counter is initialized by a call to
 173 <TT
 174 CLASS="FUNCTION"
 175 >cyg_counter_create</TT
 176 >. The first argument is used to
 177 return a handle to the new counter which can be used for subsequent
 178 operations. The second argument allows the application to provide the
 179 memory needed for the object, thus eliminating any need for dynamic
 180 memory allocation within the kernel. If a counter is no longer
 181 required and does not have any alarms attached then
 182 <TT
 183 CLASS="FUNCTION"
 184 >cyg_counter_delete</TT
 185 > can be used to release the
 186 resources, allowing the <SPAN
 187 CLASS="STRUCTNAME"
 188 >cyg_counter</SPAN
 189 > data
 190 structure to be re-used.
 191       </P
 192 ><P
 193 >Initializing a counter does not automatically attach it to any source
 194 of events. Instead some other code needs to call
 195 <TT
 196 CLASS="FUNCTION"
 197 >cyg_counter_tick</TT
 198 > whenever a suitable event
 199 occurs, which will cause the counter to be incremented and may cause
 200 alarms to trigger. The current value associated with the counter can
 201 be retrieved using <TT
 202 CLASS="FUNCTION"
 203 >cyg_counter_current_value</TT
 204 > and
 205 modified with <TT
 206 CLASS="FUNCTION"
 207 >cyg_counter_set_value</TT
 208 >. Typically
 209 the latter function is only used during initialization, for example to
 210 set a clock to wallclock time, but it can be used to reset a counter
 211 if necessary. However <TT
 212 CLASS="FUNCTION"
 213 >cyg_counter_set_value</TT
 214 > will
 215 never trigger any alarms. A newly initialized counter has a starting
 216 value of 0.
 217       </P
 218 ><P
 219 >The kernel provides two different implementations of counters. The
 220 default is <TT
 221 CLASS="VARNAME"
 222 >CYGIMP_KERNEL_COUNTERS_SINGLE_LIST</TT
 223 > which
 224 stores all alarms attached to the counter on a single list. This is
 225 simple and usually efficient. However when a tick occurs the kernel
 226 code has to traverse this list, typically at DSR level, so if there
 227 are a significant number of alarms attached to a single counter this
 228 will affect the system's dispatch latency. The alternative
 229 implementation, <TT
 230 CLASS="VARNAME"
 231 >CYGIMP_KERNEL_COUNTERS_MULTI_LIST</TT
 232 >,
 233 stores each alarm in one of an array of lists such that at most one of
 234 the lists needs to be searched per clock tick. This involves extra
 235 code and data, but can improve real-time responsiveness in some
 236 circumstances. Another configuration option that is relevant here
 237 is <TT
 238 CLASS="VARNAME"
 239 >CYGIMP_KERNEL_COUNTERS_SORT_LIST</TT
 240 >, which is
 241 disabled by default. This provides a trade off between doing work
 242 whenever a new alarm is added to a counter and doing work whenever a
 243 tick occurs. It is application-dependent which of these is more
 244 appropriate.
 245       </P
 246 ></DIV
 247 ><DIV
 248 CLASS="REFSECT1"
 249 ><A
 250 NAME="KERNEL-COUNTERS-CONTEXT"
 251 ></A
 252 ><H2
 253 >Valid contexts</H2
 254 ><P
 255 ><TT
 256 CLASS="FUNCTION"
 257 >cyg_counter_create</TT
 258 > is typically called during
 259 system initialization but may also be called in thread context.
 260 Similarly <TT
 261 CLASS="FUNCTION"
 262 >cyg_counter_delete</TT
 263 > may be called during
 264 initialization or in thread context.
 265 <TT
 266 CLASS="FUNCTION"
 267 >cyg_counter_current_value</TT
 268 >,
 269 <TT
 270 CLASS="FUNCTION"
 271 >cyg_counter_set_value</TT
 272 > and
 273 <TT
 274 CLASS="FUNCTION"
 275 >cyg_counter_tick</TT
 276 > may be called during
 277 initialization or from thread or DSR context. In fact,
 278 <TT
 279 CLASS="FUNCTION"
 280 >cyg_counter_tick</TT
 281 > is usually called from inside a
 282 DSR in response to an external event of some sort.
 283       </P
 284 ></DIV
 285 ><DIV
 286 CLASS="NAVFOOTER"
 287 ><HR
 288 ALIGN="LEFT"
 289 WIDTH="100%"><TABLE
 290 SUMMARY="Footer navigation table"
 291 WIDTH="100%"
 292 BORDER="0"
 293 CELLPADDING="0"
 294 CELLSPACING="0"
 295 ><TR
 296 ><TD
 297 WIDTH="33%"
 298 ALIGN="left"
 299 VALIGN="top"
 300 ><A
 301 HREF="kernel-exceptions.html"
 302 ACCESSKEY="P"
 303 >Prev</A
 304 ></TD
 305 ><TD
 306 WIDTH="34%"
 307 ALIGN="center"
 308 VALIGN="top"
 309 ><A
 310 HREF="ecos-ref.html"
 311 ACCESSKEY="H"
 312 >Home</A
 313 ></TD
 314 ><TD
 315 WIDTH="33%"
 316 ALIGN="right"
 317 VALIGN="top"
 318 ><A
 319 HREF="kernel-clocks.html"
 320 ACCESSKEY="N"
 321 >Next</A
 322 ></TD
 323 ></TR
 324 ><TR
 325 ><TD
 326 WIDTH="33%"
 327 ALIGN="left"
 328 VALIGN="top"
 329 >Exception handling</TD
 330 ><TD
 331 WIDTH="34%"
 332 ALIGN="center"
 333 VALIGN="top"
 334 ><A
 335 HREF="kernel.html"
 336 ACCESSKEY="U"
 337 >Up</A
 338 ></TD
 339 ><TD
 340 WIDTH="33%"
 341 ALIGN="right"
 342 VALIGN="top"
 343 >Clocks</TD
 344 ></TR
 345 ></TABLE
 346 ></DIV
 347 ></BODY
 348 ></HTML
 349 >