xref: /freebsd-src/sys/sys/timeffc.h (revision 95ee2897e98f5d444f26ed2334cc7c439f9c16c6)

/*-
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * Copyright (c) 2011 The University of Melbourne
 * All rights reserved.
 *
 * This software was developed by Julien Ridoux at the University of Melbourne
 * under sponsorship from the FreeBSD Foundation.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

#ifndef _SYS_TIMEFF_H_
#define _SYS_TIMEFF_H_

#include <sys/_ffcounter.h>

/*
 * Feed-forward clock estimate
 * Holds time mark as a ffcounter and conversion to bintime based on current
 * timecounter period and offset estimate passed by the synchronization daemon.
 * Provides time of last daemon update, clock status and bound on error.
 */
struct ffclock_estimate {
	struct bintime	update_time;	/* Time of last estimates update. */
	ffcounter	update_ffcount;	/* Counter value at last update. */
	ffcounter	leapsec_next;	/* Counter value of next leap second. */
	uint64_t	period;		/* Estimate of counter period. */
	uint32_t	errb_abs;	/* Bound on absolute clock error [ns]. */
	uint32_t	errb_rate;	/* Bound on counter rate error [ps/s]. */
	uint32_t	status;		/* Clock status. */
	int16_t		leapsec_total;	/* All leap seconds seen so far. */
	int8_t		leapsec;	/* Next leap second (in {-1,0,1}). */
};

#if __BSD_VISIBLE
#ifdef _KERNEL

/* Define the kern.sysclock sysctl tree. */
SYSCTL_DECL(_kern_sysclock);

/* Define the kern.sysclock.ffclock sysctl tree. */
SYSCTL_DECL(_kern_sysclock_ffclock);

/*
 * Index into the sysclocks array for obtaining the ASCII name of a particular
 * sysclock.
 */
#define	SYSCLOCK_FBCK	0
#define	SYSCLOCK_FFWD	1
extern int sysclock_active;

/*
 * Parameters of counter characterisation required by feed-forward algorithms.
 */
#define	FFCLOCK_SKM_SCALE	1024

/*
 * Feed-forward clock status
 */
#define	FFCLOCK_STA_UNSYNC	1
#define	FFCLOCK_STA_WARMUP	2

/*
 * Flags for use by sysclock_snap2bintime() and various ffclock_ functions to
 * control how the timecounter hardware is read and how the hardware snapshot is
 * converted into absolute time.
 * {FB|FF}CLOCK_FAST:	Do not read the hardware counter, instead using the
 *			value at last tick. The time returned has a resolution
 *			of the kernel tick timer (1/hz [s]).
 * FFCLOCK_LERP:	Linear interpolation of ffclock time to guarantee
 *			monotonic time.
 * FFCLOCK_LEAPSEC:	Include leap seconds.
 * {FB|FF}CLOCK_UPTIME:	Time stamp should be relative to system boot, not epoch.
 */
#define	FFCLOCK_FAST		0x00000001
#define	FFCLOCK_LERP		0x00000002
#define	FFCLOCK_LEAPSEC		0x00000004
#define	FFCLOCK_UPTIME		0x00000008
#define	FFCLOCK_MASK		0x0000ffff

#define	FBCLOCK_FAST		0x00010000 /* Currently unused. */
#define	FBCLOCK_UPTIME		0x00020000
#define	FBCLOCK_MASK		0xffff0000

/*
 * Feedback clock specific info structure. The feedback clock's estimation of
 * clock error is an absolute figure determined by the NTP algorithm. The status
 * is determined by the userland daemon.
 */
struct fbclock_info {
	struct bintime		error;
	struct bintime		tick_time;
	uint64_t		th_scale;
	int			status;
};

/*
 * Feed-forward clock specific info structure. The feed-forward clock's
 * estimation of clock error is an upper bound, which although potentially
 * looser than the feedback clock equivalent, is much more reliable. The status
 * is determined by the userland daemon.
 */
