osapi_time.h

Go to the documentation of this file.

/*
 * FILE: osapi_time.h - Definition of Time API
 *
 * Copyright 2005-2015 Real-Time Innovations, Inc.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 *
 * Modification History
 * --------------------
 * 16mar2015,tk  MICRO-1084 Changed comment for to/from_ntp_time to state
 *                          resolution is at least 1ns.
 * 20mar2013,tk  Updated
 * 06dec2005,rh  Created
 */
/*e \file
 * \brief Time API definition
 */
#ifndef osapi_time_h
#define osapi_time_h

#include "osapi/osapi_dll.h"
#ifndef osapi_types_h
#include "osapi/osapi_types.h"
#endif

#ifdef __cplusplus
extern "C"
{
#endif

/*e \defgroup OSAPITimeClass OSAPI Time
 *  \ingroup OSAPIModule
*/

/*e \ingroup OSAPITimeClass

    \brief NtpTime API.
*/

/* ================================================================= */
/*                           Definition: Time                        */
/* ----------------------------------------------------------------- */

/*e \ingroup OSAPITimeClass

  @brief NTP Time representation.

  Expresses time in NTP format. The second field is simply an integer
  expressing seconds. The fraction field expresses 1/2^32 of a second.
  We strongly urge customers to use our provided macros to convert this
  format to and from human readable form.

  OSAPI_NtpTime_init must be called before OSAPI_NtpTime_get. Creating a domain
  has the side-effect of calling OSAPI_NtpTime_init.

  \b Example:

  The following is a simple example on how to prepare a struct OSAPI_NtpTime structure
  to be 1.5 seconds.

  \verbatim
     struct OSAPI_NtpTime ntpTime;

     OSAPI_NtpTime_packFromMillisec(ntpTime, 1, 500);
  \endverbatim

  @see OSAPI_NtpTime_packFromMillisec OSAPI_NtpTime_packFromMicrosec
  @see OSAPI_NtpTime_packFromNanosec
  @see OSAPI_NtpTime_unpackFromMillisec OSAPI_NtpTime_unpackFromMicrosec
  @see OSAPI_NtpTime_unpackFromNanosec
 */
typedef struct OSAPI_NtpTime
{
    /* e Seconds.* */
    RTI_INT32 sec;
    /* e fraction of a second in 1/2^32 form. */
    RTI_UINT32 frac;
} OSAPI_NtpTime;

/*e \ingroup OSAPITimeClass
   The maximum number of seconds that can be represented using NTP time.
 */
#define OSAPI_NTP_TIME_SEC_MAX ((RTI_INT32)0x7fffffff)

/*e \ingroup OSAPITimeClass
   The largest possible value of the fraction field in NTP time.
 */
#define OSAPI_NTP_TIME_FRAC_MAX ((RTI_UINT32)0xffffffff)


/*e \ingroup OSAPITimeClass

  @brief Macro to convert from seconds and milliseconds to struct OSAPI_NtpTime format.

  @param time (struct OSAPI_NtpTime) contains the answer.
  @param s  (integer) Seconds to convert.
  @param msec (millisecond) Fraction portion (less than 1000).

  \verbatim
    struct OSAPI_NtpTime time;
    long sec, msec;
    sec = 10;
    msec = 577;

    OSAPI_NtpTime_packFromMillisec(time, sec, msec);
  \endverbatim

  After the above call is made, the variable time will contain the equivalent
  timestamp in struct OSAPI_NtpTime representation.

  This macro assumes that msec<1000. It is the caller's responsibility
  to ensure this. This is done for performance reasons (the extra check slows
  the execution by a factor of 5). If msec may be greater than 1000, you can invoke
  the macro as follows:
  \verbatim
    OSAPI_NtpTime_packFromMillisec(time, sec + msec/1000, msec%1000);
  \endverbatim

  This macro only evaluates its arguments once, so it is safe to invoke it
  with an argument that has side effects; that is, if you write:
  \verbatim
    RTI_UINT32 count = 10;
    OSAPI_NtpTime_packFromMillisec(time, sec, count++)
  \endverbatim
  After the macro count is guaranteed to be 11.

  The accuracy of this conversion over the whole range of millisecond values
  is 0.013 milliseconds.

  This is a fairly efficient macro. On a 400MHz Pentium-II Linux box
  the execution time is about 0.06 usec.

  \verbatim
     2^22*time.frac = ms + ms/2^6 + ms/2^7 + ms/2^11 + ms/2^14 + 1.3e-5
                    = ms + ms*393/2^14;
          time.frac = (ms<<22) + (ms<<16) + (ms<<15) + (ms<<11) + (ms<<8)
                    = (ms<<22) + ((ms*393)<<8)
  \endverbatim

  @see struct OSAPI_NtpTime OSAPI_NtpTime_unpackToMillisec
*/
OSAPIDllExport void
OSAPI_NtpTime_from_millisec(struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 msec);

/*e \ingroup OSAPITimeClass

  @brief Macro to convert from struct OSAPI_NtpTime to seconds and milliseconds.

  @param s (integer) Holds the seconds answer.
  @param msec (integer) Holds the millisecond answer.
  @param time (struct OSAPI_NtpTime) The time to convert to seconds and milliseconds.

  This macro does not check for overflow, so for a near-infinite time value,
  the conversion result may end up being negative. It is the responsibility
  of the user to avoid passing these large time values.

  Use as indicated by the following code:
  \verbatim}
    struct OSAPI_NtpTime time;
    long sec, msec;

    time.sec  = 10;
    time.frac = 577;

    OSAPI_NtpTime_unpackToMillisec(sec, msec, time);
  \endverbatim

  After the above call is made, the variables "sec" and "msec" will
  contain the equivalent timestamp.

  The accuracy of this conversion over the whole range of struct OSAPI_NtpTime values
  is 0.5 milliseconds, except for ntp values above {0x7fffffff, 0x7fffffff},
  accuracy is up to nearly 1 millisecond.

  This is a fairly efficient macro. On a 400MHz Pentium-II Linux box
  the execution time is about 0.08 usec.

  \verbatim
     ms/2^22 = frac*1000/1024 = frac*(1 - 24/1024) = frac*(1 - 3/2^7) =
               frac*(1 - 1/2^6 - 1/2^7)
  \endverbatim

  @see struct OSAPI_NtpTime OSAPI_NtpTime_packFromMillisec
*/
OSAPIDllExport void
OSAPI_NtpTime_to_millisec(RTI_INT32 *const s, RTI_UINT32 *const msec,
                          const struct OSAPI_NtpTime *const time);


/*e \ingroup OSAPITimeClass

  @brief Macro to convert from seconds and microseconds to struct OSAPI_NtpTime format.

  @param time (struct OSAPI_NtpTime) to contain the answer.
  @param s (integer) seconds of the time to covert.
  @param usec (integer) microseconds fraction to convert from.

  This macro does not check for overflow, so for a near-infinite time value,
  the conversion result may end up being negative. It is the caller's 
  responsibility to avoid passing these large time values.

  Use as indicated by the following code:
  \verbatim
    struct OSAPI_NtpTime ntp;
    long sec, usec;
    sec  = 10;
    usec = 577;

    OSAPI_NtpTime_packFromMicrosec(ntp, sec, usec);
  \endverbatim

  After the above call is made, the variable ntp will contain the equivalent
  time stamp in struct OSAPI_NtpTime representation.

  This macro assumes that msec<1000000. It is the caller's responsibility
  to ensure this. This is done for performance reasons, the extra check
  slows the execution a factor of 5! If msec may be greater than 1000000,
  you can invoke the macro as follows:
  \verbatim
    OSAPI_NtpTime_packFromMicrosec(ntp, sec + usec/1000000, usec%1000000);
  \endverbatim

  This macro only evaluates its arguments once, so it is safe to invoke it
  with an argument that has side effects; that is, if you write:
  \verbatim
    RTI_UINT32 count = 10;
    OSAPI_NtpTime_packFromMicrosec(ntp, sec, count++)
  \endverbatim

  After the macro, count is guaranteed to be 11.

  The accuracy of this conversion over the whole range of microsecond values
  is 0.0028 microseconds.

  This is a fairly efficient macro. On a 400MHz Pentium-II Linux box
  the execution time is about 0.08 usec.

  \verbatim
    2^12 * ntp.frac = us + us/2^5  + us/2^6  + us/2^10 + us/2^11
                         + us/2^13 + us/2^14 + us/2^15 + us/2^16
                         + us/2^18 + us/2^19 + us/2^20 + us/2^21
                         + us/2^23 + 3e-9
                    = us + us*99/2^11 + us*15/2^16 + us*61/2^23
           ntp.frac = (us<<12) + (us<<7) + (us<<6) + (us<<2) + (us<<1)
                               + (us>>1) + (us>>2) + (us>>3) + (us>>4)
                               + (us>>6) + (us>>7) + (us>>8) + (us>>9) + (us>>11)
                    = (us<<12) + ((us*99)<<1)+ ((us*15)>>4)+ ((us*61)>>11)
  \endverbatim
*/
OSAPIDllExport void
OSAPI_NtpTime_from_microsec(struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 usec);

/*e \ingroup OSAPITimeClass

  @brief Macro to convert from struct OSAPI_NtpTime to seconds and microseconds.

  @param s (integer) Holds the second portion.
  @param usec (integer) holds the microsecond fraction.
  @param time (struct OSAPI_NtpTime) to be converted.

  This macro does not check for overflow, so for a near-infinite time value,
  the conversion result may end up being negative. It is the caller's 
  responsibility to avoid passing these large time values.

  Use as indicated by the following code:
  \verbatim
    struct OSAPI_NtpTime ntp;
    long sec, usec;

    ntp.sec  = 10;
    ntp.frac = 577;

    OSAPI_NtpTime_unpackToMicrosec(sec, usec, ntp);
  \endverbatim

  After the above call is made, the variables "sec" and "usec" will
  contain the equivalent timestamp.

  The accuracy of this conversion over the whole range of struct OSAPI_NtpTime values
  is 0.5 microseconds, except for ntp value above {0x7fffffff, 0x7fffffff},
  accuracy is up to nearly 1 millisecond.

  This is a fairly efficient macro. On a 400MHz Pentium-II Linux box
  the execution time is about 0.12 usec.

  \verbatim
     us = frac*1000000/2^20 = frac*( 1 - 48576/2^20 )
        = frac*(1 - 47/2^10 - 7/2^14)
        = frac - ((47*frac)>>10) - ((7*frac)>>14)
        = frac - (frac>>5)-(frac>>7)-(frac>>8)-(frac>>9)-(frac>>10)
             - (frac>>12)-(frac>>13)-(frac>>14)
  \endverbatim
*/
OSAPIDllExport void
OSAPI_NtpTime_to_microsec(RTI_INT32 *const s, RTI_UINT32 *const msec,
                          const struct OSAPI_NtpTime *const time);

/*e \ingroup OSAPITimeClass

  @brief Macro to convert from seconds and nanoseconds to struct OSAPI_NtpTime format.

  @param time (struct OSAPI_NtpTime) Holds the answer.
  @param s (integer) Seconds to convert from.
  @param nsec (integer) Nanosecond fraction to convert from.

  Use as indicated by the following code:
  \verbatim
    struct OSAPI_NtpTime time;
    long sec, nsec;
    sec = 10;
    nsec = 577;

    OSAPI_NtpTime_packFromNanosec(time, sec, msec);
  \endverbatim

  After the above call is made, the variable time will contain the equivalent
  timestamp in struct OSAPI_NtpTime representation.

  This macro assumes that nsec<1000000000. It is the caller's responsibility
  to ensure this. This is done for performance reasons (the extra check
  slows the execution a factor of 5). If msec may be greater than 1000000, you
  can invoke the macro as follows:
  \verbatim}
    OSAPI_NtpTime_packFromNanosec(time, sec + nsec/1000000000, nsec%1000000000);
  \endverbatim

  This macro only evaluates its arguments once, so it is safe to invoke it
  with an argument that has side effects; that is, if you write:
  \verbatim
    RTI_UINT32 count = 10;
    OSAPI_NtpTime_packFromNanosec(time, sec, count++)
  \endverbatim
  After the macro, count is guaranteed to be 11.

  The accuracy of this conversion over the whole range of nanosecond values
  is at least 1 nanosecond.
*/
OSAPIDllExport void
OSAPI_NtpTime_from_nanosec(struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 nsec);


/*e \ingroup OSAPITimeClass

  @brief Macro to convert from struct OSAPI_NtpTime to seconds and nanoseconds.

  @param s (integer) Second of the time to covert.
  @param nsec (integer) Nanosecond fraction to convert.
  @param time (struct OSAPI_NtpTime) to convert from.

  Use as indicated by the following code:
  \verbatim
    struct OSAPI_NtpTime time;
    long sec, nsec;
    time.sec  = 10;
    time.frac = 577;

    OSAPI_NtpTime_unpackToNanosec(sec, nsec, time);
  \endverbatim
  After the above call is made, the variables "sec" and "nsec" will
  contain the equivalent timestamp.

  The accuracy of this conversion over the whole range of
  struct OSAPI_NtpTime values is at least 1 nanosecond.
*/
OSAPIDllExport void
OSAPI_NtpTime_to_nanosec(RTI_INT32 *const s, RTI_UINT32 *const nsec,
                         const struct OSAPI_NtpTime *const time);

/*e \ingroup OSAPITimeClass

  A NULL struct OSAPI_NtpTime pointer is considered infinity. This is consistent
  with the concept of infinite time on UNIX systems.

  In addition, if the seconds field equals OSAPI_NTP_TIME_SEC_MAX, the
  time value is also considered infinite.

  @param time Pointer to RTITime.
  @return RTI_TRUE if time is infinite, RTI_FALSE otherwise.
*/
OSAPIDllExport RTI_BOOL
OSAPI_NtpTime_is_infinite(const struct OSAPI_NtpTime *const time);

/*e \ingroup OSAPITimeClass

  @brief answer = t1 - t2.

  @param answer struct OSAPI_NtpTime
  @param t1 struct OSAPI_NtpTime`
  @param t2 struct OSAPI_NtpTime
 */
OSAPIDllExport void
OSAPI_NtpTime_subtract(struct OSAPI_NtpTime *const answer,
                       const struct OSAPI_NtpTime *const t1,
                       const struct OSAPI_NtpTime *const t2);

/*e \ingroup OSAPITimeClass

  @brief answer += time.

  This macro does not check for overflow.

  @param answer struct OSAPI_NtpTime
  @param time struct OSAPI_NtpTime
*/
#define OSAPI_NtpTime_increment(answer, time) \
{ \
    register RTI_UINT32 currentFrac = (answer)->frac; \
    (answer)->sec  += (time)->sec; \
    (answer)->frac += (time)->frac; \
    if (((answer)->frac < (time)->frac) || ((answer)->frac < currentFrac)) { \
        (answer)->sec++; \
    } \
}

/*e \ingroup OSAPITimeClass

  @brief Decrement one struct OSAPI_NtpTime value by another struct OSAPI_NtpTime value.

  Precondition:
  Postcondition: answer -= time.

  @param answer struct OSAPI_NtpTime
  @param time struct OSAPI_NtpTime

*/
#define OSAPI_NtpTime_decrement(answer, time) \
{ \
    register RTI_UINT32 currentFrac = (answer)->frac; \
    (answer)->sec  -= (time)->sec; \
    (answer)->frac -= (time)->frac; \
    if (((answer)->frac > currentFrac)) { (answer)->sec--; } \
}

/*e \ingroup OSAPITimeClass

  @brief Zero time.

  This global variable is for convenience. It allows you to see if a 
  RTITime variable is negative or positive by comparing against this.

  @see RtiTimeCompare
*/
#define OSAPI_NTP_TIME_ZERO {0,0}

/*e \ingroup OSAPITimeClass

  Represents the maximum timevalue that can be represented using the
  NTP time format. For all practical purposes, it can be considered
  equivalent to infinity.

*/
#define OSAPI_NTP_TIME_MAX {OSAPI_NTP_TIME_SEC_MAX,OSAPI_NTP_TIME_FRAC_MAX}

/*e \ingroup OSAPITimeClass
   The number of nanoseconds per second. 1e9.
   @see RtiTimePack RtiTimeUnpack
*/
#define OSAPI_NTP_TIME_NSEC_PER_SEC  (1000000000)
/*e \ingroup OSAPITimeClass
   The number of microseconds per second. 1e6.
   @see RtiTimePack RtiTimeUnpack
*/
#define OSAPI_NTP_TIME_USEC_PER_SEC  (1000000)
/*e \ingroup OSAPITimeClass
   The number of milliseconds per second. 1e3.
   @see RtiTimePack RtiTimeUnpack
 */
#define OSAPI_NTP_TIME_MSEC_PER_SEC  (1000)
/*e \ingroup OSAPITimeClass
  The number of microseconds per milliseconds. 1e3.
   @see RtiTimePack RtiTimeUnpack
 */
#define OSAPI_NTP_TIME_NSEC_PER_USEC (1000)
/*e \ingroup OSAPITimeClass
   The number of microseconds per milliseconds. 1e3.
   @see RtiTimePack RtiTimeUnpack
*/
#define OSAPI_NTP_TIME_USEC_PER_MSEC (1000)
/*e \ingroup OSAPITimeClass
   The number of seconds per second. 1.
   @see RtiTimePack RtiTimeUnpack
 */
#define OSAPI_NTP_TIME_SEC_PER_SEC   (1)

/*e \ingroup OSAPITimeClass
   The number of nano seconds per milli second. 1e6.
   @see RtiTimePack RtiTimeUnpack
 */
#define OSAPI_NTP_TIME_NSEC_PER_MSEC   (1000000)

#ifdef __cplusplus
}                  /* extern "C" */
#endif

#endif /* osapi_time_h */