timepps-Solaris.h   [plain text]

/***********************************************************************
 *								       *
 * Copyright (c) David L. Mills 1999-2009			       *
 *								       *
 * 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.							       *
 *								       *
 ***********************************************************************
 *								       *
 * This header file complies with "Pulse-Per-Second API for UNIX-like  *
 * Operating Systems, Version 1.0", rfc2783. Credit is due Jeff Mogul  *
 * and Marc Brett, from whom much of this code was shamelessly stolen. *
 *								       *
 * this modified timepps.h can be used to provide a PPSAPI interface   *
 * to a machine running Solaris (2.6 and above).		       *
 *								       *
 ***********************************************************************
 *								       *
 * A full PPSAPI interface to the Solaris kernel would be better, but  *
 * this at least removes the necessity for special coding from the NTP *
 * NTP drivers. 						       *
 *								       *
 ***********************************************************************
 *								       *
 * Some of this include file					       *
 * Copyright (c) 1999 by Ulrich Windl,				       *
 *	based on code by Reg Clemens <reg@dwf.com>		       *
 *		based on code by Poul-Henning Kamp <phk@FreeBSD.org>   *
 *								       *
 ***********************************************************************
 *								       *
 * "THE BEER-WARE LICENSE" (Revision 42):                              *
 * <phk@FreeBSD.org> wrote this file.  As long as you retain this      *
 * notice you can do whatever you want with this stuff. If we meet some*
 * day, and you think this stuff is worth it, you can buy me a beer    *
 * in return.	Poul-Henning Kamp				       *
 *								       *
 **********************************************************************/

/* Solaris version, TIOCGPPSEV and TIOCSPPS assumed to exist. */

#ifndef _SYS_TIMEPPS_H_
#define _SYS_TIMEPPS_H_

#include <termios.h>	/* to get TOCGPPSEV and TIOCSPPS */

/* Implementation note: the logical states ``assert'' and ``clear''
 * are implemented in terms of the UART register, i.e. ``assert''
 * means the bit is set.
 */

/*
 * The following definitions are architecture independent
 */

#define PPS_API_VERS_1	1		/* API version number */
#define PPS_JAN_1970	2208988800UL	/* 1970 - 1900 in seconds */
#define PPS_NANOSECOND	1000000000L	/* one nanosecond in decimal */
#define PPS_FRAC	4294967296.	/* 2^32 as a double */

#define PPS_NORMALIZE(x)	/* normalize timespec */ \
	do { \
		if ((x).tv_nsec >= PPS_NANOSECOND) { \
			(x).tv_nsec -= PPS_NANOSECOND; \
			(x).tv_sec++; \
		} else if ((x).tv_nsec < 0) { \
			(x).tv_nsec += PPS_NANOSECOND; \
			(x).tv_sec--; \
		} \
	} while (0)

#define PPS_TSPECTONTP(x)	/* convert timespec to l_fp */ \
	do { \
		double d_temp; \
	\
		(x).integral += (unsigned int)PPS_JAN_1970; \
		d_temp = (x).fractional * PPS_FRAC / PPS_NANOSECOND; \
		if (d_temp >= PPS_FRAC) \
			(x).integral++; \
		(x).fractional = (unsigned int)d_temp; \
	} while (0)

/*
 * Device/implementation parameters (mode)
 */

#define PPS_CAPTUREASSERT	0x01	/* capture assert events */
#define PPS_CAPTURECLEAR	0x02	/* capture clear events */
#define PPS_CAPTUREBOTH 	0x03	/* capture assert and clear events */

#define PPS_OFFSETASSERT	0x10	/* apply compensation for assert ev. */
#define PPS_OFFSETCLEAR 	0x20	/* apply compensation for clear ev. */
#define PPS_OFFSETBOTH		0x30	/* apply compensation for both */

#define PPS_CANWAIT		0x100	/* Can we wait for an event? */
#define PPS_CANPOLL		0x200	/* "This bit is reserved for */

/*
 * Kernel actions (mode)
 */

