1TS2PHC(8) System Manager's Manual TS2PHC(8)
2
6 ts2phc - Synchronizes one or more PTP Hardware Clocks using external
7 time stamps.
8
11 ts2phc [ -hmqv ] [ -c device|name ] [ -f config ] [ -l print-level ] [
12 -s device|name ] [ long-options ] ...
13
16 ts2phc synchronizes PTP Hardware Clocks (PHC) to external time stamp
17 signals. A single source may be used to distribute time to one or more
18 PHC devices.
19
22 -a Adjust the direction of synchronization automatically. The pro‐
23 gram determines which PHC should the reference clock for time
24 distribution and which should be the destinations by querying
25 the port states from the running instance of ptp4l. Note that
26 using this option, the PPS signal distribution hierarchy still
27 remains fixed as per the configuration file. This implies that
28 using this option, a PPS source of the PHC kind may become a
29 target clock, and a PPS sink may become a reference clock.
30 Other, non-PHC types of PPS sources (generic, NMEA) cannot be‐
31 come target clocks. Clocks which are not part of ptp4l's list of
32 ports are not synchronized. This option is useful when the
33 boundary_clock_jbod option of ptp4l is also enabled.
34 -c device|name
36 Specifies a PHC to be synchronized. The clock may be identified
37 by its character device (like /dev/ptp0) or its associated net‐
38 work interface (like eth0). This option may be given multiple
39 times.
40 -f config
42 Read configuration from the specified file. No configuration
43 file is read by default.
44 -h Displays the command line help summary.
46 -l print-level
48 Sets the maximum syslog level of messages which should be
49 printed or sent to the system logger. The default is 6
50 (LOG_INFO).
51 -m Prints log messages to the standard output.
53 -q Prevents sending log messages to the system logger.
55 -s device|name
57 Specifies the source of the Time of Day (ToD) data. Use the key
58 word "generic" for an external 1-PPS without ToD information.
59 When using a PHC as the time source, the clock may be identified
60 by its character device (like /dev/ptp0) or its associated net‐
61 work interface (like eth0). Use the key word "nmea" for an ex‐
62 ternal 1-PPS from a GPS providing ToD information via the RMC
63 NMEA sentence.
64 -v Prints the software version and exits.
66
69 Each and every configuration file option (see below) may also appear as
70 a "long" style command line argument. For example, the use_syslog op‐
71 tion may be set using either of these two forms.
72 --use_syslog 1 --use_syslog=1
74 Option values given on the command line override values in the global
76 section of the configuration file.
77
80 The configuration file is divided into sections. Each section starts
81 with a line containing its name enclosed in brackets and it follows
82 with settings. Each setting is placed on a separate line, it contains
83 the name of the option and the value separated by whitespace charac‐
84 ters. Empty lines and lines starting with # are ignored.
85 There are two different section types.
87 1. The global section (indicated as [global]) sets the program op‐
90 tions and the default time sink options. Other sections are
91 clock specific sections, and they override the default options.
92 2. Time sink sections give the name of the configured PHC (e.g.
94 [eth0]). Time sinks specified in the configuration file need
95 not be specified with the -c command line option.
96
99 first_step_threshold
100 The maximum offset, specified in seconds, that the servo will
101 correct by changing the clock frequency (phase when using nullf
102 servo) instead of stepping the clock. This is only applied on
103 the first update. When set to 0.0, the servo will not step the
104 clock on start. The default is 0.00002 (20 microseconds).
105 free_running
108 When set to 1, no PHC will be adjusted. This option can be use‐
109 ful in test scenarios, for example to determine how well syn‐
110 chronized a group of local clocks are to each other. The de‐
111 fault is 0 (adjust the clocks).
112 leapfile
115 The path to the current leap seconds definition file. In a De‐
116 bian system this file is provided by the tzdata package and can
117 be found at /usr/share/zoneinfo/leap-seconds.list. If a leapfile
118 is configured it will be reloaded if modified. The default is an
119 empty string, which causes the program to use a hard coded table
120 that reflects the known leap seconds on the date of the soft‐
121 ware's release.
122 logging_level
125 The maximum logging level of messages which should be printed.
126 The default is 6 (LOG_INFO).
127 max_frequency
130 The maximum allowed frequency adjustment of the clock in parts
131 per billion. This is an additional limit to the maximum allowed
132 by the hardware. When set to 0, the hardware limit will be used.
133 The default is 900000000 (90%).
134 message_tag
137 The tag which is added to all messages printed to the standard
138 output or system log. The default is an empty string (which
139 cannot be set in the configuration file as the option requires
140 an argument).
141 step_threshold
144 The maximum offset, specified in seconds, that the servo will
145 correct by changing the clock frequency instead of stepping the
146 clock. When set to 0.0, the servo will never step the clock ex‐
147 cept on start. The default is 0.0.
148 ts2phc.nmea_remote_host, ts2phc.nmea_remote_port
151 Specifies the remote host providing ToD information when using
152 the "nmea" PPS signal source. Note that if these two options
153 are both specified, then the given remote connection will be
154 used in preference to the configured serial port. These options
155 default to the empty string, that is, not specified.
156 ts2phc.nmea_serialport, ts2phc.nmea_baudrate
159 Specifies the serial port and baudrate in bps for character de‐
160 vice providing ToD information when using the "nmea" PPS signal
161 source. Note that if the options, ts2phc.nmea_remote_host and
162 ts2phc.nmea_remote_port, are both specified, then the given re‐
163 mote connection will be used in preference to the configured se‐
164 rial port. The default serial port is "/dev/ttyS0". The de‐
165 fault baudrate is 9600 bps.
166 ts2phc.perout_phase
169 Configures the offset between the beginning of the second and
170 the PPS source's rising edge. Available only for the PHC kind of
171 PPS source. The supported range is 0 to 999999999 nanoseconds.
172 The default is 0 nanoseconds, but leaving this option unspeci‐
173 fied will not transmit the phase to the kernel, instead PPS will
174 be requested to start at an absolute time equal to the nearest
175 2nd full second since the start of the program. This should
176 yield the same effect, but may not work with drivers that do not
177 support starting periodic output at an absolute time.
178 ts2phc.pulsewidth
181 The pulse width of the external PPS signal in nanoseconds. When
182 'ts2phc.extts_polarity' is "both", the given pulse width is used
183 to detect and discard the time stamp of the unwanted edge. In
184 case the PPS source is of the PHC kind, an attempt is made to
185 request the kernel to actually emit using this pulse width. If
186 this fails, it is assumed that the specified pulse width is cor‐
187 rect, and the value is used in the edge rejection algorithm.
188 The supported range is 1000000 to 990000000 nanoseconds. The
189 default is 500000000 nanoseconds.
190 ts2phc.tod_source
193 Specifies the source of Time of Day (ToD) data. Use the key
194 word "generic" for an external 1-PPS without ToD information.
195 When using a PHC as the time source, the clock may be identified
196 by its character device (like /dev/ptp0) or its associated net‐
197 work interface (like eth0). Use the key word "nmea" for an ex‐
198 ternal 1-PPS from a GPS providing ToD information via the RMC
199 NMEA sentence. The default is "generic"
200 use_syslog
203 Print messages to the system log if enabled. The default is 1
204 (enabled).
205 verbose
208 Print messages to the standard output if enabled. The default
209 is 0 (disabled).
210
213 ts2phc.channel
214 The external time stamping or periodic output channel to be
215 used. Some PHC devices feature programmable pins and one or
216 more time stamping channels. This option allows selecting a
217 particular channel to be used. When using a PHC device as the
218 PPS source, this option selects the periodic output channel.
219 The default is channel 0.
220 ts2phc.extts_correction
222 The value, in nanoseconds, to be added to each PPS time stamp.
223 The default is 0 (no correction).
224 ts2phc.extts_polarity
226 The polarity of the external PPS signal, either "rising" or
227 "falling". Some PHC devices always time stamp both edges. Set‐
228 ting this option to "both" will allow the ts2phc program to work
229 with such devices by detecting and ignoring the unwanted edge.
230 In this case be sure to set 'ts2phc.pulsewidth' to the correct
231 value. The default is "rising".
232 ts2phc.master
234 Setting this option to 1 configures the given PHC device as the
235 source of the PPS signal. The default is 0 for the time sink
236 role.
237 ts2phc.pin_index
239 The pin index to be used. Some PHC devices feature programmable
240 pins, and this option allows configuration of a particular pin
241 for the external time stamping or periodic output function. The
242 default is pin index 0.
243
246 Be cautious when sharing the same configuration file between ptp4l,
247 phc2sys, and ts2phc. Keep in mind that values specified in the config‐
248 uration file take precedence over the default values. If an option
249 which is common to the other programs is set in the configuration file,
250 then the value will be applied to all the programs using the file, and
251 this might not be what is expected.
252 It is recommended to use separate configuration files for ptp4l,
254 phc2sys, and ts2phc in order to avoid any unexpected behavior.
255
258 phc2sys(8) ptp4l(8)
259linuxptp February 2023 TS2PHC(8)