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