1/*-
  2 * SPDX-License-Identifier: Beerware
  3 *
  4 * ----------------------------------------------------------------------------
  5 * "THE BEER-WARE LICENSE" (Revision 42):
  6 * <phk@FreeBSD.ORG> wrote this file.  As long as you retain this notice you
  7 * can do whatever you want with this stuff. If we meet some day, and you think
  8 * this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
  9 * ----------------------------------------------------------------------------
 10 */
 11
 12#ifndef _SYS_TIMETC_H_
 13#define	_SYS_TIMETC_H_
 14
 15#ifndef _KERNEL
 16#error "no user-serviceable parts inside"
 17#endif
 18
 19/*-
 20 * `struct timecounter' is the interface between the hardware which implements
 21 * a timecounter and the MI code which uses this to keep track of time.
 22 *
 23 * A timecounter is a binary counter which has two properties:
 24 *    * it runs at a fixed, known frequency.
 25 *    * it has sufficient bits to not roll over in less than approximately
 26 *      max(2 msec, 2/HZ seconds).  (The value 2 here is really 1 + delta,
 27 *      for some indeterminate value of delta.)
 28 */
 29
 30struct timecounter;
 31struct vdso_timehands;
 32struct vdso_timehands32;
 33typedef u_int timecounter_get_t(struct timecounter *);
 34typedef void timecounter_pps_t(struct timecounter *);
 35typedef uint32_t timecounter_fill_vdso_timehands_t(struct vdso_timehands *,
 36    struct timecounter *);
 37typedef uint32_t timecounter_fill_vdso_timehands32_t(struct vdso_timehands32 *,
 38    struct timecounter *);
 39
 40struct timecounter {
 41	timecounter_get_t	*tc_get_timecount;
 42		/*
 43		 * This function reads the counter.  It is not required to
 44		 * mask any unimplemented bits out, as long as they are
 45		 * constant.
 46		 */
 47	timecounter_pps_t	*tc_poll_pps;
 48		/*
 49		 * This function is optional.  It will be called whenever the
 50		 * timecounter is rewound, and is intended to check for PPS
 51		 * events.  Normal hardware does not need it but timecounters
 52		 * which latch PPS in hardware (like sys/pci/xrpu.c) do.
 53		 */
 54	u_int 			tc_counter_mask;
 55		/* This mask should mask off any unimplemented bits. */
 56	uint64_t		tc_frequency;
 57		/* Frequency of the counter in Hz. */
 58	const char		*tc_name;
 59		/* Name of the timecounter. */
 60	int			tc_quality;
 61		/*
 62		 * Used to determine if this timecounter is better than
 63		 * another timecounter higher means better.  Negative
 64		 * means "only use at explicit request".
 65		 */
 66	u_int			tc_flags;
 67#define	TC_FLAGS_C2STOP		1	/* Timer dies in C2+. */
 68#define	TC_FLAGS_SUSPEND_SAFE	2	/*
 69					 * Timer functional across
 70					 * suspend/resume.
 71					 */
 72
 73	void			*tc_priv;
 74		/* Pointer to the timecounter's private parts. */
 75	struct timecounter	*tc_next;
 76		/* Pointer to the next timecounter. */
 77	timecounter_fill_vdso_timehands_t *tc_fill_vdso_timehands;
 78	timecounter_fill_vdso_timehands32_t *tc_fill_vdso_timehands32;
 79};
 80
 81extern struct timecounter *timecounter;
 82extern int tc_min_ticktock_freq; /*
 83				  * Minimal tc_ticktock() call frequency,
 84				  * required to handle counter wraps.
 85				  */
 86
 87u_int64_t tc_getfrequency(void);
 88void	tc_init(struct timecounter *tc);
 89void	tc_setclock(struct timespec *ts);
 90void	tc_ticktock(int cnt);
 91void	cpu_tick_calibration(void);
 92
 93#ifdef SYSCTL_DECL
 94SYSCTL_DECL(_kern_timecounter);
 95#endif
 96
 97/**
 98 * clockcalib(clk, clkname):
 99 * Return the frequency of the provided timer, as calibrated against the
100 * current best-available timecounter.
101 */
102uint64_t clockcalib(uint64_t (*)(void), const char *);
103
104#endif /* !_SYS_TIMETC_H_ */