162 lines
8.1 KiB
HTML
162 lines
8.1 KiB
HTML
<!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>
|