docs/rdebug.adoc

   1 = Debugging Reference Clock Drivers
   2 include::include-html.ad[]
   3
   4 [cols="10%,90%",frame="none",grid="none",style="verse"]
   5 |==============================
   6 |image:pic/oz2.gif[]|
   7 {millshome}pictures.html[from 'The Wizard of Oz', L. Frank Baum]
   8
   9 Call the girls and they'll sweep your bugs.
  10
  11 |==============================
  12
  13 == Related Links
  14
  15 include::includes/refclock.adoc[]
  16 include::includes/install.adoc[]
  17
  18 '''''
  19
  20 The link:ntpq.html[+ntpq+] utility program
  21 can be used to debug reference clocks, either on the server itself or
  22 from another machine elsewhere in the network. The server is compiled,
  23 installed and started using the configuration file described in the
  24 link:ntpd.html[+ntpd+] page and its dependencies. If the clock appears
  25 in the +ntpq+ utility and +pe+ command, no errors have occurred and the
  26 daemon has started, opened the devices specified and waiting for peers
  27 and radios to come up. If not, the first thing to look for are error
  28 messages on the system log. These are usually due to improper
  29 configuration, missing links or multiple instances of the daemon.
  30
  31 It normally takes a minute or so for evidence to appear that the clock
  32 is running and the driver is operating correctly. The first indication
  33 is a nonzero value in the +reach+ column in the +pe+ billboard. If
  34 nothing appears after a few minutes, the next step is to be sure the
  35 RS232 messages, if used, are getting to and from the clock. The most
  36 reliable way to do this is with an RS232 tester and to look for data
  37 flashes as the driver polls the clock and/or as data arrive from the
  38 clock. Our experience is that the overwhelming fraction of problems
  39 occurring during installation are due to problems such as miswired
  40 connectors or improperly configured device links at this stage.
  41
  42 If RS232 messages are getting to and from the clock, the variables of
  43 interest can be inspected using the +ntpq+ program and various commands
  44 described on the documentation page. First, use the +pe+ and +as+
  45 commands to display billboards showing the peer configuration and
  46 association IDs for all peers, including the radio clock. The assigned
  47 clock address should appear in the +pe+ billboard and the association ID
  48 for it at the same relative line position in the +as+ billboard.
  49
  50 Additional information is available with the +rv+ and +clockvar+
  51 commands, which take as argument the association ID shown in the +as+
  52 billboard. The +rv+ command with no argument shows the system variables,
  53 while the +rv+ command with association ID argument shows the peer
  54 variables for the clock, as well as other peers of interest. The
  55 +clockvar+ command with argument shows the peer variables specific to
  56 reference clock peers, including the clock status, device name, last
  57 received timecode (if relevant), and various event counters. In
  58 addition, a subset of the driver options is included. The poll and
  59 error counters in the +clockvar+ billboard are useful debugging aids.
  60 The +poll+ counts the poll messages sent to the clock, while the
  61 +noreply+, +badformat+ and +baddate+ count various errors. Check the
  62 timecode to be sure it matches what the driver expects. This may require
  63 consulting the clock hardware reference manual, which is probably pretty
  64 dusty at this stage.
  65
  66 The +ntpq+ utility program can be used for detailed inspection of the
  67 clock driver status. The most useful are the +clockstat+ and +clkbug+
  68 commands described in the document page. While these commands permit
  69 getting quite personal with the particular driver involved, their use is
  70 seldom necessary, unless an implementation bug shows up. If all else
  71 fails, turn on the debugging trace using two +-d+ flags in the +ntpd+
  72 startup command line. Most drivers will dump status at every received
  73 message in this case. While the displayed trace can be intimidating,
  74 this provides the most detailed and revealing indicator of how the
  75 driver and clock are performing and where bugs might lurk.
  76
  77 Most drivers write a message to the +clockstats+ file as each timecode
  78 or surrogate is received from the radio clock. By convention, this is
  79 the last ASCII timecode (or ASCII gloss of a binary-coded one) received
  80 from the radio clock. This file is managed by the +filegen+ facility
  81 described in the +ntpd+ page and requires specific commands in the
  82 configuration file. This forms a highly useful record to discover
  83 anomalies during regular operation of the clock. The scripts included in
  84 the +./scripts/stats+ directory can be run from a +cron+ job to collect
  85 and summarize these data on a daily or weekly basis. The summary files
  86 have proven inspirational to detect infrequent misbehavior due to clock
  87 implementation bugs in some radios.
  88
  89 '''''
  90
  91 include::includes/footer.adoc[]