White Paper
Linux Kernel Support for IEEE 1588 Hardware Timestamping
Michael Rupert, Principle System Design Engineer, Data Center Business Division

Abstract
This white paper discusses Linux kernel support for IEEE 1588 hardware timestamping, including the precisiontime protocol (PTP) hardware clock (PHC) infrastructure, and the SO_TIMESTAMPING socket option. The PHC
infrastructure and the SO_TIMESTAMPING socket option offer standardized APIs for user-space applicationsand Linux kernel device drivers. These kernel facilities improve device driver availability and simplify system
integration.

Introduction
IEEE 1588 defines a protocol, the Precision Time Protocol (PTP), that enables accurate synchronization overpacket switched networks (PSN). Hardware timestamping of PTP event messages is key to achievingnanosecond synchronization accuracy for PTP slave clocks.
A typical PTP slave clock with hardware time stamping can be divided into four components:
1. User-space software that implements an IEEE 1588 protocol stack and a PTP clock servo
2. Hardware time stamp unit (TSU) integrated with a MAC or PHY
3. PTP hardware clock (PHC) that provides the timing reference for the hardware TSU and that is controlled by
the PTP clock servo
4. Linux kernel
The Linux kernel implements built-in support for hardware timestamping of PTP event messages. The support iscomprised of the PHC infrastructure and the SO_TIMESTAMPING socket option. These kernel facilities provide
standardized user-space APIs for the PHC and TSU functions, and they provide standardized interfaces for PHC
and TSU device drivers. The net result for system integrators is improved availability of device drivers andsimplified system integration, resulting in lower development costs and reduced time to market.
To realize the benefits of the PTP support in Linux, PHC device drivers must support the PHC infrastructure; andTSU drivers must support the SO_TIMESTAMPING socket option.
Renesas provides a Linux kernel driver for the ClockMatrix family that supports the Linux PHC infrastructure.
Any IEEE 1588 software package that uses the Linux PHC API can control a ClockMatrix device using this API.
For example, Linux PTP from the Network Time Foundation is designed to use the Linux PHC API. The
ClockMatrix Linux kernel driver is available as part of main line Linux.
The Renesas PTP Clock Manager software includes a PTP clock servo with a packet delay variation (PDV) filterand other functionality that meets global ITU-T synchronization recommendations for telecom applications. The
PTP Clock Manager can be used with any IEEE 1588 protocol stack (e.g., Linux PTP) and it is compatible with
the Linux PHC API. The PTP Clock Manager is available under license from Renesas.

Rev.1.0 X0119302
Jan.29.21

Page 1
Copyright © 2021

Linux Kernel Support for IEEE 1588 Hardware Timestamping White Paper

Contents
Abstract .................................................................................................................................................................. 1
Introduction ............................................................................................................................................................ 1
Contents ................................................................................................................................................................. 2
Definitions .............................................................................................................................................................. 3
Basic Synchronization for a PTP Slave Clock .................................................................................................... 3
Hardware Timestamping of PTP Event Messages ............................................................................................. 4
Synchronizing a TSU with a Separate PHC......................................................................................................... 5
Renesas PTP Synchronization Solutions ........................................................................................................... 5
PTP Synchronization Solution Using Open Source Software Only ................................................................. 5
PTP Synchronization Solution Using Open Source and Renesas Software ................................................... 6
Conclusion ............................................................................................................................................................. 7
Revision History .................................................................................................................................................... 8

Rev.1.0 X0119302
Jan.29.21

Page 2

Linux Kernel Support for IEEE 1588 Hardware Timestamping White Paper

Definitions•

ClockIEEE 1588 defines a clock as follows: A device that can provide a measurement of the passage of time sincea defined epoch.

•

Clock Signal
IEEE 1588 defines a clock signal as follows: A physical signal that has periodic events. The periodic events
mark the significant instants at which a time counter is incremented. The clock signal is characterized by its
frequency and phase.

•IEEE 1588
Precision Time Protocol – IEEE 1588[ 1] defines a protocol, the Precision Time Protocol (PTP), that enables
accurate synchronization over packet switched networks (PSN). PTP has a wide range of applications
including telecom, industrial, enterprise, and others. PTP can be used to synchronize PTP slave clocks withnanosecond accuracy.

