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 26extern "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 */ 198struct 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 208struct 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 */ 220struct 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 */ 244int ntp_gettime(struct ntptimeval *); 245int ntp_adjtime(struct timex *); 246#else 247int ntp_gettime(); 248int ntp_adjtime(); 249#endif /* __STDC__ */ 250 251#ifdef _KERNEL 252 253extern int32_t time_state; /* clock state */ 254extern int32_t time_status; /* clock status bits */ 255extern int32_t time_offset; /* time adjustment (us) */ 256extern int32_t time_freq; /* frequency offset (scaled ppm) */ 257extern int32_t time_maxerror; /* maximum error (us) */ 258extern int32_t time_esterror; /* estimated error (us) */ 259extern int32_t time_constant; /* pll time constant */ 260extern int32_t time_precision; /* clock precision (us) */ 261extern int32_t time_tolerance; /* frequency tolerance (scaled ppm) */ 262extern int32_t pps_shift; /* interval duration (s) (shift) */ 263extern int32_t pps_freq; /* pps frequency offset (scaled ppm) */ 264extern int32_t pps_jitter; /* pps jitter (us) */ 265extern int32_t pps_stabil; /* pps stability (scaled ppm) */ 266extern int32_t pps_jitcnt; /* jitter limit exceeded */ 267extern int32_t pps_calcnt; /* calibration intervals */ 268extern int32_t pps_errcnt; /* calibration errors */ 269extern int32_t pps_stbcnt; /* stability limit exceeded */ 270 271extern void clock_update(int); 272extern 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