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 47The ffclock is an alternative method to synchronise the system clock. 48The ffclock implements a feed-forward paradigm and decouples the timestamping 49and timekeeping kernel functions. 50This ensures that past clock errors do not affect current timekeeping, an 51approach radically different from the feedback alternative implemented by the 52ntpd daemon when adjusting the system clock. 53The feed-forward approach has demonstrated better performance and higher 54robustness than a feedback approach when synchronising over the network. 55.Pp 56In the feed-forward context, a 57.Em timestamp 58is a cumulative value of the ticks of the timecounter, which can be converted 59into seconds by using the feed-forward 60.Em clock estimates . 61.Pp 62The 63.Fn ffclock_getcounter 64system call allows the calling process to retrieve the current value of the 65feed-forward counter maintained by the kernel. 66.Pp 67The 68.Fn ffclock_getestimate 69and 70.Fn ffclock_setestimate 71system calls allow the caller to get and set the kernel's feed-forward clock 72parameter estimates respectively. 73The 74.Fn ffclock_setestimate 75system call should be invoked by a single instance of a feed-forward 76synchronisation daemon. 77The 78.Fn ffclock_getestimate 79system call can be called by any process to retrieve the feed-forward clock 80estimates. 81.Pp 82The feed-forward approach does not require that the clock estimates be retrieved 83every time a timestamp is to be converted into seconds. 84The number of system calls can therefore be greatly reduced if the calling 85process retrieves the clock estimates from the clock synchronisation daemon 86instead. 87The 88.Fn ffclock_getestimate 89must be used when the feed-forward synchronisation daemon is not running 90.Po see 91.Sx USAGE 92below 93.Pc . 94.Pp 95The clock parameter estimates structure pointed to by 96.Fa cest 97is defined in 98.In sys/timeffc.h 99as: 100.Bd -literal 101struct 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 114Only the super-user may set the feed-forward clock estimates. 115.Sh RETURN VALUES 116.Rv -std 117.Sh ERRORS 118The following error codes may be set in 119.Va errno : 120.Bl -tag -width Er 121.It Bq Er EFAULT 122The 123.Fa ffcount 124or 125.Fa cest 126pointer referenced invalid memory. 127.It Bq Er EPERM 128A user other than the super-user attempted to set the feed-forward clock 129parameter estimates. 130.El 131.Sh USAGE 132The feed-forward paradigm enables the definition of specialised clock functions. 133.Pp 134In its simplest form, 135.Fn ffclock_getcounter 136can be used to establish strict order between events or to measure small time 137intervals very accurately with a minimum performance cost. 138.Pp 139Different methods exist to access absolute time 140.Po or 141.Qq wall-clock time 142.Pc tracked by the ffclock. 143The simplest method uses the ffclock sysctl interface 144.Va kern.ffclock 145to make the system clock return the ffclock time. 146The 147.Xr clock_gettime 2 148system call can then be used to retrieve the current time seen by the 149feed-forward clock. 150Note that this setting affects the entire system and that a feed-forward 151synchronisation daemon should be running. 152.Pp 153A less automated method consists of retrieving the feed-forward counter 154timestamp from the kernel and using the feed-forward clock parameter estimates 155to convert the timestamp into seconds. 156The feed-forward clock parameter estimates can be retrieved from the kernel or 157from the synchronisation daemon directly (preferred). 158This method allows converting timestamps using different clock models as needed 159by the application, while collecting meaningful upper bounds on current clock 160error. 161.Sh SEE ALSO 162.Xr date 1 , 163.Xr adjtime 2 , 164.Xr clock_gettime 2 , 165.Xr ctime 3 166.Sh HISTORY 167Feed-forward clock support first appeared in 168.Fx 10.0 . 169.Sh AUTHORS 170.An -nosplit 171The feed-forward clock support was written by 172.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au 173in collaboration with 174.An Darryl Veitch Aq Mt dveitch@unimelb.edu.au 175at the University of Melbourne under sponsorship from the FreeBSD Foundation. 176