oracular (8) ts2phc.8.gz

Provided by: linuxptp_4.2-1ubuntu1_amd64 bug

NAME

       ts2phc - Synchronizes one or more PTP Hardware Clocks using external time stamps.

SYNOPSIS

       ts2phc  [ -hmqv ] [ -c device|name ] [ -f config ] [ -l print-level ] [ -s device|name ] [
       long-options ] ...

DESCRIPTION

       ts2phc synchronizes PTP Hardware Clocks (PHC) to external time stamp  signals.   A  single
       source may be used to distribute time to one or more PHC devices.

OPTIONS

       -a     Adjust the direction of synchronization automatically. The program determines which
              PHC should the reference clock for  time  distribution  and  which  should  be  the
              destinations  by querying the port states from the running instance of ptp4l.  Note
              that using this option, the PPS signal distribution hierarchy still  remains  fixed
              as per the configuration file. This implies that using this option, a PPS source of
              the PHC kind may become a target clock, and a  PPS  sink  may  become  a  reference
              clock.  Other,  non-PHC  types  of PPS sources (generic, NMEA) cannot become target
              clocks. Clocks which are not part of ptp4l's list of ports  are  not  synchronized.
              This option is useful when the boundary_clock_jbod option of ptp4l is also enabled.

       -c device|name
              Specifies  a  PHC to be synchronized.  The clock may be identified by its character
              device (like /dev/ptp0) or its associated  network  interface  (like  eth0).   This
              option may be given multiple times.

       -f config
              Read  configuration  from  the  specified  file.   No configuration file is read by
              default.

       -h     Displays the command line help summary.

       -l print-level
              Sets the maximum syslog level of messages which should be printed or  sent  to  the
              system logger. The default is 6 (LOG_INFO).

       -m     Prints log messages to the standard output.

       -q     Prevents sending log messages to the system logger.

       -s device|name
              Specifies the source of the Time of Day (ToD) data.  Use the key word "generic" for
              an external 1-PPS without ToD information.  When using a PHC as  the  time  source,
              the  clock  may  be  identified  by  its  character  device (like /dev/ptp0) or its
              associated network interface (like eth0).  Use the key word "nmea" for an  external
              1-PPS from a GPS providing ToD information via the RMC NMEA sentence.

       -v     Prints the software version and exits.

LONG OPTIONS

       Each  and  every  configuration  file option (see below) may also appear as a "long" style
       command line argument.  For example, the use_syslog option may  be  set  using  either  of
       these two forms.

              --use_syslog 1   --use_syslog=1

       Option  values  given  on  the  command  line override values in the global section of the
       configuration file.

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.

       There are two different section types.

       1.     The global section (indicated as [global]) sets the program options and the default
              time sink options. Other sections are clock specific sections,  and  they  override
              the default options.

       2.     Time  sink sections give the name of the configured PHC (e.g.  [eth0]).  Time sinks
              specified in the configuration file need not be specified with the -c command  line
              option.

