freebsd-nq/contrib/ntp/ntpd/refclock_atom.c

/*
 * refclock_atom - clock driver for 1-pps signals
 */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <stdio.h>
#include <ctype.h>

#include "ntpd.h"
#include "ntp_io.h"
#include "ntp_unixtime.h"
#include "ntp_refclock.h"
#include "ntp_stdlib.h"

#if defined(REFCLOCK) && defined(CLOCK_ATOM)

#ifdef HAVE_PPSAPI
# include "ppsapi_timepps.h"
#endif /* HAVE_PPSAPI */

/*
 * This driver furnishes an interface for pulse-per-second (PPS) signals
 * produced by a cesium clock, timing receiver or related equipment. It
 * can be used to remove accumulated jitter and retime a secondary
 * server when synchronized to a primary server over a congested, wide-
 * area network and before redistributing the time to local clients.
 *
 * Before this driver becomes active, the local clock must be set to
 * within +-500 ms by another means, such as a radio clock or NTP
 * itself. There are two ways to connect the PPS signal, normally at TTL
 * levels, to the computer. One is to shift to EIA levels and connect to
 * pin 8 (DCD) of a serial port. This requires a level converter and
 * may require a one-shot flipflop to lengthen the pulse. The other is
 * to connect the PPS signal directly to pin 10 (ACK) of a PC paralell
 * port. These methods are architecture dependent.
 *
 * Both methods require a modified device driver and kernel interface
 * compatible with the Pulse-per-Second API for Unix-like Operating
 * Systems, Version 1.0, RFC-2783 (PPSAPI). Implementations are
 * available for FreeBSD, Linux, SunOS, Solaris and Alpha. However, at
 * present only the Alpha implementation provides the full generality of
 * the API with multiple PPS drivers and multiple handles per driver. If
 * the PPSAPI is normally implemented in the /usr/include/sys/timepps.h
 * header file and kernel support specific to each operating system.
 * However, this driver can operate without this interface if means are
 * proviced to call the pps_sample() routine from another driver. Please
 * note; if the PPSAPI interface is present, it must be used.
 *
 * In many configurations a single port is used for the radio timecode
 * and PPS signal. In order to provide for this configuration and others
 * involving dedicated multiple serial/parallel ports, the driver first
 * attempts to open the device /dev/pps%d, where %d is the unit number.
 * If this fails, the driver attempts to open the device specified by
 * the pps configuration command. If a port is to be shared, the pps
 * command must be placed before the radio device(s) and the radio
 * device(s) must be placed before the PPS driver(s) in the
 * configuration file.
 *
 * This driver normally uses the PLL/FLL clock discipline implemented in
 * the ntpd code. Ordinarily, this is the most accurate means, as the
 * median filter in the driver interface is much larger than in the
 * kernel. However, if the systemic clock frequency error is large (tens
 * to hundreds of PPM), it's better to used the kernel support, if
 * available.
 *
 * Fudge Factors
 *
 * If flag2 is dim (default), the on-time epoch is the assert edge of
 * the PPS signal; if lit, the on-time epoch is the clear edge. If flag2
 * is lit, the assert edge is used; if flag3 is dim (default), the
 * kernel PPS support is disabled; if lit it is enabled. The time1
 * parameter can be used to compensate for miscellaneous device driver
 * and OS delays.
 */
/*
 * Interface definitions
 */
#ifdef HAVE_PPSAPI
#define DEVICE		"/dev/pps%d" /* device name and unit */
#endif /* HAVE_PPSAPI */

#define	PRECISION	(-20)	/* precision assumed (about 1 us) */
#define	REFID		"PPS\0"	/* reference ID */
#define	DESCRIPTION	"PPS Clock Discipline" /* WRU */
#define NANOSECOND	1000000000 /* one second (ns) */
#define RANGEGATE	500000	/* range gate (ns) */

static struct peer *pps_peer;	/* atom driver for PPS sources */

#ifdef HAVE_PPSAPI
/*
 * PPS unit control structure
 */
struct ppsunit {
	struct timespec ts;	/* last timestamp */
	int fddev;		/* pps device descriptor */
	pps_params_t pps_params; /* pps parameters */
	pps_info_t pps_info;	/* last pps data */
	pps_handle_t handle;	/* pps handlebars */
};
#endif /* HAVE_PPSAPI */

/*
 * Function prototypes
 */
