Annotation of embedaddon/ntp/kernel/README, revision 1.1
1.1 ! misho 1: Installing Line Disciplines and Streams Modules
! 2:
! 3: Description
! 4:
! 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.
! 13:
! 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
! 23: for other kernels.
! 24:
! 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.
! 30:
! 31: tty_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:
! 43: tty_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:
! 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.
! 62:
! 63: Compiling with the Kernel
! 64:
! 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.
! 68:
! 69: 2. 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:
! 117: 3. 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:
! 125: 4. Edit /sys/conf/files and add a line which looks like:
! 126:
! 127: sys/tty_clk.c optional clk
! 128:
! 129: 5. Edit the kernel configuration file to include the following:
! 130:
! 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.
! 134:
! 135: Installing as a streams module
! 136:
! 137: The following procedures are for the tty_clk_STREAMS line discipline;
! 138: for the tty_chu_STREAMS, change "clk" to "chu".
! 139:
! 140: 1. Copy your choice to /sys/os, removing the "_STREAMS" in the
! 141: filename.
! 142:
! 143: 2. Copy the clkdefs.h file to /usr/include/sys, then construct a soft
! 144: link to /sys/sys.
! 145:
! 146: 3. Append to /sys/conf.common/files.cmn:
! 147:
! 148: os/tty_tty.c optional tty
! 149:
! 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.
! 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:
! 163: 5. 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:
! 172: 6. Run config, then make clean, then make depend, then make vmunix,
! 173: then reboot the new kernel.
! 174:
! 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.
! 179:
! 180: How to Use the tty_clk Line Discipline
! 181:
! 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.
! 192:
! 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.
! 199:
! 200: David L. Mills (mills@udel.edu)
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / ntp / kernel