[Git][NTPsec/ntpsec][master] Better documentation on how to write drivers, and when not to.
Eric S. Raymond
gitlab at mg.gitlab.com
Mon Jun 27 07:44:02 UTC 2016
Eric S. Raymond pushed to branch master at NTPsec / ntpsec
Commits:
37c0763c by Eric S. Raymond at 2016-06-27T03:43:08-04:00
Better documentation on how to write drivers, and when not to.
- - - - -
7 changed files:
- docs/asciidoc.conf
- docs/howto.txt → docs/driver-howto.txt
- docs/driver_generic.txt
- docs/driver_pps.txt
- docs/parsenew.txt → docs/generic_howto.txt
- docs/includes/refclock.txt
- docs/refclock.txt
Changes:
=====================================
docs/asciidoc.conf
=====================================
--- a/docs/asciidoc.conf
+++ b/docs/asciidoc.conf
@@ -12,6 +12,7 @@ project-contact=http://www.ntpsec.org/channels.html
project-security-list=security at ntpsec.org
project-bug-list=bugs at ntpsec.org
millshome=http://www.eecis.udel.edu/~mills/
+GPSD=http://www.catb.org/gpsd/
ntp=ntp
ntpd=ntpd
ntpdig=ntpdig
=====================================
docs/howto.txt → docs/driver-howto.txt
=====================================
--- a/docs/howto.txt
+++ b/docs/driver-howto.txt
@@ -22,8 +22,27 @@ include::includes/misc.txt[]
'''''
+== 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
+{project-shortname} 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]]
-== Description ==
+== 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
@@ -93,7 +112,10 @@ 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.
+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
@@ -101,12 +123,9 @@ The particular device is normally specified by adding a soft link
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 type number, long-form driver name, short-form driver
-name and device name. The existing assignments are in the
+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.
-All drivers supported by the particular hardware and operating system
-are automatically detected in the autoconfigure phase and conditionally
-compiled.
== Conventions, Fudge Factors and Flags ==
=====================================
docs/driver_generic.txt
=====================================
--- a/docs/driver_generic.txt
+++ b/docs/driver_generic.txt
@@ -2,7 +2,7 @@
== Name ==
-refclock_parse - multidevice parse driver for generic time radios and GPSDOs.
+refclock_generic - multidevice parse driver for generic time radios and GPSDOs.
== Synopsis ==
@@ -14,8 +14,9 @@ PPS device: /dev/refclockpps-'u'; alternate PPS device
== Description ==
-The PARSE driver supports 25 different clock
-types/configurations. PARSE is actually a multi-clock driver.
+The generic driver supports many different clock
+types/configurations by pugging type-specific packet-parsing
+routine into a generic drive framework.
Note that some of these modes below are to support equipment that
has not been commercially available for a long time, and may be
@@ -27,7 +28,7 @@ The actual receiver status is mapped into various synchronization states
generally used by receivers. The driver is configured to interpret the
time codes of Meinberg DCF77 AM receivers, DCF77 FM receivers, Meinberg
GPS16x/17x receivers, Trimble SV6 GPS, ELV DCF7000, Schmid, Wharton 400A
-and low cost receivers.
+and various low-cost receivers.
The reference clock support in NTP contains the necessary configuration
tables for those receivers. In addition to supporting several different
@@ -72,7 +73,7 @@ refclock_ppstime::
== Supported Devices ==
-Currently, twenty-five clock types are supported by the PARSE driver and
+Currently, twenty-five clock types are supported by the GENERIC driver and
up to four (devices /dev/refclock-0 - /dev/refclock-3) of these clocks
may be operational at any one time.
@@ -292,7 +293,7 @@ See comment from mode 20 clock.
*http://www.selinc.com/[Schweitzer Engineering Laboratories]*
Actual data formats and setup requirements of the various clocks can be
-found in link:parsedata.html[NTP PARSE clock data formats].
+found in link:parsedata.html[NTP GENERIC clock data formats].
== Operation ==
@@ -452,11 +453,11 @@ screen width and looks similar to:
Delete next leap second instead of adding it. (You'll need to wait a
bit for that to happen 8-)
-== Making your own PARSE clocks ==
+== Making your own generic clocks ==
-The parse clock mechanism deviates from the way other NTP reference
-clocks work. For a short description of how to build parse reference
-clocks, see link:parsenew.html[making PARSE clocks].
+The generic clock mechanism deviates from the way other NTP reference
+clocks work. For a short description of how to build generic reference
+clocks, see link:generic_howto.html[making generic clocks].
Additional Information
=====================================
docs/driver_pps.txt
=====================================
--- a/docs/driver_pps.txt
+++ b/docs/driver_pps.txt
@@ -9,13 +9,6 @@ Driver ID: PPS
Serial or Parallel Port: /dev/pps__u__
Requires: PPSAPI signal interface for PPS signal processing.
-Note: This driver supersedes an older one of the same name. The older
-driver operated with several somewhat archaic signal interface
-devices, required intricate configuration and was poorly
-documented. This driver requires the Pulse per Second API
-(PPSAPI)^1^. Note also that the +pps+ configuration
-command has been obsoleted by this driver.
-
== Description ==
This driver furnishes an interface for the pulse-per-second (PPS) signal
=====================================
docs/parsenew.txt → docs/generic_howto.txt
=====================================
--- a/docs/parsenew.txt
+++ b/docs/generic_howto.txt
@@ -1,14 +1,14 @@
-= How to build new PARSE clocks =
+= How to build new GENERIC clocks =
Here is an attempt to sketch out what you need to do in order to add
-another clock to the parse driver: Currently the implementation is being
+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:
* Does the system you want the clock connect to have the include file
-termios.h? (You need that for the parse driver)
+termios.h? (You need that for the generic driver)
What to do:
@@ -97,7 +97,7 @@ them for examples. The basic structure is:
}
-----------------------------------------------------
+
-The struct clockformat is the interface to the rest of the parse driver
+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.
+
@@ -131,11 +131,11 @@ 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
-ntpd/refclock_parse.c.
+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_parse.c fill out a new the struct clockinfo element
+* 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)
+
=====================================
docs/includes/refclock.txt
=====================================
--- a/docs/includes/refclock.txt
+++ b/docs/includes/refclock.txt
@@ -1,7 +1,7 @@
=== Reference Clock Support ===
* link:extern.html[External Clock Discipline and the Local Clock Driver]
-* link:howto.html[How to Write a Reference Clock Driver]
-* link:howto.html[How to build new PARSE clocks]
+* 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/refclock.txt
=====================================
--- a/docs/refclock.txt
+++ b/docs/refclock.txt
@@ -30,7 +30,7 @@ A general description of the reference clock support is on this
page. Additional information about each reference clock driver can be
found via links from here. Additional information is on the
link:rdebug.html[Debugging Hints for Reference Clock Drivers] and
-link:howto.html[How To Write a Reference Clock Driver] pages.
+link:driver_howto.html[How To Write a Reference Clock Driver] pages.
Information on how to support pulse-per-second (PPS) signals produced by
some devices is on the link:pps.html[Pulse-per-second (PPS) Signal
Interfacing] page. All reference clock drivers require that the
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/commit/37c0763cbdd0856b71f8e4c60006fd167a6e5c1e
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ntpsec.org/pipermail/vc/attachments/20160627/f5278c23/attachment.html>
More information about the vc
mailing list