NAME

       rtapi_get_time - get the current time

SYNTAX

       long long rtapi_get_time()

       long long rtapi_get_clocks()

DESCRIPTION

       rtapi_get_time  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.

       rtapi_get_clocks  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 long long math may be poorly supported on some platforms, especially in kernel space. Also note
       that rtapi_print() will NOT print long longs.  Most time measurements are relative, and  should  be  done
       like this:
              deltat = (long int)(end_time - start_time);
       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.

RETURN VALUE

       Returns the current time in nanoseconds or CPU clocks.

NOTES

       Certain versions of the Linux kernel provide a global variable cpu_khz.  Computing
                   deltat = (end_clocks - start_clocks) / cpu_khz:
       gives the duration measured in milliseconds.  Computing
                   deltat = (end_clocks - start_clocks) * 1000000 / cpu_khz:
       gives  the  duration  measured  in  nanoseconds  for deltas less than about 9 trillion clocks (e.g., 3000
       seconds at 3 GHz).

REALTIME CONSIDERATIONS

       May be called from init/cleanup code and from within  realtime  tasks.   Not  available  in  non-realtime
       components.

LinuxCNC Documentation                             2006-10-12                             rtapi_get_time(3rtapi)