Page MenuHomeFreeBSD
Files F144186933

D42944.diff
No OneTemporary
Actions

D42944.diff
View Options

diff --git a/lib/libc/sys/ffclock.2 b/lib/libc/sys/ffclock.2
--- a/lib/libc/sys/ffclock.2
+++ b/lib/libc/sys/ffclock.2
@@ -1,8 +1,8 @@
.\" Copyright (c) 2011 The University of Melbourne
.\" All rights reserved.
.\"
-.\" This documentation was written by Julien Ridoux at the University of
-.\" Melbourne under sponsorship from the FreeBSD Foundation.
+.\" This documentation was written by Julien Ridoux and Darryl Veitch at the
+.\" University of Melbourne under sponsorship from the FreeBSD Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@@ -25,14 +25,15 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd November 21, 2011
+.Dd Nov 30, 2023
.Dt FFCLOCK 2
.Os
.Sh NAME
.Nm ffclock_getcounter ,
.Nm ffclock_getestimate ,
.Nm ffclock_setestimate
-.Nd Retrieve feed-forward counter, get and set feed-forward clock estimates
+.Nd Retrieve feedforward counter, get and set the parameters defining the
+native feedforward clock.
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@@ -44,74 +45,70 @@
.Ft int
.Fn ffclock_setestimate "struct ffclock_estimate *cest"
.Sh DESCRIPTION
-The ffclock is an alternative method to synchronise the system clock.
-The ffclock implements a feed-forward paradigm and decouples the timestamping
-and timekeeping kernel functions.
-This ensures that past clock errors do not affect current timekeeping, an
-approach radically different from the feedback alternative implemented by the
-ntpd daemon when adjusting the system clock.
-The feed-forward approach has demonstrated better performance and higher
+The FFclock is an alternative method to synchronize the system clock.
+It implements a feedforward paradigm that decouples low level timestamping
+from the kernel timekeeping functions. This ensures that past clock errors do
+not affect current timekeeping, an approach radically different from the
+feedback alternative implemented by the ntpd daemon when adjusting the system
+clock. The feedforward approach has demonstrated better performance and higher
robustness than a feedback approach when synchronising over the network.
.Pp
-In the feed-forward context, a
-.Em timestamp
-is a cumulative value of the ticks of the timecounter, which can be converted
-into seconds by using the feed-forward
-.Em clock estimates .
+In the feedforward context, a
+.Em raw timestamp
+is a cumulative count of the increments of a timecounter of suitable width
+.Po
+at least 64 bits
+.Pc ,
+that can be converted into UTC when needed by using the feedforward
+.Em clock data
+held in the kernel, that is periodically updated by a suitable FFclock daemon.
.Pp
The
.Fn ffclock_getcounter
-system call allows the calling process to retrieve the current value of the
-feed-forward counter maintained by the kernel.
+system call allows the calling process to retrieve the current value of a
+feedforward counter maintained by the kernel.
.Pp
The
.Fn ffclock_getestimate
and
.Fn ffclock_setestimate
-system calls allow the caller to get and set the kernel's feed-forward clock
-parameter estimates respectively.
+system calls allow the caller to respectively get and set the kernel's
+native feedforward clock parameters.
The
.Fn ffclock_setestimate
-system call should be invoked by a single instance of a feed-forward
-synchronisation daemon.
+system call should be invoked by a single instance of a feedforward
+synchronization daemon.
The
.Fn ffclock_getestimate
-system call can be called by any process to retrieve the feed-forward clock
-estimates.
+system call can be called by any process to retrieve the current value of the
+parameters.
.Pp
-The feed-forward approach does not require that the clock estimates be retrieved
-every time a timestamp is to be converted into seconds.
-The number of system calls can therefore be greatly reduced if the calling
-process retrieves the clock estimates from the clock synchronisation daemon
-instead.
-The
-.Fn ffclock_getestimate
-must be used when the feed-forward synchronisation daemon is not running
-.Po see
-.Sx USAGE
-below
-.Pc .
+It is not necessary to use the get/set system calls to use the clock, as
+detailed below.
+Furthermore if bypass mode is active, system calls can also be avoided for the
+reading of the ffcounter itself.
.Pp
-The clock parameter estimates structure pointed to by
+The native clock parameter data structure pointed to by
.Fa cest
is defined in
.In sys/timeffc.h
as:
.Bd -literal
struct ffclock_estimate {
- struct bintime update_time; /* Time of last estimates update. */
- ffcounter update_ffcount; /* Counter value at last update. */
- ffcounter leapsec_next; /* Counter value of next leap second. */
- uint64_t period; /* Estimate of counter period. */
- uint32_t errb_abs; /* Bound on absolute clock error [ns]. */
- uint32_t errb_rate; /* Bound on counter rate error [ps/s]. */
- uint32_t status; /* Clock status. */
- int16_t leapsec_total; /* All leap seconds seen so far. */
- int8_t leapsec; /* Next leap second (in {-1,0,1}). */
+ struct bintime update_time; /* FFclock time of last update */
+ ffcounter update_ffcount; /* Counter value at last update */
+ ffcounter leapsec_expected; /* Estimated counter value of next leap. */
+ uint64_t period; /* Counter period estimate [2^-64 s]. */
+ uint32_t errb_abs; /* Bound on absolute clock error [ns]. */
+ uint32_t errb_rate; /* Bound on rel. counter period err [ps/s]. */
+ uint32_t status; /* Clock status. */
+ uint16_t secs_to_nextupdate;/* Estimated wait til next update [s]. */
+ int8_t leapsec_total; /* Sum of leapsecs seen since clock start. */
+ int8_t leapsec_next; /* Next leap second (in {-1,0,1}) */
};
.Ed
.Pp
-Only the super-user may set the feed-forward clock estimates.
+Only the super-user may set the feedforward clock data.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
@@ -125,51 +122,82 @@
.Fa cest
pointer referenced invalid memory.
.It Bq Er EPERM
-A user other than the super-user attempted to set the feed-forward clock
-parameter estimates.
+A user other than the super-user attempted to set the FFclock data.
.El
.Sh USAGE
-The feed-forward paradigm enables the definition of specialised clock functions.
+There are several ways to use the features and clocks made available by the
+FFclock family.
.Pp
-In its simplest form,
-.Fn ffclock_getcounter
-can be used to establish strict order between events or to measure small time
-intervals very accurately with a minimum performance cost.
-.Pp
-Different methods exist to access absolute time
-.Po or
-.Qq wall-clock time
-.Pc tracked by the ffclock.
-The simplest method uses the ffclock sysctl interface
+The simplest uses the ffclock sysctl interface
.Va kern.ffclock
-to make the system clock return the ffclock time.
-The
-.Xr clock_gettime 2
-system call can then be used to retrieve the current time seen by the
-feed-forward clock.
-Note that this setting affects the entire system and that a feed-forward
-synchronisation daemon should be running.
+to set the system clock to use the FFclock family rather than the traditional
+FBclock family. Then normal absolute time
+functions (both in the kernel and in userland) will be derived from the FFclock.
+Specifically, timetamps based on the monoFFC clock will be returned.
+This setting affects the entire system and so a feedforward synchronization
+daemon should be running.
.Pp
-A less automated method consists of retrieving the feed-forward counter
-timestamp from the kernel and using the feed-forward clock parameter estimates
-to convert the timestamp into seconds.
-The feed-forward clock parameter estimates can be retrieved from the kernel or
-from the synchronisation daemon directly (preferred).
+Another use is in packet timestamping. If a FFclock daemon is running, then
+regardless of which clock family is serving system time, the sysclock and
+FFclock bpf support allows any kind of timestamp, from any clock of either clock
+family, to be obtained by passing an appropriate timestamp descriptor
+.Po see
+.Xr bpf 4
+.Pc .
+In this way userland programs can receive timestamps based on any of the three
+kernel FFclocks: natFFC, monoFFC, and diffFFC
+.Po see
+.Xr ffclock 2
+.Pc .
+It is also possible for different applications monitoring the same packets to
+request different timestamps
+.Po
+in addition to raw timestamps
+.Pc ,
+for example one using natFCC in bintime format,
+and another using FBclock in microtime format, based on a single shared
+underlying raw timestamp marking the packet event. This scales to any number of
+taps as the raw timestamp and clock states are captured once only and reused,
+and so the delivered timestamps are unaffected by subsequent latency or tap
+access order.
+.Pp
+A third approach is less automated but more flexible. It consists of obtaining
+raw timestamps and using the contemporaneous FFclock parameters to calculate
+the UTC timestamp of the FFclock (specifically the natFFC clock), and/or to
+calculate the time interval in seconds between two events using the FFclock
+difference clock. These are simple affine functions easily calculated
+in floating point arithmetic in userland.
+The raw timestamps could be given
+externally, or obtained from the kernel via either bpf or
+.Nm ffclock_getcounter ,
+or directly in bypass mode.
+The clock parameters could be obtained via
+.Fn ffclock_getestimate ,
+or
+.Po
+preferred
+.Pc
+by interfacing with the daemon, given a suitable library.
This method allows converting timestamps using different clock models as needed
by the application, while collecting meaningful upper bounds on current clock
-error.
+error, and could be done in post processing if needed clock parameters and
+raw timestamps are stored.
.Sh SEE ALSO
.Xr date 1 ,
.Xr adjtime 2 ,
.Xr clock_gettime 2 ,
-.Xr ctime 3
+.Xr ctime 3 ,
+.Xr bpf 4 ,
+.Xr ffclock 4
.Sh HISTORY
-Feed-forward clock support first appeared in
+Feedforward clock support first appeared in
.Fx 10.0 .
.Sh AUTHORS
.An -nosplit
-The feed-forward clock support was written by
-.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au
+The feedforward clock support was written by
+.An Julien Ridoux
in collaboration with
-.An Darryl Veitch Aq Mt dveitch@unimelb.edu.au
+.An Darryl Veitch
at the University of Melbourne under sponsorship from the FreeBSD Foundation.
+It was later revised and extended by Darryl Veitch at the University of
+Technology Sydney (darryl.veitch@uts.edu.au).
diff --git a/share/man/man4/ffclock.4 b/share/man/man4/ffclock.4
--- a/share/man/man4/ffclock.4
+++ b/share/man/man4/ffclock.4
@@ -1,8 +1,8 @@
.\" Copyright (c) 2011 The University of Melbourne
.\" All rights reserved.
.\"
-.\" This documentation was written by Julien Ridoux at the University of
-.\" Melbourne under sponsorship from the FreeBSD Foundation.
+.\" This documentation was written by Julien Ridoux and Darryl Veitch at the
+.\" University of Melbourne under sponsorship from the FreeBSD Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@@ -25,41 +25,48 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd December 1, 2011
+.Dd Nov 30, 2023
.Dt FFCLOCK 4
.Os
.Sh NAME
.Nm FFCLOCK
-.Nd Feed-forward system clock
+.Nd Feedforward system clock
.Sh SYNOPSIS
.Cd options FFCLOCK
.Sh DESCRIPTION
The
.Xr ntpd 8
-daemon has been the dominant solution for system clock synchronisation for many
+daemon has been the dominant solution for system clock synchronization for many
years, which has in turn influenced the design of the system clock.
The ntpd daemon implements a feedback control algorithm which has been
demonstrated to perform poorly in common use cases.
.Pp
-Feed-forward clock synchronisation algorithms implemented by an appropriate
+Feedforward clock synchronization algorithms implemented by an appropriate
daemon, in concert with the
.Nm
kernel support, have been shown to provide highly robust and accurate clock
-synchronisation.
+synchronization.
In addition to time keeping, the
.Nm
kernel mechanism provides new timestamping capabilities and the ability to
-use specialised clocks.
-Feed-forward synchronisation is also very well suited for virtualised
+use specialized clocks. This includes one designed for the
+measurement of time differences which is extremely robust and accurate, for
+example offering nanosecond accuracy and below for packet round-trip times.
+Feedforward synchronization is also naturally suited for virtualised
environments, reducing the overhead of timekeeping in guests and ensuring
continued smooth operation of the system clock during guest live migration.
.Pp
The
.Nm
-kernel support provides feed-forward timestamping functions within the kernel
-and system calls to support feed-forward synchronisation daemons
+kernel support provides a feedforward compatible counter, feedforward
+timestamping functions within the kernel, system calls to support feedforward
+synchronization daemons
.Po see
.Xr ffclock 2
+.Pc ,
+and advanced packet timestamping support
+.Po see
+.Xr bpf 4
.Pc .
.Ss Kernel Options
The following kernel configuration options are related to
@@ -67,42 +74,61 @@
.Pp
.Bl -tag -width ".Dv FFCLOCK" -compact
.It Dv FFCLOCK
-Enable feed-forward clock support.
+Enable feedforward clock support.
.El
.Ss Configuration
-When feed-forward clock support is compiled into the kernel, multiple system
-clocks become available to choose from.
-System clock configuration is possible via the
+When feedforward clock support is compiled into the kernel, two system
+clock families become available to choose from: the traditional FBclock (the
+default) and FFclock. System clock configuration is possible via the
.Va kern.sysclock
.Xr sysctl 8
tree which provides the following variables:
.Bl -tag -width " " -offset indent
.It Va kern.sysclock.active
-Name of the current active system clock which is serving time.
-Set to one of the names in
+The system clock family that is currently serving time.
+Can be dynamically set to one of the available families, as given by
.Va kern.sysclock.available
-in order to change the default active system clock.
.It Va kern.sysclock.available
-Lists the names of available system clocks
+Lists the available system clock families
.Po
read-only
.Pc .
.El
.Pp
-Feed-forward system clock configuration is possible via the
+Within each clock family, variants of the underlying clock may be available. In
+the case of FFclock there are three: the underlying clock
+.Va natFFC
+that is directly synchronized by the FFclock daemon, a monotonized version
+.Va monoFFC
+of it
+.Po
+the system clock default, used in system timestamping functions
+.Pc , and the 'difference clock'
+.Va diffFFC ,
+available for accurate measurement of time
+difference over small time intervals
+.Po
+for example 1hr, beyond which it is better to use
+natFFC
+.Pc .
+.Pp
+Feedforward system clock configuration is possible via the
.Va kern.sysclock.ffclock
sysctl tree which provides the following variables:
.Bl -tag -width " " -offset indent
.It Va kern.sysclock.ffclock.version
-Feed-forward clock kernel version
+Feedforward clock kernel version
.Po
read-only
.Pc .
.It Va kern.sysclock.ffclock.ffcounter_bypass
-Use reliable hardware timecounter as the feed-forward counter.
-Will eventually be useful for virtualised environment like
-.Xr xen 4 ,
-but currently does nothing.
+Use direct reads of the chosen hardware timecounter when timestamping for
+latency reduction, rather than using the timecounter mechanism's
+re-synthesized version of the counter. This only applies when the native
+hardware counter is suitable for feedforward use, and direct access is
+available. It is currently supported only in the case of an invariant TSC.
+The origins of the native and timecounter-based versions of the counter are
+guaranteed to align.
.El
.Sh SEE ALSO
.Xr clock_gettime 2 ,
@@ -111,17 +137,21 @@
.Xr timecounters 4 ,
.Xr sysctl 8
.Sh HISTORY
-Feed-forward clock support first appeared in
+Feedforward clock support first appeared in
.Fx 10.0 .
.Sh AUTHORS
.An -nosplit
-The feed-forward clock support was written by
-.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au
+The feedforward clock support was written by
+.An Julien Ridoux
in collaboration with
-.An Darryl Veitch Aq Mt dveitch@unimelb.edu.au
+.An Darryl Veitch
at the University of Melbourne under sponsorship from the FreeBSD Foundation.
+It was later revised and extended by Darryl Veitch at the University of
+Technology Sydney.
.Pp
This manual page was written by
-.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au
+.An Julien Ridoux
and
-.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .
+.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org ,
+and updated by
+.An Darryl Veitch Aq Mt darryl.veitch@uts.edu.au .
diff --git a/sys/kern/kern_ffclock.c b/sys/kern/kern_ffclock.c
--- a/sys/kern/kern_ffclock.c
+++ b/sys/kern/kern_ffclock.c
@@ -4,8 +4,9 @@
* Copyright (c) 2011 The University of Melbourne
* All rights reserved.
*
- * This software was developed by Julien Ridoux at the University of Melbourne
- * under sponsorship from the FreeBSD Foundation.
+ * This software was developed by Julien Ridoux and Darryl Veitch at the
+ * University of Melbourne under sponsorship from the FreeBSD Foundation,
+ * and revised by Darryl Veitch at the University of Technology Sydney.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
diff --git a/sys/kern/kern_tc.c b/sys/kern/kern_tc.c
--- a/sys/kern/kern_tc.c
+++ b/sys/kern/kern_tc.c
@@ -10,8 +10,9 @@
*
* Copyright (c) 2011, 2015, 2016 The FreeBSD Foundation
*
- * Portions of this software were developed by Julien Ridoux at the University
- * of Melbourne under sponsorship from the FreeBSD Foundation.
+ * Portions of this software were developed by Julien Ridoux and Darryl Veitch
+ * at the University of Melbourne under sponsorship from the FreeBSD Foundation,
+ * and revised by Darryl Veitch at the University of Technology Sydney.
*
* Portions of this software were developed by Konstantin Belousov
* under sponsorship from the FreeBSD Foundation.
diff --git a/sys/kern/subr_rtc.c b/sys/kern/subr_rtc.c
--- a/sys/kern/subr_rtc.c
+++ b/sys/kern/subr_rtc.c
@@ -11,9 +11,6 @@
* the Systems Programming Group of the University of Utah Computer
* Science Department.
*
- * Portions of this software were developed by Julien Ridoux at the University
- * of Melbourne under sponsorship from the FreeBSD Foundation.
- *
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
diff --git a/sys/net/bpf.h b/sys/net/bpf.h
--- a/sys/net/bpf.h
+++ b/sys/net/bpf.h
@@ -9,6 +9,11 @@
* to Berkeley by Steven McCanne and Van Jacobson both of Lawrence
* Berkeley Laboratory.
*
+ * Portions of this software were developed by Darryl Veitch at the University
+ * of Technology Sydney, based on earlier work by Julien Ridoux and Darryl
+ * Veitch at the University of Melbourne under sponsorship from the FreeBSD
+ * Foundation.
+ *
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
diff --git a/sys/net/bpf.c b/sys/net/bpf.c
--- a/sys/net/bpf.c
+++ b/sys/net/bpf.c
@@ -10,6 +10,11 @@
* to Berkeley by Steven McCanne and Van Jacobson both of Lawrence
* Berkeley Laboratory.
*
+ * Portions of this software were developed by Darryl Veitch at the University
+ * of Technology Sydney, based on earlier work by Julien Ridoux and Darryl
+ * Veitch at the University of Melbourne under sponsorship from the FreeBSD
+ * Foundation.
+ *
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
diff --git a/sys/sys/_ffcounter.h b/sys/sys/_ffcounter.h
--- a/sys/sys/_ffcounter.h
+++ b/sys/sys/_ffcounter.h
@@ -4,8 +4,8 @@
* Copyright (c) 2011 The University of Melbourne
* All rights reserved.
*
- * This software was developed by Julien Ridoux at the University of Melbourne
- * under sponsorship from the FreeBSD Foundation.
+ * This software was developed by Julien Ridoux and Darryl Veitch at the
+ * University of Melbourne under sponsorship from the FreeBSD Foundation.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
diff --git a/sys/sys/timeffc.h b/sys/sys/timeffc.h
--- a/sys/sys/timeffc.h
+++ b/sys/sys/timeffc.h
@@ -4,8 +4,9 @@
* Copyright (c) 2011 The University of Melbourne
* All rights reserved.
*
- * This software was developed by Julien Ridoux at the University of Melbourne
- * under sponsorship from the FreeBSD Foundation.
+ * This software was developed by Julien Ridoux and Darryl Veitch at the
+ * University of Melbourne under sponsorship from the FreeBSD Foundation,
+ * and revised by Darryl Veitch at the University of Technology Sydney.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
diff --git a/sys/sys/timepps.h b/sys/sys/timepps.h
--- a/sys/sys/timepps.h
+++ b/sys/sys/timepps.h
@@ -10,8 +10,8 @@
*
* Copyright (c) 2011 The FreeBSD Foundation
*
- * Portions of this software were developed by Julien Ridoux at the University
- * of Melbourne under sponsorship from the FreeBSD Foundation.
+ * Portions of this software were developed by Julien Ridoux and Darryl Veitch
+ * at the University of Melbourne under sponsorship from the FreeBSD Foundation.
*
* The is a FreeBSD version of the RFC 2783 API for Pulse Per Second
* timing interfaces.

File Metadata

Mime Type
text/plain
Expires
Sat, Feb 7, 3:59 AM (11 h, 11 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
28452504
Default Alt Text
D42944.diff (21 KB)

Event Timeline