static	int	atom_start	P((int, struct peer *));
static	void	atom_poll	P((int, struct peer *));
static	void	atom_shutdown	P((int, struct peer *));
#ifdef HAVE_PPSAPI
static	void	atom_control	P((int, struct refclockstat *, struct
				    refclockstat *, struct peer *));
static	void	atom_timer	P((int, struct peer *));
static	int	atom_ppsapi	P((struct peer *, int));
#endif /* HAVE_PPSAPI */

/*
 * Transfer vector
 */
#ifdef HAVE_PPSAPI
struct	refclock refclock_atom = {
	atom_start,		/* start up driver */
	atom_shutdown,		/* shut down driver */
	atom_poll,		/* transmit poll message */
	atom_control,		/* fudge control */
	noentry,		/* initialize driver (not used) */
	noentry,		/* buginfo (not used) */
	atom_timer,		/* called once per second */
};
#else /* HAVE_PPSAPI */
struct	refclock refclock_atom = {
	atom_start,		/* start up driver */
	atom_shutdown,		/* shut down driver */
	atom_poll,		/* transmit poll message */
	noentry,		/* fudge control (not used) */
	noentry,		/* initialize driver (not used) */
	noentry,		/* buginfo (not used) */
	NOFLAGS			/* not used */
};
#endif /* HAVE_PPPSAPI */


/*
 * atom_start - initialize data for processing
 */
static int
atom_start(
	int unit,		/* unit number (not used) */
	struct peer *peer	/* peer structure pointer */
	)
{
	struct refclockproc *pp;
#ifdef HAVE_PPSAPI
	register struct ppsunit *up;
	char	device[80];
	int	mode;
#endif /* HAVE_PPSAPI */

	/*
	 * Allocate and initialize unit structure
	 */
	pps_peer = peer;
	pp = peer->procptr;
	peer->precision = PRECISION;
	pp->clockdesc = DESCRIPTION;
	pp->stratum = STRATUM_UNSPEC;
	memcpy((char *)&pp->refid, REFID, 4);
#ifdef HAVE_PPSAPI
	up = emalloc(sizeof(struct ppsunit));
	memset(up, 0, sizeof(struct ppsunit));
	pp->unitptr = (caddr_t)up;

	/*
	 * Open PPS device. This can be any serial or parallel port and
	 * not necessarily the port used for the associated radio.
	 */
	sprintf(device, DEVICE, unit);
	up->fddev = open(device, O_RDWR, 0777);
	if (up->fddev <= 0) {
		msyslog(LOG_ERR,
		    "refclock_atom: %s: %m", device);
		return (0);
	}

	/*
	 * Light off the PPSAPI interface.
	 */
	if (time_pps_create(up->fddev, &up->handle) < 0) {
		msyslog(LOG_ERR,
		    "refclock_atom: time_pps_create failed: %m");
		return (0);
	}

	/*
	 * If the mode is nonzero, use that for the time_pps_setparams()
	 * mode; otherwise, PPS_CAPTUREASSERT. Enable kernel PPS if
	 * flag3 is lit.
	 */
	mode = peer->ttl;
	if (mode == 0)
		mode = PPS_CAPTUREASSERT;
	return (atom_ppsapi(peer, mode));
#else /* HAVE_PPSAPI */
	return (1);
#endif /* HAVE_PPSAPI */
}


/*
 * atom_shutdown - shut down the clock
 */
static void
atom_shutdown(
	int unit,		/* unit number (not used) */
	struct peer *peer	/* peer structure pointer */
	)
{
	struct refclockproc *pp;
	register struct ppsunit *up;

	pp = peer->procptr;
	up = (struct ppsunit *)pp->unitptr;
#ifdef HAVE_PPSAPI
	if (up->fddev > 0)
		close(up->fddev);
	if (up->handle != 0)
		time_pps_destroy(up->handle);
#endif /* HAVE_PPSAPI */
	if (pps_peer == peer)
		pps_peer = NULL;
	free(up);
}


#ifdef HAVE_PPSAPI
/*
 * atom_control - fudge control
 */
static void
atom_control(
	int unit,		/* unit (not used */
	struct refclockstat *in, /* input parameters (not uded) */
	struct refclockstat *out, /* output parameters (not used) */
	struct peer *peer	/* peer structure pointer */
	)
{
	struct refclockproc *pp;
	int	mode;

	pp = peer->procptr;
	if (peer->ttl != 0)	/* all legal modes must be nonzero */
		return;

	if (pp->sloppyclockflag & CLK_FLAG2)
		mode = PPS_CAPTURECLEAR;
	else
		mode = PPS_CAPTUREASSERT;
	atom_ppsapi(peer, mode);
}


