/contrib/ntp/kernel/sys/timex.h

  1/******************************************************************************
  2 *                                                                            *
  3 * Copyright (c) David L. Mills 1993, 1994                                    *
  4 *                                                                            *
  5 * Permission to use, copy, modify, and distribute this software and its      *
  6 * documentation for any purpose and without fee is hereby granted, provided  *
  7 * that the above copyright notice appears in all copies and that both the    *
  8 * copyright notice and this permission notice appear in supporting           *
  9 * documentation, and that the name University of Delaware not be used in     *
 10 * advertising or publicity pertaining to distribution of the software        *
 11 * without specific, written prior permission.  The University of Delaware    *
 12 * makes no representations about the suitability this software for any       *
 13 * purpose.  It is provided "as is" without express or implied warranty.      *
 14 *                                                                            *
 15 ******************************************************************************/
 16
 17/*
 18 * Modification history timex.h
 19 *
 20 * 26 Sep 94	David L. Mills
 21 *	Added defines for hybrid phase/frequency-lock loop.
 22 *
 23 * 19 Mar 94	David L. Mills
 24 *	Moved defines from kernel routines to header file and added new
 25 *	defines for PPS phase-lock loop.
 26 *
 27 * 20 Feb 94	David L. Mills
 28 *	Revised status codes and structures for external clock and PPS
 29 *	signal discipline.
 30 *
 31 * 28 Nov 93	David L. Mills
 32 *	Adjusted parameters to improve stability and increase poll
 33 *	interval.
 34 *
 35 * 17 Sep 93    David L. Mills
 36 *      Created file
 37 */
 38/*
 39 * This header file defines the Network Time Protocol (NTP) interfaces
 40 * for user and daemon application programs. These are implemented using
 41 * private syscalls and data structures and require specific kernel
 42 * support.
 43 *
 44 * NAME
 45 *	ntp_gettime - NTP user application interface
 46 *
 47 * SYNOPSIS
 48 *	#include <sys/timex.h>
 49 *
 50 *	int syscall(SYS_ntp_gettime, tptr)
 51 *
 52 *	int SYS_ntp_gettime		defined in syscall.h header file
 53 *	struct ntptimeval *tptr		pointer to ntptimeval structure
 54 *
 55 * NAME
 56 *	ntp_adjtime - NTP daemon application interface
 57 *
 58 * SYNOPSIS
 59 *	#include <sys/timex.h>
 60 *
 61 *	int syscall(SYS_ntp_adjtime, mode, tptr)
 62 *
 63 *	int SYS_ntp_adjtime		defined in syscall.h header file
 64 *	struct timex *tptr		pointer to timex structure
 65 *
 66 */
 67#ifndef _SYS_TIMEX_H_
 68#define _SYS_TIMEX_H_ 1
 69
 70#ifndef MSDOS			/* Microsoft specific */
 71#include <sys/syscall.h>
 72#endif /* MSDOS */
 73
 74/*
 75 * The following defines establish the engineering parameters of the
 76 * phase-lock loop (PLL) model used in the kernel implementation. These
 77 * parameters have been carefully chosen by analysis for good stability
 78 * and wide dynamic range.
 79 *
 80 * The hz variable is defined in the kernel build environment. It
 81 * establishes the timer interrupt frequency, 100 Hz for the SunOS
 82 * kernel, 256 Hz for the Ultrix kernel and 1024 Hz for the OSF/1
 83 * kernel. SHIFT_HZ expresses the same value as the nearest power of two
 84 * in order to avoid hardware multiply operations.
 85 *
 86 * SHIFT_KG and SHIFT_KF establish the damping of the PLL and are chosen
 87 * for a slightly underdamped convergence characteristic. SHIFT_KH
 88 * establishes the damping of the FLL and is chosen by wisdom and black
 89 * art.
 90 *
 91 * MAXTC establishes the maximum time constant of the PLL. With the
 92 * SHIFT_KG and SHIFT_KF values given and a time constant range from
 93 * zero to MAXTC, the PLL will converge in 15 minutes to 16 hours,
 94 * respectively.
 95 */
 96#define SHIFT_HZ 7		/* log2(hz) */
 97#define SHIFT_KG 6		/* phase factor (shift) */
 98#define SHIFT_KF 16		/* PLL frequency factor (shift) */
 99#define SHIFT_KH 2		/* FLL frequency factor (shift) */
