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