1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun=========================================== 4*4882a593SmuzhiyunPTP hardware clock infrastructure for Linux 5*4882a593Smuzhiyun=========================================== 6*4882a593Smuzhiyun 7*4882a593Smuzhiyun This patch set introduces support for IEEE 1588 PTP clocks in 8*4882a593Smuzhiyun Linux. Together with the SO_TIMESTAMPING socket options, this 9*4882a593Smuzhiyun presents a standardized method for developing PTP user space 10*4882a593Smuzhiyun programs, synchronizing Linux with external clocks, and using the 11*4882a593Smuzhiyun ancillary features of PTP hardware clocks. 12*4882a593Smuzhiyun 13*4882a593Smuzhiyun A new class driver exports a kernel interface for specific clock 14*4882a593Smuzhiyun drivers and a user space interface. The infrastructure supports a 15*4882a593Smuzhiyun complete set of PTP hardware clock functionality. 16*4882a593Smuzhiyun 17*4882a593Smuzhiyun + Basic clock operations 18*4882a593Smuzhiyun - Set time 19*4882a593Smuzhiyun - Get time 20*4882a593Smuzhiyun - Shift the clock by a given offset atomically 21*4882a593Smuzhiyun - Adjust clock frequency 22*4882a593Smuzhiyun 23*4882a593Smuzhiyun + Ancillary clock features 24*4882a593Smuzhiyun - Time stamp external events 25*4882a593Smuzhiyun - Period output signals configurable from user space 26*4882a593Smuzhiyun - Low Pass Filter (LPF) access from user space 27*4882a593Smuzhiyun - Synchronization of the Linux system time via the PPS subsystem 28*4882a593Smuzhiyun 29*4882a593SmuzhiyunPTP hardware clock kernel API 30*4882a593Smuzhiyun============================= 31*4882a593Smuzhiyun 32*4882a593Smuzhiyun A PTP clock driver registers itself with the class driver. The 33*4882a593Smuzhiyun class driver handles all of the dealings with user space. The 34*4882a593Smuzhiyun author of a clock driver need only implement the details of 35*4882a593Smuzhiyun programming the clock hardware. The clock driver notifies the class 36*4882a593Smuzhiyun driver of asynchronous events (alarms and external time stamps) via 37*4882a593Smuzhiyun a simple message passing interface. 38*4882a593Smuzhiyun 39*4882a593Smuzhiyun The class driver supports multiple PTP clock drivers. In normal use 40*4882a593Smuzhiyun cases, only one PTP clock is needed. However, for testing and 41*4882a593Smuzhiyun development, it can be useful to have more than one clock in a 42*4882a593Smuzhiyun single system, in order to allow performance comparisons. 43*4882a593Smuzhiyun 44*4882a593SmuzhiyunPTP hardware clock user space API 45*4882a593Smuzhiyun================================= 46*4882a593Smuzhiyun 47*4882a593Smuzhiyun The class driver also creates a character device for each 48*4882a593Smuzhiyun registered clock. User space can use an open file descriptor from 49*4882a593Smuzhiyun the character device as a POSIX clock id and may call 50*4882a593Smuzhiyun clock_gettime, clock_settime, and clock_adjtime. These calls 51*4882a593Smuzhiyun implement the basic clock operations. 52*4882a593Smuzhiyun 53*4882a593Smuzhiyun User space programs may control the clock using standardized 54*4882a593Smuzhiyun ioctls. A program may query, enable, configure, and disable the 55*4882a593Smuzhiyun ancillary clock features. User space can receive time stamped 56*4882a593Smuzhiyun events via blocking read() and poll(). 57*4882a593Smuzhiyun 58*4882a593SmuzhiyunWriting clock drivers 59*4882a593Smuzhiyun===================== 60*4882a593Smuzhiyun 61*4882a593Smuzhiyun Clock drivers include include/linux/ptp_clock_kernel.h and register 62*4882a593Smuzhiyun themselves by presenting a 'struct ptp_clock_info' to the 63*4882a593Smuzhiyun registration method. Clock drivers must implement all of the 64*4882a593Smuzhiyun functions in the interface. If a clock does not offer a particular 65*4882a593Smuzhiyun ancillary feature, then the driver should just return -EOPNOTSUPP 66*4882a593Smuzhiyun from those functions. 67*4882a593Smuzhiyun 68*4882a593Smuzhiyun Drivers must ensure that all of the methods in interface are 69*4882a593Smuzhiyun reentrant. Since most hardware implementations treat the time value 70*4882a593Smuzhiyun as a 64 bit integer accessed as two 32 bit registers, drivers 71*4882a593Smuzhiyun should use spin_lock_irqsave/spin_unlock_irqrestore to protect 72*4882a593Smuzhiyun against concurrent access. This locking cannot be accomplished in 73*4882a593Smuzhiyun class driver, since the lock may also be needed by the clock 74*4882a593Smuzhiyun driver's interrupt service routine. 75*4882a593Smuzhiyun 76*4882a593SmuzhiyunSupported hardware 77*4882a593Smuzhiyun================== 78*4882a593Smuzhiyun 79*4882a593Smuzhiyun * Freescale eTSEC gianfar 80*4882a593Smuzhiyun 81*4882a593Smuzhiyun - 2 Time stamp external triggers, programmable polarity (opt. interrupt) 82*4882a593Smuzhiyun - 2 Alarm registers (optional interrupt) 83*4882a593Smuzhiyun - 3 Periodic signals (optional interrupt) 84*4882a593Smuzhiyun 85*4882a593Smuzhiyun * National DP83640 86*4882a593Smuzhiyun 87*4882a593Smuzhiyun - 6 GPIOs programmable as inputs or outputs 88*4882a593Smuzhiyun - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be 89*4882a593Smuzhiyun used as general inputs or outputs 90*4882a593Smuzhiyun - GPIO inputs can time stamp external triggers 91*4882a593Smuzhiyun - GPIO outputs can produce periodic signals 92*4882a593Smuzhiyun - 1 interrupt pin 93*4882a593Smuzhiyun 94*4882a593Smuzhiyun * Intel IXP465 95*4882a593Smuzhiyun 96*4882a593Smuzhiyun - Auxiliary Slave/Master Mode Snapshot (optional interrupt) 97*4882a593Smuzhiyun - Target Time (optional interrupt) 98*4882a593Smuzhiyun 99*4882a593Smuzhiyun * Renesas (IDT) ClockMatrix™ 100*4882a593Smuzhiyun 101*4882a593Smuzhiyun - Up to 4 independent PHC channels 102*4882a593Smuzhiyun - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2) 103*4882a593Smuzhiyun - Programmable output periodic signals 104*4882a593Smuzhiyun - Programmable inputs can time stamp external triggers 105*4882a593Smuzhiyun - Driver and/or hardware configuration through firmware (idtcm.bin) 106*4882a593Smuzhiyun - LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2)) 107*4882a593Smuzhiyun - Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs) 108*4882a593Smuzhiyun - Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional) 109