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.