1132451Sroberto<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2132451Sroberto 3132451Sroberto<html> 4132451Sroberto 5132451Sroberto <head> 6132451Sroberto <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 7132451Sroberto <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]"> 8280849Scy <title>Shared Memory Driver</title> 9182007Sroberto <link href="scripts/style.css" type="text/css" rel="stylesheet"> 10280849Scy <style type="text/css"> 11280849Scy table.dlstable { font-size:85%; } 12280849Scy td.ttf{ font-family:Courier; font-weight:bold; } 13280849Scy </style> 14132451Sroberto </head> 15132451Sroberto 16132451Sroberto <body> 17132451Sroberto <h3>Shared Memory Driver</h3> 18280849Scy<p>Last update: 19280849Scy <!-- #BeginDate format:En2m -->8-Aug-2014 19:17<!-- #EndDate --> 20280849Scy UTC</p> 21132451Sroberto <hr> 22132451Sroberto <h4>Synopsis</h4> 23132451Sroberto <p>Address: 127.127.28.<i>u</i><br> 24132451Sroberto Reference ID: <tt>SHM</tt><br> 25132451Sroberto Driver ID: <tt>SHM</tt></p> 26280849Scy 27132451Sroberto <h4>Description</h4> 28280849Scy <p>This driver receives its reference clock info from a shared 29280849Scy memory-segment. The shared memory-segment is created with owner-only 30280849Scy access by default, unless otherwise requested by the mode word for units 31280849Scy ≥2. Units 0 and 1 are always created with owner-only access for 32280849Scy backward compatibility. 33280849Scy </p> 34280849Scy 35280849Scy 36132451Sroberto <h4>Structure of shared memory-segment</h4> 37132451Sroberto <pre>struct shmTime { 38280849Scy int mode; /* 0 - if valid is set: 39280849Scy * use values, 40280849Scy * clear valid 41280849Scy * 1 - if valid is set: 42280849Scy * if count before and after read of data is equal: 43280849Scy * use values 44280849Scy * clear valid 45280849Scy */ 46280849Scy volatile int count; 47280849Scy time_t clockTimeStampSec; 48280849Scy int clockTimeStampUSec; 49280849Scy time_t receiveTimeStampSec; 50280849Scy int receiveTimeStampUSec; 51280849Scy int leap; 52280849Scy int precision; 53280849Scy int nsamples; 54280849Scy volatile int valid; 55280849Scy unsigned clockTimeStampNSec; /* Unsigned ns timestamps */ 56280849Scy unsigned receiveTimeStampNSec; /* Unsigned ns timestamps */ 57280849Scy int dummy[8]; 58132451Sroberto};</pre> 59280849Scy 60132451Sroberto <h4>Operation mode=0</h4> 61280849Scy <p>Each second, the value of <code>valid</code> of the shared memory-segment is checked:</p> 62280849Scy <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> 63280849Scy <p>If not set, <code>count</code> is bumped.</p> 64132451Sroberto <h4>Operation mode=1</h4> 65280849Scy <p>Each second, <code>valid</code> in the shared memory-segment is checked:</p> 66280849Scy <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> 67280849Scy <p>If not set, <code>count</code> is bumped</p> 68280849Scy 69280849Scy<h4>Mode-independent post-processing</h4> 70280849ScyAfter the time stamps have been successfully plucked from the SHM 71280849Scysegment, some sanity checks take place: 72280849Scy<ul> 73280849Scy <li>The receive time stamp of the SHM data must be in the last 5 74280849Scy seconds before the time the data is processed. This helps in weeding 75280849Scy out stale data. 76280849Scy <li>If the absolute difference between remote and local clock 77280849Scy exceeds the limit (either <i>time2</i> or the default of 4hrs), then 78280849Scy the sample is discarded. This check is disabled when <i>flag1</i> is 79280849Scy set to 1. 80280849Scy</ul> 81280849Scy 82280849Scy<h4>GPSD</h4> 83280849Scy 84280849Scy<a href="http://gpsd.berlios.de/"><i>GPSD</i></a> 85280849Scyknows how to talk to many GPS devices. 86280849ScyIt can work with <i>NTPD</i> through the SHM driver. 87280849Scy<P> 88280849ScyThe <i>GPSD</i> man page suggests setting minpoll and maxpoll to 4. 89280849ScyThat was an attempt to reduce jitter. 90280849ScyThe SHM driver was fixed (ntp-4.2.5p138) to collect data each second rather than 91280849Scyonce per polling interval so that suggestion is no longer reasonable. 92280849Scy<P> 93280849Scy <b>Note:</b> The <i>GPSD</i> client driver (type 46) uses the <i>GPSD</i> 94280849Scy client protocol to connect and talk to <i>GPSD</i>, but using the 95280849Scy SHM driver is the ancient way to have <i>GPSD</i> talk to <i>NTPD</i>. There 96280849Scy are some tricky points when using the SHM interface to interface 97280849Scy with <i>GPSD</i>, because <i>GPSD</i> will use two SHM clocks, one for the 98280849Scy serial data stream and one for the PPS information when 99280849Scy available. Receivers with a loose/sloppy timing between PPS and serial data 100280849Scy can easily cause trouble here because <i>NTPD</i> has no way to join the two 101280849Scy data streams and correlate the serial data with the PPS events. 102280849Scy</p> 103280849Scy<p> 104280849Scy 105280849Scy<h4>Clockstats</h4> 106280849ScyIf flag4 is set when the driver is polled, a clockstats record is written. 107280849ScyThe first 3 fields are the normal date, time, and IP address common to all clockstats records. 108280849Scy<P> 109280849ScyThe 4th field is the number of second ticks since the last poll. 110280849ScyThe 5th field is the number of good data samples found. The last 64 will be used by <i>NTPD</i>. 111280849ScyThe 6th field is the number of sample that didn't have valid data ready. 112280849ScyThe 7th field is the number of bad samples. 113280849ScyThe 8th field is the number of times the the mode 1 info was update while <i>NTPD</i> was trying to grab a sample. 114280849Scy<P> 115280849Scy 116280849ScyHere is a sample showing the GPS reception fading out: 117280849Scy<pre> 118280849Scy54364 84927.157 127.127.28.0 66 65 1 0 0 119280849Scy54364 84990.161 127.127.28.0 63 63 0 0 0 120280849Scy54364 85053.160 127.127.28.0 63 63 0 0 0 121280849Scy54364 85116.159 127.127.28.0 63 62 1 0 0 122280849Scy54364 85180.158 127.127.28.0 64 63 1 0 0 123280849Scy54364 85246.161 127.127.28.0 66 66 0 0 0 124280849Scy54364 85312.157 127.127.28.0 66 50 16 0 0 125280849Scy54364 85375.160 127.127.28.0 63 41 22 0 0 126280849Scy54364 85439.155 127.127.28.0 64 64 0 0 0 127280849Scy54364 85505.158 127.127.28.0 66 36 30 0 0 128280849Scy54364 85569.157 127.127.28.0 64 0 64 0 0 129280849Scy54364 85635.157 127.127.28.0 66 0 66 0 0 130280849Scy54364 85700.160 127.127.28.0 65 0 65 0 0 131280849Scy</pre> 132280849Scy 133280849Scy <h4>The 'mode' word</h4> 134280849Scy 135280849Scy <p> 136280849Scy Some aspects of the driver behavior can be adjusted by setting bits of 137280849Scy the 'mode' word in the server configuration line:<br> 138280849Scy <tt>server 127.127.28.</tt><i>x</i><tt> mode </tt><i>Y</i> 139280849Scy </p> 140280849Scy 141280849Scy <table border="1" width="100%"> 142280849Scy <caption>mode word bits and bit groups</caption> 143280849Scy <tbody><tr> 144280849Scy <th align="center">Bit</th> 145280849Scy <th align="center">Dec</th> 146280849Scy <th align="center">Hex</th> 147280849Scy <th align="left">Meaning</th> 148280849Scy </tr> 149280849Scy 150280849Scy <tr> 151280849Scy <td align="center">0</td> 152280849Scy <td align="center">1</td> 153280849Scy <td align="center">1</td> 154280849Scy <td>The SHM segment is private (mode 0600). This is the fixed 155280849Scy default for clock units 0 and 1; clock units >1 are mode 156280849Scy 0666 unless this bit is set for the specific unit.</td> 157280849Scy </tr><tr> 158280849Scy <td align="center">1-31</td> 159280849Scy <td align="center">-</td> 160280849Scy <td align="center">-</td> 161280849Scy <td><i>reserved -- do not use</i></td> 162280849Scy </tr> 163280849Scy </tbody> 164280849Scy </table> 165280849Scy 166280849Scy <h4>Fudge Factors</h4> 167132451Sroberto <dl> 168132451Sroberto <dt><tt>time1 <i>time</i></tt> 169132451Sroberto <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0. 170132451Sroberto <dt><tt>time2 <i>time</i></tt> 171280849Scy <dd>Maximum allowed difference between remote and local 172280849Scy clock, in seconds. Values <1.0 or >86400.0 are ignored, and the 173280849Scy default value of 4hrs (14400s) is used instead. See also flag 1. 174132451Sroberto <dt><tt>stratum <i>number</i></tt> 175132451Sroberto <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0. 176132451Sroberto <dt><tt>refid <i>string</i></tt> 177132451Sroberto <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>SHM</tt>. 178132451Sroberto <dt><tt>flag1 0 | 1</tt> 179280849Scy <dd><i>Skip</i> the difference limit check if set. Useful 180280849Scy for systems where the RTC backup cannot keep the time over 181280849Scy long periods without power and the SHM clock must be able 182280849Scy to force long-distance initial jumps. <i>Check</i> the 183280849Scy difference limit if cleared (default). 184132451Sroberto <dt><tt>flag2 0 | 1</tt> 185132451Sroberto <dd>Not used by this driver. 186132451Sroberto <dt><tt>flag3 0 | 1</tt> 187132451Sroberto <dd>Not used by this driver. 188132451Sroberto <dt><tt>flag4 0 | 1</tt> 189280849Scy <dd>If flag4 is set, clockstats records will be written when the driver is polled. 190132451Sroberto </dl> 191280849Scy 192280849Scy <h4>Public vs. Private SHM segments</h4> 193280849Scy 194280849Scy <p>The driver attempts to create a shared memory segment with an 195280849Scy identifier depending on the unit number. This identifier (which can be 196280849Scy a numeric value or a string) clearly depends on the method used, which 197280849Scy in turn depends on the host operating system:</p> 198280849Scy 199280849Scy <ul> 200280849Scy <li><p> 201280849Scy <tt>Windows</tt> uses a file mapping to the page file with the 202280849Scy name '<tt>Global\NTP</tt><i>u</i>' for public accessible 203280849Scy mappings, where <i>u</i> is the clock unit. Private / 204280849Scy non-public mappings are created as 205280849Scy '<tt>Local\NTP</tt><i>u</i>'. 206280849Scy </p><p> 207280849Scy Public access assigns a NULL DACL to the memory mapping, while 208280849Scy private access just uses the default DACL of the process creating 209280849Scy the mapping. 210280849Scy </p> 211280849Scy </li> 212280849Scy <li><p> 213280849Scy <tt>SYSV IPC</tt> creates a shared memory segment with a key value 214280849Scy of <tt>0x4E545030</tt> + <i>u</i>, where <i>u</i> is again 215280849Scy the clock unit. (This value could be hex-decoded as 'NTP0', 216280849Scy 'NTP1',..., with funny characters for units > 9.) 217280849Scy </p><p> 218280849Scy Public access means a permission set of 0666, while private access 219280849Scy creates the mapping with a permission set of 0600. 220280849Scy </p> 221280849Scy </li> 222280849Scy </ul> 223280849Scy 224280849Scy <p>There's no support for POSIX shared memory yet.</p> 225280849Scy 226280849Scy <p><i>NTPD</i> is started as root on most POSIX-like operating systems 227280849Scy and uses the setuid/setgid system API to run under reduced rights once 228280849Scy the initial setup of the process is done. One consequence out of this 229280849Scy is that the allocation of SHM segments must be done early during the 230280849Scy clock setup. The actual polling of the clock is done as the run-time 231280849Scy user; deferring the creation of the SHM segment to this point will 232280849Scy create a SHM segment owned by the runtime-user account. The internal 233280849Scy structure of <i>NTPD</i> does not permit the use of a fudge flag if 234280849Scy this is to be avoided; this is the reason why a mode bit is used for 235280849Scy the configuration of a public segment. 236280849Scy </p> 237280849Scy 238280849Scy <p>When running under Windows, the chosen user account must be able to 239280849Scy create a SHM segment in the global object name space for SHM clocks with 240280849Scy public access. Otherwise the session isolation used by Windows kernels 241280849Scy after WinXP will get into the way if the client program does not run in 242280849Scy the same session. 243280849Scy </p> 244280849Scy 245280849Scy <h4>Additional Information</h4> 246280849Scy <p><a href="../refclock.html">Reference Clock Drivers</a></p> 247280849Scy 248132451Sroberto <hr> 249182007Sroberto <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 250132451Sroberto </body> 251132451Sroberto 252280849Scy</html> 253280849Scy 254