WeOS
5.29.0

## Introduction

Precision Time Protocol (PTP) is a protocol used to synchronise clocks in a network, which is exactly what NTP (Network Time Protocol) does, but the major difference is that PTP performs synchronisation on a sub microsecond level, offering far better accuracy compared to NTP. PTP may also be referred to in a context of IEEE 1588-2008 standard, which defines version 2 of the protocol. PTP is being used in variety of use-cases, which resulted in plethora of configuration options available to users, and, as a consequence, gave rise to several additional standards, each focusing on some specific area.

The purpose of this document is to cover the basics of PTP, without going too much into details of specific use-cases.

For example use-cases, see:

- HowTo PTP

## Overview

Since PTP is but a method of synchronising clocks through network, there is a need of time-source. Usually, time-source is a device having fine clock qualities, and in a network with a few potential time-sources, there is a need to select one source with the most accurate clock which will assume the role of Grand Master (GM) clock. Selection process is made possible thanks to Best Master Clock Algorithm (BMCA), which, having analysed clock attributes from all connected time-sources, decides on which clock is the most suitable for the role of GM.

Before moving forward, it is appropriate to mention at least a few common clock types and some basic terminology.

Grandmaster (GM) - device on the network acting as a primary time source for all other devices, itself not synchronising to anyone but instead being connected to a fine time source, such as GPS.

Master - device on the network providing it’s time, while at the same time synchronising with another Master or Grandmaster.

Slave - device on the network wishing to synchronise with chosen time source, be it Master or GM.

The following is a non-exhaustive list of PTP clock types.

- Ordinary Clock (OC): station on the network that may act as either GM or Slave. Since GM, as we already know it, distributes its time throughout network, Slave, on the contrary, is a station that wishes to synchronise to GM.

- Transparent Clock (TC): switching device on the network, itself taking no part in BMCA and having no interest in getting synchronised with GM, but capable of forwarding PTP messages with as little impact on synchronisation as possible. Transparency is achieved by compensating for the so called Residence Time (packet delay within TC) and Uplink Delay (packet transmission time between two directly connected PTP stations). Simply put, even though there may be many TCs (hops) between GM and Slave, neither GM nor Slave should notice any significant impact on synchronisation.

- Boundary Clock (BC): switching device on the network, taking part in BMCA and acting as both Slave and Master clock. Being Slave to it’s upstream neighbour, it is able to synchronise to it, while at the same time being Master to it’s downstream neighbour allows that naighbor to get synchronised with itself.

Note

This system is only intended to be used as transparent or boundary clock in production. Ordinary clock mode is for testing purposes only.

## BMCA and GM election process

Before synchronisation takes place, suitable time source must be elected. Election process is performed by BMCA algorithm running on each node in PTP network, with the exception of TC. The so called ANNOUNCE messages, containing detailed information about clock qualities and issued by each node in PTP network (except TCs), are compared by BMCA. Finally, each node running BMCA issues its own resolution as to which clock has the best clock qualities, and if such resolution is identical in each node, GM clock is elected.

## Synchronisation

GM clock conveys its time via timestamp placed into SYNC message (in the case of 1-step capable device) or into FOLLOWUP message (in the case of 2-step capable device), which is then forwarded to Slave clocks.

The next step is finding out path delay (in the case of end-to-end configuration) or peer delay (in the case of peer-to-peer configuration). Peer delay is calculated between two neighboring stations while path delay is calculated between two ends, i.e. GM and Slave, and the former has the advantage of being more precise. See Table 2. This delay is needed in order to compensate for packet transmission time from GM to Slave.

Finally, when Slave clock receives SYNC message and calculates peer/path delay, it may adjust its local clock to that of GM. Synchronisation is a process that goes on ad infinitum, since clocks have tendency to drift over time.

It should be noted that PTP ports have different states associated with them, which might change over time. For example, ports fasing GM (these do receive SYNC messages on ingress) remain in MASTER state, while ports facing Slaves (these never receive SYNC messages on ingress) remain in SLAVE state. Please refer to Table 4 for a non-exhaustive list of port states.

Synchronisation mechanism is quite complex and depends on numerous details, but the intention of this document is to explain general concept only, leaving those details behind. For an in-depth insight into how PTP works on a protocol level, readers should consider studying IEEE 1588 standard.

