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 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 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 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 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 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 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 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 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 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 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 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 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