lib/libc/sys/ffclock.2

   1 .\" Copyright (c) 2011 The University of Melbourne
   2 .\" All rights reserved.
   3 .\"
   4 .\" This documentation was written by Julien Ridoux at the University of
   5 .\" Melbourne under sponsorship from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd November 21, 2011
  29 .Dt FFCLOCK 2
  30 .Os
  31 .Sh NAME
  32 .Nm ffclock_getcounter ,
  33 .Nm ffclock_getestimate ,
  34 .Nm ffclock_setestimate
  35 .Nd Retrieve feed-forward counter, get and set feed-forward clock estimates
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In sys/timeffc.h
  40 .Ft int
  41 .Fn ffclock_getcounter "ffcounter *ffcount"
  42 .Ft int
  43 .Fn ffclock_getestimate "struct ffclock_estimate *cest"
  44 .Ft int
  45 .Fn ffclock_setestimate "struct ffclock_estimate *cest"
  46 .Sh DESCRIPTION
  47 The ffclock is an alternative method to synchronise the system clock.
  48 The ffclock implements a feed-forward paradigm and decouples the timestamping
  49 and timekeeping kernel functions.
  50 This ensures that past clock errors do not affect current timekeeping, an
  51 approach radically different from the feedback alternative implemented by the
  52 ntpd daemon when adjusting the system clock.
  53 The feed-forward approach has demonstrated better performance and higher
  54 robustness than a feedback approach when synchronising over the network.
  55 .Pp
  56 In the feed-forward context, a
  57 .Em timestamp
  58 is a cumulative value of the ticks of the timecounter, which can be converted
  59 into seconds by using the feed-forward
  60 .Em clock estimates .
  61 .Pp
  62 The
  63 .Fn ffclock_getcounter
  64 system call allows the calling process to retrieve the current value of the
  65 feed-forward counter maintained by the kernel.
  66 .Pp
  67 The
  68 .Fn ffclock_getestimate
  69 and
  70 .Fn ffclock_setestimate
  71 system calls allow the caller to get and set the kernel's feed-forward clock
  72 parameter estimates respectively.
  73 The
  74 .Fn ffclock_setestimate
  75 system call should be invoked by a single instance of a feed-forward
  76 synchronisation daemon.
  77 The
  78 .Fn ffclock_getestimate
  79 system call can be called by any process to retrieve the feed-forward clock
  80 estimates.
  81 .Pp
  82 The feed-forward approach does not require that the clock estimates be retrieved
  83 every time a timestamp is to be converted into seconds.
  84 The number of system calls can therefore be greatly reduced if the calling
  85 process retrieves the clock estimates from the clock synchronisation daemon
  86 instead.
  87 The
  88 .Fn ffclock_getestimate
  89 must be used when the feed-forward synchronisation daemon is not running
  90 .Po see
  91 .Sx USAGE
  92 below
  93 .Pc .
  94 .Pp
  95 The clock parameter estimates structure pointed to by
  96 .Fa cest
  97 is defined in
  98 .In sys/timeffc.h
  99 as:
 100 .Bd -literal
 101 struct ffclock_estimate {
 102         struct bintime update_time;    /* Time of last estimates update. */
 103         ffcounter      update_ffcount; /* Counter value at last update. */
 104         ffcounter      leapsec_next;   /* Counter value of next leap second. */
 105         uint64_t       period;         /* Estimate of counter period. */
 106         uint32_t       errb_abs;       /* Bound on absolute clock error [ns]. */
 107         uint32_t       errb_rate;      /* Bound on counter rate error [ps/s]. */
 108         uint32_t       status;         /* Clock status. */
 109         int16_t        leapsec_total;  /* All leap seconds seen so far. */
 110         int8_t         leapsec;        /* Next leap second (in {-1,0,1}). */
 111 };
 112 .Ed
 113 .Pp
 114 Only the super-user may set the feed-forward clock estimates.
 115 .Sh RETURN VALUES
 116 .Rv -std
 117 .Sh ERRORS
 118 The following error codes may be set in
 119 .Va errno :
 120 .Bl -tag -width Er
 121 .It Bq Er EFAULT
 122 The
 123 .Fa ffcount
 124 or
 125 .Fa cest
 126 pointer referenced invalid memory.
 127 .It Bq Er EPERM
 128 A user other than the super-user attempted to set the feed-forward clock
 129 parameter estimates.
 130 .El
 131 .Sh USAGE
 132 The feed-forward paradigm enables the definition of specialised clock functions.
 133 .Pp
 134 In its simplest form,
 135 .Fn ffclock_getcounter
 136 can be used to establish strict order between events or to measure small time
 137 intervals very accurately with a minimum performance cost.
 138 .Pp
 139 Different methods exist to access absolute time
 140 .Po or
 141 .Qq wall-clock time
 142 .Pc tracked by the ffclock.
 143 The simplest method uses the ffclock sysctl interface
 144 .Va kern.ffclock
 145 to make the system clock return the ffclock time.
 146 The
 147 .Xr clock_gettime 2
 148 system call can then be used to retrieve the current time seen by the
 149 feed-forward clock.
 150 Note that this setting affects the entire system and that a feed-forward
 151 synchronisation daemon should be running.
 152 .Pp
 153 A less automated method consists of retrieving the feed-forward counter
 154 timestamp from the kernel and using the feed-forward clock parameter estimates
 155 to convert the timestamp into seconds.
 156 The feed-forward clock parameter estimates can be retrieved from the kernel or
 157 from the synchronisation daemon directly (preferred).
 158 This method allows converting timestamps using different clock models as needed
 159 by the application, while collecting meaningful upper bounds on current clock
 160 error.
 161 .Sh SEE ALSO
 162 .Xr date 1 ,
 163 .Xr adjtime 2 ,
 164 .Xr clock_gettime 2 ,
 165 .Xr ctime 3
 166 .Sh HISTORY
 167 Feed-forward clock support first appeared in
 168 .Fx 10.0 .
 169 .Sh AUTHORS
 170 .An -nosplit
 171 The feed-forward clock support was written by
 172 .An Julien Ridoux Aq Mt jridoux@unimelb.edu.au
 173 in collaboration with
 174 .An Darryl Veitch Aq Mt dveitch@unimelb.edu.au
 175 at the University of Melbourne under sponsorship from the FreeBSD Foundation.