201 lines
8.1 KiB
Plaintext
201 lines
8.1 KiB
Plaintext
Installing Line Disciplines and Streams Modules
|
|
|
|
Description
|
|
|
|
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
|
|
discipline can accumulate to several milliseconds on a typical Unix
|
|
workstation. In order to reduce these errors, a set of special line
|
|
disciplines can be configured in the operating system process. These
|
|
disciplines intercept special characters or signals provided by the
|
|
radio or modem clock and save a local timestamp for later processing.
|
|
|
|
The disciplines 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 reconfiguration of the Unix kernel and provisions in the NTP
|
|
daemon xntpd. 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.
|
|
|
|
There are two line disciplines included in the distribution. Support for
|
|
each is enabled by adding flags to the DEFS_LOCAL line of the build
|
|
configuration file ./Config.local. This can be done automatically by the
|
|
autoconfiguration build procedures, or can be inserted/deleted after the
|
|
process has completed.
|
|
|
|
tty_clk (CLK)
|
|
|
|
This discipline 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 timestamp in Unix timeval format. Both select() and
|
|
SIGIO are supported by the discipline. The -DCLK flag is used to
|
|
compile support for this disipline in the NTP daemon. This flag is
|
|
included if the clkdefs.h file is found in the /sys/sys directory,
|
|
or it can be added (or deleted) manually.
|
|
|
|
tty_chu (CHU)
|
|
|
|
This discipline 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 Scratchbuilt CHU Receiver
|
|
discipline (type 7). This discipline should be used in raw mode.
|
|
The -DCHU flag is used to compile support for this disipline in the
|
|
NTP daemon. This flag is included if the chudefs.h file is found in
|
|
the /sys/sys directory, or it can be added (or deleted) manually.
|
|
|
|
There are two sets of line disciplines. The tty_clk.c and chu_clk.c are
|
|
designed for use with older BSD systems and are compiled in the kernel.
|
|
The tty_clk_STREAMS.c and chu_clk_STREAMS.c are designed for use with
|
|
System V streams, in which case they can be either compiled in the
|
|
kernel or dynamically loaded. Since these disciplines are small,
|
|
unobtrusive, and to nothing unless specifically enabled by an
|
|
application program, it probably doesn't matter which method is choosen.
|
|
|
|
Compiling with the Kernel
|
|
|
|
The following procedures are for the tty_clk line discipline; for the
|
|
chu_clk, change "tty" to "chu".
|
|
1. Copy tty_clk.c into /sys/os and clkdefs.h into /sys/sys.
|
|
|
|
2. For SunOS 4.x systems, edit /sys/os/tty_conf.c using some facsimile
|
|
of the following lines:
|
|
|
|
#include "clk.h"
|
|
...
|
|
#if NCLK > 0
|
|
int clkopen(), clkclose(), clkwrite(), clkinput(), clkioctl();
|
|
#endif
|
|
...
|
|
#if NCLK > 0
|
|
{ clkopen, clkclose, ttread, clkwrite, clkioctl,
|
|
clkinput, nodev, nulldev, ttstart, nullmodem, /* 10 CLK */
|
|
ttselect },
|
|
#else
|
|
{ nodev, nodev, nodev, nodev, nodev,
|
|
nodev, nodev, nodev, nodev, nodev,
|
|
nodev },
|
|
#endif
|
|
|
|
For Ultrix 4.x systems, edit /sys/data/tty_conf_data.c using some
|
|
facsimile of the following lines:
|
|
|
|
#include "clk.h"
|
|
...
|
|
#if NCLK > 0
|
|
int clkopen(), clkclose(), clkwrite(), clkinput(), clkioctl();
|
|
#endif
|
|
...
|
|
#if NCLK > 0
|
|
clkopen, clkclose, ttread, clkwrite, clkioctl, /* 10 CLK */
|
|
clkinput, nodev, nulldev, ttstart, nulldev,
|
|
#else
|
|
nodev, nodev, nodev, nodev, nodev,
|
|
nodev, nodev, nodev, nodev, nodev,
|
|
#endif
|
|
|
|
If the kernel doesn't include the ??select() entry in the structure
|
|
(i.e., there are only ten entry points in the structure) just leave
|
|
it out. Also note that the number you give the line discipline (10
|
|
in most kernels) will be specific to that kernel and will depend on
|
|
what is in there already. The entries sould be in order with no
|
|
missing space; that is, if there are only seven disciplines already
|
|
defined and you want to use 10 for good reason, you should define a
|
|
dummy 9th entry like this:
|
|
|
|
nodev, nodev, nodev, nodev, nodev, /* 9 CLK */
|
|
nodev, nodev, nodev, nodev, nodev,
|
|
|
|
3. Edit /sys/h/ioctl.h and include a line somewhere near where other
|
|
line disciplines are defined like:
|
|
|
|
#define CLKLDISC 10 /* clock line discipline */
|
|
|
|
The "10" should match what you used as the number in the preceding
|
|
step.
|
|
|
|
4. Edit /sys/conf/files and add a line which looks like:
|
|
|
|
sys/tty_clk.c optional clk
|
|
|
|
5. Edit the kernel configuration file to include the following:
|
|
|
|
pseudo-device tty 4 # TTY clock support
|
|
6. Run config, then make clean, then make depend, then make vmunix,
|
|
then reboot the new kernel.
|
|
|
|
Installing as a streams module
|
|
|
|
The following procedures are for the tty_clk_STREAMS line discipline;
|
|
for the tty_chu_STREAMS, change "clk" to "chu".
|
|
|
|
1. Copy your choice to /sys/os, removing the "_STREAMS" in the
|
|
filename.
|
|
|
|
2. Copy the clkdefs.h file to /usr/include/sys, then construct a soft
|
|
link to /sys/sys.
|
|
|
|
3. Append to /sys/conf.common/files.cmn:
|
|
|
|
os/tty_tty.c optional tty
|
|
|
|
4. Edit /sys/sun/str_conf.c. You'll want to add lines in three places.
|
|
It'll be sort of clear where when you see the file.
|
|
|
|
#include "tty.h"
|
|
...
|
|
#if NTTY > 0
|
|
extern struct streamtab ttyinfo;
|
|
#endif
|
|
...
|
|
#if NTTY > 0
|
|
{ "tty", &ttyinfo },
|
|
#endif
|
|
|
|
5. Edit /sys/[arch]/conf/[k-name] (substituting the architecture and
|
|
kernel name) to stick in:
|
|
|
|
pseudo-device tty 4 # TTY clock support
|
|
|
|
You can change "4" to anything you like. It will limit the number
|
|
of instantiations of the tty discipline you can use at the same
|
|
time.
|
|
|
|
6. Run config, then make clean, then make depend, then make vmunix,
|
|
then reboot the new kernel.
|
|
|
|
Both disciplines can be dynamically loaded using streams procedures
|
|
specific to the kernel. Before using the chu_clk discipline, all other
|
|
streams modules that may already be on the stack should be popped, then
|
|
the discipline should be pushed on the stack.
|
|
|
|
How to Use the tty_clk Line Discipline
|
|
|
|
The tty_clk line discipline defines a new ioctl(), CLK_SETSTR, which
|
|
takes a pointer to a string of no more than CLK_MAXSTRSIZE characters.
|
|
Until the first CLK_SETSTR is performed, the discipline will simply pass
|
|
through characters. Once it is passed a string by CLK_SETSTR, any
|
|
character in that string will be immediately followed by a timestamp in
|
|
Unix timeval format. You can change the string whenever you want by
|
|
doing another CLK_SETSTR. The character must be an exact, 8 bit match.
|
|
The character '\000' cannot, unfortunately, be used, as it is the string
|
|
terminator. Passing an empty string to CLK_SETSTR turns off stamping.
|
|
Passing NULL will produce undefined results.
|
|
|
|
How to Use the tty_chu Line Discipline
|
|
The tty_chu line discipline translates data received from the CHU modem
|
|
and returns chucode structures, as defined in chudefs.h, and expected by
|
|
the Scratchbuilt CHU Receiver reference clock driver. Depending on the
|
|
settings of PEDANTIC and ANAL_RETENTIVE used when compiling the kernel,
|
|
some checking of the data may or may not be necessary.
|
|
|
|
David L. Mills (mills@udel.edu)
|