Basic Synchronization for a PTP Slave Clock
Figure 1 shows the basic PTP event message exchange between a PTP master and a PTP slave; also shown is
a PTP slave clock implemented as a servo loop with a clock servo controller (clock servo). Under ideal
conditions, the clock servo can calculate the time offset of its local time stamp unit (TSU) versus the TSU of themaster using EQ1. The time offset is digitally compensated by the clock servo; afterwards, the frequency of the
PTP slave clock signal is periodically adjusted to keep the time offset near zero. Therefore, the PTP slave clock
is synchronized and locked to the PTP master clock.
EQ1.

𝑷𝑷𝑷𝑷𝑷𝑷 𝑺𝑺𝑺𝑺𝑺𝑺𝑺𝑺𝑺𝑺 𝑪𝑪𝑪𝑪𝑪𝑪𝑪𝑪𝑪𝑪 𝑻𝑻𝑻𝑻𝑻𝑻𝑻𝑻 𝑶𝑶𝑶𝑶𝑶𝑶𝑶𝑶𝑶𝑶𝑶𝑶 =MasterClock
Time

PTP Master Clock(𝒕𝒕𝟐𝟐 −𝒕𝒕𝟏𝟏 )−(𝒕𝒕𝟒𝟒 −𝒕𝒕𝟑𝟑 )
𝟐𝟐

Slave
Clock
Time

PTP Slave Clockt1
Clock Signal

t3
t4

TSU = Time Stamp Unit

Clock
Correction

Servo
Loop

t2

TSU

Clock Servo
Controller

t1, t2 , t3, t4

TSU

Clock Signal

Clock
Synthesizer

The TSUs measure the passage of time bycounting cycles of a clock signal of known
nominal frequency.
t1, t2 , t3, t4 are measured by the TSUs and are
known to the PTP slave clock; they are used to
calculate the PTP slave clock time offset.

Figure 1. Basic Precision Time Protocol Event Message Exchange

1 IEEE Std 1588-2019, Standard for a Precision Clock Synchronization Protocol for Networked Measurement

and Control Systems.
Rev.1.0 X0119302
Jan.29.21

Page 3

Linux Kernel Support for IEEE 1588 Hardware Timestamping White Paper

Hardware Timestamping of PTP Event Messages
Hardware timestamping of PTP event messages is key to achieving nanosecond synchronization accuracy for
PTP slave clocks. The TSU should be in the signal path as close to the physical layer as practical. Hardware
TSUs are typically implemented in network interface devices such as MACs or PHYs. Compared to softwaretimestamping, hardware timestamping reduces uncertainty in the arrival and departure times of PTP event
messages from milliseconds to nanoseconds; and in this way, hardware timestamping improves the accuracy of
a PTP slave clock.
Hardware TSUs incorporate a time of day (TOD) accumulator that measures the passage of time by counting thecycles of a reference clock signal from a PTP hardware clock (PHC). The PHC is steered by the PTP clock servothat issues corrections (clock operations) to the PHC. The IEEE 1588 protocol stack obtains the PTP timestamp
information from the hardware TSU and provides it to the clock servo. This is illustrated in Figure 2.
PTP Slave Clock
User Space

GPL-2 SWIEEE 1588
Protocol Stackt1, t2 , t3, t4

PTP timestamps

TSU = Time Stamp Unit
PHC = PTP Hardware Clock
TOD = Time of Day
PPS = Pulse Per Second

SO_TIMESTAMPING
Socket Option

PTP
Packets

TODM

Clock Operations

Linux Kernel

PacketSwitched
Network

PTP
Packets

Standard
Interfaces

PHC
InfrastructureStandard
Interfaces

Kernel Driver

PTP
Master Clock

PTP Clock
Clock Servo

Kernel Driver

MAC

Clock
SignalHardware
TSU
TODTSU

PPS
TOD

PHC

Servo
Loop

Local
Oscillator

TODPHC

