sys/sys/timeffc.h

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