1PHC2SYS(8) System Manager's Manual PHC2SYS(8)
2
6 phc2sys - synchronize two or more clocks
7
10 phc2sys -a [ -r ] [ -r ] [ -f config-file ] [ options ] [ long-options
11 ]
12 phc2sys [ -f config-file ] [ -d pps-device ] [ -s device ] [ -c device
13 ] [ -O offset ] [ -w ] [ options ] [ long-options ] ...
14
18 phc2sys is a program which synchronizes two or more clocks in the sys‐
19 tem. Typically, it is used to synchronize the system clock to a PTP
20 hardware clock (PHC), which itself is synchronized by the ptp4l(8) pro‐
21 gram.
22 With the -a option, the clocks to synchronize are fetched from the run‐
24 ning ptp4l daemon and the direction of synchronization automatically
25 follows changes of the PTP port states.
26 Manual configuration is also possible. When using manual configuration,
28 two synchronization modes are supported, one uses a pulse per second
29 (PPS) signal provided by the source clock and the other mode reads time
30 from the source clock directly. Some clocks can be used in both modes,
31 the mode which will synchronize the time sink with better accuracy de‐
32 pends on hardware and driver implementation.
33
36 -a Read the clocks to synchronize from running ptp4l and follow
37 changes in the port states, adjusting the synchronization direc‐
38 tion automatically. The system clock (CLOCK_REALTIME) is not
39 synchronized, unless the -r option is also specified.
40 -r Only valid together with the -a option. Instructs phc2sys to
42 also synchronize the system clock (CLOCK_REALTIME). By default,
43 the system clock is not considered as a possible time source. If
44 you want the system clock to be eligible to become a time
45 source, specify the -r option twice.
46 -f config
48 Read configuration from the specified file. No configuration
49 file is read by default.
50 -d pps-device
52 Specify the PPS device of the source clock (e.g. /dev/pps0).
53 With this option the PPS synchronization mode is used instead of
54 the direct mode. The matching PHC must be specified using the
55 -s command line option. This option can be used only with the
56 system clock as the time sink. Not compatible with the -a op‐
57 tion.
58 -s device
60 Specify the source clock by device (e.g. /dev/ptp0) or interface
61 (e.g. eth0) or by name (e.g. CLOCK_REALTIME for the system
62 clock). When this option is used together with the -d option,
63 the source clock is used only to correct the offset by whole
64 number of seconds, which cannot be fixed with PPS alone. Not
65 compatible with the -a option. This option does not support
66 bonded interface (e.g. bond0, team0). If ptp4l has a port on an
67 active-backup bond or team interface, the -a option can be used
68 to track the active interface.
69 -i interface
71 Performs the exact same function as -s for compatibility rea‐
72 sons. Previously enabled specifying source clock by network in‐
73 terface. However, this can now be done using -s and this option
74 is no longer necessary. As such it has been deprecated, and
75 should no longer be used.
76 -c device
78 Specify the time sink by device (e.g. /dev/ptp1) or interface
79 (e.g. eth1) or by name. The default is CLOCK_REALTIME (the sys‐
80 tem clock). Not compatible with the -a option. This option may
81 be given up to 128 times.
82 -E servo
84 Specify which clock servo should be used. Valid values are pi
85 for a PI controller, linreg for an adaptive controller using
86 linear regression, and ntpshm and refclock_sock for the NTP SHM
87 and chrony SOCK reference clocks respectively to allow another
88 process to synchronize the local clock. The default is pi.
89 -P kp Specify the proportional constant of the PI controller. The de‐
91 fault is 0.7.
92 -I ki Specify the integral constant of the PI controller. The default
94 is 0.3.
95 -S step
97 Specify the step threshold of the servo. It is the maximum off‐
98 set that the servo corrects by changing the clock frequency in‐
99 stead of stepping the clock. The clock is stepped on start re‐
100 gardless of the option if the offset is larger than 20 microsec‐
101 onds (unless the -F option is used). It's specified in seconds.
102 The value of 0.0 disables stepping after the start. The default
103 is 0.0.
104 -F step
106 Specify the step threshold applied only on the first update. It
107 is the maximum offset that is corrected by changing the clock
108 frequency. It's specified in seconds. The value of 0.0 disables
109 stepping on start. The default is 0.00002 (20 microseconds).
110 -R update-rate
112 Specify the time sink update rate when running in the direct
113 synchronization mode. The default is 1 per second.
114 -N phc-num
116 Specify the number of source clock readings used for each time
117 sink update. Only the fastest reading is used to update the
118 clock. This is useful to minimize the error caused by random
119 delays in scheduling and bus utilization. The default is 5.
120 -O offset
122 Specify the offset between the sink and source times in seconds.
123 Not compatible with the -a option. See TIME SCALE USAGE below.
124 -L freq-limit
126 The maximum allowed frequency offset between uncorrected clock
127 and the system monotonic clock in parts per billion (ppb). This
128 is used as a sanity check of the synchronized clock. When a
129 larger offset is measured, a warning message will be printed and
130 the servo will be reset. When set to 0, the sanity check is dis‐
131 abled. The default is 200000000 (20%).
132 -M segment
134 The number of the SHM segment used by ntpshm servo. The default
135 is 0.
136 -u summary-updates
138 Specify the number of clock updates included in summary statis‐
139 tics. The statistics include offset root mean square (RMS), max‐
140 imum absolute offset, frequency offset mean and standard devia‐
141 tion, and mean of the delay in clock readings and standard devi‐
142 ation. The units are nanoseconds and parts per billion (ppb). If
143 zero, the individual samples are printed instead of the statis‐
144 tics. The messages are printed at the LOG_INFO level. The de‐
145 fault is 0 (disabled).
146 -w Wait until ptp4l is in a synchronized state. If the -O option is
148 not used, also keep the offset between the sink and source times
149 updated according to the currentUtcOffset value obtained from
150 ptp4l and the direction of the clock synchronization. Not com‐
151 patible with the -a option.
152 -n domain-number
154 Specify the domain number used by ptp4l. The default is 0.
155 -x When a leap second is announced, don't apply it in the kernel by
157 stepping the clock, but let the servo correct the one-second
158 offset slowly by changing the clock frequency (unless the -S op‐
159 tion is used).
160 -z uds-address
162 Specifies the address of the server's UNIX domain socket. The
163 default is /var/run/ptp4l.
164 -l print-level
166 Set the maximum syslog level of messages which should be printed
167 or sent to the system logger. The default is 6 (LOG_INFO).
168 -t message-tag
170 Specify the tag which is added to all messages printed to the
171 standard output or system log. The default is an empty string.
172 -m Print messages to the standard output.
174 -q Don't send messages to the system logger.
176 -h Display a help message.
178 -v Prints the software version and exits.
180
183 Each and every configuration file option (see below in section FILE OP‐
184 TIONS) may also appear as a "long" style command line argument. For
185 example, the transportSpecific option may be set using either of these
186 two forms:
187 --transportSpecific 1 --transportSpecific=1
189 Option values given on the command line override values in the global
191 section of the configuration file (which, in turn overrides default
192 values).
193
196 The configuration file is divided into sections. Each section starts
197 with a line containing its name enclosed in brackets and it follows
198 with settings. Each setting is placed on a separate line, it contains
199 the name of the option and the value separated by whitespace charac‐
200 ters. Empty lines and lines starting with # are ignored.
201 The global section (indicated as [global]) sets the program options.
203 This is the only used option.
204
207 clock_servo
208 The servo which is used to synchronize the local clock. Valid
209 values are "pi" for a PI controller, "linreg" for an adaptive
210 controller using linear regression, "ntpshm" for the NTP SHM
211 reference clock to allow another process to synchronize the lo‐
212 cal clock (the SHM segment number is set to the domain number),
213 and "nullf" for a servo that always dials frequency offset zero
214 (for use in SyncE nodes). The default is "pi." Same as option
215 -E (see above).
216 domainNumber
219 Specify the domain number used by phc2sys. The default is 0.
220 Same as option -n (see above).
221 first_step_threshold
224 Specify the step threshold applied only on the first update. It
225 is the maximum offset that is corrected by adjusting clock. It's
226 specified in seconds. The value of 0.0 disables stepping on
227 start. The default is 0.00002 (20 microseconds). Same as option
228 -F (see above).
229 free-running
232 Don't adjust the sink clock if enabled. The default is 0 (dis‐
233 abled).
234 kernel_leap
237 When a leap second is announced, let the kernel apply it by
238 stepping the clock instead of correcting the one-second offset
239 with servo, which would correct the one-second offset slowly by
240 changing the clock frequency (unless the step_threshold option
241 is set to correct such offset by stepping). Relevant only with
242 software time stamping. The default is 1 (enabled). Same as op‐
243 tion -x (see above).
244 logging_level
247 The maximum logging level of messages which should be printed.
248 The default is 6 (LOG_INFO). Same as option -l (see above).
249 message_tag
252 The tag which is added to all messages printed to the standard
253 output or system log. The default is an empty string (which can‐
254 not be set in the configuration file as the option requires an
255 argument). Same as option -t (see above).
256 ntpshm_segment
259 The number of the SHM segment used by ntpshm servo. The default
260 is 0. Same as option -M (see above).
261 pi_integral_const
264 Specifies the integral constant of the PI controller. Same as
265 option -I (see above).
266 pi_proportional_const
269 Specifies the proportional constant of the PI controller. Same
270 as option -P (see above).
271 refclock_sock_address
274 The address of the UNIX domain socket to be used by the ref‐
275 clock_sock servo. The default is /var/run/refclock.ptp.sock.
276 sanity_freq_limit
279 The maximum allowed frequency offset between uncorrected clock
280 and the system monotonic clock in parts per billion (ppb). This
281 is used as a sanity check of the synchronized clock. When a
282 larger offset is measured, a warning message will be printed and
283 the servo will be reset. When set to 0, the sanity check is dis‐
284 abled. The default is 200000000 (20%). Same as option -L (see
285 above).
286 step_threshold
289 Specifies the step threshold of the servo. It is the maximum
290 offset that the servo corrects by changing the clock frequency
291 (phase when using nullf servo) instead of stepping the clock.
292 The clock is stepped on start regardless of the option if the
293 offset is larger than 20 microseconds (unless the -F option is
294 used). It's specified in seconds. The value of 0.0 disables
295 stepping after the start. The default is 0.0. Same as option -S
296 (see above).
297 transportSpecific
300 The transport specific field. Must be in the range 0 to 255.
301 The default is 0.
302 uds_address
305 Specifies the address of the server's UNIX domain socket. The
306 default is /var/run/ptp4 Same as option -z (see above).
307 use_syslog
310 Print messages to the system log if enabled. The default is 1
311 (enabled). Related to option -q (see above).
312 verbose
315 Print messages to the standard output if enabled. The default
316 is 0 (disabled). Related to option -m (see above).
317
320 Ptp4l uses either PTP time scale or UTC (Coordinated Universal Time)
321 time scale. PTP time scale is continuous and shifted against UTC by a
322 few tens of seconds as PTP time scale does not apply leap seconds.
323 In hardware time stamping mode, ptp4l announces use of PTP time scale
325 and PHC is used for the stamps. That means PHC must follow PTP time
326 scale while system clock follows UTC. Time offset between these two is
327 maintained by phc2sys.
328 Phc2sys acquires the offset value either by reading it from ptp4l when
330 -a or -w is in effect or from command line when -O is supplied. Fail‐
331 ure to maintain the correct offset can result in the local system clock
332 being offset some whole number of seconds from the domain server's
333 clock when in client mode, or incorect PTP time announced to the net‐
334 work in case the host is the domain server.
335
338 Synchronize time automatically according to the current ptp4l state,
339 synchronizing the system clock to the remote server.
340 phc2sys -a -r
342 Same as above, but when the host becomes the domain server, synchronize
344 time in the domain to its system clock.
345 phc2sys -a -rr
347 Same as above, in an IEEE 802.1AS domain.
349 phc2sys -a -rr --transportSpecific=1
351 The host is a domain server, PTP clock is synchronized to system clock
353 and the time offset is obtained from ptp4l. Phc2sys waits for ptp4l to
354 get at least one port in server or client mode before starting the syn‐
355 chronization.
356 phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -w
358 Same as above, time offset is provided on command line and phc2sys does
360 not wait for ptp4l.
361 phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -O 37
363 The host is in client mode, system clock is synchronized from PTP
365 clock, phc2sys waits for ptp4l and the offset is set automatically.
366 phc2sys -s /dev/ptp0 -w
368 Same as above, PTP clock id is read from the network interface, the
370 offset is provided on command line phc2sys does not wait.
371 phc2sys -s eth0 -O -37
373
376 Be cautious when the same configuration file is used for both ptp4l and
377 phc2sys. Keep in mind, that values specified in the configuration file
378 take precedence over their default values. If a certain option, which
379 is common to ptp4l and phc2sys, is specified to a non-default value in
380 the configuration file (p.e., for ptp4l), then this non-default value
381 applies also for phc2sys. This might be not what is expected.
382 It is recommended to use seperate configuration files for ptp4l and
384 phc2sys in order to avoid any unexpected behavior.
385
388 ptp4l(8)
389linuxptp February 2023 PHC2SYS(8)