Data Structures
struct	OSAPI_NtpTime
	NtpTime API. More...

Macros
#define	OSAPI_NTP_TIME_SEC_MAX ((RTI_INT32)0x7fffffff)
#define	OSAPI_NTP_TIME_FRAC_MAX ((RTI_UINT32)0xffffffff)
#define	OSAPI_NtpTime_increment(answer, time)
	answer += time.
#define	OSAPI_NtpTime_decrement(answer, time)
	Decrement one struct OSAPI_NtpTime value by another struct OSAPI_NtpTime value.
#define	OSAPI_NTP_TIME_ZERO {0,0}
	Zero time.
#define	OSAPI_NTP_TIME_MAX {OSAPI_NTP_TIME_SEC_MAX,OSAPI_NTP_TIME_FRAC_MAX}
#define	OSAPI_NTP_TIME_NSEC_PER_SEC (1000000000)
#define	OSAPI_NTP_TIME_USEC_PER_SEC (1000000)
#define	OSAPI_NTP_TIME_MSEC_PER_SEC (1000)
#define	OSAPI_NTP_TIME_NSEC_PER_USEC (1000)
#define	OSAPI_NTP_TIME_USEC_PER_MSEC (1000)
#define	OSAPI_NTP_TIME_SEC_PER_SEC (1)
#define	OSAPI_NTP_TIME_NSEC_PER_MSEC (1000000)

Typedefs
typedef struct OSAPI_NtpTime	OSAPI_NtpTime
	NtpTime API.

Functions
void	OSAPI_NtpTime_from_millisec (struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 msec)
	Macro to convert from seconds and milliseconds to struct OSAPI_NtpTime format.
void	OSAPI_NtpTime_to_millisec (RTI_INT32 const s, RTI_UINT32 const msec, const struct OSAPI_NtpTime *const time)
	Macro to convert from struct OSAPI_NtpTime to seconds and milliseconds.
void	OSAPI_NtpTime_from_microsec (struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 usec)
	Macro to convert from seconds and microseconds to struct OSAPI_NtpTime format.
void	OSAPI_NtpTime_to_microsec (RTI_INT32 const s, RTI_UINT32 const msec, const struct OSAPI_NtpTime *const time)
	Macro to convert from struct OSAPI_NtpTime to seconds and microseconds.
void	OSAPI_NtpTime_from_nanosec (struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 nsec)
	Macro to convert from seconds and nanoseconds to struct OSAPI_NtpTime format.
void	OSAPI_NtpTime_to_nanosec (RTI_INT32 const s, RTI_UINT32 const nsec, const struct OSAPI_NtpTime *const time)
	Macro to convert from struct OSAPI_NtpTime to seconds and nanoseconds.
RTI_BOOL	OSAPI_NtpTime_is_infinite (const struct OSAPI_NtpTime *const time)
void	OSAPI_NtpTime_subtract (struct OSAPI_NtpTime const answer, const struct OSAPI_NtpTime const t1, const struct OSAPI_NtpTime *const t2)
	answer = t1 - t2.

Detailed Description

Macro Definition Documentation

#define OSAPI_NTP_TIME_SEC_MAX ((RTI_INT32)0x7fffffff)

The maximum number of seconds that can be represented using NTP time.

#define OSAPI_NTP_TIME_FRAC_MAX ((RTI_UINT32)0xffffffff)

The largest possible value of the fraction field in NTP time.

#define OSAPI_NtpTime_increment	(	answer,
		time
	)

Value:

{ \
    register RTI_UINT32 currentFrac = (answer)->frac; \
    (answer)->sec  += (time)->sec; \
    (answer)->frac += (time)->frac; \
    if (((answer)->frac < (time)->frac) || ((answer)->frac < currentFrac)) { \
        (answer)->sec++; \
    } \
}

answer += time.

This macro does not check for overflow.

Parameters:

answer	struct OSAPI_NtpTime
time	struct OSAPI_NtpTime

#define OSAPI_NtpTime_decrement	(	answer,
		time
	)

Value:

{ \
    register RTI_UINT32 currentFrac = (answer)->frac; \
    (answer)->sec  -= (time)->sec; \
    (answer)->frac -= (time)->frac; \
    if (((answer)->frac > currentFrac)) { (answer)->sec--; } \
}

Decrement one struct OSAPI_NtpTime value by another struct OSAPI_NtpTime value.

Precondition: Postcondition: answer -= time.

Parameters:

answer	struct OSAPI_NtpTime
time	struct OSAPI_NtpTime

#define OSAPI_NTP_TIME_ZERO {0,0}

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 also:: RtiTimeCompare

#define OSAPI_NTP_TIME_MAX {OSAPI_NTP_TIME_SEC_MAX,OSAPI_NTP_TIME_FRAC_MAX}

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_NSEC_PER_SEC (1000000000)

The number of nanoseconds per second. 1e9.

See also:: RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_USEC_PER_SEC (1000000)

The number of microseconds per second. 1e6.

See also:: RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_MSEC_PER_SEC (1000)

The number of milliseconds per second. 1e3.

See also:: RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_NSEC_PER_USEC (1000)

The number of microseconds per milliseconds. 1e3.

See also:: RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_USEC_PER_MSEC (1000)

The number of microseconds per milliseconds. 1e3.

See also:: RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_SEC_PER_SEC (1)

