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
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
50   events via blocking read() and poll().
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)
87