source: rtems/doc/user/clock.t @ bf4d016

4.104.114.84.95
Last change on this file since bf4d016 was bf4d016, checked in by Joel Sherrill <joel.sherrill@…>, on 04/02/07 at 18:22:56

2007-04-02 Joel Sherrill <joel@…>

  • user/clock.t: Add clock_get_uptime().
  • Property mode set to 100644
File size: 15.6 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Clock Manager
10
11@cindex clock
12
13@section Introduction
14
15The clock manager provides support for time of day
16and other time related capabilities.  The directives provided by
17the clock manager are:
18
19@itemize @bullet
20@item @code{@value{DIRPREFIX}clock_set} - Set system date and time
21@item @code{@value{DIRPREFIX}clock_get} - Get system date and time information
22@item @code{@value{DIRPREFIX}clock_get_uptime} - Get time since boot
23@item @code{@value{DIRPREFIX}clock_set_nanoseconds_extension} - Install the nanoseconds since last tick handler
24@item @code{@value{DIRPREFIX}clock_tick} - Announce a clock tick
25@end itemize
26
27@section Background
28
29@subsection Required Support
30
31For the features provided by the clock manager to be
32utilized, periodic timer interrupts are required.  Therefore, a
33real-time clock or hardware timer is necessary to create the
34timer interrupts.  The @code{@value{DIRPREFIX}clock_tick}
35directive is normally called
36by the timer ISR to announce to RTEMS that a system clock tick
37has occurred.  Elapsed time is measured in ticks.  A tick is
38defined to be an integral number of microseconds which is
39specified by the user in the Configuration Table.
40
41@subsection Time and Date Data Structures
42
43The clock facilities of the clock manager operate
44upon calendar time.  These directives utilize the following date
45and time @value{STRUCTURE} for the native time and date format:
46
47
48@ifset is-C
49@findex rtems_time_of_day
50@example
51struct rtems_tod_control @{
52  rtems_unsigned32 year;   /* greater than 1987 */
53  rtems_unsigned32 month;  /* 1 - 12 */
54  rtems_unsigned32 day;    /* 1 - 31 */
55  rtems_unsigned32 hour;   /* 0 - 23 */
56  rtems_unsigned32 minute; /* 0 - 59 */
57  rtems_unsigned32 second; /* 0 - 59 */
58  rtems_unsigned32 ticks;  /* elapsed between seconds */
59@};
60
61typedef struct rtems_tod_control rtems_time_of_day;
62@end example
63@end ifset
64
65@ifset is-Ada
66@example
67type Time_Of_Day is
68   record
69      Year    : RTEMS.Unsigned32; -- year, A.D.
70      Month   : RTEMS.Unsigned32; -- month, 1 .. 12
71      Day     : RTEMS.Unsigned32; -- day, 1 .. 31
72      Hour    : RTEMS.Unsigned32; -- hour, 0 .. 23
73      Minute  : RTEMS.Unsigned32; -- minute, 0 .. 59
74      Second  : RTEMS.Unsigned32; -- second, 0 .. 59
75      Ticks   : RTEMS.Unsigned32; -- elapsed ticks between seconds
76   end record;
77@end example
78@end ifset
79
80
81The native date and time format is the only format
82supported when setting the system date and time using the
83@code{@value{DIRPREFIX}clock_get} directive.  Some applications
84expect to operate on a "UNIX-style" date and time data structure.  The
85@code{@value{DIRPREFIX}clock_get} directive can optionally return
86the current date and time in the
87following @value{STRUCTURE}:
88
89@ifset is-C
90@example
91@group
92typedef struct @{
93  rtems_unsigned32 seconds;       /* seconds since RTEMS epoch*/
94  rtems_unsigned32 microseconds;  /* since last second        */
95@} rtems_clock_time_value;
96@end group
97@end example
98@end ifset
99
100@ifset is-Ada
101@example
102type Clock_Time_Value is
103   record
104      Seconds      : Unsigned32;
105      Microseconds : Unsigned32;
106   end record;
107@end example
108@end ifset
109
110The seconds field in this @value{STRUCTURE} is the number of
111seconds since the RTEMS epoch of January 1, 1988.
112
113@subsection Clock Tick and Timeslicing
114
115@cindex timeslicing
116
117Timeslicing is a task scheduling discipline in which
118tasks of equal priority are executed for a specific period of
119time before control of the CPU is passed to another task.  It is
120also sometimes referred to as the automatic round-robin
121scheduling algorithm.  The length of time allocated to each task
122is known as the quantum or timeslice.
123
124The system's timeslice is defined as an integral
125number of ticks, and is specified in the Configuration Table.
126The timeslice is defined for the entire system of tasks, but
127timeslicing is enabled and disabled on a per task basis.
128
129The @code{@value{DIRPREFIX}clock_tick}
130directive implements timeslicing by
131decrementing the running task's time-remaining counter when both
132timeslicing and preemption are enabled.  If the task's timeslice
133has expired, then that task will be preempted if there exists a
134ready task of equal priority.
135
136@subsection Delays
137
138@cindex delays
139
140A sleep timer allows a task to delay for a given
141interval or up until a given time, and then wake and continue
142execution.  This type of timer is created automatically by the
143@code{@value{DIRPREFIX}task_wake_after}
144and @code{@value{DIRPREFIX}task_wake_when} directives and, as a result,
145does not have an RTEMS ID.  Once activated, a sleep timer cannot
146be explicitly deleted.  Each task may activate one and only one
147sleep timer at a time.
148
149@subsection Timeouts
150
151@cindex timeouts
152
153Timeouts are a special type of timer automatically
154created when the timeout option is used on the
155@code{@value{DIRPREFIX}message_queue_receive},
156@code{@value{DIRPREFIX}event_receive},
157@code{@value{DIRPREFIX}semaphore_obtain} and
158@code{@value{DIRPREFIX}region_get_segment} directives. 
159Each task may have one and only one timeout active at a time. 
160When a timeout expires, it unblocks the task with a timeout status code.
161
162@section Operations
163
164@subsection Announcing a Tick
165
166RTEMS provides the @code{@value{DIRPREFIX}clock_tick} directive which is
167called from the user's real-time clock ISR to inform RTEMS that
168a tick has elapsed.  The tick frequency value, defined in
169microseconds, is a configuration parameter found in the
170Configuration Table.  RTEMS divides one million microseconds
171(one second) by the number of microseconds per tick to determine
172the number of calls to the
173@code{@value{DIRPREFIX}clock_tick} directive per second.  The
174frequency of @code{@value{DIRPREFIX}clock_tick}
175calls determines the resolution
176(granularity) for all time dependent RTEMS actions.  For
177example, calling @code{@value{DIRPREFIX}clock_tick}
178ten times per second yields a higher
179resolution than calling @code{@value{DIRPREFIX}clock_tick}
180two times per second.  The @code{@value{DIRPREFIX}clock_tick}
181directive is responsible for maintaining both
182calendar time and the dynamic set of timers.
183
184@subsection Setting the Time
185
186The @code{@value{DIRPREFIX}clock_set} directive allows a task or an ISR to
187set the date and time maintained by RTEMS.  If setting the date
188and time causes any outstanding timers to pass their deadline,
189then the expired timers will be fired during the invocation of
190the @code{@value{DIRPREFIX}clock_set} directive.
191
192@subsection Obtaining the Time
193
194The @code{@value{DIRPREFIX}clock_get} directive allows a task or an ISR to
195obtain the current date and time or date and time related
196information.  The current date and time can be returned in
197either native or UNIX-style format.  Additionally, the
198application can obtain date and time related information such as
199the number of seconds since the RTEMS epoch, the number of ticks
200since the executive was initialized, and the number of ticks per
201second.  The information returned by the
202@code{@value{DIRPREFIX}clock_get} directive is
203dependent on the option selected by the caller.  This
204is specified using one of the following constants
205associated with the enumerated type
206@code{@value{DIRPREFIX}clock_get_options}:
207
208@findex rtems_clock_get_options
209
210@itemize @bullet
211@item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time
212
213@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style
214date and time
215
216@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - obtain number of ticks
217since RTEMS was initialized
218
219@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number
220of seconds since RTEMS epoch
221
222@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock
223ticks per second
224
225@end itemize
226
227Calendar time operations will return an error code if
228invoked before the date and time have been set.
229
230@section Directives
231
232This section details the clock manager's directives.
233A subsection is dedicated to each of this manager's directives
234and describes the calling sequence, related constants, usage,
235and status codes.
236
237@c
238@c
239@c
240@page
241@subsection CLOCK_SET - Set system date and time
242
243@subheading CALLING SEQUENCE:
244
245@cindex set the time of day
246
247@ifset is-C
248@findex rtems_clock_set
249@example
250rtems_status_code rtems_clock_set(
251  rtems_time_of_day *time_buffer
252);
253@end example
254@end ifset
255
256@ifset is-Ada
257@example
258procedure Clock_Set (
259   Time_Buffer : in     RTEMS.Time_Of_Day;
260   Result      :    out RTEMS.Status_Codes
261);
262@end example
263@end ifset
264
265@subheading DIRECTIVE STATUS CODES:
266@code{@value{RPREFIX}SUCCESSFUL} - date and time set successfully@*
267@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL@*
268@code{@value{RPREFIX}INVALID_TIME_OF_DAY} - invalid time of day
269
270@subheading DESCRIPTION:
271
272This directive sets the system date and time.  The
273date, time, and ticks in the time_buffer @value{STRUCTURE} are all
274range-checked, and an error is returned if any one is out of its
275valid range.
276
277@subheading NOTES:
278
279Years before 1988 are invalid.
280
281The system date and time are based on the configured
282tick rate (number of microseconds in a tick).
283
284Setting the time forward may cause a higher priority
285task, blocked waiting on a specific time, to be made ready.  In
286this case, the calling task will be preempted after the next
287clock tick.
288
289Re-initializing RTEMS causes the system date and time
290to be reset to an uninitialized state.  Another call to
291@code{@value{DIRPREFIX}clock_set} is required to re-initialize
292the system date and time to application specific specifications.
293
294@c
295@c
296@c
297@page
298@subsection CLOCK_GET - Get system date and time information
299
300@cindex obtain the time of day
301
302@subheading CALLING SEQUENCE:
303
304@ifset is-C
305@findex rtems_clock_get
306@example
307rtems_status_code rtems_clock_get(
308  rtems_clock_get_options  option,
309  void                    *time_buffer
310);
311@end example
312@end ifset
313
314@ifset is-Ada
315@example
316procedure Clock_Get (
317   Option      : in     RTEMS.Clock_Get_Options;
318   Time_Buffer : in     RTEMS.Address;
319   Result      :    out RTEMS.Status_Codes
320);
321@end example
322@end ifset
323
324@subheading DIRECTIVE STATUS CODES:
325@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
326@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
327@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
328
329@subheading DESCRIPTION:
330
331This directive obtains the system date and time.  If
332the caller is attempting to obtain the date and time (i.e.
333option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH},
334@code{@value{RPREFIX}CLOCK_GET_TOD}, or
335@code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time
336has not been set with a previous call to
337@code{@value{DIRPREFIX}clock_set}, then the
338@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
339The caller can always obtain the number of ticks per second (option is
340@code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of
341ticks since the executive was initialized option is
342@code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}).
343
344The @code{option} argument may taken on any value of the enumerated
345type @code{rtems_clock_get_options}.  The data type expected for
346@code{time_buffer} is based on the value of @code{option} as
347indicated below:
348
349@findex rtems_clock_get_options
350@ifset is-C
351@itemize @bullet
352@item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *)
353
354@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - (rtems_clock_time_value *)
355
356@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - (rtems_interval *)
357
358@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - (rtems_interval *)
359
360@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - (rtems_interval *)
361
362@end itemize
363@end ifset
364
365@ifset is-Ada
366@itemize @bullet
367@item @code{@value{RPREFIX}CLOCK_GET_TOD} - Address of an variable of
368type RTEMS.Time_Of_Day
369
370@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - Address of an variable of
371type RTEMS.Clock_Time_Value
372
373@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - Address of an
374variable of type RTEMS.Interval
375
376@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - Address of an
377variable of type RTEMS.Interval
378
379@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - Address of an
380variable of type RTEMS.Interval
381
382@end itemize
383@end ifset
384
385@subheading NOTES:
386
387This directive is callable from an ISR.
388
389This directive will not cause the running task to be
390preempted.  Re-initializing RTEMS causes the system date and
391time to be reset to an uninitialized state.  Another call to
392@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
393system date and time to application specific specifications.
394
395@c
396@c
397@c
398@page
399@subsection CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
400
401@cindex clock set nanoseconds extension
402@cindex nanoseconds extension
403@cindex nanoseconds time accuracy
404
405@subheading CALLING SEQUENCE:
406
407@ifset is-C
408@findex rtems_clock_set_nanoseconds_extension
409@example
410rtems_status_code rtems_clock_set_nanoseconds_extension(
411  rtems_nanoseconds_extension_routine routine
412);
413@end example
414@end ifset
415
416@ifset is-Ada
417@example
418NOT SUPPORTED FROM Ada BINDING
419@end example
420@end ifset
421
422@subheading DIRECTIVE STATUS CODES:
423@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
424@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
425
426@subheading DESCRIPTION:
427
428This directive is used by the Clock device driver to install the
429@code{routine} which will be invoked by the internal RTEMS method used to
430obtain a highly accurate time of day.  It is usually called during
431the initialization of the driver.
432
433When the @code{routine} is invoked, it will determine the number of
434nanoseconds which have elapsed since the last invocation of
435the @code{@value{DIRPREFIX}clock_tick} directive.  It should do
436this as quickly as possible with as little impact as possible
437on the device used as a clock source.
438
439@subheading NOTES:
440
441This directive may be called from an ISR.
442
443This directive is called as part of every service to obtain the
444current date and time as well as timestamps.
445
446@c
447@c
448@c
449@page
450@subsection CLOCK_GET_UPTIME - Get the time since booy
451
452@cindex clock get uptime
453@cindex uptime
454
455@subheading CALLING SEQUENCE:
456
457@ifset is-C
458@findex rtems_clock_get_uptime
459@example
460rtems_status_code rtems_clock_get_uptime(
461  struct timespec *uptime
462);
463@end example
464@end ifset
465
466@ifset is-Ada
467@example
468NOT SUPPORTED FROM Ada BINDING
469@end example
470@end ifset
471
472@subheading DIRECTIVE STATUS CODES:
473@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
474@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
475
476@subheading DESCRIPTION:
477
478This directive returns the seconds and nanoseconds since the
479system was booted.  If the BSP supports nanosecond clock
480accuracy, the time reported will probably be different on every
481call.
482
483@subheading NOTES:
484
485This directive may be called from an ISR.
486
487@c
488@c
489@c
490@page
491@subsection CLOCK_TICK - Announce a clock tick
492
493@cindex clock tick
494
495@subheading CALLING SEQUENCE:
496
497@ifset is-C
498@findex rtems_clock_tick
499@example
500rtems_status_code rtems_clock_tick( void );
501@end example
502@end ifset
503
504@ifset is-Ada
505@example
506NOT SUPPORTED FROM Ada BINDING
507@end example
508@end ifset
509
510@subheading DIRECTIVE STATUS CODES:
511@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully
512
513@subheading DESCRIPTION:
514
515This directive announces to RTEMS that a system clock
516tick has occurred.  The directive is usually called from the
517timer interrupt ISR of the local processor.  This directive
518maintains the system date and time, decrements timers for
519delayed tasks, timeouts, rate monotonic periods, and implements
520timeslicing.
521
522@subheading NOTES:
523
524This directive is typically called from an ISR.
525
526The @code{microseconds_per_tick} and @code{ticks_per_timeslice}
527parameters in the Configuration Table contain the number of
528microseconds per tick and number of ticks per timeslice,
529respectively.
530
Note: See TracBrowser for help on using the repository browser.