NetBSD-5.0.2/dist/ntp/kernel/README
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)