1PHC2SYS(8) System Manager's Manual PHC2SYS(8)
2
6 phc2sys - synchronize two or more clocks
7
10 phc2sys -a [ -r ] [ -r ] [ options ]
11 phc2sys [ -d pps-device ] [ -s device ] [ -c device ] [ -O offset ] [
12 -w ] [ options ]
13
16 phc2sys is a program which synchronizes two or more clocks in the sys‐
17 tem. Typically, it is used to synchronize the system clock to a PTP
18 hardware clock (PHC), which itself is synchronized by the ptp4l(8) pro‐
19 gram.
20 With the -a option, the clocks to synchronize are fetched from the run‐
22 ning ptp4l daemon and the direction of synchronization automatically
23 follows changes of the PTP port states.
24 Manual configuration is also possible. When using manual configuration,
26 two synchronization modes are supported, one uses a pulse per second
27 (PPS) signal provided by the source clock and the other mode reads time
28 from the source clock directly. Some clocks can be used in both modes,
29 the mode which will synchronize the slave clock with better accuracy
30 depends on hardware and driver implementation.
31
34 -a Read the clocks to synchronize from running ptp4l and follow
35 changes in the port states, adjusting the synchronization direc‐
36 tion automatically. The system clock (CLOCK_REALTIME) is not
37 synchronized, unless the -r option is also specified.
38 -r Only valid together with the -a option. Instructs phc2sys to
40 also synchronize the system clock (CLOCK_REALTIME). By default,
41 the system clock is not considered as a possible time source. If
42 you want the system clock to be eligible to become a time
43 source, specify the -r option twice.
44 -d pps-device
46 Specify the PPS device of the master clock (e.g. /dev/pps0).
47 With this option the PPS synchronization mode is used instead of
48 the direct mode. As the PPS signal does not specify time and
49 only marks start of a second, the slave clock should be already
50 close to the correct time before phc2sys is started or the -s
51 option should be used too. With the -s option the PPS signal of
52 the master clock is enabled automatically, otherwise it has to
53 be enabled before phc2sys is started (e.g. by running echo 1 >
54 /sys/class/ptp/ptp0/pps_enable). This option can be used only
55 with the system clock as the slave clock. Not compatible with
56 the -a option.
57 -s device
59 Specify the master clock by device (e.g. /dev/ptp0) or interface
60 (e.g. eth0) or by name (e.g. CLOCK_REALTIME for the system
61 clock). When this option is used together with the -d option,
62 the master clock is used only to correct the offset by whole
63 number of seconds, which cannot be fixed with PPS alone. Not
64 compatible with the -a option.
65 -i interface
67 Performs the exact same function as -s for compatibility rea‐
68 sons. Previously enabled specifying master clock by network
69 interface. However, this can now be done using -s and this
70 option is no longer necessary. As such it has been deprecated,
71 and should no longer be used.
72 -c device
74 Specify the slave clock by device (e.g. /dev/ptp1) or interface
75 (e.g. eth1) or by name. The default is CLOCK_REALTIME (the sys‐
76 tem clock). Not compatible with the -a option.
77 -E servo
79 Specify which clock servo should be used. Valid values are pi
80 for a PI controller, linreg for an adaptive controller using
81 linear regression, and ntpshm for the NTP SHM reference clock to
82 allow another process to synchronize the local clock. The
83 default is pi.
84 -P kp Specify the proportional constant of the PI controller. The
86 default is 0.7.
87 -I ki Specify the integral constant of the PI controller. The default
89 is 0.3.
90 -S step
92 Specify the step threshold of the servo. It is the maximum off‐
93 set that the servo corrects by changing the clock frequency
94 instead of stepping the clock. The clock is stepped on start
95 regardless of the option if the offset is larger than 20
96 microseconds (unless the -F option is used). It's specified in
97 seconds. The value of 0.0 disables stepping after the start. The
98 default is 0.0.
99 -F step
101 Specify the step threshold applied only on the first update. It
102 is the maximum offset that is corrected by adjusting clock. It's
103 specified in seconds. The value of 0.0 disables stepping on
104 start. The default is 0.00002 (20 microseconds).
105 -R update-rate
107 Specify the slave clock update rate when running in the direct
108 synchronization mode. The default is 1 per second.
109 -N phc-num
111 Specify the number of master clock readings per one slave clock
112 update. Only the fastest reading is used to update the slave
113 clock, this is useful to minimize the error caused by random
114 delays in scheduling and bus utilization. The default is 5.
115 -O offset
117 Specify the offset between the slave and master times in sec‐
118 onds. Not compatible with the -a option. See TIME SCALE USAGE
119 below.
120 -L freq-limit
122 The maximum allowed frequency offset between uncorrected clock
123 and the system monotonic clock in parts per billion (ppb). This
124 is used as a sanity check of the synchronized clock. When a
125 larger offset is measured, a warning message will be printed and
126 the servo will be reset. When set to 0, the sanity check is dis‐
127 abled. The default is 200000000 (20%).
128 -M segment
130 The number of the SHM segment used by ntpshm servo. The default
131 is 0.
132 -u summary-updates
134 Specify the number of clock updates included in summary statis‐
135 tics. The statistics include offset root mean square (RMS), max‐
136 imum absolute offset, frequency offset mean and standard devia‐
137 tion, and mean of the delay in clock readings and standard devi‐
138 ation. The units are nanoseconds and parts per billion (ppb). If
139 zero, the individual samples are printed instead of the statis‐
140 tics. The messages are printed at the LOG_INFO level. The
141 default is 0 (disabled).
142 -w Wait until ptp4l is in a synchronized state. If the -O option is
144 not used, also keep the offset between the slave and master
145 times updated according to the currentUtcOffset value obtained
146 from ptp4l and the direction of the clock synchronization. Not
147 compatible with the -a option.
148 -n domain-number
150 Specify the domain number used by ptp4l. The default is 0.
151 -x When a leap second is announced, don't apply it in the kernel by
153 stepping the clock, but let the servo correct the one-second
154 offset slowly by changing the clock frequency (unless the -S
155 option is used).
156 -z uds-address
158 Specifies the address of the server's UNIX domain socket. The
159 default is /var/run/ptp4l.
160 -l print-level
162 Set the maximum syslog level of messages which should be printed
163 or sent to the system logger. The default is 6 (LOG_INFO).
164 -m Print messages to the standard output.
166 -q Don't send messages to the system logger.
168 -h Display a help message.
170 -v Prints the software version and exits.
172
175 Ptp4l uses either PTP time scale or UTC (Coordinated Universal Time)
176 time scale. PTP time scale is continuous and shifted against UTC by a
177 few tens of seconds as PTP time scale does not apply leap seconds.
178 In hardware time stamping mode, ptp4l announces use of PTP time scale
180 and PHC is used for the stamps. That means PHC must follow PTP time
181 scale while system clock follows UTC. Time offset between these two is
182 maintained by phc2sys.
183 Phc2sys acquires the offset value either by reading it from ptp4l when
185 -a or -w is in effect or from command line when -O is supplied. Fail‐
186 ure to maintain the correct offset can result in local system clock
187 being off some seconds to domain master system clock when in slave
188 mode, or incorect PTP time announced to the network in case the host is
189 the domain master.
190
193 Synchronize time automatically according to the current ptp4l state,
194 synchronize the system clock to the remote master.
195 phc2sys -a -r
197 Same as above, but when the host becomes the domain master, synchronize
199 time in the domain to its system clock.
200 phc2sys -a -rr
202 The host is a domain master, PTP clock is synchronized to system clock
204 and the time offset is obtained from ptp4l. Phc2sys waits for ptp4l to
205 get at least one port in master or slave mode before starting the syn‐
206 chronization.
207 phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -w
209 Same as above, time offset is provided on command line and phc2sys does
211 not wait for ptp4l.
212 phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -O 35
214 The host is in slave mode, system clock is synchronized from PTP clock,
216 phc2sys waits for ptp4l and the offset is set automatically.
217 phc2sys -s /dev/ptp0 -w
219 Same as above, PTP clock id is read from the network interface, the
221 offset is provided on command line phc2sys does not wait.
222 phc2sys -s eth0 -O -35
224
227 ptp4l(8)
228linuxptp November 2012 PHC2SYS(8)