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]"> 8290001Sglebius <title>Shared Memory Driver</title> 9182007Sroberto <link href="scripts/style.css" type="text/css" rel="stylesheet"> 10290001Sglebius <style type="text/css"> 11290001Sglebius table.dlstable { font-size:85%; } 12290001Sglebius td.ttf{ font-family:Courier; font-weight:bold; } 13290001Sglebius </style> 14132451Sroberto </head> 15132451Sroberto 16132451Sroberto <body> 17132451Sroberto <h3>Shared Memory Driver</h3> 18290001Sglebius<p>Last update: 19290001Sglebius <!-- #BeginDate format:En2m -->8-Aug-2014 19:17<!-- #EndDate --> 20290001Sglebius 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> 26290001Sglebius 27132451Sroberto <h4>Description</h4> 28290001Sglebius <p>This driver receives its reference clock info from a shared 29290001Sglebius memory-segment. The shared memory-segment is created with owner-only 30290001Sglebius access by default, unless otherwise requested by the mode word for units 31290001Sglebius ≥2. Units 0 and 1 are always created with owner-only access for 32290001Sglebius backward compatibility. 33290001Sglebius </p> 34290001Sglebius 35290001Sglebius 36132451Sroberto <h4>Structure of shared memory-segment</h4> 37132451Sroberto <pre>struct shmTime { 38290001Sglebius int mode; /* 0 - if valid is set: 39290001Sglebius * use values, 40290001Sglebius * clear valid 41290001Sglebius * 1 - if valid is set: 42290001Sglebius * if count before and after read of data is equal: 43290001Sglebius * use values 44290001Sglebius * clear valid 45290001Sglebius */ 46290001Sglebius volatile int count; 47290001Sglebius time_t clockTimeStampSec; 48290001Sglebius int clockTimeStampUSec; 49290001Sglebius time_t receiveTimeStampSec; 50290001Sglebius int receiveTimeStampUSec; 51290001Sglebius int leap; 52290001Sglebius int precision; 53290001Sglebius int nsamples; 54290001Sglebius volatile int valid; 55290001Sglebius unsigned clockTimeStampNSec; /* Unsigned ns timestamps */ 56290001Sglebius unsigned receiveTimeStampNSec; /* Unsigned ns timestamps */ 57290001Sglebius int dummy[8]; 58132451Sroberto};</pre> 59290001Sglebius 60132451Sroberto <h4>Operation mode=0</h4> 61290001Sglebius <p>Each second, the value of <code>valid</code> of the shared memory-segment is checked:</p> 62290001Sglebius <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> 63290001Sglebius <p>If not set, <code>count</code> is bumped.</p> 64132451Sroberto <h4>Operation mode=1</h4> 65290001Sglebius <p>Each second, <code>valid</code> in the shared memory-segment is checked:</p> 66290001Sglebius <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> 67290001Sglebius <p>If not set, <code>count</code> is bumped</p> 68290001Sglebius 69290001Sglebius<h4>Mode-independent post-processing</h4> 70290001SglebiusAfter the time stamps have been successfully plucked from the SHM 71290001Sglebiussegment, some sanity checks take place: 72290001Sglebius<ul> 73290001Sglebius <li>The receive time stamp of the SHM data must be in the last 5 74290001Sglebius seconds before the time the data is processed. This helps in weeding 75290001Sglebius out stale data. 76290001Sglebius <li>If the absolute difference between remote and local clock 77290001Sglebius exceeds the limit (either <i>time2</i> or the default of 4hrs), then 78290001Sglebius the sample is discarded. This check is disabled when <i>flag1</i> is 79290001Sglebius set to 1. 80290001Sglebius</ul> 81290001Sglebius 82290001Sglebius<h4>GPSD</h4> 83290001Sglebius 84290001Sglebius<a href="http://gpsd.berlios.de/"><i>GPSD</i></a> 85290001Sglebiusknows how to talk to many GPS devices. 86290001SglebiusIt can work with <i>NTPD</i> through the SHM driver. 87290001Sglebius<P> 88290001SglebiusThe <i>GPSD</i> man page suggests setting minpoll and maxpoll to 4. 89290001SglebiusThat was an attempt to reduce jitter. 90290001SglebiusThe SHM driver was fixed (ntp-4.2.5p138) to collect data each second rather than 91290001Sglebiusonce per polling interval so that suggestion is no longer reasonable. 92290001Sglebius<P> 93290001Sglebius <b>Note:</b> The <i>GPSD</i> client driver (type 46) uses the <i>GPSD</i> 94290001Sglebius client protocol to connect and talk to <i>GPSD</i>, but using the 95290001Sglebius SHM driver is the ancient way to have <i>GPSD</i> talk to <i>NTPD</i>. There 96290001Sglebius are some tricky points when using the SHM interface to interface 97290001Sglebius with <i>GPSD</i>, because <i>GPSD</i> will use two SHM clocks, one for the 98290001Sglebius serial data stream and one for the PPS information when 99290001Sglebius available. Receivers with a loose/sloppy timing between PPS and serial data 100290001Sglebius can easily cause trouble here because <i>NTPD</i> has no way to join the two 101290001Sglebius data streams and correlate the serial data with the PPS events. 102290001Sglebius</p> 103290001Sglebius<p> 104290001Sglebius 105290001Sglebius<h4>Clockstats</h4> 106290001SglebiusIf flag4 is set when the driver is polled, a clockstats record is written. 107290001SglebiusThe first 3 fields are the normal date, time, and IP address common to all clockstats records. 108290001Sglebius<P> 109290001SglebiusThe 4th field is the number of second ticks since the last poll. 110290001SglebiusThe 5th field is the number of good data samples found. The last 64 will be used by <i>NTPD</i>. 111290001SglebiusThe 6th field is the number of sample that didn't have valid data ready. 112290001SglebiusThe 7th field is the number of bad samples. 113290001SglebiusThe 8th field is the number of times the the mode 1 info was update while <i>NTPD</i> was trying to grab a sample. 114290001Sglebius<P> 115290001Sglebius 116290001SglebiusHere is a sample showing the GPS reception fading out: 117290001Sglebius<pre> 118290001Sglebius54364 84927.157 127.127.28.0 66 65 1 0 0 119290001Sglebius54364 84990.161 127.127.28.0 63 63 0 0 0 120290001Sglebius54364 85053.160 127.127.28.0 63 63 0 0 0 121290001Sglebius54364 85116.159 127.127.28.0 63 62 1 0 0 122290001Sglebius54364 85180.158 127.127.28.0 64 63 1 0 0 123290001Sglebius54364 85246.161 127.127.28.0 66 66 0 0 0 124290001Sglebius54364 85312.157 127.127.28.0 66 50 16 0 0 125290001Sglebius54364 85375.160 127.127.28.0 63 41 22 0 0 126290001Sglebius54364 85439.155 127.127.28.0 64 64 0 0 0 127290001Sglebius54364 85505.158 127.127.28.0 66 36 30 0 0 128290001Sglebius54364 85569.157 127.127.28.0 64 0 64 0 0 129290001Sglebius54364 85635.157 127.127.28.0 66 0 66 0 0 130290001Sglebius54364 85700.160 127.127.28.0 65 0 65 0 0 131290001Sglebius</pre> 132290001Sglebius 133290001Sglebius <h4>The 'mode' word</h4> 134290001Sglebius 135290001Sglebius <p> 136290001Sglebius Some aspects of the driver behavior can be adjusted by setting bits of 137290001Sglebius the 'mode' word in the server configuration line:<br> 138290001Sglebius <tt>server 127.127.28.</tt><i>x</i><tt> mode </tt><i>Y</i> 139290001Sglebius </p> 140290001Sglebius 141290001Sglebius <table border="1" width="100%"> 142290001Sglebius <caption>mode word bits and bit groups</caption> 143290001Sglebius <tbody><tr> 144290001Sglebius <th align="center">Bit</th> 145290001Sglebius <th align="center">Dec</th> 146290001Sglebius <th align="center">Hex</th> 147290001Sglebius <th align="left">Meaning</th> 148290001Sglebius </tr> 149290001Sglebius 150290001Sglebius <tr> 151290001Sglebius <td align="center">0</td> 152290001Sglebius <td align="center">1</td> 153290001Sglebius <td align="center">1</td> 154290001Sglebius <td>The SHM segment is private (mode 0600). This is the fixed 155290001Sglebius default for clock units 0 and 1; clock units >1 are mode 156290001Sglebius 0666 unless this bit is set for the specific unit.</td> 157290001Sglebius </tr><tr> 158290001Sglebius <td align="center">1-31</td> 159290001Sglebius <td align="center">-</td> 160290001Sglebius <td align="center">-</td> 161290001Sglebius <td><i>reserved -- do not use</i></td> 162290001Sglebius </tr> 163290001Sglebius </tbody> 164290001Sglebius </table> 165290001Sglebius 166290001Sglebius <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> 171290001Sglebius <dd>Maximum allowed difference between remote and local 172290001Sglebius clock, in seconds. Values <1.0 or >86400.0 are ignored, and the 173290001Sglebius 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> 179290001Sglebius <dd><i>Skip</i> the difference limit check if set. Useful 180290001Sglebius for systems where the RTC backup cannot keep the time over 181290001Sglebius long periods without power and the SHM clock must be able 182290001Sglebius to force long-distance initial jumps. <i>Check</i> the 183290001Sglebius 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> 189290001Sglebius <dd>If flag4 is set, clockstats records will be written when the driver is polled. 190132451Sroberto </dl> 191290001Sglebius 192290001Sglebius <h4>Public vs. Private SHM segments</h4> 193290001Sglebius 194290001Sglebius <p>The driver attempts to create a shared memory segment with an 195290001Sglebius identifier depending on the unit number. This identifier (which can be 196290001Sglebius a numeric value or a string) clearly depends on the method used, which 197290001Sglebius in turn depends on the host operating system:</p> 198290001Sglebius 199290001Sglebius <ul> 200290001Sglebius <li><p> 201290001Sglebius <tt>Windows</tt> uses a file mapping to the page file with the 202290001Sglebius name '<tt>Global\NTP</tt><i>u</i>' for public accessible 203290001Sglebius mappings, where <i>u</i> is the clock unit. Private / 204290001Sglebius non-public mappings are created as 205290001Sglebius '<tt>Local\NTP</tt><i>u</i>'. 206290001Sglebius </p><p> 207290001Sglebius Public access assigns a NULL DACL to the memory mapping, while 208290001Sglebius private access just uses the default DACL of the process creating 209290001Sglebius the mapping. 210290001Sglebius </p> 211290001Sglebius </li> 212290001Sglebius <li><p> 213290001Sglebius <tt>SYSV IPC</tt> creates a shared memory segment with a key value 214290001Sglebius of <tt>0x4E545030</tt> + <i>u</i>, where <i>u</i> is again 215290001Sglebius the clock unit. (This value could be hex-decoded as 'NTP0', 216290001Sglebius 'NTP1',..., with funny characters for units > 9.) 217290001Sglebius </p><p> 218290001Sglebius Public access means a permission set of 0666, while private access 219290001Sglebius creates the mapping with a permission set of 0600. 220290001Sglebius </p> 221290001Sglebius </li> 222290001Sglebius </ul> 223290001Sglebius 224290001Sglebius <p>There's no support for POSIX shared memory yet.</p> 225290001Sglebius 226290001Sglebius <p><i>NTPD</i> is started as root on most POSIX-like operating systems 227290001Sglebius and uses the setuid/setgid system API to run under reduced rights once 228290001Sglebius the initial setup of the process is done. One consequence out of this 229290001Sglebius is that the allocation of SHM segments must be done early during the 230290001Sglebius clock setup. The actual polling of the clock is done as the run-time 231290001Sglebius user; deferring the creation of the SHM segment to this point will 232290001Sglebius create a SHM segment owned by the runtime-user account. The internal 233290001Sglebius structure of <i>NTPD</i> does not permit the use of a fudge flag if 234290001Sglebius this is to be avoided; this is the reason why a mode bit is used for 235290001Sglebius the configuration of a public segment. 236290001Sglebius </p> 237290001Sglebius 238290001Sglebius <p>When running under Windows, the chosen user account must be able to 239290001Sglebius create a SHM segment in the global object name space for SHM clocks with 240290001Sglebius public access. Otherwise the session isolation used by Windows kernels 241290001Sglebius after WinXP will get into the way if the client program does not run in 242290001Sglebius the same session. 243290001Sglebius </p> 244290001Sglebius 245290001Sglebius <h4>Additional Information</h4> 246290001Sglebius <p><a href="../refclock.html">Reference Clock Drivers</a></p> 247290001Sglebius 248132451Sroberto <hr> 249182007Sroberto <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> 250132451Sroberto </body> 251132451Sroberto 252290001Sglebius</html> 253290001Sglebius 254