ffclock_getestimate (2)
Leading comments
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. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binar...
NAME
ffclock_getcounter ffclock_getestimate ffclock_setestimate - Retrieve feed-forward counter, get and set feed-forward clock estimatesLIBRARY
Lb libcSYNOPSIS
In sys/timeffc.h Ft int Fn ffclock_getcounter ffcounter *ffcount Ft int Fn ffclock_getestimate struct ffclock_estimate *cest Ft int Fn ffclock_setestimate struct ffclock_estimate *cestDESCRIPTION
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 robustness than a feedback approach when synchronising over the network.In the feed-forward context, a timestamp is a cumulative value of the ticks of the timecounter, which can be converted into seconds by using the feed-forward clock estimates
The Fn ffclock_getcounter system call allows the calling process to retrieve the current value of the feed-forward counter maintained by the kernel.
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. The Fn ffclock_setestimate system call should be invoked by a single instance of a feed-forward synchronisation daemon. The Fn ffclock_getestimate system call can be called by any process to retrieve the feed-forward clock estimates.
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 .
The clock parameter estimates structure pointed to by Fa cest is defined in In sys/timeffc.h as:
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}). */
};
Only the super-user may set the feed-forward clock estimates.
RETURN VALUES
Rv -stdERRORS
The following error codes may be set in errno- Bq Er EFAULT
- The Fa ffcount or Fa cest pointer referenced invalid memory.
- Bq Er EPERM
- A user other than the super-user attempted to set the feed-forward clock parameter estimates.
USAGE
The feed-forward paradigm enables the definition of specialised clock functions.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.
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 kern.ffclock to make the system clock return the ffclock time. The clock_gettime2 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.
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). This method allows converting timestamps using different clock models as needed by the application, while collecting meaningful upper bounds on current clock error.