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