1PTP4l(8) System Manager's Manual PTP4l(8)
2
6 ptp4l - PTP Boundary/Ordinary Clock
7
10 ptp4l [ -AEP246HSLmqsv ] [ -f config ] [ -p phc-device ] [ -l print-
11 level ] [ -i interface ] ...
12
15 ptp4l is an implementation of the Precision Time Protocol (PTP) accord‐
16 ing to IEEE standard 1588 for Linux. It implements Boundary Clock (BC)
17 and Ordinary Clock (OC).
18
21 -A Select the delay mechanism automatically. Start with E2E and
22 switch to P2P when a peer delay request is received.
23 -E Select the delay request-response (E2E) mechanism. This is the
25 default mechanism. All clocks on single PTP communication path
26 must use the same mechanism. A warning will be printed when a
27 peer delay request is received on port using the E2E mechanism.
28 -P Select the peer delay (P2P) mechanism. A warning will be printed
30 when a delay request is received on port using the P2P mecha‐
31 nism.
32 -2 Select the IEEE 802.3 network transport.
34 -4 Select the UDP IPv4 network transport. This is the default
36 transport.
37 -6 Select the UDP IPv6 network transport.
39 -H Select the hardware time stamping. All ports specified by the -i
41 option and in the configuration file must be attached to the
42 same PTP hardware clock (PHC). This is the default time stamp‐
43 ing.
44 -S Select the software time stamping.
46 -L Select the legacy hardware time stamping.
48 -f config
50 Read configuration from the specified file. No configuration
51 file is read by default.
52 -i interface
54 Specify a PTP port, it may be used multiple times. At least one
55 port must be specified by this option or in the configuration
56 file.
57 -p phc-device
59 With hardware time stamping, force which PHC device (e.g.
60 /dev/ptp0) should be used.
61 -s Enable the slaveOnly mode.
63 -l print-level
65 Set the maximum syslog level of messages which should be printed
66 or sent to the system logger. The default is 6 (LOG_INFO).
67 -m Print messages to the standard output.
69 -q Don't send messages to the system logger.
71 -v Prints the software version and exits.
73 -h Display a help message.
75
78 The configuration file is divided into sections. Each section starts
79 with a line containing its name enclosed in brackets and it follows
80 with settings. Each setting is placed on a separate line, it contains
81 the name of the option and the value separated by whitespace charac‐
82 ters. Empty lines and lines starting with # are ignored.
83 The global section (indicated as [global]) sets the program options,
85 clock options and default port options. Other sections are port spe‐
86 cific sections and they override the default port options. The name of
87 the section is the name of the configured port (e.g. [eth0]). Ports
88 specified in the configuration file don't need to be specified by the
89 -i option. An empty port section can be used to replace the command
90 line option.
91
94 delayAsymmetry
95 The time difference in nanoseconds of the transmit and receive
96 paths. This value should be positive when the master-to-slave
97 propagation time is longer and negative when the slave-to-master
98 time is longer. The default is 0 nanoseconds.
99 logAnnounceInterval
101 The mean time interval between Announce messages. A shorter
102 interval makes ptp4l react faster to the changes in the master-
103 slave hierarchy. The interval should be the same in the whole
104 domain. It's specified as a power of two in seconds. The
105 default is 1 (2 seconds).
106 logSyncInterval
108 The mean time interval between Sync messages. A shorter interval
109 may improve accuracy of the local clock. It's specified as a
110 power of two in seconds. The default is 0 (1 second).
111 logMinDelayReqInterval
113 The minimum permitted mean time interval between Delay_Req mes‐
114 sages. A shorter interval makes ptp4l react faster to the
115 changes in the path delay. It's specified as a power of two in
116 seconds. The default is 0 (1 second).
117 logMinPdelayReqInterval
119 The minimum permitted mean time interval between Pdelay_Req mes‐
120 sages. It's specified as a power of two in seconds. The default
121 is 0 (1 second).
122 announceReceiptTimeout
124 The number of missed Announce messages before the last Announce
125 messages expires. The default is 3.
126 syncReceiptTimeout
128 The number of sync/follow up messages that may go missing before
129 triggering a Best Master Clock election. This option is used for
130 running in gPTP mode according to the 802.1AS-2011 standard.
131 Setting this option to zero will disable the sync message time‐
132 out. The default is 0 or disabled.
133 transportSpecific
135 The transport specific field. Must be in the range 0 to 255.
136 The default is 0.
137 path_trace_enabled
139 Enable the mechanism used to trace the route of the Announce
140 messages. The default is 0 (disabled).
141 follow_up_info
143 Include the 802.1AS data in the Follow_Up messages if enabled.
144 The default is 0 (disabled).
145 fault_reset_interval
147 The time in seconds between the detection of a port's fault and
148 the fault being reset. This value is expressed as a power of
149 two. Setting this value to -128 or to the special key word
150 "ASAP" will let the fault be reset immediately. The default is
151 4 (16 seconds).
152 fault_badpeernet_interval
154 The time in seconds between the detection of a peer network mis‐
155 configuration and the fault being reset. The port is disabled
156 for the duration of the interval. The value is in seconds and
157 the special key word ASAP will let the fault be reset immedi‐
158 ately. The default is 16 seconds.
159 delay_mechanism
161 Select the delay mechanism. Possible values are E2E, P2P and
162 Auto. The default is E2E.
163 network_transport
165 Select the network transport. Possible values are UDPv4, UDPv6
166 and L2. The default is UDPv4.
167 neighborPropDelayThresh
169 Upper limit for peer delay in nanoseconds. If the estimated peer
170 delay is greater than this value the port is marked as not
171 802.1AS capable.
172 min_neighbor_prop_delay
174 Lower limit for peer delay in nanoseconds. If the estimated peer
175 delay is smaller than this value the port is marked as not
176 802.1AS capable.
177 delay_filter
179 Select the algorithm used to filter the measured delay and peer
180 delay. Possible values are moving_average and moving_median.
181 The default is moving_median.
182 delay_filter_length
184 The length of the delay filter in samples. The default is 10.
185 egressLatency
187 Specifies the difference in nanoseconds between the actual
188 transmission time at the reference plane and the reported trans‐
189 mit time stamp. This value will be added to egress time stamps
190 obtained from the hardware. The default is 0.
191 ingressLatency
193 Specifies the difference in nanoseconds between the reported
194 receive time stamp and the actual reception time at reference
195 plane. This value will be subtracted from ingress time stamps
196 obtained from the hardware. The default is 0.
197 boundary_clock_jbod
199 When running as a boundary clock (that is, when more than one
200 network interface is configured), ptp4l performs a sanity check
201 to make sure that all of the ports share the same hardware clock
202 device. This option allows ptp4l to work as a boundary clock
203 using "just a bunch of devices" that are not synchronized to
204 each other. For this mode, the collection of clocks must be syn‐
205 chronized by an external program, for example phc2sys(8) in
206 "automatic" mode. The default is 0 (disabled).
207
210 twoStepFlag
211 Enable two-step mode for sync messages. One-step mode can be
212 used only with hardware time stamping. The default is 1
213 (enabled).
214 slaveOnly
216 The local clock is a slave-only clock if enabled. This option
217 is only for use with 1588 clocks and should not be enabled for
218 802.1AS clocks. The default is 0 (disabled).
219 gmCapable
221 If this option is enabled, then the local clock is able to
222 become grand master. This is only for use with 802.1AS clocks
223 and has no effect on 1588 clocks. The default is 1 (enabled).
224 priority1
226 The priority1 attribute of the local clock. It is used in the
227 best master selection algorithm, lower values take precedence.
228 Must be in the range 0 to 255. The default is 128.
229 priority2
231 The priority2 attribute of the local clock. It is used in the
232 best master selection algorithm, lower values take precedence.
233 Must be in the range 0 to 255. The default is 128.
234 clockClass
236 The clockClass attribute of the local clock. It denotes the
237 traceability of the time distributed by the grandmaster clock.
238 The default is 248.
239 clockAccuracy
241 The clockAccuracy attribute of the local clock. It is used in
242 the best master selection algorithm. The default is 0xFE.
243 offsetScaledLogVariance
245 The offsetScaledLogVariance attribute of the local clock. It
246 characterizes the stability of the clock. The default is
247 0xFFFF.
248 domainNumber
250 The domain attribute of the local clock. The default is 0.
251 free_running
253 Don't adjust the local clock if enabled. The default is 0 (dis‐
254 abled).
255 freq_est_interval
257 The time interval over which is estimated the ratio of the local
258 and peer clock frequencies. It is specified as a power of two in
259 seconds. The default is 1 (2 seconds).
260 assume_two_step
262 Treat one-step responses as two-step if enabled. It is used to
263 work around buggy 802.1AS switches. The default is 0 (dis‐
264 abled).
265 tx_timestamp_timeout
267 The number of milliseconds to poll waiting for the tx time stamp
268 from the kernel when a message has recently been sent. The
269 default is 1.
270 check_fup_sync
272 Because of packet reordering that can occur in the network, in
273 the hardware, or in the networking stack, a follow up message
274 can appear to arrive in the application before the matching sync
275 message. As this is a normal occurrence, and the sequenceID mes‐
276 sage field ensures proper matching, the ptp4l program accepts
277 out of order packets. This option adds an additional check using
278 the software time stamps from the networking stack to verify
279 that the sync message did arrive first. This option is only use‐
280 ful if you do not trust the sequence IDs generated by the mas‐
281 ter. The default is 0 (disabled).
282 clock_servo
284 The servo which is used to synchronize the local clock. Valid
285 values are pi for a PI controller, linreg for an adaptive con‐
286 troller using linear regression, and ntpshm for the NTP SHM ref‐
287 erence clock to allow another process to synchronize the local
288 clock (the SHM segment number is set to the domain number). The
289 default is pi.
290 pi_proportional_const
292 The proportional constant of the PI controller. When set to 0.0,
293 the proportional constant will be set by the following formula
294 from the current sync interval. The default is 0.0.
295 kp = min(kp_scale * sync^kp_exponent, kp_norm_max / sync))
297 pi_integral_const
299 The integral constant of the PI controller. When set to 0.0, the
300 integral constant will be set by the following formula from the
301 current sync interval. The default is 0.0.
302 ki = min(ki_scale * sync^ki_exponent, ki_norm_max / sync)
304 pi_proportional_scale
306 The kp_scale constant in the formula used to set the propor‐
307 tional constant of the PI controller from the sync interval.
308 When set to 0.0, the value will be selected from 0.7 and 0.1 for
309 the hardware and software time stamping respectively. The
310 default is 0.0.
311 pi_proportional_exponent
313 The kp_exponent constant in the formula used to set the propor‐
314 tional constant of the PI controller from the sync interval.
315 The default is -0.3.
316 pi_proportional_norm_max
318 The kp_norm_max constant in the formula used to set the propor‐
319 tional constant of the PI controller from the sync interval.
320 The default is 0.7
321 pi_integral_scale
323 The ki_scale constant in the formula used to set the integral
324 constant of the PI controller from the sync interval. When set
325 to 0.0, the value will be selected from 0.3 and 0.001 for the
326 hardware and software time stamping respectively. The default
327 is 0.0.
328 pi_integral_exponent
330 The ki_exponent constant in the formula used to set the integral
331 constant of the PI controller from the sync interval. The
332 default is 0.4.
333 pi_integral_norm_max
335 The ki_norm_max constant in the formula used to set the integral
336 constant of the PI controller from the sync interval. The
337 default is 0.3.
338 step_threshold
340 The maximum offset the servo will correct by changing the clock
341 frequency instead of stepping the clock. When set to 0.0, the
342 servo will never step the clock except on start. It's specified
343 in seconds. The default is 0.0. This option used to be called
344 pi_offset_const.
345 first_step_threshold
347 The maximum offset the servo will correct by changing the clock
348 frequency instead of stepping the clock. This is only applied on
349 the first update. It's specified in seconds. When set to 0.0,
350 the servo won't step the clock on start. The default is 0.00002
351 (20 microseconds). This option used to be called pi_f_off‐
352 set_const.
353 max_frequency
355 The maximum allowed frequency adjustment of the clock in parts
356 per billion (ppb). This is an additional limit to the maximum
357 allowed by the hardware. When set to 0, the hardware limit will
358 be used. The default is 900000000 (90%). This option used to
359 be called pi_max_frequency.
360 sanity_freq_limit
362 The maximum allowed frequency offset between uncorrected clock
363 and the system monotonic clock in parts per billion (ppb). This
364 is used as a sanity check of the synchronized clock. When a
365 larger offset is measured, a warning message will be printed and
366 the servo will be reset. When set to 0, the sanity check is dis‐
367 abled. The default is 200000000 (20%).
368 ntpshm_segment
370 The number of the SHM segment used by ntpshm servo. The default
371 is 0.
372 ptp_dst_mac
374 The MAC address where should be PTP messages sent. Relevant
375 only with L2 transport. The default is 01:1B:19:00:00:00.
376 p2p_dst_mac
378 The MAC address where should be peer delay messages the PTP
379 peer. Relevant only with L2 transport. The default is
380 01:80:C2:00:00:0E.
381 udp6_scope
383 Specifies the desired scope for the IPv6 multicast messages.
384 This will be used as the second byte of the primary address.
385 This option is only relevant with IPv6 transport. See RFC 4291.
386 The default is 0x0E for the global scope.
387 uds_address
389 Specifies the address of the UNIX domain socket for receiving
390 local management messages. The default is /var/run/ptp4l.
391 logging_level
393 The maximum logging level of messages which should be printed.
394 The default is 6 (LOG_INFO).
395 verbose
397 Print messages to the standard output if enabled. The default
398 is 0 (disabled).
399 use_syslog
401 Print messages to the system log if enabled. The default is 1
402 (enabled).
403 summary_interval
405 The time interval in which are printed summary statistics of the
406 clock. It is specified as a power of two in seconds. The statis‐
407 tics include offset root mean square (RMS), maximum absolute
408 offset, frequency offset mean and standard deviation, and path
409 delay mean and standard deviation. The units are nanoseconds and
410 parts per billion (ppb). If there is only one clock update in
411 the interval, the sample will be printed instead of the statis‐
412 tics. The messages are printed at the LOG_INFO level. The
413 default is 0 (1 second).
414 time_stamping
416 The time stamping method. The allowed values are hardware, soft‐
417 ware and legacy. The default is hardware.
418 productDescription
420 The product description string. Allowed values must be of the
421 form manufacturerName;modelNumber;instanceIdentifier and contain
422 at most 64 utf8 symbols. The default is ";;".
423 revisionData
425 The revision description string which contains the revisions for
426 node hardware (HW), firmware (FW), and software (SW). Allowed
427 values are of the form HW;FW;SW and contain at most 32 utf8 sym‐
428 bols. The default is an ";;".
429 userDescription
431 The user description string. Allowed values are of the form
432 name;location and contain at most 128 utf8 symbols. The default
433 is an empty string.
434 manufacturerIdentity
436 The manufacturer id which should be an OUI owned by the manufac‐
437 turer. The default is 00:00:00.
438 kernel_leap
440 When a leap second is announced, let the kernel apply it by
441 stepping the clock instead of correcting the one-second offset
442 with servo, which would correct the one-second offset slowly by
443 changing the clock frequency (unless the step_threshold option
444 is set to correct such offset by stepping). Relevant only with
445 software time stamping. The default is 1 (enabled).
446 timeSource
448 The time source is a single byte code that gives an idea of the
449 kind of local clock in use. The value is purely informational,
450 having no effect on the outcome of the Best Master Clock algo‐
451 rithm, and is advertised when the clock becomes grand master.
452
455 ptp4l as domain master either uses PTP or UTC time scale depending on
456 time stamping mode. In software and legacy time stamping modes it
457 announces Arbitrary time scale mode, which is effectively UTC here, in
458 hardware time stamping mode it announces use of PTP time scale.
459 When ptp4l is the domain master using hardware time stamping, it is up
461 to phc2sys to maintain the correct offset between UTC and PTP times.
462 See phc2sys(8) manual page for more details.
463
466 pmc(8), phc2sys(8)
467linuxptp December 2014 PTP4l(8)