1 .\" Copyright (c) 2011 The University of Melbourne
2 .\" All rights reserved.
4 .\" This documentation was written by Julien Ridoux at the University of
5 .\" Melbourne under sponsorship from the FreeBSD Foundation.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
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
43 .Fn ffclock_getcounter "ffcounter *ffcount"
45 .Fn ffclock_getestimate "struct ffclock_estimate *cest"
47 .Fn ffclock_setestimate "struct ffclock_estimate *cest"
49 The ffclock is an alternative method to synchronise the system clock.
50 The ffclock implements a feed-forward paradigm and decouples the timestamping
51 and timekeeping kernel functions.
52 This ensures that past clock errors do not affect current timekeeping, an
53 approach radically different from the feedback alternative implemented by the
54 ntpd daemon when adjusting the system clock.
55 The feed-forward approach has demonstrated better performance and higher
56 robustness than a feedback approach when synchronising over the network.
58 In the feed-forward context, a
60 is a cumulative value of the ticks of the timecounter, which can be converted
61 into seconds by using the feed-forward
65 .Fn ffclock_getcounter
66 system call allows the calling process to retrieve the current value of the
67 feed-forward counter maintained by the kernel.
70 .Fn ffclock_getestimate
72 .Fn ffclock_setestimate
73 system calls allow the caller to get and set the kernel's feed-forward clock
74 parameter estimates respectively.
76 .Fn ffclock_setestimate
77 system call should be invoked by a single instance of a feed-forward
78 synchronisation daemon.
80 .Fn ffclock_getestimate
81 system call can be called by any process to retrieve the feed-forward clock
84 The feed-forward approach does not require that the clock estimates be retrieved
85 every time a timestamp is to be converted into seconds.
86 The number of system calls can therefore be greatly reduced if the calling
87 process retrieves the clock estimates from the clock synchronisation daemon
90 .Fn ffclock_getestimate
91 must be used when the feed-forward synchronisation daemon is not running
97 The clock parameter estimates structure pointed to by
103 struct 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}). */
116 Only the super-user may set the feed-forward clock estimates.
120 The following error codes may be set in
128 pointer referenced invalid memory.
130 A user other than the super-user attempted to set the feed-forward clock
134 The feed-forward paradigm enables the definition of specialised clock functions.
136 In its simplest form,
137 .Fn ffclock_getcounter
138 can be used to establish strict order between events or to measure small time
139 intervals very accurately with a minimum performance cost.
141 Different methods exist to access absolute time
144 .Pc tracked by the ffclock.
145 The simplest method uses the ffclock sysctl interface
147 to make the system clock return the ffclock time.
150 system call can then be used to retrieve the current time seen by the
152 Note that this setting affects the entire system and that a feed-forward
153 synchronisation daemon should be running.
155 A less automated method consists of retrieving the feed-forward counter
156 timestamp from the kernel and using the feed-forward clock parameter estimates
157 to convert the timestamp into seconds.
158 The feed-forward clock parameter estimates can be retrieved from the kernel or
159 from the synchronisation daemon directly (preferred).
160 This method allows converting timestamps using different clock models as needed
161 by the application, while collecting meaningful upper bounds on current clock
166 .Xr clock_gettime 2 ,
169 Feed-forward clock support first appeared in
173 The feed-forward clock support was written by
174 .An Julien Ridoux Aq Mt jridoux@unimelb.edu.au
175 in collaboration with
176 .An Darryl Veitch Aq Mt dveitch@unimelb.edu.au
177 at the University of Melbourne under sponsorship from the FreeBSD Foundation.