include/sys/timex.h

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