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. This option does not support
65 bonded interface (e.g. bond0). If ptp4l has a port on an active-
66 backup bond interface, the -a option can be used to track the
67 active interface.
68 -i interface
70 Performs the exact same function as -s for compatibility rea‐
71 sons. Previously enabled specifying master clock by network
72 interface. However, this can now be done using -s and this
73 option is no longer necessary. As such it has been deprecated,
74 and should no longer be used.
75 -c device
77 Specify the slave clock by device (e.g. /dev/ptp1) or interface
78 (e.g. eth1) or by name. The default is CLOCK_REALTIME (the sys‐
79 tem clock). Not compatible with the -a option.
80 -E servo
82 Specify which clock servo should be used. Valid values are pi
83 for a PI controller, linreg for an adaptive controller using
84 linear regression, and ntpshm for the NTP SHM reference clock to
85 allow another process to synchronize the local clock. The
86 default is pi.
87 -P kp Specify the proportional constant of the PI controller. The
89 default is 0.7.
90 -I ki Specify the integral constant of the PI controller. The default
92 is 0.3.
93 -S step
95 Specify the step threshold of the servo. It is the maximum off‐
96 set that the servo corrects by changing the clock frequency
97 instead of stepping the clock. The clock is stepped on start
98 regardless of the option if the offset is larger than 20
99 microseconds (unless the -F option is used). It's specified in
100 seconds. The value of 0.0 disables stepping after the start. The
101 default is 0.0.
102 -F step
104 Specify the step threshold applied only on the first update. It
105 is the maximum offset that is corrected by adjusting clock. It's
106 specified in seconds. The value of 0.0 disables stepping on
107 start. The default is 0.00002 (20 microseconds).
108 -R update-rate
110 Specify the slave clock update rate when running in the direct
111 synchronization mode. The default is 1 per second.
112 -N phc-num
114 Specify the number of master clock readings per one slave clock
115 update. Only the fastest reading is used to update the slave
116 clock, this is useful to minimize the error caused by random
117 delays in scheduling and bus utilization. The default is 5.
118 -O offset
120 Specify the offset between the slave and master times in sec‐
121 onds. Not compatible with the -a option. See TIME SCALE USAGE
122 below.
123 -L freq-limit
125 The maximum allowed frequency offset between uncorrected clock
126 and the system monotonic clock in parts per billion (ppb). This
127 is used as a sanity check of the synchronized clock. When a
128 larger offset is measured, a warning message will be printed and
129 the servo will be reset. When set to 0, the sanity check is dis‐
130 abled. The default is 200000000 (20%).
131 -M segment
133 The number of the SHM segment used by ntpshm servo. The default
134 is 0.
135 -u summary-updates
137 Specify the number of clock updates included in summary statis‐
138 tics. The statistics include offset root mean square (RMS), max‐
139 imum absolute offset, frequency offset mean and standard devia‐
140 tion, and mean of the delay in clock readings and standard devi‐
141 ation. The units are nanoseconds and parts per billion (ppb). If
142 zero, the individual samples are printed instead of the statis‐
143 tics. The messages are printed at the LOG_INFO level. The
144 default is 0 (disabled).
145 -w Wait until ptp4l is in a synchronized state. If the -O option is
147 not used, also keep the offset between the slave and master
148 times updated according to the currentUtcOffset value obtained
149 from ptp4l and the direction of the clock synchronization. Not
150 compatible with the -a option.
151 -n domain-number
153 Specify the domain number used by ptp4l. The default is 0.
154 -x When a leap second is announced, don't apply it in the kernel by
156 stepping the clock, but let the servo correct the one-second
157 offset slowly by changing the clock frequency (unless the -S
158 option is used).
159 -z uds-address
161 Specifies the address of the server's UNIX domain socket. The
162 default is /var/run/ptp4l.
163 -l print-level
165 Set the maximum syslog level of messages which should be printed
166 or sent to the system logger. The default is 6 (LOG_INFO).
167 -t message-tag
169 Specify the tag which is added to all messages printed to the
170 standard output or system log. The default is an empty string.
171 -m Print messages to the standard output.
173 -q Don't send messages to the system logger.
175 -h Display a help message.
177 -v Prints the software version and exits.
179
182 Ptp4l uses either PTP time scale or UTC (Coordinated Universal Time)
183 time scale. PTP time scale is continuous and shifted against UTC by a
184 few tens of seconds as PTP time scale does not apply leap seconds.
185 In hardware time stamping mode, ptp4l announces use of PTP time scale
187 and PHC is used for the stamps. That means PHC must follow PTP time
188 scale while system clock follows UTC. Time offset between these two is
189 maintained by phc2sys.
190 Phc2sys acquires the offset value either by reading it from ptp4l when
192 -a or -w is in effect or from command line when -O is supplied. Fail‐
193 ure to maintain the correct offset can result in local system clock
194 being off some seconds to domain master system clock when in slave
195 mode, or incorect PTP time announced to the network in case the host is
196 the domain master.
197
200 Synchronize time automatically according to the current ptp4l state,
201 synchronize the system clock to the remote master.
202 phc2sys -a -r
204 Same as above, but when the host becomes the domain master, synchronize
206 time in the domain to its system clock.
207 phc2sys -a -rr
209 The host is a domain master, PTP clock is synchronized to system clock
211 and the time offset is obtained from ptp4l. Phc2sys waits for ptp4l to
212 get at least one port in master or slave mode before starting the syn‐
213 chronization.
214 phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -w
216 Same as above, time offset is provided on command line and phc2sys does
218 not wait for ptp4l.
219 phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -O 35
221 The host is in slave mode, system clock is synchronized from PTP clock,
223 phc2sys waits for ptp4l and the offset is set automatically.
224 phc2sys -s /dev/ptp0 -w
226 Same as above, PTP clock id is read from the network interface, the
228 offset is provided on command line phc2sys does not wait.
229 phc2sys -s eth0 -O -35
231
234 ptp4l(8)
235linuxptp November 2012 PHC2SYS(8)