source: rtems/doc/user/clock.t @ 2d1bdc8

4.115
Last change on this file since 2d1bdc8 was 2d1bdc8, checked in by Chris Johns <chrisj@…>, on Dec 24, 2013 at 5:38:42 AM

cpukit/rtems: Add rtems_clock_get_uptime_nanoseconds to the RTEMS API.

Add Timestamp support in the score to return a timestamp in nanoseconds.
Add a test.
Update the RTEMS API documentation.

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