154359SrobertoInstalling Line Disciplines and Streams Modules 254359Sroberto 354359SrobertoDescription 454359Sroberto 554359SrobertoMost radio and modem clocks used for a primary (stratum-1) NTP server 654359Srobertoutilize serial ports operating at speeds of 9600 baud or greater. The 754359Srobertotiming jitter contributed by the serial port hardware and software 854359Srobertodiscipline can accumulate to several milliseconds on a typical Unix 954359Srobertoworkstation. In order to reduce these errors, a set of special line 1054359Srobertodisciplines can be configured in the operating system process. These 1154359Srobertodisciplines intercept special characters or signals provided by the 1254359Srobertoradio or modem clock and save a local timestamp for later processing. 1354359Sroberto 1454359SrobertoThe disciplines can be compiled in the kernel in older BSD-derived 1554359Srobertosystems, or installed as System V streams modules and either compiled in 1654359Srobertothe kernel or dynamically loaded when required. In either case, they 1754359Srobertorequire reconfiguration of the Unix kernel and provisions in the NTP 1854359Srobertodaemon xntpd. The streams modules can be pushed and popped from the 1954359Srobertostreams stack using conventional System V streams program primitives. 2054359SrobertoNote that not all Unix kernels support line disciplines and of those 2154359Srobertothat do, not all support System V streams. The disciplines here are 2254359Srobertoknown to work correctly with SunOS 4.x kernels, but have not been tested 2354359Srobertofor other kernels. 2454359Sroberto 2554359SrobertoThere are two line disciplines included in the distribution. Support for 2654359Srobertoeach is enabled by adding flags to the DEFS_LOCAL line of the build 2754359Srobertoconfiguration file ./Config.local. This can be done automatically by the 2854359Srobertoautoconfiguration build procedures, or can be inserted/deleted after the 2954359Srobertoprocess has completed. 3054359Sroberto 3154359Srobertotty_clk (CLK) 3254359Sroberto 3354359Sroberto This discipline intercepts characters received from the serial port 3454359Sroberto and passes unchanged all except a set of designated characters to 3554359Sroberto the generic serial port discipline. For each of the exception 3654359Sroberto characters, the character is inserted in the receiver buffer 3754359Sroberto followed by a timestamp in Unix timeval format. Both select() and 3854359Sroberto SIGIO are supported by the discipline. The -DCLK flag is used to 3954359Sroberto compile support for this disipline in the NTP daemon. This flag is 4054359Sroberto included if the clkdefs.h file is found in the /sys/sys directory, 4154359Sroberto or it can be added (or deleted) manually. 4254359Sroberto 4354359Srobertotty_chu (CHU) 4454359Sroberto 4554359Sroberto This discipline is a special purpose line discipline for receiving 4654359Sroberto a special timecode broadcast by Canadian time and frequency 4754359Sroberto standard station CHU. The radio signal is first demodulated by the 4854359Sroberto 300-baud modem included in the gadget box, then processed by the 4954359Sroberto discipline and finally processed by the Scratchbuilt CHU Receiver 5054359Sroberto discipline (type 7). This discipline should be used in raw mode. 5154359Sroberto The -DCHU flag is used to compile support for this disipline in the 5254359Sroberto NTP daemon. This flag is included if the chudefs.h file is found in 5354359Sroberto the /sys/sys directory, or it can be added (or deleted) manually. 5454359Sroberto 5554359SrobertoThere are two sets of line disciplines. The tty_clk.c and chu_clk.c are 5654359Srobertodesigned for use with older BSD systems and are compiled in the kernel. 5754359SrobertoThe tty_clk_STREAMS.c and chu_clk_STREAMS.c are designed for use with 5854359SrobertoSystem V streams, in which case they can be either compiled in the 5954359Srobertokernel or dynamically loaded. Since these disciplines are small, 6054359Srobertounobtrusive, and to nothing unless specifically enabled by an 6154359Srobertoapplication program, it probably doesn't matter which method is choosen. 6254359Sroberto 6354359SrobertoCompiling with the Kernel 6454359Sroberto 6554359SrobertoThe following procedures are for the tty_clk line discipline; for the 6654359Srobertochu_clk, change "tty" to "chu". 6754359Sroberto1. Copy tty_clk.c into /sys/os and clkdefs.h into /sys/sys. 6854359Sroberto 6954359Sroberto2. For SunOS 4.x systems, edit /sys/os/tty_conf.c using some facsimile 7054359Sroberto of the following lines: 7154359Sroberto 7254359Sroberto #include "clk.h" 7354359Sroberto ... 7454359Sroberto #if NCLK > 0 7554359Sroberto int clkopen(), clkclose(), clkwrite(), clkinput(), clkioctl(); 7654359Sroberto #endif 7754359Sroberto ... 7854359Sroberto #if NCLK > 0 7954359Sroberto { clkopen, clkclose, ttread, clkwrite, clkioctl, 8054359Sroberto clkinput, nodev, nulldev, ttstart, nullmodem, /* 10 CLK */ 8154359Sroberto ttselect }, 8254359Sroberto #else 8354359Sroberto { nodev, nodev, nodev, nodev, nodev, 8454359Sroberto nodev, nodev, nodev, nodev, nodev, 8554359Sroberto nodev }, 8654359Sroberto #endif 8754359Sroberto 8854359Sroberto For Ultrix 4.x systems, edit /sys/data/tty_conf_data.c using some 8954359Sroberto facsimile of the following lines: 9054359Sroberto 9154359Sroberto #include "clk.h" 9254359Sroberto ... 9354359Sroberto #if NCLK > 0 9454359Sroberto int clkopen(), clkclose(), clkwrite(), clkinput(), clkioctl(); 9554359Sroberto #endif 9654359Sroberto ... 9754359Sroberto #if NCLK > 0 9854359Sroberto clkopen, clkclose, ttread, clkwrite, clkioctl, /* 10 CLK */ 9954359Sroberto clkinput, nodev, nulldev, ttstart, nulldev, 10054359Sroberto #else 10154359Sroberto nodev, nodev, nodev, nodev, nodev, 10254359Sroberto nodev, nodev, nodev, nodev, nodev, 10354359Sroberto #endif 10454359Sroberto 10554359Sroberto If the kernel doesn't include the ??select() entry in the structure 10654359Sroberto (i.e., there are only ten entry points in the structure) just leave 10754359Sroberto it out. Also note that the number you give the line discipline (10 10854359Sroberto in most kernels) will be specific to that kernel and will depend on 10954359Sroberto what is in there already. The entries sould be in order with no 11054359Sroberto missing space; that is, if there are only seven disciplines already 11154359Sroberto defined and you want to use 10 for good reason, you should define a 11254359Sroberto dummy 9th entry like this: 11354359Sroberto 11454359Sroberto nodev, nodev, nodev, nodev, nodev, /* 9 CLK */ 11554359Sroberto nodev, nodev, nodev, nodev, nodev, 11654359Sroberto 11754359Sroberto3. Edit /sys/h/ioctl.h and include a line somewhere near where other 11854359Sroberto line disciplines are defined like: 11954359Sroberto 12054359Sroberto #define CLKLDISC 10 /* clock line discipline */ 12154359Sroberto 12254359Sroberto The "10" should match what you used as the number in the preceding 12354359Sroberto step. 12454359Sroberto 12554359Sroberto4. Edit /sys/conf/files and add a line which looks like: 12654359Sroberto 12754359Sroberto sys/tty_clk.c optional clk 12854359Sroberto 12954359Sroberto5. Edit the kernel configuration file to include the following: 13054359Sroberto 13154359Sroberto pseudo-device tty 4 # TTY clock support 13254359Sroberto6. Run config, then make clean, then make depend, then make vmunix, 13354359Sroberto then reboot the new kernel. 13454359Sroberto 13554359SrobertoInstalling as a streams module 13654359Sroberto 13754359SrobertoThe following procedures are for the tty_clk_STREAMS line discipline; 13854359Srobertofor the tty_chu_STREAMS, change "clk" to "chu". 13954359Sroberto 14054359Sroberto1. Copy your choice to /sys/os, removing the "_STREAMS" in the 14154359Sroberto filename. 14254359Sroberto 14354359Sroberto2. Copy the clkdefs.h file to /usr/include/sys, then construct a soft 14454359Sroberto link to /sys/sys. 14554359Sroberto 14654359Sroberto3. Append to /sys/conf.common/files.cmn: 14754359Sroberto 14854359Sroberto os/tty_tty.c optional tty 14954359Sroberto 15054359Sroberto4. Edit /sys/sun/str_conf.c. You'll want to add lines in three places. 15154359Sroberto It'll be sort of clear where when you see the file. 15254359Sroberto 15354359Sroberto #include "tty.h" 15454359Sroberto ... 15554359Sroberto #if NTTY > 0 15654359Sroberto extern struct streamtab ttyinfo; 15754359Sroberto #endif 15854359Sroberto ... 15954359Sroberto #if NTTY > 0 16054359Sroberto { "tty", &ttyinfo }, 16154359Sroberto #endif 16254359Sroberto 16354359Sroberto5. Edit /sys/[arch]/conf/[k-name] (substituting the architecture and 16454359Sroberto kernel name) to stick in: 16554359Sroberto 16654359Sroberto pseudo-device tty 4 # TTY clock support 16754359Sroberto 16854359Sroberto You can change "4" to anything you like. It will limit the number 16954359Sroberto of instantiations of the tty discipline you can use at the same 17054359Sroberto time. 17154359Sroberto 17254359Sroberto6. Run config, then make clean, then make depend, then make vmunix, 17354359Sroberto then reboot the new kernel. 17454359Sroberto 17554359SrobertoBoth disciplines can be dynamically loaded using streams procedures 17654359Srobertospecific to the kernel. Before using the chu_clk discipline, all other 17754359Srobertostreams modules that may already be on the stack should be popped, then 17854359Srobertothe discipline should be pushed on the stack. 17954359Sroberto 18054359SrobertoHow to Use the tty_clk Line Discipline 18154359Sroberto 18254359SrobertoThe tty_clk line discipline defines a new ioctl(), CLK_SETSTR, which 18354359Srobertotakes a pointer to a string of no more than CLK_MAXSTRSIZE characters. 18454359SrobertoUntil the first CLK_SETSTR is performed, the discipline will simply pass 18554359Srobertothrough characters. Once it is passed a string by CLK_SETSTR, any 18654359Srobertocharacter in that string will be immediately followed by a timestamp in 18754359SrobertoUnix timeval format. You can change the string whenever you want by 18854359Srobertodoing another CLK_SETSTR. The character must be an exact, 8 bit match. 18954359SrobertoThe character '\000' cannot, unfortunately, be used, as it is the string 19054359Srobertoterminator. Passing an empty string to CLK_SETSTR turns off stamping. 19154359SrobertoPassing NULL will produce undefined results. 19254359Sroberto 19354359SrobertoHow to Use the tty_chu Line Discipline 19454359SrobertoThe tty_chu line discipline translates data received from the CHU modem 19554359Srobertoand returns chucode structures, as defined in chudefs.h, and expected by 19654359Srobertothe Scratchbuilt CHU Receiver reference clock driver. Depending on the 19754359Srobertosettings of PEDANTIC and ANAL_RETENTIVE used when compiling the kernel, 19854359Srobertosome checking of the data may or may not be necessary. 19954359Sroberto 20054359SrobertoDavid L. Mills (mills@udel.edu) 201