1 Installing Line Disciplines and Streams Modules
5 Most radio and modem clocks used for a primary (stratum-1) NTP server
6 utilize serial ports operating at speeds of 9600 baud or greater. The
7 timing jitter contributed by the serial port hardware and software
8 discipline can accumulate to several milliseconds on a typical Unix
9 workstation. In order to reduce these errors, a set of special line
10 disciplines can be configured in the operating system process. These
11 disciplines intercept special characters or signals provided by the
12 radio or modem clock and save a local timestamp for later processing.
14 The disciplines can be compiled in the kernel in older BSD-derived
15 systems, or installed as System V streams modules and either compiled in
16 the kernel or dynamically loaded when required. In either case, they
17 require reconfiguration of the Unix kernel and provisions in the NTP
18 daemon xntpd. The streams modules can be pushed and popped from the
19 streams stack using conventional System V streams program primitives.
20 Note that not all Unix kernels support line disciplines and of those
21 that do, not all support System V streams. The disciplines here are
22 known to work correctly with SunOS 4.x kernels, but have not been tested
25 There are two line disciplines included in the distribution. Support for
26 each is enabled by adding flags to the DEFS_LOCAL line of the build
27 configuration file ./Config.local. This can be done automatically by the
28 autoconfiguration build procedures, or can be inserted/deleted after the
29 process has completed.
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.
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.
55 There are two sets of line disciplines. The tty_clk.c and chu_clk.c are
56 designed for use with older BSD systems and are compiled in the kernel.
57 The tty_clk_STREAMS.c and chu_clk_STREAMS.c are designed for use with
58 System V streams, in which case they can be either compiled in the
59 kernel or dynamically loaded. Since these disciplines are small,
60 unobtrusive, and to nothing unless specifically enabled by an
61 application program, it probably doesn't matter which method is choosen.
63 Compiling with the Kernel
65 The following procedures are for the tty_clk line discipline; for the
66 chu_clk, change "tty" to "chu".
67 1. Copy tty_clk.c into /sys/os and clkdefs.h into /sys/sys.
69 2. For SunOS 4.x systems, edit /sys/os/tty_conf.c using some facsimile
70 of the following lines:
75 int clkopen(), clkclose(), clkwrite(), clkinput(), clkioctl();
79 { clkopen, clkclose, ttread, clkwrite, clkioctl,
80 clkinput, nodev, nulldev, ttstart, nullmodem, /* 10 CLK */
83 { nodev, nodev, nodev, nodev, nodev,
84 nodev, nodev, nodev, nodev, nodev,
88 For Ultrix 4.x systems, edit /sys/data/tty_conf_data.c using some
89 facsimile of the following lines:
94 int clkopen(), clkclose(), clkwrite(), clkinput(), clkioctl();
98 clkopen, clkclose, ttread, clkwrite, clkioctl, /* 10 CLK */
99 clkinput, nodev, nulldev, ttstart, nulldev,
101 nodev, nodev, nodev, nodev, nodev,
102 nodev, nodev, nodev, nodev, nodev,
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:
114 nodev, nodev, nodev, nodev, nodev, /* 9 CLK */
115 nodev, nodev, nodev, nodev, nodev,
117 3. Edit /sys/h/ioctl.h and include a line somewhere near where other
118 line disciplines are defined like:
120 #define CLKLDISC 10 /* clock line discipline */
122 The "10" should match what you used as the number in the preceding
125 4. Edit /sys/conf/files and add a line which looks like:
127 sys/tty_clk.c optional clk
129 5. Edit the kernel configuration file to include the following:
131 pseudo-device tty 4 # TTY clock support
132 6. Run config, then make clean, then make depend, then make vmunix,
133 then reboot the new kernel.
135 Installing as a streams module
137 The following procedures are for the tty_clk_STREAMS line discipline;
138 for the tty_chu_STREAMS, change "clk" to "chu".
140 1. Copy your choice to /sys/os, removing the "_STREAMS" in the
143 2. Copy the clkdefs.h file to /usr/include/sys, then construct a soft
146 3. Append to /sys/conf.common/files.cmn:
148 os/tty_tty.c optional tty
150 4. 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.
156 extern struct streamtab ttyinfo;
163 5. Edit /sys/[arch]/conf/[k-name] (substituting the architecture and
164 kernel name) to stick in:
166 pseudo-device tty 4 # TTY clock support
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
172 6. Run config, then make clean, then make depend, then make vmunix,
173 then reboot the new kernel.
175 Both disciplines can be dynamically loaded using streams procedures
176 specific to the kernel. Before using the chu_clk discipline, all other
177 streams modules that may already be on the stack should be popped, then
178 the discipline should be pushed on the stack.
180 How to Use the tty_clk Line Discipline
182 The tty_clk line discipline defines a new ioctl(), CLK_SETSTR, which
183 takes a pointer to a string of no more than CLK_MAXSTRSIZE characters.
184 Until the first CLK_SETSTR is performed, the discipline will simply pass
185 through characters. Once it is passed a string by CLK_SETSTR, any
186 character in that string will be immediately followed by a timestamp in
187 Unix timeval format. You can change the string whenever you want by
188 doing another CLK_SETSTR. The character must be an exact, 8 bit match.
189 The character '\000' cannot, unfortunately, be used, as it is the string
190 terminator. Passing an empty string to CLK_SETSTR turns off stamping.
191 Passing NULL will produce undefined results.
193 How to Use the tty_chu Line Discipline
194 The tty_chu line discipline translates data received from the CHU modem
195 and returns chucode structures, as defined in chudefs.h, and expected by
196 the Scratchbuilt CHU Receiver reference clock driver. Depending on the
197 settings of PEDANTIC and ANAL_RETENTIVE used when compiling the kernel,
198 some checking of the data may or may not be necessary.
200 David L. Mills (mills@udel.edu)