[apple/xnu.git] / bsd / sys / timex.h

/*-
 ***********************************************************************
 *								       *
 * Copyright (c) David L. Mills 1993-2001			       *
 * Copyright (c) Poul-Henning Kamp 2000-2001                           *
 *								       *
 * Permission to use, copy, modify, and distribute this software and   *
 * its documentation for any purpose and without fee is hereby	       *
 * granted, provided that the above copyright notice appears in all    *
 * copies and that both the copyright notice and this permission       *
 * notice appear in supporting documentation, and that the name        *
 * University of Delaware not be used in advertising or publicity      *
 * pertaining to distribution of the software without specific,	       *
 * written prior permission. The University of Delaware makes no       *
 * representations about the suitability this software for any	       *
 * purpose. It is provided "as is" without express or implied	       *
 * warranty.							       *
 *								       *
 ***********************************************************************
 *
 * $FreeBSD$
 *
 * This header file defines the Network Time Protocol (NTP) interfaces
 * for user and daemon application programs.
 *
 * This file was originally created 17 Sep 93 by David L. Mills, Professor
 * of University of Delaware, building on work which had already been ongoing
 * for a decade and a half at that point in time.
 *
 * In 2000 the APIs got a upgrade from microseconds to nanoseconds,
 * a joint work between Poul-Henning Kamp and David L. Mills.
 *
 */

/*
 * Copyright (c) 2017 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#ifndef _SYS_TIMEX_H_
#define _SYS_TIMEX_H_ 1

#include <sys/time.h>

#define NTP_API         4               /* NTP API version */

/*
 * The following defines establish the performance envelope of the
 * kernel discipline loop. Phase or frequency errors greater than
 * NAXPHASE or MAXFREQ are clamped to these maxima. For update intervals
 * less than MINSEC, the loop always operates in PLL mode; while, for
 * update intervals greater than MAXSEC, the loop always operates in FLL
 * mode. Between these two limits the operating mode is selected by the
 * STA_FLL bit in the status word.
 */

#define MAXPHASE        500000000L      /* max phase error (ns) */
#define MAXFREQ         500000L         /* max freq error (ns/s) */
#define MINSEC          256             /* min FLL update interval (s) */
#define MAXSEC          2048            /* max PLL update interval (s) */
#define NANOSECOND      1000000000L     /* nanoseconds in one second */
#define SCALE_PPM       (65536 / 1000)  /* crude ns/s to scaled PPM */
#define MAXTC           10              /* max time constant */

/* Codes for PPS (pulse-per-second) signals or leap seconds are not used but kept
 * unchanged and commented for future compatibility.
 */

/*
 * Control mode codes (timex.modes)
 */
#define MOD_OFFSET      0x0001          /* set time offset */
#define MOD_FREQUENCY   0x0002          /* set frequency offset */
#define MOD_MAXERROR    0x0004          /* set maximum time error */
#define MOD_ESTERROR    0x0008          /* set estimated time error */
#define MOD_STATUS      0x0010          /* set clock status bits */
#define MOD_TIMECONST   0x0020          /* set PLL time constant */
#define MOD_PPSMAX      0x0040          /* set PPS maximum averaging time */
#define MOD_TAI         0x0080          /* set TAI offset */
#define MOD_MICRO       0x1000          /* select microsecond resolution */
#define MOD_NANO        0x2000          /* select nanosecond resolution */
#define MOD_CLKB        0x4000          /* select clock B */
#define MOD_CLKA        0x8000          /* select clock A */

/*
 * Status codes (timex.status)
 */
#define STA_PLL         0x0001          /* enable PLL updates (rw) */
#define STA_PPSFREQ     0x0002          /* enable PPS freq discipline (rw) */
#define STA_PPSTIME     0x0004          /* enable PPS time discipline (rw) */
#define STA_FLL         0x0008          /* enable FLL mode (rw) */
#define STA_INS         0x0010          /* insert leap (rw) */
#define STA_DEL         0x0020          /* delete leap (rw) */
#define STA_UNSYNC      0x0040          /* clock unsynchronized (rw) */
#define STA_FREQHOLD    0x0080          /* hold frequency (rw) */
#define STA_PPSSIGNAL   0x0100          /* PPS signal present (ro) */
#define STA_PPSJITTER   0x0200          /* PPS signal jitter exceeded (ro) */
#define STA_PPSWANDER   0x0400          /* PPS signal wander exceeded (ro) */
#define STA_PPSERROR    0x0800          /* PPS signal calibration error (ro) */
#define STA_CLOCKERR    0x1000          /* clock hardware fault (ro) */
#define STA_NANO        0x2000          /* resolution (0 = us, 1 = ns) (ro) */
#define STA_MODE        0x4000          /* mode (0 = PLL, 1 = FLL) (ro) */
#define STA_CLK         0x8000          /* clock source (0 = A, 1 = B) (ro) */

#define STA_RONLY (STA_PPSSIGNAL | STA_PPSJITTER | STA_PPSWANDER | \
    STA_PPSERROR | STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)

