[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

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


--- /dev/null
+++ b/docs/driver_howto.txt
@@ -0,0 +1,255 @@
+= How to Write a Reference Clock Driver =
+http://www.eecis.udel.edu/%7emills/pictures.html[from 'Pogo', Walt Kelly]
+You need a little magic.
+== Related Links ==
+== 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.
+== 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:
+  The association has just been mobilized. The driver may allocate a
+  private structure and open the device(s) required.
+  The association is about to be demobilized. The driver should close
+  all device(s) and free private structures.
+  A timecode string is ready for retrieval using the +refclock_gtlin()+
+  or +refclock_gtraw()+ routines and provide clock updates.
+  Called at poll timeout, by default 64 s. Ordinarily, the driver will
+  send a poll sequence to the radio as required.
+  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.
+== 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.
+  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.
+  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.
+  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.
+  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.
+== 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.
+  This routine initializes the Pulse-per-Second interface (see below).
+  This routine is called once per second to read the latest PPS offset
+  and save it in the circular buffer (see below).
+== 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.

--- 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]

--- a/docs/rdebug.txt
+++ b/docs/rdebug.txt
@@ -11,7 +11,7 @@ Call the girls and they'll sweep your bugs.
 == Related Links ==

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