1139825Simp/*- 2139825Simp *********************************************************************** 344574Sphk * * 475540Sjhay * Copyright (c) David L. Mills 1993-2001 * 544574Sphk * * 644574Sphk * Permission to use, copy, modify, and distribute this software and * 744574Sphk * its documentation for any purpose and without fee is hereby * 844574Sphk * granted, provided that the above copyright notice appears in all * 944574Sphk * copies and that both the copyright notice and this permission * 1044574Sphk * notice appear in supporting documentation, and that the name * 1144574Sphk * University of Delaware not be used in advertising or publicity * 1244574Sphk * pertaining to distribution of the software without specific, * 1344574Sphk * written prior permission. The University of Delaware makes no * 1444574Sphk * representations about the suitability this software for any * 1544574Sphk * purpose. It is provided "as is" without express or implied * 1644574Sphk * warranty. * 1744574Sphk * * 1844574Sphk **********************************************************************/ 192291Sjkh 202291Sjkh/* 212291Sjkh * Modification history timex.h 222291Sjkh * 2375540Sjhay * 16 Aug 00 David L. Mills 2465432Sphk * API Version 4. Added MOD_TAI and tai member of ntptimeval 2565432Sphk * structure. 2665432Sphk * 2744574Sphk * 17 Nov 98 David L. Mills 2844574Sphk * Revised for nanosecond kernel and user interface. 2944574Sphk * 3021101Sjhay * 26 Sep 94 David L. Mills 3121101Sjhay * Added defines for hybrid phase/frequency-lock loop. 3221101Sjhay * 332291Sjkh * 19 Mar 94 David L. Mills 342291Sjkh * Moved defines from kernel routines to header file and added new 352291Sjkh * defines for PPS phase-lock loop. 362291Sjkh * 372291Sjkh * 20 Feb 94 David L. Mills 382291Sjkh * Revised status codes and structures for external clock and PPS 392291Sjkh * signal discipline. 402291Sjkh * 412291Sjkh * 28 Nov 93 David L. Mills 422291Sjkh * Adjusted parameters to improve stability and increase poll 432291Sjkh * interval. 442291Sjkh * 452291Sjkh * 17 Sep 93 David L. Mills 462291Sjkh * Created file 4755205Speter * 4855205Speter * $FreeBSD$ 492291Sjkh */ 502291Sjkh/* 512291Sjkh * This header file defines the Network Time Protocol (NTP) interfaces 522291Sjkh * for user and daemon application programs. These are implemented using 5344574Sphk * defined syscalls and data structures and require specific kernel 542291Sjkh * support. 552291Sjkh * 5644574Sphk * The original precision time kernels developed from 1993 have an 5744574Sphk * ultimate resolution of one microsecond; however, the most recent 5844574Sphk * kernels have an ultimate resolution of one nanosecond. In these 5944574Sphk * kernels, a ntp_adjtime() syscalls can be used to determine which 6044574Sphk * resolution is in use and to select either one at any time. The 6144574Sphk * resolution selected affects the scaling of certain fields in the 6244574Sphk * ntp_gettime() and ntp_adjtime() syscalls, as described below. 6344574Sphk * 642291Sjkh * NAME 652291Sjkh * ntp_gettime - NTP user application interface 662291Sjkh * 672291Sjkh * SYNOPSIS 682291Sjkh * #include <sys/timex.h> 692291Sjkh * 7044666Sphk * int ntp_gettime(struct ntptimeval *ntv); 712291Sjkh * 7244574Sphk * DESCRIPTION 7344666Sphk * The time returned by ntp_gettime() is in a timespec structure, 7444574Sphk * but may be in either microsecond (seconds and microseconds) or 7544574Sphk * nanosecond (seconds and nanoseconds) format. The particular 7644574Sphk * format in use is determined by the STA_NANO bit of the status 7744574Sphk * word returned by the ntp_adjtime() syscall. 782291Sjkh * 792291Sjkh * NAME 802291Sjkh * ntp_adjtime - NTP daemon application interface 812291Sjkh * 822291Sjkh * SYNOPSIS 832291Sjkh * #include <sys/timex.h> 8444574Sphk * #include <sys/syscall.h> 852291Sjkh * 8644574Sphk * int syscall(SYS_ntp_adjtime, tptr); 8744666Sphk * int SYS_ntp_adjtime; 8844574Sphk * struct timex *tptr; 892291Sjkh * 9044574Sphk * DESCRIPTION 9144574Sphk * Certain fields of the timex structure are interpreted in either 9244574Sphk * microseconds or nanoseconds according to the state of the 9344574Sphk * STA_NANO bit in the status word. See the description below for 9444574Sphk * further information. 952291Sjkh */ 962291Sjkh#ifndef _SYS_TIMEX_H_ 9745294Sphk#define _SYS_TIMEX_H_ 1 9865432Sphk#define NTP_API 4 /* NTP API version */ 992291Sjkh 100250889Sed#ifdef __FreeBSD__ 101250889Sed#include <sys/_timespec.h> 102250889Sed#endif /* __FreeBSD__ */ 1032291Sjkh#ifndef MSDOS /* Microsoft specific */ 1042291Sjkh#include <sys/syscall.h> 1052291Sjkh#endif /* MSDOS */ 1062291Sjkh 1072291Sjkh/* 10844574Sphk * The following defines establish the performance envelope of the 10944574Sphk * kernel discipline loop. Phase or frequency errors greater than 11044574Sphk * NAXPHASE or MAXFREQ are clamped to these maxima. For update intervals 11144574Sphk * less than MINSEC, the loop always operates in PLL mode; while, for 11244574Sphk * update intervals greater than MAXSEC, the loop always operates in FLL 11344574Sphk * mode. Between these two limits the operating mode is selected by the 11444574Sphk * STA_FLL bit in the status word. 1152291Sjkh */ 11644574Sphk#define MAXPHASE 500000000L /* max phase error (ns) */ 11744574Sphk#define MAXFREQ 500000L /* max freq error (ns/s) */ 11844574Sphk#define MINSEC 256 /* min FLL update interval (s) */ 11945294Sphk#define MAXSEC 2048 /* max PLL update interval (s) */ 12044574Sphk#define NANOSECOND 1000000000L /* nanoseconds in one second */ 12144574Sphk#define SCALE_PPM (65536 / 1000) /* crude ns/s to scaled PPM */ 12250656Sphk#define MAXTC 10 /* max time constant */ 1232291Sjkh 1242291Sjkh/* 1252291Sjkh * The following defines and structures define the user interface for 12644574Sphk * the ntp_gettime() and ntp_adjtime() syscalls. 1272291Sjkh * 12845294Sphk * Control mode codes (timex.modes) 1292291Sjkh */ 1302291Sjkh#define MOD_OFFSET 0x0001 /* set time offset */ 1312291Sjkh#define MOD_FREQUENCY 0x0002 /* set frequency offset */ 1322291Sjkh#define MOD_MAXERROR 0x0004 /* set maximum time error */ 1332291Sjkh#define MOD_ESTERROR 0x0008 /* set estimated time error */ 1342291Sjkh#define MOD_STATUS 0x0010 /* set clock status bits */ 13544574Sphk#define MOD_TIMECONST 0x0020 /* set PLL time constant */ 13650656Sphk#define MOD_PPSMAX 0x0040 /* set PPS maximum averaging time */ 13765432Sphk#define MOD_TAI 0x0080 /* set TAI offset */ 13844574Sphk#define MOD_MICRO 0x1000 /* select microsecond resolution */ 13944574Sphk#define MOD_NANO 0x2000 /* select nanosecond resolution */ 14044574Sphk#define MOD_CLKB 0x4000 /* select clock B */ 14144574Sphk#define MOD_CLKA 0x8000 /* select clock A */ 1422291Sjkh 1432291Sjkh/* 1442291Sjkh * Status codes (timex.status) 1452291Sjkh */ 1462291Sjkh#define STA_PLL 0x0001 /* enable PLL updates (rw) */ 1472291Sjkh#define STA_PPSFREQ 0x0002 /* enable PPS freq discipline (rw) */ 1482291Sjkh#define STA_PPSTIME 0x0004 /* enable PPS time discipline (rw) */ 14944574Sphk#define STA_FLL 0x0008 /* enable FLL mode (rw) */ 1502291Sjkh#define STA_INS 0x0010 /* insert leap (rw) */ 1512291Sjkh#define STA_DEL 0x0020 /* delete leap (rw) */ 1522291Sjkh#define STA_UNSYNC 0x0040 /* clock unsynchronized (rw) */ 15321101Sjhay#define STA_FREQHOLD 0x0080 /* hold frequency (rw) */ 1542291Sjkh#define STA_PPSSIGNAL 0x0100 /* PPS signal present (ro) */ 1552291Sjkh#define STA_PPSJITTER 0x0200 /* PPS signal jitter exceeded (ro) */ 1562291Sjkh#define STA_PPSWANDER 0x0400 /* PPS signal wander exceeded (ro) */ 1572291Sjkh#define STA_PPSERROR 0x0800 /* PPS signal calibration error (ro) */ 1582291Sjkh#define STA_CLOCKERR 0x1000 /* clock hardware fault (ro) */ 15944574Sphk#define STA_NANO 0x2000 /* resolution (0 = us, 1 = ns) (ro) */ 16044574Sphk#define STA_MODE 0x4000 /* mode (0 = PLL, 1 = FLL) (ro) */ 16144574Sphk#define STA_CLK 0x8000 /* clock source (0 = A, 1 = B) (ro) */ 1622291Sjkh 1632291Sjkh#define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \ 16444574Sphk STA_PPSERROR | STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK) 1652291Sjkh 1662291Sjkh/* 1672291Sjkh * Clock states (time_state) 1682291Sjkh */ 1692291Sjkh#define TIME_OK 0 /* no leap second warning */ 1702291Sjkh#define TIME_INS 1 /* insert leap second warning */ 1712291Sjkh#define TIME_DEL 2 /* delete leap second warning */ 1722291Sjkh#define TIME_OOP 3 /* leap second in progress */ 1732291Sjkh#define TIME_WAIT 4 /* leap second has occured */ 17444574Sphk#define TIME_ERROR 5 /* error (see status word) */ 1752291Sjkh 1762291Sjkh/* 1772291Sjkh * NTP user interface (ntp_gettime()) - used to read kernel clock values 1782291Sjkh * 17944574Sphk * Note: The time member is in microseconds if STA_NANO is zero and 18044574Sphk * nanoseconds if not. 1812291Sjkh */ 1822291Sjkhstruct ntptimeval { 18345294Sphk struct timespec time; /* current time (ns) (ro) */ 1842291Sjkh long maxerror; /* maximum error (us) (ro) */ 1852291Sjkh long esterror; /* estimated error (us) (ro) */ 18665432Sphk long tai; /* TAI offset */ 18744574Sphk int time_state; /* time status */ 1882291Sjkh}; 1892291Sjkh 1902291Sjkh/* 19144574Sphk * NTP daemon interface (ntp_adjtime()) - used to discipline CPU clock 19244574Sphk * oscillator and determine status. 19344574Sphk * 19444574Sphk * Note: The offset, precision and jitter members are in microseconds if 19544574Sphk * STA_NANO is zero and nanoseconds if not. 1962291Sjkh */ 1972291Sjkhstruct timex { 1982291Sjkh unsigned int modes; /* clock mode bits (wo) */ 19944574Sphk long offset; /* time offset (ns/us) (rw) */ 20044574Sphk long freq; /* frequency offset (scaled PPM) (rw) */ 20144574Sphk long maxerror; /* maximum error (us) (rw) */ 20244574Sphk long esterror; /* estimated error (us) (rw) */ 20344574Sphk int status; /* clock status bits (rw) */ 20444574Sphk long constant; /* poll interval (log2 s) (rw) */ 20544574Sphk long precision; /* clock precision (ns/us) (ro) */ 20644574Sphk long tolerance; /* clock frequency tolerance (scaled 20744574Sphk * PPM) (ro) */ 2082291Sjkh /* 2092291Sjkh * The following read-only structure members are implemented 2102291Sjkh * only if the PPS signal discipline is configured in the 21144574Sphk * kernel. They are included in all configurations to insure 21244574Sphk * portability. 2132291Sjkh */ 21444574Sphk long ppsfreq; /* PPS frequency (scaled PPM) (ro) */ 21544574Sphk long jitter; /* PPS jitter (ns/us) (ro) */ 21644574Sphk int shift; /* interval duration (s) (shift) (ro) */ 21744574Sphk long stabil; /* PPS stability (scaled PPM) (ro) */ 21844574Sphk long jitcnt; /* jitter limit exceeded (ro) */ 21944574Sphk long calcnt; /* calibration intervals (ro) */ 22044574Sphk long errcnt; /* calibration errors (ro) */ 22144574Sphk long stbcnt; /* stability limit exceeded (ro) */ 22244574Sphk}; 2232291Sjkh 2242291Sjkh#ifdef __FreeBSD__ 2252291Sjkh 22655205Speter#ifdef _KERNEL 22795529Sphkvoid ntp_update_second(int64_t *adjustment, time_t *newsec); 22855205Speter#else /* !_KERNEL */ 2292291Sjkh#include <sys/cdefs.h> 2302291Sjkh 2312291Sjkh__BEGIN_DECLS 23292719Salfredint ntp_adjtime(struct timex *); 23392719Salfredint ntp_gettime(struct ntptimeval *); 2342291Sjkh__END_DECLS 23555205Speter#endif /* _KERNEL */ 2362291Sjkh 23744666Sphk#endif /* __FreeBSD__ */ 2382291Sjkh 23944666Sphk#endif /* !_SYS_TIMEX_H_ */ 240