[Git][NTPsec/ntpsec][master] 4 commits: Revert "Change filename for consistency, this was causing a broken link"
Eric S. Raymond
gitlab at mg.gitlab.com
Tue Nov 29 15:48:08 UTC 2016
Eric S. Raymond pushed to branch master at NTPsec / ntpsec
Commits:
be6f3dad by Sanjeev Gupta at 2016-11-29T21:53:06+08:00
Revert "Change filename for consistency, this was causing a broken link"
This reverts commit 40ddb8ead332be7f9163a7b4f689f3fde7e1da2d.
While modifying the filename, I changed the extension
from .txt to .html
- - - - -
b86bae29 by Sanjeev Gupta at 2016-11-29T21:56:47+08:00
Do 40ddb8ead332be7f9163a7b4f689f3fde7e1da2d properly
I goofed up with filenames, this reverts and repatches
the filenames for the refclock includes.
- - - - -
fc9c27dc by Sanjeev Gupta at 2016-11-29T22:10:51+08:00
Force update on NTPsec website
- - - - -
d3494e90 by Sanjeev Gupta at 2016-11-29T22:15:54+08:00
"Force update on NTPsec website"
Some docs were updated in mid-Nov, but not rebuilt
on the www host. Touching them again to force a rebuild
- - - - -
3 changed files:
- + docs/driver_howto.txt
- docs/includes/refclock.txt
- docs/rdebug.txt
Changes:
=====================================
docs/driver_howto.txt
=====================================
--- /dev/null
+++ b/docs/driver_howto.txt
@@ -0,0 +1,255 @@
+= How to Write a Reference Clock Driver =
+
+[cols="10%,90%",frame="none",grid="none",style="verse"]
+|==============================
+|image:pic/pogo4.gif[]|
+http://www.eecis.udel.edu/%7emills/pictures.html[from 'Pogo', Walt Kelly]
+
+You need a little magic.
+
+|==============================
+
+== Related Links ==
+
+include::includes/misc.txt[]
+
+== Table of Contents ==
+
+* link:#desc[Description]
+* link:#file[Files Which Need to be Changed]
+* link:#intf[Interface Routine Overview]
+* link:#pps[Pulse-per-Second Interface]
+
+'''''
+
+== When Not to Write a Driver ==
+
+If the device you are trying to support is an exotic GPS, you should
+probably not write an +ntpd+ driver for it. Instead, check to see if
+it is already supported by {GPSD}, a project with which NTPsec
+cooperates closely. The GPSD people are specialists in managing GPSes
+and better at it than we are, supporting a much broader range of
+devices, and GPSD is designed to feed clock samples to +ntpd+ from any
+of them. If you need to write a driver for a GPS, they'll take it and
+should have it.
+
+If you have a non-GPS time source (like a time radio or GPSDO) that
+you want to support, consider link:generic_howto.html[writing a mode
+for it in the generic driver] rather than a full driver of its own;
+this will be easier. The generic driver is so called because it
+factors out a lot of I/O and housekeeping code common to all drivers,
+allowing you support a new device type by writing only a parser for
+its sentences.
+
+[[desc]]
+== Structure of a Driver ==
+
+NTP reference clock support maintains the fiction that the clock is
+actually an ordinary server in the NTP tradition, but operating at a
+synthetic stratum of zero. The entire suite of algorithms filter the
+received data and select the best sources to correct the system clock.
+No packets are exchanged with a reference clock; however, the transmit,
+receive and packet procedures are replaced with code to simulate them.
+
+The driver assumes three timescales: standard time maintained by a
+distant laboratory such as USNO or NIST, reference time maintained by
+the external radio and the system time maintained by NTP. The radio
+synchronizes reference time via radio, satellite or modem. As the
+transmission means may not always be reliable, most radios continue to
+provide clock updates for some time after signal loss using an internal
+reference oscillator. In such cases the radio may or may not reveal the
+time since last synchronized or the estimated time error.
+
+All three timescales run only in Coordinated Universal Time (UTC) and
+are not adjusted for local timezone or standard/daylight time. The local
+timezone, standard/daylight indicator and year, if provided, are
+ignored. However, it is important to determine whether a leap second is
+to be inserted in the UTC timescale in the near future so NTP can insert
+it in the system timescale at the appropriate epoch.
+
+The interface routines in the +ntp_refclock.c+ source file call the
+following driver routines via a transfer vector:
+
++startup+::
+ The association has just been mobilized. The driver may allocate a
+ private structure and open the device(s) required.
++shutdown+::
+ The association is about to be demobilized. The driver should close
+ all device(s) and free private structures.
++receive+::
+ A timecode string is ready for retrieval using the +refclock_gtlin()+
+ or +refclock_gtraw()+ routines and provide clock updates.
++poll+::
+ Called at poll timeout, by default 64 s. Ordinarily, the driver will
+ send a poll sequence to the radio as required.
++timer+::
+ Called once per second. This can be used for housekeeping functions.
+ In the case with pulse-per-second (PPS) signals, this can be used to
+ process the signals and provide clock updates.
+
+The receive routine retrieves a timecode string via serial or parallel
+port, PPS signal or other means. It decodes the timecode in days, hours,
+minutes, seconds and nanoseconds and checks for errors. It provides
+these data along with the on-time timestamp to the +refclock_process+
+routine, which saves the computed offset in a 60-sample circular buffer.
+On occasion, either by timeout, sample count or call to the poll
+routine, the driver calls +refclock_receive+ to process the circular
+buffer samples and update the system clock.
+
+The best way to understand how the clock drivers work is to study one of
+the drivers already implemented, such as +refclock_spectracom.c+. The
+main interface is the +refclockproc+ structure, which contains for most
+drivers the decoded timecode, on-time timestamp, reference timestamp,
+exception reports and statistics tallies, etc. The support routines are
+passed a pointer to the +peer+ structure, which contains a pointer to
+the +refclockproc+ structure, which in turn contains a pointer to the
+unit structure, if used. For legacy purposes, a table
++typeunit[type][unit]+ contains the peer structure pointer for each
+configured clock type and unit. This structure should not be used for
+new implementations.
+
+Radio and modem reference clocks by convention have addresses of the
+form +127.127.t.u+, where _t_ is the clock type and _u_ in the range 0-3
+is used to distinguish multiple instances of clocks of the same type.
+These addresses used to be exposed as part of the refclock
+configuration syntax, but are no longer. Nothing in ntpd now actually
+requires this form of address for clocks, but it is still generated
+so as not to hand surprises to legacy +ntpq+ instances that still make
+the assumption.
+
+Most clocks require a serial or parallel port or special bus peripheral.
+The particular device is normally specified by adding a soft link
++/dev/deviceu+ to the particular hardware device.
+
+By convention, reference clock drivers are named in the form
++refclock_xxxx.c+, where +xxxx+ is a unique string. Each driver is
+assigned a unique long-form driver name, short-form driver name and
+device name. The existing assignments are in the
+link:refclock.html[Reference Clock Drivers] page and its dependencies.
+
+== Conventions, Fudge Factors and Flags ==
+
+Most drivers support manual or automatic calibration for systematic
+offset bias using values encoded in the +refclock+ configuration command.
+By convention, the +time1+ value defines the calibration offset in
+seconds. For those drivers that support statistics collection using the
++filegen+ utility and the +clockstats+ file, the +flag4+ switch enables
+the utility.
+
+If the calibration feature has been enabled, the +flag1+ switch is set
+and the PPS signal is actively disciplining the system time, the +time1+
+value is automatically adjusted to maintain a residual offset of zero.
+Once the its value has stabilized, the value can be inserted in the
+configuration file and the calibration feature disabled.
+
+[[file]]
+== Files Which Need to be Changed ==
+
+When a new reference clock driver is installed, the following files need
+to be edited. Note that changes are also necessary to properly integrate
+the driver in the configuration and makefile scripts, but these are
+decidedly beyond the scope of this page.
+
++./include/ntp.h+::
+ The reference clock type defines are used in many places. Each driver
+ is assigned a unique type number. Unused numbers are clearly marked in
+ the list. A unique +REFCLK_xxxx+ identification code should be
+ recorded in the list opposite its assigned type number.
++./libntp/clocktypes.c+::
+ The +./libntp/clktype+ array is used by certain display functions. A
+ unique short-form name of the driver should be entered together with
+ its assigned identification code.
++./ntpd/ntp_control.c+::
+ The +clocktypes+ array is used for certain control message displays
+ functions. It should be initialized with the reference clock class
+ assigned to the driver, as per the NTP specification RFC-1305. See the
+ +./include/ntp_control.h+ header file for the assigned classes.
++./ntpd/refclock_conf.c+::
+ This file contains a list of external structure definitions which are
+ conditionally defined. A new set of entries should be installed
+ similar to those already in the table. The +refclock_conf+ array is a
+ set of pointers to transfer vectors in the individual drivers. The
+ external name of the transfer vector should be initialized in
+ correspondence with the type number.
+
+[[intf]]
+== Interface Routine Overview ==
+
++refclock_newpeer+ - initialize and start a reference clock.::
+ This routine allocates and initializes the interface structure which
+ supports a reference clock in the form of an ordinary NTP peer. A
+ driver-specific support routine completes the initialization, if used.
+ Default peer variables which identify the clock and establish its
+ reference ID and stratum are set here. It returns one if success and
+ zero if the clock address is invalid or already running, insufficient
+ resources are available or the driver declares a bum rap.
++refclock_unpeer+ - shut down a clock::
+ This routine is used to shut down a clock and return its resources to
+ the system.
++refclock_transmit+ - simulate the transmit procedure::
+ This routine implements the NTP transmit procedure for a reference
+ clock. This provides a mechanism to call the driver at the NTP poll
+ interval, as well as provides a reachability mechanism to detect a
+ broken radio or other madness.
++refclock_process+ - insert a sample in the circular buffer::
+ This routine saves the offset computed from the on-time timestamp and
+ the days, hours, minutes, seconds and nanoseconds in the circular
+ buffer. Note that no provision is included for the year, as provided
+ by some (but not all) radio clocks. Ordinarily, the year is implicit
+ in the Unix file system and hardware/software clock support, so this
+ is ordinarily not a problem.
++refclock_receive+ - simulate the receive and packet procedures::
+ This routine simulates the NTP receive and packet procedures for a
+ reference clock. This provides a mechanism in which the ordinary NTP
+ filter, selection and combining algorithms can be used to suppress
+ misbehaving radios and to mitigate between them when more than one is
+ available for backup.
++refclock_gtraw+, +refclock_gtlin+ - read the buffer and on-time timestamp::
+ These routines return the data received from the clock and the on-time
+ timestamp. The +refclock_gtraw+ routine returns a batch of one or more
+ characters returned by the Unix terminal routines in raw mode. The
+ +refclock_gtlin+ routine removes the parity bit and control characters
+ and returns all the characters up to and including the line
+ terminator. Either routine returns the number of characters delivered.
++refclock_open+ - open a serial port for reference clock::
+ This routine opens a serial port for I/O and sets default options. It
+ returns the file descriptor if success and zero if failure.
++refclock_ioctl+ - set serial port control functions::
+ This routine attempts to hide the internal, system-specific details of
+ serial ports. It can handle POSIX (+termios+), SYSV (+termio+) and BSD
+ (+sgtty+) interfaces with varying degrees of success. The routine
+ returns one if success and zero if failure.
++refclock_ppsapi+::
+ This routine initializes the Pulse-per-Second interface (see below).
++refclock_pps+::
+ This routine is called once per second to read the latest PPS offset
+ and save it in the circular buffer (see below).
+
+[[pps]]
+== Pulse-per-Second Interface ==
+
+When the Pulse-per-Second Application Interface (RFC 2783) is present, a
+compact PPS interface is available to all drivers. See the
+link:prefer.html[Mitigation Rules and the Prefer Peer] page for further
+information. To use this interface, include the +timeppps.h+ and
++refclock_pps.h+ header files and define the +refclock_ppsctl+ structure
+in the driver private storage. The +timepps.h+ file is specific to each
+operating system and may not be available for some systems.
+
+To use the interface, call +refclock_ppsapi+ from the startup routine
+passing the device file descriptor and +refclock_ppsctl+ structure
+pointer. Then, call +refclock_pps+ from the timer routine passing the
+association pointer and +refclock_ppsctl+ structure pointer. See the
++refclock_pps.c+ file for examples and calling sequences. If the PPS
+signal is valid, the offset sample will be save in the circular buffer
+and a bit set in the association flags word indicating the sample is
+valid and the driver an be selected as a PPS peer. If this bit is set
+when the poll routine is called, the driver calls the
++refclock_receive+ routine to process the samples in the circular
+buffer and update the system clock.
+
+'''''
+
+image:pic/pogo1a.gif[]
+
+include::includes/footer.txt[]
=====================================
docs/includes/refclock.txt
=====================================
--- a/docs/includes/refclock.txt
+++ b/docs/includes/refclock.txt
@@ -1,6 +1,6 @@
=== Reference Clock Support ===
* link:extern.html[External Clock Discipline and the Local Clock Driver]
-* link:driver_howto.html[How to Write a Reference Clock Driver]
+* link:driver_howto.html[How to Write a Reference Clock Driver]
* link:generic_howto.html[How to build new generic clocks]
* link:refclock.html[Reference Clock Drivers]
* link:sitemap.html[Site Map]
=====================================
docs/rdebug.txt
=====================================
--- a/docs/rdebug.txt
+++ b/docs/rdebug.txt
@@ -11,7 +11,7 @@ Call the girls and they'll sweep your bugs.
== Related Links ==
-include::includes/refclock.txt[]
+include::includes/refclock.txt[]
include::includes/install.txt[]
'''''
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/68bc58be0060b5c055085187b2df3a70f22d6210...d3494e906048a8e5882be0f63b44a6093c01105f
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ntpsec.org/pipermail/vc/attachments/20161129/009c3983/attachment.html>
More information about the vc
mailing list