share/man/man4/ffclock.4

   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 December 1, 2011
  31 .Dt FFCLOCK 4
  32 .Os
  33 .Sh NAME
  34 .Nm FFCLOCK
  35 .Nd Feed-forward system clock
  36 .Sh SYNOPSIS
  37 .Cd options FFCLOCK
  38 .Sh DESCRIPTION
  39 The
  40 .Xr ntpd 8
  41 daemon has been the dominant solution for system clock synchronisation for many
  42 years, which has in turn influenced the design of the system clock.
  43 The ntpd daemon implements a feedback control algorithm which has been
  44 demonstrated to perform poorly in common use cases.
  45 .Pp
  46 Feed-forward clock synchronisation algorithms implemented by an appropriate
  47 daemon, in concert with the
  48 .Nm
  49 kernel support, have been shown to provide highly robust and accurate clock
  50 synchronisation.
  51 In addition to time keeping, the
  52 .Nm
  53 kernel mechanism provides new timestamping capabilities and the ability to
  54 use specialised clocks.
  55 Feed-forward synchronisation is also very well suited for virtualised
  56 environments, reducing the overhead of timekeeping in guests and ensuring
  57 continued smooth operation of the system clock during guest live migration.
  58 .Pp
  59 The
  60 .Nm
  61 kernel support provides feed-forward timestamping functions within the kernel
  62 and system calls to support feed-forward synchronisation daemons
  63 .Po see
  64 .Xr ffclock 2
  65 .Pc .
  66 .Ss Kernel Options
  67 The following kernel configuration options are related to
  68 .Nm :
  69 .Pp
  70 .Bl -tag -width ".Dv FFCLOCK" -compact
  71 .It Dv FFCLOCK
  72 Enable feed-forward clock support.
  73 .El
  74 .Ss Configuration
  75 When feed-forward clock support is compiled into the kernel, multiple system
  76 clocks become available to choose from.
  77 System clock configuration is possible via the
  78 .Va kern.sysclock
  79 .Xr sysctl 8
  80 tree which provides the following variables:
  81 .Bl -tag -width "    " -offset indent
  82 .It Va kern.sysclock.active
  83 Name of the current active system clock which is serving time.
  84 Set to one of the names in
  85 .Va kern.sysclock.available
  86 in order to change the default active system clock.
  87 .It Va kern.sysclock.available
  88 Lists the names of available system clocks
  89 .Po
  90 read only
  91 .Pc .
  92 .El
  93 .Pp
  94 Feed-forward system clock configuration is possible via the
  95 .Va kern.sysclock.ffclock
  96 sysctl tree which provides the following variables:
  97 .Bl -tag -width "    " -offset indent
  98 .It Va kern.sysclock.ffclock.version
  99 Feed-forward clock kernel version
 100 .Po
 101 read only
 102 .Pc .
 103 .It Va kern.sysclock.ffclock.ffcounter_bypass
 104 Use reliable hardware timecounter as the feed-forward counter.
 105 Will eventually be useful for virtualised environment like
 106 .Xr xen 4 ,
 107 but currently does nothing.
 108 .El
 109 .Sh SEE ALSO
 110 .Xr clock_gettime 2 ,
 111 .Xr ffclock 2 ,
 112 .Xr bpf 4 ,
 113 .Xr timecounters 4 ,
 114 .Xr sysctl 8
 115 .Sh HISTORY
 116 Feed-forward clock support first appeared in
 117 .Fx 10.0 .
 118 .Sh AUTHORS
 119 .An -nosplit
 120 The feed-forward clock support was written by
 121 .An Julien Ridoux Aq jridoux@unimelb.edu.au
 122 in collaboration with
 123 .An Darryl Veitch Aq dveitch@unimelb.edu.au
 124 at the University of Melbourne under sponsorship from the FreeBSD Foundation.
 125 .Pp
 126 This manual page was written by
 127 .An Julien Ridoux Aq jridoux@unimelb.edu.au
 128 and
 129 .An Lawrence Stewart Aq lstewart@FreeBSD.org .