From 2f3b9f718fa82dac83c0c3d18bfd121c807135d6 Mon Sep 17 00:00:00 2001 From: Miroslav Lichvar Date: Thu, 1 Nov 2012 11:24:24 +0100 Subject: [PATCH] Add man pages. Signed-off-by: Miroslav Lichvar --- hwstamp_ctl.8 | 56 ++++++++++ phc2sys.8 | 91 ++++++++++++++++ pmc.8 | 85 +++++++++++++++ ptp4l.8 | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 523 insertions(+) create mode 100644 hwstamp_ctl.8 create mode 100644 phc2sys.8 create mode 100644 pmc.8 create mode 100644 ptp4l.8 diff --git a/hwstamp_ctl.8 b/hwstamp_ctl.8 new file mode 100644 index 0000000..1c1a45e --- /dev/null +++ b/hwstamp_ctl.8 @@ -0,0 +1,56 @@ +.TH HWSTAMP_CTL 8 "November 2012" "linuxptp" +.SH NAME +hwstamp_ctl \- set time stamping policy at the driver level + +.SH SYNOPSIS +.B hwstamp_ctl +.BI \-i " interface" +[ +.BI \-r " rx-filter" +] [ +.BI \-t " tx-type" +] + +.SH DESCRIPTION +.B hwstamp_ctl +is a program used to set the hardware time stamping policy at the network +driver level with the +.B SIOCSHWTSTAMP +.BR ioctl (2). +The +.I tx-type +and +.I rx-filter +values are hints to the driver what it is expected to do. If the requested +fine-grained filtering for incoming packets is not supported, the driver may +time stamp more than just the requested types of packets. + +This program is a debugging tool. The +.BR ptp4l (8) +program does not need this program to function, it will set the policy +automatically as appropriate. + +.SH OPTIONS +.TP +.BI \-i " interface" +Specify the network interface of which the policy should be changed. +.TP +.BI \-r " rx-filter" +Specify which types of incoming packets should be time stamped, +.I rx-filter +is an integer value. +.TP +.BI \-t " tx-type" +Enable or disable hardware time stamping for outgoing packets, +.I tx-type +is an integer value. +.TP +.BI \-h +Display a help message and list of possible values for +.I rx-filter +and +.IR tx-type . + +.SH SEE ALSO +.BR ioctl (2), +.BR ptp4l (8) diff --git a/phc2sys.8 b/phc2sys.8 new file mode 100644 index 0000000..26b37a8 --- /dev/null +++ b/phc2sys.8 @@ -0,0 +1,91 @@ +.TH PHC2SYS 8 "November 2012" "linuxptp" +.SH NAME +phc2sys \- synchronize two clocks + +.SH SYNOPSIS +.B phc2sys +{ +.BI \-d " pps-device" +[ +.BI \-s " phc-device" +| +.BI \-i " interface" +] | +.BI \-s " phc-device" +| +.BI \-i " interface" +} [ +.BI \-c " phc-device" +] [ +.BI \-P " kp" +] [ +.BI \-I " ki" +] [ +.BI \-R " update-rate" +] [ +.BI \-N " clock-readings" +] + +.SH DESCRIPTION +.B phc2sys +is a program which synchronizes two clocks in the system. Typically, it is used +to synchronize the system clock to a PTP hardware clock (PHC), which itself is +synchronized by the +.BR ptp4l (8) +program. + +Two synchronization modes are supported, one uses a pulse per second (PPS) +signal provided by the source clock and the other mode reads time from the +source clock directly. The PPS mode is usually preferred, because reading the +PHC is slow and introduces an unknown error in the readings, but not all PHCs +provide the PPS signal. + +.SH OPTIONS +.TP +.BI \-d " pps-device" +Specify the PPS device of the master clock (e.g. /dev/pps0). With this option +the PPS synchronization mode is used instead of the direct mode. As the PPS +signal does not specify time and only marks start of a second, the slave clock +should be already close to the correct time before +.B phc2sys +is started or the +.B \-s +option should be used too. +.TP +.BI \-s " phc-device" +Specify the device of the master clock (e.g. /dev/ptp0). When this option is +used together with the +.B \-d +option, the master clock is read only on start to fix an offset over 0.5 +seconds which cannot be fixed with PPS alone. +.TP +.BI \-i " interface" +Similar to the +.B \-s +option, but specified by the interface which provides the master clock. +.TP +.BI \-c " phc-device" +Specify the device of the slave clock (e.g. /dev/ptp1). The default slave clock +is the system clock (CLOCK_REALTIME). +.TP +.BI \-P " kp" +Specify the proportional constant of the PI controller. The default is 0.7. +.TP +.BI \-I " ki" +Specify the integral constant of the PI controller. The default is 0.3. +.TP +.BI \-R " update-rate" +Specify the slave clock update rate when running in the direct synchronization +mode. The default is 1 per second. +.TP +.BI \-N " phc-num" +Specify the number of master clock readings per one slave clock update. Only +the fastest reading is used to update the slave clock, this is useful to +minimize the error caused by random delays in scheduling and bus utilization. +The default is 5. +.TP +.BI \-h +Display a help message. + +.SH SEE ALSO +.BR ptp4l (8) diff --git a/pmc.8 b/pmc.8 new file mode 100644 index 0000000..65bedb7 --- /dev/null +++ b/pmc.8 @@ -0,0 +1,85 @@ +.TH PMC 8 "November 2012" "linuxptp" +.SH NAME +pmc \- PTP management client + +.SH SYNOPSIS +.B pmc +[ +.B \-2 +| +.B \-4 +| +.B \-6 +| +.B \-u +] [ +.BI \-b " boundary-hops" +] [ +.BI \-d " domain-number" +] [ +.BI \-i " interface" +] [ +.BI \-t " transport-specific-field" +] + +.SH DESCRIPTION +.B pmc +is a program which implements a PTP management client according to IEEE +standard 1588. The program reads from the standard input actions specified by +name and management ID, sends them over the selected transport and prints any +received replies. There are three actions supported: +.B GET +retrieves the specified information, +.B SET +updates the specified information and +.B CMD +(or +.BR COMMAND ) +initiates the specified event. + +Command +.B help +can be used to get a list of supported actions and management IDs. + +.SH OPTIONS +.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 \-u +Select the Unix Domain Socket transport. +.TP +.BI \-b " boundary-hops" +Specify the boundary hops value in sent messages. The default is 1. +.TP +.BI \-d " domain-number" +Specify the domain number in sent messages. The default is 0. +.TP +.BI \-i " interface" +Specify the network interface. The default is /tmp/pmc for the Unix Domain +Socket transport and eth0 for the other transports. +.TP +.BI \-t " transport-specific-field" +Specify the transport specific field in sent messages as a hexadecimal number. +The default is 0x0. +.TP +.B \-h +Display a help message. + +.SH MANAGEMENT IDS + +.TP +.B CURRENT_DATA_SET +.TP +.B TIME_STATUS_NP +.TP +.B NULL_MANAGEMENT + +.SH SEE ALSO +.BR ptp4l (8) diff --git a/ptp4l.8 b/ptp4l.8 new file mode 100644 index 0000000..5fb0c7c --- /dev/null +++ b/ptp4l.8 @@ -0,0 +1,291 @@ +.TH PTP4l 8 "November 2012" "linuxptp" +.SH NAME +ptp4l \- PTP Boundary/Ordinary Clock + +.SH SYNOPSIS +.B ptp4l +[ +.B \-A +| +.B \-E +| +.B \-P +] [ +.B \-2 +| +.B \-4 +| +.B \-6 +] [ +.B \-H +| +.B \-S +| +.B \-L +] [ +.BI \-f " config" +] [ +.BI \-p " phc-device" +] [ +.B \-s +] [ +.BI \-l " print-level" +] [ +.B \-q +] [ +.B \-v +] +[ +.BI \-i " interface" +] +.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) and Ordinary Clock +(OC). + +.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. +.TP +.B \-P +Select the peer delay (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 \-p " phc-device" +With hardware time stamping, force which PHC device (e.g. /dev/ptp0) should be +used. +.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 \-q +Don't send messages to the system logger. +.TP +.B \-v +Print messages to the standard output. +.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 \-h +Display a help message. + +.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. + +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. +The name of the section is 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. + +.SH PORT OPTIONS + +.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 transportSpecific +The transport specific field. Must be in the range 0 to 255. +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 delay_mechanism +Select the delay mechanism. Possible values are E2E, P2P and Auto. +The default is E2E. +.TP +.B network_transport +Select the network transport. Possible values are UDPv4, UDPv6 and L2. +The default is UDPv4. + +.SH PROGRAM AND CLOCK OPTIONS + +.TP +.B twoStepFlag +The local clock is a two-step clock if enabled. One-step clocks are not +supported yet. +The default is 1 (enabled). +.TP +.B slaveOnly +The local clock is a slave-only clock if enabled. +The default is 0 (disabled). +.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 domainNumber +The domain attribute of the local clock. +The default is 0. +.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 tx_timestamp_retries +The number of retries to fetch the tx time stamp from the kernel when a message +is sent. +The default is 2. +.TP +.B clock_servo +The servo which is used to synchronize the local clock. Currently only one +servo is implemented, a PI controller. +The default is pi. +.TP +.B pi_proportional_const +The proportional constant of the PI controller. 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_integral_const +The integral constant of the PI controller. 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_offset_const +The maximum offset the PI controller will correct by changing the clock +frequency instead of stepping the clock. When set to 0.0, the controller will +never step the clock. +The default is 0.0. +.TP +.B ptp_dst_mac +The MAC address where should be PTP messages sent. +Relevant only with L2 transport. The default is 01:1B:19:00:00:00. +.TP +.B p2p_dst_mac +The MAC address where should be peer delay messages the PTP peer. +Relevant only with L2 transport. The default is 01:80:C2:00:00:0E. +.TP +.B logging_level +The maximum logging level of messages which should be printed. +The default is 6 (LOG_INFO). +.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 time_stamping +The time stamping method. The allowed values are hardware, software and legacy. +The default is hardware. + +.SH SEE ALSO +.BR pmc (8), +.BR phc2sys (8)