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. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="The eCos Kernel"
23 HREF="kernel.html"><LINK
25 TITLE="Exception handling"
26 HREF="kernel-exceptions.html"><LINK
29 HREF="kernel-clocks.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="kernel-exceptions.html"
71 HREF="kernel-clocks.html"
82 NAME="KERNEL-COUNTERS">Counters</H1
90 >cyg_counter_create, cyg_counter_delete, cyg_counter_current_value, cyg_counter_set_value, cyg_counter_tick -- Count event occurrences</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/kernel/kapi.h>
118 >void cyg_counter_create</CODE
119 >(cyg_handle_t* handle, cyg_counter* counter);</CODE
125 >void cyg_counter_delete</CODE
126 >(cyg_handle_t counter);</CODE
132 >cyg_tick_count_t cyg_counter_current_value</CODE
133 >(cyg_handle_t counter);</CODE
139 >void cyg_counter_set_value</CODE
140 >(cyg_handle_t counter, cyg_tick_count_t new_value);</CODE
146 >void cyg_counter_tick</CODE
147 >(cyg_handle_t counter);</CODE
156 NAME="KERNEL-COUNTERS-DESCRIPTION"
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"
168 > to counters, causing a function
169 to be called when some number of events have occurred.
172 >A new counter is initialized by a call to
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
184 >cyg_counter_delete</TT
185 > can be used to release the
186 resources, allowing the <SPAN
190 structure to be re-used.
193 >Initializing a counter does not automatically attach it to any source
194 of events. Instead some other code needs to call
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
203 >cyg_counter_current_value</TT
207 >cyg_counter_set_value</TT
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
213 >cyg_counter_set_value</TT
215 never trigger any alarms. A newly initialized counter has a starting
219 >The kernel provides two different implementations of counters. The
222 >CYGIMP_KERNEL_COUNTERS_SINGLE_LIST</TT
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
231 >CYGIMP_KERNEL_COUNTERS_MULTI_LIST</TT
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
239 >CYGIMP_KERNEL_COUNTERS_SORT_LIST</TT
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
250 NAME="KERNEL-COUNTERS-CONTEXT"
257 >cyg_counter_create</TT
258 > is typically called during
259 system initialization but may also be called in thread context.
262 >cyg_counter_delete</TT
263 > may be called during
264 initialization or in thread context.
267 >cyg_counter_current_value</TT
271 >cyg_counter_set_value</TT
275 >cyg_counter_tick</TT
276 > may be called during
277 initialization or from thread or DSR context. In fact,
280 >cyg_counter_tick</TT
281 > is usually called from inside a
282 DSR in response to an external event of some sort.
290 SUMMARY="Footer navigation table"
301 HREF="kernel-exceptions.html"
319 HREF="kernel-clocks.html"
329 >Exception handling</TD