Figure 2. Typical PTP Slave Clock Implementation Using Hardware Timestamping
The logical PHC and TSU functions can be implemented in a single silicon device or they can be implemented inseparate devices. Separate timing devices have advantages 2 as a central resource for generating and managing
clock signals that are shared between TSUs in multiple devices. For this reason, the PHC function is often
implemented in a dedicated timing device. Figure 2 shows TSU and PHC functions implemented in separate
devices.
A perennial challenge for PTP system integrators is obtaining and maintaining drivers for PHCs and hardware
TSUs. It is inefficient for silicon device manufacturers to create drivers to cover more than a few of the PTP
protocol stacks and clock servo software packages available in the industry. For this reason, device
manufacturers typically provide example driver code and leave driver development to the system integrator.
The Linux kernel implements built-in support for hardware timestamping of PTP event messages. The support iscomprised of the PHC infrastructure and the SO_TIMESTAMPING socket option (see Figure 2). These kernel

2 Advantages include: Adjusting clock skews with sub-nanosecond resolution, measuring clock delays,

generating low phase-noise clocks, generating clocks with a range of frequencies, generating ITU-T compliant
synchronous Ethernet clocks, and managing redundant clock sources, etc.
Rev.1.0 X0119302
Jan.29.21

Page 4

Linux Kernel Support for IEEE 1588 Hardware Timestamping White Paper

facilities provide standardized user-space APIs for the PHC and TSU functions, and they provide standardized
interfaces for PHC and TSU device drivers.
Developers can write their user-space PTP applications for the standard Linux APIs without detailed knowledgeof the PHC or TSU devices that will be used in the final system. Similarly, silicon device manufacturers can writeand validate Linux kernel device drivers using the standard Linux kernel APIs without detailed knowledge of theuser-space applications that will use them. The net result for system integrators is improved availability of device
drivers and simplified system integration, resulting in lower development costs and reduced time to market.
Linux kernel support for PTP helps ensure forward compatibility with new kernel releases. The Linux kernel
developers strive to maintain stable user-space APIs as the kernel evolves, and kernel device drivers that arepart of main line Linux are maintained from release to release. Furthermore, the Linux community and the silicon
device manufacturers can make improvements to the drivers and every system that uses them can easily adopt
them.
To realize the benefits of the PTP support in Linux, PHC device drivers must support the PHC infrastructure; andTSU drivers must support the SO_TIMESTAMPING socket option. For reasons described below, it is also usefulfor the TSU driver to support the PHC infrastructure for its TOD accumulator.
The SO_TIMESTAMPING socket option and the PHC infrastructure are available together in Linux kernel
versions 3.0 and later.

Synchronizing a TSU with a Separate PHC
When the PHC and TSU are implemented separately, the system integrator must synchronize TODTSU with
TODPHC. This can be done by timing TODTSU with the same PHC clock and pulse per second (PPS) signals thattime TODPHC. At system start-up there will be a static time offset between TODTSU and TODPHC that must be
eliminated; there is an open-source user-space application called ts2phc[3] available for this purpose. The ts2phc
utility controls TODTSU as a PHC; a prerequisite is that the TSU driver must support the PHC infrastructure. Any
frequency adjustments made to the PHC after the two TODs are aligned will be tracked by the TSU.

Renesas PTP Synchronization Solutions
The Renesas ClockMatrix family of timing devices includes several products designed for use as PHCs (e.g.,
8A34001/2/3/4/5 are excellent devices for telecom PHC applications). Renesas created a Linux kernel driver for
the ClockMatrix family that supports the Linux PHC infrastructure. The ClockMatrix driver is available as part ofmain line Linux and it is compatible with Linux kernel versions 3.0 and higher.

PTP Synchronization Solution Using Open Source Software Only
The ClockMatrix Linux kernel driver is compatible with the Linux PTP software suite version 3.0 and higher,
including its IEEE 1588-2019 protocol stack, and the included PTP clock servo and ts2phc utility. Linux PTP isan open-source (GPL-2) software suite available from the Network Time Foundation.
When used with a ClockMatrix device, Linux PTP will bypass the software low-pass filter function of its PTP
clock servo and instead will use the write phase mode and hardware low-pass filter implemented by the
ClockMatrix devices. This servo implementation is suitable for applications that do not need to handle high levelsof packet delay variation (PDV)[4].

