diff options
Diffstat (limited to 'contrib/ntp/html/ldisc.htm')
| -rw-r--r-- | contrib/ntp/html/ldisc.htm | 206 |
1 files changed, 67 insertions, 139 deletions
diff --git a/contrib/ntp/html/ldisc.htm b/contrib/ntp/html/ldisc.htm index 5dd732699882..e6a026aa93fe 100644 --- a/contrib/ntp/html/ldisc.htm +++ b/contrib/ntp/html/ldisc.htm @@ -1,4 +1,3 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN"> <html><head><title> Line Disciplines and Streams Modules </title></head><body><h3> @@ -7,125 +6,66 @@ Line Disciplines and Streams Modules <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. +<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 intrinsic delay and jitter contributed by the serial port hardware and software driver can accumulate up to a millisecond in newer Unix systems and tens of milliseconds in older ones. In order to reduce the effects of delay and jitter, a set of special line disciplines, stream modules and operating system calls (ioctls) can be configured in some Unix kernels. These routines intercept special characters or signals provided by the radio or modem clock and save a timestamp for later processing. + +<p>The routines provide two important functions. Some insert a timestamp in the receive data stream upon occurance of a designated character or characters at the serial interface. This can be used to timestamp an on-time character produced by a radio clock, for example. Other routines support an application program interface for pulse-per-second (PPS) signals generated by some radio clocks and laboratory instruments. These routines are normally accessed through the PPSAPI application program interface described below. + +<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 <tt>ntpd</tt>. The streams modules can be pushed and popped from the streams stack using conventional System V streams program primitives. Note that some Unix kernels do not support line disciplines and some do not support System V streams. The routines described here are known to work correctly with the Unix kernels called out in the descriptions, but have not been tested for other kernels. + +<h4>PPSAPI Application Program Interface</h4> + +<p>Pulse-per-second (PPS) signals are normally processed as described in the <a href=pps.htm>Pulse-per-second (PPS) Signal Interfacing</a> page. The <a href=driver22.htm>PPS Clock Discipline</a> driver uses the PPSAPI application program interface to capture PPS signal transitions used to fine-tune the system clock. This interface, defined in RFC-2783, is the only PPS interface supported in NTP. While older PPS interfaces based on the ioctls described below continue to be supported, they are used only in the special header file <t>/usr/include/sys/timepps.h</tt>, which implements the PPSAPI specific to each archeticture and operating system. + +<p>It is the intent of the evolving design to remove all PPS support from the various clock drivers and utilize only the PPS driver for PPS support. This allows the required sanity checks and signal grooming to be provided and maintained in one place and avoids cluttering up the drivers with duplicate functionality. Since the PPS signal samples are processed by the entire suite of NTP grooming, selection and clustering algorithms, noisy PPS signals and signals outside specific time and frequency tolerances are excluded. + +<p>The PPSAPI interface provides the following functions: <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. +<dt><tt>time_pps_create</tt> +<dd>Creates a PPS interface instance and returns a handle to it.</dd> + +<dt><tt>time_pps_destroy</tt> +<dd>Destroys a PPS interface and returns the resources used.</dd> + +<dt><tt>time_pps_setparams</tt> +<dd>Sets the parameters associated with a PPS interface instance, including offsets to be automatically added to captured timestamps.</dd> + +<dt><tt>time_pps_getparams</tt> +<dd>Returns the parameters associated with a PPS interface instance.</dd> + +<dt><tt>time_pps_getcap</tt> +<dd>Returns the capabilities of the current interface and kernel implementation.</dd> + +<dt><tt>time_pps_fetch</tt> +<dd>Returns the current timestamps associated with a PPS interface instance in either nanoseconds and nanoseconds (Unix <tt>timespec</tt>) or seconds and fraction (NTP) format.</dd> + +<dt><tt>time_pps_kcbind</tt> +<dd>If kernel PPS processing is supported, this binds the support to the associated PPS interface instance.</dd> </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 +<p>The entire PPS interface functionality is currently provided by inline code in the <tt>timepps.h</tt> header files implemented for SunOS, Solaris, FreeBSD, Linux and Tru64. While not all implementations support the full PPSAPI specification, they do support all the functions required for the PPS driver. The FreeBSD, Linux and Solaris implementations can be used with the stock kernels provided with those systems; however, the Tru64 and SunOS kernels require additional functions not provided in the stock kernels. Solaris users are cautioned that these ioctls function improperly in Solaris versions prior to 2.8 with patch Generic_108528-02. + +<h4><tt>tty_clk</tt> Line Discipline/Streams Module</h4> + +<p>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 <tt>timeval</tt> format. Both <tt>select()</tt> and <tt>SIGIO</tt> are supported by the routine. Support for this routine is automatically detected during the NTP build process and interface code compiled as necessary. + +<p>There are two versions of the <tt>tty_clk</tt> routine. The <tt>tty_clk.c</tt> line discipline is designed for older BSD systems and is compiled in the kernel. The <tt>tty_clk_STREAMS.c</tt> is designed for System V streams, in which case it 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 of these routines is in the <tt>README</tt> file in the <tt>./kernel</tt> directory. + +<p>The <tt>tty_clk</tt> routine defines a new ioctl <tt>CLK_SETSTR</tt>, which takes a pointer to a string of no more than 32 characters. Until the first <tt>CLK_SETSTR</tt> is performed, the routine will simply pass through characters. Once it is passed a string by <tt>CLK_SETSTR</tt>, any character in that string will be immediately followed by a timestamp in Unix <tt>timeval</tt> format. You can change the string whenever you want by doing another <tt>CLK_SETSTR</tt>. 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 <tt>CLK_SETSTR</tt> turns off timestamping. Passing <tt>NULL</tt> may produce surprising results. + +<p><h4><tt>TIOCDCDTIMESTAMP</tt> ioctl in FreeBSD</h4> + +<p>This ioctl is included in FreeBSD 2.2 and later. It causes a timestamp to be inserted in the serial port receive data stream when the data carrier detect (DCD) signal is asserted. This is useful for those radio clocks that indicate the on-time epoch by means of a modem control signal. It is not recommended that this be used for PPS timestamps, as this function is available using the PPS application program interface included in FreeBSD 3.4 and later. + +<p>The <tt>TIOCDCDTIMESTAMP</tt> ioctl() is detected and compiled automatically on FreeBSD systems if available. With FreeBSD 2.2 the measured delay between activation of the DCD signal and the time the timestamp is captured on a 66MHz 486DX2 is 19 <font face=Symbol>m</font>s and on a 100MHz Pentium is 6 <font face=Symbol>m</font>s. + +<h4><tt>ppsclock</tt>Streams Module</h4> + +<p>This routine is a streams module which causes a timestamp to be captured when the DCD signal is asserted. It is normally used in connection with a PPS signal generated by some radio clocks. However, it is normally used only by the PPSAPI interface and should be avoided in other contexts. Instructions on how to configure and build a kernel supporting either of these routines is in the <tt>README</tt> file in the <tt>./kernel</tt> directory. + +<p>The ppsclock streams module implements the <tt>CIOGETEV</tt> ioctl, which takes a pointer to the structure <pre> struct ppsclockev { @@ -134,28 +74,16 @@ struct ppsclockev { }; </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> +<p>The <tt>ppsclock</tt> module is pushed on the streams stack of the serial port connected to the DCD line. At each positive-going edge of the PPS signal, the routine latches the current local timestamp and increments a counter. At each <tt>CIOGETEV</tt> ioctl call, the current values of the timestamp and counter are returned in the <tt>ppsclockev</tt> structure. + +<p><h4><tt>TIOCSPPS</tt> and <tt>TIOCGETPPSEV</tt> ioctls in Solaris</h4> + +<p>These ioctls are included in Solaris 2.4 and later. They implement the same function as the <tt>ppsclock</tt> streams module, but are implemented as integrated system calls independent of the streams facility. They are normally used in connection with a pulse-per-second (PPS) signal generated by some radio clocks. However, these ioctls are normally used only by the PPSAPI interface and should be avoided in other contexts. See the Sun documentation for the calling sequence and return values. + +<p>Users are cautioned that these ioctls function improperly in Solaris versions prior to 2.8 with patch Generic_108528-02. + +<h4><tt>tty_chu</tt> Line Discipline/Streams Module (depredated)</h4> + +<p>This routine is a special purpose line discipline for receiving a special timecode broadcast by Canadian time and frequency standard station CHU. It has been removed from the distribution since its function has been replaced by the <a href=driver7.htm>Radio CHU Audio Demodulator/Decoder (type 7)</a> clock driver. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a></address></a></body></html> |