Commit | Line | Data |
---|---|---|
d94ba80e RC |
1 | |
2 | * PTP hardware clock infrastructure for Linux | |
3 | ||
4 | This patch set introduces support for IEEE 1588 PTP clocks in | |
5 | Linux. Together with the SO_TIMESTAMPING socket options, this | |
6 | presents a standardized method for developing PTP user space | |
7 | programs, synchronizing Linux with external clocks, and using the | |
8 | ancillary features of PTP hardware clocks. | |
9 | ||
10 | A new class driver exports a kernel interface for specific clock | |
11 | drivers and a user space interface. The infrastructure supports a | |
12 | complete set of PTP hardware clock functionality. | |
13 | ||
14 | + Basic clock operations | |
15 | - Set time | |
16 | - Get time | |
17 | - Shift the clock by a given offset atomically | |
18 | - Adjust clock frequency | |
19 | ||
20 | + Ancillary clock features | |
d94ba80e RC |
21 | - Time stamp external events |
22 | - Period output signals configurable from user space | |
23 | - Synchronization of the Linux system time via the PPS subsystem | |
24 | ||
25 | ** PTP hardware clock kernel API | |
26 | ||
27 | A PTP clock driver registers itself with the class driver. The | |
28 | class driver handles all of the dealings with user space. The | |
29 | author of a clock driver need only implement the details of | |
30 | programming the clock hardware. The clock driver notifies the class | |
31 | driver of asynchronous events (alarms and external time stamps) via | |
32 | a simple message passing interface. | |
33 | ||
34 | The class driver supports multiple PTP clock drivers. In normal use | |
35 | cases, only one PTP clock is needed. However, for testing and | |
36 | development, it can be useful to have more than one clock in a | |
37 | single system, in order to allow performance comparisons. | |
38 | ||
39 | ** PTP hardware clock user space API | |
40 | ||
41 | The class driver also creates a character device for each | |
42 | registered clock. User space can use an open file descriptor from | |
43 | the character device as a POSIX clock id and may call | |
44 | clock_gettime, clock_settime, and clock_adjtime. These calls | |
45 | implement the basic clock operations. | |
46 | ||
47 | User space programs may control the clock using standardized | |
48 | ioctls. A program may query, enable, configure, and disable the | |
49 | ancillary clock features. User space can receive time stamped | |
93e9ad98 | 50 | events via blocking read() and poll(). |
d94ba80e RC |
51 | |
52 | ** Writing clock drivers | |
53 | ||
54 | Clock drivers include include/linux/ptp_clock_kernel.h and register | |
55 | themselves by presenting a 'struct ptp_clock_info' to the | |
56 | registration method. Clock drivers must implement all of the | |
57 | functions in the interface. If a clock does not offer a particular | |
58 | ancillary feature, then the driver should just return -EOPNOTSUPP | |
59 | from those functions. | |
60 | ||
61 | Drivers must ensure that all of the methods in interface are | |
62 | reentrant. Since most hardware implementations treat the time value | |
63 | as a 64 bit integer accessed as two 32 bit registers, drivers | |
64 | should use spin_lock_irqsave/spin_unlock_irqrestore to protect | |
65 | against concurrent access. This locking cannot be accomplished in | |
66 | class driver, since the lock may also be needed by the clock | |
67 | driver's interrupt service routine. | |
68 | ||
69 | ** Supported hardware | |
70 | ||
71 | + Freescale eTSEC gianfar | |
72 | - 2 Time stamp external triggers, programmable polarity (opt. interrupt) | |
73 | - 2 Alarm registers (optional interrupt) | |
74 | - 3 Periodic signals (optional interrupt) | |
75 | ||
76 | + National DP83640 | |
77 | - 6 GPIOs programmable as inputs or outputs | |
78 | - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be | |
79 | used as general inputs or outputs | |
80 | - GPIO inputs can time stamp external triggers | |
81 | - GPIO outputs can produce periodic signals | |
82 | - 1 interrupt pin | |
83 | ||
84 | + Intel IXP465 | |
85 | - Auxiliary Slave/Master Mode Snapshot (optional interrupt) | |
86 | - Target Time (optional interrupt) |