1Installing Line Disciplines and Streams Modules
2
3Description
4
5Most radio and modem clocks used for a primary (stratum-1) NTP server
6utilize serial ports operating at speeds of 9600 baud or greater. The
7timing jitter contributed by the serial port hardware and software
8discipline can accumulate to several milliseconds on a typical Unix
9workstation. In order to reduce these errors, a set of special line
10disciplines can be configured in the operating system process. These
11disciplines intercept special characters or signals provided by the
12radio or modem clock and save a local timestamp for later processing.
13
14The disciplines can be compiled in the kernel in older BSD-derived
15systems, or installed as System V streams modules and either compiled in
16the kernel or dynamically loaded when required. In either case, they
17require reconfiguration of the Unix kernel and provisions in the NTP
18daemon xntpd. The streams modules can be pushed and popped from the
19streams stack using conventional System V streams program primitives.
20Note that not all Unix kernels support line disciplines and of those
21that do, not all support System V streams. The disciplines here are
22known to work correctly with SunOS 4.x kernels, but have not been tested
23for other kernels.
24
25There are two line disciplines included in the distribution. Support for
26each is enabled by adding flags to the DEFS_LOCAL line of the build
27configuration file ./Config.local. This can be done automatically by the
28autoconfiguration build procedures, or can be inserted/deleted after the
29process has completed.
30
31tty_clk (CLK)
32
33     This discipline intercepts characters received from the serial port
34     and passes unchanged all except a set of designated characters to
35     the generic serial port discipline. For each of the exception
36     characters, the character is inserted in the receiver buffer
37     followed by a timestamp in Unix timeval format. Both select() and
38     SIGIO are supported by the discipline. The -DCLK flag is used to
39     compile support for this disipline in the NTP daemon. This flag is
40     included if the clkdefs.h file is found in the /sys/sys directory,
41     or it can be added (or deleted) manually.
42
43tty_chu (CHU)
44
45     This discipline is a special purpose line discipline for receiving
46     a special timecode broadcast by Canadian time and frequency
47     standard station CHU. The radio signal is first demodulated by the
48     300-baud modem included in the gadget box, then processed by the
49     discipline and finally processed by the Scratchbuilt CHU Receiver
50     discipline (type 7). This discipline should be used in raw mode.
51     The -DCHU flag is used to compile support for this disipline in the
52     NTP daemon. This flag is included if the chudefs.h file is found in
53     the /sys/sys directory, or it can be added (or deleted) manually.
54
55There are two sets of line disciplines. The tty_clk.c and chu_clk.c are
56designed for use with older BSD systems and are compiled in the kernel.
57The tty_clk_STREAMS.c and chu_clk_STREAMS.c are designed for use with
58System V streams, in which case they can be either compiled in the
59kernel or dynamically loaded. Since these disciplines are small,
60unobtrusive, and to nothing unless specifically enabled by an
61application program, it probably doesn't matter which method is choosen.
62
63Compiling with the Kernel
64
65The following procedures are for the tty_clk line discipline; for the
66chu_clk, change "tty" to "chu".
671.   Copy tty_clk.c into /sys/os and clkdefs.h into /sys/sys.
68
692.   For SunOS 4.x systems, edit /sys/os/tty_conf.c using some facsimile
70     of the following lines:
71
72     #include "clk.h"
73     ...
74     #if NCLK > 0
75     int  clkopen(), clkclose(), clkwrite(), clkinput(), clkioctl();
76     #endif
77     ...
78     #if NCLK > 0
79          { clkopen, clkclose, ttread, clkwrite, clkioctl,
80            clkinput, nodev, nulldev, ttstart, nullmodem, /* 10 CLK */
81            ttselect },
82     #else
83          { nodev, nodev, nodev, nodev, nodev,
84            nodev, nodev, nodev, nodev, nodev,
85            nodev },
86     #endif
87
88     For Ultrix 4.x systems, edit /sys/data/tty_conf_data.c using some
89     facsimile of the following lines:
90
91     #include "clk.h"
92     ...
93     #if NCLK > 0
94     int  clkopen(), clkclose(), clkwrite(), clkinput(), clkioctl();
95     #endif
96     ...
97     #if NCLK > 0
98          clkopen, clkclose, ttread, clkwrite, clkioctl, /* 10 CLK */
99          clkinput, nodev, nulldev, ttstart, nulldev,
100     #else
101          nodev, nodev, nodev, nodev, nodev,
102          nodev, nodev, nodev, nodev, nodev,
103     #endif
104
105     If the kernel doesn't include the ??select() entry in the structure
106     (i.e., there are only ten entry points in the structure) just leave
107     it out. Also note that the number you give the line discipline (10
108     in most kernels) will be specific to that kernel and will depend on
109     what is in there already. The entries sould be in order with no
110     missing space; that is, if there are only seven disciplines already
111     defined and you want to use 10 for good reason, you should define a
112     dummy 9th entry like this:
113
114     nodev, nodev, nodev, nodev, nodev, /* 9 CLK */
115     nodev, nodev, nodev, nodev, nodev,
116
1173.   Edit /sys/h/ioctl.h and include a line somewhere near where other
118     line disciplines are defined like:
119
120     #define  CLKLDISC  10        /* clock line discipline */
121
122     The "10" should match what you used as the number in the preceding
123     step.
124
1254.   Edit /sys/conf/files and add a line which looks like:
126
127     sys/tty_clk.c     optional clk
128
1295.   Edit the kernel configuration file to include the following:
130
131     pseudo-device  tty 4  # TTY clock support
1326.   Run config, then make clean, then make depend, then make vmunix,
133     then reboot the new kernel.
134
135Installing as a streams module
136
137The following procedures are for the tty_clk_STREAMS line discipline;
138for the tty_chu_STREAMS, change "clk" to "chu".
139
1401.   Copy your choice to /sys/os, removing the "_STREAMS" in the
141     filename.
142
1432.   Copy the clkdefs.h file to /usr/include/sys, then construct a soft
144     link to /sys/sys.
145
1463.   Append to /sys/conf.common/files.cmn:
147
148     os/tty_tty.c  optional tty
149
1504.   Edit /sys/sun/str_conf.c. You'll want to add lines in three places.
151     It'll be sort of clear where when you see the file.
152
153     #include "tty.h"
154     ...
155     #if NTTY > 0
156     extern struct streamtab ttyinfo;
157     #endif
158     ...
159     #if NTTY > 0
160          { "tty", &ttyinfo },
161     #endif
162
1635.   Edit /sys/[arch]/conf/[k-name] (substituting the architecture and
164     kernel name) to stick in:
165
166     pseudo-device  tty 4  # TTY clock support
167
168     You can change "4" to anything you like. It will limit the number
169     of instantiations of the tty discipline you can use at the same
170     time.
171
1726.   Run config, then make clean, then make depend, then make vmunix,
173     then reboot the new kernel.
174
175Both disciplines can be dynamically loaded using streams procedures
176specific to the kernel. Before using the chu_clk discipline, all other
177streams modules that may already be on the stack should be popped, then
178the discipline should be pushed on the stack.
179
180How to Use the tty_clk Line Discipline
181
182The tty_clk line discipline defines a new ioctl(), CLK_SETSTR, which
183takes a pointer to a string of no more than CLK_MAXSTRSIZE characters.
184Until the first CLK_SETSTR is performed, the discipline will simply pass
185through characters. Once it is passed a string by CLK_SETSTR, any
186character in that string will be immediately followed by a timestamp in
187Unix timeval format. You can change the string whenever you want by
188doing another CLK_SETSTR. The character must be an exact, 8 bit match.
189The character '\000' cannot, unfortunately, be used, as it is the string
190terminator. Passing an empty string to CLK_SETSTR turns off stamping.
191Passing NULL will produce undefined results.
192
193How to Use the tty_chu Line Discipline
194The tty_chu line discipline translates data received from the CHU modem
195and returns chucode structures, as defined in chudefs.h, and expected by
196the Scratchbuilt CHU Receiver reference clock  driver. Depending on the
197settings of PEDANTIC and ANAL_RETENTIVE used when compiling the kernel,
198some checking of the data may or may not be necessary.
199
200David L. Mills (mills@udel.edu)
201