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