Annotation of embedaddon/ntp/kernel/README, revision 1.1.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