If you are using the current version of Cumulus Linux, the content on this page may not be up to date. The current version of the documentation is available here. If you are redirected to the main page of the user guide, then this page may have been renamed; please search for it there.

Pulse Per Second - PPS

PPS is the simplest form of synchronization. The PPS source provides a signal precisely every second. The switch is capable of using an external PPS signal to synchronize its PHC (for PPS In) and can also generate the PPS signal that other devices can use to synchronize their clocks (for PPS Out).

  • In PPS In mode, the switch can use an external PPS signal to adjust the phase of its PHC. The PPS signal does not provide ToD, so Cumulus Linux uses PTP for ToD; you must configure a PTP slave port on the switch for PPS In.
  • In PPS Out mode, the switch can output the PPS signal. The switch can use this signal to check the accuracy of its PHC frequency and other devices can use this signal to synchronize their PHC.

Cumulus Linux supports PPS for the NVIDIA SN3750-SX and SN5400 switches only. PPS on the NVIDIA SN5400 switch is in BETA.

Enable PPS Synchronization

To enable PPS synchronization:

Before you enable PPS In, make sure to configure a PTP slave port on the switch. See Precision Time Protocol - PTP.

cumulus@switch:~$ nv set platform pulse-per-second in state enabled
cumulus@switch:~$ nv config apply

When you enable PPS In, the PTP log reporting offset is one every two seconds instead of one every second.

cumulus@switch:~$ nv set platform pulse-per-second out state enabled
cumulus@switch:~$ nv config apply
  1. Edit the Default interface options section of the /etc/ptp4l.conf file to configure the PTP slave port on the switch. PPS In requires PTP slave port. See Precision Time Protocol - PTP for information about PTP.

    cumulus@switch:~$ sudo nano /etc/linuxptp/pps_out.conf
    ...
    # Default interface options
    #
    time_stamping                  hardware
    [swp29]
    udp_ttl                      1
    masterOnly                   0
    delay_mechanism              E2E
    network_transport            RAWUDPv4
    
  2. Edit the /etc/linuxptp/ts2phc.conf file to set the following parameters to enable PPS In.

    cumulus@switch:~$ sudo nano /etc/linuxptp/ts2phc.conf
    # Default configurations
    [global]
    use_syslog                0
    verbose                   1
    logging_level             6
    slave_event_monitor       /var/run/ptp_sem.sock
    ts2phc.pulsewidth         500000000
    ts2phc.tod_source         ptp 
    #
    # servo parameters
    #
    pi_proportional_const          0.000000
    pi_integral_const              0.000000
    pi_proportional_scale          0.700000
    pi_proportional_exponent       -0.300000
    pi_proportional_norm_max       0.700000
    pi_integral_scale              0.300000
    pi_integral_exponent           0.400000
    pi_integral_norm_max           0.300000
    step_threshold                 0.000000050
    first_step_threshold           0.000000001
    max_frequency                  500000000
    sanity_freq_limit              0
    #
    [/dev/ptp1] 
    ts2phc.pin_index               0 
    ts2phc.channel                 0
    ts2phc.extts_polarity          rising 
    ts2phc.extts_correction        0
    
  3. Enable and start the ptp4l and phc2sys services:

    cumulus@switch:~$ sudo systemctl enable ptp4l.service phc2sys.service
    cumulus@switch:~$ sudo systemctl start ptp4l.service phc2sys.service
    
  1. Edit the /etc/linuxptp/pps_out.conf file to set the following parameters.

    cumulus@switch:~$ sudo nano /etc/linuxptp/pps_out.conf
    # Configuration file used for the pps_out.service
    # It is shell formatted and the file is source'd by the service
    # Set the PTP device to source our PPS from. 
    # If not specified, the service will find the first device with a clock name "sx_ptp".
    PTP_DEV=/dev/ptp1
    # Set the pin index on the PPS device to send on. 
    # On the NVIDIA systems, only pin 1 (0-based) is supported
    OUT_PIN=1
    # Set the file where to cache the last started values. 
    # This is used primarily in the "stop" operation to know what to clean up.
    CACHE_FILE=/var/run/pps_out
    # Set the out pulse charateristics for frequency and width
    PULSE_FREQ=1000000000
    PULSE_WIDTH=500000000
    PULSE_PHASE=0
    
  2. Enable and start the pps_out service:

    cumulus@switch:~$ sudo systemctl enable pps_out.service 
    cumulus@switch:~$ sudo systemctl start pps_out.service 
    

PPS Synchronization Settings

You can configure these PPS settings:

PPS In SettingDescription
channel-indexSets the channel index for PPS In. You can set a value of 1 or 0. The default value is 0.
logging-levelSets the logging level for PPS In. You can specify emergency, alert, critical, error, warning, notice, info, or debug. The default logging level is info.
pin-indexSets the pin index for PPS In. You can set a value of 1 or 0. The default value is 0.
signal-polaritySets the polarity of the PPS In signal. You can specify rising-edge, falling-edge, or both. The default setting is rising-edge.
signal-widthSets the pulse width of the PPS In signal. You can set a value between 1000000 and 999000000. The default value is 500000000.
timestamp-correctionSets the value, in nanoseconds, to add to each PPS In timestamp. You can set a value between -1000000000 and 1000000000. The default value is 0.
PPS Out SettingDescription
channel-indexSets the channel index for PPS Out. You can set a value of 1 or 0. The default value is 0.
frequency-adjustmentSets the frequency adjustment of the PPS Out signal. You can set a value between 1000000000 and 2147483647. The default value is 1000000000.
pin-indexSets the pin index for PPS Out. Cumulus Linux supports only pin 1.
signal-widthSets the pulse width of the PPS Out signal. You can set a value between 1000000 and 999000000. The default value is 500000000.

