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