<!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>xntpd</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>xntpd</code> is enabled
by adding flags to the <code>DEFS_LOCAL</code> line of the
<code>xntpd</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>xntpd</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.html"> 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>xntpd</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.html"> 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>xntpd</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>
