freebsd-nq/usr.sbin/xntpd/include/ntp_timex.h

/******************************************************************************
 *                                                                            *
 * Copyright (c) David L. Mills 1993                                          *
 *                                                                            *
 * 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.      *
 *                                                                            *
 ******************************************************************************/

/*
 * Modification history timex.h
 *
 * 28 Nov 93	David L. Mills
 *	Adjusted parameters to improve stability and increase poll interval
 *
 * 10 Oct 93	Torsten Duwe
 *	Changed to ntp_timex.h (#ifdef'd HAVE_SYS_TIMEX_H)
 * 
 * 17 Sep 93    David L. Mills
 *      Created file
 */
/*
 * This header file defines the Network Time Protocol (NTP) interfaces
 * for user and daemon application programs. These are implemented using
 * private syscalls and data structures and require specific kernel
 * support.
 *
 * NAME
 *	ntp_gettime - NTP user application interface
 *
 * SYNOPSIS
 *	#include <sys/timex.h>
 *
 *	int syscall(SYS_ntp_gettime, tptr)
 *
 *	int SYS_ntp_gettime		defined in syscall.h header file
 *	struct ntptimeval *tptr	pointer to ntptimeval structure
 *
 * NAME
 *	ntp_adjtime - NTP daemon application interface
 *
 * SYNOPSIS
 *	#include <sys/timex.h>
 *
 *	int syscall(SYS_ntp_adjtime, mode, tptr)
 *
 *	int SYS_ntp_adjtime		defined in syscall.h header file
 *	struct timex *tptr		pointer to timex structure
 *
 */
#ifndef _NTP_TIMEX_H
#define _NTP_TIMEX_H

/*
 * Include system timex.h (if appropriate)
 */
#ifdef HAVE_SYS_TIMEX_H
#include <sys/timex.h>
#else  /* provide definitions */
#include <sys/syscall.h>

extern int syscall      P((int, void *, ...));

#define ntp_gettime(t)  syscall(SYS_ntp_gettime, (t))
#define ntp_adjtime(t)  syscall(SYS_ntp_adjtime, (t))

/*
 * The following defines establish the engineering parameters of the PLL
 * model. The HZ variable establishes the timer interrupt frequency, 100 Hz 
 * for the SunOS kernel, 256 Hz for the Ultrix kernel and 1024 Hz for the
 * OSF/1 kernel. The SHIFT_HZ define expresses the same value as the
 * nearest power of two in order to avoid hardware multiply operations.
 */
#define SHIFT_HZ 7		/* log2(HZ) */

/*
 * The SHIFT_KG and SHIFT_KF defines establish the damping of the PLL
 * and are chosen by analysis for a slightly underdamped convergence
 * characteristic. The MAXTC define establishes the maximum time constant
 * of the PLL. With the parameters given and the default time constant of
 * zero, the PLL will converge in about 15 minutes.
 */
#define SHIFT_KG 6		/* shift for phase increment */
#define SHIFT_KF 16		/* shift for frequency increment */
#define MAXTC 6			/* maximum time constant (shift) */

/*
 * The SHIFT_SCALE define establishes the decimal point of the time_phase
 * variable which serves as a an extension to the low-order bits of the
 * system clock variable. The SHIFT_UPDATE define establishes the decimal
 * point of the time_offset variable which represents the current offset
 * with respect to standard time. The SHIFT_USEC define represents 1 us in
 * external units (shift), while the FINEUSEC define represents 1 us in
 * internal units.
 */
#define SHIFT_SCALE 23		/* shift for phase scale factor */
#define SHIFT_UPDATE (SHIFT_KG + MAXTC) /* shift for offset scale factor */
#define SHIFT_USEC 16		/* shift for 1 us in external units */
#define FINEUSEC (1 << SHIFT_SCALE) /* 1 us in internal units */

/*
 * Mode codes (timex.mode) 
 */
#define ADJ_OFFSET	0x0001	/* time offset */
#define ADJ_FREQUENCY	0x0002	/* frequency offset */
#define ADJ_MAXERROR	0x0004	/* maximum time error */
#define ADJ_ESTERROR	0x0008	/* estimated time error */
#define ADJ_STATUS	0x0010	/* clock status */
#define ADJ_TIMECONST	0x0020	/* pll time constant */

/*
 * Clock command/status codes (timex.status)
 */
#define TIME_OK		0	/* clock synchronized */
#define TIME_INS	1	/* insert leap second */
#define TIME_DEL	2	/* delete leap second */
#define TIME_OOP	3	/* leap second in progress */
#define TIME_BAD	4	/* clock not synchronized */

/*
 * NTP user interface - used to read kernel clock values
 * Note: maximum error = NTP synch distance = dispersion + delay / 2;
 * estimated error = NTP dispersion.
 */
struct ntptimeval {
	struct timeval time;	/* current time */
	long maxerror;		/* maximum error (usec) */
	long esterror;		/* estimated error (usec) */
};

/*
 * NTP daemon interface - used to discipline kernel clock oscillator
 */
struct timex {
	int mode;		/* mode selector */
	long offset;		/* time offset (usec) */
	long frequency;		/* frequency offset (scaled ppm) */
	long maxerror;		/* maximum error (usec) */
	long esterror;		/* estimated error (usec) */
	int status;		/* clock command/status */
	long time_constant;	/* pll time constant */
	long precision;		/* clock precision (usec) (read only) */
	long tolerance;		/* clock frequency tolerance (ppm)
				 * (read only)
				 */
};

#endif /* HAVE_SYS_TIMEX_H */

#endif /* _NTP_TIMEX_H */