The number of seconds per second. 1.

See also:: RtiTimePack RtiTimeUnpack

#define OSAPI_NTP_TIME_NSEC_PER_MSEC (1000000)

The number of nano seconds per milli second. 1e6.

See also:: RtiTimePack RtiTimeUnpack

Typedef Documentation

typedef struct OSAPI_NtpTime OSAPI_NtpTime

NtpTime API.

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.

Example:

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

     struct OSAPI_NtpTime ntpTime;

     OSAPI_NtpTime_packFromMillisec(ntpTime, 1, 500);

See also:: OSAPI_NtpTime_packFromMillisec OSAPI_NtpTime_packFromMicrosec; OSAPI_NtpTime_packFromNanosec; OSAPI_NtpTime_unpackFromMillisec OSAPI_NtpTime_unpackFromMicrosec; OSAPI_NtpTime_unpackFromNanosec

Function Documentation

void OSAPI_NtpTime_from_millisec	(	struct OSAPI_NtpTime *const	time,
		RTI_INT32	s,
		RTI_UINT32	msec
	)

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

Parameters:

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

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

    OSAPI_NtpTime_packFromMillisec(time, sec, msec);

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:

    OSAPI_NtpTime_packFromMillisec(time, sec + msec/1000, msec%1000);

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:

    RTI_UINT32 count = 10;
    OSAPI_NtpTime_packFromMillisec(time, sec, count++)

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.

     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)

See also:: struct OSAPI_NtpTime OSAPI_NtpTime_unpackToMillisec

void OSAPI_NtpTime_to_millisec	(	RTI_INT32 *const	s,
		RTI_UINT32 *const	msec,
		const struct OSAPI_NtpTime *const	time
	)

Macro to convert from struct OSAPI_NtpTime to seconds and milliseconds.

Parameters:

s	(integer) Holds the seconds answer.
msec	(integer) Holds the millisecond answer.
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:

}
    struct OSAPI_NtpTime time;
    long sec, msec;

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

    OSAPI_NtpTime_unpackToMillisec(sec, msec, time);

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.

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

See also:: struct OSAPI_NtpTime OSAPI_NtpTime_packFromMillisec

void OSAPI_NtpTime_from_microsec	(	struct OSAPI_NtpTime *const	time,
		RTI_INT32	s,
		RTI_UINT32	usec
	)

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

Parameters:

time	(struct OSAPI_NtpTime) to contain the answer.
s	(integer) seconds of the time to covert.
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:

    struct OSAPI_NtpTime ntp;
    long sec, usec;
    sec  = 10;
    usec = 577;

    OSAPI_NtpTime_packFromMicrosec(ntp, sec, usec);

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:

    OSAPI_NtpTime_packFromMicrosec(ntp, sec + usec/1000000, usec%1000000);

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:

    RTI_UINT32 count = 10;
    OSAPI_NtpTime_packFromMicrosec(ntp, sec, count++)

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.

    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)

void OSAPI_NtpTime_to_microsec	(	RTI_INT32 *const	s,
		RTI_UINT32 *const	msec,
		const struct OSAPI_NtpTime *const	time
	)

Macro to convert from struct OSAPI_NtpTime to seconds and microseconds.

Parameters:

s	(integer) Holds the second portion.
usec	(integer) holds the microsecond fraction.
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:

    struct OSAPI_NtpTime ntp;
    long sec, usec;

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

    OSAPI_NtpTime_unpackToMicrosec(sec, usec, ntp);

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.

     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)

void OSAPI_NtpTime_from_nanosec	(	struct OSAPI_NtpTime *const	time,
		RTI_INT32	s,
		RTI_UINT32	nsec
	)

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

Parameters:

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

Use as indicated by the following code:

    struct OSAPI_NtpTime time;
    long sec, nsec;
    sec = 10;
    nsec = 577;

    OSAPI_NtpTime_packFromNanosec(time, sec, msec);

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:

}
    OSAPI_NtpTime_packFromNanosec(time, sec + nsec/1000000000, nsec%1000000000);

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:

    RTI_UINT32 count = 10;
    OSAPI_NtpTime_packFromNanosec(time, sec, count++)

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.

void OSAPI_NtpTime_to_nanosec	(	RTI_INT32 *const	s,
		RTI_UINT32 *const	nsec,
		const struct OSAPI_NtpTime *const	time
	)

Macro to convert from struct OSAPI_NtpTime to seconds and nanoseconds.

Parameters:

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

Use as indicated by the following code:

    struct OSAPI_NtpTime time;
    long sec, nsec;
    time.sec  = 10;
    time.frac = 577;

    OSAPI_NtpTime_unpackToNanosec(sec, nsec, time);

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.

RTI_BOOL OSAPI_NtpTime_is_infinite ( const struct OSAPI_NtpTime *const time )

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.

Parameters:

time	Pointer to RTITime.

Returns:: RTI_TRUE if time is infinite, RTI_FALSE otherwise.

void OSAPI_NtpTime_subtract	(	struct OSAPI_NtpTime *const	answer,
		const struct OSAPI_NtpTime *const	t1,
		const struct OSAPI_NtpTime *const	t2
	)

answer = t1 - t2.

Parameters:

answer	struct OSAPI_NtpTime
t1	struct OSAPI_NtpTime`
t2	struct OSAPI_NtpTime

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation