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 slave clock with better accuracy
32 depends 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 master clock (e.g. /dev/pps0).
53 With this option the PPS synchronization mode is used instead of
54 the direct mode. As the PPS signal does not specify time and
55 only marks start of a second, the slave clock should be already
56 close to the correct time before phc2sys is started or the -s
57 option should be used too. With the -s option the PPS signal of
58 the master clock is enabled automatically, otherwise it has to
59 be enabled before phc2sys is started (e.g. by running echo 1 >
60 /sys/class/ptp/ptp0/pps_enable). This option can be used only
61 with the system clock as the slave clock. Not compatible with
62 the -a option.
63 -s device
65 Specify the master clock by device (e.g. /dev/ptp0) or interface
66 (e.g. eth0) or by name (e.g. CLOCK_REALTIME for the system
67 clock). When this option is used together with the -d option,
68 the master clock is used only to correct the offset by whole
69 number of seconds, which cannot be fixed with PPS alone. Not
70 compatible with the -a option. This option does not support
71 bonded interface (e.g. bond0, team0). If ptp4l has a port on an
72 active-backup bond or team interface, the -a option can be used
73 to track the active interface.
74 -i interface
76 Performs the exact same function as -s for compatibility rea‐
77 sons. Previously enabled specifying master clock by network
78 interface. However, this can now be done using -s and this
79 option is no longer necessary. As such it has been deprecated,
80 and should no longer be used.
81 -c device
83 Specify the slave clock by device (e.g. /dev/ptp1) or interface
84 (e.g. eth1) or by name. The default is CLOCK_REALTIME (the sys‐
85 tem clock). Not compatible with the -a option.
86 -E servo
88 Specify which clock servo should be used. Valid values are pi
89 for a PI controller, linreg for an adaptive controller using
90 linear regression, and ntpshm for the NTP SHM reference clock to
91 allow another process to synchronize the local clock. The
92 default is pi.
93 -P kp Specify the proportional constant of the PI controller. The
95 default is 0.7.
96 -I ki Specify the integral constant of the PI controller. The default
98 is 0.3.
99 -S step
101 Specify the step threshold of the servo. It is the maximum off‐
102 set that the servo corrects by changing the clock frequency
103 instead of stepping the clock. The clock is stepped on start
104 regardless of the option if the offset is larger than 20
105 microseconds (unless the -F option is used). It's specified in
106 seconds. The value of 0.0 disables stepping after the start. The
107 default is 0.0.
108 -F step
110 Specify the step threshold applied only on the first update. It
111 is the maximum offset that is corrected by changing the clock
112 frequency. It's specified in seconds. The value of 0.0 disables
113 stepping on start. The default is 0.00002 (20 microseconds).
114 -R update-rate
116 Specify the slave clock update rate when running in the direct
117 synchronization mode. The default is 1 per second.
118 -N phc-num
120 Specify the number of master clock readings per one slave clock
121 update. Only the fastest reading is used to update the slave
122 clock, this is useful to minimize the error caused by random
123 delays in scheduling and bus utilization. The default is 5.
124 -O offset
126 Specify the offset between the slave and master times in sec‐
127 onds. Not compatible with the -a option. See TIME SCALE USAGE
128 below.
129 -L freq-limit
131 The maximum allowed frequency offset between uncorrected clock
132 and the system monotonic clock in parts per billion (ppb). This
133 is used as a sanity check of the synchronized clock. When a
134 larger offset is measured, a warning message will be printed and
135 the servo will be reset. When set to 0, the sanity check is dis‐
136 abled. The default is 200000000 (20%).
137 -M segment
139 The number of the SHM segment used by ntpshm servo. The default
140 is 0.
141 -u summary-updates
143 Specify the number of clock updates included in summary statis‐
144 tics. The statistics include offset root mean square (RMS), max‐
145 imum absolute offset, frequency offset mean and standard devia‐
146 tion, and mean of the delay in clock readings and standard devi‐
147 ation. The units are nanoseconds and parts per billion (ppb). If
148 zero, the individual samples are printed instead of the statis‐
149 tics. The messages are printed at the LOG_INFO level. The
150 default is 0 (disabled).
151 -w Wait until ptp4l is in a synchronized state. If the -O option is
153 not used, also keep the offset between the slave and master
154 times updated according to the currentUtcOffset value obtained
155 from ptp4l and the direction of the clock synchronization. Not
156 compatible with the -a option.
157 -n domain-number
159 Specify the domain number used by ptp4l. The default is 0.
160 -x When a leap second is announced, don't apply it in the kernel by
162 stepping the clock, but let the servo correct the one-second
163 offset slowly by changing the clock frequency (unless the -S
164 option is used).
165 -z uds-address
167 Specifies the address of the server's UNIX domain socket. The
168 default is /var/run/ptp4l.
169 -l print-level
171 Set the maximum syslog level of messages which should be printed
172 or sent to the system logger. The default is 6 (LOG_INFO).
173 -t message-tag
175 Specify the tag which is added to all messages printed to the
176 standard output or system log. The default is an empty string.
177 -m Print messages to the standard output.
179 -q Don't send messages to the system logger.
181 -h Display a help message.
183 -v Prints the software version and exits.
185
188 Each and every configuration file option (see below in section
189 FILE OPTIONS) may also appear as a "long" style command line argument.
190 For example, the transportSpecific option may be set using either of
191 these two forms:
192 --transportSpecific 1 --transportSpecific=1
194 Option values given on the command line override values in the global
196 section of the configuration file (which, in turn overrides default
197 values).
198
201 The configuration file is divided into sections. Each section starts
202 with a line containing its name enclosed in brackets and it follows
203 with settings. Each setting is placed on a separate line, it contains
204 the name of the option and the value separated by whitespace charac‐
205 ters. Empty lines and lines starting with # are ignored.
206 The global section (indicated as [global]) sets the program options.
208 This is the only used option.
209
212 domainNumber
213 Specify the domain number used by phc2sys. The default is 0.
214 Same as option -n (see above).
215 kernel_leap
218 When a leap second is announced, let the kernel apply it by
219 stepping the clock instead of correcting the one-second offset
220 with servo, which would correct the one-second offset slowly by
221 changing the clock frequency (unless the step_threshold option
222 is set to correct such offset by stepping). Relevant only with
223 software time stamping. The default is 1 (enabled). Same as
224 option -x (see above).
225 The maximum logging level of messages which should be printed.
227 The default is 6 (LOG_INFO). Same as option -l (see above).
228 logging_level
231 The maximum logging level of messages which should be printed.
232 The default is 6 (LOG_INFO). Same as option -l (see above).
233 message_tag
236 The tag which is added to all messages printed to the standard
237 output or system log. The default is an empty string (which can‐
238 not be set in the configuration file as the option requires an
239 argument). Same as option -t (see above).
240 sanity_freq_limit
243 The maximum allowed frequency offset between uncorrected clock
244 and the system monotonic clock in parts per billion (ppb). This
245 is used as a sanity check of the synchronized clock. When a
246 larger offset is measured, a warning message will be printed and
247 the servo will be reset. When set to 0, the sanity check is dis‐
248 abled. The default is 200000000 (20%). Same as option -L (see
249 above).
250 clock_servo
253 The servo which is used to synchronize the local clock. Valid
254 values are "pi" for a PI controller, "linreg" for an adaptive
255 controller using linear regression, "ntpshm" for the NTP SHM
256 reference clock to allow another process to synchronize the
257 local clock (the SHM segment number is set to the domain num‐
258 ber), and "nullf" for a servo that always dials frequency offset
259 zero (for use in SyncE nodes). The default is "pi." Same as
260 option -E (see above).
261 transportSpecific
264 The transport specific field. Must be in the range 0 to 255.
265 The default is 0.
266 use_syslog
269 Print messages to the system log if enabled. The default is 1
270 (enabled). Related to option -q (see above).
271 verbose
274 Print messages to the standard output if enabled. The default
275 is 0 (disabled). Related to option -m (see above).
276 pi_proportional_const
279 Specifies the proportional constant of the PI controller. Same
280 as option -P (see above).
281 pi_integral_const
284 Specifies the integral constant of the PI controller. Same as
285 option -I (see 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 instead of stepping the clock. The clock is stepped on start
292 regardless of the option if the offset is larger than 20
293 microseconds (unless the -F option is used). It's specified
294 in seconds. The value of 0.0 disables stepping after the start.
295 The default is 0.0. Same as option -S (see above).
296 first_step_threshold
299 Specify the step threshold applied only on the first update. It
300 is the maximum offset that is corrected by adjusting clock. It's
301 specified in seconds. The value of 0.0 disables stepping on
302 start. The default is 0.00002 (20 microseconds). Same as option
303 -F (see above).
304 ntpshm_segment
307 The number of the SHM segment used by ntpshm servo. The default
308 is 0. Same as option -M (see above).
309 uds_address
312 Specifies the address of the server's UNIX domain socket. The
313 default is /var/run/ptp4 Same as option -z (see above).
314
317 Ptp4l uses either PTP time scale or UTC (Coordinated Universal Time)
318 time scale. PTP time scale is continuous and shifted against UTC by a
319 few tens of seconds as PTP time scale does not apply leap seconds.
320 In hardware time stamping mode, ptp4l announces use of PTP time scale
322 and PHC is used for the stamps. That means PHC must follow PTP time
323 scale while system clock follows UTC. Time offset between these two is
324 maintained by phc2sys.
325 Phc2sys acquires the offset value either by reading it from ptp4l when
327 -a or -w is in effect or from command line when -O is supplied. Fail‐
328 ure to maintain the correct offset can result in local system clock
329 being off some seconds to domain master system clock when in slave
330 mode, or incorect PTP time announced to the network in case the host is
331 the domain master.
332
335 Synchronize time automatically according to the current ptp4l state,
336 synchronize the system clock to the remote master.
337 phc2sys -a -r
339 Same as above, but when the host becomes the domain master, synchronize
341 time in the domain to its system clock.
342 phc2sys -a -rr
344 Same as above, in an IEEE 802.1AS domain.
346 phc2sys -a -rr --transportSpecific=1
348 The host is a domain master, PTP clock is synchronized to system clock
350 and the time offset is obtained from ptp4l. Phc2sys waits for ptp4l to
351 get at least one port in master or slave mode before starting the syn‐
352 chronization.
353 phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -w
355 Same as above, time offset is provided on command line and phc2sys does
357 not wait for ptp4l.
358 phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -O 35
360 The host is in slave mode, system clock is synchronized from PTP clock,
362 phc2sys waits for ptp4l and the offset is set automatically.
363 phc2sys -s /dev/ptp0 -w
365 Same as above, PTP clock id is read from the network interface, the
367 offset is provided on command line phc2sys does not wait.
368 phc2sys -s eth0 -O -35
370
373 Be cautious when the same configuration file is used for both ptp4l and
374 phc2sys. Keep in mind, that values specified in the configuration file
375 take precedence over their default values. If a certain option, which
376 is common to ptp4l and phc2sys, is specified to a non-default value in
377 the configuration file (p.e., for ptp4l), then this non-default value
378 applies also for phc2sys. This might be not what is expected.
379 It is recommended to use seperate configuration files for ptp4l and
381 phc2sys in order to avoid any unexpected behavior.
382
385 ptp4l(8)
386linuxptp April 2018 PHC2SYS(8)