#define PPS_ECHOASSERT		0x40	/* feed back assert event to output */
#define PPS_ECHOCLEAR		0x80	/* feed back clear event to output */

/*
 * Timestamp formats (tsformat)
 */

#define PPS_TSFMT_TSPEC 	0x1000	/* select timespec format */
#define PPS_TSFMT_NTPFP 	0x2000	/* select NTP format */

/*
 * Kernel discipline actions (not used in Solaris)
 */

#define PPS_KC_HARDPPS		0	/* enable kernel consumer */
#define PPS_KC_HARDPPS_PLL	1	/* phase-lock mode */
#define PPS_KC_HARDPPS_FLL	2	/* frequency-lock mode */

/*
 * Type definitions
 */

typedef unsigned long pps_seq_t;	/* sequence number */

typedef struct ntp_fp {
	unsigned int	integral;
	unsigned int	fractional;
} ntp_fp_t;				/* NTP-compatible time stamp */

typedef union pps_timeu {		/* timestamp format */
	struct timespec tspec;
	ntp_fp_t	ntpfp;
	unsigned long	longpad[3];
} pps_timeu_t;				/* generic data type to represent time stamps */

/*
 * Timestamp information structure
 */

typedef struct pps_info {
	pps_seq_t	assert_sequence;	/* seq. num. of assert event */
	pps_seq_t	clear_sequence; 	/* seq. num. of clear event */
	pps_timeu_t	assert_tu;		/* time of assert event */
	pps_timeu_t	clear_tu;		/* time of clear event */
	int		current_mode;		/* current mode bits */
} pps_info_t;

#define assert_timestamp	assert_tu.tspec
#define clear_timestamp 	clear_tu.tspec

#define assert_timestamp_ntpfp	assert_tu.ntpfp
#define clear_timestamp_ntpfp	clear_tu.ntpfp

/*
 * Parameter structure
 */

typedef struct pps_params {
	int		api_version;	/* API version # */
	int		mode;		/* mode bits */
	pps_timeu_t assert_off_tu;	/* offset compensation for assert */
	pps_timeu_t clear_off_tu;	/* offset compensation for clear */
} pps_params_t;

#define assert_offset		assert_off_tu.tspec
#define clear_offset		clear_off_tu.tspec

#define assert_offset_ntpfp	assert_off_tu.ntpfp
#define clear_offset_ntpfp	clear_off_tu.ntpfp

/* addition of NTP fixed-point format */

#define NTPFP_M_ADD(r_i, r_f, a_i, a_f) 	/* r += a */ \
	do { \
		register u_int32 lo_tmp; \
		register u_int32 hi_tmp; \
		\
		lo_tmp = ((r_f) & 0xffff) + ((a_f) & 0xffff); \
		hi_tmp = (((r_f) >> 16) & 0xffff) + (((a_f) >> 16) & 0xffff); \
		if (lo_tmp & 0x10000) \
			hi_tmp++; \
		(r_f) = ((hi_tmp & 0xffff) << 16) | (lo_tmp & 0xffff); \
		\
		(r_i) += (a_i); \
		if (hi_tmp & 0x10000) \
			(r_i)++; \
	} while (0)

#define	NTPFP_L_ADDS(r, a)	NTPFP_M_ADD((r)->integral, (r)->fractional, \
					    (int)(a)->integral, (a)->fractional)

/*
 * The following definitions are architecture-dependent
 */

#define PPS_CAP (PPS_CAPTUREASSERT | PPS_OFFSETASSERT | PPS_TSFMT_TSPEC | PPS_TSFMT_NTPFP)
#define PPS_RO	(PPS_CANWAIT | PPS_CANPOLL)

typedef struct {
	int filedes;		/* file descriptor */
	pps_params_t params;	/* PPS parameters set by user */
} pps_unit_t;

/*
 *------ Here begins the implementation-specific part! ------
 */

#include <errno.h>

/*
 * pps handlebars, which are required to be an opaque scalar.  This
 * implementation uses the handle as a pointer so it must be large
 * enough.  uintptr_t is as large as a pointer.
 */
typedef uintptr_t pps_handle_t; 

/*
 * create PPS handle from file descriptor
 */

