0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===========================================
0004 PTP hardware clock infrastructure for Linux
0005 ===========================================
0006
0007 This patch set introduces support for IEEE 1588 PTP clocks in
0008 Linux. Together with the SO_TIMESTAMPING socket options, this
0009 presents a standardized method for developing PTP user space
0010 programs, synchronizing Linux with external clocks, and using the
0011 ancillary features of PTP hardware clocks.
0012
0013 A new class driver exports a kernel interface for specific clock
0014 drivers and a user space interface. The infrastructure supports a
0015 complete set of PTP hardware clock functionality.
0016
0017 + Basic clock operations
0018 - Set time
0019 - Get time
0020 - Shift the clock by a given offset atomically
0021 - Adjust clock frequency
0022
0023 + Ancillary clock features
0024 - Time stamp external events
0025 - Period output signals configurable from user space
0026 - Low Pass Filter (LPF) access from user space
0027 - Synchronization of the Linux system time via the PPS subsystem
0028
0029 PTP hardware clock kernel API
0030 =============================
0031
0032 A PTP clock driver registers itself with the class driver. The
0033 class driver handles all of the dealings with user space. The
0034 author of a clock driver need only implement the details of
0035 programming the clock hardware. The clock driver notifies the class
0036 driver of asynchronous events (alarms and external time stamps) via
0037 a simple message passing interface.
0038
0039 The class driver supports multiple PTP clock drivers. In normal use
0040 cases, only one PTP clock is needed. However, for testing and
0041 development, it can be useful to have more than one clock in a
0042 single system, in order to allow performance comparisons.
0043
0044 PTP hardware clock user space API
0045 =================================
0046
0047 The class driver also creates a character device for each
0048 registered clock. User space can use an open file descriptor from
0049 the character device as a POSIX clock id and may call
0050 clock_gettime, clock_settime, and clock_adjtime. These calls
0051 implement the basic clock operations.
0052
0053 User space programs may control the clock using standardized
0054 ioctls. A program may query, enable, configure, and disable the
0055 ancillary clock features. User space can receive time stamped
0056 events via blocking read() and poll().
0057
0058 Writing clock drivers
0059 =====================
0060
0061 Clock drivers include include/linux/ptp_clock_kernel.h and register
0062 themselves by presenting a 'struct ptp_clock_info' to the
0063 registration method. Clock drivers must implement all of the
0064 functions in the interface. If a clock does not offer a particular
0065 ancillary feature, then the driver should just return -EOPNOTSUPP
0066 from those functions.
0067
0068 Drivers must ensure that all of the methods in interface are
0069 reentrant. Since most hardware implementations treat the time value
0070 as a 64 bit integer accessed as two 32 bit registers, drivers
0071 should use spin_lock_irqsave/spin_unlock_irqrestore to protect
0072 against concurrent access. This locking cannot be accomplished in
0073 class driver, since the lock may also be needed by the clock
0074 driver's interrupt service routine.
0075
0076 Supported hardware
0077 ==================
0078
0079 * Freescale eTSEC gianfar
0080
0081 - 2 Time stamp external triggers, programmable polarity (opt. interrupt)
0082 - 2 Alarm registers (optional interrupt)
0083 - 3 Periodic signals (optional interrupt)
0084
0085 * National DP83640
0086
0087 - 6 GPIOs programmable as inputs or outputs
0088 - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
0089 used as general inputs or outputs
0090 - GPIO inputs can time stamp external triggers
0091 - GPIO outputs can produce periodic signals
0092 - 1 interrupt pin
0093
0094 * Intel IXP465
0095
0096 - Auxiliary Slave/Master Mode Snapshot (optional interrupt)
0097 - Target Time (optional interrupt)
0098
0099 * Renesas (IDT) ClockMatrix™
0100
0101 - Up to 4 independent PHC channels
0102 - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2)
0103 - Programmable output periodic signals
0104 - Programmable inputs can time stamp external triggers
0105 - Driver and/or hardware configuration through firmware (idtcm.bin)
0106 - LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2))
0107 - Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs)
0108 - Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional)
