Commit | Line | Data |
---|---|---|
c92992fc | 1 | .. SPDX-License-Identifier: GPL-2.0 |
d94ba80e | 2 | |
329f0041 MCC |
3 | =========================================== |
4 | PTP hardware clock infrastructure for Linux | |
5 | =========================================== | |
d94ba80e RC |
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 | |
d94ba80e RC |
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 | ||
329f0041 MCC |
28 | PTP hardware clock kernel API |
29 | ============================= | |
d94ba80e RC |
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 | ||
329f0041 MCC |
43 | PTP hardware clock user space API |
44 | ================================= | |
d94ba80e RC |
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 | |
93e9ad98 | 55 | events via blocking read() and poll(). |
d94ba80e | 56 | |
329f0041 MCC |
57 | Writing clock drivers |
58 | ===================== | |
d94ba80e RC |
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 | ||
329f0041 MCC |
75 | Supported hardware |
76 | ================== | |
77 | ||
78 | * Freescale eTSEC gianfar | |
d94ba80e | 79 | |
d94ba80e RC |
80 | - 2 Time stamp external triggers, programmable polarity (opt. interrupt) |
81 | - 2 Alarm registers (optional interrupt) | |
82 | - 3 Periodic signals (optional interrupt) | |
83 | ||
329f0041 MCC |
84 | * National DP83640 |
85 | ||
d94ba80e RC |
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 | ||
329f0041 MCC |
93 | * Intel IXP465 |
94 | ||
d94ba80e RC |
95 | - Auxiliary Slave/Master Mode Snapshot (optional interrupt) |
96 | - Target Time (optional interrupt) |