100#define MAXTC 6			/* maximum time constant (shift) */
101
102/*
103 * The following defines establish the scaling of the various variables
104 * used by the PLL. They are chosen to allow the greatest precision
105 * possible without overflow of a 32-bit word.
106 *
107 * SHIFT_SCALE defines the scaling (shift) of the time_phase variable,
108 * which serves as a an extension to the low-order bits of the system
109 * clock variable time.tv_usec.
110 *
111 * SHIFT_UPDATE defines the scaling (shift) of the time_offset variable,
112 * which represents the current time offset with respect to standard
113 * time.
114 *
115 * SHIFT_USEC defines the scaling (shift) of the time_freq and
116 * time_tolerance variables, which represent the current frequency
117 * offset and maximum frequency tolerance.
118 *
119 * FINEUSEC is 1 us in SHIFT_UPDATE units of the time_phase variable.
120 */
121#define SHIFT_SCALE 22		/* phase scale (shift) */
122#define SHIFT_UPDATE (SHIFT_KG + MAXTC) /* time offset scale (shift) */
123#define SHIFT_USEC 16		/* frequency offset scale (shift) */
124#define FINEUSEC (1L << SHIFT_SCALE) /* 1 us in phase units */
125
126/*
127 * The following defines establish the performance envelope of the PLL.
128 * They insure it operates within predefined limits, in order to satisfy
129 * correctness assertions. An excursion which exceeds these bounds is
130 * clamped to the bound and operation proceeds accordingly. In practice,
131 * this can occur only if something has failed or is operating out of
132 * tolerance, but otherwise the PLL continues to operate in a stable
133 * mode.
134 *
135 * MAXPHASE must be set greater than or equal to CLOCK.MAX (128 ms), as
136 * defined in the NTP specification. CLOCK.MAX establishes the maximum
137 * time offset allowed before the system time is reset, rather than
138 * incrementally adjusted. Here, the maximum offset is clamped to
139 * MAXPHASE only in order to prevent overflow errors due to defective
140 * protocol implementations.
141 *
142 * MAXFREQ is the maximum frequency tolerance of the CPU clock
143 * oscillator plus the maximum slew rate allowed by the protocol. It
144 * should be set to at least the frequency tolerance of the oscillator
145 * plus 100 ppm for vernier frequency adjustments. If the kernel
146 * PPS discipline code is configured (PPS_SYNC), the oscillator time and
147 * frequency are disciplined to an external source, presumably with
148 * negligible time and frequency error relative to UTC, and MAXFREQ can
149 * be reduced.
150 *
151 * MAXTIME is the maximum jitter tolerance of the PPS signal if the
152 * kernel PPS discipline code is configured (PPS_SYNC).
153 *
154 * MINSEC and MAXSEC define the lower and upper bounds on the interval
155 * between protocol updates.
156 */
157#define MAXPHASE 512000L	/* max phase error (us) */
158#ifdef PPS_SYNC
159#define MAXFREQ (512L << SHIFT_USEC) /* max freq error (100 ppm) */
160#define MAXTIME (200L << PPS_AVG) /* max PPS error (jitter) (200 us) */
161#else
162#define MAXFREQ (512L << SHIFT_USEC) /* max freq error (200 ppm) */
163#endif /* PPS_SYNC */
164#define MINSEC 16L		/* min interval between updates (s) */
165#define MAXSEC 1200L		/* max interval between updates (s) */
166
167#ifdef PPS_SYNC
168/*
169 * The following defines are used only if a pulse-per-second (PPS)
170 * signal is available and connected via a modem control lead, such as
171 * produced by the optional ppsclock feature incorporated in the Sun
172 * asynch driver. They establish the design parameters of the frequency-
173 * lock loop used to discipline the CPU clock oscillator to the PPS
174 * signal.
175 *
176 * PPS_AVG is the averaging factor for the frequency loop, as well as
177 * the time and frequency dispersion.
178 *
179 * PPS_SHIFT and PPS_SHIFTMAX specify the minimum and maximum
180 * calibration intervals, respectively, in seconds as a power of two.
181 *
182 * PPS_VALID is the maximum interval before the PPS signal is considered
183 * invalid and protocol updates used directly instead.
184 *
185 * MAXGLITCH is the maximum interval before a time offset of more than
186 * MAXTIME is believed.
187 */
188#define PPS_AVG 2		/* pps averaging constant (shift) */
189#define PPS_SHIFT 2		/* min interval duration (s) (shift) */
190#define PPS_SHIFTMAX 8		/* max interval duration (s) (shift) */
191#define PPS_VALID 120		/* pps signal watchdog max (s) */
192#define MAXGLITCH 30		/* pps signal glitch max (s) */
193#endif /* PPS_SYNC */
194
195/*
196 * The following defines and structures define the user interface for
197 * the ntp_gettime() and ntp_adjtime() system calls.
198 *
199 * Control mode codes (timex.modes)
200 */
201#define MOD_OFFSET	0x0001	/* set time offset */
202#define MOD_FREQUENCY	0x0002	/* set frequency offset */
203#define MOD_MAXERROR	0x0004	/* set maximum time error */
204#define MOD_ESTERROR	0x0008	/* set estimated time error */
205#define MOD_STATUS	0x0010	/* set clock status bits */
206#define MOD_TIMECONST	0x0020	/* set pll time constant */
207#define MOD_CANSCALE	0x0040	/* kernel can scale offset field */
208#define MOD_DOSCALE	0x0080	/* userland wants to scale offset field */
209
210/*
211 * Status codes (timex.status)
212 */
213#define STA_PLL		0x0001	/* enable PLL updates (rw) */
214#define STA_PPSFREQ	0x0002	/* enable PPS freq discipline (rw) */
215#define STA_PPSTIME	0x0004	/* enable PPS time discipline (rw) */
216#define STA_FLL		0x0008	/* select frequency-lock mode (rw) */
217
218#define STA_INS		0x0010	/* insert leap (rw) */
219#define STA_DEL		0x0020	/* delete leap (rw) */
220#define STA_UNSYNC	0x0040	/* clock unsynchronized (rw) */
221#define STA_FREQHOLD	0x0080	/* hold frequency (rw) */
222
223#define STA_PPSSIGNAL	0x0100	/* PPS signal present (ro) */
224#define STA_PPSJITTER	0x0200	/* PPS signal jitter exceeded (ro) */
225#define STA_PPSWANDER	0x0400	/* PPS signal wander exceeded (ro) */
226#define STA_PPSERROR	0x0800	/* PPS signal calibration error (ro) */
227
228#define STA_CLOCKERR	0x1000	/* clock hardware fault (ro) */
229
230#define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \
231    STA_PPSERROR | STA_CLOCKERR) /* read-only bits */
232
233/*
234 * Clock states (time_state)
235 */
236#define TIME_OK		0	/* no leap second warning */
237#define TIME_INS	1	/* insert leap second warning */
238#define TIME_DEL	2	/* delete leap second warning */
239#define TIME_OOP	3	/* leap second in progress */
240#define TIME_WAIT	4	/* leap second has occurred */
241#define TIME_ERROR	5	/* clock not synchronized */
242
243/*
244 * NTP user interface (ntp_gettime()) - used to read kernel clock values
245 *
246 * Note: maximum error = NTP synch distance = dispersion + delay / 2;
247 * estimated error = NTP dispersion.
248 */
249struct ntptimeval {
250	struct timeval time;	/* current time (ro) */
251	long maxerror;		/* maximum error (us) (ro) */
252	long esterror;		/* estimated error (us) (ro) */
253};
254
255/*
256 * NTP daemon interface - (ntp_adjtime()) used to discipline CPU clock
257 * oscillator
258 */
259struct timex {
260	unsigned int modes;	/* clock mode bits (wo) */
261	long offset;		/* time offset (us) (rw) */
262	long freq;		/* frequency offset (scaled ppm) (rw) */
263	long maxerror;		/* maximum error (us) (rw) */
264	long esterror;		/* estimated error (us) (rw) */
265	int status;		/* clock status bits (rw) */
266	long constant;		/* pll time constant (rw) */
267	long precision;		/* clock precision (us) (ro) */
268	long tolerance;		/* clock frequency tolerance (scaled
269				 * ppm) (ro) */
270	/*
271	 * The following read-only structure members are implemented
272	 * only if the PPS signal discipline is configured in the
273	 * kernel.
274	 */
275	long ppsfreq;		/* pps frequency (scaled ppm) (ro) */
276	long jitter;		/* pps jitter (us) (ro) */
277	int shift;		/* interval duration (s) (shift) (ro) */
278	long stabil;		/* pps stability (scaled ppm) (ro) */
279	long jitcnt;		/* jitter limit exceeded (ro) */
280	long calcnt;		/* calibration intervals (ro) */
281	long errcnt;		/* calibration errors (ro) */
282	long stbcnt;		/* stability limit exceeded (ro) */
283
284};
285#ifdef __FreeBSD__
286
287/*
288 * sysctl identifiers underneath kern.ntp_pll
289 */
290#define NTP_PLL_GETTIME	1	/* used by ntp_gettime() */
291#define NTP_PLL_MAXID	2	/* number of valid ids */
292
293#define NTP_PLL_NAMES { \
294			  { 0, 0 }, \
295			  { "gettime", CTLTYPE_STRUCT }, \
296		      }
297
298#ifndef KERNEL
299#include <sys/cdefs.h>
300
301__BEGIN_DECLS
302extern int ntp_gettime        __P((struct ntptimeval *));
303extern int ntp_adjtime        __P((struct timex *));
304__END_DECLS
305
306#endif /* not KERNEL */
307
308#endif /* __FreeBSD__ */
309#endif /* _SYS_TIMEX_H_ */