source: rtems/doc/user/clock.t @ 96ec8ee8

4.115
Last change on this file since 96ec8ee8 was 96ec8ee8, checked in by Sebastian Huber <sebastian.huber@…>, on 08/22/14 at 15:09:36

rtems: Add more clock tick functions

Add rtems_clock_tick_later(), rtems_clock_tick_later_usec() and
rtems_clock_tick_before().

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