The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/sys/timex.h

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

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

Cache object: bc1c0ecefad5714e5bd56d0f2e94d736


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.