Integrate the new "nanokernel" PLL from Dave Mills.

This code is backwards compatible with the older "microkernel" PLL, but
allows ntpd v4 to use nanosecond resolution.  Many other improvements.

PPS_SYNC and hardpps() are NOT supported yet.

1 files changed, 107 insertions, 190 deletions

diff --git a/sys/sys/timex.h b/sys/sys/timex.h
index 47fd808..a829045 100644
--- a/sys/sys/timex.h
+++ b/sys/sys/timex.h
@@ -1,22 +1,27 @@
-/******************************************************************************
- *                                                                            *
- * Copyright (c) David L. Mills 1993, 1994                                    *
- *                                                                            *
- * Permission to use, copy, modify, and distribute this software and its      *
- * documentation for any purpose and without fee is hereby granted, provided  *
- * that the above copyright notice appears in all copies and that both the    *
- * copyright notice and this permission notice appear in supporting           *
- * documentation, and that the name University of Delaware not be used in     *
- * advertising or publicity pertaining to distribution of the software        *
- * without specific, written prior permission.  The University of Delaware    *
- * makes no representations about the suitability this software for any       *
- * purpose.  It is provided "as is" without express or implied warranty.      *
- *                                                                            *
- ******************************************************************************/
+/***********************************************************************
+ *								       *
+ * Copyright (c) David L. Mills 1993-1998			       *
+ *								       *
+ * Permission to use, copy, modify, and distribute this software and   *
+ * its documentation for any purpose and without fee is hereby	       *
+ * granted, provided that the above copyright notice appears in all    *
+ * copies and that both the copyright notice and this permission       *
+ * notice appear in supporting documentation, and that the name        *
+ * University of Delaware not be used in advertising or publicity      *
+ * pertaining to distribution of the software without specific,	       *
+ * written prior permission. The University of Delaware makes no       *
+ * representations about the suitability this software for any	       *
+ * purpose. It is provided "as is" without express or implied	       *
+ * warranty.							       *
+ *								       *
+ **********************************************************************/
 
 /*
  * Modification history timex.h
  *
+ * 17 Nov 98	David L. Mills
+ *	Revised for nanosecond kernel and user interface.
+ *
  * 26 Sep 94	David L. Mills
  *	Added defines for hybrid phase/frequency-lock loop.
  *
@@ -38,31 +43,50 @@
 /*
  * This header file defines the Network Time Protocol (NTP) interfaces
  * for user and daemon application programs. These are implemented using
- * private syscalls and data structures and require specific kernel
+ * defined syscalls and data structures and require specific kernel
  * support.
  *
+ * The original precision time kernels developed from 1993 have an
+ * ultimate resolution of one microsecond; however, the most recent
+ * kernels have an ultimate resolution of one nanosecond. In these
+ * kernels, a ntp_adjtime() syscalls can be used to determine which
+ * resolution is in use and to select either one at any time. The
+ * resolution selected affects the scaling of certain fields in the
+ * ntp_gettime() and ntp_adjtime() syscalls, as described below.
+ *
  * NAME
  *	ntp_gettime - NTP user application interface
  *
  * SYNOPSIS
  *	#include <sys/timex.h>
+ *	#include <sys/syscall.h>
  *
- *	int syscall(SYS_ntp_gettime, tptr)
+ *	int syscall(SYS_ntp_gettime, tptr);
+ *	int SYS_ntp_gettime;
+ *	struct ntptimeval *tptr;
  *
- *	int SYS_ntp_gettime		defined in syscall.h header file
- *	struct ntptimeval *tptr		pointer to ntptimeval structure
+ * DESCRIPTION
+ *	The time returned by ntp_gettime() is in a timeval structure,
+ *	but may be in either microsecond (seconds and microseconds) or
+ *	nanosecond (seconds and nanoseconds) format. The particular
+ *	format in use is determined by the STA_NANO bit of the status
+ *	word returned by the ntp_adjtime() syscall.
  *
  * NAME
  *	ntp_adjtime - NTP daemon application interface
  *
  * SYNOPSIS
  *	#include <sys/timex.h>
+ *	#include <sys/syscall.h>
  *
- *	int syscall(SYS_ntp_adjtime, mode, tptr)
- *
- *	int SYS_ntp_adjtime		defined in syscall.h header file
- *	struct timex *tptr		pointer to timex structure
+ *	int syscall(SYS_ntp_adjtime, tptr);
+ *	struct timex *tptr;
  *
+ * DESCRIPTION
+ *	Certain fields of the timex structure are interpreted in either
+ *	microseconds or nanoseconds according to the state of the
+ *	STA_NANO bit in the status word. See the description below for
+ *	further information.
  */
 #ifndef _SYS_TIMEX_H_
 #define _SYS_TIMEX_H_ 1
