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 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(long 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_ */