Message | Timestamped | Description
--- | --- | ---
ANNOUNCE | No | Used to announce the presence and attributes of the local clock to the network for BMCA selection.
SYNC | Yes | Used by a master clock to convey time.
DELAY REQUEST | Yes | Sent by a slave clock to calculate link delay between a master and slave. Used in the end-to-end delay mechanism.
DELAY RESPONSE | No | Sent by a master clock to a slave clock as a response to DELAY REQUEST for the end-to-end delay mechanism.
PEER DELAY REQUEST | Yes | Used to calculate the delay of a link to incoming slave port. Used in the peer-to-peer delay mechanism.
PEER DELAY RESPONSE | Yes | Response to a request by a slave port. Used in the peer-to-peer delay mechanism.

Table 1: Some common PTP messages

Delay Mechanism | Description
--- | ---
End-to-End | Path delay is calculated from grandmaster to slave clock.
Peer-to-Peer | Path delay is calculated between each pair of clocks in the path between grandmaster and slave clocks.

Table 2: Delay Mechanisms

Timestamping Method | Description
--- | ---
software | Timestamps are generated in software and uses 2-step operation (for testing only).
twostep | Timestamps are generated in hardware and uses 2-step operation.
onestep | Timestamps are generated in hardware and uses 1-step operation.

Table 3: Timestamping Methods

Port States | Description
--- | ---
INITIALIZING | PTP is initialising hardware and communication on this port.
FAULTY | This port is currently experiencing a FAULT and will not transmit PTP messages.
LISTENING | This port is waiting to receive an announce packet from a master.
MASTER | This port is in a master state and is transmitting/forwarding synchronisation information.
UNCALIBRATED | This port has selected a master but is not currently synchronising. Note that this state is expected on transparent clocks which do not synchronise their clock.
SLAVE | This port is synchronising to its selected master port.

Table 4: PTP port states. This is not a complete listing or description, please refer to IEEE 1588 standard for a full description.

### 2-step to 1-step conversion

A 1-step TC automatically converts 2-step SYNC/FOLLOW_UP to 1-step SYNC (timestamping modes `onestep`). The TwoStepFlag bit identifies a SYNC message as 2-step, at which point it waits for the FOLLOW_UP to get the originTimestamp, places that into the SYNC, and sends it as a 1-step SYNC.

## Simple Use-Case examples

PTP may be employed in networks of different topologies, such as tree or ring. Figure 1 exemplifies network implementing tree topology, where TC acts as a port expander, allowing more devices to be connected to PTP network.

Figure 2 depicts ring topology formed by TCs. Besides allowing more devices to be connected to PTP network, this topology additionally provides failover and is therefore to some extent forgiving with regard to devices that may occasionally fail in one way or another. Note that in order to prevent loops one TC in PTP network will block one of its ring ports.

                                           .-------.
                                           |       |
                                +----------+s OC   |
                                |          |       |
                                |          '---+---'
            .-------.       .---+---.      .-------.
            |       |       |   m   |      |       |
            |  GM  m+-------+s TC  m+------+s OC   |
            |       |       |   m   |      |       |
            '-------'       '---+---'      '---+---'
                                |          .-------.
                                |          |       |
                                +----------+s OC   |
                                           |       |
                                           '-------'

Figure 1: Transparent clock as a port expander. The letters 'm' and 's' are denoted to represent MASTER and SLAVE ports respectively.

                                           .-------.
                                           |       |
                                +----------+s TC  m+----------+
                                |          |       |          |
                                |          '---+---'          |
            .-------.       .---+---.                     .---+---.      .-------.
            |       |       |   m   |                     |   b   |      |       |
            |  GM  m+-------+s TC   |                     |  TC  m+ -----+  OC   |
            |       |       |   m   |                     |   s   |      |       |
            '-------'       '---+---'                     '---+---'      '-------'
                                |          .-------.          |
                                |          |       |          |
                                +----------+s TC  m|----------+
                                           |       |
                                           '-------'

Figure 1: PTP Ring configuration. Let 'b' denote a port which is currently blocking PTP traffic. The letters 'm' and 's' are denoted to represent MASTER and SLAVE ports respectively.

## Global PTP Configuration

    example:/#> configure
    example:/config/#> ptp
    example:/config/ptp/#>

`[no] enable`
  Activate or deactivate PTP
`[no] minor_version [0|1]`

  PTP Minor Version

  Choose between IEEE 1588-2008 (2.0) and IEEE 1588-2019 (2.1) frame formats (default 2.0), by controlling minor version.

  These two frame formats are compatible, however, some older equipment might discard 2.1 frame format due to HW limitation.

