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