include/sys/timeffc.h

0001 /**
0002  * @file
0003  *
0004  * @ingroup RTEMSScoreTimecounter
0005  *
0006  * @brief This header file provides interfaces of the feed-back and
0007  *   feed-forward clock implementations.
0008  */
0009
0010 /*-
0011  * SPDX-License-Identifier: BSD-2-Clause
0012  *
0013  * Copyright (c) 2011 The University of Melbourne
0014  * All rights reserved.
0015  *
0016  * This software was developed by Julien Ridoux at the University of Melbourne
0017  * under sponsorship from the FreeBSD Foundation.
0018  *
0019  * Redistribution and use in source and binary forms, with or without
0020  * modification, are permitted provided that the following conditions
0021  * are met:
0022  * 1. Redistributions of source code must retain the above copyright
0023  *    notice, this list of conditions and the following disclaimer.
0024  * 2. Redistributions in binary form must reproduce the above copyright
0025  *    notice, this list of conditions and the following disclaimer in the
0026  *    documentation and/or other materials provided with the distribution.
0027  *
0028  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
0029  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0030  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0031  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
0032  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
0033  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
0034  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
0035  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
0036  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
0037  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
0038  * SUCH DAMAGE.
0039  */
0040
0041 #ifndef _SYS_TIMEFF_H_
0042 #define _SYS_TIMEFF_H_
0043
0044 #include <sys/_ffcounter.h>
0045
0046 /*
0047  * Feed-forward clock estimate
0048  * Holds time mark as a ffcounter and conversion to bintime based on current
0049  * timecounter period and offset estimate passed by the synchronization daemon.
0050  * Provides time of last daemon update, clock status and bound on error.
0051  */
0052 struct ffclock_estimate {
0053     struct bintime  update_time;    /* Time of last estimates update. */
0054     ffcounter   update_ffcount; /* Counter value at last update. */
0055     ffcounter   leapsec_next;   /* Counter value of next leap second. */
0056     uint64_t    period;     /* Estimate of counter period. */
0057     uint32_t    errb_abs;   /* Bound on absolute clock error [ns]. */
0058     uint32_t    errb_rate;  /* Bound on counter rate error [ps/s]. */
0059     uint32_t    status;     /* Clock status. */
0060     int16_t     leapsec_total;  /* All leap seconds seen so far. */
0061     int8_t      leapsec;    /* Next leap second (in {-1,0,1}). */
0062 };
0063
0064 #if __BSD_VISIBLE
0065 #ifdef _KERNEL
0066
0067 #ifndef __rtems__
0068 /* Define the kern.sysclock sysctl tree. */
0069 SYSCTL_DECL(_kern_sysclock);
0070
0071 /* Define the kern.sysclock.ffclock sysctl tree. */
0072 SYSCTL_DECL(_kern_sysclock_ffclock);
0073 #endif /* __rtems__ */
0074
0075 /*
0076  * Index into the sysclocks array for obtaining the ASCII name of a particular
0077  * sysclock.
0078  */
0079 #define SYSCLOCK_FBCK   0
0080 #define SYSCLOCK_FFWD   1
0081 extern int sysclock_active;
0082
0083 /*
0084  * Parameters of counter characterisation required by feed-forward algorithms.
0085  */
0086 #define FFCLOCK_SKM_SCALE   1024
0087
0088 /*
0089  * Feed-forward clock status
0090  */
0091 #define FFCLOCK_STA_UNSYNC  1
0092 #define FFCLOCK_STA_WARMUP  2
0093
0094 /*
0095  * Flags for use by sysclock_snap2bintime() and various ffclock_ functions to
0096  * control how the timecounter hardware is read and how the hardware snapshot is
0097  * converted into absolute time.
0098  * {FB|FF}CLOCK_FAST:   Do not read the hardware counter, instead using the
0099  *          value at last tick. The time returned has a resolution
0100  *          of the kernel tick timer (1/hz [s]).
0101  * FFCLOCK_LERP:    Linear interpolation of ffclock time to guarantee
0102  *          monotonic time.
0103  * FFCLOCK_LEAPSEC: Include leap seconds.
0104  * {FB|FF}CLOCK_UPTIME: Time stamp should be relative to system boot, not epoch.
0105  */
0106 #define FFCLOCK_FAST        0x00000001
0107 #define FFCLOCK_LERP        0x00000002
0108 #define FFCLOCK_LEAPSEC     0x00000004
0109 #define FFCLOCK_UPTIME      0x00000008
0110 #define FFCLOCK_MASK        0x0000ffff
0111
0112 #define FBCLOCK_FAST        0x00010000 /* Currently unused. */
0113 #define FBCLOCK_UPTIME      0x00020000
0114 #define FBCLOCK_MASK        0xffff0000
0115
0116 /*
0117  * Feedback clock specific info structure. The feedback clock's estimation of
0118  * clock error is an absolute figure determined by the NTP algorithm. The status
0119  * is determined by the userland daemon.
0120  */
0121 struct fbclock_info {
0122     struct bintime      error;
0123     struct bintime      tick_time;
0124     uint64_t        th_scale;
0125     int         status;
0126 };
0127
0128 /*
0129  * Feed-forward clock specific info structure. The feed-forward clock's
0130  * estimation of clock error is an upper bound, which although potentially
0131  * looser than the feedback clock equivalent, is much more reliable. The status
0132  * is determined by the userland daemon.
0133  */
0134 struct ffclock_info {
0135     struct bintime      error;
0136     struct bintime      tick_time;
0137     struct bintime      tick_time_lerp;
0138     uint64_t        period;
0139     uint64_t        period_lerp;
0140     int         leapsec_adjustment;
0141     int         status;
0142 };
0143
0144 /*
0145  * Snapshot of system clocks and related information. Holds time read from each
0146  * clock based on a single read of the active hardware timecounter, as well as
0147  * respective clock information such as error estimates and the ffcounter value
0148  * at the time of the read.
0149  */
0150 struct sysclock_snap {
0151     struct fbclock_info fb_info;
0152     struct ffclock_info ff_info;
0153     ffcounter       ffcount;
0154     unsigned int        delta;
0155     int         sysclock_active;
0156 };
0157
0158 /* Take a snapshot of the system clocks and related information. */
0159 void sysclock_getsnapshot(struct sysclock_snap *clock_snap, int fast);
0160
0161 /* Convert a timestamp from the selected system clock into bintime. */
0162 int sysclock_snap2bintime(struct sysclock_snap *cs, struct bintime *bt,
0163     int whichclock, uint32_t flags);
0164
0165 /* Resets feed-forward clock from RTC */
0166 void ffclock_reset_clock(struct timespec *ts);
0167
0168 /*
0169  * Return the current value of the feed-forward clock counter. Essential to
0170  * measure time interval in counter units. If a fast timecounter is used by the
0171  * system, may also allow fast but accurate timestamping.
0172  */
0173 void ffclock_read_counter(ffcounter *ffcount);
0174
0175 /*
0176  * Retrieve feed-forward counter value and time of last kernel tick. This
0177  * accepts the FFCLOCK_LERP flag.
0178  */
0179 void ffclock_last_tick(ffcounter *ffcount, struct bintime *bt, uint32_t flags);
0180
0181 /*
0182  * Low level routines to convert a counter timestamp into absolute time and a
0183  * counter timestamp interval into an interval in seconds. The absolute time
0184  * conversion accepts the FFCLOCK_LERP flag.
0185  */
0186 void ffclock_convert_abs(ffcounter ffcount, struct bintime *bt, uint32_t flags);
0187 void ffclock_convert_diff(ffcounter ffdelta, struct bintime *bt);
0188
0189 /*
0190  * Feed-forward clock routines.
0191  *
0192  * These functions rely on the timecounters and ffclock_estimates stored in
0193  * fftimehands. Note that the error_bound parameter is not the error of the
0194  * clock but an upper bound on the error of the absolute time or time interval
0195  * returned.
0196  *
0197  * ffclock_abstime(): retrieves current time as counter value and convert this
0198  *     timestamp in seconds. The value (in seconds) of the converted timestamp
0199  *     depends on the flags passed: for a given counter value, different
0200  *     conversions are possible. Different clock models can be selected by
0201  *     combining flags (for example (FFCLOCK_LERP|FFCLOCK_UPTIME) produces
0202  *     linearly interpolated uptime).
0203  * ffclock_difftime(): computes a time interval in seconds based on an interval
0204  *     measured in ffcounter units. This should be the preferred way to measure
0205  *     small time intervals very accurately.
0206  */
0207 void ffclock_abstime(ffcounter *ffcount, struct bintime *bt,
0208     struct bintime *error_bound, uint32_t flags);
0209 void ffclock_difftime(ffcounter ffdelta, struct bintime *bt,
0210     struct bintime *error_bound);
0211
0212 /*
0213  * Wrapper routines to return current absolute time using the feed-forward
0214  * clock. These functions are named after those defined in <sys/time.h>, which
0215  * contains a description of the original ones.
0216  */
0217 void ffclock_bintime(struct bintime *bt);
0218 void ffclock_nanotime(struct timespec *tsp);
0219 void ffclock_microtime(struct timeval *tvp);
0220
0221 void ffclock_getbintime(struct bintime *bt);
0222 void ffclock_getnanotime(struct timespec *tsp);
0223 void ffclock_getmicrotime(struct timeval *tvp);
0224
0225 void ffclock_binuptime(struct bintime *bt);
0226 void ffclock_nanouptime(struct timespec *tsp);
0227 void ffclock_microuptime(struct timeval *tvp);
0228
0229 void ffclock_getbinuptime(struct bintime *bt);
0230 void ffclock_getnanouptime(struct timespec *tsp);
0231 void ffclock_getmicrouptime(struct timeval *tvp);
0232
0233 /*
0234  * Wrapper routines to convert a time interval specified in ffcounter units into
0235  * seconds using the current feed-forward clock estimates.
0236  */
0237 void ffclock_bindifftime(ffcounter ffdelta, struct bintime *bt);
0238 void ffclock_nanodifftime(ffcounter ffdelta, struct timespec *tsp);
0239 void ffclock_microdifftime(ffcounter ffdelta, struct timeval *tvp);
0240
0241 /*
0242  * When FFCLOCK is enabled in the kernel, [get]{bin,nano,micro}[up]time() become
0243  * wrappers around equivalent feedback or feed-forward functions. Provide access
0244  * outside of kern_tc.c to the feedback clock equivalent functions for
0245  * specialised use i.e. these are not for general consumption.
0246  */
0247 void fbclock_bintime(struct bintime *bt);
0248 void fbclock_nanotime(struct timespec *tsp);
0249 void fbclock_microtime(struct timeval *tvp);
0250
0251 void fbclock_getbintime(struct bintime *bt);
0252 void fbclock_getnanotime(struct timespec *tsp);
0253 void fbclock_getmicrotime(struct timeval *tvp);
0254
0255 void fbclock_binuptime(struct bintime *bt);
0256 void fbclock_nanouptime(struct timespec *tsp);
0257 void fbclock_microuptime(struct timeval *tvp);
0258
0259 void fbclock_getbinuptime(struct bintime *bt);
0260 void fbclock_getnanouptime(struct timespec *tsp);
0261 void fbclock_getmicrouptime(struct timeval *tvp);
0262
0263 /*
0264  * Public system clock wrapper API which allows consumers to select which clock
0265  * to obtain time from, independent of the current default system clock. These
0266  * wrappers should be used instead of directly calling the underlying fbclock_
0267  * or ffclock_ functions.
0268  */
0269 static inline void
0270 bintime_fromclock(struct bintime *bt, int whichclock)
0271 {
0272
0273     if (whichclock == SYSCLOCK_FFWD)
0274         ffclock_bintime(bt);
0275     else
0276         fbclock_bintime(bt);
0277 }
0278
0279 static inline void
0280 nanotime_fromclock(struct timespec *tsp, int whichclock)
0281 {
0282
0283     if (whichclock == SYSCLOCK_FFWD)
0284         ffclock_nanotime(tsp);
0285     else
0286         fbclock_nanotime(tsp);
0287 }
0288
0289 static inline void
0290 microtime_fromclock(struct timeval *tvp, int whichclock)
0291 {
0292
0293     if (whichclock == SYSCLOCK_FFWD)
0294         ffclock_microtime(tvp);
0295     else
0296         fbclock_microtime(tvp);
0297 }
0298
0299 static inline void
0300 getbintime_fromclock(struct bintime *bt, int whichclock)
0301 {
0302
0303     if (whichclock == SYSCLOCK_FFWD)
0304         ffclock_getbintime(bt);
0305     else
0306         fbclock_getbintime(bt);
0307 }
0308
0309 static inline void
0310 getnanotime_fromclock(struct timespec *tsp, int whichclock)
0311 {
0312
0313     if (whichclock == SYSCLOCK_FFWD)
0314         ffclock_getnanotime(tsp);
0315     else
0316         fbclock_getnanotime(tsp);
0317 }
0318
0319 static inline void
0320 getmicrotime_fromclock(struct timeval *tvp, int whichclock)
0321 {
0322
0323     if (whichclock == SYSCLOCK_FFWD)
0324         ffclock_getmicrotime(tvp);
0325     else
0326         fbclock_getmicrotime(tvp);
0327 }
0328
0329 static inline void
0330 binuptime_fromclock(struct bintime *bt, int whichclock)
0331 {
0332
0333     if (whichclock == SYSCLOCK_FFWD)
0334         ffclock_binuptime(bt);
0335     else
0336         fbclock_binuptime(bt);
0337 }
0338
0339 static inline void
0340 nanouptime_fromclock(struct timespec *tsp, int whichclock)
0341 {
0342
0343     if (whichclock == SYSCLOCK_FFWD)
0344         ffclock_nanouptime(tsp);
0345     else
0346         fbclock_nanouptime(tsp);
0347 }
0348
0349 static inline void
0350 microuptime_fromclock(struct timeval *tvp, int whichclock)
0351 {
0352
0353     if (whichclock == SYSCLOCK_FFWD)
0354         ffclock_microuptime(tvp);
0355     else
0356         fbclock_microuptime(tvp);
0357 }
0358
0359 static inline void
0360 getbinuptime_fromclock(struct bintime *bt, int whichclock)
0361 {
0362
0363     if (whichclock == SYSCLOCK_FFWD)
0364         ffclock_getbinuptime(bt);
0365     else
0366         fbclock_getbinuptime(bt);
0367 }
0368
0369 static inline void
0370 getnanouptime_fromclock(struct timespec *tsp, int whichclock)
0371 {
0372
0373     if (whichclock == SYSCLOCK_FFWD)
0374         ffclock_getnanouptime(tsp);
0375     else
0376         fbclock_getnanouptime(tsp);
0377 }
0378
0379 static inline void
0380 getmicrouptime_fromclock(struct timeval *tvp, int whichclock)
0381 {
0382
0383     if (whichclock == SYSCLOCK_FFWD)
0384         ffclock_getmicrouptime(tvp);
0385     else
0386         fbclock_getmicrouptime(tvp);
0387 }
0388
0389 #else /* !_KERNEL */
0390
0391 /* Feed-Forward Clock system calls. */
0392 __BEGIN_DECLS
0393 int ffclock_getcounter(ffcounter *ffcount);
0394 int ffclock_getestimate(struct ffclock_estimate *cest);
0395 int ffclock_setestimate(struct ffclock_estimate *cest);
0396 __END_DECLS
0397
0398 #endif /* _KERNEL */
0399 #endif /* __BSD_VISIBLE */
0400 #endif /* _SYS_TIMEFF_H_ */