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.\" $FreeBSD$ 29.\" 30.Dd November 21, 2011 31.Dt FFCLOCK 2 32.Os 33.Sh NAME 34.Nm ffclock_getcounter , 35.Nm ffclock_getestimate , 36.Nm ffclock_setestimate 37.Nd Retrieve feed-forward counter, get and set feed-forward clock estimates 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/timeffc.h 42.Ft int 43.Fn ffclock_getcounter "ffcounter *ffcount" 44.Ft int 45.Fn ffclock_getestimate "struct ffclock_estimate *cest" 46.Ft int 47.Fn ffclock_setestimate "struct ffclock_estimate *cest" 48.Sh DESCRIPTION 49The ffclock is an alternative method to synchronise the system clock. 50The ffclock implements a feed-forward paradigm and decouples the timestamping 51and timekeeping kernel functions. 52This ensures that past clock errors do not affect current timekeeping, an 53approach radically different from the feedback alternative implemented by the 54ntpd daemon when adjusting the system clock. 55The feed-forward approach has demonstrated better performance and higher 56robustness than a feedback approach when synchronising over the network. 57.Pp 58In the feed-forward context, a 59.Em timestamp 60is a cumulative value of the ticks of the timecounter, which can be converted 61into seconds by using the feed-forward 62.Em clock estimates . 63.Pp 64The 65.Fn ffclock_getcounter 66system call allows the calling process to retrieve the current value of the 67feed-forward counter maintained by the kernel. 68.Pp 69The 70.Fn ffclock_getestimate 71and 72.Fn ffclock_setestimate 73system calls allow the caller to get and set the kernel's feed-forward clock 74parameter estimates respectively. 75The 76.Fn ffclock_setestimate 77system call should be invoked by a single instance of a feed-forward 78synchronisation daemon. 79The 80.Fn ffclock_getestimate 81system call can be called by any process to retrieve the feed-forward clock 82estimates. 83.Pp 84The feed-forward approach does not require that the clock estimates be retrieved 85every time a timestamp is to be converted into seconds. 86The number of system calls can therefore be greatly reduced if the calling 87process retrieves the clock estimates from the clock synchronisation daemon 88instead. 89The 90.Fn ffclock_getestimate 91must be used when the feed-forward synchronisation daemon is not running 92.Po see 93.Sx USAGE 94below 95.Pc . 96.Pp 97The clock parameter estimates structure pointed to by 98.Fa cest 99is defined in 100.In sys/timeffc.h 101as: 102.Bd -literal 103struct ffclock_estimate { 104 struct bintime update_time; /* Time of last estimates update. */ 105 ffcounter update_ffcount; /* Counter value at last update. */ 106 ffcounter leapsec_next; /* Counter value of next leap second. */ 107 uint64_t period; /* Estimate of counter period. */ 108 uint32_t errb_abs; /* Bound on absolute clock error [ns]. */ 109 uint32_t errb_rate; /* Bound on counter rate error [ps/s]. */ 110 uint32_t status; /* Clock status. */ 111 int16_t leapsec_total; /* All leap seconds seen so far. */ 112 int8_t leapsec; /* Next leap second (in {-1,0,1}). */ 113}; 114.Ed 115.Pp 116Only the super-user may set the feed-forward clock estimates. 117.Sh RETURN VALUES 118.Rv -std 119.Sh ERRORS 120The following error codes may be set in 121.Va errno : 122.Bl -tag -width Er 123.It Bq Er EFAULT 124The 125.Fa ffcount 126or 127.Fa cest 128pointer referenced invalid memory. 129.It Bq Er EPERM 130A user other than the super-user attempted to set the feed-forward clock 131parameter estimates. 132.El 133.Sh USAGE 134The feed-forward paradigm enables the definition of specialised clock functions. 135.Pp 136In its simplest form, 137.Fn ffclock_getcounter 138can be used to establish strict order between events or to measure small time 139intervals very accurately with a minimum performance cost. 140.Pp 141Different methods exist to access absolute time 142.Po or 143.Qq wall-clock time 144.Pc tracked by the ffclock. 145The simplest method uses the ffclock sysctl interface 146.Va kern.ffclock 147to make the system clock return the ffclock time. 148The 149.Xr clock_gettime 2 150system call can then be used to retrieve the current time seen by the 151feed-forward clock. 152Note that this setting affects the entire system and that a feed-forward 153synchronisation daemon should be running. 154.Pp 155A less automated method consists of retrieving the feed-forward counter 156timestamp from the kernel and using the feed-forward clock parameter estimates 157to convert the timestamp into seconds. 158The feed-forward clock parameter estimates can be retrieved from the kernel or 159from the synchronisation daemon directly (preferred). 160This method allows converting timestamps using different clock models as needed 161by the application, while collecting meaningful upper bounds on current clock 162error. 163.Sh SEE ALSO 164.Xr date 1 , 165.Xr adjtime 2 , 166.Xr clock_gettime 2 , 167.Xr ctime 3 168.Sh HISTORY 169Feed-forward clock support first appeared in 170.Fx 10.0 . 171.Sh AUTHORS 172.An -nosplit 173The feed-forward clock support was written by 174.An Julien Ridoux Aq Mt [email protected] 175in collaboration with 176.An Darryl Veitch Aq Mt [email protected] 177at the University of Melbourne under sponsorship from the FreeBSD Foundation. 178