static inline int
time_pps_create(
	int filedes,		/* file descriptor */
	pps_handle_t *handle	/* returned handle */
	)
{
	pps_unit_t *punit;
	int one = 1;

	/*
	 * Check for valid arguments and attach PPS signal.
	 */

	if (!handle) {
		errno = EFAULT;
		return (-1);	/* null pointer */
	}

	if (ioctl(filedes, TIOCSPPS, &one) < 0) {
		perror("refclock_ioctl: TIOCSPPS failed:");
		return (-1);
	}

	/*
	 * Allocate and initialize default unit structure.
	 */

	punit = malloc(sizeof(*punit));
	if (NULL == punit) {
		errno = ENOMEM;
		return (-1);	/* what, no memory? */
	}

	memset(punit, 0, sizeof(*punit));
	punit->filedes = filedes;
	punit->params.api_version = PPS_API_VERS_1;
	punit->params.mode = PPS_CAPTUREASSERT | PPS_TSFMT_TSPEC;

	*handle = (pps_handle_t)punit;
	return (0);
}

/*
 * release PPS handle
 */

static inline int
time_pps_destroy(
	pps_handle_t handle
	)
{
	pps_unit_t *punit;

	/*
	 * Check for valid arguments and detach PPS signal.
	 */

	if (!handle) {
		errno = EBADF;
		return (-1);	/* bad handle */
	}
	punit = (pps_unit_t *)handle;
	free(punit);
	return (0);
}

/*
 * set parameters for handle
 */

static inline int
time_pps_setparams(
	pps_handle_t handle,
	const pps_params_t *params
	)
{
	pps_unit_t *	punit;
	int		mode, mode_in;
	/*
	 * Check for valid arguments and set parameters.
	 */

	if (!handle) {
		errno = EBADF;
		return (-1);	/* bad handle */
	}

	if (!params) {
		errno = EFAULT;
		return (-1);	/* bad argument */
	}

	/*
	 * There was no reasonable consensu in the API working group.
	 * I require `api_version' to be set!
	 */

	if (params->api_version != PPS_API_VERS_1) {
		errno = EINVAL;
		return(-1);
	}

	/*
	 * only settable modes are PPS_CAPTUREASSERT and PPS_OFFSETASSERT
	 */

	mode_in = params->mode;
	punit = (pps_unit_t *)handle;

	/*
	 * Only one of the time formats may be selected
	 * if a nonzero assert offset is supplied.
	 */
	if ((mode_in & (PPS_TSFMT_TSPEC | PPS_TSFMT_NTPFP)) ==
	    (PPS_TSFMT_TSPEC | PPS_TSFMT_NTPFP)) {

		if (punit->params.assert_offset.tv_sec ||
			punit->params.assert_offset.tv_nsec) {

			errno = EINVAL;
			return(-1);
		}

		/*
		 * If no offset was specified but both time
		 * format flags are used consider it harmless
		 * but turn off PPS_TSFMT_NTPFP so getparams
		 * will not show both formats lit.
		 */
		mode_in &= ~PPS_TSFMT_NTPFP;
	}

	/* turn off read-only bits */

	mode_in &= ~PPS_RO;

	/*
	 * test remaining bits, should only have captureassert, 
	 * offsetassert, and/or timestamp format bits.
	 */

	if (mode_in & ~(PPS_CAPTUREASSERT | PPS_OFFSETASSERT |
			PPS_TSFMT_TSPEC | PPS_TSFMT_NTPFP)) {
		errno = EOPNOTSUPP;
		return(-1);
	}

	/*
	 * ok, ready to go.
	 */

	mode = punit->params.mode;
	memcpy(&punit->params, params, sizeof(punit->params));
	punit->params.api_version = PPS_API_VERS_1;
	punit->params.mode = mode | mode_in;
	return (0);
}

/*
 * get parameters for handle
 */