struct ffclock_info {
	struct bintime		error;
	struct bintime		tick_time;
	struct bintime		tick_time_lerp;
	uint64_t		period;
	uint64_t		period_lerp;
	int			leapsec_adjustment;
	int			status;
};

/*
 * Snapshot of system clocks and related information. Holds time read from each
 * clock based on a single read of the active hardware timecounter, as well as
 * respective clock information such as error estimates and the ffcounter value
 * at the time of the read.
 */
struct sysclock_snap {
	struct fbclock_info	fb_info;
	struct ffclock_info	ff_info;
	ffcounter		ffcount;
	unsigned int		delta;
	int			sysclock_active;
};

/* Take a snapshot of the system clocks and related information. */
void sysclock_getsnapshot(struct sysclock_snap *clock_snap, int fast);

/* Convert a timestamp from the selected system clock into bintime. */
int sysclock_snap2bintime(struct sysclock_snap *cs, struct bintime *bt,
    int whichclock, uint32_t flags);

/* Resets feed-forward clock from RTC */
void ffclock_reset_clock(struct timespec *ts);

/*
 * Return the current value of the feed-forward clock counter. Essential to
 * measure time interval in counter units. If a fast timecounter is used by the
 * system, may also allow fast but accurate timestamping.
 */
void ffclock_read_counter(ffcounter *ffcount);

/*
 * Retrieve feed-forward counter value and time of last kernel tick. This
 * accepts the FFCLOCK_LERP flag.
 */
void ffclock_last_tick(ffcounter *ffcount, struct bintime *bt, uint32_t flags);

/*
 * Low level routines to convert a counter timestamp into absolute time and a
 * counter timestamp interval into an interval in seconds. The absolute time
 * conversion accepts the FFCLOCK_LERP flag.
 */
void ffclock_convert_abs(ffcounter ffcount, struct bintime *bt, uint32_t flags);
void ffclock_convert_diff(ffcounter ffdelta, struct bintime *bt);

/*
 * Feed-forward clock routines.
 *
 * These functions rely on the timecounters and ffclock_estimates stored in
 * fftimehands. Note that the error_bound parameter is not the error of the
 * clock but an upper bound on the error of the absolute time or time interval
 * returned.
 *
 * ffclock_abstime(): retrieves current time as counter value and convert this
 *     timestamp in seconds. The value (in seconds) of the converted timestamp
 *     depends on the flags passed: for a given counter value, different
 *     conversions are possible. Different clock models can be selected by
 *     combining flags (for example (FFCLOCK_LERP|FFCLOCK_UPTIME) produces
 *     linearly interpolated uptime).
 * ffclock_difftime(): computes a time interval in seconds based on an interval
 *     measured in ffcounter units. This should be the preferred way to measure
 *     small time intervals very accurately.
 */
void ffclock_abstime(ffcounter *ffcount, struct bintime *bt,
    struct bintime *error_bound, uint32_t flags);
void ffclock_difftime(ffcounter ffdelta, struct bintime *bt,
    struct bintime *error_bound);

/*
 * Wrapper routines to return current absolute time using the feed-forward
 * clock. These functions are named after those defined in <sys/time.h>, which
 * contains a description of the original ones.
 */
void ffclock_bintime(struct bintime *bt);
void ffclock_nanotime(struct timespec *tsp);
void ffclock_microtime(struct timeval *tvp);

void ffclock_getbintime(struct bintime *bt);
void ffclock_getnanotime(struct timespec *tsp);
void ffclock_getmicrotime(struct timeval *tvp);

void ffclock_binuptime(struct bintime *bt);
void ffclock_nanouptime(struct timespec *tsp);
void ffclock_microuptime(struct timeval *tvp);

void ffclock_getbinuptime(struct bintime *bt);
void ffclock_getnanouptime(struct timespec *tsp);
void ffclock_getmicrouptime(struct timeval *tvp);

