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