xref: /illumos-gate/usr/src/uts/common/sys/timex.h (revision ba3594ba)
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 2014 Garrett D'Amore <garrett@damore.org>
17  *
18  * Copyright 1996-1997, 2002 Sun Microsystems, Inc.  All rights reserved.
19  * Use is subject to license terms.
20  */
21 
22 #ifndef	_SYS_TIMEX_H
23 #define	_SYS_TIMEX_H
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 /*
241  * NTP syscalls
242  */
243 int ntp_gettime(struct ntptimeval *);
244 int ntp_adjtime(struct timex *);
245 
246 #ifdef _KERNEL
247 
248 extern int32_t time_state;	/* clock state */
249 extern int32_t time_status;	/* clock status bits */
250 extern int32_t time_offset;	/* time adjustment (us) */
251 extern int32_t time_freq;	/* frequency offset (scaled ppm) */
252 extern int32_t time_maxerror;	/* maximum error (us) */
253 extern int32_t time_esterror;	/* estimated error (us) */
254 extern int32_t time_constant;	/* pll time constant */
255 extern int32_t time_precision;	/* clock precision (us) */
256 extern int32_t time_tolerance;	/* frequency tolerance (scaled ppm) */
257 extern int32_t pps_shift;	/* interval duration (s) (shift) */
258 extern int32_t pps_freq;	/* pps frequency offset (scaled ppm) */
259 extern int32_t pps_jitter;	/* pps jitter (us) */
260 extern int32_t pps_stabil;	/* pps stability (scaled ppm) */
261 extern int32_t pps_jitcnt;	/* jitter limit exceeded */
262 extern int32_t pps_calcnt;	/* calibration intervals */
263 extern int32_t pps_errcnt;	/* calibration errors */
264 extern int32_t pps_stbcnt;	/* stability limit exceeded */
265 
266 extern void clock_update(int);
267 extern void ddi_hardpps(struct timeval *, int);
268 
269 #endif /* _KERNEL */
270 
271 
272 #ifdef	__cplusplus
273 }
274 #endif
275 
276 #endif	/* _SYS_TIMEX_H */
277