.TH PTP4l 8 "April 2018" "linuxptp"

.SH NAME

ptp4l - PTP Boundary/Ordinary/Transparent Clock

.SH SYNOPSIS

.B ptp4l

[

.B \-AEP246HSLmqsv

] [

.BI \-f " config"

] [

.BI \-p " phc-device"

] [

.BI \-l " print-level"

]

[

.BI \-i " interface"

] [

.I long-options

]

.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), Ordinary Clock

(OC), and Transparent Clock (TC).

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

(This option is deprecated.)

Before Linux kernel v3.5 there was no way to discover the PHC device

associated with a network interface.  This option specifies the PHC

device (e.g. /dev/ptp0) to be used when running on legacy kernels.

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

Each and every configuration file option (see below) may also appear

as a "long" style command line argument.  For example, the slaveOnly

option may be set using either of these two forms.

.RS

\f(CW\-\-slaveOnly 1   \-\-slaveOnly=1\fP

.RE

Option values given on the command line override values in the global

section of the configuration file.

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

There are three different section types.

.TP

.B 1.

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.

.TP

.B 2.

Port sections give 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.

.TP

.B 3.

Tables for configuring unicast discovery begin with

.B \%[unicast_master_table].

See UNICAST DISCOVERY OPTIONS, below.

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

By default, incoming messages are dropped if their transportSpecific

field does not match the configured value.  However, many of

transports specified in the 1588 standard mandate ignoring this field.

Moreover, some equipment is known to set the reserved bits.

Configuring this option as 1 causes this field to be ignored

completely on receive.  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 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).

.TP

.B inhibit_multicast_service

Some unicast mode profiles insist that no multicast message are ever

transmitted.  Setting this option inhibits multicast transmission.

The default is 0 (mutlicast enabled).

.TP

.B net_sync_monitor

Enables the NetSync Monitor (NSM) protocol. The NSM protocol allows a

station to measure how well another node is synchronized. The monitor

sends a unicast delay request to the node, which replies

unconditionally with unicast delay response, sync, and follow up

messages. If the monitor is synchronized to the GM, it can use the

time stamps in the message to estimate the node's offset.  This option

requires that the 'hybrid_e2e' option be enabled as well.

The default is 0 (disabled).

.TP

.B unicast_listen

When enabled, this option allows the port to grant unicast message

contracts.  Incoming requests for will be granted limited only by the

amount of memory available.

The default is 0 (disabled).

.TP

.B unicast_master_table

When set to a positive integer, this option specifies the table id to

be used for unicast discovery.  Each table lives in its own section

and has a unique, positive numerical ID.  Entries in the table are a

pair of transport type and protocol address.  Tables may not be shared

between ports, but nothing prevents table entries from appearing in

more than table.

The default is 0 (unicast discovery disabled).

.TP

.B unicast_req_duration

The service time in seconds to be requested during unicast discovery.

Note that the remote node is free to grant a different duration.

The default is 3600 seconds or one hour.

.TP

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

.TP

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

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

Setting this option to one (1) prevents the port from entering the

SLAVE state. In addition, the local clock will ignore Announce

messages received on this port. This option's intended use is to

support the Telecom Profiles according to ITU-T G.8265.1, G.8275.1,

and G.8275.2. The default value is zero or false.

.TP

.B G.8275.portDS.localPriority

The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an

alternate Best Master Clock Algorithm (BMCA) with a unique data set

comparison algorithm.  The value of this option is associated with

Announce messages arriving on a particular port and is used as a tie

breaker whenever clockClass, clockAccuracy, offsetScaledLogVariance,

and priority2 are equal. This option is only used when

"dataset_comparison" is set to "telecom".

The default value is 128.

Warning: the BMCA is guaranteed to produce a spanning tree (that is, a

timing network without loops) only when using the default values of

G.8275.defaultDS.localPriority and G.8275.portDS.localPriority.

Careful network engineering is needed when using non-default values.

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

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

.TP

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

.TP

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

.TP

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

.TP

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

.B ptp4l

to the same subnet.

.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 G.8275.defaultDS.localPriority

The Telecom Profiles (ITU-T G.8275.1 and G.8275.2) specify an

alternate Best Master Clock Algorithm (BMCA) with a unique data set

comparison algorithm.  The value of this option is associated with the

local clock and is used as a tie breaker whenever clockClass,

clockAccuracy, offsetScaledLogVariance, and priority2 are equal. This

option is only used when "dataset_comparison" is set to "telecom".

The default value is 128.

Warning: the BMCA is guaranteed to produce a spanning tree (that is, a

timing network without loops) only when using the default values of

G.8275.defaultDS.localPriority and G.8275.portDS.localPriority.

Careful network engineering is needed when using non-default values.

.TP

.B domainNumber

The domain attribute of the local clock.

The default is 0.

.TP

.B utc_offset

The current offset between TAI and UTC.

The default is 37.

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

When running as a Transparent Clock, increment the "stepsRemoved"

field of Announce messages that pass through the switch.  Enabling

this option ensures that PTP message loops never form, provided the

switches all implement this option together with the BMCA.

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

.TP

.B clock_type

Specifies the kind of PTP clock.  Valid values are "OC" for ordinary

clock, "BC" for boundary clock, "P2P_TC" for peer to peer transparent

clock, and "E2E_TC" for end to end transparent clock.  An multi-port

ordinary clock will automatically be configured as a boundary clock.

The default is "OC".

.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

.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.00002 (20 microseconds).

This option used to be called

.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

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

The initial path delay of the clock in nanoseconds used for synchronization of

the clock before the delay is measured using the E2E or P2P delay mechanism. If

set to 0, the clock will not be updated until the delay is measured.

The default is 0.

.TP

.B ntpshm_segment

The number of the SHM segment used by ntpshm servo.

The default is 0.

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

Defines the Differentiated Services Codepoint (DSCP) to be used for PTP

event messages. Must be a value between 0 and 63. There are several media

streaming standards out there that require specific values for this option.

For example 46 (EF PHB) in AES67 or 48 (CS6 PHB) in RAVENNA. The default

is 0.

.TP

.B dscp_general

Defines the Differentiated Services Codepoint (DSCP) to be used for PTP

general messages. Must be a value between 0 and 63. There are several media

streaming standards out there that recommend specific values for this option.

For example 34 (AF41 PHB) in AES67 or 46 (EF PHB) in RAVENNA. The default

is 0.

.TP

.B dataset_comparison

Specifies the method to be used when comparing data sets during the

Best Master Clock Algorithm.  The possible values are "ieee1588" and

"G.8275.x".  The default is "ieee1588".

.TP

.B logging_level

The maximum logging level of messages which should be printed.

The default is 6 (LOG_INFO).

.TP

.B message_tag

The tag which is added to all messages printed to the standard output or system

log.

The default is an empty string (which cannot be set in the configuration file

as the option requires an argument).

.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 UNICAST DISCOVERY OPTIONS

.TP

.B table_id

Each table must begin with a unique, positive table ID.  The port that

claims a given table does so by including the ID as the value of

its 'unicast_master_table' option.

.TP

.B logQueryInterval

This option configures the time to wait between unicast negotiation

attempts.  It is specified as a power of two in seconds.

The default is 0 (1 second).

.TP

.B peer_address

This option specifies the unicast address of the peer for use with the

peer to peer delay mechanism.  If specified, the port owning the table

will negotiate unicast peer delay responses from the machine at the

given remote address, otherwise the port will send multicast peer

delay requests.

.TP

.B L2|UDPv4

Each table entry specifies the transport type and network address of a

potential remote master.  If multiple masters are specified, then

unicast negotiation will be performed with each if them.

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