155714Skris/****************************************************************************** 255714Skris * * 355714Skris * Copyright (c) David L. Mills 1993, 1994 * 455714Skris * * 555714Skris * Permission to use, copy, modify, and distribute this software and its * 655714Skris * documentation for any purpose and without fee is hereby granted, provided * 755714Skris * that the above copyright notice appears in all copies and that both the * 855714Skris * copyright notice and this permission notice appear in supporting * 955714Skris * documentation, and that the name University of Delaware not be used in * 1055714Skris * advertising or publicity pertaining to distribution of the software * 1155714Skris * without specific, written prior permission. The University of Delaware * 1255714Skris * makes no representations about the suitability this software for any * 1355714Skris * purpose. It is provided "as is" without express or implied warranty. * 1455714Skris * * 1555714Skris ******************************************************************************/ 1655714Skris 1755714Skris/* 1855714Skris * Modification history timex.h 1955714Skris * 2055714Skris * 26 Sep 94 David L. Mills 2155714Skris * Added defines for hybrid phase/frequency-lock loop. 2255714Skris * 2355714Skris * 19 Mar 94 David L. Mills 2455714Skris * Moved defines from kernel routines to header file and added new 2555714Skris * defines for PPS phase-lock loop. 2655714Skris * 2755714Skris * 20 Feb 94 David L. Mills 2855714Skris * Revised status codes and structures for external clock and PPS 2955714Skris * signal discipline. 3055714Skris * 3155714Skris * 28 Nov 93 David L. Mills 3255714Skris * Adjusted parameters to improve stability and increase poll 3355714Skris * interval. 3455714Skris * 3555714Skris * 17 Sep 93 David L. Mills 3655714Skris * Created file 3755714Skris */ 3855714Skris/* 3955714Skris * This header file defines the Network Time Protocol (NTP) interfaces 4055714Skris * for user and daemon application programs. These are implemented using 4155714Skris * private syscalls and data structures and require specific kernel 4255714Skris * support. 4355714Skris * 4455714Skris * NAME 4555714Skris * ntp_gettime - NTP user application interface 4655714Skris * 4755714Skris * SYNOPSIS 4855714Skris * #include <sys/timex.h> 4955714Skris * 5055714Skris * int syscall(SYS_ntp_gettime, tptr) 5155714Skris * 5255714Skris * int SYS_ntp_gettime defined in syscall.h header file 5355714Skris * struct ntptimeval *tptr pointer to ntptimeval structure 5455714Skris * 5555714Skris * NAME 5655714Skris * ntp_adjtime - NTP daemon application interface 5755714Skris * 5855714Skris * SYNOPSIS 5955714Skris * #include <sys/timex.h> 6055714Skris * 6155714Skris * int syscall(SYS_ntp_adjtime, mode, tptr) 6268651Skris * 6368651Skris * int SYS_ntp_adjtime defined in syscall.h header file 6468651Skris * struct timex *tptr pointer to timex structure 6555714Skris * 6655714Skris */ 6755714Skris#ifndef _SYS_TIMEX_H_ 6855714Skris#define _SYS_TIMEX_H_ 1 6955714Skris 7055714Skris#ifndef MSDOS /* Microsoft specific */ 7155714Skris#include <sys/syscall.h> 7255714Skris#endif /* MSDOS */ 7355714Skris 7455714Skris/* 7555714Skris * The following defines establish the engineering parameters of the 7655714Skris * phase-lock loop (PLL) model used in the kernel implementation. These 7755714Skris * parameters have been carefully chosen by analysis for good stability 7855714Skris * and wide dynamic range. 7955714Skris * 8055714Skris * The hz variable is defined in the kernel build environment. It 8155714Skris * establishes the timer interrupt frequency, 100 Hz for the SunOS 8255714Skris * kernel, 256 Hz for the Ultrix kernel and 1024 Hz for the OSF/1 8355714Skris * kernel. SHIFT_HZ expresses the same value as the nearest power of two 8455714Skris * in order to avoid hardware multiply operations. 8555714Skris * 8655714Skris * SHIFT_KG and SHIFT_KF establish the damping of the PLL and are chosen 8755714Skris * for a slightly underdamped convergence characteristic. SHIFT_KH 8855714Skris * establishes the damping of the FLL and is chosen by wisdom and black 8955714Skris * art. 9055714Skris * 9155714Skris * MAXTC establishes the maximum time constant of the PLL. With the 9255714Skris * SHIFT_KG and SHIFT_KF values given and a time constant range from 9355714Skris * zero to MAXTC, the PLL will converge in 15 minutes to 16 hours, 9455714Skris * respectively. 9555714Skris */ 9655714Skris#define SHIFT_HZ 7 /* log2(hz) */ 9755714Skris#define SHIFT_KG 6 /* phase factor (shift) */ 9855714Skris#define SHIFT_KF 16 /* PLL frequency factor (shift) */ 9955714Skris#define SHIFT_KH 2 /* FLL frequency factor (shift) */ 10055714Skris#define MAXTC 6 /* maximum time constant (shift) */ 10155714Skris 10255714Skris/* 10355714Skris * The following defines establish the scaling of the various variables 10455714Skris * used by the PLL. They are chosen to allow the greatest precision 10555714Skris * possible without overflow of a 32-bit word. 10655714Skris * 10755714Skris * SHIFT_SCALE defines the scaling (shift) of the time_phase variable, 10855714Skris * which serves as a an extension to the low-order bits of the system 10955714Skris * clock variable time.tv_usec. 11055714Skris * 11168651Skris * SHIFT_UPDATE defines the scaling (shift) of the time_offset variable, 11268651Skris * which represents the current time offset with respect to standard 11355714Skris * time. 11455714Skris * 11555714Skris * SHIFT_USEC defines the scaling (shift) of the time_freq and 11655714Skris * time_tolerance variables, which represent the current frequency 11755714Skris * offset and maximum frequency tolerance. 11855714Skris * 11968651Skris * FINEUSEC is 1 us in SHIFT_UPDATE units of the time_phase variable. 12055714Skris */ 12155714Skris#define SHIFT_SCALE 22 /* phase scale (shift) */ 12255714Skris#define SHIFT_UPDATE (SHIFT_KG + MAXTC) /* time offset scale (shift) */ 12355714Skris#define SHIFT_USEC 16 /* frequency offset scale (shift) */ 12455714Skris#define FINEUSEC (1L << SHIFT_SCALE) /* 1 us in phase units */ 12568651Skris 12668651Skris/* 12768651Skris * The following defines establish the performance envelope of the PLL. 12868651Skris * They insure it operates within predefined limits, in order to satisfy 12955714Skris * correctness assertions. An excursion which exceeds these bounds is 13055714Skris * clamped to the bound and operation proceeds accordingly. In practice, 13155714Skris * this can occur only if something has failed or is operating out of 13255714Skris * tolerance, but otherwise the PLL continues to operate in a stable 13355714Skris * mode. 13455714Skris * 13555714Skris * MAXPHASE must be set greater than or equal to CLOCK.MAX (128 ms), as 13655714Skris * defined in the NTP specification. CLOCK.MAX establishes the maximum 13755714Skris * time offset allowed before the system time is reset, rather than 13855714Skris * incrementally adjusted. Here, the maximum offset is clamped to 13955714Skris * MAXPHASE only in order to prevent overflow errors due to defective 14055714Skris * protocol implementations. 14155714Skris * 14255714Skris * MAXFREQ is the maximum frequency tolerance of the CPU clock 143109998Smarkm * oscillator plus the maximum slew rate allowed by the protocol. It 14455714Skris * should be set to at least the frequency tolerance of the oscillator 145109998Smarkm * plus 100 ppm for vernier frequency adjustments. If the kernel 146109998Smarkm * PPS discipline code is configured (PPS_SYNC), the oscillator time and 14755714Skris * frequency are disciplined to an external source, presumably with 148109998Smarkm * negligible time and frequency error relative to UTC, and MAXFREQ can 149109998Smarkm * be reduced. 15055714Skris * 151109998Smarkm * MAXTIME is the maximum jitter tolerance of the PPS signal if the 152109998Smarkm * kernel PPS discipline code is configured (PPS_SYNC). 153109998Smarkm * 154109998Smarkm * MINSEC and MAXSEC define the lower and upper bounds on the interval 15555714Skris * between protocol updates. 156109998Smarkm */ 157109998Smarkm#define MAXPHASE 512000L /* max phase error (us) */ 15855714Skris#ifdef PPS_SYNC 159109998Smarkm#define MAXFREQ (512L << SHIFT_USEC) /* max freq error (100 ppm) */ 160109998Smarkm#define MAXTIME (200L << PPS_AVG) /* max PPS error (jitter) (200 us) */ 161109998Smarkm#else 16255714Skris#define MAXFREQ (512L << SHIFT_USEC) /* max freq error (200 ppm) */ 16355714Skris#endif /* PPS_SYNC */ 16455714Skris#define MINSEC 16L /* min interval between updates (s) */ 16555714Skris#define MAXSEC 1200L /* max interval between updates (s) */ 16655714Skris 16755714Skris#ifdef PPS_SYNC 16855714Skris/* 16955714Skris * The following defines are used only if a pulse-per-second (PPS) 17055714Skris * signal is available and connected via a modem control lead, such as 17155714Skris * produced by the optional ppsclock feature incorporated in the Sun 172109998Smarkm * asynch driver. They establish the design parameters of the frequency- 173109998Smarkm * lock loop used to discipline the CPU clock oscillator to the PPS 174109998Smarkm * signal. 175109998Smarkm * 176109998Smarkm * PPS_AVG is the averaging factor for the frequency loop, as well as 177109998Smarkm * the time and frequency dispersion. 178109998Smarkm * 17955714Skris * PPS_SHIFT and PPS_SHIFTMAX specify the minimum and maximum 180109998Smarkm * calibration intervals, respectively, in seconds as a power of two. 181109998Smarkm * 182109998Smarkm * PPS_VALID is the maximum interval before the PPS signal is considered 18355714Skris * invalid and protocol updates used directly instead. 18455714Skris * 18555714Skris * MAXGLITCH is the maximum interval before a time offset of more than 18655714Skris * MAXTIME is believed. 18755714Skris */ 18855714Skris#define PPS_AVG 2 /* pps averaging constant (shift) */ 18955714Skris#define PPS_SHIFT 2 /* min interval duration (s) (shift) */ 19055714Skris#define PPS_SHIFTMAX 8 /* max interval duration (s) (shift) */ 19168651Skris#define PPS_VALID 120 /* pps signal watchdog max (s) */ 192109998Smarkm#define MAXGLITCH 30 /* pps signal glitch max (s) */ 19355714Skris#endif /* PPS_SYNC */ 19455714Skris 19568651Skris/* 196109998Smarkm * The following defines and structures define the user interface for 197109998Smarkm * the ntp_gettime() and ntp_adjtime() system calls. 198109998Smarkm * 199109998Smarkm * Control mode codes (timex.modes) 200109998Smarkm */ 20155714Skris#define MOD_OFFSET 0x0001 /* set time offset */ 20255714Skris#define MOD_FREQUENCY 0x0002 /* set frequency offset */ 20355714Skris#define MOD_MAXERROR 0x0004 /* set maximum time error */ 204109998Smarkm#define MOD_ESTERROR 0x0008 /* set estimated time error */ 205109998Smarkm#define MOD_STATUS 0x0010 /* set clock status bits */ 20655714Skris#define MOD_TIMECONST 0x0020 /* set pll time constant */ 20755714Skris#define MOD_CANSCALE 0x0040 /* kernel can scale offset field */ 20855714Skris#define MOD_DOSCALE 0x0080 /* userland wants to scale offset field */ 20955714Skris 21055714Skris/* 21155714Skris * Status codes (timex.status) 21255714Skris */ 21355714Skris#define STA_PLL 0x0001 /* enable PLL updates (rw) */ 214109998Smarkm#define STA_PPSFREQ 0x0002 /* enable PPS freq discipline (rw) */ 215109998Smarkm#define STA_PPSTIME 0x0004 /* enable PPS time discipline (rw) */ 216109998Smarkm#define STA_FLL 0x0008 /* select frequency-lock mode (rw) */ 217109998Smarkm 218109998Smarkm#define STA_INS 0x0010 /* insert leap (rw) */ 21955714Skris#define STA_DEL 0x0020 /* delete leap (rw) */ 22055714Skris#define STA_UNSYNC 0x0040 /* clock unsynchronized (rw) */ 22155714Skris#define STA_FREQHOLD 0x0080 /* hold frequency (rw) */ 22255714Skris 22355714Skris#define STA_PPSSIGNAL 0x0100 /* PPS signal present (ro) */ 22455714Skris#define STA_PPSJITTER 0x0200 /* PPS signal jitter exceeded (ro) */ 225109998Smarkm#define STA_PPSWANDER 0x0400 /* PPS signal wander exceeded (ro) */ 22655714Skris#define STA_PPSERROR 0x0800 /* PPS signal calibration error (ro) */ 22755714Skris 22855714Skris#define STA_CLOCKERR 0x1000 /* clock hardware fault (ro) */ 22955714Skris 23055714Skris#define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \ 23155714Skris STA_PPSERROR | STA_CLOCKERR) /* read-only bits */ 232109998Smarkm 23355714Skris/* 234109998Smarkm * Clock states (time_state) 23572613Skris */ 23655714Skris#define TIME_OK 0 /* no leap second warning */ 237109998Smarkm#define TIME_INS 1 /* insert leap second warning */ 238109998Smarkm#define TIME_DEL 2 /* delete leap second warning */ 239109998Smarkm#define TIME_OOP 3 /* leap second in progress */ 240109998Smarkm#define TIME_WAIT 4 /* leap second has occurred */ 241109998Smarkm#define TIME_ERROR 5 /* clock not synchronized */ 242109998Smarkm 243109998Smarkm/* 244109998Smarkm * NTP user interface (ntp_gettime()) - used to read kernel clock values 245109998Smarkm * 24655714Skris * Note: maximum error = NTP synch distance = dispersion + delay / 2; 24755714Skris * estimated error = NTP dispersion. 24859191Skris */ 24955714Skrisstruct ntptimeval { 25059191Skris struct timeval time; /* current time (ro) */ 25155714Skris long maxerror; /* maximum error (us) (ro) */ 25255714Skris long esterror; /* estimated error (us) (ro) */ 25355714Skris}; 25455714Skris 25555714Skris/* 25659191Skris * NTP daemon interface - (ntp_adjtime()) used to discipline CPU clock 25755714Skris * oscillator 25855714Skris */ 25955714Skrisstruct timex { 26055714Skris unsigned int modes; /* clock mode bits (wo) */ 26155714Skris long offset; /* time offset (us) (rw) */ 26289837Skris long freq; /* frequency offset (scaled ppm) (rw) */ 26355714Skris long maxerror; /* maximum error (us) (rw) */ 26455714Skris long esterror; /* estimated error (us) (rw) */ 26555714Skris int status; /* clock status bits (rw) */ 26655714Skris long constant; /* pll time constant (rw) */ 26755714Skris long precision; /* clock precision (us) (ro) */ 26855714Skris long tolerance; /* clock frequency tolerance (scaled 26955714Skris * ppm) (ro) */ 27055714Skris /* 27155714Skris * The following read-only structure members are implemented 27255714Skris * only if the PPS signal discipline is configured in the 27355714Skris * kernel. 27455714Skris */ 27555714Skris long ppsfreq; /* pps frequency (scaled ppm) (ro) */ 27655714Skris long jitter; /* pps jitter (us) (ro) */ 27755714Skris int shift; /* interval duration (s) (shift) (ro) */ 27855714Skris long stabil; /* pps stability (scaled ppm) (ro) */ 27955714Skris long jitcnt; /* jitter limit exceeded (ro) */ 28055714Skris long calcnt; /* calibration intervals (ro) */ 28159191Skris long errcnt; /* calibration errors (ro) */ 28255714Skris long stbcnt; /* stability limit exceeded (ro) */ 28355714Skris 28455714Skris}; 28555714Skris#ifdef __FreeBSD__ 28655714Skris 28755714Skris/* 28855714Skris * sysctl identifiers underneath kern.ntp_pll 28955714Skris */ 29055714Skris#define NTP_PLL_GETTIME 1 /* used by ntp_gettime() */ 29155714Skris#define NTP_PLL_MAXID 2 /* number of valid ids */ 29255714Skris 29355714Skris#define NTP_PLL_NAMES { \ 29455714Skris { 0, 0 }, \ 29555714Skris { "gettime", CTLTYPE_STRUCT }, \ 29655714Skris } 29755714Skris 29855714Skris#ifndef KERNEL 29959191Skris#include <sys/cdefs.h> 30055714Skris 30155714Skris__BEGIN_DECLS 30255714Skrisextern int ntp_gettime __P((struct ntptimeval *)); 30355714Skrisextern int ntp_adjtime __P((struct timex *)); 30455714Skris__END_DECLS 30555714Skris 30655714Skris#endif /* not KERNEL */ 30755714Skris 30855714Skris#endif /* __FreeBSD__ */ 30955714Skris#endif /* _SYS_TIMEX_H_ */ 31055714Skris