sys/sys/timex.h

   1 /***********************************************************************
   2  *                                                                     *
   3  * Copyright (c) David L. Mills 1993-2001                              *
   4  *                                                                     *
   5  * Permission to use, copy, modify, and distribute this software and   *
   6  * its documentation for any purpose and without fee is hereby         *
   7  * granted, provided that the above copyright notice appears in all    *
   8  * copies and that both the copyright notice and this permission       *
   9  * notice appear in supporting documentation, and that the name        *
  10  * University of Delaware not be used in advertising or publicity      *
  11  * pertaining to distribution of the software without specific,        *
  12  * written prior permission. The University of Delaware makes no       *
  13  * representations about the suitability this software for any         *
  14  * purpose. It is provided "as is" without express or implied          *
  15  * warranty.                                                           *
  16  *                                                                     *
  17  **********************************************************************/
  18
  19 /*
  20  * Modification history timex.h
  21  *
  22  * 16 Aug 00    David L. Mills
  23  *      API Version 4. Added MOD_TAI and tai member of ntptimeval
  24  *      structure.
  25  *
  26  * 17 Nov 98    David L. Mills
  27  *      Revised for nanosecond kernel and user interface.
  28  *
  29  * 26 Sep 94    David L. Mills
  30  *      Added defines for hybrid phase/frequency-lock loop.
  31  *
  32  * 19 Mar 94    David L. Mills
  33  *      Moved defines from kernel routines to header file and added new
  34  *      defines for PPS phase-lock loop.
  35  *
  36  * 20 Feb 94    David L. Mills
  37  *      Revised status codes and structures for external clock and PPS
  38  *      signal discipline.
  39  *
  40  * 28 Nov 93    David L. Mills
  41  *      Adjusted parameters to improve stability and increase poll
  42  *      interval.
  43  *
  44  * 17 Sep 93    David L. Mills
  45  *      Created file
  46  *
  47  * $FreeBSD: src/sys/sys/timex.h,v 1.12.2.1 2001/04/22 11:19:39 jhay Exp $
  48  * $DragonFly: src/sys/sys/timex.h,v 1.7 2006/10/23 21:50:33 dillon Exp $
  49  */
  50 /*
  51  * This header file defines the Network Time Protocol (NTP) interfaces
  52  * for user and daemon application programs. These are implemented using
  53  * defined syscalls and data structures and require specific kernel
  54  * support.
  55  *
  56  * The original precision time kernels developed from 1993 have an
  57  * ultimate resolution of one microsecond; however, the most recent
  58  * kernels have an ultimate resolution of one nanosecond. In these
  59  * kernels, a ntp_adjtime() syscalls can be used to determine which
  60  * resolution is in use and to select either one at any time. The
  61  * resolution selected affects the scaling of certain fields in the
  62  * ntp_gettime() and ntp_adjtime() syscalls, as described below.
  63  *
  64  * NAME
  65  *      ntp_gettime - NTP user application interface
  66  *
  67  * SYNOPSIS
  68  *      #include <sys/timex.h>
  69  *
  70  *      int ntp_gettime(struct ntptimeval *ntv);
  71  *
  72  * DESCRIPTION
  73  *      The time returned by ntp_gettime() is in a timespec structure,
  74  *      but may be in either microsecond (seconds and microseconds) or
  75  *      nanosecond (seconds and nanoseconds) format. The particular
  76  *      format in use is determined by the STA_NANO bit of the status
  77  *      word returned by the ntp_adjtime() syscall.
  78  *
  79  * NAME
  80  *      ntp_adjtime - NTP daemon application interface
  81  *
  82  * SYNOPSIS
  83  *      #include <sys/timex.h>
  84  *      #include <sys/syscall.h>
  85  *
  86  *      int syscall(SYS_ntp_adjtime, tptr);
  87  *      int SYS_ntp_adjtime;
  88  *      struct timex *tptr;
  89  *
  90  * DESCRIPTION
  91  *      Certain fields of the timex structure are interpreted in either
  92  *      microseconds or nanoseconds according to the state of the
  93  *      STA_NANO bit in the status word. See the description below for
  94  *      further information.
  95  */
  96 #ifndef _SYS_TIMEX_H_
  97 #define _SYS_TIMEX_H_
  98
  99 #define NTP_API         4       /* NTP API version */
 100
 101 #ifndef _SYS_SYSCALL_H_
 102 #include <sys/syscall.h>
 103 #endif
 104 #ifndef _SYS_TIME_H_
 105 #include <sys/time.h>
 106 #endif
 107
 108 /*
 109  * The following defines establish the performance envelope of the
 110  * kernel discipline loop. Phase or frequency errors greater than
 111  * NAXPHASE or MAXFREQ are clamped to these maxima. For update intervals
 112  * less than MINSEC, the loop always operates in PLL mode; while, for
 113  * update intervals greater than MAXSEC, the loop always operates in FLL
 114  * mode. Between these two limits the operating mode is selected by the
 115  * STA_FLL bit in the status word.
 116  */
 117 #define MAXPHASE        500000000L /* max phase error (ns) */
 118 #define MAXFREQ         500000L /* max freq error (ns/s) */
 119 #define MINSEC          256     /* min FLL update interval (s) */
 120 #define MAXSEC          2048    /* max PLL update interval (s) */
 121 #define NANOSECOND      1000000000L /* nanoseconds in one second */
 122 #define SCALE_PPM       (65536 / 1000) /* crude ns/s to scaled PPM */
 123 #define MAXTC           10      /* max time constant */
 124
 125 /*
 126  * The following defines and structures define the user interface for
 127  * the ntp_gettime() and ntp_adjtime() syscalls.
 128  *
 129  * Control mode codes (timex.modes)
 130  */
 131 #define MOD_OFFSET      0x0001  /* set time offset */
 132 #define MOD_FREQUENCY   0x0002  /* set frequency offset */
 133 #define MOD_MAXERROR    0x0004  /* set maximum time error */
 134 #define MOD_ESTERROR    0x0008  /* set estimated time error */
 135 #define MOD_STATUS      0x0010  /* set clock status bits */
 136 #define MOD_TIMECONST   0x0020  /* set PLL time constant */
 137 #define MOD_PPSMAX      0x0040  /* set PPS maximum averaging time */
 138 #define MOD_TAI         0x0080  /* set TAI offset */
 139 #define MOD_MICRO       0x1000  /* select microsecond resolution */
 140 #define MOD_NANO        0x2000  /* select nanosecond resolution */
 141 #define MOD_CLKB        0x4000  /* select clock B */
 142 #define MOD_CLKA        0x8000  /* select clock A */
 143
 144 /*
 145  * Status codes (timex.status)
 146  */
 147 #define STA_PLL         0x0001  /* enable PLL updates (rw) */
 148 #define STA_PPSFREQ     0x0002  /* enable PPS freq discipline (rw) */
 149 #define STA_PPSTIME     0x0004  /* enable PPS time discipline (rw) */
 150 #define STA_FLL         0x0008  /* enable FLL mode (rw) */
 151 #define STA_INS         0x0010  /* insert leap (rw) */
 152 #define STA_DEL         0x0020  /* delete leap (rw) */
 153 #define STA_UNSYNC      0x0040  /* clock unsynchronized (rw) */
 154 #define STA_FREQHOLD    0x0080  /* hold frequency (rw) */
 155 #define STA_PPSSIGNAL   0x0100  /* PPS signal present (ro) */
 156 #define STA_PPSJITTER   0x0200  /* PPS signal jitter exceeded (ro) */
 157 #define STA_PPSWANDER   0x0400  /* PPS signal wander exceeded (ro) */
 158 #define STA_PPSERROR    0x0800  /* PPS signal calibration error (ro) */
 159 #define STA_CLOCKERR    0x1000  /* clock hardware fault (ro) */
 160 #define STA_NANO        0x2000  /* resolution (0 = us, 1 = ns) (ro) */
 161 #define STA_MODE        0x4000  /* mode (0 = PLL, 1 = FLL) (ro) */
 162 #define STA_CLK         0x8000  /* clock source (0 = A, 1 = B) (ro) */
 163
 164 #define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \
 165     STA_PPSERROR | STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)
 166
 167 /*
 168  * Clock states (time_state)
 169  */
 170 #define TIME_OK         0       /* no leap second warning */
 171 #define TIME_INS        1       /* insert leap second warning */
 172 #define TIME_DEL        2       /* delete leap second warning */
 173 #define TIME_OOP        3       /* leap second in progress */
 174 #define TIME_WAIT       4       /* leap second has occured */
 175 #define TIME_ERROR      5       /* error (see status word) */
 176
 177 /*
 178  * NTP user interface (ntp_gettime()) - used to read kernel clock values
 179  *
 180  * Note: The time member is in microseconds if STA_NANO is zero and
 181  * nanoseconds if not.
 182  */
 183 struct ntptimeval {
 184         struct timespec time;   /* current time (ns) (ro) */
 185         long maxerror;          /* maximum error (us) (ro) */
 186         long esterror;          /* estimated error (us) (ro) */
 187         long tai;               /* TAI offset */
 188         int time_state;         /* time status */
 189 };
 190
 191 /*
 192  * NTP daemon interface (ntp_adjtime()) - used to discipline CPU clock
 193  * oscillator and determine status.
 194  *
 195  * Note: The offset, precision and jitter members are in microseconds if
 196  * STA_NANO is zero and nanoseconds if not.
 197  */
 198 struct timex {
 199         unsigned int modes;     /* clock mode bits (wo) */
 200         long    offset;         /* time offset (ns/us) (rw) */
 201         long    freq;           /* frequency offset (scaled PPM) (rw) */
 202         long    maxerror;       /* maximum error (us) (rw) */
 203         long    esterror;       /* estimated error (us) (rw) */
 204         int     status;         /* clock status bits (rw) */
 205         long    constant;       /* poll interval (log2 s) (rw) */
 206         long    precision;      /* clock precision (ns/us) (ro) */
 207         long    tolerance;      /* clock frequency tolerance (scaled
 208                                  * PPM) (ro) */
 209         /*
 210          * The following read-only structure members are implemented
 211          * only if the PPS signal discipline is configured in the
 212          * kernel. They are included in all configurations to insure
 213          * portability.
 214          */
 215         long    ppsfreq;        /* PPS frequency (scaled PPM) (ro) */
 216         long    jitter;         /* PPS jitter (ns/us) (ro) */
 217         int     shift;          /* interval duration (s) (shift) (ro) */
 218         long    stabil;         /* PPS stability (scaled PPM) (ro) */
 219         long    jitcnt;         /* jitter limit exceeded (ro) */
 220         long    calcnt;         /* calibration intervals (ro) */
 221         long    errcnt;         /* calibration errors (ro) */
 222         long    stbcnt;         /* stability limit exceeded (ro) */
 223 };
 224
 225 #ifdef __DragonFly__
 226
 227 #ifdef _KERNEL
 228
 229 int   ntp_update_second (time_t, int64_t *);
 230
 231 #else
 232
 233 #include <sys/cdefs.h>
 234
 235 __BEGIN_DECLS
 236 int     ntp_adjtime (struct timex *);
 237 int     ntp_gettime (struct ntptimeval *);
 238 __END_DECLS
 239 #endif /* _KERNEL */
 240
 241 #endif /* __DragonFly__ */
 242
 243 #endif /* !_SYS_TIMEX_H_ */