[Git][NTPsec/ntpsec][master] 2 commits: Markup fixes for generic clock driver HOWTO.
Eric S. Raymond
gitlab at mg.gitlab.com
Tue Sep 19 23:22:11 UTC 2017
Eric S. Raymond pushed to branch master at NTPsec / ntpsec
Commits:
89c5d129 by Eric S. Raymond at 2017-09-19T15:43:07Z
Markup fixes for generic clock driver HOWTO.
- - - - -
bc4aa35c by Eric S. Raymond at 2017-09-19T23:21:46Z
In clock_sample(), prevent jitter from zeroing if all samples are bad.
- - - - -
2 changed files:
- docs/generic_howto.txt
- ntpd/ntp_proto.c
Changes:
=====================================
docs/generic_howto.txt
=====================================
--- a/docs/generic_howto.txt
+++ b/docs/generic_howto.txt
@@ -5,7 +5,7 @@ another clock to the generic driver: Currently the implementation is being
cleaned up - so not all information in here is completely correct. Refer
to the included code where in doubt.
-Prerequisites:
+== Prerequisites ==
* Does the system you want the clock connect to have the include file
termios.h? (You need that for the generic driver)
@@ -14,15 +14,16 @@ What to do:
Make a conversion module (libparse/clk_*.c)
-1. What is the time code format ?
-* find year, month, day, hour, minute, second, status (synchronised or
+== What is 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 */
- {
+struct clocktime /* clock time broken up from time code */
+{
long day;
long month;
long year;
@@ -33,49 +34,50 @@ clocktime:
long utcoffset; /* in seconds */
time_t utcoffset; /* true utc time instead of date/time */
long flags; /* current clock status */
- };
+};
-------------------------------------------------------------------------------
-+
+
Conversion is usually simple and straightforward. 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 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)
----------------------------------------------------------------------------------
-+
+
+|-------------------------------------------------------------------------------
+| 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 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)
-----------------------------------------------------------------------------
-+
+
+|----------------------------------------------------------------------------
+| 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)
@@ -95,12 +97,12 @@ them for examples. The basic structure is:
}
}
-----------------------------------------------------
-+
-The struct clockformat is the interface to the rest of the generic driver
-- it holds all information necessary for finding the clock message and
-doing the appropriate time stamping.
-+
-----------------------------------------------------------------------------------
+
+The struct clockformat is the interface to the rest of the generic
+driver - it holds all information necessary for finding the clock
+message and doing the appropriate time stamping.
+
+--------------------------------------------------------------------------------
struct clockformat
{
unsigned long (*input)();
@@ -120,92 +122,95 @@ struct clockformat
unsigned long flags;
/* information for the parser what to look for */
};
-----------------------------------------------------------------------------------
-+
+--------------------------------------------------------------------------------
+
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.
-2. TTY setup and initialization/configuration will be done in
+== Driver initialization ==
+
+TTY setup and initialization/configuration will be done in
ntpd/refclock_generic.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 ntpd/refclock_generic.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
- {
- unsigned long cl_flags; /* operation flags (io modes) */
+
+--------------------------------------------------------------------------------
+struct clockinfo {
+ unsigned long cl_flags; /* operation flags (io modes) */
PARSE_F_PPSPPS use loopfilter PPS code
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 */
+ 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 */
+ int (*cl_init)(); /* active poll init routine */
The routine to call for very special initializations.
- void (*cl_event)(); /* special event handling (e.g. reset clock) */
+ void (*cl_event)(); /* special event handling (e.g. reset clock) */
What to do, when an event happens - used to re-initialize clocks on timeout.
- void (*cl_end)(); /* active poll end routine */
+ void (*cl_end)(); /* active poll end routine */
The routine to call to undo any special initialization (free memory/timers)
- void *cl_data; /* local data area for "poll" mechanism */
+ void *cl_data; /* local data area for "poll" mechanism */
local data for polling routines
- u_fp cl_rootdelay; /* rootdelay */
+ u_fp cl_rootdelay; /* rootdelay */
NTP rootdelay estimate (usually 0)
- unsigned long cl_basedelay; /* current offset - unsigned l_fp
- fractional part (fraction) by
- which the RS232 time code is
- delayed from the actual time. */
+ unsigned long cl_basedelay; /* current offset - unsigned l_fp
+ fractional part (fraction) by
+ which the RS232 time code is
+ delayed from the actual time. */
- unsigned long cl_ppsdelay; /* current PPS offset - unsigned l_fp fractional
- time (fraction) by which the PPS time stamp is delayed (usually 0)
- part */
+ unsigned long cl_ppsdelay; /* current PPS offset - unsigned
+ l_fp fractional time (fraction)
+ by which the PPS time stamp is
+ delayed (usually 0) */
- char *cl_id; /* ID code (usually "DCF") */
+ char *cl_id; /* ID code */
Refclock id - (max 4 chars)
- char *cl_description; /* device name */
+ char *cl_description; /* device name */
Name of this device.
- char *cl_format; /* fixed format */
+ char *cl_format; /* fixed format */
If the data format cann not ne detected automatically this is the name
- as in clk_*.c clockformat.
+ as in clk_*.c clockformat.
- unsigned char cl_type; /* clock type (ntp control) */
+ unsigned char cl_type; /* clock type (ntp control) */
Type if clock as in clock status word (ntp control messages) - usually 0
- unsigned long cl_maxunsync; /* time to trust oscillator after losing synch
- */
- seconds a clock can be trusted after losing synchronisation.
-
- unsigned long cl_speed; /* terminal input & output baudrate */
- unsigned long cl_cflag; /* terminal io flags */
- unsigned long cl_iflag; /* terminal io flags */
- unsigned long cl_oflag; /* terminal io flags */
- unsigned long cl_lflag; /* terminal io flags */
- termio*.h tty modes.
-
- unsigned long cl_samples; /* samples for median filter */
- unsigned long cl_keep; /* samples for median filter to keep */
+ unsigned long cl_maxunsync; /* time to trust oscillator after
+ losing synch -- seconds a clock
+ can be trusted after losing
+ synchronisation. */
+ unsigned long cl_speed; /* terminal input & output baudrate */
+ unsigned long cl_cflag; /* terminal io flags */
+ unsigned long cl_iflag; /* terminal io flags */
+ unsigned long cl_oflag; /* terminal io flags */
+ unsigned long cl_lflag; /* terminal io flags */
+
+ unsigned long cl_samples; /* samples for median filter */
+ unsigned long cl_keep; /* samples for median filter to keep */
median filter parameters - smoothing and rejection of bad samples
} 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 yours and tweak that
=====================================
ntpd/ntp_proto.c
=====================================
--- a/ntpd/ntp_proto.c
+++ b/ntpd/ntp_proto.c
@@ -1397,7 +1397,7 @@ clock_filter(
double dst[NTP_SHIFT]; /* distance vector */
int ord[NTP_SHIFT]; /* index vector */
int i, j, k, m;
- double dtemp, etemp;
+ double dtemp, etemp, jtemp;
char tbuf[80];
/*
@@ -1489,14 +1489,14 @@ clock_filter(
* to 1.0. The jitter is the RMS differences relative to the
* lowest delay sample.
*/
- peer->disp = peer->jitter = 0;
+ peer->disp = jtemp = 0;
k = ord[0];
for (i = NTP_SHIFT - 1; i >= 0; i--) {
j = ord[i];
peer->disp = NTP_FWEIGHT * (peer->disp +
peer->filter_disp[j]);
if (i < m)
- peer->jitter += DIFF(peer->filter_offset[j],
+ jtemp += DIFF(peer->filter_offset[j],
peer->filter_offset[k]);
}
@@ -1513,6 +1513,7 @@ clock_filter(
etemp = fabs(peer->offset - peer->filter_offset[k]);
peer->offset = peer->filter_offset[k];
peer->delay = peer->filter_delay[k];
+ peer->jitter = jtemp;
if (m > 1)
peer->jitter /= m - 1;
peer->jitter = SQRT(peer->jitter);
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/38662175a00b3c7d40415cdbcf7439c4696c76b3...bc4aa35c297740d455c4c6ca233d1cc0db73bf56
---
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/38662175a00b3c7d40415cdbcf7439c4696c76b3...bc4aa35c297740d455c4c6ca233d1cc0db73bf56
You're receiving this email because of your account on gitlab.com.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ntpsec.org/pipermail/vc/attachments/20170919/3c6d24ca/attachment.html>
More information about the vc
mailing list