`[no|show] clock [TYPE]`

  Type of PTP Clock

  There are several different types of PTP clocks, implementing different functions in a PTP network. An ordinary clock may act as a time source for other clocks, or synchronise against another ordinary clock.

  A transparent clock is used to transparently switch PTP messages, updating timestamps with a correction to adjust for its residence time.

  A boundary clock is used to synchronise the switch’s own clock and transmit new PTP Sync messages downstream, creating a boundary where changes upstream are isolated from the downstream.

  Note

  The support for an ordinary clock on this system is for testing purposes only.

`[no] description [name STRING] [location STRING]`
  User defined description
`[no|show] profile [TYPE]`

  PTP Profile

  PTP has many options and configurable attributes. A profile is a collection of default values or choices of these options and attributes.

  Each profile is specified so that a system can be configured without further user configuration of the profile specific settings.

  Specifically, default refers to the default configuration for this system if nothing else is chosen. Power-v1 and power-v2 refer to the 2011 and 2017 editions of the PTP power profile IEEE C37.238 respectively.

`[no] show`
  Show a summary of PTP settings

## Clock Configuration

Below is a list of all clock settings available in WeOS. Note that some options are specific to a certain type of clock and will be unavailable in other clock types.

`[no] client-only`

  Force the local clock to be a client clock

  A client clock will not be part of the Best Master Clock Algorithm (BMCA).

`[no] priority1 [NUM]`

  Priority1 attribute of the local clock

  This attribute is the most important attribute for chosing a master clock in the Best Master Clock Algorithm (BMCA).

`[no] priority2 [NUM]`

  Priority2 attribute of the local clock

  This attribute is used to determine a grand-master given that they have equal priority1, clock quality and offset variance.

`[no] ports [PORT | PORTA PORTB | PORTA..PORTB]`

  Configure Clock ports

  Port configuration depends on chosen clock type. Transparent clock requires at least 2 ports to be configured, while Ordinary clock requires only 1.

`[no] show`
  Show a summary of PTP clock settings

## Profile Configuration

Since PTP has vast range of options many of which are incompatible with each other, a need for some kind of standard arose and took shape of the so called profile. Profile is a set of predefined options, compatible with each other, providing out-of-the-box configuration. Devices configured with the same profile are said to work without the need of any additional configuration.

WeOS in combination with some specific hardware (to be checked in release notes), supports the following two IEEE standards for Power System Applications: IEEE C37.238-2011 IEEE C37.238-2017

For simplicity, IEEE C37.238-2011 standard is referred to as Power-v1 in WeOS, while IEEE C37.238-2017 as Power-v2.

`[no] delay endtoend|peertopeer`

  Delay Mechanism

  Delay mechanism is the method by which PTP calculates the delay on the path between synchronising clocks. This can be done by calculating the delay on each hop or across the full path. These modes are called end-to-end and peer-to-peer respectively.

  Peer-to-peer mode is more resistant to changes in the network, while end-to-end mode may allow for non PTP devices in the network.

`[no] domain [NUM]`

  Domain number of the local clock

  Domain number specifies which clock domain this clock belongs too. Local clock will synchronise to a grand-master belonging to the same domain.

  Available range: [0 - 255] Reserved range: [128 - 255] Standard range: [0 - 127]

  Domain number 0 is the default domain in profile C37.238-2011 (power-v1).

  Domain number 254 is only allowed to be used in profile IEEE C37.238-2011 (power-v2), as an exception, and is that profile’s default domain.

`[no] egress-vlan id [NUM] prio [NUM]`

  VLAN (8021Q) settings for PTP packets.

  VLAN settings for PTP packets on egress. PTP packets will be transmitted with the configured VLAN priority and id.

`[no] timestamping software|twostep|onestep`

  Time Stamping method

  Timestamps can be generated either in hardware or in software. Software timestamps are generated before being passed to hardware for transmission; increasing jitter and path-delay. Hardware timestamping is done close to the wire, providing much better accuracy.

  There are two hardware timestamping methods:

  - two-step - first step is taking the timestamp when sending SYNC packet, and second step is sending this timestamp in a FOLLOWUP packet.

  - one-step - taking timestamp and sending it in a SYNC message is done in one step. And if hardware supports it, peer-to-peer messages are also sent in one step.

  Software timestamping is always two-step.

  software
    Timestamps are generated in software and uses 2-step operation (for testing only).
  twostep
    Timestamps are generated in hardware and uses 2-step operation.
  onestep
    Timestamps are generated in hardware and uses 1-step operation.
`[no] logAnnounceInterval [INTERVAL]`

  Frequency of ‘Announce’ messages sent by an OC/BC

  0=1s interval, 1=2s, 2=4s, 3=8s, -1=0.5s, -2=0.25. As defined in IEEE 1588.

