17c478bd9Sstevel@tonic-gate /* 27c478bd9Sstevel@tonic-gate * Copyright (c) David L. Mills 1993, 1994 37c478bd9Sstevel@tonic-gate * 47c478bd9Sstevel@tonic-gate * Permission to use, copy, modify, and distribute this software and its 57c478bd9Sstevel@tonic-gate * documentation for any purpose and without fee is hereby granted, provided 67c478bd9Sstevel@tonic-gate * that the above copyright notice appears in all copies and that both the 77c478bd9Sstevel@tonic-gate * copyright notice and this permission notice appear in supporting 87c478bd9Sstevel@tonic-gate * documentation, and that the name University of Delaware not be used in 97c478bd9Sstevel@tonic-gate * advertising or publicity pertaining to distribution of the software 107c478bd9Sstevel@tonic-gate * without specific, written prior permission. The University of Delaware 117c478bd9Sstevel@tonic-gate * makes no representations about the suitability this software for any 127c478bd9Sstevel@tonic-gate * purpose. It is provided "as is" without express or implied warranty. 137c478bd9Sstevel@tonic-gate */ 147c478bd9Sstevel@tonic-gate 157c478bd9Sstevel@tonic-gate /* 16*ba3594baSGarrett D'Amore * Copyright 2014 Garrett D'Amore <garrett@damore.org> 17*ba3594baSGarrett D'Amore * 187c478bd9Sstevel@tonic-gate * Copyright 1996-1997, 2002 Sun Microsystems, Inc. All rights reserved. 197c478bd9Sstevel@tonic-gate * Use is subject to license terms. 207c478bd9Sstevel@tonic-gate */ 217c478bd9Sstevel@tonic-gate 227c478bd9Sstevel@tonic-gate #ifndef _SYS_TIMEX_H 237c478bd9Sstevel@tonic-gate #define _SYS_TIMEX_H 247c478bd9Sstevel@tonic-gate 257c478bd9Sstevel@tonic-gate #ifdef __cplusplus 267c478bd9Sstevel@tonic-gate extern "C" { 277c478bd9Sstevel@tonic-gate #endif 287c478bd9Sstevel@tonic-gate 297c478bd9Sstevel@tonic-gate #include <sys/types.h> 307c478bd9Sstevel@tonic-gate #include <sys/time.h> 317c478bd9Sstevel@tonic-gate #include <sys/syscall.h> 327c478bd9Sstevel@tonic-gate #include <sys/inttypes.h> 337c478bd9Sstevel@tonic-gate 347c478bd9Sstevel@tonic-gate /* 357c478bd9Sstevel@tonic-gate * The following defines establish the engineering parameters of the 367c478bd9Sstevel@tonic-gate * phase-lock loop (PLL) model used in the kernel implementation. These 377c478bd9Sstevel@tonic-gate * parameters have been carefully chosen by analysis for good stability 387c478bd9Sstevel@tonic-gate * and wide dynamic range. 397c478bd9Sstevel@tonic-gate * 407c478bd9Sstevel@tonic-gate * The hz variable is defined in the kernel build environment. It 417c478bd9Sstevel@tonic-gate * establishes the timer interrupt frequency. 427c478bd9Sstevel@tonic-gate * 437c478bd9Sstevel@tonic-gate * SCALE_KG and SCALE_KF establish the damping of the PLL and are chosen 447c478bd9Sstevel@tonic-gate * for a slightly underdamped convergence characteristic. SCALE_KH 457c478bd9Sstevel@tonic-gate * establishes the damping of the FLL and is chosen by wisdom and black 467c478bd9Sstevel@tonic-gate * art. 477c478bd9Sstevel@tonic-gate * 487c478bd9Sstevel@tonic-gate * MAXTC establishes the maximum time constant of the PLL. With the 497c478bd9Sstevel@tonic-gate * SCALE_KG and SCALE_KF values given and a time constant range from 507c478bd9Sstevel@tonic-gate * zero to MAXTC, the PLL will converge in 15 minutes to 16 hours, 517c478bd9Sstevel@tonic-gate * respectively. 527c478bd9Sstevel@tonic-gate */ 537c478bd9Sstevel@tonic-gate #define SCALE_KG (1<<6) /* phase factor (multiplier) */ 547c478bd9Sstevel@tonic-gate #define SCALE_KF (1<<16) /* PLL frequency factor (multiplier) */ 557c478bd9Sstevel@tonic-gate #define SCALE_KH (1<<2) /* FLL frequency factor (multiplier) */ 567c478bd9Sstevel@tonic-gate #define MAXTC (1<<6) /* maximum time constant */ 577c478bd9Sstevel@tonic-gate 587c478bd9Sstevel@tonic-gate 597c478bd9Sstevel@tonic-gate /* 607c478bd9Sstevel@tonic-gate * The following defines establish the scaling of the various variables 617c478bd9Sstevel@tonic-gate * used by the PLL. They are chosen to allow the greatest precision 627c478bd9Sstevel@tonic-gate * possible without overflow of a 32-bit word. 637c478bd9Sstevel@tonic-gate * 647c478bd9Sstevel@tonic-gate * SCALE_PHASE defines the scaling (multiplier) of the time_phase variable, 657c478bd9Sstevel@tonic-gate * which serves as a an extension to the low-order bits of the system 667c478bd9Sstevel@tonic-gate * clock variable time.tv_usec. 677c478bd9Sstevel@tonic-gate * 687c478bd9Sstevel@tonic-gate * SCALE_UPDATE defines the scaling (multiplier) of the time_offset variable, 697c478bd9Sstevel@tonic-gate * which represents the current time offset with respect to standard 707c478bd9Sstevel@tonic-gate * time. 717c478bd9Sstevel@tonic-gate * 727c478bd9Sstevel@tonic-gate * SCALE_USEC defines the scaling (multiplier) of the time_freq and 737c478bd9Sstevel@tonic-gate * time_tolerance variables, which represent the current frequency 747c478bd9Sstevel@tonic-gate * offset and maximum frequency tolerance. 757c478bd9Sstevel@tonic-gate * 767c478bd9Sstevel@tonic-gate * FINEUSEC is 1 us in SCALE_UPDATE units of the time_phase variable. 777c478bd9Sstevel@tonic-gate */ 787c478bd9Sstevel@tonic-gate #define SCALE_PHASE (1<<22) /* phase scale */ 797c478bd9Sstevel@tonic-gate #define SCALE_USEC (1<<16) 807c478bd9Sstevel@tonic-gate #define SCALE_UPDATE (SCALE_KG * MAXTC) /* */ 817c478bd9Sstevel@tonic-gate #define FINEUSEC (1<<22) /* 1 us in phase units */ 827c478bd9Sstevel@tonic-gate 837c478bd9Sstevel@tonic-gate /* 847c478bd9Sstevel@tonic-gate * The following defines establish the performance envelope of the PLL. 857c478bd9Sstevel@tonic-gate * They insure it operates within predefined limits, in order to satisfy 867c478bd9Sstevel@tonic-gate * correctness assertions. An excursion which exceeds these bounds is 877c478bd9Sstevel@tonic-gate * clamped to the bound and operation proceeds accordingly. In practice, 887c478bd9Sstevel@tonic-gate * this can occur only if something has failed or is operating out of 897c478bd9Sstevel@tonic-gate * tolerance, but otherwise the PLL continues to operate in a stable 907c478bd9Sstevel@tonic-gate * mode. 917c478bd9Sstevel@tonic-gate * 927c478bd9Sstevel@tonic-gate * MAXPHASE must be set greater than or equal to CLOCK.MAX (128 ms), as 937c478bd9Sstevel@tonic-gate * defined in the NTP specification. CLOCK.MAX establishes the maximum 947c478bd9Sstevel@tonic-gate * time offset allowed before the system time is reset, rather than 957c478bd9Sstevel@tonic-gate * incrementally adjusted. Here, the maximum offset is clamped to 967c478bd9Sstevel@tonic-gate * MAXPHASE only in order to prevent overflow errors due to defective 977c478bd9Sstevel@tonic-gate * protocol implementations. 987c478bd9Sstevel@tonic-gate * 997c478bd9Sstevel@tonic-gate * MAXFREQ is the maximum frequency tolerance of the CPU clock 1007c478bd9Sstevel@tonic-gate * oscillator plus the maximum slew rate allowed by the protocol. It 1017c478bd9Sstevel@tonic-gate * should be set to at least the frequency tolerance of the oscillator 1027c478bd9Sstevel@tonic-gate * plus 100 ppm for vernier frequency adjustments. The oscillator time and 1037c478bd9Sstevel@tonic-gate * frequency are disciplined to an external source, presumably with 1047c478bd9Sstevel@tonic-gate * negligible time and frequency error relative to UTC, and MAXFREQ can 1057c478bd9Sstevel@tonic-gate * be reduced. 1067c478bd9Sstevel@tonic-gate * 1077c478bd9Sstevel@tonic-gate * MAXTIME is the maximum jitter tolerance of the PPS signal. 1087c478bd9Sstevel@tonic-gate * 1097c478bd9Sstevel@tonic-gate * MINSEC and MAXSEC define the lower and upper bounds on the interval 1107c478bd9Sstevel@tonic-gate * between protocol updates. 1117c478bd9Sstevel@tonic-gate */ 1127c478bd9Sstevel@tonic-gate #define MAXPHASE 512000 /* max phase error (us) */ 1137c478bd9Sstevel@tonic-gate #define MAXFREQ (512 * SCALE_USEC) /* max freq error (100 ppm) */ 1147c478bd9Sstevel@tonic-gate #define MAXTIME (200 << PPS_AVG) /* max PPS error (jitter) (200 us) */ 1157c478bd9Sstevel@tonic-gate #define MINSEC 16 /* min interval between updates (s) */ 1167c478bd9Sstevel@tonic-gate #define MAXSEC 1200 /* max interval between updates (s) */ 1177c478bd9Sstevel@tonic-gate 1187c478bd9Sstevel@tonic-gate /* 1197c478bd9Sstevel@tonic-gate * The following defines are used only if a pulse-per-second (PPS) 1207c478bd9Sstevel@tonic-gate * signal is available and connected via a modem control lead, such as 1217c478bd9Sstevel@tonic-gate * produced by the optional ppsclock feature incorporated in the Sun 1227c478bd9Sstevel@tonic-gate * asynch driver. They establish the design parameters of the frequency- 1237c478bd9Sstevel@tonic-gate * lock loop used to discipline the CPU clock oscillator to the PPS 1247c478bd9Sstevel@tonic-gate * signal. 1257c478bd9Sstevel@tonic-gate * 1267c478bd9Sstevel@tonic-gate * PPS_AVG is the averaging factor for the frequency loop, as well as 1277c478bd9Sstevel@tonic-gate * the time and frequency dispersion. 1287c478bd9Sstevel@tonic-gate * 1297c478bd9Sstevel@tonic-gate * PPS_SHIFT and PPS_SHIFTMAX specify the minimum and maximum 1307c478bd9Sstevel@tonic-gate * calibration intervals, respectively, in seconds as a power of two. 1317c478bd9Sstevel@tonic-gate * 1327c478bd9Sstevel@tonic-gate * PPS_VALID is the maximum interval before the PPS signal is considered 1337c478bd9Sstevel@tonic-gate * invalid and protocol updates used directly instead. 1347c478bd9Sstevel@tonic-gate * 1357c478bd9Sstevel@tonic-gate * MAXGLITCH is the maximum interval before a time offset of more than 1367c478bd9Sstevel@tonic-gate * MAXTIME is believed. 1377c478bd9Sstevel@tonic-gate */ 1387c478bd9Sstevel@tonic-gate #define PPS_AVG 2 /* pps averaging constant (shift) */ 1397c478bd9Sstevel@tonic-gate #define PPS_SHIFT 2 /* min interval duration (s) (shift) */ 1407c478bd9Sstevel@tonic-gate #define PPS_SHIFTMAX 8 /* max interval duration (s) (shift) */ 1417c478bd9Sstevel@tonic-gate #define PPS_VALID 120 /* pps signal watchdog max (s) */ 1427c478bd9Sstevel@tonic-gate #define MAXGLITCH 30 /* pps signal glitch max (s) */ 1437c478bd9Sstevel@tonic-gate 1447c478bd9Sstevel@tonic-gate /* 1457c478bd9Sstevel@tonic-gate * The following defines and structures define the user interface for 1467c478bd9Sstevel@tonic-gate * the ntp_gettime() and ntp_adjtime() system calls. 1477c478bd9Sstevel@tonic-gate * 1487c478bd9Sstevel@tonic-gate * Control mode codes (timex.modes) 1497c478bd9Sstevel@tonic-gate */ 1507c478bd9Sstevel@tonic-gate #define MOD_OFFSET 0x0001 /* set time offset */ 1517c478bd9Sstevel@tonic-gate #define MOD_FREQUENCY 0x0002 /* set frequency offset */ 1527c478bd9Sstevel@tonic-gate #define MOD_MAXERROR 0x0004 /* set maximum time error */ 1537c478bd9Sstevel@tonic-gate #define MOD_ESTERROR 0x0008 /* set estimated time error */ 1547c478bd9Sstevel@tonic-gate #define MOD_STATUS 0x0010 /* set clock status bits */ 1557c478bd9Sstevel@tonic-gate #define MOD_TIMECONST 0x0020 /* set pll time constant */ 1567c478bd9Sstevel@tonic-gate #define MOD_CLKB 0x4000 /* set clock B */ 1577c478bd9Sstevel@tonic-gate #define MOD_CLKA 0x8000 /* set clock A */ 1587c478bd9Sstevel@tonic-gate 1597c478bd9Sstevel@tonic-gate /* 1607c478bd9Sstevel@tonic-gate * Status codes (timex.status) 1617c478bd9Sstevel@tonic-gate */ 1627c478bd9Sstevel@tonic-gate #define STA_PLL 0x0001 /* enable PLL updates (rw) */ 1637c478bd9Sstevel@tonic-gate #define STA_PPSFREQ 0x0002 /* enable PPS freq discipline (rw) */ 1647c478bd9Sstevel@tonic-gate #define STA_PPSTIME 0x0004 /* enable PPS time discipline (rw) */ 1657c478bd9Sstevel@tonic-gate #define STA_FLL 0x0008 /* select frequency-lock mode (rw) */ 1667c478bd9Sstevel@tonic-gate 1677c478bd9Sstevel@tonic-gate #define STA_INS 0x0010 /* insert leap (rw) */ 1687c478bd9Sstevel@tonic-gate #define STA_DEL 0x0020 /* delete leap (rw) */ 1697c478bd9Sstevel@tonic-gate #define STA_UNSYNC 0x0040 /* clock unsynchronized (rw) */ 1707c478bd9Sstevel@tonic-gate #define STA_FREQHOLD 0x0080 /* hold frequency (rw) */ 1717c478bd9Sstevel@tonic-gate 1727c478bd9Sstevel@tonic-gate #define STA_PPSSIGNAL 0x0100 /* PPS signal present (ro) */ 1737c478bd9Sstevel@tonic-gate #define STA_PPSJITTER 0x0200 /* PPS signal jitter exceeded (ro) */ 1747c478bd9Sstevel@tonic-gate #define STA_PPSWANDER 0x0400 /* PPS signal wander exceeded (ro) */ 1757c478bd9Sstevel@tonic-gate #define STA_PPSERROR 0x0800 /* PPS signal calibration error (ro) */ 1767c478bd9Sstevel@tonic-gate 1777c478bd9Sstevel@tonic-gate #define STA_CLOCKERR 0x1000 /* clock hardware fault (ro) */ 1787c478bd9Sstevel@tonic-gate 1797c478bd9Sstevel@tonic-gate #define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \ 1807c478bd9Sstevel@tonic-gate STA_PPSERROR | STA_CLOCKERR) /* read-only bits */ 1817c478bd9Sstevel@tonic-gate 1827c478bd9Sstevel@tonic-gate /* 1837c478bd9Sstevel@tonic-gate * Clock states (time_state) 1847c478bd9Sstevel@tonic-gate */ 1857c478bd9Sstevel@tonic-gate #define TIME_OK 0 /* no leap second warning */ 1867c478bd9Sstevel@tonic-gate #define TIME_INS 1 /* insert leap second warning */ 1877c478bd9Sstevel@tonic-gate #define TIME_DEL 2 /* delete leap second warning */ 1887c478bd9Sstevel@tonic-gate #define TIME_OOP 3 /* leap second in progress */ 1897c478bd9Sstevel@tonic-gate #define TIME_WAIT 4 /* leap second has occured */ 1907c478bd9Sstevel@tonic-gate #define TIME_ERROR 5 /* clock not synchronized */ 1917c478bd9Sstevel@tonic-gate 1927c478bd9Sstevel@tonic-gate /* 1937c478bd9Sstevel@tonic-gate * NTP user interface (ntp_gettime()) - used to read kernel clock values 1947c478bd9Sstevel@tonic-gate * 1957c478bd9Sstevel@tonic-gate * Note: maximum error = NTP synch distance = dispersion + delay / 2; 1967c478bd9Sstevel@tonic-gate * estimated error = NTP dispersion. 1977c478bd9Sstevel@tonic-gate */ 1987c478bd9Sstevel@tonic-gate struct ntptimeval { 1997c478bd9Sstevel@tonic-gate struct timeval time; /* current time (ro) */ 2007c478bd9Sstevel@tonic-gate int32_t maxerror; /* maximum error (us) (ro) */ 2017c478bd9Sstevel@tonic-gate int32_t esterror; /* estimated error (us) (ro) */ 2027c478bd9Sstevel@tonic-gate }; 2037c478bd9Sstevel@tonic-gate 2047c478bd9Sstevel@tonic-gate #if defined(_SYSCALL32) 2057c478bd9Sstevel@tonic-gate 2067c478bd9Sstevel@tonic-gate /* Kernel's view of _ILP32 application's ntptimeval struct */ 2077c478bd9Sstevel@tonic-gate 2087c478bd9Sstevel@tonic-gate struct ntptimeval32 { 2097c478bd9Sstevel@tonic-gate struct timeval32 time; 2107c478bd9Sstevel@tonic-gate int32_t maxerror; 2117c478bd9Sstevel@tonic-gate int32_t esterror; 2127c478bd9Sstevel@tonic-gate }; 2137c478bd9Sstevel@tonic-gate 2147c478bd9Sstevel@tonic-gate #endif /* _SYSCALL32 */ 2157c478bd9Sstevel@tonic-gate 2167c478bd9Sstevel@tonic-gate /* 2177c478bd9Sstevel@tonic-gate * NTP daemon interface - (ntp_adjtime()) used to discipline CPU clock 2187c478bd9Sstevel@tonic-gate * oscillator 2197c478bd9Sstevel@tonic-gate */ 2207c478bd9Sstevel@tonic-gate struct timex { 2217c478bd9Sstevel@tonic-gate uint32_t modes; /* clock mode bits (wo) */ 2227c478bd9Sstevel@tonic-gate int32_t offset; /* time offset (us) (rw) */ 2237c478bd9Sstevel@tonic-gate int32_t freq; /* frequency offset (scaled ppm) (rw) */ 2247c478bd9Sstevel@tonic-gate int32_t maxerror; /* maximum error (us) (rw) */ 2257c478bd9Sstevel@tonic-gate int32_t esterror; /* estimated error (us) (rw) */ 2267c478bd9Sstevel@tonic-gate int32_t status; /* clock status bits (rw) */ 2277c478bd9Sstevel@tonic-gate int32_t constant; /* pll time constant (rw) */ 2287c478bd9Sstevel@tonic-gate int32_t precision; /* clock precision (us) (ro) */ 2297c478bd9Sstevel@tonic-gate int32_t tolerance; /* clock freq tolerance (scaled ppm) (ro) */ 2307c478bd9Sstevel@tonic-gate int32_t ppsfreq; /* pps frequency (scaled ppm) (ro) */ 2317c478bd9Sstevel@tonic-gate int32_t jitter; /* pps jitter (us) (ro) */ 2327c478bd9Sstevel@tonic-gate int32_t shift; /* interval duration (s) (shift) (ro) */ 2337c478bd9Sstevel@tonic-gate int32_t stabil; /* pps stability (scaled ppm) (ro) */ 2347c478bd9Sstevel@tonic-gate int32_t jitcnt; /* jitter limit exceeded (ro) */ 2357c478bd9Sstevel@tonic-gate int32_t calcnt; /* calibration intervals (ro) */ 2367c478bd9Sstevel@tonic-gate int32_t errcnt; /* calibration errors (ro) */ 2377c478bd9Sstevel@tonic-gate int32_t stbcnt; /* stability limit exceeded (ro) */ 2387c478bd9Sstevel@tonic-gate }; 2397c478bd9Sstevel@tonic-gate 2407c478bd9Sstevel@tonic-gate /* 2417c478bd9Sstevel@tonic-gate * NTP syscalls 2427c478bd9Sstevel@tonic-gate */ 2437c478bd9Sstevel@tonic-gate int ntp_gettime(struct ntptimeval *); 2447c478bd9Sstevel@tonic-gate int ntp_adjtime(struct timex *); 2457c478bd9Sstevel@tonic-gate 2467c478bd9Sstevel@tonic-gate #ifdef _KERNEL 2477c478bd9Sstevel@tonic-gate 2487c478bd9Sstevel@tonic-gate extern int32_t time_state; /* clock state */ 2497c478bd9Sstevel@tonic-gate extern int32_t time_status; /* clock status bits */ 2507c478bd9Sstevel@tonic-gate extern int32_t time_offset; /* time adjustment (us) */ 2517c478bd9Sstevel@tonic-gate extern int32_t time_freq; /* frequency offset (scaled ppm) */ 2527c478bd9Sstevel@tonic-gate extern int32_t time_maxerror; /* maximum error (us) */ 2537c478bd9Sstevel@tonic-gate extern int32_t time_esterror; /* estimated error (us) */ 2547c478bd9Sstevel@tonic-gate extern int32_t time_constant; /* pll time constant */ 2557c478bd9Sstevel@tonic-gate extern int32_t time_precision; /* clock precision (us) */ 2567c478bd9Sstevel@tonic-gate extern int32_t time_tolerance; /* frequency tolerance (scaled ppm) */ 2577c478bd9Sstevel@tonic-gate extern int32_t pps_shift; /* interval duration (s) (shift) */ 2587c478bd9Sstevel@tonic-gate extern int32_t pps_freq; /* pps frequency offset (scaled ppm) */ 2597c478bd9Sstevel@tonic-gate extern int32_t pps_jitter; /* pps jitter (us) */ 2607c478bd9Sstevel@tonic-gate extern int32_t pps_stabil; /* pps stability (scaled ppm) */ 2617c478bd9Sstevel@tonic-gate extern int32_t pps_jitcnt; /* jitter limit exceeded */ 2627c478bd9Sstevel@tonic-gate extern int32_t pps_calcnt; /* calibration intervals */ 2637c478bd9Sstevel@tonic-gate extern int32_t pps_errcnt; /* calibration errors */ 2647c478bd9Sstevel@tonic-gate extern int32_t pps_stbcnt; /* stability limit exceeded */ 2657c478bd9Sstevel@tonic-gate 2667c478bd9Sstevel@tonic-gate extern void clock_update(int); 2677c478bd9Sstevel@tonic-gate extern void ddi_hardpps(struct timeval *, int); 2687c478bd9Sstevel@tonic-gate 2697c478bd9Sstevel@tonic-gate #endif /* _KERNEL */ 2707c478bd9Sstevel@tonic-gate 2717c478bd9Sstevel@tonic-gate 2727c478bd9Sstevel@tonic-gate #ifdef __cplusplus 2737c478bd9Sstevel@tonic-gate } 2747c478bd9Sstevel@tonic-gate #endif 2757c478bd9Sstevel@tonic-gate 2767c478bd9Sstevel@tonic-gate #endif /* _SYS_TIMEX_H */ 277