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
26 HREF="kernel-counters.html"><LINK
29 HREF="kernel-alarms.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="kernel-counters.html"
71 HREF="kernel-alarms.html"
82 NAME="KERNEL-CLOCKS">Clocks</H1
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 -- Provide system clocks</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/kernel/kapi.h>
118 >void cyg_clock_create</CODE
119 >(cyg_resolution_t resolution, cyg_handle_t* handle, cyg_clock* clock);</CODE
125 >void cyg_clock_delete</CODE
126 >(cyg_handle_t clock);</CODE
132 >void cyg_clock_to_counter</CODE
133 >(cyg_handle_t clock, cyg_handle_t* counter);</CODE
139 >void cyg_clock_set_resolution</CODE
140 >(cyg_handle_t clock, cyg_resolution_t resolution);</CODE
146 >cyg_resolution_t cyg_clock_get_resolution</CODE
147 >(cyg_handle_t clock);</CODE
153 >cyg_handle_t cyg_real_time_clock</CODE
160 >cyg_tick_count_t cyg_current_time</CODE
170 NAME="KERNEL-CLOCKS-DESCRIPTION"
175 >In the eCos kernel clock objects are a special form of <A
176 HREF="kernel-counters.html"
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
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
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
194 >CYGVAR_KERNEL_COUNTERS_CLOCK</TT
196 Otherwise the real-time clock can be accessed by a call to
199 >cyg_real_time_clock</TT
200 >, allowing applications to
201 attach alarms, and the current counter value can be obtained using
204 >cyg_current_time</TT
208 >Applications can create and destroy additional clocks if desired,
211 >cyg_clock_create</TT
215 >cyg_clock_delete</TT
216 >. The first argument to
219 >cyg_clock_create</TT
222 HREF="kernel-clocks.html#KERNEL-CLOCKS-RESOLUTION"
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
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
238 >cyg_clock_to_counter</TT
245 NAME="KERNEL-CLOCKS-RESOLUTION"
248 >Clock Resolutions and Ticks</H2
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
258 >The main reason for this is that it accurately reflects the
259 hardware: calling something like <TT
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
267 >cyg_thread_delay</TT
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
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
281 > which suggests a granularity that is
282 not actually provided.
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.
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 * 100) / 1000000000) = 5
305 clock ticks. Given the large numbers involved this arithmetic normally
306 has to be done using 64-bit precision and the
309 >long long</SPAN
310 > data type, but allows code to run on
311 hardware with unusual clock frequencies.
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
321 >cyg_clock_get_resolution</TT
323 For clocks created by application code, there is also a 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
332 >cyg_clock_get_resolution</TT
333 >: changing the actual
334 underlying clock frequency will require appropriate manipulation of
341 NAME="KERNEL-CLOCKS-CONTEXT"
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
353 >cyg_clock_delete</TT
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
360 >cyg_clock_get_resolution</TT
364 >cyg_clock_set_resolution</TT
365 > so theoretically it is
366 possible that the former returns an inconsistent data structure.
374 SUMMARY="Footer navigation table"
385 HREF="kernel-counters.html"
403 HREF="kernel-alarms.html"
projects / karo-tx-redboot.git / blob