sys/sys/timeffc.h

   1 /*-
   2  * Copyright (c) 2011 The University of Melbourne
   3  * All rights reserved.
   4  *
   5  * This software was developed by Julien Ridoux at the University of Melbourne
   6  * under sponsorship from the FreeBSD Foundation.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in the
  15  *    documentation and/or other materials provided with the distribution.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27  * SUCH DAMAGE.
  28  *
  29  * $FreeBSD$
  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_ */