Signed-off-by: Richard Cochran <richardcoch...@gmail.com> --- ptp4l.8 | 1125 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 618 insertions(+), 507 deletions(-)
diff --git a/ptp4l.8 b/ptp4l.8 index 8b477f0..484793e 100644 --- a/ptp4l.8 +++ b/ptp4l.8 @@ -142,93 +142,68 @@ See UNICAST DISCOVERY OPTIONS, below. .SH PORT OPTIONS +.TP +.B announceReceiptTimeout +The number of missed Announce messages before the last Announce messages +expires. +The default is 3. + +.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 delayAsymmetry The time difference in nanoseconds of the transmit and receive paths. This value should be positive when the server-to-client propagation time is longer and negative when the client-to-server 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 client/server 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 operLogSyncInterval -The Sync message interval to be requested once the clock enters the -SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option is -set, then the local client port will request the remote server to -switch to the given message rate via a signaling message containing a -Message interval request TLV. This option is specified as a power of -two in seconds, and default value 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 operLogPdelayReqInterval -The Pdelay Request messages interval to be used once the clock enters -the SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option -is set, then the local client port will adopt this rate when the local -clock enters the "locked stable" state. This option is specified as a -power of two in seconds, and the default value is 0 (1 second). -.TP -.B inhibit_delay_req -Don't send any delay requests. This will need the asCapable config option to be -set to 'true'. This is useful when running as a designated server who does not -need to calculate offset from client. The default is 0 (disabled). +.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 announceReceiptTimeout -The number of missed Announce messages before the last Announce messages -expires. -The default is 3. +.B delay_filter_length +The length of the delay filter in samples. +The default is 10. + .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. +.B delay_mechanism +Select the delay mechanism. Possible values are E2E, P2P, NONE and Auto. +The default is E2E. + .TP .B delay_response_timeout The number of delay response messages that may go missing before triggering a synchronization fault. Setting this option to zero will disable the delay response timeout. The default is 0 or disabled. + .TP -.B transportSpecific -The transport specific field. Must be in the range 0 to 255. +.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 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). +.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 fault_reset_interval The time in seconds between the detection of a port's fault and the fault @@ -236,17 +211,28 @@ 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. +.B follow_up_info +Include the 802.1AS data in the Follow_Up messages if enabled. +The default is 0 (disabled). + .TP -.B delay_mechanism -Select the delay mechanism. Possible values are E2E, P2P, NONE and Auto. -The default is E2E. +.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 "G.8275.x". +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 hybrid_e2e Enables the "hybrid" delay mechanism from the draft Enterprise @@ -256,124 +242,115 @@ announce message. Ports in the server 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 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 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 inhibit_delay_req +Don't send any delay requests. This will need the asCapable config option to be +set to 'true'. This is useful when running as a designated server who does not +need to calculate offset from client. 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. -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. +.B logAnnounceInterval +The mean time interval between Announce messages. A shorter interval makes +ptp4l react faster to the changes in the client/server 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 network_transport -Select the network transport. Possible values are UDPv4, UDPv6 and L2. -The default is UDPv4. +.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 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. +.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 serverOnly -Setting this option to one (1) prevents the port from entering the -client 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. +.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 masterOnly This option is deprecated and will be removed in a future release. Use "serverOnly" instead. -.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 "G.8275.x". -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. +.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 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. +.B network_transport +Select the network transport. Possible values are UDPv4, UDPv6 and L2. +The default is UDPv4. + .TP -.B delay_filter_length -The length of the delay filter in samples. -The default is 10. +.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 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. +.B operLogPdelayReqInterval +The Pdelay Request messages interval to be used once the clock enters +the SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option +is set, then the local client port will adopt this rate when the local +clock enters the "locked stable" state. This option is specified as a +power of two in seconds, and the default value is 0 (1 second). + .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. +.B operLogSyncInterval +The Sync message interval to be requested once the clock enters the +SERVO_LOCKED_STABLE state. If the 'msg_interval_request' option is +set, then the local client port will request the remote server to +switch to the given message rate via a signaling message containing a +Message interval request TLV. This option is specified as a power of +two in seconds, and default value is 0 (1 second). + .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. +.B path_trace_enabled +Enable the mechanism used to trace the route of the Announce messages. The default is 0 (disabled). + .TP .B phc_index Specifies the index of the PHC to be used for synchronization with hardware @@ -382,6 +359,47 @@ free-running physical clock (created by writing to /sys/class/ptp/ptp*/n_vclocks). The default is -1, which means the index will be set to the PHC associated with the interface, or the device specified by the \fB-p\fP option. + +.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 serverOnly +Setting this option to one (1) prevents the port from entering the +client 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 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 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 udp_ttl Specifies the Time to live (TTL) value for IPv4 multicast messages and the hop @@ -390,54 +408,90 @@ 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 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 twoStepFlag -Enable two-step mode for sync messages. One-step mode can be used only with -hardware time stamping. -The default is 1 (enabled). +.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. +The default is 0 (unicast discovery disabled). + .TP -.B clientOnly -The local clock is a client-only clock if enabled. The default is 0 (disabled). +.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. + +.SH PROGRAM AND CLOCK OPTIONS + .TP -.B slaveOnly -This option is deprecated and will be removed in a future release. -Use "clientOnly" instead. +.B asCapable +If set to 'true', all the checks which can unset asCapable variable (as +described in Section 10.2.4.1 of 802.1AS) are skipped. If set to 'auto', +asCapable is initialized to 'false' and will be set to 'true' after the +relevant checks have passed. The default value is 'auto'. + .TP -.B socket_priority -Configure the SO_PRIORITY of sockets. This is to support cases where a user -wants to route ptp4l traffic using Linux qdiscs for the purpose of traffic -shaping. This option is only available with the IEEE 802.3 transport (the -\fB-2\fP option) and is silently ignored when using the UDP IPv4/6 network -transports. Must be in the range of 0 to 15, inclusive. The default is 0. +.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 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). +.B BMCA +This option enables use of static roles for server and client devices +instead of running the best master clock algorithm (BMCA) described in +1588 profile. This can be used to speed up the start time for servers +and clients when you know the roles of the devices in advance. When set to +\'noop', the traditional BMCA algorithm used by 1588 is skipped. masterOnly and +clientOnly will be used to determine the server or client role for the device. In a +bridge, clientOnly (which is a global option) can be set to make all ports +assume the client role. masterOnly (which is a per-port config option) can then +be used to set individual ports to take on the server role. +The default value is 'ptp' which runs the BMCA related state machines. + .TP -.B priority1 -The priority1 attribute of the local clock. It is used in the PTP server -selection algorithm, lower values take precedence. Must be in the range 0 to -255. -The default is 128. +.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 server. +The default is 0 (disabled). + .TP -.B priority2 -The priority2 attribute of the local clock. It is used in the PTP server -selection algorithm, lower values take precedence. Must be in the range 0 to -255. -The default is 128. +.B clientOnly +The local clock is a client-only clock if enabled. The default is 0 (disabled). + +.TP +.B clockAccuracy +The clockAccuracy attribute of the local clock. It is used in the PTP server +selection algorithm. +The default is 0xFE. + .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 PTP server -selection algorithm. -The default is 0xFE. +.B clock_class_threshold +The maximum clock class value from master, acceptible to sub-ordinate +clock beyond which it moves out of lock state. +The default value is 248. + .TP .B clockIdentity The clockIdentity attribute of the local clock. @@ -447,165 +501,154 @@ identify the specific clock. If default is used or if not set at all, the clockIdentity will be automtically generated. The default is "000000.0000.000000" -.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 "G.8275.x". -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 maxStepsRemoved -When using this option, if the value of stepsRemoved of an Announce -message is greater than or equal to the value of maxStepsRemoved the -Announce message is not considered in the operation of the BMCA. -The default value is 255. +.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" and "refclock_sock" for the NTP SHM and +chrony SOCK reference clocks respectively to allow another process to +synchronize the local clock, and "nullf" for a servo that always dials +frequency offset zero (for use in SyncE nodes). +The default is "pi." + .TP -.B clock_class_threshold -The maximum clock class value from master, acceptible to sub-ordinate -clock beyond which it moves out of lock state. -The default value is 248. +.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 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 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. +.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 first_step_threshold +The maximum offset the servo will correct by changing the clock frequency (phase +when using nullf servo) 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 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. +.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 "G.8275.x". +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 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 10. +.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 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 server. +.B ignore_source_id +This will disable source port identity checking for Sync and Follow_Up +messages. This is useful when the announce messages are disabled in the server +and the client does not have any way to know the server's identity. 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" and "refclock_sock" for the NTP SHM and -chrony SOCK reference clocks respectively to allow another process to -synchronize the local clock, 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. +.B inhibit_announce +This will disable the timer for announce messages (i.e. FD_MANNO_TIMER) and +also the announce message timeout timer (i.e. FD_ANNOUNCE_TIMER). This is used +by the Automotive profile as part of switching over to a static BMCA. If this +option is enabled, ignore_source_id has to be enabled in the client because it +has no way to identify the server in the Sync and Follow_Up messages. The +default is 0 (disabled). -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. +.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 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. +.B interface_rate_tlv +When the client and server are operating are operating at different interface rate, +delay asymmetry caused due to different interface rate needs to be compensated. +The server sends its interface rate using interface rate TLV +as per G.8275.2 Annex D. +The default is 0 (does not support interface rate tlv). + .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. +.B hwts_filter +Select the hardware time stamp filter setting mode. +Possible values are normal, check, full. +Normal mode set the filters as needed. +Check mode only check but do not set. +Full mode set the receive filter to mark all packets with hardware time stamp, + so all applications can get them. +The default is normal. + .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 -The maximum offset the servo will correct by changing the clock frequency (phase -when using nullf servo) 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 . +option is set to correct such offset by stepping). +Relevant only with software time stamping. The default is 1 (enabled). + .TP -.B first_step_threshold -The maximum offset the servo will correct by changing the clock frequency (phase -when using nullf servo) 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 . +.B logging_level +The maximum logging level of messages which should be printed. +The default is 6 (LOG_INFO). + +.TP +.B manufacturerIdentity +The manufacturer id which should be an OUI owned by the manufacturer. +The default is 00:00:00. + .TP .B max_frequency The maximum allowed frequency adjustment of the clock in parts per billion @@ -614,142 +657,187 @@ 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. If the frequency correction set by -ptp4l changes unexpectedly between updates of the clock (e.g. due to another -process trying to control the clock), a warning message will be printed. When -set to 0, the sanity check is disabled. The default is 200000000 (20%). +.B maxStepsRemoved +When using this option, if the value of stepsRemoved of an Announce +message is greater than or equal to the value of maxStepsRemoved the +Announce message is not considered in the operation of the BMCA. +The default value is 255. + .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. +.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 refclock_sock_address -The address of the UNIX domain socket to be used by the refclock_sock servo. -The default is /var/run/refclock.ptp.sock. +.B msg_interval_request +This option, when set, will trigger an adjustment to the Sync and peer +delay request message intervals when the clock servo transitions into +the SERVO_LOCKED_STABLE state. The Sync interval will be adjusted via +the signaling mechanism while the pdelay request interval is simply +adjusted locally. The values to use for the new Sync and peer delay +request intervals are specified by the operLogSyncInterval and +operLogPdelayReqInterval options, respectively. +The default value of msg_interval_request is 0 (disabled). + .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 uds_ro_address -Specifies the address of the second UNIX domain socket for receiving local -management messages, which is restricted to GET actions and does not forward -messages to other ports. Access to this socket can be given to untrusted -applications for monitoring purposes. The default is /var/run/ptp4lro. -.TP -.B uds_file_mode -File mode of the UNIX domain socket used for receiving local management -messages. The mode should be specified as an octal number, i.e. it -should start with a 0 literal. The default mode is 0660. -.TP -.B uds_ro_file_mode -File mode of the second (read-only) UNIX domain socket used for receiving -local management messages. The mode should be specified as an octal number, -i.e. it should start with a 0 literal. The default mode is 0666. -.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. +.B offsetScaledLogVariance +The offsetScaledLogVariance attribute of the local clock. It characterizes the +stability of the clock. +The default is 0xFFFF. + .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". +.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 logging_level -The maximum logging level of messages which should be printed. -The default is 6 (LOG_INFO). +.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 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). +.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 verbose -Print messages to the standard output if enabled. -The default is 0 (disabled). +.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 use_syslog -Print messages to the system log if enabled. -The default is 1 (enabled). +.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 interface_rate_tlv -When the client and server are operating are operating at different interface rate, -delay asymmetry caused due to different interface rate needs to be compensated. -The server sends its interface rate using interface rate TLV -as per G.8275.2 Annex D. -The default is 0 (does not support interface rate tlv). +.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 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). +.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 time_stamping -The time stamping method to be used. The allowed values are hardware, -software, legacy, onestep, and p2p1step. -The default is hardware. +.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 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 priority1 +The priority1 attribute of the local clock. It is used in the PTP server +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 PTP server +selection algorithm, lower values take precedence. Must be in the range 0 to +255. +The default is 128. + +.TP +.B refclock_sock_address +The address of the UNIX domain socket to be used by the refclock_sock servo. +The default is /var/run/refclock.ptp.sock. + .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. +.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. If the frequency correction set by +ptp4l changes unexpectedly between updates of the clock (e.g. due to another +process trying to control the clock), a warning message will be printed. When +set to 0, the sanity check is disabled. The default is 200000000 (20%). + .TP -.B manufacturerIdentity -The manufacturer id which should be an OUI owned by the manufacturer. -The default is 00:00:00. +.B servo_num_offset_values +The number of offset values considered in order to transition from the +SERVO_LOCKED to the SERVO_LOCKED_STABLE state. +The transition occurs once the last 'servo_num_offset_values' offsets +are all below the 'servo_offset_threshold' value. +The default value is 10. + +.TP +.B servo_offset_threshold +The offset threshold used in order to transition from the SERVO_LOCKED +to the SERVO_LOCKED_STABLE state. The transition occurs once the +last 'servo_num_offset_values' offsets are all below the threshold value. +The default value of offset_threshold is 0 (disabled). + +.TP +.B slave_event_monitor +Specifies the address of a UNIX domain socket for event +monitoring. A local monitoring client bound to this address will receive +SLAVE_RX_SYNC_TIMING_DATA and SLAVE_DELAY_TIMING_DATA_NP TLVs. +The default is the empty string (disabled). + +.TP +.B slaveOnly +This option is deprecated and will be removed in a future release. +Use "clientOnly" instead. + +.TP +.B socket_priority +Configure the SO_PRIORITY of sockets. This is to support cases where a user +wants to route ptp4l traffic using Linux qdiscs for the purpose of traffic +shaping. This option is only available with the IEEE 802.3 transport (the +\fB-2\fP option) and is silently ignored when using the UDP IPv4/6 network +transports. Must be in the range of 0 to 15, inclusive. The default is 0. + .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). +The maximum offset the servo will correct by changing the clock frequency (phase +when using nullf servo) 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 step_window When set, indicates the number of Sync events after a clock step that @@ -758,82 +846,102 @@ This is used in situations where clock stepping is unable to happen instantaneously so there is a lag before the timestamps can settle properly to reflect the clock step. The default is 0 (disabled). + +.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 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 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. + .TP -.B hwts_filter -Select the hardware time stamp filter setting mode. -Possible values are normal, check, full. -Normal mode set the filters as needed. -Check mode only check but do not set. -Full mode set the receive filter to mark all packets with hardware time stamp, - so all applications can get them. -The default is normal. +.B time_stamping +The time stamping method to be used. The allowed values are hardware, +software, legacy, onestep, and p2p1step. +The default is hardware. + .TP -.B asCapable -If set to 'true', all the checks which can unset asCapable variable (as -described in Section 10.2.4.1 of 802.1AS) are skipped. If set to 'auto', -asCapable is initialized to 'false' and will be set to 'true' after the -relevant checks have passed. The default value is 'auto'. +.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 BMCA -This option enables use of static roles for server and client devices -instead of running the best master clock algorithm (BMCA) described in -1588 profile. This can be used to speed up the start time for servers -and clients when you know the roles of the devices in advance. When set to -\'noop', the traditional BMCA algorithm used by 1588 is skipped. masterOnly and -clientOnly will be used to determine the server or client role for the device. In a -bridge, clientOnly (which is a global option) can be set to make all ports -assume the client role. masterOnly (which is a per-port config option) can then -be used to set individual ports to take on the server role. -The default value is 'ptp' which runs the BMCA related state machines. +.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 10. + .TP -.B inhibit_announce -This will disable the timer for announce messages (i.e. FD_MANNO_TIMER) and -also the announce message timeout timer (i.e. FD_ANNOUNCE_TIMER). This is used -by the Automotive profile as part of switching over to a static BMCA. If this -option is enabled, ignore_source_id has to be enabled in the client because it -has no way to identify the server in the Sync and Follow_Up messages. The -default is 0 (disabled). +.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 ignore_source_id -This will disable source port identity checking for Sync and Follow_Up -messages. This is useful when the announce messages are disabled in the server -and the client does not have any way to know the server's identity. -The default is 0 (disabled). +.B uds_address +Specifies the address of the UNIX domain socket for receiving local +management messages. The default is /var/run/ptp4l. + .TP -.B msg_interval_request -This option, when set, will trigger an adjustment to the Sync and peer -delay request message intervals when the clock servo transitions into -the SERVO_LOCKED_STABLE state. The Sync interval will be adjusted via -the signaling mechanism while the pdelay request interval is simply -adjusted locally. The values to use for the new Sync and peer delay -request intervals are specified by the operLogSyncInterval and -operLogPdelayReqInterval options, respectively. -The default value of msg_interval_request is 0 (disabled). +.B uds_file_mode +File mode of the UNIX domain socket used for receiving local management +messages. The mode should be specified as an octal number, i.e. it +should start with a 0 literal. The default mode is 0660. + .TP -.B servo_num_offset_values -The number of offset values considered in order to transition from the -SERVO_LOCKED to the SERVO_LOCKED_STABLE state. -The transition occurs once the last 'servo_num_offset_values' offsets -are all below the 'servo_offset_threshold' value. -The default value is 10. +.B uds_ro_address +Specifies the address of the second UNIX domain socket for receiving local +management messages, which is restricted to GET actions and does not forward +messages to other ports. Access to this socket can be given to untrusted +applications for monitoring purposes. The default is /var/run/ptp4lro. + .TP -.B servo_offset_threshold -The offset threshold used in order to transition from the SERVO_LOCKED -to the SERVO_LOCKED_STABLE state. The transition occurs once the -last 'servo_num_offset_values' offsets are all below the threshold value. -The default value of offset_threshold is 0 (disabled). +.B uds_ro_file_mode +File mode of the second (read-only) UNIX domain socket used for receiving +local management messages. The mode should be specified as an octal number, +i.e. it should start with a 0 literal. The default mode is 0666. + .TP -.B slave_event_monitor -Specifies the address of a UNIX domain socket for event -monitoring. A local monitoring client bound to this address will receive -SLAVE_RX_SYNC_TIMING_DATA and SLAVE_DELAY_TIMING_DATA_NP TLVs. -The default is the empty string (disabled). +.B use_syslog +Print messages to the system log if enabled. +The default is 1 (enabled). + +.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 utc_offset +The current offset between TAI and UTC. +The default is 37. + +.TP +.B verbose +Print messages to the standard output if enabled. +The default is 0 (disabled). + .TP .B write_phase_mode This option enables using the "write phase" feature of a PTP Hardware @@ -844,15 +952,17 @@ The default value is 0 (disabled). .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. +.B L2|UDPv4|UDPv6 +Each table entry specifies the transport type and network address of a +potential remote server. If multiple servers are specified, then +unicast negotiation will be performed with each if them. + .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 @@ -860,11 +970,12 @@ 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|UDPv6 -Each table entry specifies the transport type and network address of a -potential remote server. If multiple servers are specified, then -unicast negotiation will be performed with each if them. +.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. .SH TIME SCALE USAGE -- 2.30.2 _______________________________________________ Linuxptp-devel mailing list Linuxptp-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/linuxptp-devel