static inline int
time_pps_getparams(
	pps_handle_t handle,
	pps_params_t *params
	)
{
	pps_unit_t *	punit;

	/*
	 * Check for valid arguments and get parameters.
	 */

	if (!handle) {
		errno = EBADF;
		return (-1);	/* bad handle */
	}

	if (!params) {
		errno = EFAULT;
		return (-1);	/* bad argument */
	}

	punit = (pps_unit_t *)handle;
	memcpy(params, &punit->params, sizeof(params));
	return (0);
}

/*
 * get capabilities for handle
 */

static inline int
time_pps_getcap(
	pps_handle_t handle,
	int *mode
	)
{
	/*
	 * Check for valid arguments and get capabilities.
	 */

	if (!handle) {
		errno = EBADF;
		return (-1);	/* bad handle */
	}

	if (!mode) {
		errno = EFAULT;
		return (-1);	/* bad argument */
	}
	*mode = PPS_CAP;
	return (0);
}

/*
 * Fetch timestamps
 */

static inline int
time_pps_fetch(
	pps_handle_t handle,
	const int tsformat,
	pps_info_t *ppsinfo,
	const struct timespec *timeout
	)
{
	struct ppsclockev {
		struct timeval tv;
		u_int serial;
	} ev;

	pps_info_t	infobuf;
	pps_unit_t *	punit;

	/*
	 * Check for valid arguments and fetch timestamps
	 */

	if (!handle) {
		errno = EBADF;
		return (-1);	/* bad handle */
	}

	if (!ppsinfo) {
		errno = EFAULT;
		return (-1);	/* bad argument */
	}

	/*
	 * nb. PPS_CANWAIT is NOT set by the implementation, we can totally
	 * ignore the timeout variable.
	 */

	memset(&infobuf, 0, sizeof(infobuf));
	punit = (pps_unit_t *)handle;

	/*
	 * if not captureassert, nothing to return.
	 */

	if (!punit->params.mode & PPS_CAPTUREASSERT) {
		memcpy(ppsinfo, &infobuf, sizeof(*ppsinfo));
		return (0);
	}

	if (ioctl(punit->filedes, TIOCGPPSEV, (caddr_t) &ev) < 0) {
		perror("time_pps_fetch:");
		errno = EOPNOTSUPP;
		return(-1);
	}

	infobuf.assert_sequence = ev.serial;
	infobuf.assert_timestamp.tv_sec = ev.tv.tv_sec;
	infobuf.assert_timestamp.tv_nsec = ev.tv.tv_usec * 1000;

	/*
	 * Translate to specified format then apply offset
	 */

	switch (tsformat) {
	case PPS_TSFMT_TSPEC:
		/* timespec format requires no conversion */
		if (punit->params.mode & PPS_OFFSETASSERT) {
			infobuf.assert_timestamp.tv_sec  += 
				punit->params.assert_offset.tv_sec;
			infobuf.assert_timestamp.tv_nsec += 
				punit->params.assert_offset.tv_nsec;
			PPS_NORMALIZE(infobuf.assert_timestamp);
		}
		break;

	case PPS_TSFMT_NTPFP:
		/* NTP format requires conversion to fraction form */
		PPS_TSPECTONTP(infobuf.assert_timestamp_ntpfp);
		if (punit->params.mode & PPS_OFFSETASSERT)
			NTPFP_L_ADDS(&infobuf.assert_timestamp_ntpfp, 
				     &punit->params.assert_offset_ntpfp);
		break;		

	default:
		errno = EINVAL;
		return (-1);
	}

	infobuf.current_mode = punit->params.mode;
	memcpy(ppsinfo, &infobuf, sizeof(*ppsinfo));
	return (0);
}

/*
 * specify kernel consumer
 */

static inline int
time_pps_kcbind(
	pps_handle_t handle,
	const int kernel_consumer,
	const int edge,
	const int tsformat
	)
{
	/*
	 * Check for valid arguments and bind kernel consumer
	 */
	if (!handle) {
		errno = EBADF;
		return (-1);	/* bad handle */
	}
	if (geteuid() != 0) {
		errno = EPERM;
		return (-1);	/* must be superuser */
	}
	errno = EOPNOTSUPP;
	return(-1);
}

#endif /* _SYS_TIMEPPS_H_ */