1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
= Shared Memory Driver
include::include-html.ad[]
== Synopsis
["verse",subs="normal"]
Name: shm
Reference 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 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.
== 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 +ntpd+, and +valid+ is cleared and +count+ is incremented.
If not set, +count+ is incremented.
== 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.
== 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.
== GPSD
https://gpsd.io/[_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 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_. There are some tricky points
when using the SHM interface to interface with _GPSD_, because _GPSD_
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 _ntpd_
has no way to join the two data streams and correlate the serial data
with the PPS events.
== 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.
== The \'mode' word
Some aspects of the driver behavior can be adjusted by setting bits of
the mode option of the refclock declaration.
["literal",subs="normal"]
.mode word bits and bit groups
[cols="10%,10%,10%,70%",options="header"]
|=============================================================
| 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_
|=============================================================
== 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.
== Configuration Example
The most common use of this driver is to get samples from a gpsd instance:
----------------------------------------------------------------------------
refclock shm unit 0 refid GPS
refclock shm unit 1 prefer refid PPS
----------------------------------------------------------------------------
== 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.
== Additional Information
link:refclock.html[Reference Clock Drivers]
'''''
include::includes/footer.adoc[]
|
