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 */