Introduction

Precision Time Protocol (PTP) is a protocol used to synchronize clocks in a network, which is exactly what NTP (Network Time Protocol) does, but the major difference is that PTP performs synchronization 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:

Overview

Since PTP is but a method of synchronizing 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 analyzed 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 synchronizing 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 synchronizing with another Master or Grandmaster.

Slave - device on the network wishing to synchronize 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 synchronize to GM.

  • Transparent Clock (TC): switching device on the network, itself taking no part in BMCA and having no interest in getting synchronized with GM, but capable of forwarding PTP messages with as little impact on synchronization 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 synchronization.

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

Note

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

BMCA and GM election process

Before synchronization 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.

Synchronization

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 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. Synchronization 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.

Synchronization 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.
hardware Timestamps are generated in hardware and sent as a follow-up packet.
onestep Timestamps are generated in hardware and sent immediately for Sync and Delay-Request packets. Others are sent in a follow-up packet.
p2p1step Timestamps are generated in hardware and sent immediately for both Sync packets and Peer-Delay-Request packets.

Table 3: Timestamping Methods

Port States Description
INITIALIZING PTP is initializing 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.
UNCALIBRATED This port has selected a master but is not currently synchronizing. Note that this state is expected on transparent clocks which do not synchronize their clock.
SLAVE This port is synchronizing 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.

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|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 synchronize 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.

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 synchronizing 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 synchronize 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|hardware|onestep|p2p1step

Time Stamping method

Timestamps can be generated via the use of hardware or software. In software, timestamps are generated before being passed to hardware for transmission; increasing jitter and path-delay. In hardware, timestamping is done close to the wire, allowing precise timestamping.

In hardware, timestamps can either be generated and sent directly (onestep) or generated and sent in a follow-up packet at a later time (twostep). Software timestamping by necessity is always twostep, while timestamping in hardware may depend on capabilities and configuration.

Hardware timestamping refers to twostep timestamping, onestep to end-to-end packets and p2p1step to onestepped peer-to-peer packets.

[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 summarized. 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 neighbors.

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