1 files changed, 161 insertions, 0 deletions
diff --git a/contrib/ntp/html/ldisc.htm b/contrib/ntp/html/ldisc.htm
new file mode 100644
index 000000000000..5dd732699882
--- /dev/null
+++ b/contrib/ntp/html/ldisc.htm
@@ -0,0 +1,161 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
+<html><head><title>
+Line Disciplines and Streams Modules
+</title></head><body><h3>
+Line Disciplines and Streams Modules
+</h3><hr>
+
+<p><h4>Description</h4>
+
+<p>Most radio and modem clocks used for a primary (stratum-1) NTP server
+utilize serial ports operating at speeds of 9600 baud or greater. The
+timing jitter contributed by the serial port hardware and software
+driver can accumulate to several milliseconds on a typical Unix
+workstation. In order to reduce these errors, a set of special line
+disciplines and stream modules can be configured in the Unix kernel.
+These routines intercept special characters or signals provided by the
+radio or modem clock and save a local timestamp for later processing.
+
+<p>The routines can be compiled in the kernel in older BSD-derived
+systems, or installed as System V streams modules and either compiled in
+the kernel or dynamically loaded when required. In either case, they
+require minor changes in some kernel files and in the NTP daemon
+<code>ntpd</code>. The streams modules can be pushed and popped from
+the streams stack using conventional System V streams program
+primitives. Note that not all Unix kernels support line disciplines and
+of those that do, not all support System V streams. The disciplines here
+are known to work correctly with SunOS 4.x kernels, but have not been
+tested for other kernels.
+
+<p>There are two line disciplines and a special streams module included
+in the distribution. Support for each in <code>ntpd</code> is enabled
+by adding flags to the <code>DEFS_LOCAL</code> line of the
+<code>ntpd</code> configuration file <code>./Config.local</code>. This
+can be done automatically by the autoconfiguration build procedures, or
+can be inserted/deleted after the process has completed.
+
+<dl>
+
+<dt><code>tty_clk</code>
+<dd>This routine intercepts characters received from the serial port and
+passes unchanged all except a set of designated characters to the
+generic serial port discipline. For each of the exception characters,
+the character is inserted in the receiver buffer followed by a local
+timestamp in Unix <code>timeval</code> format. Both
+<code>select()</code> and <code>SIGIO</code> are supported by the
+routine. The <code>-DTTYCLK</code> flag is used to compile support for
+this discipline in <code>ntpd</code>. This flag is automatically
+included if the <code>clkdefs.h</code> file is found in the
+<code>/usr/include/sys</code> directory, or it can be added (or deleted)
+manually. This module must be configured in the kernel during the kernel
+build process, as described in the <code>README</code> file in the
+<code>./kernel</code> directory.
+
+<p><dt><code>tty_chu</code>
+<dd>This routine is a special purpose line discipline for receiving a
+special timecode broadcast by Canadian time and frequency standard
+station CHU. The radio signal is first demodulated by the 300-baud modem
+included in the gadget box, then processed by the discipline and finally
+processed by the CHU modem driver (type 7) described in the <a href =
+"refclock.htm"> Reference Clock Drivers </a> page. This discipline
+should be used in raw mode. The <code>-DCHUCLK</code> flag is used to
+compile support for this discipline in <code>ntpd</code>. This flag is
+automatically included if the <code>chudefs.h</code> file is found in
+the <code>/usr/include/sys</code> directory, or it can be added (or
+deleted) manually. This module must be configured in the kernel during
+the kernel build process, as described in the <code>README</code> file
+in the <code>./kernel</code> directory.
+<p><dt><code>ppsclock</code>
+<dd>This routine is a special purpose streams module which monitors the
+state of the data carrier detect (DCD) modem interface signal. It is
+normally used in connection with a pulse-per-second (PPS) signal
+generated by some radio clocks, which requires a hardware level
+converter/pulse generator, such as described in the <a href =
+"gadget.htm"> Gadget Box PPS Level Converter and CHU Modem </a> page.
+For each positive-going edge of the DCD signal, the
+<code>ppsclock</code> module captures a timestamp in Unix
+<code>timeval</code> format for later retrieval using a special
+<code>ioctl()</code> system call. The <code>-DPPS</code> flag is used to
+compile support for this module in <code>ntpd</code>. This flag is
+automatically included if the <code>ppsclock.h</code> file is found in
+the <code>/sys/sys</code> directory, or it can be added (or deleted)
+manually. This module must also be configured in the kernel during the
+kernel build process, as described in the <code>README</code> file in
+the <code>./kernel</code> directory.
+
+</dl>
+
+<p>There are two versions of both the <code>tty_clk</code> and
+<code>chu_clk</code> programs. The <code>tty_clk.c</code> and
+<code>chu_clk.c</code> are designed for use with older BSD systems and
+are compiled in the kernel. The <code>tty_clk_STREAMS.c</code> and
+<code>chu_clk_STREAMS.c</code> are designed for use with System V
+streams, in which case they can be either compiled in the kernel or
+dynamically loaded. Since these programs are small, unobtrusive, and do
+nothing unless specifically enabled by an application program, it
+probably doesn't matter which version is chosen. Instructions on how to
+configure and build a kernel supporting either or both of these line
+disciplines is in the <code>README</code> file in the
+<code>./kernel</code> directory.
+
+<p><h4>How to Use the <code>tty_clk</code> Line Discipline</h4>
+
+<p>The tty_clk line discipline defines a new <code>ioctl()</code>,
+<code>CLK_SETSTR</code>, which takes a pointer to a string of no more
+than 32 characters. Until the first <code>CLK_SETSTR</code> is
+performed, the discipline will simply pass through characters. Once it
+is passed a string by <code>CLK_SETSTR</code>, any character in that
+string will be immediately followed by a timestamp in Unix
+<code>timeval</code> format. You can change the string whenever you want
+by doing another <code>CLK_SETSTR</code>. The character must be an
+exact, 8 bit match. The character '\000' cannot, be used, as it is the
+string terminator. Passing an empty string to <code>CLK_SETSTR</code>
+turns off timestamping. Passing <code>NULL</code> will produce undefined
+results.
+
+<p><h4>How to Use the <code>tty_chu</code> Line Discipline</h4>
+
+<p>The tty_chu line discipline translates data received from the CHU
+modem and returns <code>chucode</code> structures, as defined in
+chudefs.h, and expected by the Scratchbuilt CHU Receiver reference clock
+driver. Depending on the settings of <code>PEDANTIC</code> and
+<code>ANAL_RETENTIVE</code> used when compiling the kernel, some
+checking of the data may or may not be necessary.
+
+<p><h4>How to Use the <code>ppsclock</code> Stream Module</h4>
+
+<p>The ppsclock streams module implements an <code>ioctl()
+CIOGETEV</code>, which takes a pointer to the structure
+
+<pre>
+struct ppsclockev {
+     struct timeval tv;
+     u_int serial;
+};
+</pre>
+
+<p>The ppsclock module is pushed on the streams stack of the serial port
+connected to the PPS signal. The port must be configured for local
+operation, rather than remote (modem) operation. At each positive-going
+edge of the DCD signal, the routine latches the current local timestamp
+and increments a counter. At each <code>CIOGETEV ioctl()</code> call,
+the current values of the timestamp and counter are returned in the
+<code>ppsclockev</code> structure.
+
+<p><h4>TIOCDCDTIMESTAMP timestamping</h4>
+
+<p>On FreeBSD 2.2 and later systems the TIOCDCDTIMESTAMP ioctl is used
+to read the timestamp when the DCD serial go active. To use this the
+PPS signal must be tied to the serial port DCD signal through the
+appropriate level converters and pulse stretch circuitry if necessary.
+This enhances the accuracy of the driver to a few microseconds. Using
+FreeBSD 2.2 the measured delay between activation of the PPS signal and
+the time the timestamp is made on a 66MHz 486DX2 is 19us and on a
+100MHz Pentium is 6us. The driver does NOT compensate for this.
+
+<p>The TIOCDCDTIMESTAMP timestamping ioctl() is used automatically
+on FreeBSD systems if available. It is integrated into the
+refclock_gtlin() function so any driver using it will benefit from
+the enhanced accuracy.
+
+<hr><address>David L. Mills (mills@udel.edu)</address></body></html>