1  .TH rtapi_get_time "3rtapi" "2006-10-12" "LinuxCNC Documentation" "HAL"
 2  .SH NAME
 3  
 4  rtapi_get_time \- get the current time
 5  
 6  .SH SYNTAX
 7  .HP
 8  long long rtapi_get_time()
 9  .HP
10  long long rtapi_get_clocks()
11  
12  .SH DESCRIPTION
13  \fBrtapi_get_time\fR returns the current time in nanoseconds.  Depending on the
14  RTOS, this may be time since boot, or time since the clock period was set, or
15  some other time.  Its absolute value means nothing, but it is monotonically
16  increasing and can be used to schedule future events, or to time the duration
17  of some activity.  Returns a 64 bit value.  The resolution of the returned
18  value may be as good as one nano-second, or as poor as several microseconds.
19  May be called from init/cleanup code, and from within realtime tasks.  
20  
21  \fBrtapi_get_clocks\fR returns the current time in CPU clocks.  It is 
22  fast, since it just reads the TSC in the CPU instead of calling a
23  kernel or RTOS function.  Of course, times measured in CPU clocks
24  are not as convenient, but for relative measurements this works
25  fine.  Its absolute value means nothing, but it is monotonically
26  increasing and can be used to schedule future events, or to time
27  the duration of some activity.  (on SMP machines, the two TSC's
28  may get out of sync, so if a task reads the TSC, gets swapped to
29  the other CPU, and reads again, the value may decrease.  RTAPI
30  tries to force all RT tasks to run on one CPU.)
31  Returns a 64 bit value.  The resolution of the returned value is
32  one CPU clock, which is usually a few nanoseconds to a fraction of
33  a nanosecond. 
34      
35  Note that \fIlong long\fR math may be poorly supported on some platforms,
36  especially in kernel space. Also note that rtapi_print() will NOT
37  print \fIlong long\fRs.  Most time measurements are relative, and should
38  be done like this:
39  .RS
40  deltat = (long int)(end_time \- start_time);
41  .RE
42  where end_time and start_time are longlong values returned from rtapi_get_time,
43  and deltat is an ordinary long int (32 bits).  This will work for times up to a
44  second or so, depending on the CPU clock frequency.  It is best used for
45  millisecond and microsecond scale measurements though.
46  
47  .SH RETURN VALUE
48  Returns the current time in nanoseconds or CPU clocks.
49  .SH NOTES
50  Certain versions of the Linux kernel provide a global variable \fBcpu_khz\fR.
51  Computing 
52  .RS
53  	deltat = (end_clocks \- start_clocks) / cpu_khz:
54  .RE
55  gives the duration measured in milliseconds.  Computing
56  .RS
57  	deltat = (end_clocks \- start_clocks) * 1000000 / cpu_khz:
58  .RE
59  gives the duration measured in nanoseconds for deltas less than about 9
60  trillion clocks (e.g., 3000 seconds at 3GHz).
61  
62  .SH REALTIME CONSIDERATIONS
63  May be called from init/cleanup code and from within realtime tasks.
64  Not available in userspace components.