Provided by: linuxptp_1.8-1ubuntu0.1_amd64 bug

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

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

       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.

       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.

       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.

SEE ALSO

       pmc(8), phc2sys(8)