About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / ptp


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog