OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

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

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 
>Clocks</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="Counters"
26 
HREF="kernel-counters.html"><LINK
27 
REL="NEXT"
28 
TITLE="Alarms"
29 
HREF="kernel-alarms.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-counters.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-alarms.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-CLOCKS">Clocks</H1
83 
><DIV
84 
CLASS="REFNAMEDIV"
85 
><A
86 
NAME="AEN922"
87 
></A
88 
><H2
89 
>Name</H2
90 
>cyg_clock_create, cyg_clock_delete, cyg_clock_to_counter, cyg_clock_set_resolution, cyg_clock_get_resolution, cyg_real_time_clock, cyg_current_time&nbsp;--&nbsp;Provide system clocks</DIV
91 
><DIV
92 
CLASS="REFSYNOPSISDIV"
93 
><A
94 
NAME="AEN931"><H2
95 
>Synopsis</H2
96 
><DIV
97 
CLASS="FUNCSYNOPSIS"
98 
><A
99 
NAME="AEN932"><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_clock_create</CODE
119 
>(cyg_resolution_t resolution, cyg_handle_t* handle, cyg_clock* clock);</CODE
120 
></P
121 
><P
122 
><CODE
123 
><CODE
124 
CLASS="FUNCDEF"
125 
>void cyg_clock_delete</CODE
126 
>(cyg_handle_t clock);</CODE
127 
></P
128 
><P
129 
><CODE
130 
><CODE
131 
CLASS="FUNCDEF"
132 
>void cyg_clock_to_counter</CODE
133 
>(cyg_handle_t clock, cyg_handle_t* counter);</CODE
134 
></P
135 
><P
136 
><CODE
137 
><CODE
138 
CLASS="FUNCDEF"
139 
>void cyg_clock_set_resolution</CODE
140 
>(cyg_handle_t clock, cyg_resolution_t resolution);</CODE
141 
></P
142 
><P
143 
><CODE
144 
><CODE
145 
CLASS="FUNCDEF"
146 
>cyg_resolution_t cyg_clock_get_resolution</CODE
147 
>(cyg_handle_t clock);</CODE
148 
></P
149 
><P
150 
><CODE
151 
><CODE
152 
CLASS="FUNCDEF"
153 
>cyg_handle_t cyg_real_time_clock</CODE
154 
>(void);</CODE
155 
></P
156 
><P
157 
><CODE
158 
><CODE
159 
CLASS="FUNCDEF"
160 
>cyg_tick_count_t cyg_current_time</CODE
161 
>(void);</CODE
162 
></P
163 
><P
164 
></P
165 
></DIV
166 
></DIV
167 
><DIV
168 
CLASS="REFSECT1"
169 
><A
170 
NAME="KERNEL-CLOCKS-DESCRIPTION"
171 
></A
172 
><H2
173 
>Description</H2
174 
><P
175 
>In the eCos kernel clock objects are a special form of <A
176 
HREF="kernel-counters.html"
177 
>counter</A
178 
> objects. They are attached to
179 
a specific type of hardware, clocks that generate ticks at very
180 
specific time intervals, whereas counters can be used with any event
181 
source.
182 
      </P
183 
><P
184 
>In a default configuration the kernel provides a single clock
185 
instance, the real-time clock. This gets used for timeslicing and for
186 
operations that involve a timeout, for example
187 
<TT
188 
CLASS="FUNCTION"
189 
>cyg_semaphore_timed_wait</TT
190 
>. If this functionality
191 
is not required it can be removed from the system using the
192 
configuration option <TT
193 
CLASS="VARNAME"
194 
>CYGVAR_KERNEL_COUNTERS_CLOCK</TT
195 
>.
196 
Otherwise the real-time clock can be accessed by a call to
197 
<TT
198 
CLASS="FUNCTION"
199 
>cyg_real_time_clock</TT
200 
>, allowing applications to
201 
attach alarms, and the current counter value can be obtained using
202 
<TT
203 
CLASS="FUNCTION"
204 
>cyg_current_time</TT
205 
>.
206 
      </P