The NVUE CLI includes the phase adjustment setting for PPS Out. Cumulus Linux 5.9 and later does not support this setting.

The following example configures PPS In and sets:

  • The channel index to 1.
  • The pin index to 1.
  • The signal width to 999000000.
  • The timestamp correction to 1000000000.
  • The logging level to warning.
  • The polarity of the PPS In signal to falling-edge.
cumulus@switch:~$ nv set platform pulse-per-second in channel-index 1
cumulus@switch:~$ nv set platform pulse-per-second in pin-index 1
cumulus@switch:~$ nv set platform pulse-per-second in signal-width 999000000
cumulus@switch:~$ nv set platform pulse-per-second in timestamp-correction 1000000000
cumulus@switch:~$ nv set platform pulse-per-second in logging-level warning
cumulus@switch:~$ nv set platform pulse-per-second in signal-polarity falling-edge
cumulus@switch:~$ nv config apply

The following example configures PPS Out and sets:

  • The channel index to 1.
  • The signal width to 999000000.
  • The frequency-adjustment of the PPS Out signal to 2147483647.
cumulus@switch:~$ nv set platform pulse-per-second out channel-index 1
cumulus@switch:~$ nv set platform pulse-per-second out signal-width 999000000
cumulus@switch:~$ nv set platform pulse-per-second out frequency-adjustment 2147483647
cumulus@switch:~$ nv config apply

To configure PPS In, edit the /etc/linuxptp/ts2phc.conf file, then restart the PPS In service with the sudo systemctl restart ts2phc.service command.

The following example configures PPS In and sets:

  • The channel index to 1
  • The pin index to 1
  • The signal width to 999000000.
  • The timestamp correction to 1000000000.
  • The logging level to 4 (warning).
  • The polarity of the PPS In signal to falling edge (falling).
cumulus@switch:~$ sudo nano /etc/linuxptp/ts2phc.conf
# ts2phc is enabled 
[global] 
use_syslog                     0 
verbose                        1 
slave_event_monitor            /var/run/ptp_sem.sock 
logging_level                  4 
ts2phc.pulsewidth              999000000 
ts2phc.tod_source              ptp 
domainNumber                   0
...
[/dev/ptp1] 
ts2phc.pin_index               1 
ts2phc.channel                 1 
ts2phc.extts_polarity          falling 
ts2phc.extts_correction        0

To configure PPS Out, edit the /etc/linuxptp/pps_out.conf.conf file, then restart the PPS Out service with the sudo systemctl restart pps_out.service command.

The following example configures PPS Out and sets:

  • The channel index to 1.
  • The signal width to 999000000.
  • The frequency-adjustment of the PPS Out signal to 2147483647.
cumulus@switch:~$ sudo nano /etc/linuxptp/pps_out.conf.conf
# Configuration file used for the pps_out.service
# It is shell formatted and the file is source'd by the service
#
# Set the PTP device to source our PPS from. 
# If not specified, the service will find the first device with a clock name "sx_ptp".
PTP_DEV=/dev/ptp1
#
# Set the pin index on the PPS device to send on. 
# On the NVIDIA systems, only pin 1 (0-based) is supported
OUT_PIN=1
#
OUT_CHANNEL=1 
#
# Set the file where to cache the last started values. 
# This is used primarily in the "stop" operation to know what to clean up.
CACHE_FILE=/var/run/pps_out
#
# Set the out pulse charateristics for frequency and width
PULSE_FREQ=2147483647
PULSE_WIDTH=999000000
PULSE_PHASE=1000000000

Show PPS Configuration Settings

To show a summary of the PPS In and PPS out configuration settings, run the nv show platform pulse-per-second command:

cumulus@switch:~$ nv show platform pulse-per-second
                        applied
----------------------  -----------
in
  state                 enabled
  pin-index             0
  channel-index         0
  signal-width          500000000
  signal-polarity       rising-edge
  timestamp-correction  0
  logging-level         info
out
  state                 disabled
  pin-index             1
  channel-index         0
  frequency-adjustment  1000000000
  phase-adjustment      0
  signal-width          500000000

To show only PPS In configuration settings, run the nv show platform pulse-per-second in command:

cumulus@switch:~$ nv show platform pulse-per-second in
                      applied
--------------------  -----------
state                 enabled
pin-index             0
channel-index         0
signal-width          500000000
signal-polarity       rising-edge
timestamp-correction  0
logging-level         info

To show only PPS Out configuration settings, run the nv show platform pulse-per-second out command:

cumulus@switch:~$ nv show platform pulse-per-second out
                      applied
--------------------  ----------
state                 disabled
pin-index             1
channel-index         0
frequency-adjustment  1000000000
phase-adjustment      0
signal-width          500000000