<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
<html><head><title>
Debugging Hints for Reference Clock Drivers
</title></head><body><h3>
Debugging Hints for Reference Clock Drivers
</h3><hr>

<p>The <a href = "ntpq.html"> <code>ntpq</code></a> and <a href =
"xntpdc.html"> <code>xntpdc</code> </a>utility programs can be used to
debug reference clocks, either on the server itself or from another
machine elsewhere in the network. The server is compiled, installed and
started using the command-line switches described in the <a href =
"xntpd.html"> <code>xntpd</code> </a> page. The first thing to look for
are error messages on the system log. If none occur, the daemon has
started, opened the devices specified and waiting for peers and radios
to come up.

<p>The next step is to be sure the RS232 messages, if used, are getting
to and from the clock. The most reliable way to do this is with an RS232
tester and to look for data flashes as the driver polls the clock and/or
as data arrive from the clock. Our experience is that the overwhelming
fraction of problems occurring during installation are due to problems
such as miswired connectors or improperly configured device links at
this stage.

<p>If RS232 messages are getting to and from the clock, the variables of
interest can be inspected using the <code>ntpq</code> program and
various commands described on the documentation page. First, use the
<code>pe</code> and <code>as</code> commands to display billboards
showing the peer configuration and association IDs for all peers,
including the radio clock peers. The assigned clock address should
appear in the <code>pe</code> billboard and the association ID for it at
the same relative line position in the <code>as</code> billboard. If
things are operating correctly, after a minute or two samples should
show up in the <code>pe</code> display line for the clock.

<p>Additional information is available with the <code>rv</code> and
<code>clockvar</code> commands, which take as argument the association
ID shown in the <code>as</code> billboard. The <code>rv</code> command
with no argument shows the system variables, while the <code>rv</code>
command with association ID argument shows the peer variables for the
clock, as well as any other peers of interest. The <code>clockvar</code>
command with argument shows the peer variables specific to reference
clock peers, including the clock status, device name, last received
timecode (if relevant), and various event counters. In addition, a
subset of the <code>fudge</code> parameters is included.

<p>The <code>xntpdc</code> utility program can be used for detailed
inspection of the clock driver status. The most useful are the
<code>clockstat</code> and <code>clkbug</code> commands described in the
document page. While these commands permit getting quite personal with
the particular driver involved, their use is seldom necessary, unless an
implementation bug shows up.

<p>Most drivers write a message to the <code>clockstats</code> file as
each timecode or surrogate is received from the radio clock. By
convention, this is the last ASCII timecode (or ASCII gloss of a binary-
coded one) received from the radio clock. This file is managed by the
<code>filegen</code> facility described in the <code>xntpd</code> page
and requires specific commands in the configuration file. This forms a
highly useful record to discover anomalies during regular operation of
the clock. The scripts included in the <code>./scripts/stats</code>
directory can be run from a <code>cron</code> job to collect and
summarize these data on a daily or weekly basis. The summary files have
proven invaluable to detect infrequent misbehavior due to clock
implementation bugs in some radios.
<hr><address>David L. Mills (mills@udel.edu)</address></body></html>
