diff options
Diffstat (limited to 'html/drivers/driver28.html')
| -rw-r--r-- | html/drivers/driver28.html | 136 |
1 files changed, 121 insertions, 15 deletions
diff --git a/html/drivers/driver28.html b/html/drivers/driver28.html index 8c7fd80..efa862f 100644 --- a/html/drivers/driver28.html +++ b/html/drivers/driver28.html @@ -7,6 +7,10 @@ <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]"> <title>Shared Memory Driver</title> <link href="scripts/style.css" type="text/css" rel="stylesheet"> + <style type="text/css"> + table.dlstable { font-size:85%; } + td.ttf{ font-family:Courier; font-weight:bold; } + </style> </head> <body> @@ -21,7 +25,13 @@ Driver ID: <tt>SHM</tt></p> <h4>Description</h4> - <p>This driver receives its reference clock info from a shared memory-segment. The shared memory-segment is created with owner-only access for unit 0 and 1, and world access for unit 2 and 3</p> + <p>This driver receives its reference clock info from a shared + memory-segment. The shared memory-segment is created with owner-only + access by default, unless otherwise requested by the mode word for units + ≥2. Units 0 and 1 are always created with owner-only access for + backward compatibility. + </p> + <h4>Structure of shared memory-segment</h4> <pre>struct shmTime { @@ -49,14 +59,14 @@ <h4>Operation mode=0</h4> <p>Each second, the value of <code>valid</code> of the shared memory-segment is checked:</p> - <p>If set, the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are passed to ntp, and <code>valid</code> is cleared and <code>count</code> is bumped.</p> + <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> <p>If not set, <code>count</code> is bumped.</p> <h4>Operation mode=1</h4> <p>Each second, <code>valid</code> in the shared memory-segment is checked:</p> - <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 ntp. 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 ntp. The <code>valid</code> flag is cleared and <code>count</code> is bumped.</p> + <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> <p>If not set, <code>count</code> is bumped</p> -<h4>Mode-independent postprocessing</h4> +<h4>Mode-independent post-processing</h4> After the time stamps have been successfully plucked from the SHM segment, some sanity checks take place: <ul> @@ -69,30 +79,38 @@ segment, some sanity checks take place: set to 1. </ul> -<h4>gpsd</h4> +<h4>GPSD</h4> -<a href="http://gpsd.berlios.de/"><i>gpsd</i></a> +<a href="http://gpsd.berlios.de/"><i>GPSD</i></a> knows how to talk to many GPS devices. -It can work with <i>ntpd</i> through the SHM driver. +It can work with <i>NTPD</i> through the SHM driver. <P> -The <i>gpsd</i> man page suggests setting minpoll and maxpoll to 4. +The <i>GPSD</i> man page suggests setting minpoll and maxpoll to 4. That was an attempt to reduce jitter. The SHM driver was fixed (ntp-4.2.5p138) to collect data each second rather than once per polling interval so that suggestion is no longer reasonable. <P> - <b>Note:</b> The GPSD client driver (type 46) uses the <i>gpsd</i> - client protocol to connect and talk to <i>gpsd</i>, but using the - SHM driver is the ancient way to have <i>gpsd</i> talk to <i>ntpd</i>. + <b>Note:</b> The <i>GPSD</i> client driver (type 46) uses the <i>GPSD</i> + client protocol to connect and talk to <i>GPSD</i>, but using the + SHM driver is the ancient way to have <i>GPSD</i> talk to <i>NTPD</i>. There + are some tricky points when using the SHM interface to interface + with <i>GPSD</i>, because <i>GPSD</i> will use two SHM clocks, one for the + serial data stream and one for the PPS information when + available. Receivers with a loose/sloppy timing between PPS and serial data + can easily cause trouble here because <i>NTPD</i> has no way to join the two + data streams and correlate the serial data with the PPS events. +</p> +<p> <h4>Clockstats</h4> If flag4 is set when the driver is polled, a clockstats record is written. The first 3 fields are the normal date, time, and IP address common to all clockstats records. <P> The 4th field is the number of second ticks since the last poll. -The 5th field is the number of good data samples found. The last 64 will be used by ntpd. +The 5th field is the number of good data samples found. The last 64 will be used by <i>NTPD</i>. The 6th field is the number of sample that didn't have valid data ready. The 7th field is the number of bad samples. -The 8th field is the number of times the the mode 1 info was update while nptd was trying to grab a sample. +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. <P> Here is a sample showing the GPS reception fading out: @@ -112,6 +130,39 @@ Here is a sample showing the GPS reception fading out: 54364 85700.160 127.127.28.0 65 0 65 0 0 </pre> + <h4>The 'mode' word</h4> + + <p> + Some aspects of the driver behavior can be adjusted by setting bits of + the 'mode' word in the server configuration line:<br> + <tt>server 127.127.28.</tt><i>x</i><tt> mode </tt><i>Y</i> + </p> + + <table border="1" width="100%"> + <caption>mode word bits and bit groups</caption> + <tbody><tr> + <th align="center">Bit</th> + <th align="center">Dec</th> + <th align="center">Hex</th> + <th align="left">Meaning</th> + </tr> + + <tr> + <td align="center">0</td> + <td align="center">1</td> + <td align="center">1</td> + <td>The SHM segment is private (mode 0600). This is the fixed + default for clock units 0 and 1; clock units >1 are mode + 0666 unless this bit is set for the specific unit.</td> + </tr><tr> + <td align="center">1-31</td> + <td align="center">-</td> + <td align="center">-</td> + <td><i>reserved -- do not use</i></td> + </tr> + </tbody> + </table> + <h4>Fudge Factors</h4> <dl> <dt><tt>time1 <i>time</i></tt> @@ -136,9 +187,64 @@ Here is a sample showing the GPS reception fading out: <dd>Not used by this driver. <dt><tt>flag4 0 | 1</tt> <dd>If flag4 is set, clockstats records will be written when the driver is polled. - <h4>Additional Information</h4> - <p><a href="../refclock.html">Reference Clock Drivers</a></p> </dl> + + <h4>Public vs. Private SHM segments</h4> + + <p>The driver attempts to create a shared memory segment with an + identifier depending on the unit number. This identifier (which can be + a numeric value or a string) clearly depends on the method used, which + in turn depends on the host operating system:</p> + + <ul> + <li><p> + <tt>Windows</tt> uses a file mapping to the page file with the + name '<tt>Global\NTP</tt><i>u</i>' for public accessible + mappings, where <i>u</i> is the clock unit. Private / + non-public mappings are created as + '<tt>Local\NTP</tt><i>u</i>'. + </p><p> + Public access assigns a NULL DACL to the memory mapping, while + private access just uses the default DACL of the process creating + the mapping. + </p> + </li> + <li><p> + <tt>SYSV IPC</tt> creates a shared memory segment with a key value + of <tt>0x4E545030</tt> + <i>u</i>, where <i>u</i> is again + the clock unit. (This value could be hex-decoded as 'NTP0', + 'NTP1',..., with funny characters for units > 9.) + </p><p> + Public access means a permission set of 0666, while private access + creates the mapping with a permission set of 0600. + </p> + </li> + </ul> + + <p>There's no support for POSIX shared memory yet.</p> + + <p><i>NTPD</i> is started as root on most POSIX-like operating systems + and uses the setuid/setgid system API to run under reduced rights once + the initial setup of the process is done. One consequence out of this + is that the allocation of SHM segments must be done early during the + clock setup. The actual polling of the clock is done as the run-time + user; deferring the creation of the SHM segment to this point will + create a SHM segment owned by the runtime-user account. The internal + structure of <i>NTPD</i> does not permit the use of a fudge flag if + this is to be avoided; this is the reason why a mode bit is used for + the configuration of a public segment. + </p> + + <p>When running under Windows, the chosen user account must be able to + create a SHM segment in the global object name space for SHM clocks with + public access. Otherwise the session isolation used by Windows kernels + after WinXP will get into the way if the client program does not run in + the same session. + </p> + + <h4>Additional Information</h4> + <p><a href="../refclock.html">Reference Clock Drivers</a></p> + <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> |