Documentation/driver-api/ptp.rst
.. SPDX-License-Identifier: GPL-2.0
This patch set introduces support for IEEE 1588 PTP clocks in Linux. Together with the SO_TIMESTAMPING socket options, this presents a standardized method for developing PTP user space programs, synchronizing Linux with external clocks, and using the ancillary features of PTP hardware clocks.
A new class driver exports a kernel interface for specific clock drivers and a user space interface. The infrastructure supports a complete set of PTP hardware clock functionality.
Basic clock operations
Ancillary clock features
A PTP clock driver registers itself with the class driver. The class driver handles all of the dealings with user space. The author of a clock driver need only implement the details of programming the clock hardware. The clock driver notifies the class driver of asynchronous events (alarms and external time stamps) via a simple message passing interface.
The class driver supports multiple PTP clock drivers. In normal use cases, only one PTP clock is needed. However, for testing and development, it can be useful to have more than one clock in a single system, in order to allow performance comparisons.
The class driver also creates a character device for each registered clock. User space can use an open file descriptor from the character device as a POSIX clock id and may call clock_gettime, clock_settime, and clock_adjtime. These calls implement the basic clock operations.
User space programs may control the clock using standardized ioctls. A program may query, enable, configure, and disable the ancillary clock features. User space can receive time stamped events via blocking read() and poll().
Clock drivers include include/linux/ptp_clock_kernel.h and register themselves by presenting a 'struct ptp_clock_info' to the registration method. Clock drivers must implement all of the functions in the interface. If a clock does not offer a particular ancillary feature, then the driver should just return -EOPNOTSUPP from those functions.
Drivers must ensure that all of the methods in interface are reentrant. Since most hardware implementations treat the time value as a 64 bit integer accessed as two 32 bit registers, drivers should use spin_lock_irqsave/spin_unlock_irqrestore to protect against concurrent access. This locking cannot be accomplished in class driver, since the lock may also be needed by the clock driver's interrupt service routine.
The 'struct ptp_clock_info' interface has a '.adjphase' function. This function has a set of requirements from the PHC in order to be implemented.
* The PHC implements a servo algorithm internally that is used to
correct the offset passed in the '.adjphase' call.
* When other PTP adjustment functions are called, the PHC servo
algorithm is disabled.
NOTE: '.adjphase' is not a simple time adjustment functionality that 'jumps' the PHC clock time based on the provided offset. It should correct the offset provided using an internal algorithm.
Freescale eTSEC gianfar
National DP83640
Intel IXP465
Renesas (IDT) ClockMatrix™
NVIDIA Mellanox