Ubuntu Manpage: ptp4l - PTP Boundary/Ordinary Clock

NAME

       ptp4l - PTP Boundary/Ordinary Clock

SYNOPSIS

       ptp4l [ -AEP246HSLmqsv ] [ -f config ] [ -p phc-device ] [ -l print-level ] [ -i interface
       ] ...

DESCRIPTION

       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).

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 mechanism.

-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 stamping.

-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 characters. 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 specific  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 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).

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).

announceReceiptTimeout
The number of missed Announce messages before the last Announce messages expires.
The default is 3.

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.

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 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.

delay_mechanism
Select the delay mechanism. Possible values are E2E, P2P and Auto. The default is
E2E.

hybrid_e2e
Enables the "hybrid" delay mechanism from the draft Enterprise Profile. When
enabled, ports in the slave state send their delay request messages to the unicast
address taken from the master's announce message. Ports in the master state will
reply to unicast delay requests using unicast delay responses. This option has no
effect if the delay_mechanism is set to P2P. The default is 0 (disabled).

ptp_dst_mac
The MAC address to which PTP messages should be sent. Relevant only with L2
transport. The default is 01:1B:19:00:00:00.

p2p_dst_mac
The MAC address to which peer delay messages should be sent. Relevant only with L2
transport. The default is 01:80:C2:00:00:0E.

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.

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.

tsproc_mode
Select the time stamp processing mode used to calculate offset and delay. Possible
values are filter, raw, filter_weight, raw_weight. Raw modes perform well when the
rate of sync messages (logSyncInterval) is similar to the rate of delay messages
(logMinDelayReqInterval or logMinPdelayReqInterval). Weighting is useful with
larger network jitters (e.g. software time stamping). The default is filter.

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.

delay_filter_length
The length of the delay filter in samples. The default is 10.

egressLatency
Specifies the difference in nanoseconds between the actual transmission time at the
reference plane and the reported transmit time stamp. This value will be added to
egress time stamps obtained from the hardware. The default is 0.

ingressLatency
Specifies the difference in nanoseconds between the reported receive time stamp and
the actual reception time at reference plane. This value will be subtracted from
ingress time stamps obtained from the hardware. The default is 0.

boundary_clock_jbod
When running as a boundary clock (that is, when more than one network interface is
configured), ptp4l performs a sanity check to make sure that all of the ports share
the same hardware clock device. This option allows ptp4l to work as a boundary
clock using "just a bunch of devices" that are not synchronized to each other. For
this mode, the collection of clocks must be synchronized by an external program,
for example phc2sys(8) in "automatic" mode. The default is 0 (disabled).

udp_ttl
Specifies the Time to live (TTL) value for IPv4 multicast messages and the hop
limit for IPv6 multicast messages. This option is only relevant with the IPv4 and
IPv6 UDP transports. The default is 1 to restrict the messages sent by ptp4l to the
same subnet.

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. This option is only for use with
1588 clocks and should not be enabled for 802.1AS clocks. The default is 0
(disabled).

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).

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 (disabled).

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 (disabled).

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.

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).

clock_servo
The servo which is used to synchronize the local clock. Valid values are "pi" for a
PI controller, "linreg" for an adaptive controller using linear regression,
"ntpshm" for the NTP SHM reference clock to allow another process to synchronize
the local clock (the SHM segment number is set to the domain number), and "nullf"
for a servo that always dials frequency offset zero (for use in SyncE nodes). 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 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.

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.

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

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.

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 pi_offset_const.

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.00002 (20 microseconds). This option used to be called pi_f_offset_const.

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 pi_max_frequency.

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%).

ntpshm_segment
The number of the SHM segment used by ntpshm servo. The default is 0.

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.

uds_address
Specifies the address of the UNIX domain socket for receiving local management
messages. The default is /var/run/ptp4l.

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 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).

time_stamping
The time stamping method. The allowed values are hardware, software 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 symbols. 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 manufacturer. 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 step_threshold
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 algorithm, and is advertised when the clock becomes grand master.

TIME SCALE USAGE

       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  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.