contrib/ntp/kernel/README

   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)