/*
 * Initialize PPSAPI
 */
int
atom_ppsapi(
	struct peer *peer,	/* peer structure pointer */
	int mode		/* mode */
	)
{
	struct refclockproc *pp;
	register struct ppsunit *up;
	int capability;

	pp = peer->procptr;
	up = (struct ppsunit *)pp->unitptr;
	if (up->handle == 0)
		return (0);

	if (time_pps_getcap(up->handle, &capability) < 0) {
		msyslog(LOG_ERR,
		    "refclock_atom: time_pps_getcap failed: %m");
		return (0);
	}
	memset(&up->pps_params, 0, sizeof(pps_params_t));
	up->pps_params.api_version = PPS_API_VERS_1;
	up->pps_params.mode = mode | PPS_TSFMT_TSPEC;
	if (time_pps_setparams(up->handle, &up->pps_params) < 0) {
		msyslog(LOG_ERR,
		    "refclock_atom: time_pps_setparams failed: %m");
		return (0);
	}
	if (pp->sloppyclockflag & CLK_FLAG3) {
		if (time_pps_kcbind(up->handle, PPS_KC_HARDPPS,
		    up->pps_params.mode & ~PPS_TSFMT_TSPEC,
		    PPS_TSFMT_TSPEC) < 0) {
			msyslog(LOG_ERR,
			    "refclock_atom: time_pps_kcbind failed: %m");
			return (0);
		}
		pps_enable = 1;
	}
#if DEBUG
	if (debug) {
		time_pps_getparams(up->handle, &up->pps_params);
		printf(
		    "refclock_ppsapi: fd %d capability 0x%x version %d mode 0x%x\n",
		    up->fddev, capability, up->pps_params.api_version,
		    up->pps_params.mode);
	}
#endif
	return (1);
}


/*
 * atom_timer - called once per second
 *
 * This routine is called once per second when the PPSAPI interface is
 * present. It snatches the PPS timestamp from the kernel and saves the
 * sign-extended fraction in a circular buffer for processing at the
 * next poll event.
 */
static void
atom_timer(
	int	unit,		/* unit number (not used) */
	struct peer *peer	/* peer structure pointer */
	)
{
	register struct ppsunit *up;
	struct refclockproc *pp;
	pps_info_t pps_info;
	struct timespec timeout, ts;
	long	sec, nsec;
	double	dtemp;
	char	tbuf[80];	/* monitor buffer */

	/*
	 * Convert the timespec nanoseconds field to signed double and
	 * save in the median filter. for billboards. No harm is done if
	 * previous data are overwritten. If the discipline comes bum or
	 * the data grow stale, just forget it. A range gate rejects new
	 * samples if less than a jiggle time from the next second.
	 */ 
	pp = peer->procptr;
	up = (struct ppsunit *)pp->unitptr;
	if (up->handle == 0)
		return;

	timeout.tv_sec = 0;
	timeout.tv_nsec = 0;
	memcpy(&pps_info, &up->pps_info, sizeof(pps_info_t));
	if (time_pps_fetch(up->handle, PPS_TSFMT_TSPEC, &up->pps_info,
	    &timeout) < 0) {
		refclock_report(peer, CEVNT_FAULT);
		return;
	}
	if (up->pps_params.mode & PPS_CAPTUREASSERT) {
		ts = up->pps_info.assert_timestamp;
	} else if (up->pps_params.mode & PPS_CAPTURECLEAR) {
		ts = up->pps_info.clear_timestamp;
	} else {
		refclock_report(peer, CEVNT_FAULT);
		return;
	}

	/*
	 * There can be zero, one or two PPS seconds between polls. If
	 * zero, either the poll clock is slightly faster than the PPS
	 * clock or the PPS clock has died. If the PPS clock advanced
	 * once between polls, we make sure the fraction time difference
	 * since the last sample is within the range gate of 5 ms (500
	 * PPM). If the PPS clock advanced twice since the last poll,
	 * the poll bracketed more than one second and the first second
	 * was lost to a slip. Since the interval since the last sample
	 * found is now two seconds, just widen the range gate. If the
	 * PPS clock advanced three or more times, either the signal has
	 * failed for a number of seconds or we have runts, in which
	 * case just ignore them.
	 *
	 * If flag4 is lit, record each second offset to clockstats.
	 * That's so we can make awesome Allan deviation plots.
	 */
	sec = ts.tv_sec - up->ts.tv_sec;
	nsec = ts.tv_nsec - up->ts.tv_nsec;
	up->ts = ts;
	if (nsec < 0) {
		sec --;
		nsec += NANOSECOND;
	} else if (nsec >= NANOSECOND) {
		sec++;
		nsec -= NANOSECOND;
	}
	if (sec * NANOSECOND + nsec > NANOSECOND + RANGEGATE)
		return;

	else if (sec * NANOSECOND + nsec < NANOSECOND - RANGEGATE)
		return;

	pp->lastrec.l_ui = ts.tv_sec + JAN_1970;
	dtemp = ts.tv_nsec * FRAC / 1e9;
	if (dtemp >= FRAC)
		pp->lastrec.l_ui++;
	pp->lastrec.l_uf = (u_int32)dtemp;
	if (ts.tv_nsec > NANOSECOND / 2)
		ts.tv_nsec -= NANOSECOND;
	dtemp = -(double)ts.tv_nsec / NANOSECOND;
	SAMPLE(dtemp + pp->fudgetime1);
	if (pp->sloppyclockflag & CLK_FLAG4){
		sprintf(tbuf, "%.9f", dtemp);
		record_clock_stats(&peer->srcadr, tbuf);
	}
#ifdef DEBUG
	if (debug > 1)
		printf("atom_timer: %lu %f %f\n", current_time,
		    dtemp, pp->fudgetime1);
#endif
	return;
}
#endif /* HAVE_PPSAPI */