207 
><P
208 
>Applications can create and destroy additional clocks if desired,
209 
using <TT
210 
CLASS="FUNCTION"
211 
>cyg_clock_create</TT
212 
> and
213 
<TT
214 
CLASS="FUNCTION"
215 
>cyg_clock_delete</TT
216 
>. The first argument to
217 
<TT
218 
CLASS="FUNCTION"
219 
>cyg_clock_create</TT
220 
> specifies the
221 
<A
222 
HREF="kernel-clocks.html#KERNEL-CLOCKS-RESOLUTION"
223 
>resolution</A
224 
> this clock
225 
will run at. The second argument is used to return a handle for this
226 
clock object, and the third argument provides the kernel with the
227 
memory needed to hold this object. This clock will not actually tick
228 
by itself. Instead it is the responsibility of application code to
229 
initialize a suitable hardware timer to generate interrupts at the
230 
appropriate frequency, install an interrupt handler for this, and
231 
call <TT
232 
CLASS="FUNCTION"
233 
>cyg_counter_tick</TT
234 
> from inside the DSR.
235 
Associated with each clock is a kernel counter, a handle for which can
236 
be obtained using <TT
237 
CLASS="FUNCTION"
238 
>cyg_clock_to_counter</TT
239 
>.
240 
      </P
241 
></DIV
242 
><DIV
243 
CLASS="REFSECT1"
244 
><A
245 
NAME="KERNEL-CLOCKS-RESOLUTION"
246 
></A
247 
><H2
248 
>Clock Resolutions and Ticks</H2
249 
><P
250 
>At the kernel level all clock-related operations including delays,
251 
timeouts and alarms work in units of clock ticks, rather than in units
252 
of seconds or milliseconds. If the calling code, whether the
253 
application or some other package, needs to operate using units such
254 
as milliseconds then it has to convert from these units to clock
255 
ticks.
256 
      </P
257 
><P
258 
>The main reason for this is that it accurately reflects the
259 
hardware: calling something like <TT
260 
CLASS="FUNCTION"
261 
>nanosleep</TT
262 
> with a
263 
delay of ten nanoseconds will not work as intended on any real
264 
hardware because timer interrupts simply will not happen that
265 
frequently; instead calling <TT
266 
CLASS="FUNCTION"
267 
>cyg_thread_delay</TT
268 
> with
269 
the equivalent delay of 0 ticks gives a much clearer indication that
270 
the application is attempting something inappropriate for the target
271 
hardware. Similarly, passing a delay of five ticks to
272 
<TT
273 
CLASS="FUNCTION"
274 
>cyg_thread_delay</TT
275 
> makes it fairly obvious that
276 
the current thread will be suspended for somewhere between four and
277 
five clock periods, as opposed to passing 50000000 to
278 
<TT
279 
CLASS="FUNCTION"
280 
>nanosleep</TT
281 
> which suggests a granularity that is
282 
not actually provided.
283 
      </P
284 
><P
285 
>A secondary reason is that conversion between clock ticks and units
286 
such as milliseconds can be somewhat expensive, and whenever possible
287 
should be done at compile-time or by the application developer rather
288 
than at run-time. This saves code size and cpu cycles.
289 
      </P
290 
><P
291 
>The information needed to perform these conversions is the clock
292 
resolution. This is a structure with two fields, a dividend and a
293 
divisor, and specifies the number of nanoseconds between clock ticks.
294 
For example a clock that runs at 100Hz will have 10 milliseconds
295 
between clock ticks, or 10000000 nanoseconds. The ratio between the
296 
resolution's dividend and divisor will therefore be 10000000 to 1, and
297 
typical values for these might be 1000000000 and 100. If the clock
298 
runs at a different frequency, say 60Hz, the numbers could be
299 
1000000000 and 60 respectively. Given a delay in nanoseconds, this can
300 
be converted to clock ticks by multiplying with the the divisor and
301 
then dividing by the dividend. For example a delay of 50 milliseconds
302 
corresponds to 50000000 nanoseconds, and with a clock frequency of
303 
100Hz this can be converted to
304 
((50000000&nbsp;*&nbsp;100)&nbsp;/&nbsp;1000000000)&nbsp;=&nbsp;5
305 
clock ticks. Given the large numbers involved this arithmetic normally
306 
has to be done using 64-bit precision and the
307 
<SPAN
308 
CLASS="TYPE"
309 
>long&nbsp;long</SPAN
310 
> data type, but allows code to run on
311 
hardware with unusual clock frequencies.
312 
      </P
