diff options
Diffstat (limited to 'contrib/ntp/kernel/README')
-rw-r--r-- | contrib/ntp/kernel/README | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/contrib/ntp/kernel/README b/contrib/ntp/kernel/README new file mode 100644 index 000000000000..253d04e4e8d5 --- /dev/null +++ b/contrib/ntp/kernel/README @@ -0,0 +1,200 @@ +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) |