timex.h revision 7c478bd95313f5f23a4c958a745db2134aa03244
/*
* Copyright (c) David L. Mills 1993, 1994
*
* Permission to use, copy, modify, and distribute this software and its
* documentation for any purpose and without fee is hereby granted, provided
* that the above copyright notice appears in all copies and that both the
* copyright notice and this permission notice appear in supporting
* documentation, and that the name University of Delaware not be used in
* advertising or publicity pertaining to distribution of the software
* without specific, written prior permission. The University of Delaware
* makes no representations about the suitability this software for any
* purpose. It is provided "as is" without express or implied warranty.
*/
/*
* Copyright 1996-1997, 2002 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _SYS_TIMEX_H
#define _SYS_TIMEX_H
#pragma ident "%Z%%M% %I% %E% SMI"
#ifdef __cplusplus
extern "C" {
#endif
#include <sys/inttypes.h>
/*
* The following defines establish the engineering parameters of the
* phase-lock loop (PLL) model used in the kernel implementation. These
* parameters have been carefully chosen by analysis for good stability
* and wide dynamic range.
*
* The hz variable is defined in the kernel build environment. It
* establishes the timer interrupt frequency.
*
* SCALE_KG and SCALE_KF establish the damping of the PLL and are chosen
* for a slightly underdamped convergence characteristic. SCALE_KH
* establishes the damping of the FLL and is chosen by wisdom and black
* art.
*
* MAXTC establishes the maximum time constant of the PLL. With the
* SCALE_KG and SCALE_KF values given and a time constant range from
* zero to MAXTC, the PLL will converge in 15 minutes to 16 hours,
* respectively.
*/
/*
* The following defines establish the scaling of the various variables
* used by the PLL. They are chosen to allow the greatest precision
* possible without overflow of a 32-bit word.
*
* SCALE_PHASE defines the scaling (multiplier) of the time_phase variable,
* which serves as a an extension to the low-order bits of the system
* clock variable time.tv_usec.
*
* SCALE_UPDATE defines the scaling (multiplier) of the time_offset variable,
* which represents the current time offset with respect to standard
* time.
*
* SCALE_USEC defines the scaling (multiplier) of the time_freq and
* time_tolerance variables, which represent the current frequency
* offset and maximum frequency tolerance.
*
* FINEUSEC is 1 us in SCALE_UPDATE units of the time_phase variable.
*/
/*
* The following defines establish the performance envelope of the PLL.
* They insure it operates within predefined limits, in order to satisfy
* correctness assertions. An excursion which exceeds these bounds is
* clamped to the bound and operation proceeds accordingly. In practice,
* this can occur only if something has failed or is operating out of
* tolerance, but otherwise the PLL continues to operate in a stable
* mode.
*
* MAXPHASE must be set greater than or equal to CLOCK.MAX (128 ms), as
* defined in the NTP specification. CLOCK.MAX establishes the maximum
* time offset allowed before the system time is reset, rather than
* incrementally adjusted. Here, the maximum offset is clamped to
* MAXPHASE only in order to prevent overflow errors due to defective
* protocol implementations.
*
* MAXFREQ is the maximum frequency tolerance of the CPU clock
* oscillator plus the maximum slew rate allowed by the protocol. It
* should be set to at least the frequency tolerance of the oscillator
* plus 100 ppm for vernier frequency adjustments. The oscillator time and
* frequency are disciplined to an external source, presumably with
* negligible time and frequency error relative to UTC, and MAXFREQ can
* be reduced.
*
* MAXTIME is the maximum jitter tolerance of the PPS signal.
*
* MINSEC and MAXSEC define the lower and upper bounds on the interval
* between protocol updates.
*/
/*
* The following defines are used only if a pulse-per-second (PPS)
* signal is available and connected via a modem control lead, such as
* produced by the optional ppsclock feature incorporated in the Sun
* asynch driver. They establish the design parameters of the frequency-
* lock loop used to discipline the CPU clock oscillator to the PPS
* signal.
*
* PPS_AVG is the averaging factor for the frequency loop, as well as
* the time and frequency dispersion.
*
* PPS_SHIFT and PPS_SHIFTMAX specify the minimum and maximum
* calibration intervals, respectively, in seconds as a power of two.
*
* PPS_VALID is the maximum interval before the PPS signal is considered
* invalid and protocol updates used directly instead.
*
* MAXGLITCH is the maximum interval before a time offset of more than
* MAXTIME is believed.
*/
/*
* The following defines and structures define the user interface for
* the ntp_gettime() and ntp_adjtime() system calls.
*
* Control mode codes (timex.modes)
*/
/*
* Status codes (timex.status)
*/
/*
* Clock states (time_state)
*/
#define TIME_OK 0 /* no leap second warning */
/*
* NTP user interface (ntp_gettime()) - used to read kernel clock values
*
* Note: maximum error = NTP synch distance = dispersion + delay / 2;
* estimated error = NTP dispersion.
*/
struct ntptimeval {
};
#if defined(_SYSCALL32)
/* Kernel's view of _ILP32 application's ntptimeval struct */
struct ntptimeval32 {
};
#endif /* _SYSCALL32 */
/*
* NTP daemon interface - (ntp_adjtime()) used to discipline CPU clock
* oscillator
*/
struct timex {
};
#if defined(__STDC__)
/*
* NTP syscalls
*/
int ntp_gettime(struct ntptimeval *);
int ntp_adjtime(struct timex *);
#else
int ntp_gettime();
int ntp_adjtime();
#endif /* __STDC__ */
#ifdef _KERNEL
extern void clock_update(int);
extern void ddi_hardpps(struct timeval *, int);
#endif /* _KERNEL */
#ifdef __cplusplus
}
#endif
#endif /* _SYS_TIMEX_H */