bsd/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 /*
  36  * Copyright (c) 2017 Apple Computer, Inc. All rights reserved.
  37  *
  38  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  39  *
  40  * This file contains Original Code and/or Modifications of Original Code
  41  * as defined in and that are subject to the Apple Public Source License
  42  * Version 2.0 (the 'License'). You may not use this file except in
  43  * compliance with the License. The rights granted to you under the License
  44  * may not be used to create, or enable the creation or redistribution of,
  45  * unlawful or unlicensed copies of an Apple operating system, or to
  46  * circumvent, violate, or enable the circumvention or violation of, any
  47  * terms of an Apple operating system software license agreement.
  48  *
  49  * Please obtain a copy of the License at
  50  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  51  *
  52  * The Original Code and all software distributed under the License are
  53  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  54  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  55  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  56  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  57  * Please see the License for the specific language governing rights and
  58  * limitations under the License.
  59  *
  60  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  61  */
  62
  63 #ifndef _SYS_TIMEX_H_
  64 #define _SYS_TIMEX_H_ 1
  65
  66 #include <sys/time.h>
  67
  68 #define NTP_API         4               /* NTP API version */
  69
  70 /*
  71  * The following defines establish the performance envelope of the
  72  * kernel discipline loop. Phase or frequency errors greater than
  73  * NAXPHASE or MAXFREQ are clamped to these maxima. For update intervals
  74  * less than MINSEC, the loop always operates in PLL mode; while, for
  75  * update intervals greater than MAXSEC, the loop always operates in FLL
  76  * mode. Between these two limits the operating mode is selected by the
  77  * STA_FLL bit in the status word.
  78  */
  79
  80 #define MAXPHASE        500000000L      /* max phase error (ns) */
  81 #define MAXFREQ         500000L         /* max freq error (ns/s) */
  82 #define MINSEC          256             /* min FLL update interval (s) */
  83 #define MAXSEC          2048            /* max PLL update interval (s) */
  84 #define NANOSECOND      1000000000L     /* nanoseconds in one second */
  85 #define SCALE_PPM       (65536 / 1000)  /* crude ns/s to scaled PPM */
  86 #define MAXTC           10              /* max time constant */
  87
  88 /* Codes for PPS (pulse-per-second) signals or leap seconds are not used but kept
  89  * unchanged and commented for future compatibility.
  90  */
  91
  92 /*
  93  * Control mode codes (timex.modes)
  94  */
  95 #define MOD_OFFSET      0x0001          /* set time offset */
  96 #define MOD_FREQUENCY   0x0002          /* set frequency offset */
  97 #define MOD_MAXERROR    0x0004          /* set maximum time error */
  98 #define MOD_ESTERROR    0x0008          /* set estimated time error */
  99 #define MOD_STATUS      0x0010          /* set clock status bits */
 100 #define MOD_TIMECONST   0x0020          /* set PLL time constant */
 101 #define MOD_PPSMAX      0x0040          /* set PPS maximum averaging time */
 102 #define MOD_TAI         0x0080          /* set TAI offset */
 103 #define MOD_MICRO       0x1000          /* select microsecond resolution */
 104 #define MOD_NANO        0x2000          /* select nanosecond resolution */
 105 #define MOD_CLKB        0x4000          /* select clock B */
 106 #define MOD_CLKA        0x8000          /* select clock A */
 107
 108 /*
 109  * Status codes (timex.status)
 110  */
 111 #define STA_PLL         0x0001          /* enable PLL updates (rw) */
 112 #define STA_PPSFREQ     0x0002          /* enable PPS freq discipline (rw) */
 113 #define STA_PPSTIME     0x0004          /* enable PPS time discipline (rw) */
 114 #define STA_FLL         0x0008          /* enable FLL mode (rw) */
 115 #define STA_INS         0x0010          /* insert leap (rw) */
 116 #define STA_DEL         0x0020          /* delete leap (rw) */
 117 #define STA_UNSYNC      0x0040          /* clock unsynchronized (rw) */
 118 #define STA_FREQHOLD    0x0080          /* hold frequency (rw) */
 119 #define STA_PPSSIGNAL   0x0100          /* PPS signal present (ro) */
 120 #define STA_PPSJITTER   0x0200          /* PPS signal jitter exceeded (ro) */
 121 #define STA_PPSWANDER   0x0400          /* PPS signal wander exceeded (ro) */
 122 #define STA_PPSERROR    0x0800          /* PPS signal calibration error (ro) */
 123 #define STA_CLOCKERR    0x1000          /* clock hardware fault (ro) */
 124 #define STA_NANO        0x2000          /* resolution (0 = us, 1 = ns) (ro) */
 125 #define STA_MODE        0x4000          /* mode (0 = PLL, 1 = FLL) (ro) */
 126 #define STA_CLK         0x8000          /* clock source (0 = A, 1 = B) (ro) */
 127
 128 #define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \
 129     STA_PPSERROR | STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)
 130
 131 #define STA_SUPPORTED (STA_PLL | STA_FLL | STA_UNSYNC | STA_FREQHOLD | \
 132     STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)
 133
 134 /*
 135  * Clock states (ntptimeval.time_state)
 136  */
 137 #define TIME_OK         0               /* no leap second warning */
 138 #define TIME_INS        1               /* insert leap second warning */
 139 #define TIME_DEL        2               /* delete leap second warning */
 140 #define TIME_OOP        3               /* leap second in progress */
 141 #define TIME_WAIT       4               /* leap second has occurred */
 142 #define TIME_ERROR      5               /* error (see status word) */
 143
 144 /*
 145  * NTP user interface -- ntp_gettime - used to read kernel clock values
 146  */
 147 struct ntptimeval {
 148         struct timespec time;           /* current time (ns) (ro) */
 149         long maxerror;                  /* maximum error (us) (ro) */
 150         long esterror;                  /* estimated error (us) (ro) */
 151         long tai;                       /* TAI offset */
 152         int time_state;                 /* time status */
 153 };
 154
 155 /*
 156  * NTP daemon interface -- ntp_adjtime -- used to discipline CPU clock
 157  * oscillator and control/determine status.
 158  *
 159  * Note: The offset, precision and jitter members are in microseconds if
 160  * STA_NANO is zero and nanoseconds if not.
 161  */
 162 struct timex {
 163         unsigned int modes;             /* clock mode bits (wo) */
 164         long    offset;                 /* time offset (ns/us) (rw) */
 165         long    freq;                   /* frequency offset (scaled PPM) (rw) */
 166         long    maxerror;               /* maximum error (us) (rw) */
 167         long    esterror;               /* estimated error (us) (rw) */
 168         int     status;                 /* clock status bits (rw) */
 169         long    constant;               /* poll interval (log2 s) (rw) */
 170         long    precision;              /* clock precision (ns/us) (ro) */
 171         long    tolerance;              /* clock frequency tolerance (scaled
 172                                          * PPM) (ro) */
 173         /*
 174          * The following read-only structure members are used by
 175          * the PPS signal discipline that is currently not supported.
 176          * They are included for compatibility.
 177          */
 178         long    ppsfreq;                /* PPS frequency (scaled PPM) (ro) */
 179         long    jitter;                 /* PPS jitter (ns/us) (ro) */
 180         int     shift;                  /* interval duration (s) (shift) (ro) */
 181         long    stabil;                 /* PPS stability (scaled PPM) (ro) */
 182         long    jitcnt;                 /* jitter limit exceeded (ro) */
 183         long    calcnt;                 /* calibration intervals (ro) */
 184         long    errcnt;                 /* calibration errors (ro) */
 185         long    stbcnt;                 /* stability limit exceeded (ro) */
 186 };
 187
 188 #ifdef KERNEL
 189 #ifdef XNU_KERNEL_PRIVATE
 190 #include <sys/_types/_user32_timex.h>
 191 #include <sys/_types/_user64_timex.h>
 192 #include <sys/_types/_user32_ntptimeval.h>
 193 #include <sys/_types/_user64_ntptimeval.h>
 194 #include <kern/clock.h>
 195
 196 int64_t ntp_get_freq(void);
 197 void    ntp_update_second(int64_t *adjustment, clock_sec_t secs);
 198 void    ntp_init(void);
 199 #endif
 200 #else /* !_KERNEL */
 201 #include <sys/cdefs.h>
 202
 203 __BEGIN_DECLS
 204 #if !defined(_POSIX_C_SOURCE) || defined(_DARWIN_C_SOURCE)
 205 int     ntp_adjtime(struct timex *);
 206 int     ntp_gettime(struct ntptimeval *);
 207 #endif /* (!_POSIX_C_SOURCE || _DARWIN_C_SOURCE) */
 208 __END_DECLS
 209 #endif /* KERNEL */
 210
 211
 212 #endif /* !_SYS_TIMEX_H_ */