138 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===========================================4PTP hardware clock infrastructure for Linux5===========================================6 7 This patch set introduces support for IEEE 1588 PTP clocks in8 Linux. Together with the SO_TIMESTAMPING socket options, this9 presents a standardized method for developing PTP user space10 programs, synchronizing Linux with external clocks, and using the11 ancillary features of PTP hardware clocks.12 13 A new class driver exports a kernel interface for specific clock14 drivers and a user space interface. The infrastructure supports a15 complete set of PTP hardware clock functionality.16 17 + Basic clock operations18 - Set time19 - Get time20 - Shift the clock by a given offset atomically21 - Adjust clock frequency22 23 + Ancillary clock features24 - Time stamp external events25 - Period output signals configurable from user space26 - Low Pass Filter (LPF) access from user space27 - Synchronization of the Linux system time via the PPS subsystem28 29PTP hardware clock kernel API30=============================31 32 A PTP clock driver registers itself with the class driver. The33 class driver handles all of the dealings with user space. The34 author of a clock driver need only implement the details of35 programming the clock hardware. The clock driver notifies the class36 driver of asynchronous events (alarms and external time stamps) via37 a simple message passing interface.38 39 The class driver supports multiple PTP clock drivers. In normal use40 cases, only one PTP clock is needed. However, for testing and41 development, it can be useful to have more than one clock in a42 single system, in order to allow performance comparisons.43 44PTP hardware clock user space API45=================================46 47 The class driver also creates a character device for each48 registered clock. User space can use an open file descriptor from49 the character device as a POSIX clock id and may call50 clock_gettime, clock_settime, and clock_adjtime. These calls51 implement the basic clock operations.52 53 User space programs may control the clock using standardized54 ioctls. A program may query, enable, configure, and disable the55 ancillary clock features. User space can receive time stamped56 events via blocking read() and poll().57 58Writing clock drivers59=====================60 61 Clock drivers include include/linux/ptp_clock_kernel.h and register62 themselves by presenting a 'struct ptp_clock_info' to the63 registration method. Clock drivers must implement all of the64 functions in the interface. If a clock does not offer a particular65 ancillary feature, then the driver should just return -EOPNOTSUPP66 from those functions.67 68 Drivers must ensure that all of the methods in interface are69 reentrant. Since most hardware implementations treat the time value70 as a 64 bit integer accessed as two 32 bit registers, drivers71 should use spin_lock_irqsave/spin_unlock_irqrestore to protect72 against concurrent access. This locking cannot be accomplished in73 class driver, since the lock may also be needed by the clock74 driver's interrupt service routine.75 76PTP hardware clock requirements for '.adjphase'77-----------------------------------------------78 79 The 'struct ptp_clock_info' interface has a '.adjphase' function.80 This function has a set of requirements from the PHC in order to be81 implemented.82 83 * The PHC implements a servo algorithm internally that is used to84 correct the offset passed in the '.adjphase' call.85 * When other PTP adjustment functions are called, the PHC servo86 algorithm is disabled.87 88 **NOTE:** '.adjphase' is not a simple time adjustment functionality89 that 'jumps' the PHC clock time based on the provided offset. It90 should correct the offset provided using an internal algorithm.91 92Supported hardware93==================94 95 * Freescale eTSEC gianfar96 97 - 2 Time stamp external triggers, programmable polarity (opt. interrupt)98 - 2 Alarm registers (optional interrupt)99 - 3 Periodic signals (optional interrupt)100 101 * National DP83640102 103 - 6 GPIOs programmable as inputs or outputs104 - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be105 used as general inputs or outputs106 - GPIO inputs can time stamp external triggers107 - GPIO outputs can produce periodic signals108 - 1 interrupt pin109 110 * Intel IXP465111 112 - Auxiliary Slave/Master Mode Snapshot (optional interrupt)113 - Target Time (optional interrupt)114 115 * Renesas (IDT) ClockMatrix™116 117 - Up to 4 independent PHC channels118 - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2)119 - Programmable output periodic signals120 - Programmable inputs can time stamp external triggers121 - Driver and/or hardware configuration through firmware (idtcm.bin)122 - LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2))123 - Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs)124 - Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional)125 126 * NVIDIA Mellanox127 128 - GPIO129 - Certain variants of ConnectX-6 Dx and later products support one130 GPIO which can time stamp external triggers and one GPIO to produce131 periodic signals.132 - Certain variants of ConnectX-5 and older products support one GPIO,133 configured to either time stamp external triggers or produce134 periodic signals.135 - PHC instances136 - All ConnectX devices have a free-running counter137 - ConnectX-6 Dx and later devices have a UTC format counter138