@@ -72,138 +96,40 @@
 #endif /* MSDOS */
 
 /*
- * The following defines establish the engineering parameters of the
- * phase-lock loop (PLL) model used in the kernel implementation. These
- * parameters have been carefully chosen by analysis for good stability
- * and wide dynamic range.
- *
- * The hz variable is defined in the kernel build environment. It
- * establishes the timer interrupt frequency, 100 Hz for the SunOS
- * kernel, 256 Hz for the Ultrix kernel and 1024 Hz for the OSF/1
- * kernel. SHIFT_HZ expresses the same value as the nearest power of two
- * in order to avoid hardware multiply operations.
- *
- * SHIFT_KG and SHIFT_KF establish the damping of the PLL and are chosen
- * for a slightly underdamped convergence characteristic. SHIFT_KH
- * establishes the damping of the FLL and is chosen by wisdom and black
- * art.
- *
- * MAXTC establishes the maximum time constant of the PLL. With the
- * SHIFT_KG and SHIFT_KF values given and a time constant range from
- * zero to MAXTC, the PLL will converge in 15 minutes to 16 hours,
- * respectively.
- */
-#define SHIFT_HZ 7		/* log2(hz) */
-#define SHIFT_KG 6		/* phase factor (shift) */
-#define SHIFT_KF 16		/* PLL frequency factor (shift) */
-#define SHIFT_KH 2		/* FLL frequency factor (shift) */
-#define MAXTC 6			/* maximum time constant (shift) */
-
-/*
- * The following defines establish the scaling of the various variables
- * used by the PLL. They are chosen to allow the greatest precision
- * possible without overflow of a 32-bit word.
- *
- * SHIFT_SCALE defines the scaling (shift) of the time_phase variable,
- * which serves as a an extension to the low-order bits of the system
- * clock variable time.tv_usec.
- *
- * SHIFT_UPDATE defines the scaling (shift) of the time_offset variable,
- * which represents the current time offset with respect to standard
- * time.
- *
- * SHIFT_USEC defines the scaling (shift) of the time_freq and
- * time_tolerance variables, which represent the current frequency
- * offset and maximum frequency tolerance.
- *
- * FINEUSEC is 1 us in SHIFT_UPDATE units of the time_phase variable.
- */
-#define SHIFT_SCALE 22		/* phase scale (shift) */
-#define SHIFT_UPDATE (SHIFT_KG + MAXTC) /* time offset scale (shift) */
-#define SHIFT_USEC 16		/* frequency offset scale (shift) */
-#define FINEUSEC (1L << SHIFT_SCALE) /* 1 us in phase units */
-
-/*
- * The following defines establish the performance envelope of the PLL.
- * They insure it operates within predefined limits, in order to satisfy
- * correctness assertions. An excursion which exceeds these bounds is
- * clamped to the bound and operation proceeds accordingly. In practice,
- * this can occur only if something has failed or is operating out of
- * tolerance, but otherwise the PLL continues to operate in a stable
- * mode.
- *
- * MAXPHASE must be set greater than or equal to CLOCK.MAX (128 ms), as
- * defined in the NTP specification. CLOCK.MAX establishes the maximum
- * time offset allowed before the system time is reset, rather than
- * incrementally adjusted. Here, the maximum offset is clamped to
- * MAXPHASE only in order to prevent overflow errors due to defective
- * protocol implementations.
- *
- * MAXFREQ is the maximum frequency tolerance of the CPU clock
- * oscillator plus the maximum slew rate allowed by the protocol. It
- * should be set to at least the frequency tolerance of the oscillator
- * plus 100 ppm for vernier frequency adjustments. If the kernel
- * PPS discipline code is configured (PPS_SYNC), the oscillator time and
- * frequency are disciplined to an external source, presumably with
- * negligible time and frequency error relative to UTC, and MAXFREQ can
- * be reduced.
- *
- * MAXTIME is the maximum jitter tolerance of the PPS signal if the
- * kernel PPS discipline code is configured (PPS_SYNC).
- *
- * MINSEC and MAXSEC define the lower and upper bounds on the interval
- * between protocol updates.
- */
-#define MAXPHASE 512000L	/* max phase error (us) */
-#ifdef PPS_SYNC
-#define MAXFREQ (512L << SHIFT_USEC) /* max freq error (100 ppm) */
-#define MAXTIME (200L << PPS_AVG) /* max PPS error (jitter) (200 us) */
-#else
-#define MAXFREQ (512L << SHIFT_USEC) /* max freq error (200 ppm) */
-#endif /* PPS_SYNC */
-#define MINSEC 16L		/* min interval between updates (s) */
-#define MAXSEC 1200L		/* max interval between updates (s) */
-
-/*
- * The following defines are used only if a pulse-per-second (PPS)
- * signal is available and connected via a modem control lead, such as
- * produced by the optional ppsclock feature incorporated in the Sun
- * asynch driver. They establish the design parameters of the frequency-
- * lock loop used to discipline the CPU clock oscillator to the PPS
- * signal.
- *
- * PPS_AVG is the averaging factor for the frequency loop, as well as
- * the time and frequency dispersion.
- *
- * PPS_SHIFT and PPS_SHIFTMAX specify the minimum and maximum
- * calibration intervals, respectively, in seconds as a power of two.
- *
- * PPS_VALID is the maximum interval before the PPS signal is considered
- * invalid and protocol updates used directly instead.
- *
- * MAXGLITCH is the maximum interval before a time offset of more than
- * MAXTIME is believed.
+ * The following defines establish the performance envelope of the
+ * kernel discipline loop. Phase or frequency errors greater than
+ * NAXPHASE or MAXFREQ are clamped to these maxima. For update intervals
+ * less than MINSEC, the loop always operates in PLL mode; while, for
+ * update intervals greater than MAXSEC, the loop always operates in FLL
+ * mode. Between these two limits the operating mode is selected by the
+ * STA_FLL bit in the status word.
  */