3 The ts2phc utility is included in the Linux PTP software suite available from the Network Time Foundation.
4 For more information, see the Renesas whitepaper titled Limiting IEEE 1588 Slave Clock Wander Caused byPacket Delay Variation.

Rev.1.0 X0119302
Jan.29.21

Page 5

Linux Kernel Support for IEEE 1588 Hardware Timestamping White Paper

Figure 3 illustrates a PTP slave clock design that uses open-source software only, and is suitable forapplications that do not need to handle high levels of PDV.
PTP Slave Clock

Renesas SW
Renesas HWLinux PTP v3+
IEEE 1588
Protocol Stack

User Space

GPL-2 SW
Non-Renesas SW
Non-Renesas HWt1, t2 , t3, t4

SO_TIMESTAMPING
Socket Option

PHC
InfrastructureLinux Kernel

PTP
Packets

TODM

PacketSwitched
Network

PTP
Packets

Servo
Loop

Kernel Driver

Kernel Driver

PTP
Master Clock

Linux PTP Suite

Clock Operations

PTP timestamps

TSU = Time Stamp Unit
PHC = PTP Hardware Clock
TOD = Time of Day
PPS = Pulse Per Second

Linux PTP3+
PTP Clock
Clock Servo

MAC

Clock
SignalHardware
TSU
TODTSUPPS
TOD

RenesasClockMatrix

Local
Oscillator

TODPHC

Figure 3. Renesas PTP Slave Clock Implementation Using Only Open-Source Software

PTP Synchronization Solution Using Open Source and Renesas Software
The design shown in Figure 3 is suitable for many PTP applications. However, for applications that require
tolerance to PDV and global compliance to ITU-T synchronization recommendations for telecom applications, amore sophisticated PTP clock servo is needed.
The Renesas PTP Clock Manager user-space application is available from Renesas under license for use withRenesas timing devices. The PTP Clock Manager includes a PTP clock servo with a PDV filter[4] and otherfunctionality that meets global ITU-T synchronization recommendations for telecom applications. The PTP ClockManager is compatible with Linux PTP versions 3.0 and higher, specifically the IEEE 1588-2019 protocol stack; itis also compatible with Linux kernel versions 3.0 and higher.
The Renesas PTP Clock Manager synchronizes the TODTSU with the TODPHC using its own alternative to ts2phc.
While synchronizing TODTSU with TODPHC, the PTP Clock Manager controls TODTSU as a PHC; a prerequisite isthat the TSU driver must support the PHC infrastructure.
Figure 4 shows a PTP slave clock design that uses the Renesas PTP Clock Manager software. This clock
design is suitable for applications that need to manage high levels of PDV and/or that need to comply with global
ITU-T synchronization recommendation for telecom applications.

Rev.1.0 X0119302
Jan.29.21

Page 6

Linux Kernel Support for IEEE 1588 Hardware Timestamping White Paper

PTP Slave Clock

Renesas SW
Renesas HWLinux PTP v3+
IEEE 1588
Protocol Stack

User Space

GPL-2 SW
Non-Renesas SW
Non-Renesas HWt1, t2 , t3, t4

Clock Operations

PTP timestamps

TSU = Time Stamp Unit
PHC = PTP Hardware Clock
TOD = Time of Day
PPS = Pulse Per Second
UDS = Unix Domain Socket

UDS

SO_TIMESTAMPING
Socket Option

PTP
Packets

TODM

PHC
InfrastructureLinux Kernel

PacketSwitched
Network

PTP
Packets

Servo
Loop

Kernel Driver

Kernel Driver

PTP
Master Clock

Renesas PTP
Clock Manager
Clock Servo

MAC

Clock
SignalHardware
TSU
TODTSUPPS
TOD

RenesasClockMatrix

Local
Oscillator

TODPHC

Figure 4. Renesas PTP Slave Clock Implementation Using PTP Clock Manager Software

