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#ifndef _SYS_TIMEX_H_
36#define _SYS_TIMEX_H_ 1
37
38#define NTP_API		4		/* NTP API version */
39
40#ifdef __FreeBSD__
41#include <sys/_timespec.h>
42#endif /* __FreeBSD__ */
43
44/*
45 * The following defines establish the performance envelope of the
46 * kernel discipline loop. Phase or frequency errors greater than
47 * NAXPHASE or MAXFREQ are clamped to these maxima. For update intervals
48 * less than MINSEC, the loop always operates in PLL mode; while, for
49 * update intervals greater than MAXSEC, the loop always operates in FLL
50 * mode. Between these two limits the operating mode is selected by the
51 * STA_FLL bit in the status word.
52 */
53
54#define MAXPHASE	500000000L	/* max phase error (ns) */
55#define MAXFREQ		500000L		/* max freq error (ns/s) */
56#define MINSEC		256		/* min FLL update interval (s) */
57#define MAXSEC		2048		/* max PLL update interval (s) */
58#define NANOSECOND	1000000000L	/* nanoseconds in one second */
59#define SCALE_PPM	(65536 / 1000)	/* crude ns/s to scaled PPM */
60#define MAXTC		10		/* max time constant */
61
62/*
63 * Control mode codes (timex.modes)
64 */
65#define MOD_OFFSET	0x0001		/* set time offset */
66#define MOD_FREQUENCY	0x0002		/* set frequency offset */
67#define MOD_MAXERROR	0x0004		/* set maximum time error */
68#define MOD_ESTERROR	0x0008		/* set estimated time error */
69#define MOD_STATUS	0x0010		/* set clock status bits */
70#define MOD_TIMECONST	0x0020		/* set PLL time constant */
71#define MOD_PPSMAX	0x0040		/* set PPS maximum averaging time */
72#define MOD_TAI		0x0080		/* set TAI offset */
73#define	MOD_MICRO	0x1000		/* select microsecond resolution */
74#define	MOD_NANO	0x2000		/* select nanosecond resolution */
75#define MOD_CLKB	0x4000		/* select clock B */
76#define MOD_CLKA	0x8000		/* select clock A */
77
78/*
79 * Status codes (timex.status)
80 */
81#define STA_PLL		0x0001		/* enable PLL updates (rw) */
82#define STA_PPSFREQ	0x0002		/* enable PPS freq discipline (rw) */
83#define STA_PPSTIME	0x0004		/* enable PPS time discipline (rw) */
84#define STA_FLL		0x0008		/* enable FLL mode (rw) */
85#define STA_INS		0x0010		/* insert leap (rw) */
86#define STA_DEL		0x0020		/* delete leap (rw) */
87#define STA_UNSYNC	0x0040		/* clock unsynchronized (rw) */
88#define STA_FREQHOLD	0x0080		/* hold frequency (rw) */
89#define STA_PPSSIGNAL	0x0100		/* PPS signal present (ro) */
90#define STA_PPSJITTER	0x0200		/* PPS signal jitter exceeded (ro) */
91#define STA_PPSWANDER	0x0400		/* PPS signal wander exceeded (ro) */
92#define STA_PPSERROR	0x0800		/* PPS signal calibration error (ro) */
93#define STA_CLOCKERR	0x1000		/* clock hardware fault (ro) */
94#define STA_NANO	0x2000		/* resolution (0 = us, 1 = ns) (ro) */
95#define STA_MODE	0x4000		/* mode (0 = PLL, 1 = FLL) (ro) */
96#define STA_CLK		0x8000		/* clock source (0 = A, 1 = B) (ro) */
97
98#define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \
99    STA_PPSERROR | STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)
100
101/*
102 * Clock states (ntptimeval.time_state)
103 */
104#define TIME_OK		0		/* no leap second warning */
105#define TIME_INS	1		/* insert leap second warning */
106#define TIME_DEL	2		/* delete leap second warning */
107#define TIME_OOP	3		/* leap second in progress */
108#define TIME_WAIT	4		/* leap second has occurred */
109#define TIME_ERROR	5		/* error (see status word) */
110
111/*
112 * NTP user interface -- ntp_gettime(2) - used to read kernel clock values
113 */
114struct ntptimeval {
115	struct timespec time;		/* current time (ns) (ro) */
116	long maxerror;			/* maximum error (us) (ro) */
117	long esterror;			/* estimated error (us) (ro) */
118	long tai;			/* TAI offset */
119	int time_state;			/* time status */
120};
121
122/*
123 * NTP daemon interface -- ntp_adjtime(2) -- used to discipline CPU clock
124 * oscillator and control/determine status.
125 *
126 * Note: The offset, precision and jitter members are in microseconds if
127 * STA_NANO is zero and nanoseconds if not.
128 */
129struct timex {
130	unsigned int modes;		/* clock mode bits (wo) */
131	long	offset;			/* time offset (ns/us) (rw) */
132	long	freq;			/* frequency offset (scaled PPM) (rw) */
133	long	maxerror;		/* maximum error (us) (rw) */
134	long	esterror;		/* estimated error (us) (rw) */
135	int	status;			/* clock status bits (rw) */
136	long	constant;		/* poll interval (log2 s) (rw) */
137	long	precision;		/* clock precision (ns/us) (ro) */
138	long	tolerance;		/* clock frequency tolerance (scaled
139				 	 * PPM) (ro) */
140	/*
141	 * The following read-only structure members are implemented
142	 * only if the PPS signal discipline is configured in the
143	 * kernel. They are included in all configurations to insure
144	 * portability.
145	 */
146	long	ppsfreq;		/* PPS frequency (scaled PPM) (ro) */
147	long	jitter;			/* PPS jitter (ns/us) (ro) */
148	int	shift;			/* interval duration (s) (shift) (ro) */
149	long	stabil;			/* PPS stability (scaled PPM) (ro) */
150	long	jitcnt;			/* jitter limit exceeded (ro) */
151	long	calcnt;			/* calibration intervals (ro) */
152	long	errcnt;			/* calibration errors (ro) */
153	long	stbcnt;			/* stability limit exceeded (ro) */
154};
155
156#ifdef __FreeBSD__
157
158#ifdef _KERNEL
159void	ntp_update_second(int64_t *adjustment, time_t *newsec);
160#else /* !_KERNEL */
161#include <sys/cdefs.h>
162
163__BEGIN_DECLS
164int	ntp_adjtime(struct timex *);
165int	ntp_gettime(struct ntptimeval *);
166__END_DECLS
167#endif /* _KERNEL */
168
169#endif /* __FreeBSD__ */
170
171#endif /* !_SYS_TIMEX_H_ */
172