-#define PPS_AVG 2		/* pps averaging constant (shift) */
-#define PPS_SHIFT 2		/* min interval duration (s) (shift) */
-#define PPS_SHIFTMAX 8		/* max interval duration (s) (shift) */
-#define PPS_VALID 120		/* pps signal watchdog max (s) */
-#define MAXGLITCH 30		/* pps signal glitch max (s) */
+#define MAXPHASE	500000000L /* max phase error (ns) */
+#define MAXFREQ		500000L	/* max freq error (ns/s) */
+#define MINSEC		256	/* min FLL update interval (s) */
+#define MAXSEC		1600	/* max PLL update interval (s) */
+#define NANOSECOND	1000000000L /* nanoseconds in one second */
+#define SCALE_PPM	(65536 / 1000) /* crude ns/s to scaled PPM */
+#define MAXTC		10	/* max time constant in PLL mode */
 
 /*
  * The following defines and structures define the user interface for
- * the ntp_gettime() and ntp_adjtime() system calls.
+ * the ntp_gettime() and ntp_adjtime() syscalls.
  *
- * Control mode codes (timex.modes)
+ * Control mode codes (timex.modes and nanotimex.modes)
  */
 #define MOD_OFFSET	0x0001	/* set time offset */
 #define MOD_FREQUENCY	0x0002	/* set frequency offset */
 #define MOD_MAXERROR	0x0004	/* set maximum time error */
 #define MOD_ESTERROR	0x0008	/* set estimated time error */
 #define MOD_STATUS	0x0010	/* set clock status bits */
