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/*
36 * Copyright (c) 2017 Apple Computer, Inc. All rights reserved.
37 *
38 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
39 *
40 * This file contains Original Code and/or Modifications of Original Code
41 * as defined in and that are subject to the Apple Public Source License
42 * Version 2.0 (the 'License'). You may not use this file except in
43 * compliance with the License. The rights granted to you under the License
44 * may not be used to create, or enable the creation or redistribution of,
45 * unlawful or unlicensed copies of an Apple operating system, or to
46 * circumvent, violate, or enable the circumvention or violation of, any
47 * terms of an Apple operating system software license agreement.
48 *
49 * Please obtain a copy of the License at
50 * http://www.opensource.apple.com/apsl/ and read it before using this file.
51 *
52 * The Original Code and all software distributed under the License are
53 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
54 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
55 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
56 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
57 * Please see the License for the specific language governing rights and
58 * limitations under the License.
59 *
60 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
61 */
62
63#ifndef _SYS_TIMEX_H_
64#define _SYS_TIMEX_H_ 1
65
66#include <sys/time.h>
67
68#define NTP_API 4 /* NTP API version */
69
70/*
71 * The following defines establish the performance envelope of the
72 * kernel discipline loop. Phase or frequency errors greater than
73 * NAXPHASE or MAXFREQ are clamped to these maxima. For update intervals
74 * less than MINSEC, the loop always operates in PLL mode; while, for
75 * update intervals greater than MAXSEC, the loop always operates in FLL
76 * mode. Between these two limits the operating mode is selected by the
77 * STA_FLL bit in the status word.
78 */
79
80#define MAXPHASE 500000000L /* max phase error (ns) */
81#define MAXFREQ 500000L /* max freq error (ns/s) */
82#define MINSEC 256 /* min FLL update interval (s) */
83#define MAXSEC 2048 /* max PLL update interval (s) */
84#define NANOSECOND 1000000000L /* nanoseconds in one second */
85#define SCALE_PPM (65536 / 1000) /* crude ns/s to scaled PPM */
86#define MAXTC 10 /* max time constant */
87
88/* Codes for PPS (pulse-per-second) signals or leap seconds are not used but kept
89 * unchanged and commented for future compatibility.
90 */
91
92/*
93 * Control mode codes (timex.modes)
94 */
95#define MOD_OFFSET 0x0001 /* set time offset */
96#define MOD_FREQUENCY 0x0002 /* set frequency offset */
97#define MOD_MAXERROR 0x0004 /* set maximum time error */
98#define MOD_ESTERROR 0x0008 /* set estimated time error */
99#define MOD_STATUS 0x0010 /* set clock status bits */
100#define MOD_TIMECONST 0x0020 /* set PLL time constant */
101#define MOD_PPSMAX 0x0040 /* set PPS maximum averaging time */
102#define MOD_TAI 0x0080 /* set TAI offset */
103#define MOD_MICRO 0x1000 /* select microsecond resolution */
104#define MOD_NANO 0x2000 /* select nanosecond resolution */
105#define MOD_CLKB 0x4000 /* select clock B */
106#define MOD_CLKA 0x8000 /* select clock A */
107
108/*
109 * Status codes (timex.status)
110 */
111#define STA_PLL 0x0001 /* enable PLL updates (rw) */
112#define STA_PPSFREQ 0x0002 /* enable PPS freq discipline (rw) */
113#define STA_PPSTIME 0x0004 /* enable PPS time discipline (rw) */
114#define STA_FLL 0x0008 /* enable FLL mode (rw) */
115#define STA_INS 0x0010 /* insert leap (rw) */
116#define STA_DEL 0x0020 /* delete leap (rw) */
117#define STA_UNSYNC 0x0040 /* clock unsynchronized (rw) */
118#define STA_FREQHOLD 0x0080 /* hold frequency (rw) */
119#define STA_PPSSIGNAL 0x0100 /* PPS signal present (ro) */
120#define STA_PPSJITTER 0x0200 /* PPS signal jitter exceeded (ro) */
121#define STA_PPSWANDER 0x0400 /* PPS signal wander exceeded (ro) */
122#define STA_PPSERROR 0x0800 /* PPS signal calibration error (ro) */
123#define STA_CLOCKERR 0x1000 /* clock hardware fault (ro) */
124#define STA_NANO 0x2000 /* resolution (0 = us, 1 = ns) (ro) */
125#define STA_MODE 0x4000 /* mode (0 = PLL, 1 = FLL) (ro) */
126#define STA_CLK 0x8000 /* clock source (0 = A, 1 = B) (ro) */
127
128#define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \
129 STA_PPSERROR | STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)
130
131#define STA_SUPPORTED (STA_PLL | STA_FLL | STA_UNSYNC | STA_FREQHOLD | \
132 STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)
133
134/*
135 * Clock states (ntptimeval.time_state)
136 */
137#define TIME_OK 0 /* no leap second warning */
138#define TIME_INS 1 /* insert leap second warning */
139#define TIME_DEL 2 /* delete leap second warning */
140#define TIME_OOP 3 /* leap second in progress */
141#define TIME_WAIT 4 /* leap second has occurred */
142#define TIME_ERROR 5 /* error (see status word) */
143
144/*
145 * NTP user interface -- ntp_gettime - used to read kernel clock values
146 */
147struct ntptimeval {
148 struct timespec time; /* current time (ns) (ro) */
149 long maxerror; /* maximum error (us) (ro) */
150 long esterror; /* estimated error (us) (ro) */
151 long tai; /* TAI offset */
152 int time_state; /* time status */
153};
154
155/*
156 * NTP daemon interface -- ntp_adjtime -- used to discipline CPU clock
157 * oscillator and control/determine status.
158 *
159 * Note: The offset, precision and jitter members are in microseconds if
160 * STA_NANO is zero and nanoseconds if not.
161 */
162struct timex {
163 unsigned int modes; /* clock mode bits (wo) */
164 long offset; /* time offset (ns/us) (rw) */
165 long freq; /* frequency offset (scaled PPM) (rw) */
166 long maxerror; /* maximum error (us) (rw) */
167 long esterror; /* estimated error (us) (rw) */
168 int status; /* clock status bits (rw) */
169 long constant; /* poll interval (log2 s) (rw) */
170 long precision; /* clock precision (ns/us) (ro) */
171 long tolerance; /* clock frequency tolerance (scaled
172 * PPM) (ro) */
173 /*
174 * The following read-only structure members are used by
175 * the PPS signal discipline that is currently not supported.
176 * They are included for compatibility.
177 */
178 long ppsfreq; /* PPS frequency (scaled PPM) (ro) */
179 long jitter; /* PPS jitter (ns/us) (ro) */
180 int shift; /* interval duration (s) (shift) (ro) */
181 long stabil; /* PPS stability (scaled PPM) (ro) */
182 long jitcnt; /* jitter limit exceeded (ro) */
183 long calcnt; /* calibration intervals (ro) */
184 long errcnt; /* calibration errors (ro) */
185 long stbcnt; /* stability limit exceeded (ro) */
186};
187
188#ifdef KERNEL
189#ifdef XNU_KERNEL_PRIVATE
190#include <sys/_types/_user32_timex.h>
191#include <sys/_types/_user64_timex.h>
192#include <sys/_types/_user32_ntptimeval.h>
193#include <sys/_types/_user64_ntptimeval.h>
194#include <kern/clock.h>
195
196int64_t ntp_get_freq(void);
197void ntp_update_second(int64_t *adjustment, clock_sec_t secs);
198void ntp_init(void);
199#endif
200#else /* !_KERNEL */
201#include <sys/cdefs.h>
202
203__BEGIN_DECLS
204#if !defined(_POSIX_C_SOURCE) || defined(_DARWIN_C_SOURCE)
205int ntp_adjtime(struct timex *);
206int ntp_gettime(struct ntptimeval *);
207#endif /* (!_POSIX_C_SOURCE || _DARWIN_C_SOURCE) */
208__END_DECLS
209#endif /* KERNEL */
210
211
212#endif /* !_SYS_TIMEX_H_ */
213