PTP4l(8)PTP4l(8)NAMEptp4l - PTP Boundary/Ordinary Clock
SYNOPSISptp4l [ -AEP246HSLmqsv ] [ -f config ] [ -p phc-device ] [ -l print-
level ] [ -i interface ] ...
DESCRIPTIONptp4l is an implementation of the Precision Time Protocol (PTP) accord‐
ing to IEEE standard 1588 for Linux. It implements Boundary Clock (BC)
and Ordinary Clock (OC).
OPTIONS-A Select the delay mechanism automatically. Start with E2E and
switch to P2P when a peer delay request is received.
-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.
-P Select the peer delay (P2P) mechanism. A warning will be printed
when a delay request is received on port using the P2P mecha‐
nism.
-2 Select the IEEE 802.3 network transport.
-4 Select the UDP IPv4 network transport. This is the default
transport.
-6 Select the UDP IPv6 network transport.
-H Select the hardware time stamping. All ports specified by the -i
option and in the configuration file must be attached to the
same PTP hardware clock (PHC). This is the default time stamp‐
ing.
-S Select the software time stamping.
-L Select the legacy hardware time stamping.
-f config
Read configuration from the specified file. No configuration
file is read by default.
-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.
-p phc-device
With hardware time stamping, force which PHC device (e.g.
/dev/ptp0) should be used.
-s Enable the slaveOnly mode.
-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).
-m Print messages to the standard output.
-q Don't send messages to the system logger.
-v Prints the software version and exits.
-h Display a help message.
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 charac‐
ters. Empty lines and lines starting with # are ignored.
The global section (indicated as [global]) sets the program options,
clock options and default port options. Other sections are port spe‐
cific sections and they override the default port options. The name of
the section is the name of the configured port (e.g. [eth0]). Ports
specified in the configuration file don't need to be specified by the
-i option. An empty port section can be used to replace the command
line option.
PORT OPTIONS
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.
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).
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).
logMinDelayReqInterval
The minimum permitted mean time interval between Delay_Req mes‐
sages. 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).
logMinPdelayReqInterval
The minimum permitted mean time interval between Pdelay_Req mes‐
sages. It's specified as a power of two in seconds. The default
is 0 (1 second).
announceReceiptTimeout
The number of missed Announce messages before the last Announce
messages expires. The default is 3.
transportSpecific
The transport specific field. Must be in the range 0 to 255.
The default is 0.
path_trace_enabled
Enable the mechanism used to trace the route of the Announce
messages. The default is 0 (disabled).
follow_up_info
Include the 802.1AS data in the Follow_Up messages if enabled.
The default is 0 (disabled).
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).
fault_badpeernet_interval
The time in seconds between the detection of a peer network mis‐
configuration 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 immedi‐
ately. The default is 16 seconds.
delay_mechanism
Select the delay mechanism. Possible values are E2E, P2P and
Auto. The default is E2E.
network_transport
Select the network transport. Possible values are UDPv4, UDPv6
and L2. The default is UDPv4.
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.
PROGRAM AND CLOCK OPTIONS
twoStepFlag
Enable two-step mode for sync messages. One-step mode can be
used only with hardware time stamping. The default is 1
(enabled).
slaveOnly
The local clock is a slave-only clock if enabled. The default
is 0 (disabled).
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.
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.
clockClass
The clockClass attribute of the local clock. It denotes the
traceability of the time distributed by the grandmaster clock.
The default is 248.
clockAccuracy
The clockAccuracy attribute of the local clock. It is used in
the best master selection algorithm. The default is 0xFE.
offsetScaledLogVariance
The offsetScaledLogVariance attribute of the local clock. It
characterizes the stability of the clock. The default is
0xFFFF.
domainNumber
The domain attribute of the local clock. The default is 0.
free_running
Don't adjust the local clock if enabled. The default is 0 (dis‐
abled).
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).
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 (dis‐
abled).
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.
clock_servo
The servo which is used to synchronize the local clock. Cur‐
rently only one servo is implemented, a PI controller. The
default is pi.
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))
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)
pi_proportional_scale
The kp_scale constant in the formula used to set the propor‐
tional 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.
pi_proportional_exponent
The kp_exponent constant in the formula used to set the propor‐
tional constant of the PI controller from the sync interval.
The default is -0.3.
pi_proportional_norm_max
The kp_norm_max constant in the formula used to set the propor‐
tional constant of the PI controller from the sync interval.
The default is 0.7
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.
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.
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.
pi_offset_const
The maximum offset the PI controller will correct by changing
the clock frequency instead of stepping the clock. When set to
0.0, the controller will never step the clock except on start.
The default is 0.0.
pi_f_offset_const
The maximum offset the PI controller will correct by changing
the clock frequency instead of stepping the clock. This is only
applied on the first update. When set to 0.0, the controller
won't step the clock on start. The default is 0.0000001 (100
nanoseconds).
pi_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%).
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.
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.
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.
logging_level
The maximum logging level of messages which should be printed.
The default is 6 (LOG_INFO).
verbose
Print messages to the standard output if enabled. The default
is 0 (disabled).
use_syslog
Print messages to the system log if enabled. The default is 1
(enabled).
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 statis‐
tics 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 statis‐
tics. The messages are printed at the LOG_INFO level. The
default is 0 (1 second).
time_stamping
The time stamping method. The allowed values are hardware, soft‐
ware and legacy. The default is hardware.
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 ";;".
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 sym‐
bols. The default is an ";;".
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.
manufacturerIdentity
The manufacturer id which should be an OUI owned by the manufac‐
turer. The default is 00:00:00.
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 pi_offset_const option
is set to correct such offset by stepping). Relevant only with
software time stamping. The default is 1 (enabled).
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 algo‐
rithm, and is advertised when the clock becomes grand master.
TIME SCALE USAGEptp4l 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 ptp4l is the domain master using hardware time stamping, it is up
to phc2sys to maintain the correct offset between UTC and PTP times.
See phc2sys(8) manual page for more details.
SEE ALSOpmc(8), phc2sys(8)linuxptp July 2013 PTP4l(8)