`[no] step_threshold [NUM]`

  Offset at which an OC/BC steps the clock

  A value of 0 means it will never step beyond the initial synchronisation. The value 0.00002 (20 microseconds) is used for the initial synchronisation

  Default: 0

  Range: 0-1 (floating point)

`[no] show`
  Show a summary of PTP profile settings

## Status Overview

Status of local PTP clock and PTP network may be obtaine by commands available inside ptp context of adminexec.

    example:/#> ptp
    example:/ptp/#>

`[no] network [clock-ID ID] [boundary-hop NUM]`

  Show PTP network summary

  Query PTP network for management responses. By default, local boundary domain is queried and summarised. If an ID is specified, a more detailed summary of only that clock’s response is displayed.

`[no] query [boundary-hop NUM] DATASET1 DATASET2..`

  Query network for PTP management response.

  The Precision Time Protocol (PTP), with reference to IEEE 1588 has multitude of parameters which may be of interest for configuration and debugging purposes.

  By default, this command sends management packets to the local clock, which responds with data sets as specified by the 1588 standard. If boundary hop is specified, query the network.

`[no] show`
  Show summary of PTP clock and ports.

`show` command displays summary of the local clock and and overview of directly connected neighbours.

    tc:/#> show ptp
    Clock
    ID                : 00077c.fffe.785325
    Type              : TC P2P
    Domain            : 0
    Mean Path delay   : 0.0
    Master Offset     : -7075504342646.0
    Priority1         : 254
    Priority2         : 128
    Product           : Westermo;RedFox-5728-E-F16G-T12G-HVHV;00:07:7c:78:53:20
    Distance          : 1
    Description       : tcbridge;room2

    Ports
    ID                     INTERFACE        STATE          PEER DELAY
    00077c.fffe.785325-1   eth5             MASTER         96
    00077c.fffe.785325-2   eth11            UNCALIBRATED   90
    00077c.fffe.785325-3   eth25            MASTER         8

`show network` command queries PTP network for PTP management responses and aggregates a summary. Each clock will be identifiable via its ID. This ID may also be used to provide a summary of a remote clock. Here’s how this command may look like: `show network clock-id 0011b4.fffe.2ed8c7`. If the clock is behind one or more boundary clocks, the option `boundary-hops` may also be specified.

    tc:/#> show ptp network

    Clocks
    ID                     TYPE    DOMAIN   MASTER OFFSET   DESCRIPTION
    00077c.fffe.785325     TC P2P  0        -775503935118.0 tcbridge;room2
    00077c.fffe.7bf4c5     OC      0        0.0             grandmaster;room1
    00077c.fffe.78530b     OC      0        1.0             slave1;room3
    00077c.fffe.784fda     OC      0        1.0             slave2;room3

    tc:/#> show ptp network  clock-id 00077c.fffe.7bf4c5
    Clock
    ID                : 00077c.fffe.7bf4c5
    Type              : OC
    Domain            : 0
    Mean Path delay   : 0.0
    Master Offset     : 0.0
    Priority1         : 128
    Priority2         : 128
    Product           : Westermo;RedFox-5728-E-F16G-T12G-HVHV;00:07:7c:7b:f4:c0
    Distance          : 0
    Description       : grandmaster;room1

    Ports
    ID                     STATE          PEER DELAY
    00077c.fffe.7bf4c5-1   MASTER         95

Lastly, the `query` command embodies utility for showing PTP management responses in a more raw manner. It is useful if one knows exactly what one is looking for, but may require more comprehensive knowledge of PTP to be correctly understood.

    tc:/#> show ptp query
    TRANSPARENT_CLOCK_DEFAULT
    00077c.fffe.785325-0
        clockIdentity                           00077c.fffe.785325
        numberPorts                             3
        delayMechanism                          2
        primaryDomain                           0
    TRANSPARENT_CLOCK_PORT
    00077c.fffe.785325-1
        portIdentity                            00077c.fffe.785325-1
        faultyFlag                              0
        logMinPdelayReqInterval                 0
        peerMeanPathDelay                       92
    00077c.fffe.785325-2
        portIdentity                            00077c.fffe.785325-2
        faultyFlag                              0
        logMinPdelayReqInterval                 0
        peerMeanPathDelay                       90
    00077c.fffe.785325-3
        portIdentity                            00077c.fffe.785325-3
        faultyFlag                              0
        logMinPdelayReqInterval                 0
        peerMeanPathDelay                       8

« Previous Next »