docs/kernpps.adoc

   1 = PPSAPI Interface for Precision Time Signals
   2 include::include-html.ad[]
   3
   4 [cols="10%,90%",frame="none",grid="none",style="verse"]
   5 |==============================
   6 |image:pic/tonea.gif[]|
   7 {millshome}pictures.html[from 'NBS Special Publication 432, 1979'] (out of print)
   8
   9 |==============================
  10
  11 == Related Links
  12
  13 include::includes/misc.adoc[]
  14
  15 '''''
  16
  17 == Introduction
  18
  19 RFC 2783 describes the PPSAPI application programming interface for
  20 external precision time signals, such as the pulse-per-second (PPS)
  21 signal generated by some radio clocks and cesium oscillators. The PPSAPI
  22 provides a generic capability in the ubiquitous Unix kernel which can be
  23 used for a wide variety of measurement applications, including network
  24 time synchronization and related experiments. The hardware to do this
  25 requires only a serial port and a modem control lead, such as the data
  26 carrier detect (DCD) lead, which can be driven by an external source via
  27 a level converter/pulse generator such as described on the
  28 link:pps.html[Pulse-per-second (PPS) Signal Interfacing] page. In some
  29 systems a parallel port can be used for the same purpose.
  30
  31 The PPSAPI interface defined in RFC 2783 is the only PPS interface
  32 supported in NTP Version 4. The PPSAPI is supported in stock FreeBSD
  33 and in Linux.
  34
  35 The special header file +/usr/include/sys/timepps.h+ implements the
  36 PPSAPI using whatever primitives are available in each architecture and
  37 operating system. It obsoletes previous APIs based on the +tty_clock+
  38 and +ppsclock+ line disciplines and streams modules, which are no longer
  39 supported.
  40
  41 The link:driver_pps.html[PPS Clock Discipline] driver
  42 uses the PPSAPI in conjunction with a local radio clock or remote
  43 NTP server as a reference clock. The driver can also use the PPSAPI as
  44 an interface directly to the kernel PPS facility as described on the
  45 link:kern.html[Kernel Model for Precision Timekeeping] page.
  46
  47 == PPSAPI Application Program Interface
  48
  49 The PPSAPI interface provides the following functions:
  50
  51 +time_pps_create+::
  52   Creates a PPS interface instance and returns a handle to it.
  53 +time_pps_destroy+::
  54   Destroys a PPS interface and returns the resources used.
  55 +time_pps_setparams+::
  56   Sets the parameters associated with a PPS interface instance,
  57   including offsets to be automatically added to captured timestamps.
  58 +time_pps_getparams+::
  59   Returns the parameters associated with a PPS interface instance.
  60 +time_pps_getcap+::
  61   Returns the capabilities of the current interface and kernel
  62   implementation.
  63 +time_pps_fetch+::
  64   Returns the current timestamps associated with a PPS interface
  65   instance in either seconds and nanoseconds (Unix +timespec+) or
  66   seconds and fraction (NTP) format.
  67 +time_pps_kcbind+::
  68   If kernel PPS processing is supported, this binds the support to the
  69   associated PPS interface instance.
  70
  71 The entire PPS interface functionality is currently provided by inline
  72 code in the +timepps.h+ header file. While not all implementations
  73 support the full PPSAPI specification, they do support all the functions
  74 required for the PPS driver described next. The FreeBSD, Linux and
  75 Solaris implementations can be used with the stock kernels provided with
  76 those systems; however, the Tru64 and SunOS kernels require additional
  77 functions not provided in the stock kernels. Solaris users are cautioned
  78 that these functions operate improperly in Solaris versions prior to 2.8
  79 with patch Generic_108528-02. Header files for other systems can be
  80 found via the web at
  81 https://www.eecis.udel.edu/~ntp/ntp_spool/software/nanokernel.tar.gz[nanokernel.tar.gz].
  82
  83 '''''
  84
  85 include::includes/footer.adoc[]