-#define MOD_TIMECONST	0x0020	/* set pll time constant */
-#define MOD_CANSCALE	0x0040	/* kernel can scale offset field */
-#define MOD_DOSCALE	0x0080	/* userland wants to scale offset field */
+#define MOD_TIMECONST	0x0020	/* set PLL time constant */
+#define	MOD_PLL		0x0400	/* select default PLL mode */
+#define	MOD_FLL		0x0800	/* select default FLL mode */
+#define	MOD_MICRO	0x1000	/* select microsecond resolution */
+#define	MOD_NANO	0x2000	/* select nanosecond resolution */
+#define MOD_CLKB	0x4000	/* select clock B */
+#define MOD_CLKA	0x8000	/* select clock A */
 
 /*
  * Status codes (timex.status)
@@ -211,22 +137,22 @@
 #define STA_PLL		0x0001	/* enable PLL updates (rw) */
 #define STA_PPSFREQ	0x0002	/* enable PPS freq discipline (rw) */
 #define STA_PPSTIME	0x0004	/* enable PPS time discipline (rw) */
-#define STA_FLL		0x0008	/* select frequency-lock mode (rw) */
-
+#define STA_FLL		0x0008	/* enable FLL mode (rw) */
 #define STA_INS		0x0010	/* insert leap (rw) */
 #define STA_DEL		0x0020	/* delete leap (rw) */
 #define STA_UNSYNC	0x0040	/* clock unsynchronized (rw) */
 #define STA_FREQHOLD	0x0080	/* hold frequency (rw) */
-
 #define STA_PPSSIGNAL	0x0100	/* PPS signal present (ro) */
 #define STA_PPSJITTER	0x0200	/* PPS signal jitter exceeded (ro) */
 #define STA_PPSWANDER	0x0400	/* PPS signal wander exceeded (ro) */
 #define STA_PPSERROR	0x0800	/* PPS signal calibration error (ro) */
-
 #define STA_CLOCKERR	0x1000	/* clock hardware fault (ro) */
+#define STA_NANO	0x2000	/* resolution (0 = us, 1 = ns) (ro) */
+#define STA_MODE	0x4000	/* mode (0 = PLL, 1 = FLL) (ro) */
+#define STA_CLK		0x8000	/* clock source (0 = A, 1 = B) (ro) */
 
 #define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \
-    STA_PPSERROR | STA_CLOCKERR) /* read-only bits */
+    STA_PPSERROR | STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)
 
 /*
  * Clock states (time_state)
@@ -236,74 +162,65 @@
 #define TIME_DEL	2	/* delete leap second warning */
 #define TIME_OOP	3	/* leap second in progress */
 #define TIME_WAIT	4	/* leap second has occured */
