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

4.115
Last change on this file since f553c6e was f553c6e, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 22, 2014 at 2:39:47 PM

rtems: Inline rtems_clock_get_ticks_since_boot()

Update documentation.

  • 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 current ticks counter value
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 preempted.
573
574@c
575@c
576@c
577@page
578@subsection CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
579
580@cindex obtain ticks since boot
581@cindex get current ticks counter value
582
583@subheading CALLING SEQUENCE:
584
585@ifset is-C
586@findex rtems_clock_get_ticks_since_boot
587@example
588rtems_interval rtems_clock_get_ticks_since_boot(void);
589@end example
590@end ifset
591
592@ifset is-Ada
593@example
594function Clock_Get_Ticks_Since_Boot
595return RTEMS.Interval;
596@end example
597@end ifset
598
599@subheading DIRECTIVE STATUS CODES:
600NONE
601
602@subheading DESCRIPTION:
603
604This directive returns the current tick counter value.  With a 1ms clock tick,
605this counter overflows after 50 days since boot.  This is the historical
606measure of uptime in an RTEMS system.  The newer service
607@code{@value{DIRPREFIX}clock_get_uptime} is another and potentially more
608accurate way of obtaining similar information.
609
610@subheading NOTES:
611
612This directive is callable from an ISR.
613
614This directive will not cause the running task to be preempted.
615
616@c
617@c
618@c
619@page
620@subsection CLOCK_GET_UPTIME - Get the time since boot
621
622@cindex clock get uptime
623@cindex uptime
624
625@subheading CALLING SEQUENCE:
626
627@ifset is-C
628@findex rtems_clock_get_uptime
629@example
630rtems_status_code rtems_clock_get_uptime(
631  struct timespec *uptime
632);
633@end example
634@end ifset
635
636@ifset is-Ada
637@example
638procedure Clock_Get_Uptime (
639   Uptime :    out RTEMS.Timespec;
640   Result :    out RTEMS.Status_Codes
641);
642@end example
643@end ifset
644
645@subheading DIRECTIVE STATUS CODES:
646@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
647@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
648
649@subheading DESCRIPTION:
650
651This directive returns the seconds and nanoseconds since the
652system was booted.  If the BSP supports nanosecond clock
653accuracy, the time reported will probably be different on every
654call.
655
656@subheading NOTES:
657
658This directive may be called from an ISR.
659
660@c
661@c
662@c
663@page
664@subsection CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
665
666@cindex clock get uptime
667@cindex uptime
668
669@subheading CALLING SEQUENCE:
670
671@ifset is-C
672@findex rtems_clock_get_uptime_timeval
673@example
674void rtems_clock_get_uptime_timeval(
675  struct timeval *uptime
676);
677@end example
678@end ifset
679
680@subheading DIRECTIVE STATUS CODES:
681
682NONE
683
684@subheading DESCRIPTION:
685
686This directive returns the seconds and microseconds since the
687system was booted.  If the BSP supports nanosecond clock
688accuracy, the time reported will probably be different on every
689call.
690
691@subheading NOTES:
692
693This directive may be called from an ISR.
694
695@c
696@c
697@c
698@page
699@subsection CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
700
701@cindex clock get uptime
702@cindex uptime
703
704@subheading CALLING SEQUENCE:
705
706@ifset is-C
707@findex rtems_clock_get_uptime_seconds
708@example
709time_t rtems_clock_get_uptime_seconds(void);
710@end example
711@end ifset
712
713@subheading DIRECTIVE STATUS CODES:
714
715The system uptime in seconds.
716
717@subheading DESCRIPTION:
718
719This directive returns the seconds since the system was booted.
720
721@subheading NOTES:
722
723This directive may be called from an ISR.
724
725@c
726@c
727@c
728@page
729@subsection CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
730
731@cindex clock get nanoseconds uptime
732@cindex uptime
733
734@subheading CALLING SEQUENCE:
735
736@ifset is-C
737@findex rtems_clock_get_uptime_nanoseconds
738@example
739uint64_t rtems_clock_get_uptime_nanoseconds(void);
740@end example
741@end ifset
742
743@subheading DIRECTIVE STATUS CODES:
744
745The system uptime in nanoseconds.
746
747@subheading DESCRIPTION:
748
749This directive returns the nanoseconds since the system was booted.
750
751@subheading NOTES:
752
753This directive may be called from an ISR.
754
755@c
756@c
757@c
758@page
759@subsection CLOCK_SET_NANOSECONDS_EXTENSION - Install the nanoseconds since last tick handler
760
761@cindex clock set nanoseconds extension
762@cindex nanoseconds extension
763@cindex nanoseconds time accuracy
764
765@subheading CALLING SEQUENCE:
766
767@ifset is-C
768@findex rtems_clock_set_nanoseconds_extension
769@example
770rtems_status_code rtems_clock_set_nanoseconds_extension(
771  rtems_nanoseconds_extension_routine routine
772);
773@end example
774@end ifset
775
776@ifset is-Ada
777@example
778NOT SUPPORTED FROM Ada BINDING
779@end example
780@end ifset
781
782@subheading DIRECTIVE STATUS CODES:
783@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully@*
784@code{@value{RPREFIX}INVALID_ADDRESS} - @code{time_buffer} is NULL
785
786@subheading DESCRIPTION:
787
788This directive is used by the Clock device driver to install the
789@code{routine} which will be invoked by the internal RTEMS method used to
790obtain a highly accurate time of day.  It is usually called during
791the initialization of the driver.
792
793When the @code{routine} is invoked, it will determine the number of
794nanoseconds which have elapsed since the last invocation of
795the @code{@value{DIRPREFIX}clock_tick} directive.  It should do
796this as quickly as possible with as little impact as possible
797on the device used as a clock source.
798
799@subheading NOTES:
800
801This directive may be called from an ISR.
802
803This directive is called as part of every service to obtain the
804current date and time as well as timestamps.
805
806@c
807@c
808@c
809@page
810@subsection CLOCK_TICK - Announce a clock tick
811
812@cindex clock tick
813
814@subheading CALLING SEQUENCE:
815
816@ifset is-C
817@findex rtems_clock_tick
818@example
819rtems_status_code rtems_clock_tick( void );
820@end example
821@end ifset
822
823@ifset is-Ada
824@example
825procedure Clock_Tick (
826   Result :    out RTEMS.Status_Codes
827);
828@end example
829@end ifset
830
831@subheading DIRECTIVE STATUS CODES:
832@code{@value{RPREFIX}SUCCESSFUL} - clock tick processed successfully
833
834@subheading DESCRIPTION:
835
836This directive announces to RTEMS that a system clock
837tick has occurred.  The directive is usually called from the
838timer interrupt ISR of the local processor.  This directive
839maintains the system date and time, decrements timers for
840delayed tasks, timeouts, rate monotonic periods, and implements
841timeslicing.
842
843@subheading NOTES:
844
845This directive is typically called from an ISR.
846
847The @code{microseconds_per_tick} and @code{ticks_per_timeslice}
848parameters in the Configuration Table contain the number of
849microseconds per tick and number of ticks per timeslice,
850respectively.
Note: See TracBrowser for help on using the repository browser.