diff options
Diffstat (limited to 'contrib/ntp/html/ldisc.htm')
-rw-r--r-- | contrib/ntp/html/ldisc.htm | 161 |
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 0000000..5dd7326 --- /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> |