#define STA_SUPPORTED (STA_PLL | STA_FLL | STA_UNSYNC | STA_FREQHOLD | \
    STA_CLOCKERR | STA_NANO | STA_MODE | STA_CLK)

/*
 * Clock states (ntptimeval.time_state)
 */
#define TIME_OK         0               /* no leap second warning */
#define TIME_INS        1               /* insert leap second warning */
#define TIME_DEL        2               /* delete leap second warning */
#define TIME_OOP        3               /* leap second in progress */
#define TIME_WAIT       4               /* leap second has occurred */
#define TIME_ERROR      5               /* error (see status word) */

/*
 * NTP user interface -- ntp_gettime - used to read kernel clock values
 */
struct ntptimeval {
	struct timespec time;           /* current time (ns) (ro) */
	long maxerror;                  /* maximum error (us) (ro) */
	long esterror;                  /* estimated error (us) (ro) */
	long tai;                       /* TAI offset */
	int time_state;                 /* time status */
};

/*
 * NTP daemon interface -- ntp_adjtime -- used to discipline CPU clock
 * oscillator and control/determine status.
 *
 * Note: The offset, precision and jitter members are in microseconds if
 * STA_NANO is zero and nanoseconds if not.
 */
struct timex {
	unsigned int modes;             /* clock mode bits (wo) */
	long    offset;                 /* time offset (ns/us) (rw) */
	long    freq;                   /* frequency offset (scaled PPM) (rw) */
	long    maxerror;               /* maximum error (us) (rw) */
	long    esterror;               /* estimated error (us) (rw) */
	int     status;                 /* clock status bits (rw) */
	long    constant;               /* poll interval (log2 s) (rw) */
	long    precision;              /* clock precision (ns/us) (ro) */
	long    tolerance;              /* clock frequency tolerance (scaled
	                                 * PPM) (ro) */
	/*
	 * The following read-only structure members are used by
	 * the PPS signal discipline that is currently not supported.
	 * They are included for compatibility.
	 */
	long    ppsfreq;                /* PPS frequency (scaled PPM) (ro) */
	long    jitter;                 /* PPS jitter (ns/us) (ro) */
	int     shift;                  /* interval duration (s) (shift) (ro) */
	long    stabil;                 /* PPS stability (scaled PPM) (ro) */
	long    jitcnt;                 /* jitter limit exceeded (ro) */
	long    calcnt;                 /* calibration intervals (ro) */
	long    errcnt;                 /* calibration errors (ro) */
	long    stbcnt;                 /* stability limit exceeded (ro) */
};

#ifdef KERNEL
#ifdef XNU_KERNEL_PRIVATE
#include <sys/_types/_user32_timex.h>
#include <sys/_types/_user64_timex.h>
#include <sys/_types/_user32_ntptimeval.h>
#include <sys/_types/_user64_ntptimeval.h>
#include <kern/clock.h>

int64_t ntp_get_freq(void);
void    ntp_update_second(int64_t *adjustment, clock_sec_t secs);
void    ntp_init(void);
#endif
#else /* !_KERNEL */
#include <sys/cdefs.h>

__BEGIN_DECLS
#if !defined(_POSIX_C_SOURCE) || defined(_DARWIN_C_SOURCE)
int     ntp_adjtime(struct timex *);
int     ntp_gettime(struct ntptimeval *);
#endif /* (!_POSIX_C_SOURCE || _DARWIN_C_SOURCE) */
__END_DECLS
#endif /* KERNEL */


#endif /* !_SYS_TIMEX_H_ */
Commit	Line	Data
5ba3f43e A	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
0a7de745	68	#define NTP_API 4 /* NTP API version */
5ba3f43e A	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 */
0a7de745 A	103	#define MOD_MICRO 0x1000 /* select microsecond resolution */
0a7de745 A	104	#define MOD_NANO 0x2000 /* select nanosecond resolution */
5ba3f43e A	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	*/
	147	struct ntptimeval {
0a7de745 A	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 */
5ba3f43e A	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	*/
	162	struct timex {
0a7de745 A	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) */
5ba3f43e A	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	*/
0a7de745 A	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) */
5ba3f43e A	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
	196	int64_t ntp_get_freq(void);
0a7de745 A	197	void ntp_update_second(int64_t *adjustment, clock_sec_t secs);
0a7de745 A	198	void ntp_init(void);
5ba3f43e A	199	#endif
	200	#else /* !_KERNEL */
	201	#include <sys/cdefs.h>
	202
	203	__BEGIN_DECLS
	204	#if !defined(_POSIX_C_SOURCE) \|\| defined(_DARWIN_C_SOURCE)
0a7de745 A	205	int ntp_adjtime(struct timex *);
0a7de745 A	206	int ntp_gettime(struct ntptimeval *);
5ba3f43e A	207	#endif /* (!_POSIX_C_SOURCE \|\| _DARWIN_C_SOURCE) */
	208	__END_DECLS
	209	#endif /* KERNEL */
	210
	211
	212	#endif /* !_SYS_TIMEX_H_ */