1 /*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 2011 The University of Melbourne
5 * All rights reserved.
6 *
7 * This software was developed by Julien Ridoux at the University of Melbourne
8 * under sponsorship from the FreeBSD Foundation.
9 *
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
12 * are met:
13 * 1. Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in the
17 * documentation and/or other materials provided with the distribution.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
23 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 * SUCH DAMAGE.
30 */
31
32 #ifndef _SYS_TIMEFF_H_
33 #define _SYS_TIMEFF_H_
34
35 #include <sys/_ffcounter.h>
36
37 /*
38 * Feed-forward clock estimate
39 * Holds time mark as a ffcounter and conversion to bintime based on current
40 * timecounter period and offset estimate passed by the synchronization daemon.
41 * Provides time of last daemon update, clock status and bound on error.
42 */
43 struct ffclock_estimate {
44 struct bintime update_time; /* Time of last estimates update. */
45 ffcounter update_ffcount; /* Counter value at last update. */
46 ffcounter leapsec_next; /* Counter value of next leap second. */
47 uint64_t period; /* Estimate of counter period. */
48 uint32_t errb_abs; /* Bound on absolute clock error [ns]. */
49 uint32_t errb_rate; /* Bound on counter rate error [ps/s]. */
50 uint32_t status; /* Clock status. */
51 int16_t leapsec_total; /* All leap seconds seen so far. */
52 int8_t leapsec; /* Next leap second (in {-1,0,1}). */
53 };
54
55 #if __BSD_VISIBLE
56 #ifdef _KERNEL
57
58 /* Define the kern.sysclock sysctl tree. */
59 SYSCTL_DECL(_kern_sysclock);
60
61 /* Define the kern.sysclock.ffclock sysctl tree. */
62 SYSCTL_DECL(_kern_sysclock_ffclock);
63
64 /*
65 * Index into the sysclocks array for obtaining the ASCII name of a particular
66 * sysclock.
67 */
68 #define SYSCLOCK_FBCK 0
69 #define SYSCLOCK_FFWD 1
70 extern int sysclock_active;
71
72 /*
73 * Parameters of counter characterisation required by feed-forward algorithms.
74 */
75 #define FFCLOCK_SKM_SCALE 1024
76
77 /*
78 * Feed-forward clock status
79 */
80 #define FFCLOCK_STA_UNSYNC 1
81 #define FFCLOCK_STA_WARMUP 2
82
83 /*
84 * Flags for use by sysclock_snap2bintime() and various ffclock_ functions to
85 * control how the timecounter hardware is read and how the hardware snapshot is
86 * converted into absolute time.
87 * {FB|FF}CLOCK_FAST: Do not read the hardware counter, instead using the
88 * value at last tick. The time returned has a resolution
89 * of the kernel tick timer (1/hz [s]).
90 * FFCLOCK_LERP: Linear interpolation of ffclock time to guarantee
91 * monotonic time.
92 * FFCLOCK_LEAPSEC: Include leap seconds.
93 * {FB|FF}CLOCK_UPTIME: Time stamp should be relative to system boot, not epoch.
94 */
95 #define FFCLOCK_FAST 0x00000001
96 #define FFCLOCK_LERP 0x00000002
97 #define FFCLOCK_LEAPSEC 0x00000004
98 #define FFCLOCK_UPTIME 0x00000008
99 #define FFCLOCK_MASK 0x0000ffff
100
101 #define FBCLOCK_FAST 0x00010000 /* Currently unused. */
102 #define FBCLOCK_UPTIME 0x00020000
103 #define FBCLOCK_MASK 0xffff0000
104
105 /*
106 * Feedback clock specific info structure. The feedback clock's estimation of
107 * clock error is an absolute figure determined by the NTP algorithm. The status
108 * is determined by the userland daemon.
109 */
110 struct fbclock_info {
111 struct bintime error;
112 struct bintime tick_time;
113 uint64_t th_scale;
114 int status;
115 };
116
117 /*
118 * Feed-forward clock specific info structure. The feed-forward clock's
119 * estimation of clock error is an upper bound, which although potentially
120 * looser than the feedback clock equivalent, is much more reliable. The status
121 * is determined by the userland daemon.
122 */
123 struct ffclock_info {
124 struct bintime error;
125 struct bintime tick_time;
126 struct bintime tick_time_lerp;
127 uint64_t period;
128 uint64_t period_lerp;
129 int leapsec_adjustment;
130 int status;
131 };
132
133 /*
134 * Snapshot of system clocks and related information. Holds time read from each
135 * clock based on a single read of the active hardware timecounter, as well as
136 * respective clock information such as error estimates and the ffcounter value
137 * at the time of the read.
138 */
139 struct sysclock_snap {
140 struct fbclock_info fb_info;
141 struct ffclock_info ff_info;
142 ffcounter ffcount;
143 unsigned int delta;
144 int sysclock_active;
145 };
146
147 /* Take a snapshot of the system clocks and related information. */
148 void sysclock_getsnapshot(struct sysclock_snap *clock_snap, int fast);
149
150 /* Convert a timestamp from the selected system clock into bintime. */
151 int sysclock_snap2bintime(struct sysclock_snap *cs, struct bintime *bt,
152 int whichclock, uint32_t flags);
153
154 /* Resets feed-forward clock from RTC */
155 void ffclock_reset_clock(struct timespec *ts);
156
157 /*
158 * Return the current value of the feed-forward clock counter. Essential to
159 * measure time interval in counter units. If a fast timecounter is used by the
160 * system, may also allow fast but accurate timestamping.
161 */
162 void ffclock_read_counter(ffcounter *ffcount);
163
164 /*
165 * Retrieve feed-forward counter value and time of last kernel tick. This
166 * accepts the FFCLOCK_LERP flag.
167 */
168 void ffclock_last_tick(ffcounter *ffcount, struct bintime *bt, uint32_t flags);
169
170 /*
171 * Low level routines to convert a counter timestamp into absolute time and a
172 * counter timestamp interval into an interval in seconds. The absolute time
173 * conversion accepts the FFCLOCK_LERP flag.
174 */
175 void ffclock_convert_abs(ffcounter ffcount, struct bintime *bt, uint32_t flags);
176 void ffclock_convert_diff(ffcounter ffdelta, struct bintime *bt);
177
178 /*
179 * Feed-forward clock routines.
180 *
181 * These functions rely on the timecounters and ffclock_estimates stored in
182 * fftimehands. Note that the error_bound parameter is not the error of the
183 * clock but an upper bound on the error of the absolute time or time interval
184 * returned.
185 *
186 * ffclock_abstime(): retrieves current time as counter value and convert this
187 * timestamp in seconds. The value (in seconds) of the converted timestamp
188 * depends on the flags passed: for a given counter value, different
189 * conversions are possible. Different clock models can be selected by
190 * combining flags (for example (FFCLOCK_LERP|FFCLOCK_UPTIME) produces
191 * linearly interpolated uptime).
192 * ffclock_difftime(): computes a time interval in seconds based on an interval
193 * measured in ffcounter units. This should be the preferred way to measure
194 * small time intervals very accurately.
195 */
196 void ffclock_abstime(ffcounter *ffcount, struct bintime *bt,
197 struct bintime *error_bound, uint32_t flags);
198 void ffclock_difftime(ffcounter ffdelta, struct bintime *bt,
199 struct bintime *error_bound);
200
201 /*
202 * Wrapper routines to return current absolute time using the feed-forward
203 * clock. These functions are named after those defined in <sys/time.h>, which
204 * contains a description of the original ones.
205 */
206 void ffclock_bintime(struct bintime *bt);
207 void ffclock_nanotime(struct timespec *tsp);
208 void ffclock_microtime(struct timeval *tvp);
209
210 void ffclock_getbintime(struct bintime *bt);
211 void ffclock_getnanotime(struct timespec *tsp);
212 void ffclock_getmicrotime(struct timeval *tvp);
213
214 void ffclock_binuptime(struct bintime *bt);
215 void ffclock_nanouptime(struct timespec *tsp);
216 void ffclock_microuptime(struct timeval *tvp);
217
218 void ffclock_getbinuptime(struct bintime *bt);
219 void ffclock_getnanouptime(struct timespec *tsp);
220 void ffclock_getmicrouptime(struct timeval *tvp);
221
222 /*
223 * Wrapper routines to convert a time interval specified in ffcounter units into
224 * seconds using the current feed-forward clock estimates.
225 */
226 void ffclock_bindifftime(ffcounter ffdelta, struct bintime *bt);
227 void ffclock_nanodifftime(ffcounter ffdelta, struct timespec *tsp);
228 void ffclock_microdifftime(ffcounter ffdelta, struct timeval *tvp);
229
230 /*
231 * When FFCLOCK is enabled in the kernel, [get]{bin,nano,micro}[up]time() become
232 * wrappers around equivalent feedback or feed-forward functions. Provide access
233 * outside of kern_tc.c to the feedback clock equivalent functions for
234 * specialised use i.e. these are not for general consumption.
235 */
236 void fbclock_bintime(struct bintime *bt);
237 void fbclock_nanotime(struct timespec *tsp);
238 void fbclock_microtime(struct timeval *tvp);
239
240 void fbclock_getbintime(struct bintime *bt);
241 void fbclock_getnanotime(struct timespec *tsp);
242 void fbclock_getmicrotime(struct timeval *tvp);
243
244 void fbclock_binuptime(struct bintime *bt);
245 void fbclock_nanouptime(struct timespec *tsp);
246 void fbclock_microuptime(struct timeval *tvp);
247
248 void fbclock_getbinuptime(struct bintime *bt);
249 void fbclock_getnanouptime(struct timespec *tsp);
250 void fbclock_getmicrouptime(struct timeval *tvp);
251
252 /*
253 * Public system clock wrapper API which allows consumers to select which clock
254 * to obtain time from, independent of the current default system clock. These
255 * wrappers should be used instead of directly calling the underlying fbclock_
256 * or ffclock_ functions.
257 */
258 static inline void
bintime_fromclock(struct bintime * bt,int whichclock)259 bintime_fromclock(struct bintime *bt, int whichclock)
260 {
261
262 if (whichclock == SYSCLOCK_FFWD)
263 ffclock_bintime(bt);
264 else
265 fbclock_bintime(bt);
266 }
267
268 static inline void
nanotime_fromclock(struct timespec * tsp,int whichclock)269 nanotime_fromclock(struct timespec *tsp, int whichclock)
270 {
271
272 if (whichclock == SYSCLOCK_FFWD)
273 ffclock_nanotime(tsp);
274 else
275 fbclock_nanotime(tsp);
276 }
277
278 static inline void
microtime_fromclock(struct timeval * tvp,int whichclock)279 microtime_fromclock(struct timeval *tvp, int whichclock)
280 {
281
282 if (whichclock == SYSCLOCK_FFWD)
283 ffclock_microtime(tvp);
284 else
285 fbclock_microtime(tvp);
286 }
287
288 static inline void
getbintime_fromclock(struct bintime * bt,int whichclock)289 getbintime_fromclock(struct bintime *bt, int whichclock)
290 {
291
292 if (whichclock == SYSCLOCK_FFWD)
293 ffclock_getbintime(bt);
294 else
295 fbclock_getbintime(bt);
296 }
297
298 static inline void
getnanotime_fromclock(struct timespec * tsp,int whichclock)299 getnanotime_fromclock(struct timespec *tsp, int whichclock)
300 {
301
302 if (whichclock == SYSCLOCK_FFWD)
303 ffclock_getnanotime(tsp);
304 else
305 fbclock_getnanotime(tsp);
306 }
307
308 static inline void
getmicrotime_fromclock(struct timeval * tvp,int whichclock)309 getmicrotime_fromclock(struct timeval *tvp, int whichclock)
310 {
311
312 if (whichclock == SYSCLOCK_FFWD)
313 ffclock_getmicrotime(tvp);
314 else
315 fbclock_getmicrotime(tvp);
316 }
317
318 static inline void
binuptime_fromclock(struct bintime * bt,int whichclock)319 binuptime_fromclock(struct bintime *bt, int whichclock)
320 {
321
322 if (whichclock == SYSCLOCK_FFWD)
323 ffclock_binuptime(bt);
324 else
325 fbclock_binuptime(bt);
326 }
327
328 static inline void
nanouptime_fromclock(struct timespec * tsp,int whichclock)329 nanouptime_fromclock(struct timespec *tsp, int whichclock)
330 {
331
332 if (whichclock == SYSCLOCK_FFWD)
333 ffclock_nanouptime(tsp);
334 else
335 fbclock_nanouptime(tsp);
336 }
337
338 static inline void
microuptime_fromclock(struct timeval * tvp,int whichclock)339 microuptime_fromclock(struct timeval *tvp, int whichclock)
340 {
341
342 if (whichclock == SYSCLOCK_FFWD)
343 ffclock_microuptime(tvp);
344 else
345 fbclock_microuptime(tvp);
346 }
347
348 static inline void
getbinuptime_fromclock(struct bintime * bt,int whichclock)349 getbinuptime_fromclock(struct bintime *bt, int whichclock)
350 {
351
352 if (whichclock == SYSCLOCK_FFWD)
353 ffclock_getbinuptime(bt);
354 else
355 fbclock_getbinuptime(bt);
356 }
357
358 static inline void
getnanouptime_fromclock(struct timespec * tsp,int whichclock)359 getnanouptime_fromclock(struct timespec *tsp, int whichclock)
360 {
361
362 if (whichclock == SYSCLOCK_FFWD)
363 ffclock_getnanouptime(tsp);
364 else
365 fbclock_getnanouptime(tsp);
366 }
367
368 static inline void
getmicrouptime_fromclock(struct timeval * tvp,int whichclock)369 getmicrouptime_fromclock(struct timeval *tvp, int whichclock)
370 {
371
372 if (whichclock == SYSCLOCK_FFWD)
373 ffclock_getmicrouptime(tvp);
374 else
375 fbclock_getmicrouptime(tvp);
376 }
377
378 #else /* !_KERNEL */
379
380 /* Feed-Forward Clock system calls. */
381 __BEGIN_DECLS
382 int ffclock_getcounter(ffcounter *ffcount);
383 int ffclock_getestimate(struct ffclock_estimate *cest);
384 int ffclock_setestimate(struct ffclock_estimate *cest);
385 __END_DECLS
386
387 #endif /* _KERNEL */
388 #endif /* __BSD_VISIBLE */
389 #endif /* _SYS_TIMEFF_H_ */
390