phc2sys.8: Doc long opts / cfgfile handling

[RC: Added -f flag help and removed extraneous text.]

Signed-off-by: Peter Schneider <peter@psch.de>
Signed-off-by: Richard Cochran <richardcochran@gmail.com>
master
Peter Schneider 2018-04-15 21:13:58 +02:00 committed by Richard Cochran
parent 79d290e222
commit 89969b4b0f
1 changed files with 196 additions and 3 deletions

199
phc2sys.8
View File

@ -1,4 +1,4 @@
.TH PHC2SYS 8 "November 2012" "linuxptp"
.TH PHC2SYS 8 "April 2018" "linuxptp"
.SH NAME
phc2sys \- synchronize two or more clocks
@ -8,10 +8,16 @@ phc2sys \- synchronize two or more clocks
.B \-r
] [
.B \-r
] [ options ]
] [
.BI \-f " config-file"
] [ options ] [
.I long-options
]
.br
.B phc2sys
[
.BI \-f " config-file"
] [
.BI \-d " pps-device"
] [
.BI \-s " device"
@ -21,7 +27,11 @@ phc2sys \- synchronize two or more clocks
.BI \-O " offset"
] [
.BI \-w
] [ options ]
] [ options ] [
.I long-options
]
.I .\|.\|.
.SH DESCRIPTION
.B phc2sys
@ -67,6 +77,10 @@ system clock to be eligible to become a time source, specify the
.B \-r
option twice.
.TP
.BI \-f " config"
Read configuration from the specified file. No configuration file is read by
default.
.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
@ -226,6 +240,167 @@ Display a help message.
.B \-v
Prints the software version and exits.
.SH LONG OPTIONS
Each and every configuration file option (see below in section
.BR FILE\ OPTIONS)
may also appear
as a "long" style command line argument. For example, the transportSpecific
option may be set using either of these two forms:
.RS
\f(CW\-\-transportSpecific 1 \-\-transportSpecific=1\fP
.RE
Option values given on the command line override values in the global
section of the configuration file (which, in turn overrides default
values).
.SH CONFIGURATION FILE
The configuration file is divided into sections. Each section starts with a
line containing its name enclosed in brackets and it follows with settings.
Each setting is placed on a separate line, it contains the name of the
option and the value separated by whitespace characters. Empty lines and lines
starting with # are ignored.
The global section (indicated as
.BR [global] )
sets the program options. This is the only used option.
.SH FILE OPTIONS
.TP
.B domainNumber
Specify the domain number used by phc2sys. The default is 0. Same as option
.B \-n
(see above).
.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 step_threshold option is set to correct such offset by
stepping). Relevant only with software time stamping. The default is 1
(enabled). Same as option
.B \-x
(see above).
The maximum logging level of messages which should be printed.
The default is 6 (LOG_INFO). Same as option
.B \-l
(see above).
.TP
.B logging_level
The maximum logging level of messages which should be printed.
The default is 6 (LOG_INFO). Same as option
.B \-l
(see above).
.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).
Same as option
.B \-t
(see above).
.TP
.B sanity_freq_limit
The maximum allowed frequency offset between uncorrected clock and the
system monotonic clock in parts per billion (ppb). This is used as a
sanity check of the synchronized clock. When a larger offset is measured,
a warning message will be printed and the servo will be reset. When set
to 0, the sanity check is disabled. The default is 200000000 (20%).
Same as option
.B \-L
(see above).
.TP
.B clock_servo
The servo which is used to synchronize the local clock. Valid values
are "pi" for a PI controller, "linreg" for an adaptive controller using
linear regression, "ntpshm" for the NTP SHM reference clock to allow
another process to synchronize the local clock (the SHM segment number
is set to the domain number), and "nullf" for a servo that always dials
frequency offset zero (for use in SyncE nodes). The default is "pi."
Same as option
.B \-E
(see above).
.TP
.B transportSpecific
The transport specific field. Must be in the range 0 to 255.
The default is 0.
.TP
.B use_syslog
Print messages to the system log if enabled. The default is 1 (enabled).
Related to option
.B \-q
(see above).
.TP
.B verbose
Print messages to the standard output if enabled. The default is 0 (disabled).
Related to option
.B \-m
(see above).
.TP
.B pi_proportional_const
Specifies the proportional constant of the PI controller.
Same as option
.B \-P
(see above).
.TP
.B pi_integral_const
Specifies the integral constant of the PI controller.
Same as option
.B \-I
(see above).
.TP
.B step_threshold
Specifies the step threshold of the servo. It is the maximum offset that
the servo corrects by changing the clock frequency instead of stepping
the clock. The clock is stepped on start regardless of the option if the
offset is larger than 20 microseconds (unless the -F option is used).
It's specified in seconds. The value of 0.0 disables stepping after
the start. The default is 0.0.
Same as option
.B \-S
(see above).
.TP
.B first_step_threshold
Specify the step threshold applied only on the first update. It is the
maximum offset that is corrected by adjusting clock. It's specified in
seconds. The value of 0.0 disables stepping on start. The default is
0.00002 (20 microseconds).
Same as option
.B \-F
(see above).
.TP
.B ntpshm_segment
The number of the SHM segment used by ntpshm servo. The default is 0.
Same as option
.B \-M
(see above).
.TP
.B uds_address
Specifies the address of the server's UNIX domain socket. The default
is /var/run/ptp4
Same as option
.B \-z
(see above).
.SH TIME SCALE USAGE
.B Ptp4l
@ -269,6 +444,12 @@ in the domain to its system clock.
\f(CWphc2sys \-a \-rr\fP
.RE
Same as above, in an IEEE 802.1AS domain.
.RS
\f(CWphc2sys \-a \-rr --transportSpecific=1\fP
.RE
The host is a domain master, PTP clock is synchronized to system clock and the
time offset is obtained from
.BR ptp4l .
@ -310,5 +491,17 @@ does not wait.
\f(CWphc2sys \-s eth0 \-O \-35\fP
.RE
.SH WARNING
Be cautious when the same configuration file is used for both ptp4l and phc2sys.
Keep in mind, that values specified in the configuration file take precedence
over their default values. If a certain option, which is common to ptp4l and
phc2sys, is specified to a non-default value in the configuration file
(p.e., for ptp4l), then this non-default value applies also for phc2sys. This
might be not what is expected.
It is recommended to use seperate configuration files for ptp4l and
phc2sys in order to avoid any unexpected behavior.
.SH SEE ALSO
.BR ptp4l (8)