1*2b15cb3dSCy Schubert<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2*2b15cb3dSCy Schubert<html> 3*2b15cb3dSCy Schubert<head> 4*2b15cb3dSCy Schubert<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> 5*2b15cb3dSCy Schubert<title>PPSAPI Interface for Precision Time Signals</title> 6*2b15cb3dSCy Schubert<link href="scripts/style.css" type="text/css" rel="stylesheet"> 7*2b15cb3dSCy Schubert</head> 8*2b15cb3dSCy Schubert<body> 9*2b15cb3dSCy Schubert<h3>PPSAPI Interface for Precision Time Signals</h3> 10*2b15cb3dSCy Schubert<img src="pic/tonea.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>NBS Special Publication 432, 1979</i></a> (out of print) 11*2b15cb3dSCy Schubert<p>Last update: 12*2b15cb3dSCy Schubert <!-- #BeginDate format:En2m -->10-Mar-2014 05:10<!-- #EndDate --> 13*2b15cb3dSCy Schubert UTC</p> 14*2b15cb3dSCy Schubert<br clear="left"> 15*2b15cb3dSCy Schubert<h4>Related Links</h4> 16*2b15cb3dSCy Schubert<p> 17*2b15cb3dSCy Schubert <script type="text/javascript" language="javascript" src="scripts/misc.txt"></script> 18*2b15cb3dSCy Schubert <br clear="left"> 19*2b15cb3dSCy Schubert</p> 20*2b15cb3dSCy Schubert<hr> 21*2b15cb3dSCy Schubert<h4>Introduction</h4> 22*2b15cb3dSCy Schubert<p>RFC-2783 describes the PPSAPI application programming interface for external precision time signals, such as the pulse-per-second (PPS) signal generated by some radio clocks and cesium oscillators. The PPSAPI provides a generic capability in the ubiquitous Unix kernel which can be used for a wide variety of measurement applications, including network time synchronization and related experiments. The hardware to do this requires only a serial port and a modem control lead, such as the data carrier detect (DCD) lead, which can be driven by an external source via a level converter/pulse generator such as described on the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. In some systems a parallel port can be used for the same purpose.</p> 23*2b15cb3dSCy Schubert<p>The PPSAPI interface defined in RFC-2783 is the only PPS interface supported in NTP Version 4. The PPSAPI is supported in stock FreeBSD and, with the addition of the <tt>PPSkit</tt> kernel module, in Linux.</p> 24*2b15cb3dSCy Schubert<p>The special header file <tt>/usr/include/sys/timepps.h</tt> implements the PPSAPI using whatever primitives are available in each archeticture and operating system. It obsoletes previous APIs based on the <tt>tty_clock</tt> and <tt>ppsclock</tt> line disciplines and streams modules, which are no longer supported.</p> 25*2b15cb3dSCy Schubert<p>The <a href="drivers/driver22.html">PPS Clock Discipline</a> driver (type 22) uses the PPSAPI in conjunction with a local radio clock or remote NTP server as a reference clock. The driver can also use the PPSAPI as an interface directly to the kernel PPS facility as described on the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page.</p> 26*2b15cb3dSCy Schubert<h4>PPSAPI Application Program Interface</h4> 27*2b15cb3dSCy Schubert<p>The PPSAPI interface provides the following functions:</p> 28*2b15cb3dSCy Schubert<dl> 29*2b15cb3dSCy Schubert <dt><tt>time_pps_create</tt></dt> 30*2b15cb3dSCy Schubert <dd>Creates a PPS interface instance and returns a handle to it.</dd> 31*2b15cb3dSCy Schubert <dt><tt>time_pps_destroy</tt></dt> 32*2b15cb3dSCy Schubert <dd>Destroys a PPS interface and returns the resources used.</dd> 33*2b15cb3dSCy Schubert <dt><tt>time_pps_setparams</tt></dt> 34*2b15cb3dSCy Schubert <dd>Sets the parameters associated with a PPS interface instance, including offsets to be automatically added to captured timestamps.</dd> 35*2b15cb3dSCy Schubert <dt><tt>time_pps_getparams</tt></dt> 36*2b15cb3dSCy Schubert <dd>Returns the parameters associated with a PPS interface instance. 37*2b15cb3dSCy Schubert </dd><dt><tt>time_pps_getcap</tt></dt> 38*2b15cb3dSCy Schubert <dd>Returns the capabilities of the current interface and kernel implementation.</dd> 39*2b15cb3dSCy Schubert <dt><tt>time_pps_fetch</tt></dt> 40*2b15cb3dSCy Schubert <dd>Returns the current timestamps associated with a PPS interface instance in either nanoseconds and nanoseconds (Unix <tt>timespec</tt>) or seconds and fraction (NTP) format.</dd> 41*2b15cb3dSCy Schubert <dt><tt>time_pps_kcbind</tt></dt> 42*2b15cb3dSCy Schubert <dd>If kernel PPS processing is supported, this binds the support to the associated PPS interface instance.</dd> 43*2b15cb3dSCy Schubert</dl> 44*2b15cb3dSCy Schubert<p>The entire PPS interface functionality is currently provided by inline code in the <tt>timepps.h</tt> header file. While not all implementations support the full PPSAPI specification, they do support all the functions required for the PPS driver described next. The FreeBSD, Linux and Solaris implementations can be used with the stock kernels provided with those systems; however, the Tru64 and SunOS kernels require additional functions not provided in the stock kernels. Solaris users are cautioned that these functions operate improperly in Solaris versions prior to 2.8 with patch Generic_108528-02. Header files for other systems can be found via the web at <a href="ftp://ftp.udel.edu/pub/ntp/software/nanokernel.tar.gz">nanokernel.tar.gz</a>.</p> 45*2b15cb3dSCy Schubert<hr> 46*2b15cb3dSCy Schubert<hr> 47*2b15cb3dSCy Schubert<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 48*2b15cb3dSCy Schubert</body> 49*2b15cb3dSCy Schubert</html> 50
