Return to README CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / ntp / kernel

Initial revision

    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)