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