### Shared Memory Driver

Last update: 8-Aug-2014 19:17 UTC

#### Synopsis

Address: 127.127.28.u
Reference ID: `SHM`
Driver ID: `SHM`

#### Description

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

#### Structure of shared memory-segment

    struct shmTime {
            int    mode; /* 0 - if valid is set:
                          *       use values,
                          *       clear valid
                          * 1 - if valid is set:
                          *       if count before and after read of data is equal:
                          *         use values
                          *       clear valid
                          */
            volatile int    count;
            time_t          clockTimeStampSec;
            int             clockTimeStampUSec;
            time_t          receiveTimeStampSec;
            int             receiveTimeStampUSec;
            int             leap;
            int             precision;
            int             nsamples;
            volatile int    valid;
            unsigned        clockTimeStampNSec;     /* Unsigned ns timestamps */
            unsigned        receiveTimeStampNSec;   /* Unsigned ns timestamps */
            int             dummy[8];
    };

#### Operation mode=0

Each second, the value of `valid` of the shared memory-segment is checked:

If set, the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are passed to ntp, and `valid` is cleared and `count` is bumped.

If not set, `count` is bumped.

#### Operation mode=1

Each second, `valid` in the shared memory-segment is checked:

If set, the `count` field of the record is remembered, and the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are read. Then, the remembered `count` is compared to current value of `count` 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 `valid` flag is cleared and `count` is bumped.

If not set, `count` is bumped

#### Mode-independent postprocessing

After the time stamps have been successfully plucked from the SHM segment, some sanity checks take place:

- The receive time stamp of the SHM data must be in the last 5 seconds before the time the data is processed. This helps in weeding out stale data.
- If the absolute difference between remote and local clock exceeds the limit (either time2 or the default of 4hrs), then the sample is discarded. This check is disabled when flag1 is set to 1.

#### gpsd

gpsd knows how to talk to many GPS devices. It can work with ntpd through the SHM driver.

The gpsd 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.

Note: The GPSD client driver (type 46) uses the gpsd client protocol to connect and talk to gpsd, but using the SHM driver is the ancient way to have gpsd talk to ntpd.

#### Clockstats

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.

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 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.

Here is a sample showing the GPS reception fading out:

    54364 84927.157 127.127.28.0  66  65   1   0   0
    54364 84990.161 127.127.28.0  63  63   0   0   0
    54364 85053.160 127.127.28.0  63  63   0   0   0
    54364 85116.159 127.127.28.0  63  62   1   0   0
    54364 85180.158 127.127.28.0  64  63   1   0   0
    54364 85246.161 127.127.28.0  66  66   0   0   0
    54364 85312.157 127.127.28.0  66  50  16   0   0
    54364 85375.160 127.127.28.0  63  41  22   0   0
    54364 85439.155 127.127.28.0  64  64   0   0   0
    54364 85505.158 127.127.28.0  66  36  30   0   0
    54364 85569.157 127.127.28.0  64   0  64   0   0
    54364 85635.157 127.127.28.0  66   0  66   0   0
    54364 85700.160 127.127.28.0  65   0  65   0   0

#### Fudge Factors

`time1 time`
  Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
`time2 time`
  Maximum allowed difference between remote and local clock, in seconds. Values <1.0 or >86400.0 are ignored, and the default value of 4hrs (14400s) is used instead. See also flag 1.
`stratum number`
  Specifies the driver stratum, in decimal from 0 to 15, with default 0.
`refid string`
  Specifies the driver reference identifier, an ASCII string from one to four characters, with default `SHM`.
`flag1 0 | 1`
  Skip the difference limit check if set. Useful for systems where the RTC backup cannot keep the time over long periods without power and the SHM clock must be able to force long-distance initial jumps. Check the difference limit if cleared (default).
`flag2 0 | 1`
  Not used by this driver.
`flag3 0 | 1`
  Not used by this driver.
`flag4 0 | 1`
  If flag4 is set, clockstats records will be written when the driver is polled.

  #### Additional Information

  Reference Clock Drivers