Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
FFCLOCK(2)		       System Calls Manual		      FFCLOCK(2)

NAME
     ffclock_getcounter,  ffclock_getestimate,	ffclock_setestimate  -- Retrieve
     feed-forward counter, get and set feed-forward clock estimates

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/timeffc.h>

     int
     ffclock_getcounter(ffcounter *ffcount);

     int
     ffclock_getestimate(struct ffclock_estimate *cest);

     int
     ffclock_setestimate(struct ffclock_estimate *cest);

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 sys-
     tem 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 ffclock_getcounter() system call allows the calling process to retrieve
     the current value of the feed-forward counter maintained by the kernel.

     The  ffclock_getestimate() and ffclock_setestimate() system calls allow the
     caller to get and set the kernel's feed-forward clock  parameter  estimates
     respectively.  The ffclock_setestimate() system call should be invoked by a
     single   instance	of  a  feed-forward  synchronisation  daemon.	The  ff-
     clock_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 re-
     trieved every time a timestamp is to be converted into seconds.  The number
     of system calls can therefore be greatly reduced if the calling process re-
     trieves the clock estimates from the clock synchronisation daemon	instead.
     The  ffclock_getestimate()  must be used when the feed-forward synchronisa-
     tion daemon is not running (see "USAGE" below).

     The clock parameter estimates structure pointed to by cest  is  defined  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
     Upon successful completion, the value 0 is returned; otherwise the value -1
     is returned and the global variable errno is set to indicate the error.

ERRORS
     The following error codes may be set in errno:

     [EFAULT]		The ffcount or cest pointer referenced invalid memory.

     [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 func-
     tions.

     In its simplest form, 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	(or  "wall-clock  time")
     tracked  by the ffclock. The simplest method uses the ffclock sysctl inter-
     face kern.ffclock to make the system clock return the  ffclock  time.   The
     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.

     A	less  automated  method  consists of retrieving the feed-forward counter
     timestamp from the kernel and using the feed-forward clock parameter  esti-
     mates  to convert the timestamp into seconds.  The feed-forward clock para-
     meter estimates can be retrieved from the kernel or from  the  synchronisa-
     tion 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.

SEE ALSO
     date(1), adjtime(2), clock_gettime(2), ctime(3)

HISTORY
     Feed-forward clock support first appeared in FreeBSD 10.0.

AUTHORS
     The   feed-forward  clock	support  was  written  by  Julien  Ridoux  <jri-
     doux@unimelb.edu.au>    in     collaboration     with     Darryl	  Veitch
     <dveitch@unimelb.edu.au>  at  the University of Melbourne under sponsorship
     from the FreeBSD Foundation.

FreeBSD ports 15.quarterly	November 21, 2011		      FFCLOCK(2)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ffclock_getcounter&sektion=2&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help