/*
 * pps_sample - receive PPS data from some other clock driver
 *
 * This routine is called once per second when the external clock driver
 * processes PPS information. It processes the PPS timestamp and saves
 * the sign-extended fraction in a circular buffer for processing at the
 * next poll event. This works only for a single PPS device.
 *
 * The routine should be used by another configured driver ONLY when
 * this driver is configured as well and the PPSAPI is NOT in use.
 */
int
pps_sample(
	   l_fp *offset		/* PPS offset */
	   )
{
	register struct peer *peer;
	struct refclockproc *pp;
	l_fp lftmp;
	double doffset;

	peer = pps_peer;
	if (peer == NULL)
		return (1);

	pp = peer->procptr;

	/*
	 * Convert the timeval to l_fp and save for billboards. Sign-
	 * extend the fraction and stash in the buffer. No harm is done
	 * if previous data are overwritten. If the discipline comes bum
	 * or the data grow stale, just forget it.
	 */ 
	pp->lastrec = *offset;
	L_CLR(&lftmp);
	L_ADDF(&lftmp, pp->lastrec.l_f);
	LFPTOD(&lftmp, doffset);
	SAMPLE(-doffset + pp->fudgetime1);
	return (0);
}


/*
 * atom_poll - called by the transmit procedure
 */
static void
atom_poll(
	int unit,		/* unit number (not used) */
	struct peer *peer	/* peer structure pointer */
	)
{
	struct refclockproc *pp;
	pp = peer->procptr;
	pp->polls++;

	/*
	 * Valid time is returned only if the prefer peer has survived
	 * the intersection algorithm and within 0.4 s of local time
	 * and not too long ago. This ensures the PPS time is within
	 * 0.5 s of the local time and the seconds numbering is
	 * unambiguous. Note that the leap bits, stratum and refid are
	 * set from the prefer peer, unless overriden by a fudge
	 * command.
	 */
	if (pp->codeproc == pp->coderecv) {
		refclock_report(peer, CEVNT_TIMEOUT);
		return;

	} else if (sys_prefer == NULL) {
		pp->codeproc = pp->coderecv;
		return;

	} else if (fabs(sys_prefer->offset) >= 0.4) {
		pp->codeproc = pp->coderecv;
		return;
	}
	pp->leap = sys_prefer->leap;
	if (pp->stratum >= STRATUM_UNSPEC)
		peer->stratum = sys_prefer->stratum;
	else
		peer->stratum = pp->stratum;
	pp->lastref = pp->lastrec;
	refclock_receive(peer);
}
#else
int refclock_atom_bs;
int
pps_sample(
	   l_fp *offset		/* PPS offset */
	   )
{
	return (1);
}
#endif /* REFCLOCK */