sys/sys/timex.h

   1 /*-
   2  ***********************************************************************
   3  *                                                                     *
   4  * Copyright (c) David L. Mills 1993-2001                              *
   5  * Copyright (c) Poul-Henning Kamp 2000-2001                           *
   6  *                                                                     *
   7  * Permission to use, copy, modify, and distribute this software and   *
   8  * its documentation for any purpose and without fee is hereby         *
   9  * granted, provided that the above copyright notice appears in all    *
  10  * copies and that both the copyright notice and this permission       *
  11  * notice appear in supporting documentation, and that the name        *
  12  * University of Delaware not be used in advertising or publicity      *
  13  * pertaining to distribution of the software without specific,        *
  14  * written prior permission. The University of Delaware makes no       *
  15  * representations about the suitability this software for any         *
  16  * purpose. It is provided "as is" without express or implied          *
  17  * warranty.                                                           *
  18  *                                                                     *
  19  ***********************************************************************
  20  *
  21  * $FreeBSD$
  22  *
  23  * This header file defines the Network Time Protocol (NTP) interfaces
  24  * for user and daemon application programs.
  25  *
  26  * This file was originally created 17 Sep 93 by David L. Mills, Professor
  27  * of University of Delaware, building on work which had already been ongoing
  28  * for a decade and a half at that point in time.
  29  *
  30  * In 2000 the APIs got a upgrade from microseconds to nanoseconds,
  31  * a joint work between Poul-Henning Kamp and David L. Mills.
  32  *
  33  */
  34
  35 #ifndef _SYS_TIMEX_H_
  36 #define _SYS_TIMEX_H_ 1
  37
  38 #define NTP_API         4               /* NTP API version */
  39
  40 #ifdef __FreeBSD__
  41 #include <sys/_timespec.h>
  42 #endif /* __FreeBSD__ */
  43
  44 /*
  45  * The following defines establish the performance envelope of the
  46  * kernel discipline loop. Phase or frequency errors greater than
  47  * NAXPHASE or MAXFREQ are clamped to these maxima. For update intervals
  48  * less than MINSEC, the loop always operates in PLL mode; while, for
  49  * update intervals greater than MAXSEC, the loop always operates in FLL
  50  * mode. Between these two limits the operating mode is selected by the
  51  * STA_FLL bit in the status word.
  52  */
  53
  54 #define MAXPHASE        500000000L      /* max phase error (ns) */
  55 #define MAXFREQ         500000L         /* max freq error (ns/s) */
  56 #define MINSEC          256             /* min FLL update interval (s) */
  57 #define MAXSEC          2048            /* max PLL update interval (s) */
  58 #define NANOSECOND      1000000000L     /* nanoseconds in one second */
  59 #define SCALE_PPM       (65536 / 1000)  /* crude ns/s to scaled PPM */
  60 #define MAXTC           10              /* max time constant */
  61
  62 /*
  63  * Control mode codes (timex.modes)
  64  */
  65 #define MOD_OFFSET      0x0001          /* set time offset */
  66 #define MOD_FREQUENCY   0x0002          /* set frequency offset */
  67 #define MOD_MAXERROR    0x0004          /* set maximum time error */
  68 #define MOD_ESTERROR    0x0008          /* set estimated time error */
  69 #define MOD_STATUS      0x0010          /* set clock status bits */
  70 #define MOD_TIMECONST   0x0020          /* set PLL time constant */
  71 #define MOD_PPSMAX      0x0040          /* set PPS maximum averaging time */
  72 #define MOD_TAI         0x0080          /* set TAI offset */
  73 #define MOD_MICRO       0x1000          /* select microsecond resolution */
  74 #define MOD_NANO        0x2000          /* select nanosecond resolution */
  75 #define MOD_CLKB        0x4000          /* select clock B */
  76 #define MOD_CLKA        0x8000          /* select clock A */
  77
  78 /*
  79  * Status codes (timex.status)
  80  */
  81 #define STA_PLL         0x0001          /* enable PLL updates (rw) */
  82 #define STA_PPSFREQ     0x0002          /* enable PPS freq discipline (rw) */
  83 #define STA_PPSTIME     0x0004          /* enable PPS time discipline (rw) */
  84 #define STA_FLL         0x0008          /* enable FLL mode (rw) */
  85 #define STA_INS         0x0010          /* insert leap (rw) */
  86 #define STA_DEL         0x0020          /* delete leap (rw) */
  87 #define STA_UNSYNC      0x0040          /* clock unsynchronized (rw) */
  88 #define STA_FREQHOLD    0x0080          /* hold frequency (rw) */
  89 #define STA_PPSSIGNAL   0x0100          /* PPS signal present (ro) */
  90 #define STA_PPSJITTER   0x0200          /* PPS signal jitter exceeded (ro) */
  91 #define STA_PPSWANDER   0x0400          /* PPS signal wander exceeded (ro) */
  92 #define STA_PPSERROR    0x0800          /* PPS signal calibration error (ro) */
  93 #define STA_CLOCKERR    0x1000          /* clock hardware fault (ro) */
  94 #define STA_NANO        0x2000          /* resolution (0 = us, 1 = ns) (ro) */
  95 #define STA_MODE        0x4000          /* mode (0 = PLL, 1 = FLL) (ro) */
  96 #define STA_CLK         0x8000          /* clock source (0 = A, 1 = B) (ro) */
  97
  98 #define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \
  99     STA_PPSERROR | STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)
 100
 101 /*
 102  * Clock states (ntptimeval.time_state)
 103  */
 104 #define TIME_OK         0               /* no leap second warning */
 105 #define TIME_INS        1               /* insert leap second warning */
 106 #define TIME_DEL        2               /* delete leap second warning */
 107 #define TIME_OOP        3               /* leap second in progress */
 108 #define TIME_WAIT       4               /* leap second has occurred */
 109 #define TIME_ERROR      5               /* error (see status word) */
 110
 111 /*
 112  * NTP user interface -- ntp_gettime(2) - used to read kernel clock values
 113  */
 114 struct ntptimeval {
 115         struct timespec time;           /* current time (ns) (ro) */
 116         long maxerror;                  /* maximum error (us) (ro) */
 117         long esterror;                  /* estimated error (us) (ro) */
 118         long tai;                       /* TAI offset */
 119         int time_state;                 /* time status */
 120 };
 121
 122 /*
 123  * NTP daemon interface -- ntp_adjtime(2) -- used to discipline CPU clock
 124  * oscillator and control/determine status.
 125  *
 126  * Note: The offset, precision and jitter members are in microseconds if
 127  * STA_NANO is zero and nanoseconds if not.
 128  */
 129 struct timex {
 130         unsigned int modes;             /* clock mode bits (wo) */
 131         long    offset;                 /* time offset (ns/us) (rw) */
 132         long    freq;                   /* frequency offset (scaled PPM) (rw) */
 133         long    maxerror;               /* maximum error (us) (rw) */
 134         long    esterror;               /* estimated error (us) (rw) */
 135         int     status;                 /* clock status bits (rw) */
 136         long    constant;               /* poll interval (log2 s) (rw) */
 137         long    precision;              /* clock precision (ns/us) (ro) */
 138         long    tolerance;              /* clock frequency tolerance (scaled
 139                                          * PPM) (ro) */
 140         /*
 141          * The following read-only structure members are implemented
 142          * only if the PPS signal discipline is configured in the
 143          * kernel. They are included in all configurations to insure
 144          * portability.
 145          */
 146         long    ppsfreq;                /* PPS frequency (scaled PPM) (ro) */
 147         long    jitter;                 /* PPS jitter (ns/us) (ro) */
 148         int     shift;                  /* interval duration (s) (shift) (ro) */
 149         long    stabil;                 /* PPS stability (scaled PPM) (ro) */
 150         long    jitcnt;                 /* jitter limit exceeded (ro) */
 151         long    calcnt;                 /* calibration intervals (ro) */
 152         long    errcnt;                 /* calibration errors (ro) */
 153         long    stbcnt;                 /* stability limit exceeded (ro) */
 154 };
 155
 156 #ifdef __FreeBSD__
 157
 158 #ifdef _KERNEL
 159 void    ntp_update_second(int64_t *adjustment, time_t *newsec);
 160 #else /* !_KERNEL */
 161 #include <sys/cdefs.h>
 162
 163 __BEGIN_DECLS
 164 int     ntp_adjtime(struct timex *);
 165 int     ntp_gettime(struct ntptimeval *);
 166 __END_DECLS
 167 #endif /* _KERNEL */
 168
 169 #endif /* __FreeBSD__ */
 170
 171 #endif /* !_SYS_TIMEX_H_ */