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