-#define TIME_ERROR	5	/* clock not synchronized */
+#define TIME_ERROR	5	/* error (see status word) */
 
 /*
  * NTP user interface (ntp_gettime()) - used to read kernel clock values
  *
- * Note: maximum error = NTP synch distance = dispersion + delay / 2;
- * estimated error = NTP dispersion.
+ * Note: The time member is in microseconds if STA_NANO is zero and
+ * nanoseconds if not.
  */
 struct ntptimeval {
-	struct timeval time;	/* current time (ro) */
+	struct timespec time;	/* current time (ns) (ro) */
 	long maxerror;		/* maximum error (us) (ro) */
 	long esterror;		/* estimated error (us) (ro) */
-	int time_state;		/* what ntp_gettime returns */
+	int time_state;		/* time status */
 };
 
 /*
- * NTP daemon interface - (ntp_adjtime()) used to discipline CPU clock
- * oscillator
+ * NTP daemon interface (ntp_adjtime()) - used to discipline CPU clock
+ * oscillator and determine status.
+ *
+ * Note: The offset, precision and jitter members are in microseconds if
+ * STA_NANO is zero and nanoseconds if not.
  */
 struct timex {
 	unsigned int modes;	/* clock mode bits (wo) */
-	long offset;		/* time offset (us) (rw) */
-	long freq;		/* frequency offset (scaled ppm) (rw) */
-	long maxerror;		/* maximum error (us) (rw) */
-	long esterror;		/* estimated error (us) (rw) */
-	int status;		/* clock status bits (rw) */
-	long constant;		/* pll time constant (rw) */
-	long precision;		/* clock precision (us) (ro) */
-	long tolerance;		/* clock frequency tolerance (scaled
-				 * ppm) (ro) */
+	long	offset;		/* time offset (ns/us) (rw) */
+	long	freq;		/* frequency offset (scaled PPM) (rw) */
+	long	maxerror;	/* maximum error (us) (rw) */
+	long	esterror;	/* estimated error (us) (rw) */
+	int	status;		/* clock status bits (rw) */
+	long	constant;	/* poll interval (log2 s) (rw) */
+	long	precision;	/* clock precision (ns/us) (ro) */
+	long	tolerance;	/* clock frequency tolerance (scaled
+				 * PPM) (ro) */
 	/*
 	 * The following read-only structure members are implemented
 	 * only if the PPS signal discipline is configured in the
-	 * kernel.
+	 * kernel. They are included in all configurations to insure
+	 * portability.
 	 */
-	long ppsfreq;		/* pps frequency (scaled ppm) (ro) */
-	long jitter;		/* pps jitter (us) (ro) */
-	int shift;		/* interval duration (s) (shift) (ro) */
-	long stabil;		/* pps stability (scaled ppm) (ro) */
-	long jitcnt;		/* jitter limit exceeded (ro) */
-	long calcnt;		/* calibration intervals (ro) */
-	long errcnt;		/* calibration errors (ro) */
-	long stbcnt;		/* stability limit exceeded (ro) */
-
+	long	ppsfreq;	/* PPS frequency (scaled PPM) (ro) */
+	long	jitter;		/* PPS jitter (ns/us) (ro) */
+	int	shift;		/* interval duration (s) (shift) (ro) */
+	long	stabil;		/* PPS stability (scaled PPM) (ro) */
+	long	jitcnt;		/* jitter limit exceeded (ro) */
+	long	calcnt;		/* calibration intervals (ro) */
+	long	errcnt;		/* calibration errors (ro) */
+	long	stbcnt;		/* stability limit exceeded (ro) */
 };
-#ifdef __FreeBSD__
 
-/*
- * sysctl identifiers underneath kern.ntp_pll
- */
-#define NTP_PLL_GETTIME	1	/* used by ntp_gettime() */
-#define NTP_PLL_MAXID	2	/* number of valid ids */
-
-#define NTP_PLL_NAMES { \
-			  { 0, 0 }, \
-			  { "gettime", CTLTYPE_STRUCT }, \
-		      }
+#ifdef __FreeBSD__
 
 #ifdef KERNEL
 void ntp_update_second __P((struct timecounter *tc));
-extern long time_phase;
-extern long time_adj;
 #else
 #include <sys/cdefs.h>
 
 __BEGIN_DECLS
-extern int ntp_gettime	__P((struct ntptimeval *));
-extern int ntp_adjtime	__P((struct timex *));
+extern int ntp_gettime		__P((struct ntptimeval *));
+extern int ntp_adjtime		__P((struct timex *));
 __END_DECLS
 
 #endif /* not KERNEL */