= PARSE reference clock driver =
by Frank Kardel

This directory contains the files making up the parser for
the parse refclock driver. For reasonably sane clocks this refclock
drivers allows a refclock implementation by just providing a
conversion routine and the appropriate NTP parameters. Refclock
support can run as low as 3k code with the parse refclock driver.

The structure of the parse reference clock driver is as follows:

ntpd contains the contains NTP implementation and calls a reference
clock driver named "generic" which is implemented by refclock_parse.c,
which contains a large number of refclock descriptions.

The kind of clock is selected by the subtype parameter. This parameter
selects the clock type which determines how I/O is done, the tty
parameters and the NTP parameters.

refclock_parse operates on an abstract reference clock that delivers
time stamps and statuses. Offsets and sychronization information is
derived from this data and passed on to refclock_receive of ntpd which
uses that data for syncronisation.

The abstract reference clock is generated by the parse* routines. They
parse the incoming data stream from the clock and convert it to the
appropriate time stamps.  The data is also mapped into the abstract
clock states

POWERUP:: clock has no valid phase and time code information.

NOSYNC:: Time code is not confirmed, phase is probably OK.

SYNC:: Time code and phase are correct.

A clock is trusted for a certain time (type parameter) when it leaves
the SYNC state. This is derived from the observation that quite a few
clocks can still generate good time code information when losing
contact to their synchronisation source. When the clock does not
reagain synchronisation in that trust period it will be deemed
unsynchronised until it regains synchronisation. The same will happen
if ntpd sees the clock unsynchronised at startup.

The upper bit of x specifies that all samples delivered from the clock
should be used to discipline the NTP loopfilter. For clock with
accurate once a second time information this means big improvements
for time keeping.  A prerequisite for passing on the time stamps to
the loopfilter is that the clock is in synchronised state.

Here is how to read the files in this (libparse) directory:

parse.c:: These are the general routines to parse the incoming data
	  stream. Usually these routines should not require
	  modification.

clk_*.c:: These files hold the conversion code for the time stamps and
	  the description how the time code can be parsed and where
	  the time stamps are to be taken.  If you want to add a new
	  clock type, this is the file you need to write in addition
	  to mentioning it in parse_conf.c and setting up the NTP and
	  TTY parameters in refclock_parse.c.

Further information can be found in the various source files.

