474 lines
16 KiB
Groff
474 lines
16 KiB
Groff
.TH PTP4l 8 "October 2013" "linuxptp"
|
|
.SH NAME
|
|
ptp4l \- PTP Boundary/Ordinary Clock
|
|
|
|
.SH SYNOPSIS
|
|
.B ptp4l
|
|
[
|
|
.B \-AEP246HSLmqsv
|
|
] [
|
|
.BI \-f " config"
|
|
] [
|
|
.BI \-p " phc-device"
|
|
] [
|
|
.BI \-l " print-level"
|
|
]
|
|
[
|
|
.BI \-i " interface"
|
|
]
|
|
.I .\|.\|.
|
|
|
|
.SH DESCRIPTION
|
|
.B ptp4l
|
|
is an implementation of the Precision Time Protocol (PTP) according to IEEE
|
|
standard 1588 for Linux. It implements Boundary Clock (BC) and Ordinary Clock
|
|
(OC).
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-A
|
|
Select the delay mechanism automatically. Start with E2E and switch to P2P when
|
|
a peer delay request is received.
|
|
.TP
|
|
.B \-E
|
|
Select the delay request-response (E2E) mechanism. This is the default
|
|
mechanism. All clocks on single PTP communication path must use the same
|
|
mechanism. A warning will be printed when a peer delay request is received on
|
|
port using the E2E mechanism.
|
|
.TP
|
|
.B \-P
|
|
Select the peer delay (P2P) mechanism. A warning will be printed when a delay
|
|
request is received on port using the P2P mechanism.
|
|
.TP
|
|
.B \-2
|
|
Select the IEEE 802.3 network transport.
|
|
.TP
|
|
.B \-4
|
|
Select the UDP IPv4 network transport. This is the default transport.
|
|
.TP
|
|
.B \-6
|
|
Select the UDP IPv6 network transport.
|
|
.TP
|
|
.B \-H
|
|
Select the hardware time stamping. All ports specified by the
|
|
.B \-i
|
|
option and in the configuration file must be attached to the same PTP hardware
|
|
clock (PHC). This is the default time stamping.
|
|
.TP
|
|
.B \-S
|
|
Select the software time stamping.
|
|
.TP
|
|
.B \-L
|
|
Select the legacy hardware time stamping.
|
|
.TP
|
|
.BI \-f " config"
|
|
Read configuration from the specified file. No configuration file is read by
|
|
default.
|
|
.TP
|
|
.BI \-i " interface"
|
|
Specify a PTP port, it may be used multiple times. At least one port must be
|
|
specified by this option or in the configuration file.
|
|
.TP
|
|
.BI \-p " phc-device"
|
|
With hardware time stamping, force which PHC device (e.g. /dev/ptp0) should be
|
|
used.
|
|
.TP
|
|
.B \-s
|
|
Enable the slaveOnly mode.
|
|
.TP
|
|
.BI \-l " print-level"
|
|
Set the maximum syslog level of messages which should be printed or sent to
|
|
the system logger. The default is 6 (LOG_INFO).
|
|
.TP
|
|
.B \-m
|
|
Print messages to the standard output.
|
|
.TP
|
|
.B \-q
|
|
Don't send messages to the system logger.
|
|
.TP
|
|
.B \-v
|
|
Prints the software version and exits.
|
|
.TP
|
|
.BI \-h
|
|
Display a help message.
|
|
|
|
.SH CONFIGURATION FILE
|
|
|
|
The configuration file is divided into sections. Each section starts with a
|
|
line containing its name enclosed in brackets and it follows with settings.
|
|
Each setting is placed on a separate line, it contains the name of the
|
|
option and the value separated by whitespace characters. Empty lines and lines
|
|
starting with # are ignored.
|
|
|
|
The global section (indicated as
|
|
.BR [global] )
|
|
sets the program options, clock options and default port options. Other
|
|
sections are port specific sections and they override the default port options.
|
|
The name of the section is the name of the configured port (e.g.
|
|
.BR [eth0] ).
|
|
Ports specified in the configuration file don't need to be
|
|
specified by the
|
|
.B \-i
|
|
option. An empty port section can be used to replace the command line option.
|
|
|
|
.SH PORT OPTIONS
|
|
|
|
.TP
|
|
.B delayAsymmetry
|
|
The time difference in nanoseconds of the transmit and receive
|
|
paths. This value should be positive when the master-to-slave
|
|
propagation time is longer and negative when the slave-to-master time
|
|
is longer. The default is 0 nanoseconds.
|
|
.TP
|
|
.B logAnnounceInterval
|
|
The mean time interval between Announce messages. A shorter interval makes
|
|
ptp4l react faster to the changes in the master-slave hierarchy. The interval
|
|
should be the same in the whole domain. It's specified as a power of two in
|
|
seconds.
|
|
The default is 1 (2 seconds).
|
|
.TP
|
|
.B logSyncInterval
|
|
The mean time interval between Sync messages. A shorter interval may improve
|
|
accuracy of the local clock. It's specified as a power of two in seconds.
|
|
The default is 0 (1 second).
|
|
.TP
|
|
.B logMinDelayReqInterval
|
|
The minimum permitted mean time interval between Delay_Req messages. A shorter
|
|
interval makes ptp4l react faster to the changes in the path delay. It's
|
|
specified as a power of two in seconds.
|
|
The default is 0 (1 second).
|
|
.TP
|
|
.B logMinPdelayReqInterval
|
|
The minimum permitted mean time interval between Pdelay_Req messages. It's
|
|
specified as a power of two in seconds.
|
|
The default is 0 (1 second).
|
|
.TP
|
|
.B announceReceiptTimeout
|
|
The number of missed Announce messages before the last Announce messages
|
|
expires.
|
|
The default is 3.
|
|
.TP
|
|
.B syncReceiptTimeout
|
|
The number of sync/follow up messages that may go missing before
|
|
triggering a Best Master Clock election. This option is used for
|
|
running in gPTP mode according to the 802.1AS-2011 standard. Setting
|
|
this option to zero will disable the sync message timeout.
|
|
The default is 0 or disabled.
|
|
.TP
|
|
.B transportSpecific
|
|
The transport specific field. Must be in the range 0 to 255.
|
|
The default is 0.
|
|
.TP
|
|
.B path_trace_enabled
|
|
Enable the mechanism used to trace the route of the Announce messages.
|
|
The default is 0 (disabled).
|
|
.TP
|
|
.B follow_up_info
|
|
Include the 802.1AS data in the Follow_Up messages if enabled.
|
|
The default is 0 (disabled).
|
|
.TP
|
|
.B fault_reset_interval
|
|
The time in seconds between the detection of a port's fault and the fault
|
|
being reset. This value is expressed as a power of two. Setting this
|
|
value to -128 or to the special key word "ASAP" will let the fault be
|
|
reset immediately.
|
|
The default is 4 (16 seconds).
|
|
.TP
|
|
.B fault_badpeernet_interval
|
|
The time in seconds between the detection of a peer network misconfiguration
|
|
and the fault being reset. The port is disabled for the duration of the
|
|
interval. The value is in seconds and the special key word ASAP will let
|
|
the fault be reset immediately.
|
|
The default is 16 seconds.
|
|
.TP
|
|
.B delay_mechanism
|
|
Select the delay mechanism. Possible values are E2E, P2P and Auto.
|
|
The default is E2E.
|
|
.TP
|
|
.B network_transport
|
|
Select the network transport. Possible values are UDPv4, UDPv6 and L2.
|
|
The default is UDPv4.
|
|
.TP
|
|
.B neighborPropDelayThresh
|
|
Upper limit for peer delay in nanoseconds. If the estimated peer delay is
|
|
greater than this value the port is marked as not 802.1AS capable.
|
|
.TP
|
|
.B min_neighbor_prop_delay
|
|
Lower limit for peer delay in nanoseconds. If the estimated peer delay is
|
|
smaller than this value the port is marked as not 802.1AS capable.
|
|
.TP
|
|
.B delay_filter
|
|
Select the algorithm used to filter the measured delay and peer delay. Possible
|
|
values are moving_average and moving_median.
|
|
The default is moving_median.
|
|
.TP
|
|
.B delay_filter_length
|
|
The length of the delay filter in samples.
|
|
The default is 10.
|
|
|
|
.SH PROGRAM AND CLOCK OPTIONS
|
|
|
|
.TP
|
|
.B twoStepFlag
|
|
Enable two-step mode for sync messages. One-step mode can be used only with
|
|
hardware time stamping.
|
|
The default is 1 (enabled).
|
|
.TP
|
|
.B slaveOnly
|
|
The local clock is a slave-only clock if enabled.
|
|
This option is only for use with 1588 clocks and should not be enabled
|
|
for 802.1AS clocks.
|
|
The default is 0 (disabled).
|
|
.TP
|
|
.B gmCapable
|
|
If this option is enabled, then the local clock is able to become grand master.
|
|
This is only for use with 802.1AS clocks and has no effect on 1588 clocks.
|
|
The default is 1 (enabled).
|
|
.TP
|
|
.B priority1
|
|
The priority1 attribute of the local clock. It is used in the best master
|
|
selection algorithm, lower values take precedence. Must be in the range 0 to
|
|
255.
|
|
The default is 128.
|
|
.TP
|
|
.B priority2
|
|
The priority2 attribute of the local clock. It is used in the best master
|
|
selection algorithm, lower values take precedence. Must be in the range 0 to
|
|
255.
|
|
The default is 128.
|
|
.TP
|
|
.B clockClass
|
|
The clockClass attribute of the local clock. It denotes the traceability of the
|
|
time distributed by the grandmaster clock.
|
|
The default is 248.
|
|
.TP
|
|
.B clockAccuracy
|
|
The clockAccuracy attribute of the local clock. It is used in the best master
|
|
selection algorithm.
|
|
The default is 0xFE.
|
|
.TP
|
|
.B offsetScaledLogVariance
|
|
The offsetScaledLogVariance attribute of the local clock. It characterizes the
|
|
stability of the clock.
|
|
The default is 0xFFFF.
|
|
.TP
|
|
.B domainNumber
|
|
The domain attribute of the local clock.
|
|
The default is 0.
|
|
.TP
|
|
.B free_running
|
|
Don't adjust the local clock if enabled.
|
|
The default is 0 (disabled).
|
|
.TP
|
|
.B freq_est_interval
|
|
The time interval over which is estimated the ratio of the local and
|
|
peer clock frequencies. It is specified as a power of two in seconds.
|
|
The default is 1 (2 seconds).
|
|
.TP
|
|
.B assume_two_step
|
|
Treat one-step responses as two-step if enabled. It is used to work around
|
|
buggy 802.1AS switches.
|
|
The default is 0 (disabled).
|
|
.TP
|
|
.B tx_timestamp_timeout
|
|
The number of milliseconds to poll waiting for the tx time stamp from the kernel
|
|
when a message has recently been sent.
|
|
The default is 1.
|
|
.TP
|
|
.B check_fup_sync
|
|
Because of packet reordering that can occur in the network, in the
|
|
hardware, or in the networking stack, a follow up message can appear
|
|
to arrive in the application before the matching sync message. As this
|
|
is a normal occurrence, and the sequenceID message field ensures
|
|
proper matching, the ptp4l program accepts out of order packets. This
|
|
option adds an additional check using the software time stamps from
|
|
the networking stack to verify that the sync message did arrive
|
|
first. This option is only useful if you do not trust the sequence IDs
|
|
generated by the master.
|
|
The default is 0 (disabled).
|
|
.TP
|
|
.B clock_servo
|
|
The servo which is used to synchronize the local clock. Currently only one
|
|
servo is implemented, a PI controller.
|
|
The default is pi.
|
|
.TP
|
|
.B pi_proportional_const
|
|
The proportional constant of the PI controller. When set to 0.0, the
|
|
proportional constant will be set by the following formula from the current
|
|
sync interval.
|
|
The default is 0.0.
|
|
|
|
kp = min(kp_scale * sync^kp_exponent, kp_norm_max / sync))
|
|
.TP
|
|
.B pi_integral_const
|
|
The integral constant of the PI controller. When set to 0.0, the
|
|
integral constant will be set by the following formula from the current
|
|
sync interval.
|
|
The default is 0.0.
|
|
|
|
ki = min(ki_scale * sync^ki_exponent, ki_norm_max / sync)
|
|
.TP
|
|
.B pi_proportional_scale
|
|
The kp_scale constant in the formula used to set the proportional constant of
|
|
the PI controller from the sync interval. When set to 0.0, the value will be
|
|
selected from 0.7 and 0.1 for the hardware and software time stamping
|
|
respectively.
|
|
The default is 0.0.
|
|
.TP
|
|
.B pi_proportional_exponent
|
|
The kp_exponent constant in the formula used to set the proportional constant of
|
|
the PI controller from the sync interval.
|
|
The default is -0.3.
|
|
.TP
|
|
.B pi_proportional_norm_max
|
|
The kp_norm_max constant in the formula used to set the proportional constant of
|
|
the PI controller from the sync interval.
|
|
The default is 0.7
|
|
.TP
|
|
.B pi_integral_scale
|
|
The ki_scale constant in the formula used to set the integral constant of
|
|
the PI controller from the sync interval. When set to 0.0, the value will be
|
|
selected from 0.3 and 0.001 for the hardware and software time stamping
|
|
respectively.
|
|
The default is 0.0.
|
|
.TP
|
|
.B pi_integral_exponent
|
|
The ki_exponent constant in the formula used to set the integral constant of
|
|
the PI controller from the sync interval.
|
|
The default is 0.4.
|
|
.TP
|
|
.B pi_integral_norm_max
|
|
The ki_norm_max constant in the formula used to set the integral constant of
|
|
the PI controller from the sync interval.
|
|
The default is 0.3.
|
|
.TP
|
|
.B step_threshold
|
|
The maximum offset the servo will correct by changing the clock
|
|
frequency instead of stepping the clock. When set to 0.0, the servo will
|
|
never step the clock except on start. It's specified in seconds.
|
|
The default is 0.0.
|
|
This option used to be called (and can still be set by)
|
|
.BR pi_offset_const .
|
|
.TP
|
|
.B first_step_threshold
|
|
The maximum offset the servo will correct by changing the clock
|
|
frequency instead of stepping the clock. This is only applied on the first
|
|
update. It's specified in seconds. When set to 0.0, the servo won't step
|
|
the clock on start.
|
|
The default is 0.0000001 (100 nanoseconds).
|
|
This option used to be called (and can still be set by)
|
|
.BR pi_f_offset_const .
|
|
.TP
|
|
.B max_frequency
|
|
The maximum allowed frequency adjustment of the clock in parts per billion
|
|
(ppb). This is an additional limit to the maximum allowed by the hardware. When
|
|
set to 0, the hardware limit will be used.
|
|
The default is 900000000 (90%).
|
|
This option used to be called (and can still be set by)
|
|
.BR pi_max_frequency .
|
|
.TP
|
|
.B sanity_freq_limit
|
|
The maximum allowed frequency offset between uncorrected clock and the system
|
|
monotonic clock in parts per billion (ppb). This is used as a sanity check of
|
|
the synchronized clock. When a larger offset is measured, a warning message
|
|
will be printed and the servo will be reset. When set to 0, the sanity check is
|
|
disabled. The default is 200000000 (20%).
|
|
.TP
|
|
.B ptp_dst_mac
|
|
The MAC address where should be PTP messages sent.
|
|
Relevant only with L2 transport. The default is 01:1B:19:00:00:00.
|
|
.TP
|
|
.B p2p_dst_mac
|
|
The MAC address where should be peer delay messages the PTP peer.
|
|
Relevant only with L2 transport. The default is 01:80:C2:00:00:0E.
|
|
.TP
|
|
.B udp6_scope
|
|
Specifies the desired scope for the IPv6 multicast messages. This
|
|
will be used as the second byte of the primary address. This option
|
|
is only relevant with IPv6 transport. See RFC 4291. The default is
|
|
0x0E for the global scope.
|
|
.TP
|
|
.B uds_address
|
|
Specifies the address of the UNIX domain socket for receiving local
|
|
management messages. The default is /var/run/ptp4l.
|
|
.TP
|
|
.B logging_level
|
|
The maximum logging level of messages which should be printed.
|
|
The default is 6 (LOG_INFO).
|
|
.TP
|
|
.B verbose
|
|
Print messages to the standard output if enabled.
|
|
The default is 0 (disabled).
|
|
.TP
|
|
.B use_syslog
|
|
Print messages to the system log if enabled.
|
|
The default is 1 (enabled).
|
|
.TP
|
|
.B summary_interval
|
|
The time interval in which are printed summary statistics of the clock. It is
|
|
specified as a power of two in seconds. The statistics include offset root mean
|
|
square (RMS), maximum absolute offset, frequency offset mean and standard
|
|
deviation, and path delay mean and standard deviation. The units are
|
|
nanoseconds and parts per billion (ppb). If there is only one clock update in
|
|
the interval, the sample will be printed instead of the statistics. The
|
|
messages are printed at the LOG_INFO level.
|
|
The default is 0 (1 second).
|
|
.TP
|
|
.B time_stamping
|
|
The time stamping method. The allowed values are hardware, software and legacy.
|
|
The default is hardware.
|
|
.TP
|
|
.B productDescription
|
|
The product description string. Allowed values must be of the form
|
|
manufacturerName;modelNumber;instanceIdentifier and contain at most 64
|
|
utf8 symbols. The default is ";;".
|
|
.TP
|
|
.B revisionData
|
|
The revision description string which contains the revisions for node
|
|
hardware (HW), firmware (FW), and software (SW). Allowed values are of
|
|
the form HW;FW;SW and contain at most 32 utf8 symbols. The default is
|
|
an ";;".
|
|
.TP
|
|
.B userDescription
|
|
The user description string. Allowed values are of the form
|
|
name;location and contain at most 128 utf8 symbols. The default is an
|
|
empty string.
|
|
.TP
|
|
.B manufacturerIdentity
|
|
The manufacturer id which should be an OUI owned by the manufacturer.
|
|
The default is 00:00:00.
|
|
.TP
|
|
.B kernel_leap
|
|
When a leap second is announced, let the kernel apply it by stepping the clock
|
|
instead of correcting the one-second offset with servo, which would correct the
|
|
one-second offset slowly by changing the clock frequency (unless the
|
|
.B step_threshold
|
|
option is set to correct such offset by stepping).
|
|
Relevant only with software time stamping. The default is 1 (enabled).
|
|
.TP
|
|
.B timeSource
|
|
The time source is a single byte code that gives an idea of the kind
|
|
of local clock in use. The value is purely informational, having no
|
|
effect on the outcome of the Best Master Clock algorithm, and is
|
|
advertised when the clock becomes grand master.
|
|
|
|
.SH TIME SCALE USAGE
|
|
|
|
.B ptp4l
|
|
as domain master either uses PTP or UTC time scale depending on time stamping
|
|
mode. In software and legacy time stamping modes it announces Arbitrary time
|
|
scale mode, which is effectively UTC here, in hardware time stamping mode it
|
|
announces use of PTP time scale.
|
|
|
|
When
|
|
.B ptp4l
|
|
is the domain master using hardware time stamping, it is up to
|
|
.B phc2sys
|
|
to maintain the correct offset between UTC and PTP times. See
|
|
.BR phc2sys (8)
|
|
manual page for more details.
|
|
|
|
.SH SEE ALSO
|
|
.BR pmc (8),
|
|
.BR phc2sys (8)
|