contrib/ntp/html/drivers/driver28.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2
   3 <html>
   4
   5     <head>
   6         <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   7         <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
   8         <title>Shared Memory Driver</title>
   9         <link href="scripts/style.css" type="text/css" rel="stylesheet">
  10         <style type="text/css">
  11           table.dlstable { font-size:85%; }
  12           td.ttf{ font-family:Courier; font-weight:bold; }
  13         </style>
  14     </head>
  15
  16     <body>
  17         <h3>Shared Memory Driver</h3>
  18 <p>Last update:
  19   <!-- #BeginDate format:En2m -->8-Aug-2014  19:17<!-- #EndDate -->
  20   UTC</p>
  21         <hr>
  22         <h4>Synopsis</h4>
  23         <p>Address: 127.127.28.<i>u</i><br>
  24             Reference ID: <tt>SHM</tt><br>
  25             Driver ID: <tt>SHM</tt></p>
  26
  27         <h4>Description</h4>
  28         <p>This driver receives its reference clock info from a shared
  29         memory-segment. The shared memory-segment is created with owner-only
  30         access by default, unless otherwise requested by the mode word for units
  31         &ge;2. Units 0 and 1 are always created with owner-only access for
  32         backward compatibility.
  33         </p>
  34
  35
  36         <h4>Structure of shared memory-segment</h4>
  37         <pre>struct shmTime {
  38         int    mode; /* 0 - if valid is set:
  39                       *       use values,
  40                       *       clear valid
  41                       * 1 - if valid is set:
  42                       *       if count before and after read of data is equal:
  43                       *         use values
  44                       *       clear valid
  45                       */
  46         volatile int    count;
  47         time_t          clockTimeStampSec;
  48         int             clockTimeStampUSec;
  49         time_t          receiveTimeStampSec;
  50         int             receiveTimeStampUSec;
  51         int             leap;
  52         int             precision;
  53         int             nsamples;
  54         volatile int    valid;
  55         unsigned        clockTimeStampNSec;     /* Unsigned ns timestamps */
  56         unsigned        receiveTimeStampNSec;   /* Unsigned ns timestamps */
  57         int             dummy[8];
  58 };</pre>
  59
  60         <h4>Operation mode=0</h4>
  61         <p>Each second, the value of <code>valid</code> of the shared memory-segment is checked:</p>
  62         <p>If set, the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are passed to <i>NTPD</i>, and <code>valid</code> is cleared and <code>count</code> is bumped.</p>
  63         <p>If not set, <code>count</code> is bumped.</p>
  64         <h4>Operation mode=1</h4>
  65         <p>Each second, <code>valid</code> in the shared memory-segment is checked:</p>
  66         <p>If set, the <code>count</code> field of the record is remembered, and the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are read. Then, the remembered <code>count</code> is compared to current value of <code>count</code> now in the record. If both are equal, the values read from the record are passed to <i>NTPD</i>. If they differ, another process has modified the record while it was read out (was not able to produce this case), and failure is reported to <i>NTPD</i>. The <code>valid</code> flag is cleared and <code>count</code> is bumped.</p>
  67         <p>If not set, <code>count</code> is bumped</p>
  68
  69 <h4>Mode-independent post-processing</h4>
  70 After the time stamps have been successfully plucked from the SHM
  71 segment, some sanity checks take place:
  72 <ul>
  73   <li>The receive time stamp of the SHM data must be in the last 5
  74   seconds before the time the data is processed. This helps in weeding
  75   out stale data.
  76   <li>If the absolute difference between remote and local clock
  77   exceeds the limit (either <i>time2</i> or the default of 4hrs), then
  78   the sample is discarded. This check is disabled when <i>flag1</i> is
  79   set to 1.
  80 </ul>
  81
  82 <h4>GPSD</h4>
  83
  84 <a href="http://gpsd.berlios.de/"><i>GPSD</i></a>
  85 knows how to talk to many GPS devices.
  86 It can work with <i>NTPD</i> through the SHM driver.
  87 <P>
  88 The <i>GPSD</i> man page suggests setting minpoll and maxpoll to 4.
  89 That was an attempt to reduce jitter.
  90 The SHM driver was fixed (ntp-4.2.5p138) to collect data each second rather than
  91 once per polling interval so that suggestion is no longer reasonable.
  92 <P>
  93   <b>Note:</b> The <i>GPSD</i> client driver (type 46) uses the <i>GPSD</i>
  94   client protocol to connect and talk to <i>GPSD</i>, but using the
  95   SHM driver is the ancient way to have <i>GPSD</i> talk to <i>NTPD</i>. There
  96   are some tricky points when using the SHM interface to interface
  97   with <i>GPSD</i>, because <i>GPSD</i> will use two SHM clocks, one for the
  98   serial data stream and one for the PPS information when
  99   available. Receivers with a loose/sloppy timing between PPS and serial data
 100   can easily cause trouble here because <i>NTPD</i> has no way to join the two
 101   data streams and correlate the serial data with the PPS events.
 102 </p>
 103 <p>
 104
 105 <h4>Clockstats</h4>
 106 If flag4 is set when the driver is polled, a clockstats record is written.
 107 The first 3 fields are the normal date, time, and IP address common to all clockstats records.
 108 <P>
 109 The 4th field is the number of second ticks since the last poll.
 110 The 5th field is the number of good data samples found.  The last 64 will be used by <i>NTPD</i>.
 111 The 6th field is the number of sample that didn't have valid data ready.
 112 The 7th field is the number of bad samples.
 113 The 8th field is the number of times the the mode 1 info was update while <i>NTPD</i> was trying to grab a sample.
 114 <P>
 115
 116 Here is a sample showing the GPS reception fading out:
 117 <pre>
 118 54364 84927.157 127.127.28.0  66  65   1   0   0
 119 54364 84990.161 127.127.28.0  63  63   0   0   0
 120 54364 85053.160 127.127.28.0  63  63   0   0   0
 121 54364 85116.159 127.127.28.0  63  62   1   0   0
 122 54364 85180.158 127.127.28.0  64  63   1   0   0
 123 54364 85246.161 127.127.28.0  66  66   0   0   0
 124 54364 85312.157 127.127.28.0  66  50  16   0   0
 125 54364 85375.160 127.127.28.0  63  41  22   0   0
 126 54364 85439.155 127.127.28.0  64  64   0   0   0
 127 54364 85505.158 127.127.28.0  66  36  30   0   0
 128 54364 85569.157 127.127.28.0  64   0  64   0   0
 129 54364 85635.157 127.127.28.0  66   0  66   0   0
 130 54364 85700.160 127.127.28.0  65   0  65   0   0
 131 </pre>
 132
 133     <h4>The 'mode' word</h4>
 134
 135     <p>
 136       Some aspects of the driver behavior can be adjusted by setting bits of
 137       the 'mode' word in the server configuration line:<br>
 138       &nbsp;&nbsp;<tt>server 127.127.28.</tt><i>x</i><tt> mode </tt><i>Y</i>
 139     </p>
 140
 141     <table border="1" width="100%">
 142       <caption>mode word bits and bit groups</caption>
 143       <tbody><tr>
 144         <th align="center">Bit</th>
 145         <th align="center">Dec</th>
 146         <th align="center">Hex</th>
 147         <th align="left">Meaning</th>
 148       </tr>
 149
 150       <tr>
 151         <td align="center">0</td>
 152         <td align="center">1</td>
 153         <td align="center">1</td>
 154         <td>The SHM segment is private (mode 0600). This is the fixed
 155         default for clock units 0 and 1; clock units &gt;1 are mode
 156         0666 unless this bit is set for the specific unit.</td>
 157       </tr><tr>
 158         <td align="center">1-31</td>
 159         <td align="center">-</td>
 160         <td align="center">-</td>
 161         <td><i>reserved -- do not use</i></td>
 162         </tr>
 163       </tbody>
 164       </table>
 165
 166         <h4>Fudge Factors</h4>
 167         <dl>
 168             <dt><tt>time1 <i>time</i></tt>
 169             <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
 170             <dt><tt>time2 <i>time</i></tt>
 171             <dd>Maximum allowed difference between remote and local
 172             clock, in seconds. Values <1.0 or >86400.0 are ignored, and the
 173             default value of 4hrs (14400s) is used instead. See also flag 1.
 174             <dt><tt>stratum <i>number</i></tt>
 175             <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
 176             <dt><tt>refid <i>string</i></tt>
 177             <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>SHM</tt>.
 178             <dt><tt>flag1 0 | 1</tt>
 179             <dd><i>Skip</i> the difference limit check if set. Useful
 180             for systems where the RTC backup cannot keep the time over
 181             long periods without power and the SHM clock must be able
 182             to force long-distance initial jumps. <i>Check</i> the
 183             difference limit if cleared (default).
 184             <dt><tt>flag2 0 | 1</tt>
 185             <dd>Not used by this driver.
 186             <dt><tt>flag3 0 | 1</tt>
 187             <dd>Not used by this driver.
 188             <dt><tt>flag4 0 | 1</tt>
 189             <dd>If flag4 is set, clockstats records will be written when the driver is polled.
 190         </dl>
 191
 192         <h4>Public vs. Private SHM segments</h4>
 193
 194         <p>The driver attempts to create a shared memory segment with an
 195           identifier depending on the unit number. This identifier (which can be
 196           a numeric value or a string) clearly depends on the method used, which
 197           in turn depends on the host operating system:</p>
 198
 199         <ul>
 200           <li><p>
 201               <tt>Windows</tt> uses a file mapping to the page file with the
 202               name '<tt>Global\NTP</tt><i>u</i>' for public accessible
 203               mappings, where <i>u</i> is the clock unit. Private /
 204               non-public mappings are created as
 205               '<tt>Local\NTP</tt><i>u</i>'.
 206             </p><p>
 207               Public access assigns a NULL DACL to the memory mapping, while
 208               private access just uses the default DACL of the process creating
 209               the mapping.
 210             </p>
 211           </li>
 212           <li><p>
 213               <tt>SYSV IPC</tt> creates a shared memory segment with a key value
 214               of <tt>0x4E545030</tt> + <i>u</i>, where <i>u</i> is again
 215               the clock unit. (This value could be hex-decoded as 'NTP0',
 216               'NTP1',..., with funny characters for units &gt; 9.)
 217             </p><p>
 218               Public access means a permission set of 0666, while private access
 219               creates the mapping with a permission set of 0600.
 220             </p>
 221           </li>
 222         </ul>
 223
 224         <p>There's no support for POSIX shared memory yet.</p>
 225
 226         <p><i>NTPD</i> is started as root on most POSIX-like operating systems
 227         and uses the setuid/setgid system API to run under reduced rights once
 228         the initial setup of the process is done. One consequence out of this
 229         is that the allocation of SHM segments must be done early during the
 230         clock setup. The actual polling of the clock is done as the run-time
 231         user; deferring the creation of the SHM segment to this point will
 232         create a SHM segment owned by the runtime-user account. The internal
 233         structure of <i>NTPD</i> does not permit the use of a fudge flag if
 234         this is to be avoided; this is the reason why a mode bit is used for
 235         the configuration of a public segment.
 236         </p>
 237
 238         <p>When running under Windows, the chosen user account must be able to
 239         create a SHM segment in the global object name space for SHM clocks with
 240         public access. Otherwise the session isolation used by Windows kernels
 241         after WinXP will get into the way if the client program does not run in
 242         the same session.
 243         </p>
 244
 245         <h4>Additional Information</h4>
 246         <p><a href="../refclock.html">Reference Clock Drivers</a></p>
 247
 248         <hr>
 249         <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
 250     </body>
 251
 252 </html>
 253