contrib/ntp/libparse/README

   1 PARSE reference clock driver:
   2
   3 This directory contains the files making up the parser for
   4 the parse refclock driver. For reasonably sane clocks this refclock
   5 drivers allows a refclock implementation by just providing a
   6 conversion routine and the appropriate NTP parameters. Refclock
   7 support can run as low a 3k code with the parse refclock driver.
   8
   9 The modules in here are designed to live in two worlds. In userlevel
  10 as part of the xntp daemon and in kernel land as part of a STREAMS module
  11 or, if someone gets to it, as part of a line discipline. Currently only
  12 SunOS4.x/SunOS5.x STREAMS are supported (volunteers for other vendors like HP?).
  13 This structure means, that refclock_parse can work with or without kernel
  14 support. Kernelsupport increases accuracy tremendingly. The current restriction
  15 of the parse driver is that it only supports SYSV type ttys and that kernel
  16 support is only available for Suns right now.
  17
  18 Three kernel modules are part of this directory. These work only on
  19 SunOS (SunOS4 and SunOS5).
  20
  21         SunOS4 (aka Solaris 1.x):
  22                 parsestreams.loadable_module.o  - standard parse module for SunOS 4
  23
  24                 Both modules can be loaded via modload <modulename>.
  25
  26         SunOS5 (aka Solaris 2.x):
  27                 parse           - auto loadable streams module
  28
  29                 To install just drop "parse" into /kernel/strmod and
  30                 start the daemon (SunOS5 will do the rest).
  31
  32 The structure of the parse reference clock driver is as follows:
  33
  34         ntpd    - contains NTP implementation and calls a reference clock
  35                   127.127.8.x which is implemented by
  36                   refclock_parse.c
  37                   - which contains several refclock decriptions. These are
  38                     selected by the x part of the refclock address.
  39                     The lower two bits specify the device to use. Thus the
  40                     value (x % 4) determines the device to open
  41                     (/dev/refclock-0 - /dev/refclock-3).
  42
  43                     The kind of clock is selected by the mode parameter. This parameter
  44                     selects the clock type which deterimines how I/O is done,
  45                     the tty parameters and the NTP parameters.
  46
  47                     refclock_parse operates on an abstract reference clock
  48                     that delivers time stamps and stati. Offsets and sychron-
  49                     isation information is derived from this data and passed
  50                     on to refclock_receive of xntp which uses that data for
  51                     syncronisation.
  52
  53                     The abstract reference clock is generated by the parse*
  54                     routines. They parse the incoming data stream from the
  55                     clock and convert it to the appropriate time stamps.
  56                     The data is also mapped int the abstract clock states
  57                         POWERUP - clock has no valid phase and time code
  58                                   information
  59
  60                         NOSYNC  - Time code is not confirmed, phase is probably
  61                                   ok.
  62                         SYNC    - Time code and phase are correct.
  63
  64                     A clock is trusted for a certain time (type parameter) when
  65                     it leaves the SYNC state. This is derived from the
  66                     observation that quite a few clocks can still generate good
  67                     time code information when losing contact to their
  68                     synchronisation source. When the clock does not reagain
  69                     synchronisation in that trust period it will be deemed
  70                     unsynchronised until it regains synchronisation. The same
  71                     will happen if xntp sees the clock unsynchronised at
  72                     startup.
  73
  74                     The upper bit of x specifies that all samples delivered
  75                     from the clock should be used to discipline the NTP
  76                     loopfilter. For clock with accurate once a second time
  77                     information this means big improvements for time keeping.
  78                     A prerequisite for passing on the time stamps to
  79                     the loopfilter is, that the clock is in synchronised state.
  80
  81            parse.c  These are the general routines to parse the incoming data
  82                     stream. Usually these routines should not require
  83                     modification.
  84
  85            clk_*.c  These files hole the conversion code for the time stamps
  86                     and the description how the time code can be parsed and
  87                     where the time stamps are to be taken.
  88                     If you want to add a new clock type this is the file
  89                     you need to write in addition to mention it in
  90                     parse_conf.c and setting up the NTP and TTY parameters
  91                     in refclock_parse.c.
  92
  93 Further information can be found in parse/README.parse and the various source
  94 files.
  95
  96 Frank Kardel