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  * Clock flags to select how the feed-forward counter is converted to absolute
  85  * time by ffclock_convert_abs().
  86  * FAST:    do not read the hardware counter, return feed-forward clock time
  87  *          at last tick. The time returned has the resolution of the kernel
  88  *          tick (1/hz [s]).
  89  * LERP:    linear interpolation of ffclock time to guarantee monotonic time.
  90  * LEAPSEC: include leap seconds.
  91  * UPTIME:  removes time of boot.
  92  */
  93 #define FFCLOCK_FAST            1
  94 #define FFCLOCK_LERP            2
  95 #define FFCLOCK_LEAPSEC         4
  96 #define FFCLOCK_UPTIME          8
  97
  98 /* Resets feed-forward clock from RTC */
  99 void ffclock_reset_clock(struct timespec *ts);
 100
 101 /*
 102  * Return the current value of the feed-forward clock counter. Essential to
 103  * measure time interval in counter units. If a fast timecounter is used by the
 104  * system, may also allow fast but accurate timestamping.
 105  */
 106 void ffclock_read_counter(ffcounter *ffcount);
 107
 108 /*
 109  * Retrieve feed-forward counter value and time of last kernel tick. This
 110  * accepts the FFCLOCK_LERP flag.
 111  */
 112 void ffclock_last_tick(ffcounter *ffcount, struct bintime *bt, uint32_t flags);
 113
 114 /*
 115  * Low level routines to convert a counter timestamp into absolute time and a
 116  * counter timestamp interval into an interval in seconds. The absolute time
 117  * conversion accepts the FFCLOCK_LERP flag.
 118  */
 119 void ffclock_convert_abs(ffcounter ffcount, struct bintime *bt, uint32_t flags);
 120 void ffclock_convert_diff(ffcounter ffdelta, struct bintime *bt);
 121
 122 /*
 123  * Feed-forward clock routines.
 124  *
 125  * These functions rely on the timecounters and ffclock_estimates stored in
 126  * fftimehands. Note that the error_bound parameter is not the error of the
 127  * clock but an upper bound on the error of the absolute time or time interval
 128  * returned.
 129  *
 130  * ffclock_abstime(): retrieves current time as counter value and convert this
 131  *     timestamp in seconds. The value (in seconds) of the converted timestamp
 132  *     depends on the flags passed: for a given counter value, different
 133  *     conversions are possible. Different clock models can be selected by
 134  *     combining flags (for example (FFCLOCK_LERP|FFCLOCK_UPTIME) produces
 135  *     linearly interpolated uptime).
 136  * ffclock_difftime(): computes a time interval in seconds based on an interval
 137  *     measured in ffcounter units. This should be the preferred way to measure
 138  *     small time intervals very accurately.
 139  */
 140 void ffclock_abstime(ffcounter *ffcount, struct bintime *bt,
 141     struct bintime *error_bound, uint32_t flags);
 142 void ffclock_difftime(ffcounter ffdelta, struct bintime *bt,
 143     struct bintime *error_bound);
 144
 145 /*
 146  * Wrapper routines to return current absolute time using the feed-forward
 147  * clock. These functions are named after those defined in <sys/time.h>, which
 148  * contains a description of the original ones.
 149  */
 150 void ffclock_bintime(struct bintime *bt);
 151 void ffclock_nanotime(struct timespec *tsp);
 152 void ffclock_microtime(struct timeval *tvp);
 153
 154 void ffclock_getbintime(struct bintime *bt);
 155 void ffclock_getnanotime(struct timespec *tsp);
 156 void ffclock_getmicrotime(struct timeval *tvp);
 157
 158 void ffclock_binuptime(struct bintime *bt);
 159 void ffclock_nanouptime(struct timespec *tsp);
 160 void ffclock_microuptime(struct timeval *tvp);
 161
 162 void ffclock_getbinuptime(struct bintime *bt);
 163 void ffclock_getnanouptime(struct timespec *tsp);
 164 void ffclock_getmicrouptime(struct timeval *tvp);
 165
 166 /*
 167  * Wrapper routines to convert a time interval specified in ffcounter units into
 168  * seconds using the current feed-forward clock estimates.
 169  */
 170 void ffclock_bindifftime(ffcounter ffdelta, struct bintime *bt);
 171 void ffclock_nanodifftime(ffcounter ffdelta, struct timespec *tsp);
 172 void ffclock_microdifftime(ffcounter ffdelta, struct timeval *tvp);
 173
 174 /*
 175  * When FFCLOCK is enabled in the kernel, [get]{bin,nano,micro}[up]time() become
 176  * wrappers around equivalent feedback or feed-forward functions. Provide access
 177  * outside of kern_tc.c to the feedback clock equivalent functions for
 178  * specialised use i.e. these are not for general consumption.
 179  */
 180 void fbclock_bintime(struct bintime *bt);
 181 void fbclock_nanotime(struct timespec *tsp);
 182 void fbclock_microtime(struct timeval *tvp);
 183
 184 void fbclock_getbintime(struct bintime *bt);
 185 void fbclock_getnanotime(struct timespec *tsp);
 186 void fbclock_getmicrotime(struct timeval *tvp);
 187
 188 void fbclock_binuptime(struct bintime *bt);
 189 void fbclock_nanouptime(struct timespec *tsp);
 190 void fbclock_microuptime(struct timeval *tvp);
 191
 192 void fbclock_getbinuptime(struct bintime *bt);
 193 void fbclock_getnanouptime(struct timespec *tsp);
 194 void fbclock_getmicrouptime(struct timeval *tvp);
 195
 196 /*
 197  * Public system clock wrapper API which allows consumers to select which clock
 198  * to obtain time from, independent of the current default system clock. These
 199  * wrappers should be used instead of directly calling the underlying fbclock_
 200  * or ffclock_ functions.
 201  */
 202 static inline void
 203 bintime_fromclock(struct bintime *bt, int whichclock)
 204 {
 205
 206         if (whichclock == SYSCLOCK_FFWD)
 207                 ffclock_bintime(bt);
 208         else
 209                 fbclock_bintime(bt);
 210 }
 211
 212 static inline void
 213 nanotime_fromclock(struct timespec *tsp, int whichclock)
 214 {
 215
 216         if (whichclock == SYSCLOCK_FFWD)
 217                 ffclock_nanotime(tsp);
 218         else
 219                 fbclock_nanotime(tsp);
 220 }
 221
 222 static inline void
 223 microtime_fromclock(struct timeval *tvp, int whichclock)
 224 {
 225
 226         if (whichclock == SYSCLOCK_FFWD)
 227                 ffclock_microtime(tvp);
 228         else
 229                 fbclock_microtime(tvp);
 230 }
 231
 232 static inline void
 233 getbintime_fromclock(struct bintime *bt, int whichclock)
 234 {
 235
 236         if (whichclock == SYSCLOCK_FFWD)
 237                 ffclock_getbintime(bt);
 238         else
 239                 fbclock_getbintime(bt);
 240 }
 241
 242 static inline void
 243 getnanotime_fromclock(struct timespec *tsp, int whichclock)
 244 {
 245
 246         if (whichclock == SYSCLOCK_FFWD)
 247                 ffclock_getnanotime(tsp);
 248         else
 249                 fbclock_getnanotime(tsp);
 250 }
 251
 252 static inline void
 253 getmicrotime_fromclock(struct timeval *tvp, int whichclock)
 254 {
 255
 256         if (whichclock == SYSCLOCK_FFWD)
 257                 ffclock_getmicrotime(tvp);
 258         else
 259                 fbclock_getmicrotime(tvp);
 260 }
 261
 262 static inline void
 263 binuptime_fromclock(struct bintime *bt, int whichclock)
 264 {
 265
 266         if (whichclock == SYSCLOCK_FFWD)
 267                 ffclock_binuptime(bt);
 268         else
 269                 fbclock_binuptime(bt);
 270 }
 271
 272 static inline void
 273 nanouptime_fromclock(struct timespec *tsp, int whichclock)
 274 {
 275
 276         if (whichclock == SYSCLOCK_FFWD)
 277                 ffclock_nanouptime(tsp);
 278         else
 279                 fbclock_nanouptime(tsp);
 280 }
 281
 282 static inline void
 283 microuptime_fromclock(struct timeval *tvp, int whichclock)
 284 {
 285
 286         if (whichclock == SYSCLOCK_FFWD)
 287                 ffclock_microuptime(tvp);
 288         else
 289                 fbclock_microuptime(tvp);
 290 }
 291
 292 static inline void
 293 getbinuptime_fromclock(struct bintime *bt, int whichclock)
 294 {
 295
 296         if (whichclock == SYSCLOCK_FFWD)
 297                 ffclock_getbinuptime(bt);
 298         else
 299                 fbclock_getbinuptime(bt);
 300 }
 301
 302 static inline void
 303 getnanouptime_fromclock(struct timespec *tsp, int whichclock)
 304 {
 305
 306         if (whichclock == SYSCLOCK_FFWD)
 307                 ffclock_getnanouptime(tsp);
 308         else
 309                 fbclock_getnanouptime(tsp);
 310 }
 311
 312 static inline void
 313 getmicrouptime_fromclock(struct timeval *tvp, int whichclock)
 314 {
 315
 316         if (whichclock == SYSCLOCK_FFWD)
 317                 ffclock_getmicrouptime(tvp);
 318         else
 319                 fbclock_getmicrouptime(tvp);
 320 }
 321
 322 #else /* !_KERNEL */
 323
 324 /* Feed-Forward Clock system calls. */
 325 __BEGIN_DECLS
 326 int ffclock_getcounter(ffcounter *ffcount);
 327 int ffclock_getestimate(struct ffclock_estimate *cest);
 328 int ffclock_setestimate(struct ffclock_estimate *cest);
 329 __END_DECLS
 330
 331 #endif /* _KERNEL */
 332 #endif /* __BSD_VISIBLE */
 333 #endif /* _SYS_TIMEFF_H_ */