64 lines
2.7 KiB
Text
64 lines
2.7 KiB
Text
.TH rtapi_get_time "3rtapi" "2006-10-12" "LinuxCNC Documentation" "HAL"
|
|
.SH NAME
|
|
|
|
rtapi_get_time \- get the current time
|
|
|
|
.SH SYNTAX
|
|
.HP
|
|
long long rtapi_get_time()
|
|
.HP
|
|
long long rtapi_get_clocks()
|
|
|
|
.SH DESCRIPTION
|
|
\fBrtapi_get_time\fR returns the current time in nanoseconds. Depending on the
|
|
RTOS, this may be time since boot, or time since the clock period was set, or
|
|
some other time. Its absolute value means nothing, but it is monotonically
|
|
increasing and can be used to schedule future events, or to time the duration
|
|
of some activity. Returns a 64 bit value. The resolution of the returned
|
|
value may be as good as one nano-second, or as poor as several microseconds.
|
|
May be called from init/cleanup code, and from within realtime tasks.
|
|
|
|
\fBrtapi_get_clocks\fR returns the current time in CPU clocks. It is
|
|
fast, since it just reads the TSC in the CPU instead of calling a
|
|
kernel or RTOS function. Of course, times measured in CPU clocks
|
|
are not as convenient, but for relative measurements this works
|
|
fine. Its absolute value means nothing, but it is monotonically
|
|
increasing and can be used to schedule future events, or to time
|
|
the duration of some activity. (on SMP machines, the two TSC's
|
|
may get out of sync, so if a task reads the TSC, gets swapped to
|
|
the other CPU, and reads again, the value may decrease. RTAPI
|
|
tries to force all RT tasks to run on one CPU.)
|
|
Returns a 64 bit value. The resolution of the returned value is
|
|
one CPU clock, which is usually a few nanoseconds to a fraction of
|
|
a nanosecond.
|
|
|
|
Note that \fIlong long\fR math may be poorly supported on some platforms,
|
|
especially in kernel space. Also note that rtapi_print() will NOT
|
|
print \fIlong long\fRs. Most time measurements are relative, and should
|
|
be done like this:
|
|
.RS
|
|
deltat = (long int)(end_time - start_time);
|
|
.RE
|
|
where end_time and start_time are longlong values returned from rtapi_get_time,
|
|
and deltat is an ordinary long int (32 bits). This will work for times up to a
|
|
second or so, depending on the CPU clock frequency. It is best used for
|
|
millisecond and microsecond scale measurements though.
|
|
|
|
.SH RETURN VALUE
|
|
Returns the current time in nanoseconds or CPU clocks.
|
|
.SH NOTES
|
|
Certain versions of the Linux kernel provide a global variable \fBcpu_khz\fR.
|
|
Computing
|
|
.RS
|
|
deltat = (end_clocks - start_clocks) / cpu_khz:
|
|
.RE
|
|
gives the duration measured in milliseconds. Computing
|
|
.RS
|
|
deltat = (end_clocks - start_clocks) * 1000000 / cpu_khz:
|
|
.RE
|
|
gives the duration measured in nanoseconds for deltas less than about 9
|
|
trillion clocks (e.g., 3000 seconds at 3GHz).
|
|
|
|
.SH REALTIME CONSIDERATIONS
|
|
May be called from init/cleanup code and from within realtime tasks.
|
|
Not available in userspace components.
|