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    - Low Pass Filter (LPF) access from user space
27    - Synchronization of the Linux system time via the PPS subsystem
28
29PTP hardware clock kernel API
30=============================
31
32   A PTP clock driver registers itself with the class driver. The
33   class driver handles all of the dealings with user space. The
34   author of a clock driver need only implement the details of
35   programming the clock hardware. The clock driver notifies the class
36   driver of asynchronous events (alarms and external time stamps) via
37   a simple message passing interface.
38
39   The class driver supports multiple PTP clock drivers. In normal use
40   cases, only one PTP clock is needed. However, for testing and
41   development, it can be useful to have more than one clock in a
42   single system, in order to allow performance comparisons.
43
44PTP hardware clock user space API
45=================================
46
47   The class driver also creates a character device for each
48   registered clock. User space can use an open file descriptor from
49   the character device as a POSIX clock id and may call
50   clock_gettime, clock_settime, and clock_adjtime.  These calls
51   implement the basic clock operations.
52
53   User space programs may control the clock using standardized
54   ioctls. A program may query, enable, configure, and disable the
55   ancillary clock features. User space can receive time stamped
56   events via blocking read() and poll().
57
58Writing clock drivers
59=====================
60
61   Clock drivers include include/linux/ptp_clock_kernel.h and register
62   themselves by presenting a 'struct ptp_clock_info' to the
63   registration method. Clock drivers must implement all of the
64   functions in the interface. If a clock does not offer a particular
65   ancillary feature, then the driver should just return -EOPNOTSUPP
66   from those functions.
67
68   Drivers must ensure that all of the methods in interface are
69   reentrant. Since most hardware implementations treat the time value
70   as a 64 bit integer accessed as two 32 bit registers, drivers
71   should use spin_lock_irqsave/spin_unlock_irqrestore to protect
72   against concurrent access. This locking cannot be accomplished in
73   class driver, since the lock may also be needed by the clock
74   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 be
81   implemented.
82
83     * The PHC implements a servo algorithm internally that is used to
84       correct the offset passed in the '.adjphase' call.
85     * When other PTP adjustment functions are called, the PHC servo
86       algorithm is disabled.
87
88   **NOTE:** '.adjphase' is not a simple time adjustment functionality
89   that 'jumps' the PHC clock time based on the provided offset. It
90   should correct the offset provided using an internal algorithm.
91
92Supported hardware
93==================
94
95   * Freescale eTSEC gianfar
96
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 DP83640
102
103     - 6 GPIOs programmable as inputs or outputs
104     - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
105       used as general inputs or outputs
106     - GPIO inputs can time stamp external triggers
107     - GPIO outputs can produce periodic signals
108     - 1 interrupt pin
109
110   * Intel IXP465
111
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 channels
118     - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2)
119     - Programmable output periodic signals
120     - Programmable inputs can time stamp external triggers
121     - 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 Mellanox
127
128     - GPIO
129          - Certain variants of ConnectX-6 Dx and later products support one
130            GPIO which can time stamp external triggers and one GPIO to produce
131            periodic signals.
132          - Certain variants of ConnectX-5 and older products support one GPIO,
133            configured to either time stamp external triggers or produce
134            periodic signals.
135     - PHC instances
136          - All ConnectX devices have a free-running counter
137          - ConnectX-6 Dx and later devices have a UTC format counter
138