Conclusion
Hardware timestamping of PTP event messages is key to achieving nanosecond synchronization accuracy for
PTP slave clocks. Hardware timestamping is implemented with hardware TSUs timed by clock signals generated
by PHCs. The hardware TSUs are often integrated with PHYs and MACs for proximity to the physical layer.
The logical PHC and TSU functions can be implemented in a single silicon device or they can be implemented inseparate devices. A separate timing device has advantages as a central resource for generating and managing
clock signals that are shared between TSUs in multiple devices. For this reason, the PHC function is often
implemented in a dedicated timing device.
The Linux kernel implements built-in support for hardware timestamping of PTP event messages. The support iscomprised of the PHC infrastructure and the SO_TIMESTAMPING socket option. These kernel facilities provide
standardized user-space APIs for the PHC and TSU functions, and they provide standardized interfaces for PHC
and TSU device drivers. The net result for system integrators is improved availability of device drivers andsimplified system integration, resulting in lower development costs and reduced time to market.
To realize the benefits of the PTP support in Linux, PHC device drivers must support the PHC infrastructure; andTSU drivers must support the SO_TIMESTAMPING socket option. It is also useful for the TSU driver to support
the PHC infrastructure for its TOD accumulator.
The Renesas ClockMatrix family of timing devices are an excellent choice to implement PHCs for hardware
timestamping applications. Renesas provides a Linux kernel driver for the ClockMatrix family that supports theLinux PHC infrastructure.
The Renesas PTP Clock Manager software implements a PTP clock servo with a PDV filter and otherfunctionality that meets global ITU-T synchronization recommendations for telecom applications. The PTP ClockManager is compatible with the Linux PHC infrastructure.
The standardized PHC infrastructure and SO_TIMESTAMPING socket option APIs enable modularity of PTP
functions. For example, the Renesas PTP Clock Manager can be substituted for the Linux PTP servo forapplications that require PDV filtering. Similarly, the hardware based low-pass filter in the ClockMatrix devices
can be substituted for the software based low-pass filter in the Linux PTP servo.

Rev.1.0 X0119302
Jan.29.21

Page 7

Linux Kernel Support for IEEE 1588 Hardware Timestamping White Paper

Revision History
Revision

Date

1.0

Jan.29.21

Rev.1.0 X0119302
Jan.29.21

Description
Initial release.

Page 8

IMPORTANT NOTICE AND DISCLAIMER
RENESAS ELECTRONICS CORPORATION AND ITS SUBSIDIARIES (“RENESAS”) PROVIDES TECHNICALSPECIFICATIONS AND RELIABILITY DATA (INCLUDING DATASHEETS), DESIGN RESOURCES (INCLUDINGREFERENCE DESIGNS), APPLICATION OR OTHER DESIGN ADVICE, WEB TOOLS, SAFETY INFORMATION, AND
OTHER RESOURCES “AS IS” AND WITH ALL FAULTS, AND DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, OR NON-INFRINGEMENT OF THIRD-PARTY INTELLECTUAL PROPERTY RIGHTS.
These resources are intended for developers who are designing with Renesas products. You are solely responsible for (1)selecting the appropriate products for your application, (2) designing, validating, and testing your application, and (3)ensuring your application meets applicable standards, and any other safety, security, or other requirements. These
resources are subject to change without notice. Renesas grants you permission to use these resources only to develop an
application that uses Renesas products. Other reproduction or use of these resources is strictly prohibited. No license is
granted to any other Renesas intellectual property or to any third-party intellectual property. Renesas disclaims
responsibility for, and you will fully indemnify Renesas and its representatives against, any claims, damages, costs, losses,
or liabilities arising from your use of these resources. Renesas' products are provided only subject to Renesas' Terms andConditions of Sale or other applicable terms agreed to in writing. No use of any Renesas resources expands or otherwise
alters any applicable warranties or warranty disclaimers for these products.

(Disclaimer Rev.1.01 Jan 2024)

Corporate Headquarters

Contact Information

TOYOSU FORESIA, 3-2-24 Toyosu,
Koto-ku, Tokyo 135-0061, Japan
www.renesas.com

For further information on a product, technology, the most
up-to-date version of a document, or your nearest sales
office, please visit www.renesas.com/contact-us/.

Trademarks
Renesas and the Renesas logo are trademarks of Renesas
Electronics Corporation. All trademarks and registeredtrademarks are the property of their respective owners.

© 2024 Renesas Electronics Corporation. All rights reserved.