diff options
Diffstat (limited to 'usr.sbin/xntpd/parse/README.new_clocks')
| -rw-r--r-- | usr.sbin/xntpd/parse/README.new_clocks | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/usr.sbin/xntpd/parse/README.new_clocks b/usr.sbin/xntpd/parse/README.new_clocks new file mode 100644 index 0000000..8fdd7cb --- /dev/null +++ b/usr.sbin/xntpd/parse/README.new_clocks @@ -0,0 +1,212 @@ +Here is an attempt to sketch out what you need to do in order to +add another clock to the parse driver: + +Prerequisites: +- Does the system you want the clock connect to have + termio.h or termios.h ? (You need that for the parse driver) + +What to do: + +Make a conversion module (parse/clk_*.c) + +- What ist the time code format ? + - find year, month, day, hour, minute, second, status (synchronised or + not), possibly time zone information (you need to give the offset to UTC) + You will have to convert the data from a string into a struct clocktime: + struct clocktime /* clock time broken up from time code */ + { + LONG day; + LONG month; + LONG year; + LONG hour; + LONG minute; + LONG second; + LONG usecond; + LONG utcoffset; /* in seconds */ + time_t utcoffset; /* true utc time instead of date/time */ + LONG flags; /* current clock status */ + }; + + Conversion is usually simple and straight forward. For the flags following + values can be OR'ed together: + + PARSEB_ANNOUNCE switch time zone warning (informational only) + PARSEB_POWERUP no synchronisation - clock confused (must set then) + PARSEB_NOSYNC timecode currently not confirmed (must set then) + usually on reception error when there is still a + chance the the generated time is still ok. + + PARSEB_DST DST in effect (informational only) + PARSEB_UTC timecode contains UTC time (informational only) + PARSEB_LEAPADD LEAP addition warning (prior to leap happening - must set when imminent) + also used for time code that do not encode the + direction (as this is currently the default). + PARSEB_LEAPDEL LEAP deletion warning (prior to leap happening - must set when imminent) + PARSEB_ALTERNATE backup transmitter (informational only) + PARSEB_POSITION geographic position available (informational only) + PARSEB_LEAPSECOND actual leap second (this time code is the leap + second - informational only) + + These are feature flags denoting items that are supported by the clock: + PARSEB_S_LEAP supports LEAP - might set PARSEB_LEAP + PARSEB_S_ANTENNA supports ANTENNA - might set PARSEB_ALTERNATE + PARSEB_S_PPS supports PPS time stamping + PARSEB_S_POSITION supports position information (GPS) + + If the utctime field is non zero this value will be take as + time code value. This allows for conversion routines that + already have the utc time value. The utctime field gives the seconds + since Jan 1st 1970, 0:00:00. The useconds field gives the respective + usec value. The fields for date and time (down to second resolution) + will be ignored. + + Conversion is done in the cvt_* routine in parse/clk_*.c files. look in + them for examples. The basic structure is: + + struct clockformat <yourclock>_format = { + lots of fields for you to fill out (see below) + }; + + static cvt_<yourclock>() + ... + { + if (<I do not recognize my time code>) { + return CVT_NONE; + } else { + if (<conversion into clockformat is ok>) { + <set all necessary flags>; + return CVT_OK; + } else { + return CVT_FAIL|CVT_BADFMT; + } + } + + The struct clockformat is the interface to the rest of the parse + driver - it holds all information necessary for finding the + clock message and doing the appropriate time stamping. + +struct clockformat +{ + unsigned LONG (*convert)(); + /* conversion routine - your routine - cvt_<yourclock> */ + void (*syncevt)(); + /* routine for handling RS232 sync events (time stamps) - usually sync_simple */ + unsigned LONG (*syncpps)(); + /* PPS input routine - usually pps_simple */ + unsigned LONG (*synth)(); + /* time code synthesizer - usually not used - (LONG (*)())0 */ + void *data; + /* local parameters - any parameters/data/configuration info your conversion + routine might need */ + char *name; + /* clock format name - Name of the time code */ + unsigned short length; + /* maximum length of data packet for your clock format */ + unsigned LONG flags; + /* information for the parser what to look for */ + struct timeval timeout; + /* buffer restart after timeout (us) - some clocks preceede new data by + a longer period of silence - unsually not used */ + unsigned char startsym; + /* start symbol - character at the beginning of the clock data */ + unsigned char endsym; + /* end symbol - character at the end of the clock data */ + unsigned char syncsym; + /* sync symbol - character that is "on time" - where the time stamp should be taken */ +}; + + The flags: + F_START use startsym to find the beginning of the clock data + F_END use endsym to find the end of the clock data + SYNC_TIMEOUT packet restart after timeout in timeout field + SYNC_START packet start is sync event (time stamp at paket start) + SYNC_END packet end is sync event (time stamp at paket end) + SYNC_CHAR special character (syncsym) is sync event + SYNC_ONE PPS synchronize on 'ONE' transition + SYNC_ZERO PPS synchronize on 'ZERO' transition + SYNC_SYNTHESIZE generate intermediate time stamps (very special case!) + CVT_FIXEDONLY convert only in fixed configuration - (data format not + suitable for auto-configuration) + + + The above should have given you some hints on how to build a clk_*.c + file with the time code conversion. See the examples and pick a clock + closest to yours and tweak the code to match your clock. + + In order to make your clk_*.c file usable a reference to the clockformat + structure must be put into parse_conf.c. + +TTY setup and initialisation/configuration will be done in +xntpd/refclock_parse.c + +- Find out the exact tty settings for your clock (baud rate, parity, + stop bits, character size, ...) and note them in terms of + termio*.h c_cflag macros. + +- in xntpd/refclock_parse.c fill out a new the struct clockinfo element + (that allocates a new "IP" address - see comments) + (see all the other clocks for example) + struct clockinfo + { + U_LONG cl_flags; /* operation flags (io modes) */ + PARSE_F_NOPOLLONLY always do async io - read whenever input comes + PARSE_F_POLLONLY never do async io - only read when expecting data + PARSE_F_PPSPPS use loopfilter PPS code (CIOGETEV) + PARSE_F_PPSONSECOND PPS pulses are on second + usually flags stay 0 as they are used only for special setups + + void (*cl_poll)(); /* active poll routine */ + The routine to call when the clock needs data sent to it in order to + get a time code from the clock (e.g. Trimble clock) + int (*cl_init)(); /* active poll init routine */ + The routine to call for very special initializations. + void (*cl_end)(); /* active poll end routine */ + The routine to call to undo any special initialisation (free memory/timers) + void *cl_data; /* local data area for "poll" mechanism */ + local data for polling routines + u_fp cl_rootdelay; /* rootdelay */ + NTP rottdelay estimate (usually 0) + U_LONG cl_basedelay; /* current offset - unsigned l_fp fractional par + time (fraction) by which the RS232 time code is delayed from the actual time. + t */ + U_LONG cl_ppsdelay; /* current PPS offset - unsigned l_fp fractional + time (fraction) by which the PPS time stamp is delayed (usually 0) + part */ + char *cl_id; /* ID code (usually "DCF") */ + Refclock id - (max 4 chars) + char *cl_description; /* device name */ + Name of this device. + char *cl_format; /* fixed format */ + If the data format cann not ne detected automatically this is the name + as in clk_*.c clockformat. + u_char cl_type; /* clock type (ntp control) */ + Type if clock as in clock status word (ntp control messages) - usually 0 + U_LONG cl_maxunsync; /* time to trust oscillator after loosing synch + */ + seconds a clock can be trusted after loosing synchronisation. + + U_LONG cl_cflag; /* terminal io flags */ + U_LONG cl_iflag; /* terminal io flags */ + U_LONG cl_oflag; /* terminal io flags */ + U_LONG cl_lflag; /* terminal io flags */ + termio*.h tty modes. + } clockinfo[] = { + ...,<other clocks>,... + { < your parameters> }, + }; + + +Well, this is very sketchy, i know. But I hope it helps a little bit. +The best way is to look which clock comes closest to your and tweak that +code. +Two sorts of clocks are used with parse. Clocks that automatically send +their time code (once a second) do not need entries in the poll routines because +they send the data all the time. The second sort are the clocks that need a +command sent to them in order to reply with a time code (like the Trimble +clock). + +For questions: kardel@informatik.uni-erlangen.de. Please include +an exact description on how your clock works. (initialisation, +TTY modes, strings to be sent to it, responses received from the clock). + +Frank Kardel |
