source: rtems/doc/user/clock.t @ 90733a86

4.115
Last change on this file since 90733a86 was 90733a86, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 16, 2012 at 1:14:03 PM

rtems: Add rtems_clock_get_uptime_seconds()

  • Property mode set to 100644
File size: 23.4 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5
6@chapter Clock Manager
7
8@cindex clock
9
10@section Introduction
11
12The clock manager provides support for time of day
13and other time related capabilities.  The directives provided by
14the clock manager are:
15
16@itemize @bullet
17@item @code{@value{DIRPREFIX}clock_set} - Set date and time
18@item @code{@value{DIRPREFIX}clock_get} - Get date and time information
19@item @code{@value{DIRPREFIX}clock_get_tod} - Get date and time in TOD format
20@item @code{@value{DIRPREFIX}clock_get_tod_timeval} - Get date and time in timeval format
21@item @code{@value{DIRPREFIX}clock_get_seconds_since_epoch} - Get seconds since epoch
22@item @code{@value{DIRPREFIX}clock_get_ticks_per_second} - Get ticks per second
23@item @code{@value{DIRPREFIX}clock_get_ticks_since_boot} - Get ticks since boot
24@item @code{@value{DIRPREFIX}clock_get_uptime} - Get time since boot
25@item @code{@value{DIRPREFIX}clock_get_uptime_timeval} - Get time since boot in timeval format
26@item @code{@value{DIRPREFIX}clock_get_uptime_seconds} - Get seconds since boot
27@item @code{@value{DIRPREFIX}clock_set_nanoseconds_extension} - Install the nanoseconds since last tick handler
28@item @code{@value{DIRPREFIX}clock_tick} - Announce a clock tick
29@end itemize
30
31@section Background
32
33@subsection Required Support
34
35For the features provided by the clock manager to be
36utilized, periodic timer interrupts are required.  Therefore, a
37real-time clock or hardware timer is necessary to create the
38timer interrupts.  The @code{@value{DIRPREFIX}clock_tick}
39directive is normally called
40by the timer ISR to announce to RTEMS that a system clock tick
41has occurred.  Elapsed time is measured in ticks.  A tick is
42defined to be an integral number of microseconds which is
43specified by the user in the Configuration Table.
44
45@subsection Time and Date Data Structures
46
47The clock facilities of the clock manager operate
48upon calendar time.  These directives utilize the following date
49and time @value{STRUCTURE} for the native time and date format:
50
51
52@ifset is-C
53@findex rtems_time_of_day
54@example
55struct rtems_tod_control @{
56  uint32_t year;   /* greater than 1987 */
57  uint32_t month;  /* 1 - 12 */
58  uint32_t day;    /* 1 - 31 */
59  uint32_t hour;   /* 0 - 23 */
60  uint32_t minute; /* 0 - 59 */
61  uint32_t second; /* 0 - 59 */
62  uint32_t ticks;  /* elapsed between seconds */
63@};
64
65typedef struct rtems_tod_control rtems_time_of_day;
66@end example
67@end ifset
68
69@ifset is-Ada
70@example
71type Time_Of_Day is
72   record
73      Year    : RTEMS.Unsigned32; -- year, A.D.
74      Month   : RTEMS.Unsigned32; -- month, 1 .. 12
75      Day     : RTEMS.Unsigned32; -- day, 1 .. 31
76      Hour    : RTEMS.Unsigned32; -- hour, 0 .. 23
77      Minute  : RTEMS.Unsigned32; -- minute, 0 .. 59
78      Second  : RTEMS.Unsigned32; -- second, 0 .. 59
79      Ticks   : RTEMS.Unsigned32; -- elapsed ticks between seconds
80   end record;
81@end example
82@end ifset
83
84
85The native date and time format is the only format
86supported when setting the system date and time using the
87@code{@value{DIRPREFIX}clock_set} directive.  Some applications
88expect to operate on a "UNIX-style" date and time data structure.  The
89@code{@value{DIRPREFIX}clock_get_tod_timeval} always returns
90the date and time in @code{struct timeval} format.  The
91@code{@value{DIRPREFIX}clock_get} directive can optionally return
92the current date and time in this format. 
93
94The @code{struct timeval} data structure has two fields: @code{tv_sec}
95and @code{tv_usec} which are seconds and microseconds, respectively.
96The @code{tv_sec} field in this data structure is the number of seconds
97since the POSIX epoch of January 1, 1970 but will never be prior to
98the RTEMS epoch of January 1, 1988.
99
100@subsection Clock Tick and Timeslicing
101
102@cindex timeslicing
103
104Timeslicing is a task scheduling discipline in which
105tasks of equal priority are executed for a specific period of
106time before control of the CPU is passed to another task.  It is
107also sometimes referred to as the automatic round-robin
108scheduling algorithm.  The length of time allocated to each task
109is known as the quantum or timeslice.
110
111The system's timeslice is defined as an integral
112number of ticks, and is specified in the Configuration Table.
113The timeslice is defined for the entire system of tasks, but
114timeslicing is enabled and disabled on a per task basis.
115
116The @code{@value{DIRPREFIX}clock_tick}
117directive implements timeslicing by
118decrementing the running task's time-remaining counter when both
119timeslicing and preemption are enabled.  If the task's timeslice
120has expired, then that task will be preempted if there exists a
121ready task of equal priority.
122
123@subsection Delays
124
125@cindex delays
126
127A sleep timer allows a task to delay for a given
128interval or up until a given time, and then wake and continue
129execution.  This type of timer is created automatically by the
130@code{@value{DIRPREFIX}task_wake_after}
131and @code{@value{DIRPREFIX}task_wake_when} directives and, as a result,
132does not have an RTEMS ID.  Once activated, a sleep timer cannot
133be explicitly deleted.  Each task may activate one and only one
134sleep timer at a time.
135
136@subsection Timeouts
137
138@cindex timeouts
139
140Timeouts are a special type of timer automatically
141created when the timeout option is used on the
142@code{@value{DIRPREFIX}message_queue_receive},
143@code{@value{DIRPREFIX}event_receive},
144@code{@value{DIRPREFIX}semaphore_obtain} and
145@code{@value{DIRPREFIX}region_get_segment} directives. 
146Each task may have one and only one timeout active at a time. 
147When a timeout expires, it unblocks the task with a timeout status code.
148
149@section Operations
150
151@subsection Announcing a Tick
152
153RTEMS provides the @code{@value{DIRPREFIX}clock_tick} directive which is
154called from the user's real-time clock ISR to inform RTEMS that
155a tick has elapsed.  The tick frequency value, defined in
156microseconds, is a configuration parameter found in the
157Configuration Table.  RTEMS divides one million microseconds
158(one second) by the number of microseconds per tick to determine
159the number of calls to the
160@code{@value{DIRPREFIX}clock_tick} directive per second.  The
161frequency of @code{@value{DIRPREFIX}clock_tick}
162calls determines the resolution
163(granularity) for all time dependent RTEMS actions.  For
164example, calling @code{@value{DIRPREFIX}clock_tick}
165ten times per second yields a higher
166resolution than calling @code{@value{DIRPREFIX}clock_tick}
167two times per second.  The @code{@value{DIRPREFIX}clock_tick}
168directive is responsible for maintaining both
169calendar time and the dynamic set of timers.
170
171@subsection Setting the Time
172
173The @code{@value{DIRPREFIX}clock_set} directive allows a task or an ISR to
174set the date and time maintained by RTEMS.  If setting the date
175and time causes any outstanding timers to pass their deadline,
176then the expired timers will be fired during the invocation of
177the @code{@value{DIRPREFIX}clock_set} directive.
178
179@subsection Obtaining the Time
180
181The @code{@value{DIRPREFIX}clock_get} directive allows a task or an ISR to
182obtain the current date and time or date and time related
183information.  The current date and time can be returned in
184either native or UNIX-style format.  Additionally, the
185application can obtain date and time related information such as
186the number of seconds since the RTEMS epoch, the number of ticks
187since the executive was initialized, and the number of ticks per
188second.  The information returned by the
189@code{@value{DIRPREFIX}clock_get} directive is
190dependent on the option selected by the caller.  This
191is specified using one of the following constants
192associated with the enumerated type
193@code{@value{DIRPREFIX}clock_get_options}:
194
195@findex rtems_clock_get_options
196
197@itemize @bullet
198@item @code{@value{RPREFIX}CLOCK_GET_TOD} - obtain native style date and time
199
200@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - obtain UNIX-style
201date and time
202
203@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - obtain number of ticks
204since RTEMS was initialized
205
206@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - obtain number
207of seconds since RTEMS epoch
208
209@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - obtain number of clock
210ticks per second
211
212@end itemize
213
214Calendar time operations will return an error code if
215invoked before the date and time have been set.
216
217@section Directives
218
219This section details the clock manager's directives.
220A subsection is dedicated to each of this manager's directives
221and describes the calling sequence, related constants, usage,
222and status codes.
223
224@c
225@c
226@c
227@page
228@subsection CLOCK_SET - Set date and time
229
230@subheading CALLING SEQUENCE:
231
232@cindex set the time of day
233
234@ifset is-C
235@findex rtems_clock_set
236@example
237rtems_status_code rtems_clock_set(
238  rtems_time_of_day *time_buffer
239);
240@end example
241@end ifset
242
243@ifset is-Ada
244@example
245procedure Clock_Set (
246   Time_Buffer : in     RTEMS.Time_Of_Day;
247   Result      :    out RTEMS.Status_Codes
248);
249@end example
250@end ifset
251
252@subheading DIRECTIVE STATUS CODES:
253@code{@value{RPREFIX}SUCCESSFUL} - date and time set successfully@*
254@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL@*
255@code{@value{RPREFIX}INVALID_CLOCK} - invalid time of day
256
257@subheading DESCRIPTION:
258
259This directive sets the system date and time.  The
260date, time, and ticks in the time_buffer @value{STRUCTURE} are all
261range-checked, and an error is returned if any one is out of its
262valid range.
263
264@subheading NOTES:
265
266Years before 1988 are invalid.
267
268The system date and time are based on the configured
269tick rate (number of microseconds in a tick).
270
271Setting the time forward may cause a higher priority
272task, blocked waiting on a specific time, to be made ready.  In
273this case, the calling task will be preempted after the next
274clock tick.
275
276Re-initializing RTEMS causes the system date and time
277to be reset to an uninitialized state.  Another call to
278@code{@value{DIRPREFIX}clock_set} is required to re-initialize
279the system date and time to application specific specifications.
280
281@c
282@c
283@c
284@page
285@subsection CLOCK_GET - Get date and time information
286
287@cindex obtain the time of day
288
289@subheading CALLING SEQUENCE:
290
291@ifset is-C
292@findex rtems_clock_get
293@example
294rtems_status_code rtems_clock_get(
295  rtems_clock_get_options  option,
296  void                    *time_buffer
297);
298@end example
299@end ifset
300
301@ifset is-Ada
302@example
303procedure Clock_Get (
304   Option      : in     RTEMS.Clock_Get_Options;
305   Time_Buffer : in     RTEMS.Address;
306   Result      :    out RTEMS.Status_Codes
307);
308@end example
309@end ifset
310
311@subheading DIRECTIVE STATUS CODES:
312@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
313@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
314@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
315
316@subheading DESCRIPTION:
317
318This directive obtains the system date and time.  If
319the caller is attempting to obtain the date and time (i.e.
320option is set to either @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH},
321@code{@value{RPREFIX}CLOCK_GET_TOD}, or
322@code{@value{RPREFIX}CLOCK_GET_TIME_VALUE}) and the date and time
323has not been set with a previous call to
324@code{@value{DIRPREFIX}clock_set}, then the
325@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
326The caller can always obtain the number of ticks per second (option is
327@code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND}) and the number of
328ticks since the executive was initialized option is
329@code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT}).
330
331The @code{option} argument may taken on any value of the enumerated
332type @code{rtems_clock_get_options}.  The data type expected for
333@code{time_buffer} is based on the value of @code{option} as
334indicated below:
335
336@findex rtems_clock_get_options
337@ifset is-C
338@itemize @bullet
339@item @code{@value{RPREFIX}CLOCK_GET_TOD} - (rtems_time_of_day *)
340
341@item @code{@value{RPREFIX}CLOCK_GET_SECONDS_SINCE_EPOCH} - (rtems_interval *)
342
343@item @code{@value{RPREFIX}CLOCK_GET_TICKS_SINCE_BOOT} - (rtems_interval *)
344
345@item @code{@value{RPREFIX}CLOCK_GET_TICKS_PER_SECOND} - (rtems_interval *)
346
347@item @code{@value{RPREFIX}CLOCK_GET_TIME_VALUE} - (struct timeval *)
348
349@end itemize
350@end ifset
351
352@ifset is-Ada
353@itemize @bullet
354@item @code{@value{RPREFIX}Clock_Get_TOD} - Address of an variable of
355type RTEMS.Time_Of_Day
356
357@item @code{@value{RPREFIX}Clock_Get_Seconds_Since_Epoch} - Address of an
358variable of type RTEMS.Interval
359
360@item @code{@value{RPREFIX}Clock_Get_Ticks_Since_Boot} - Address of an
361variable of type RTEMS.Interval
362
363@item @code{@value{RPREFIX}Clock_Get_Ticks_Per_Second} - Address of an
364variable of type RTEMS.Interval
365
366@item @code{@value{RPREFIX}Clock_Get_Time_Value} - Address of an variable of
367type RTEMS.Clock_Time_Value
368
369@end itemize
370@end ifset
371
372@subheading NOTES:
373
374This directive is callable from an ISR.
375
376This directive will not cause the running task to be
377preempted.  Re-initializing RTEMS causes the system date and
378time to be reset to an uninitialized state.  Another call to
379@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
380system date and time to application specific specifications.
381
382@c
383@c
384@c
385@page
386@subsection CLOCK_GET_TOD - Get date and time in TOD format
387
388@cindex obtain the time of day
389
390@subheading CALLING SEQUENCE:
391
392@ifset is-C
393@findex rtems_clock_get_tod
394@example
395rtems_status_code rtems_clock_get_tod(
396  rtems_time_of_day *time_buffer
397);
398@end example
399@end ifset
400
401@ifset is-Ada
402@example
403procedure Clock_Get_TOD (
404   Time_Buffer : in     RTEMS.Time_Of_Day;
405   Result      :    out RTEMS.Status_Codes
406);
407@end example
408@end ifset
409
410@subheading DIRECTIVE STATUS CODES:
411@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
412@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
413@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
414
415@subheading DESCRIPTION:
416
417This directive obtains the system date and time.  If the date and time
418has not been set with a previous call to
419@code{@value{DIRPREFIX}clock_set}, then the
420@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
421
422@subheading NOTES:
423
424This directive is callable from an ISR.
425
426This directive will not cause the running task to be
427preempted.  Re-initializing RTEMS causes the system date and
428time to be reset to an uninitialized state.  Another call to
429@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
430system date and time to application specific specifications.
431
432@c
433@c
434@c
435@page
436@subsection CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
437
438@cindex obtain the time of day
439
440@subheading CALLING SEQUENCE:
441
442@ifset is-C
443@findex rtems_clock_get_tod_timeval
444@example
445rtems_status_code rtems_clock_get_tod(
446  struct timeval  *time
447);
448@end example
449@end ifset
450
451@ifset is-Ada
452@example
453procedure Clock_Get_TOD_Timeval (
454   Time   : in     RTEMS.Timeval;
455   Result :    out RTEMS.Status_Codes
456);
457@end example
458@end ifset
459
460@subheading DIRECTIVE STATUS CODES:
461@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
462@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
463@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time} is NULL
464
465@subheading DESCRIPTION:
466
467This directive obtains the system date and time in POSIX
468@code{struct timeval} format.  If the date and time
469has not been set with a previous call to
470@code{@value{DIRPREFIX}clock_set}, then the
471@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
472
473@subheading NOTES:
474
475This directive is callable from an ISR.
476
477This directive will not cause the running task to be
478preempted.  Re-initializing RTEMS causes the system date and
479time to be reset to an uninitialized state.  Another call to
480@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
481system date and time to application specific specifications.
482
483@c
484@c
485@c
486@page
487@subsection CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
488
489@cindex obtain seconds since epoch
490
491@subheading CALLING SEQUENCE:
492
493@ifset is-C
494@findex rtems_clock_get_seconds_since_epoch
495@example
496rtems_status_code rtems_clock_get_seconds_since_epoch(
497  rtems_interval *the_interval
498);
499@end example
500@end ifset
501
502@ifset is-Ada
503@example
504procedure Clock_Get_Seconds_Since_Epoch(
505   The_Interval :    out RTEMS.Interval;
506   Result       :    out RTEMS.Status_Codes
507);
508@end example
509@end ifset
510
511@subheading DIRECTIVE STATUS CODES:
512@code{@value{RPREFIX}SUCCESSFUL} - current time obtained successfully@*
513@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set@*
514@code{@value{RPREFIX}INVALID_ADDRESS} - @code{the_interval} is NULL
515
516@subheading DESCRIPTION:
517
518This directive returns the number of seconds since the RTEMS
519epoch and the current system date and time.  If the date and time
520has not been set with a previous call to
521@code{@value{DIRPREFIX}clock_set}, then the
522@code{@value{RPREFIX}NOT_DEFINED} status code is returned.
523
524@subheading NOTES:
525
526This directive is callable from an ISR.
527
528This directive will not cause the running task to be
529preempted.  Re-initializing RTEMS causes the system date and
530time to be reset to an uninitialized state.  Another call to
531@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
532system date and time to application specific specifications.
533
534@c
535@c
536@c
537@page
538@subsection CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
539
540@cindex obtain seconds since epoch
541
542@subheading CALLING SEQUENCE:
543
544@ifset is-C
545@findex rtems_clock_get_ticks_per_second
546@example
547rtems_interval rtems_clock_get_ticks_per_second(void);
548@end example
549@end ifset
550
551@ifset is-Ada
552@example
553function Clock_Get_Ticks_Per_Seconds
554return RTEMS.Interval;
555@end example
556@end ifset
557
558@subheading DIRECTIVE STATUS CODES:
559NONE
560
561@subheading DESCRIPTION:
562
563This directive returns the number of clock ticks per second.  This
564is strictly based upon the microseconds per clock tick that the
565application has configured.
566
567@subheading NOTES:
568
569This directive is callable from an ISR.
570
571This directive will not cause the running task to be
572preempted.  Re-initializing RTEMS causes the system date and
573time to be reset to an uninitialized state.  Another call to
574@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
575system date and time to application specific specifications.
576
577@c
578@c
579@c
580@page
581@subsection CLOCK_GET_TICKS_SINCE_BOOT - Get ticks since boot
582
583@cindex obtain ticks since boot
584
585@subheading CALLING SEQUENCE:
586
587@ifset is-C
588@findex rtems_clock_get_ticks_since_boot
589@example
590rtems_interval rtems_clock_get_ticks_since_boot(void);
591@end example
592@end ifset
593
594@ifset is-Ada
595@example
596function Clock_Get_Ticks_Since_Boot
597return RTEMS.Interval;
598@end example
599@end ifset
600
601@subheading DIRECTIVE STATUS CODES:
602NONE
603
604@subheading DESCRIPTION:
605
606This directive returns the number of clock ticks that have elapsed
607since the system was booted.  This is the historical measure of uptime
608in an RTEMS system.  The newer service
609@code{@value{DIRPREFIX}clock_get_uptime} is another and potentially
610more accurate way of obtaining similar information.
611
612@subheading NOTES:
613
614This directive is callable from an ISR.
615
616This directive will not cause the running task to be
617preempted.  Re-initializing RTEMS causes the system date and
618time to be reset to an uninitialized state.  Another call to
619@code{@value{DIRPREFIX}clock_set} is required to re-initialize the
620system date and time to application specific specifications.
621
622This directive simply returns the number of times the dirivective
623@code{@value{DIRPREFIX}clock_tick} has been invoked since the
624system was booted.
625
626@c
627@c
628@c
629@page
630@subsection CLOCK_GET_UPTIME - Get the time since boot
631
632@cindex clock get uptime
633@cindex uptime
634
635@subheading CALLING SEQUENCE:
636
637@ifset is-C
638@findex rtems_clock_get_uptime
639@example
640rtems_status_code rtems_clock_get_uptime(
641  struct timespec *uptime
642);
643@end example
644@end ifset
645
646@ifset is-Ada
647@example
648procedure Clock_Get_Uptime (
649   Uptime :    out RTEMS.Timespec;
650   Result :    out RTEMS.Status_Codes
651);
652@end example
653@end ifset
654
655@subheading DIRECTIVE STATUS CODES:
656@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
657@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
658
659@subheading DESCRIPTION:
660
661This directive returns the seconds and nanoseconds since the
662system was booted.  If the BSP supports nanosecond clock
663accuracy, the time reported will probably be different on every
664call.
665
666@subheading NOTES:
667
668This directive may be called from an ISR.
669
670@c
671@c
672@c
673@page
674@subsection CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
675
676@cindex clock get uptime
677@cindex uptime
678
679@subheading CALLING SEQUENCE:
680
681@ifset is-C
682@findex rtems_clock_get_uptime_timeval
683@example
684void rtems_clock_get_uptime_timeval(
685  struct timeval *uptime
686);
687@end example
688@end ifset
689
690@subheading DIRECTIVE STATUS CODES:
691
692NONE
693
694@subheading DESCRIPTION:
695
696This directive returns the seconds and microseconds since the
697system was booted.  If the BSP supports nanosecond clock
698accuracy, the time reported will probably be different on every
699call.
700
701@subheading NOTES:
702
703This directive may be called from an ISR.
704
705@c
706@c
707@c
708@page
709@subsection CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
710
711@cindex clock get uptime
712@cindex uptime
713
714@subheading CALLING SEQUENCE:
715
716@ifset is-C
717@findex rtems_clock_get_uptime_seconds
718@example
719time_t rtems_clock_get_uptime_seconds(void);
720@end example
721@end ifset
722
723@subheading DIRECTIVE STATUS CODES:
724
725The system uptime in seconds.
726
727@subheading DESCRIPTION:
728
729This directive returns the seconds since the system was booted.
730
731@subheading NOTES:
732
733This directive may be called from an ISR.
734
735@c
736@c
737@c
738@page
739@subsection CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
740
741@cindex clock set nanoseconds extension
742@cindex nanoseconds extension
743@cindex nanoseconds time accuracy
744
745@subheading CALLING SEQUENCE:
746
747@ifset is-C
748@findex rtems_clock_set_nanoseconds_extension
749@example
750rtems_status_code rtems_clock_set_nanoseconds_extension(
751  rtems_nanoseconds_extension_routine routine
752);
753@end example
754@end ifset
755
756@ifset is-Ada
757@example
758NOT SUPPORTED FROM Ada BINDING
759@end example
760@end ifset
761
762@subheading DIRECTIVE STATUS CODES:
763@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
764@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
765
766@subheading DESCRIPTION:
767
768This directive is used by the Clock device driver to install the
769@code{routine} which will be invoked by the internal RTEMS method used to
770obtain a highly accurate time of day.  It is usually called during
771the initialization of the driver.
772
773When the @code{routine} is invoked, it will determine the number of
774nanoseconds which have elapsed since the last invocation of
775the @code{@value{DIRPREFIX}clock_tick} directive.  It should do
776this as quickly as possible with as little impact as possible
777on the device used as a clock source.
778
779@subheading NOTES:
780
781This directive may be called from an ISR.
782
783This directive is called as part of every service to obtain the
784current date and time as well as timestamps.
785
786@c
787@c
788@c
789@page
790@subsection CLOCK_TICK - Announce a clock tick
791
792@cindex clock tick
793
794@subheading CALLING SEQUENCE:
795
796@ifset is-C
797@findex rtems_clock_tick
798@example
799rtems_status_code rtems_clock_tick( void );
800@end example
801@end ifset
802
803@ifset is-Ada
804@example
805procedure Clock_Tick (
806   Result :    out RTEMS.Status_Codes
807);
808@end example
809@end ifset
810
811@subheading DIRECTIVE STATUS CODES:
812@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully
813
814@subheading DESCRIPTION:
815
816This directive announces to RTEMS that a system clock
817tick has occurred.  The directive is usually called from the
818timer interrupt ISR of the local processor.  This directive
819maintains the system date and time, decrements timers for
820delayed tasks, timeouts, rate monotonic periods, and implements
821timeslicing.
822
823@subheading NOTES:
824
825This directive is typically called from an ISR.
826
827The @code{microseconds_per_tick} and @code{ticks_per_timeslice}
828parameters in the Configuration Table contain the number of
829microseconds per tick and number of ticks per timeslice,
830respectively.
831
Note: See TracBrowser for help on using the repository browser.