1*0Sstevel@tonic-gate /* 2*0Sstevel@tonic-gate * Copyright (c) David L. Mills 1993, 1994 3*0Sstevel@tonic-gate * 4*0Sstevel@tonic-gate * Permission to use, copy, modify, and distribute this software and its 5*0Sstevel@tonic-gate * documentation for any purpose and without fee is hereby granted, provided 6*0Sstevel@tonic-gate * that the above copyright notice appears in all copies and that both the 7*0Sstevel@tonic-gate * copyright notice and this permission notice appear in supporting 8*0Sstevel@tonic-gate * documentation, and that the name University of Delaware not be used in 9*0Sstevel@tonic-gate * advertising or publicity pertaining to distribution of the software 10*0Sstevel@tonic-gate * without specific, written prior permission. The University of Delaware 11*0Sstevel@tonic-gate * makes no representations about the suitability this software for any 12*0Sstevel@tonic-gate * purpose. It is provided "as is" without express or implied warranty. 13*0Sstevel@tonic-gate */ 14*0Sstevel@tonic-gate 15*0Sstevel@tonic-gate /* 16*0Sstevel@tonic-gate * Copyright 1996-1997, 2002 Sun Microsystems, Inc. All rights reserved. 17*0Sstevel@tonic-gate * Use is subject to license terms. 18*0Sstevel@tonic-gate */ 19*0Sstevel@tonic-gate 20*0Sstevel@tonic-gate #ifndef _SYS_TIMEX_H 21*0Sstevel@tonic-gate #define _SYS_TIMEX_H 22*0Sstevel@tonic-gate 23*0Sstevel@tonic-gate #pragma ident "%Z%%M% %I% %E% SMI" 24*0Sstevel@tonic-gate 25*0Sstevel@tonic-gate #ifdef __cplusplus 26*0Sstevel@tonic-gate extern "C" { 27*0Sstevel@tonic-gate #endif 28*0Sstevel@tonic-gate 29*0Sstevel@tonic-gate #include <sys/types.h> 30*0Sstevel@tonic-gate #include <sys/time.h> 31*0Sstevel@tonic-gate #include <sys/syscall.h> 32*0Sstevel@tonic-gate #include <sys/inttypes.h> 33*0Sstevel@tonic-gate 34*0Sstevel@tonic-gate /* 35*0Sstevel@tonic-gate * The following defines establish the engineering parameters of the 36*0Sstevel@tonic-gate * phase-lock loop (PLL) model used in the kernel implementation. These 37*0Sstevel@tonic-gate * parameters have been carefully chosen by analysis for good stability 38*0Sstevel@tonic-gate * and wide dynamic range. 39*0Sstevel@tonic-gate * 40*0Sstevel@tonic-gate * The hz variable is defined in the kernel build environment. It 41*0Sstevel@tonic-gate * establishes the timer interrupt frequency. 42*0Sstevel@tonic-gate * 43*0Sstevel@tonic-gate * SCALE_KG and SCALE_KF establish the damping of the PLL and are chosen 44*0Sstevel@tonic-gate * for a slightly underdamped convergence characteristic. SCALE_KH 45*0Sstevel@tonic-gate * establishes the damping of the FLL and is chosen by wisdom and black 46*0Sstevel@tonic-gate * art. 47*0Sstevel@tonic-gate * 48*0Sstevel@tonic-gate * MAXTC establishes the maximum time constant of the PLL. With the 49*0Sstevel@tonic-gate * SCALE_KG and SCALE_KF values given and a time constant range from 50*0Sstevel@tonic-gate * zero to MAXTC, the PLL will converge in 15 minutes to 16 hours, 51*0Sstevel@tonic-gate * respectively. 52*0Sstevel@tonic-gate */ 53*0Sstevel@tonic-gate #define SCALE_KG (1<<6) /* phase factor (multiplier) */ 54*0Sstevel@tonic-gate #define SCALE_KF (1<<16) /* PLL frequency factor (multiplier) */ 55*0Sstevel@tonic-gate #define SCALE_KH (1<<2) /* FLL frequency factor (multiplier) */ 56*0Sstevel@tonic-gate #define MAXTC (1<<6) /* maximum time constant */ 57*0Sstevel@tonic-gate 58*0Sstevel@tonic-gate 59*0Sstevel@tonic-gate /* 60*0Sstevel@tonic-gate * The following defines establish the scaling of the various variables 61*0Sstevel@tonic-gate * used by the PLL. They are chosen to allow the greatest precision 62*0Sstevel@tonic-gate * possible without overflow of a 32-bit word. 63*0Sstevel@tonic-gate * 64*0Sstevel@tonic-gate * SCALE_PHASE defines the scaling (multiplier) of the time_phase variable, 65*0Sstevel@tonic-gate * which serves as a an extension to the low-order bits of the system 66*0Sstevel@tonic-gate * clock variable time.tv_usec. 67*0Sstevel@tonic-gate * 68*0Sstevel@tonic-gate * SCALE_UPDATE defines the scaling (multiplier) of the time_offset variable, 69*0Sstevel@tonic-gate * which represents the current time offset with respect to standard 70*0Sstevel@tonic-gate * time. 71*0Sstevel@tonic-gate * 72*0Sstevel@tonic-gate * SCALE_USEC defines the scaling (multiplier) of the time_freq and 73*0Sstevel@tonic-gate * time_tolerance variables, which represent the current frequency 74*0Sstevel@tonic-gate * offset and maximum frequency tolerance. 75*0Sstevel@tonic-gate * 76*0Sstevel@tonic-gate * FINEUSEC is 1 us in SCALE_UPDATE units of the time_phase variable. 77*0Sstevel@tonic-gate */ 78*0Sstevel@tonic-gate #define SCALE_PHASE (1<<22) /* phase scale */ 79*0Sstevel@tonic-gate #define SCALE_USEC (1<<16) 80*0Sstevel@tonic-gate #define SCALE_UPDATE (SCALE_KG * MAXTC) /* */ 81*0Sstevel@tonic-gate #define FINEUSEC (1<<22) /* 1 us in phase units */ 82*0Sstevel@tonic-gate 83*0Sstevel@tonic-gate /* 84*0Sstevel@tonic-gate * The following defines establish the performance envelope of the PLL. 85*0Sstevel@tonic-gate * They insure it operates within predefined limits, in order to satisfy 86*0Sstevel@tonic-gate * correctness assertions. An excursion which exceeds these bounds is 87*0Sstevel@tonic-gate * clamped to the bound and operation proceeds accordingly. In practice, 88*0Sstevel@tonic-gate * this can occur only if something has failed or is operating out of 89*0Sstevel@tonic-gate * tolerance, but otherwise the PLL continues to operate in a stable 90*0Sstevel@tonic-gate * mode. 91*0Sstevel@tonic-gate * 92*0Sstevel@tonic-gate * MAXPHASE must be set greater than or equal to CLOCK.MAX (128 ms), as 93*0Sstevel@tonic-gate * defined in the NTP specification. CLOCK.MAX establishes the maximum 94*0Sstevel@tonic-gate * time offset allowed before the system time is reset, rather than 95*0Sstevel@tonic-gate * incrementally adjusted. Here, the maximum offset is clamped to 96*0Sstevel@tonic-gate * MAXPHASE only in order to prevent overflow errors due to defective 97*0Sstevel@tonic-gate * protocol implementations. 98*0Sstevel@tonic-gate * 99*0Sstevel@tonic-gate * MAXFREQ is the maximum frequency tolerance of the CPU clock 100*0Sstevel@tonic-gate * oscillator plus the maximum slew rate allowed by the protocol. It 101*0Sstevel@tonic-gate * should be set to at least the frequency tolerance of the oscillator 102*0Sstevel@tonic-gate * plus 100 ppm for vernier frequency adjustments. The oscillator time and 103*0Sstevel@tonic-gate * frequency are disciplined to an external source, presumably with 104*0Sstevel@tonic-gate * negligible time and frequency error relative to UTC, and MAXFREQ can 105*0Sstevel@tonic-gate * be reduced. 106*0Sstevel@tonic-gate * 107*0Sstevel@tonic-gate * MAXTIME is the maximum jitter tolerance of the PPS signal. 108*0Sstevel@tonic-gate * 109*0Sstevel@tonic-gate * MINSEC and MAXSEC define the lower and upper bounds on the interval 110*0Sstevel@tonic-gate * between protocol updates. 111*0Sstevel@tonic-gate */ 112*0Sstevel@tonic-gate #define MAXPHASE 512000 /* max phase error (us) */ 113*0Sstevel@tonic-gate #define MAXFREQ (512 * SCALE_USEC) /* max freq error (100 ppm) */ 114*0Sstevel@tonic-gate #define MAXTIME (200 << PPS_AVG) /* max PPS error (jitter) (200 us) */ 115*0Sstevel@tonic-gate #define MINSEC 16 /* min interval between updates (s) */ 116*0Sstevel@tonic-gate #define MAXSEC 1200 /* max interval between updates (s) */ 117*0Sstevel@tonic-gate 118*0Sstevel@tonic-gate /* 119*0Sstevel@tonic-gate * The following defines are used only if a pulse-per-second (PPS) 120*0Sstevel@tonic-gate * signal is available and connected via a modem control lead, such as 121*0Sstevel@tonic-gate * produced by the optional ppsclock feature incorporated in the Sun 122*0Sstevel@tonic-gate * asynch driver. They establish the design parameters of the frequency- 123*0Sstevel@tonic-gate * lock loop used to discipline the CPU clock oscillator to the PPS 124*0Sstevel@tonic-gate * signal. 125*0Sstevel@tonic-gate * 126*0Sstevel@tonic-gate * PPS_AVG is the averaging factor for the frequency loop, as well as 127*0Sstevel@tonic-gate * the time and frequency dispersion. 128*0Sstevel@tonic-gate * 129*0Sstevel@tonic-gate * PPS_SHIFT and PPS_SHIFTMAX specify the minimum and maximum 130*0Sstevel@tonic-gate * calibration intervals, respectively, in seconds as a power of two. 131*0Sstevel@tonic-gate * 132*0Sstevel@tonic-gate * PPS_VALID is the maximum interval before the PPS signal is considered 133*0Sstevel@tonic-gate * invalid and protocol updates used directly instead. 134*0Sstevel@tonic-gate * 135*0Sstevel@tonic-gate * MAXGLITCH is the maximum interval before a time offset of more than 136*0Sstevel@tonic-gate * MAXTIME is believed. 137*0Sstevel@tonic-gate */ 138*0Sstevel@tonic-gate #define PPS_AVG 2 /* pps averaging constant (shift) */ 139*0Sstevel@tonic-gate #define PPS_SHIFT 2 /* min interval duration (s) (shift) */ 140*0Sstevel@tonic-gate #define PPS_SHIFTMAX 8 /* max interval duration (s) (shift) */ 141*0Sstevel@tonic-gate #define PPS_VALID 120 /* pps signal watchdog max (s) */ 142*0Sstevel@tonic-gate #define MAXGLITCH 30 /* pps signal glitch max (s) */ 143*0Sstevel@tonic-gate 144*0Sstevel@tonic-gate /* 145*0Sstevel@tonic-gate * The following defines and structures define the user interface for 146*0Sstevel@tonic-gate * the ntp_gettime() and ntp_adjtime() system calls. 147*0Sstevel@tonic-gate * 148*0Sstevel@tonic-gate * Control mode codes (timex.modes) 149*0Sstevel@tonic-gate */ 150*0Sstevel@tonic-gate #define MOD_OFFSET 0x0001 /* set time offset */ 151*0Sstevel@tonic-gate #define MOD_FREQUENCY 0x0002 /* set frequency offset */ 152*0Sstevel@tonic-gate #define MOD_MAXERROR 0x0004 /* set maximum time error */ 153*0Sstevel@tonic-gate #define MOD_ESTERROR 0x0008 /* set estimated time error */ 154*0Sstevel@tonic-gate #define MOD_STATUS 0x0010 /* set clock status bits */ 155*0Sstevel@tonic-gate #define MOD_TIMECONST 0x0020 /* set pll time constant */ 156*0Sstevel@tonic-gate #define MOD_CLKB 0x4000 /* set clock B */ 157*0Sstevel@tonic-gate #define MOD_CLKA 0x8000 /* set clock A */ 158*0Sstevel@tonic-gate 159*0Sstevel@tonic-gate /* 160*0Sstevel@tonic-gate * Status codes (timex.status) 161*0Sstevel@tonic-gate */ 162*0Sstevel@tonic-gate #define STA_PLL 0x0001 /* enable PLL updates (rw) */ 163*0Sstevel@tonic-gate #define STA_PPSFREQ 0x0002 /* enable PPS freq discipline (rw) */ 164*0Sstevel@tonic-gate #define STA_PPSTIME 0x0004 /* enable PPS time discipline (rw) */ 165*0Sstevel@tonic-gate #define STA_FLL 0x0008 /* select frequency-lock mode (rw) */ 166*0Sstevel@tonic-gate 167*0Sstevel@tonic-gate #define STA_INS 0x0010 /* insert leap (rw) */ 168*0Sstevel@tonic-gate #define STA_DEL 0x0020 /* delete leap (rw) */ 169*0Sstevel@tonic-gate #define STA_UNSYNC 0x0040 /* clock unsynchronized (rw) */ 170*0Sstevel@tonic-gate #define STA_FREQHOLD 0x0080 /* hold frequency (rw) */ 171*0Sstevel@tonic-gate 172*0Sstevel@tonic-gate #define STA_PPSSIGNAL 0x0100 /* PPS signal present (ro) */ 173*0Sstevel@tonic-gate #define STA_PPSJITTER 0x0200 /* PPS signal jitter exceeded (ro) */ 174*0Sstevel@tonic-gate #define STA_PPSWANDER 0x0400 /* PPS signal wander exceeded (ro) */ 175*0Sstevel@tonic-gate #define STA_PPSERROR 0x0800 /* PPS signal calibration error (ro) */ 176*0Sstevel@tonic-gate 177*0Sstevel@tonic-gate #define STA_CLOCKERR 0x1000 /* clock hardware fault (ro) */ 178*0Sstevel@tonic-gate 179*0Sstevel@tonic-gate #define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \ 180*0Sstevel@tonic-gate STA_PPSERROR | STA_CLOCKERR) /* read-only bits */ 181*0Sstevel@tonic-gate 182*0Sstevel@tonic-gate /* 183*0Sstevel@tonic-gate * Clock states (time_state) 184*0Sstevel@tonic-gate */ 185*0Sstevel@tonic-gate #define TIME_OK 0 /* no leap second warning */ 186*0Sstevel@tonic-gate #define TIME_INS 1 /* insert leap second warning */ 187*0Sstevel@tonic-gate #define TIME_DEL 2 /* delete leap second warning */ 188*0Sstevel@tonic-gate #define TIME_OOP 3 /* leap second in progress */ 189*0Sstevel@tonic-gate #define TIME_WAIT 4 /* leap second has occured */ 190*0Sstevel@tonic-gate #define TIME_ERROR 5 /* clock not synchronized */ 191*0Sstevel@tonic-gate 192*0Sstevel@tonic-gate /* 193*0Sstevel@tonic-gate * NTP user interface (ntp_gettime()) - used to read kernel clock values 194*0Sstevel@tonic-gate * 195*0Sstevel@tonic-gate * Note: maximum error = NTP synch distance = dispersion + delay / 2; 196*0Sstevel@tonic-gate * estimated error = NTP dispersion. 197*0Sstevel@tonic-gate */ 198*0Sstevel@tonic-gate struct ntptimeval { 199*0Sstevel@tonic-gate struct timeval time; /* current time (ro) */ 200*0Sstevel@tonic-gate int32_t maxerror; /* maximum error (us) (ro) */ 201*0Sstevel@tonic-gate int32_t esterror; /* estimated error (us) (ro) */ 202*0Sstevel@tonic-gate }; 203*0Sstevel@tonic-gate 204*0Sstevel@tonic-gate #if defined(_SYSCALL32) 205*0Sstevel@tonic-gate 206*0Sstevel@tonic-gate /* Kernel's view of _ILP32 application's ntptimeval struct */ 207*0Sstevel@tonic-gate 208*0Sstevel@tonic-gate struct ntptimeval32 { 209*0Sstevel@tonic-gate struct timeval32 time; 210*0Sstevel@tonic-gate int32_t maxerror; 211*0Sstevel@tonic-gate int32_t esterror; 212*0Sstevel@tonic-gate }; 213*0Sstevel@tonic-gate 214*0Sstevel@tonic-gate #endif /* _SYSCALL32 */ 215*0Sstevel@tonic-gate 216*0Sstevel@tonic-gate /* 217*0Sstevel@tonic-gate * NTP daemon interface - (ntp_adjtime()) used to discipline CPU clock 218*0Sstevel@tonic-gate * oscillator 219*0Sstevel@tonic-gate */ 220*0Sstevel@tonic-gate struct timex { 221*0Sstevel@tonic-gate uint32_t modes; /* clock mode bits (wo) */ 222*0Sstevel@tonic-gate int32_t offset; /* time offset (us) (rw) */ 223*0Sstevel@tonic-gate int32_t freq; /* frequency offset (scaled ppm) (rw) */ 224*0Sstevel@tonic-gate int32_t maxerror; /* maximum error (us) (rw) */ 225*0Sstevel@tonic-gate int32_t esterror; /* estimated error (us) (rw) */ 226*0Sstevel@tonic-gate int32_t status; /* clock status bits (rw) */ 227*0Sstevel@tonic-gate int32_t constant; /* pll time constant (rw) */ 228*0Sstevel@tonic-gate int32_t precision; /* clock precision (us) (ro) */ 229*0Sstevel@tonic-gate int32_t tolerance; /* clock freq tolerance (scaled ppm) (ro) */ 230*0Sstevel@tonic-gate int32_t ppsfreq; /* pps frequency (scaled ppm) (ro) */ 231*0Sstevel@tonic-gate int32_t jitter; /* pps jitter (us) (ro) */ 232*0Sstevel@tonic-gate int32_t shift; /* interval duration (s) (shift) (ro) */ 233*0Sstevel@tonic-gate int32_t stabil; /* pps stability (scaled ppm) (ro) */ 234*0Sstevel@tonic-gate int32_t jitcnt; /* jitter limit exceeded (ro) */ 235*0Sstevel@tonic-gate int32_t calcnt; /* calibration intervals (ro) */ 236*0Sstevel@tonic-gate int32_t errcnt; /* calibration errors (ro) */ 237*0Sstevel@tonic-gate int32_t stbcnt; /* stability limit exceeded (ro) */ 238*0Sstevel@tonic-gate }; 239*0Sstevel@tonic-gate 240*0Sstevel@tonic-gate #if defined(__STDC__) 241*0Sstevel@tonic-gate /* 242*0Sstevel@tonic-gate * NTP syscalls 243*0Sstevel@tonic-gate */ 244*0Sstevel@tonic-gate int ntp_gettime(struct ntptimeval *); 245*0Sstevel@tonic-gate int ntp_adjtime(struct timex *); 246*0Sstevel@tonic-gate #else 247*0Sstevel@tonic-gate int ntp_gettime(); 248*0Sstevel@tonic-gate int ntp_adjtime(); 249*0Sstevel@tonic-gate #endif /* __STDC__ */ 250*0Sstevel@tonic-gate 251*0Sstevel@tonic-gate #ifdef _KERNEL 252*0Sstevel@tonic-gate 253*0Sstevel@tonic-gate extern int32_t time_state; /* clock state */ 254*0Sstevel@tonic-gate extern int32_t time_status; /* clock status bits */ 255*0Sstevel@tonic-gate extern int32_t time_offset; /* time adjustment (us) */ 256*0Sstevel@tonic-gate extern int32_t time_freq; /* frequency offset (scaled ppm) */ 257*0Sstevel@tonic-gate extern int32_t time_maxerror; /* maximum error (us) */ 258*0Sstevel@tonic-gate extern int32_t time_esterror; /* estimated error (us) */ 259*0Sstevel@tonic-gate extern int32_t time_constant; /* pll time constant */ 260*0Sstevel@tonic-gate extern int32_t time_precision; /* clock precision (us) */ 261*0Sstevel@tonic-gate extern int32_t time_tolerance; /* frequency tolerance (scaled ppm) */ 262*0Sstevel@tonic-gate extern int32_t pps_shift; /* interval duration (s) (shift) */ 263*0Sstevel@tonic-gate extern int32_t pps_freq; /* pps frequency offset (scaled ppm) */ 264*0Sstevel@tonic-gate extern int32_t pps_jitter; /* pps jitter (us) */ 265*0Sstevel@tonic-gate extern int32_t pps_stabil; /* pps stability (scaled ppm) */ 266*0Sstevel@tonic-gate extern int32_t pps_jitcnt; /* jitter limit exceeded */ 267*0Sstevel@tonic-gate extern int32_t pps_calcnt; /* calibration intervals */ 268*0Sstevel@tonic-gate extern int32_t pps_errcnt; /* calibration errors */ 269*0Sstevel@tonic-gate extern int32_t pps_stbcnt; /* stability limit exceeded */ 270*0Sstevel@tonic-gate 271*0Sstevel@tonic-gate extern void clock_update(int); 272*0Sstevel@tonic-gate extern void ddi_hardpps(struct timeval *, int); 273*0Sstevel@tonic-gate 274*0Sstevel@tonic-gate #endif /* _KERNEL */ 275*0Sstevel@tonic-gate 276*0Sstevel@tonic-gate 277*0Sstevel@tonic-gate #ifdef __cplusplus 278*0Sstevel@tonic-gate } 279*0Sstevel@tonic-gate #endif 280*0Sstevel@tonic-gate 281*0Sstevel@tonic-gate #endif /* _SYS_TIMEX_H */ 282