1. Synopsis

Name: shm
Reference ID: SHM

2. Description

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.

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];
};

4. 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 ntpd, and valid is cleared and count is incremented.

If not set, count is incremented.

5. 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 ntpd. 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 ntpd. The valid flag is cleared and count is incremented.

If not set, count is incremented.

6. Mode-independent post-processing

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 within 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 4 h), then the sample is discarded. This check is disabled when flag1 is set to 1.

7. 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 source designator 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 mode 1 info was updated while ntpd was trying to acquire a sample.

Here is a sample showing the GPS reception fading out:

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

The clock identification is normally the driver type and unit, but if your ntpd was built in strict Classic compatibility mode it will be a magic clock address expressing the same information in a more opaque way.

8. The 'mode' word

Some aspects of the driver behavior can be adjusted by setting bits of the mode option of the refclock declaration.

Table 1. mode word bits and bit groups
Bit Dec Hex Meaning

0

1

1

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.

1-31

-

-

reserved — do not use

9. Driver Options

unit number

The driver unit number, defaulting to 0. Used as a distinguishing suffix in the IPC unit name.

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 4 h (14400 s) 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}

Check the difference limit check if set. Skip the difference limit if not set (default). There is really no need for this flag, just let the upper level logic prune out falsetickers. NOTE: this flag is the opposite of flag1 in NTP Classic.

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.

subtype

Not used by this driver.

mode

Can be used to set private mode

path filename

Not used by this driver.

ppspath filename

Not used by this driver.

baud number

Not used by this driver.

10. GPSD Configuration Example

The most common use of this driver is to get samples from a gpsd instance. GPSD knows how to talk to many GPS devices. GPSD will provide one or more SHM clocks depending on its configuration.

For a GPS receiver with a pulse-per-second (PPS) connected to the host, there will be one SHM clock for the serial data stream only and another SHM clock with the PPS timing (when available):

refclock shm unit 0 refid GPS
refclock shm unit 1 prefer refid PPS

Note that there may be additional SHM clocks. For example, the PPS might be on unit 2.

The ntpd default minpoll is 6, and can be set as low as 0. Changing minpoll to 3, 2, 1 or maybe even as low as 0, may reduce your PPS jitter by over a factor of 4.

Any change will require several hours for ntpd to converge with the new settings. Use ntpviz to find the best poll interval for your system.

The value that yields the lowest jitter may not be the one that yields the best offset.

11. Public vs. Private SHM segments

The driver attempts to create a shared memory segment with an identifier depending on the unit number. Unix creates a shared memory segment with a key value of \0x4E545030+u, where u is again the clock unit. (This value could be hex-decoded as 'NTP0', 'NTP1',…​, with funny characters for units > 9.)

Public access means a permission set of 0666, while private access creates the mapping with a permission set of 0600.

ntpd 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 an SHM segment owned by the runtime-user account. The internal structure of ntpd does not permit the use of a refclock option if this is to be avoided; this is the reason why a mode bit is used for the configuration of a public segment.

12. Additional Information