1PARSE reference clock driver: 2 3This directory contains the files making up the parser for 4the parse refclock driver. For reasonably sane clocks this refclock 5drivers allows a refclock implementation by just providing a 6conversion routine and the appropriate NTP parameters. Refclock 7support can run as low a 3k code with the parse refclock driver. 8 9The modules in here are designed to live in two worlds. In userlevel 10as part of the xntp daemon and in kernel land as part of a STREAMS module 11or, if someone gets to it, as part of a line discipline. Currently only 12SunOS4.x/SunOS5.x STREAMS are supported (volunteers for other vendors like HP?). 13This structure means, that refclock_parse can work with or without kernel 14support. Kernelsupport increases accuracy tremendingly. The current restriction 15of the parse driver is that it only supports SYSV type ttys and that kernel 16support is only available for Suns right now. 17 18Three kernel modules are part of this directory. These work only on 19SunOS (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 32The 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 93Further information can be found in parse/README.parse and the various source 94files. 95 96Frank Kardel 97