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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-counters.html] - Blame information for rev 598

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- 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 
>

powered by: WebSVN 2.1.0

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