Return to README CVS log

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

Annotation of embedaddon/ntp/libparse/README, revision 1.1.1.1

1.1       misho       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