GLOBAL OPTIONS

       first_step_threshold
              The  maximum  offset, specified in seconds, that 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. When set to 0.0, the servo will not step
              the clock on start.  The default is 0.00002 (20 microseconds).

       free_running
              When set to 1, no PHC will  be  adjusted.   This  option  can  be  useful  in  test
              scenarios,  for  example to determine how well synchronized a group of local clocks
              are to each other.  The default is 0 (adjust the clocks).

       leapfile
              The path to the current leap seconds definition file. In a Debian system this  file
              is  provided  by  the  tzdata package and can be found at /usr/share/zoneinfo/leap-
              seconds.list. If a leapfile is configured it will  be  reloaded  if  modified.  The
              default is an empty string, which causes the program to use a hard coded table that
              reflects the known leap seconds on the date of the software's release.

       logging_level
              The maximum logging level of messages which should be printed.  The  default  is  6
              (LOG_INFO).

       max_frequency
              The  maximum  allowed frequency adjustment of the clock in parts per billion.  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%).

       message_tag
              The  tag  which  is  added to all messages printed to the standard output or system
              log.  If the tag contains the string "{level}", it will be replaced  with  the  log
              level  of the message as a number.  The default is an empty string (which cannot be
              set in the configuration file as the option requires an argument).

       step_threshold
              The maximum offset, specified in seconds, that 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.  The default is 0.0.

       ts2phc.nmea_remote_host, ts2phc.nmea_remote_port
              Specifies the remote host providing ToD  information  when  using  the  "nmea"  PPS
              signal  source.   Note that if these two options are both specified, then the given
              remote connection will be used in preference to the configured serial port.   These
              options default to the empty string, that is, not specified.

       ts2phc.nmea_serialport, ts2phc.nmea_baudrate
              Specifies  the  serial  port and baudrate in bps for character device providing ToD
              information when using the "nmea" PPS signal source.  Note  that  if  the  options,
              ts2phc.nmea_remote_host  and  ts2phc.nmea_remote_port, are both specified, then the
              given remote connection will be used in preference to the configured  serial  port.
              The default serial port is "/dev/ttyS0".  The default baudrate is 9600 bps.

       ts2phc.perout_phase
              Configures  the  offset  between  the  beginning of the second and the PPS source's
              rising edge. Available only for the PHC kind of PPS source. The supported range  is
              0  to  999999999 nanoseconds. The default is 0 nanoseconds, but leaving this option
              unspecified will not transmit  the  phase  to  the  kernel,  instead  PPS  will  be
              requested  to  start at an absolute time equal to the nearest 2nd full second since
              the start of the program. This should yield the same effect, but may not work  with
              drivers that do not support starting periodic output at an absolute time.

       ts2phc.pulsewidth
              The   pulse   width   of   the   external   PPS   signal   in   nanoseconds.   When
              'ts2phc.extts_polarity' is "both", the given pulse width  is  used  to  detect  and
              discard  the  time stamp of the unwanted edge. In case the PPS source is of the PHC
              kind, an attempt is made to request the kernel to actually emit  using  this  pulse
              width.  If this fails, it is assumed that the specified pulse width is correct, and
              the value is used in the edge rejection algorithm.  The supported range is  1000000
              to 990000000 nanoseconds.  The default is 500000000 nanoseconds.

       ts2phc.tod_source
              Specifies  the source of Time of Day (ToD) data.  Use the key word "generic" for an
              external 1-PPS without ToD information.  When using a PHC as the time  source,  the
              clock  may be identified by its character device (like /dev/ptp0) or its associated
              network interface (like eth0).  Use the key word "nmea" for an external 1-PPS  from
              a  GPS  providing  ToD  information  via  the  RMC  NMEA  sentence.  The default is
              "generic"

       use_syslog
              Print messages to the system log if enabled.  The default is 1 (enabled).

       verbose
              Print messages to the standard output if enabled.  The default is 0 (disabled).

TIME SINK OPTIONS

       ts2phc.channel
              The external time stamping or periodic output channel to be used.  Some PHC devices
              feature  programmable  pins  and  one  or more time stamping channels.  This option
              allows selecting a particular channel to be used.  When using a PHC device  as  the
              PPS  source,  this  option  selects  the  periodic  output channel.  The default is
              channel 0.

       ts2phc.extts_correction
              The value, in nanoseconds, to be added to each PPS time stamp.  The  default  is  0
              (no correction).

       ts2phc.extts_polarity
              The  polarity  of  the external PPS signal, either "rising" or "falling".  Some PHC
              devices always time stamp both edges.  Setting this option to "both" will allow the
              ts2phc  program  to  work  with such devices by detecting and ignoring the unwanted
              edge.  In this case be sure to set 'ts2phc.pulsewidth' to the correct  value.   The
              default is "rising".

       ts2phc.master
              Setting  this  option to 1 configures the given PHC device as the source of the PPS
              signal.  The default is 0 for the time sink role.

       ts2phc.pin_index
              The pin index to be used.  Some PHC devices feature  programmable  pins,  and  this
              option  allows  configuration of a particular pin for the external time stamping or
              periodic output function.  The default is pin index 0.

WARNING

       Be cautious when sharing the same configuration file between ptp4l, phc2sys,  and  ts2phc.
       Keep  in  mind  that  values  specified in the configuration file take precedence over the
       default values.  If an option which is  common  to  the  other  programs  is  set  in  the
       configuration file, then the value will be applied to all the programs using the file, and
       this might not be what is expected.

       It is recommended to use separate configuration files for ptp4l, phc2sys,  and  ts2phc  in
       order to avoid any unexpected behavior.

SEE ALSO

       phc2sys(8) ptp4l(8)