xref: /freebsd/share/man/man4/ffclock.4 (revision 8202ceccea3c602b789404e75657818634916654)
1257c3b0bSLawrence Stewart.\" Copyright (c) 2011 The University of Melbourne
2257c3b0bSLawrence Stewart.\" All rights reserved.
3257c3b0bSLawrence Stewart.\"
4257c3b0bSLawrence Stewart.\" This documentation was written by Julien Ridoux at the University of
5257c3b0bSLawrence Stewart.\" Melbourne under sponsorship from the FreeBSD Foundation.
6257c3b0bSLawrence Stewart.\"
7257c3b0bSLawrence Stewart.\" Redistribution and use in source and binary forms, with or without
8257c3b0bSLawrence Stewart.\" modification, are permitted provided that the following conditions
9257c3b0bSLawrence Stewart.\" are met:
10257c3b0bSLawrence Stewart.\" 1. Redistributions of source code must retain the above copyright
11257c3b0bSLawrence Stewart.\"    notice, this list of conditions and the following disclaimer.
12257c3b0bSLawrence Stewart.\" 2. Redistributions in binary form must reproduce the above copyright
13257c3b0bSLawrence Stewart.\"    notice, this list of conditions and the following disclaimer in the
14257c3b0bSLawrence Stewart.\"    documentation and/or other materials provided with the distribution.
15257c3b0bSLawrence Stewart.\"
16257c3b0bSLawrence Stewart.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17257c3b0bSLawrence Stewart.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18257c3b0bSLawrence Stewart.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19257c3b0bSLawrence Stewart.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20257c3b0bSLawrence Stewart.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21257c3b0bSLawrence Stewart.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22257c3b0bSLawrence Stewart.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23257c3b0bSLawrence Stewart.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24257c3b0bSLawrence Stewart.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25257c3b0bSLawrence Stewart.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26257c3b0bSLawrence Stewart.\" SUCH DAMAGE.
27257c3b0bSLawrence Stewart.\"
28257c3b0bSLawrence Stewart.\" $FreeBSD$
29257c3b0bSLawrence Stewart.\"
30257c3b0bSLawrence Stewart.Dd December 1, 2011
31257c3b0bSLawrence Stewart.Dt FFCLOCK 4
32257c3b0bSLawrence Stewart.Os
33257c3b0bSLawrence Stewart.Sh NAME
34257c3b0bSLawrence Stewart.Nm FFCLOCK
35257c3b0bSLawrence Stewart.Nd Feed-forward system clock
36257c3b0bSLawrence Stewart.Sh SYNOPSIS
37257c3b0bSLawrence Stewart.Cd options FFCLOCK
38257c3b0bSLawrence Stewart.Sh DESCRIPTION
39257c3b0bSLawrence StewartThe
40257c3b0bSLawrence Stewart.Xr ntpd 8
41257c3b0bSLawrence Stewartdaemon has been the dominant solution for system clock synchronisation for many
42257c3b0bSLawrence Stewartyears, which has in turn influenced the design of the system clock.
43257c3b0bSLawrence StewartThe ntpd daemon implements a feedback control algorithm which has been
44257c3b0bSLawrence Stewartdemonstrated to perform poorly in common use cases.
45257c3b0bSLawrence Stewart.Pp
46257c3b0bSLawrence StewartFeed-forward clock synchronisation algorithms implemented by an appropriate
47257c3b0bSLawrence Stewartdaemon, in concert with the
48257c3b0bSLawrence Stewart.Nm
49257c3b0bSLawrence Stewartkernel support, have been shown to provide highly robust and accurate clock
50257c3b0bSLawrence Stewartsynchronisation.
51257c3b0bSLawrence StewartIn addition to time keeping, the
52257c3b0bSLawrence Stewart.Nm
53257c3b0bSLawrence Stewartkernel mechanism provides new timestamping capabilities and the ability to
54257c3b0bSLawrence Stewartuse specialised clocks.
55257c3b0bSLawrence StewartFeed-forward synchronisation is also very well suited for virtualised
56257c3b0bSLawrence Stewartenvironments, reducing the overhead of timekeeping in guests and ensuring
57257c3b0bSLawrence Stewartcontinued smooth operation of the system clock during guest live migration.
58257c3b0bSLawrence Stewart.Pp
59257c3b0bSLawrence StewartThe
60257c3b0bSLawrence Stewart.Nm
61257c3b0bSLawrence Stewartkernel support provides feed-forward timestamping functions within the kernel
62257c3b0bSLawrence Stewartand system calls to support feed-forward synchronisation daemons
63257c3b0bSLawrence Stewart.Po see
64257c3b0bSLawrence Stewart.Xr ffclock 2
65257c3b0bSLawrence Stewart.Pc .
66257c3b0bSLawrence Stewart.Ss Kernel Options
67257c3b0bSLawrence StewartThe following kernel configuration options are related to
68257c3b0bSLawrence Stewart.Nm :
69257c3b0bSLawrence Stewart.Pp
70257c3b0bSLawrence Stewart.Bl -tag -width ".Dv FFCLOCK" -compact
71257c3b0bSLawrence Stewart.It Dv FFCLOCK
72257c3b0bSLawrence StewartEnable feed-forward clock support.
73257c3b0bSLawrence Stewart.El
74257c3b0bSLawrence Stewart.Ss Configuration
75257c3b0bSLawrence StewartWhen feed-forward clock support is compiled into the kernel, multiple system
76257c3b0bSLawrence Stewartclocks become available to choose from.
77257c3b0bSLawrence StewartSystem clock configuration is possible via the
78257c3b0bSLawrence Stewart.Va kern.sysclock
79257c3b0bSLawrence Stewart.Xr sysctl 8
80257c3b0bSLawrence Stewarttree which provides the following variables:
81257c3b0bSLawrence Stewart.Bl -tag -width "    " -offset indent
82257c3b0bSLawrence Stewart.It Va kern.sysclock.active
83257c3b0bSLawrence StewartName of the current active system clock which is serving time.
84257c3b0bSLawrence StewartSet to one of the names in
85257c3b0bSLawrence Stewart.Va kern.sysclock.available
86257c3b0bSLawrence Stewartin order to change the default active system clock.
87257c3b0bSLawrence Stewart.It Va kern.sysclock.available
88257c3b0bSLawrence StewartLists the names of available system clocks
89257c3b0bSLawrence Stewart.Po
90*8202ceccSWarner Loshread-only
91257c3b0bSLawrence Stewart.Pc .
92257c3b0bSLawrence Stewart.El
93257c3b0bSLawrence Stewart.Pp
94257c3b0bSLawrence StewartFeed-forward system clock configuration is possible via the
95257c3b0bSLawrence Stewart.Va kern.sysclock.ffclock
96257c3b0bSLawrence Stewartsysctl tree which provides the following variables:
97257c3b0bSLawrence Stewart.Bl -tag -width "    " -offset indent
98257c3b0bSLawrence Stewart.It Va kern.sysclock.ffclock.version
99257c3b0bSLawrence StewartFeed-forward clock kernel version
100257c3b0bSLawrence Stewart.Po
101*8202ceccSWarner Loshread-only
102257c3b0bSLawrence Stewart.Pc .
103257c3b0bSLawrence Stewart.It Va kern.sysclock.ffclock.ffcounter_bypass
104257c3b0bSLawrence StewartUse reliable hardware timecounter as the feed-forward counter.
105257c3b0bSLawrence StewartWill eventually be useful for virtualised environment like
106257c3b0bSLawrence Stewart.Xr xen 4 ,
107257c3b0bSLawrence Stewartbut currently does nothing.
108257c3b0bSLawrence Stewart.El
109257c3b0bSLawrence Stewart.Sh SEE ALSO
110257c3b0bSLawrence Stewart.Xr clock_gettime 2 ,
111257c3b0bSLawrence Stewart.Xr ffclock 2 ,
112257c3b0bSLawrence Stewart.Xr bpf 4 ,
113e3bf726bSAlexander Motin.Xr timecounters 4 ,
114257c3b0bSLawrence Stewart.Xr sysctl 8
115257c3b0bSLawrence Stewart.Sh HISTORY
116257c3b0bSLawrence StewartFeed-forward clock support first appeared in
117257c3b0bSLawrence Stewart.Fx 10.0 .
118257c3b0bSLawrence Stewart.Sh AUTHORS
119257c3b0bSLawrence Stewart.An -nosplit
120257c3b0bSLawrence StewartThe feed-forward clock support was written by
1216c899950SBaptiste Daroussin.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au
122257c3b0bSLawrence Stewartin collaboration with
1236c899950SBaptiste Daroussin.An Darryl Veitch Aq Mt dveitch@unimelb.edu.au
124257c3b0bSLawrence Stewartat the University of Melbourne under sponsorship from the FreeBSD Foundation.
125257c3b0bSLawrence Stewart.Pp
126257c3b0bSLawrence StewartThis manual page was written by
1276c899950SBaptiste Daroussin.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au
128257c3b0bSLawrence Stewartand
1296c899950SBaptiste Daroussin.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .
130