/*
 * Wrapper routines to convert a time interval specified in ffcounter units into
 * seconds using the current feed-forward clock estimates.
 */
void ffclock_bindifftime(ffcounter ffdelta, struct bintime *bt);
void ffclock_nanodifftime(ffcounter ffdelta, struct timespec *tsp);
void ffclock_microdifftime(ffcounter ffdelta, struct timeval *tvp);

/*
 * When FFCLOCK is enabled in the kernel, [get]{bin,nano,micro}[up]time() become
 * wrappers around equivalent feedback or feed-forward functions. Provide access
 * outside of kern_tc.c to the feedback clock equivalent functions for
 * specialised use i.e. these are not for general consumption.
 */
void fbclock_bintime(struct bintime *bt);
void fbclock_nanotime(struct timespec *tsp);
void fbclock_microtime(struct timeval *tvp);

void fbclock_getbintime(struct bintime *bt);
void fbclock_getnanotime(struct timespec *tsp);
void fbclock_getmicrotime(struct timeval *tvp);

void fbclock_binuptime(struct bintime *bt);
void fbclock_nanouptime(struct timespec *tsp);
void fbclock_microuptime(struct timeval *tvp);

void fbclock_getbinuptime(struct bintime *bt);
void fbclock_getnanouptime(struct timespec *tsp);
void fbclock_getmicrouptime(struct timeval *tvp);

/*
 * Public system clock wrapper API which allows consumers to select which clock
 * to obtain time from, independent of the current default system clock. These
 * wrappers should be used instead of directly calling the underlying fbclock_
 * or ffclock_ functions.
 */
static inline void
bintime_fromclock(struct bintime *bt, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_bintime(bt);
	else
		fbclock_bintime(bt);
}

static inline void
nanotime_fromclock(struct timespec *tsp, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_nanotime(tsp);
	else
		fbclock_nanotime(tsp);
}

static inline void
microtime_fromclock(struct timeval *tvp, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_microtime(tvp);
	else
		fbclock_microtime(tvp);
}

static inline void
getbintime_fromclock(struct bintime *bt, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_getbintime(bt);
	else
		fbclock_getbintime(bt);
}

static inline void
getnanotime_fromclock(struct timespec *tsp, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_getnanotime(tsp);
	else
		fbclock_getnanotime(tsp);
}

static inline void
getmicrotime_fromclock(struct timeval *tvp, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_getmicrotime(tvp);
	else
		fbclock_getmicrotime(tvp);
}

static inline void
binuptime_fromclock(struct bintime *bt, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_binuptime(bt);
	else
		fbclock_binuptime(bt);
}

static inline void
nanouptime_fromclock(struct timespec *tsp, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_nanouptime(tsp);
	else
		fbclock_nanouptime(tsp);
}

static inline void
microuptime_fromclock(struct timeval *tvp, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_microuptime(tvp);
	else
		fbclock_microuptime(tvp);
}

static inline void
getbinuptime_fromclock(struct bintime *bt, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_getbinuptime(bt);
	else
		fbclock_getbinuptime(bt);
}

static inline void
getnanouptime_fromclock(struct timespec *tsp, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_getnanouptime(tsp);
	else
		fbclock_getnanouptime(tsp);
}

static inline void
getmicrouptime_fromclock(struct timeval *tvp, int whichclock)
{

	if (whichclock == SYSCLOCK_FFWD)
		ffclock_getmicrouptime(tvp);
	else
		fbclock_getmicrouptime(tvp);
}

#else /* !_KERNEL */

/* Feed-Forward Clock system calls. */
__BEGIN_DECLS
int ffclock_getcounter(ffcounter *ffcount);
int ffclock_getestimate(struct ffclock_estimate *cest);
int ffclock_setestimate(struct ffclock_estimate *cest);
__END_DECLS

#endif /* _KERNEL */
#endif /* __BSD_VISIBLE */
#endif /* _SYS_TIMEFF_H_ */