313 
><P
314 
>The default frequency for the real-time clock on any platform is
315 
usually about 100Hz, but platform-specific documentation should be
316 
consulted for this information. Usually it is possible to override
317 
this default by configuration options, but again this depends on the
318 
capabilities of the underlying hardware. The resolution for any clock
319 
can be obtained using <TT
320 
CLASS="FUNCTION"
321 
>cyg_clock_get_resolution</TT
322 
>.
323 
For clocks created by application code, there is also a function
324 
<TT
325 
CLASS="FUNCTION"
326 
>cyg_clock_set_resolution</TT
327 
>. This does not affect
328 
the underlying hardware timer in any way, it merely updates the
329 
information that will be returned in subsequent calls to
330 
<TT
331 
CLASS="FUNCTION"
332 
>cyg_clock_get_resolution</TT
333 
>: changing the actual
334 
underlying clock frequency will require appropriate manipulation of
335 
the timer hardware.
336 
      </P
337 
></DIV
338 
><DIV
339 
CLASS="REFSECT1"
340 
><A
341 
NAME="KERNEL-CLOCKS-CONTEXT"
342 
></A
343 
><H2
344 
>Valid contexts</H2
345 
><P
346 
><TT
347 
CLASS="FUNCTION"
348 
>cyg_clock_create</TT
349 
> is usually only called during
350 
system initialization (if at all), but may also be called from thread
351 
context. The same applies to <TT
352 
CLASS="FUNCTION"
353 
>cyg_clock_delete</TT
354 
>.
355 
The remaining functions may be called during initialization, from
356 
thread context, or from DSR context, although it should be noted that
357 
there is no locking between
358 
<TT
359 
CLASS="FUNCTION"
360 
>cyg_clock_get_resolution</TT
361 
> and
362 
<TT
363 
CLASS="FUNCTION"
364 
>cyg_clock_set_resolution</TT
365 
> so theoretically it is
366 
possible that the former returns an inconsistent data structure.
367 
      </P
368 
></DIV
369 
><DIV
370 
CLASS="NAVFOOTER"
371 
><HR
372 
ALIGN="LEFT"
373 
WIDTH="100%"><TABLE
374 
SUMMARY="Footer navigation table"
375 
WIDTH="100%"
376 
BORDER="0"
377 
CELLPADDING="0"
378 
CELLSPACING="0"
379 
><TR
380 
><TD
381 
WIDTH="33%"
382 
ALIGN="left"
383 
VALIGN="top"
384 
><A
385 
HREF="kernel-counters.html"
386 
ACCESSKEY="P"
387 
>Prev</A
388 
></TD
389 
><TD
390 
WIDTH="34%"
391 
ALIGN="center"
392 
VALIGN="top"
393 
><A
394 
HREF="ecos-ref.html"
395 
ACCESSKEY="H"
396 
>Home</A
397 
></TD
398 
><TD
399 
WIDTH="33%"
400 
ALIGN="right"
401 
VALIGN="top"
402 
><A
403 
HREF="kernel-alarms.html"
404 
ACCESSKEY="N"
405 
>Next</A
406 
></TD
407 
></TR
408 
><TR
409 
><TD
410 
WIDTH="33%"
411 
ALIGN="left"
412 
VALIGN="top"
413 
>Counters</TD
414 
><TD
415 
WIDTH="34%"
416 
ALIGN="center"
417 
VALIGN="top"
418 
><A
419 
HREF="kernel.html"
420 
ACCESSKEY="U"
421 
>Up</A
422 
></TD
423 
><TD
424 
WIDTH="33%"
425 
ALIGN="right"
426 
VALIGN="top"
427 
>Alarms</TD
428 
></TR
429 
></TABLE
430 
></DIV
431 
></BODY
432 
></HTML
433 
>

powered by: WebSVN 2.1.0

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