1PHC2SYS(8)                  System Manager's Manual                 PHC2SYS(8)
2
3
4

NAME

6       phc2sys - synchronize two or more clocks
7
8

SYNOPSIS

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
15
16

DESCRIPTION

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
23       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
27       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
34

OPTIONS

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
41       -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
47       -f config
48              Read configuration from the  specified  file.  No  configuration
49              file is read by default.
50
51       -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
64       -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
75       -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
82       -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
87       -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
94       -P kp  Specify  the  proportional  constant  of  the PI controller. The
95              default is 0.7.
96
97       -I ki  Specify the integral constant of the PI controller. The  default
98              is 0.3.
99
100       -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
109       -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
115       -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
119       -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
125       -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
130       -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
138       -M segment
139              The number of the SHM segment used by ntpshm servo.  The default
140              is 0.
141
142       -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
152       -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
158       -n domain-number
159              Specify the domain number used by ptp4l. The default is 0.
160
161       -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
166       -z uds-address
167              Specifies the address of the server's UNIX domain  socket.   The
168              default is /var/run/ptp4l.
169
170       -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
174       -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
178       -m     Print messages to the standard output.
179
180       -q     Don't send messages to the system logger.
181
182       -h     Display a help message.
183
184       -v     Prints the software version and exits.
185
186

LONG OPTIONS

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
193              --transportSpecific 1   --transportSpecific=1
194
195       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
199

CONFIGURATION FILE

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
207       The global section (indicated as [global]) sets  the  program  options.
208       This is the only used option.
209
210

FILE OPTIONS

212       domainNumber
213              Specify  the  domain  number  used by phc2sys. The default is 0.
214              Same as option -n (see above).
215
216
217       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
226              The maximum logging level of messages which should  be  printed.
227              The default is 6 (LOG_INFO). Same as option -l (see above).
228
229
230       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
234
235       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
241
242       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
251
252       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
262
263       transportSpecific
264              The transport specific field. Must be in the  range  0  to  255.
265              The default is 0.
266
267
268       use_syslog
269              Print  messages  to the system log if enabled.  The default is 1
270              (enabled).  Related to option -q (see above).
271
272
273       verbose
274              Print messages to the standard output if enabled.   The  default
275              is 0 (disabled).  Related to option -m (see above).
276
277
278       pi_proportional_const
279              Specifies  the proportional constant of the PI controller.  Same
280              as option -P (see above).
281
282
283       pi_integral_const
284              Specifies the integral constant of the PI controller.   Same  as
285              option -I (see above).
286
287
288       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
297
298       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
305
306       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
310
311       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
315

TIME SCALE USAGE

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
321       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
326       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
333

EXAMPLES

335       Synchronize  time  automatically  according to the current ptp4l state,
336       synchronize the system clock to the remote master.
337
338              phc2sys -a -r
339
340       Same as above, but when the host becomes the domain master, synchronize
341       time in the domain to its system clock.
342
343              phc2sys -a -rr
344
345       Same as above, in an IEEE 802.1AS domain.
346
347              phc2sys -a -rr --transportSpecific=1
348
349       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
354              phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -w
355
356       Same as above, time offset is provided on command line and phc2sys does
357       not wait for ptp4l.
358
359              phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -O 35
360
361       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
364              phc2sys -s /dev/ptp0 -w
365
366       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
369              phc2sys -s eth0 -O -35
370
371

WARNING

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
380       It is recommended to use seperate configuration  files  for  ptp4l  and
381       phc2sys in order to avoid any unexpected behavior.
382
383

SEE ALSO

385       ptp4l(8)
386
387
388
389linuxptp                          April 2018                        PHC2SYS(8)
Impressum