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 ≥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> 70After the time stamps have been successfully plucked from the SHM 71segment, 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> 85knows how to talk to many GPS devices. 86It can work with <i>NTPD</i> through the SHM driver. 87<P> 88The <i>GPSD</i> man page suggests setting minpoll and maxpoll to 4. 89That was an attempt to reduce jitter. 90The SHM driver was fixed (ntp-4.2.5p138) to collect data each second rather than 91once 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> 106If flag4 is set when the driver is polled, a clockstats record is written. 107The first 3 fields are the normal date, time, and IP address common to all clockstats records. 108<P> 109The 4th field is the number of second ticks since the last poll. 110The 5th field is the number of good data samples found. The last 64 will be used by <i>NTPD</i>. 111The 6th field is the number of sample that didn't have valid data ready. 112The 7th field is the number of bad samples. 113The 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 116Here is a sample showing the GPS reception fading out: 117<pre> 11854364 84927.157 127.127.28.0 66 65 1 0 0 11954364 84990.161 127.127.28.0 63 63 0 0 0 12054364 85053.160 127.127.28.0 63 63 0 0 0 12154364 85116.159 127.127.28.0 63 62 1 0 0 12254364 85180.158 127.127.28.0 64 63 1 0 0 12354364 85246.161 127.127.28.0 66 66 0 0 0 12454364 85312.157 127.127.28.0 66 50 16 0 0 12554364 85375.160 127.127.28.0 63 41 22 0 0 12654364 85439.155 127.127.28.0 64 64 0 0 0 12754364 85505.158 127.127.28.0 66 36 30 0 0 12854364 85569.157 127.127.28.0 64 0 64 0 0 12954364 85635.157 127.127.28.0 66 0 66 0 0 13054364 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 <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 >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 > 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 254