[linux-block.git] / Documentation / driver-api / ptp.rst

.. SPDX-License-Identifier: GPL-2.0

===========================================
PTP hardware clock infrastructure for Linux
===========================================

  This patch set introduces support for IEEE 1588 PTP clocks in
  Linux. Together with the SO_TIMESTAMPING socket options, this
  presents a standardized method for developing PTP user space
  programs, synchronizing Linux with external clocks, and using the
  ancillary features of PTP hardware clocks.

  A new class driver exports a kernel interface for specific clock
  drivers and a user space interface. The infrastructure supports a
  complete set of PTP hardware clock functionality.

  + Basic clock operations
    - Set time
    - Get time
    - Shift the clock by a given offset atomically
    - Adjust clock frequency

  + Ancillary clock features
    - Time stamp external events
    - Period output signals configurable from user space
    - Low Pass Filter (LPF) access from user space
    - Synchronization of the Linux system time via the PPS subsystem

PTP hardware clock kernel API
=============================

   A PTP clock driver registers itself with the class driver. The
   class driver handles all of the dealings with user space. The
   author of a clock driver need only implement the details of
   programming the clock hardware. The clock driver notifies the class
   driver of asynchronous events (alarms and external time stamps) via
   a simple message passing interface.

   The class driver supports multiple PTP clock drivers. In normal use
   cases, only one PTP clock is needed. However, for testing and
   development, it can be useful to have more than one clock in a
   single system, in order to allow performance comparisons.

PTP hardware clock user space API
=================================

   The class driver also creates a character device for each
   registered clock. User space can use an open file descriptor from
   the character device as a POSIX clock id and may call
   clock_gettime, clock_settime, and clock_adjtime.  These calls
   implement the basic clock operations.

   User space programs may control the clock using standardized
   ioctls. A program may query, enable, configure, and disable the
   ancillary clock features. User space can receive time stamped
   events via blocking read() and poll().

Writing clock drivers
=====================

   Clock drivers include include/linux/ptp_clock_kernel.h and register
   themselves by presenting a 'struct ptp_clock_info' to the
   registration method. Clock drivers must implement all of the
   functions in the interface. If a clock does not offer a particular
   ancillary feature, then the driver should just return -EOPNOTSUPP
   from those functions.

   Drivers must ensure that all of the methods in interface are
   reentrant. Since most hardware implementations treat the time value
   as a 64 bit integer accessed as two 32 bit registers, drivers
   should use spin_lock_irqsave/spin_unlock_irqrestore to protect
   against concurrent access. This locking cannot be accomplished in
   class driver, since the lock may also be needed by the clock
   driver's interrupt service routine.

Supported hardware
==================

   * Freescale eTSEC gianfar

     - 2 Time stamp external triggers, programmable polarity (opt. interrupt)
     - 2 Alarm registers (optional interrupt)
     - 3 Periodic signals (optional interrupt)

   * National DP83640

     - 6 GPIOs programmable as inputs or outputs
     - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
       used as general inputs or outputs
     - GPIO inputs can time stamp external triggers
     - GPIO outputs can produce periodic signals
     - 1 interrupt pin

   * Intel IXP465

     - Auxiliary Slave/Master Mode Snapshot (optional interrupt)
     - Target Time (optional interrupt)

   * Renesas (IDT) ClockMatrix™

     - Up to 4 independent PHC channels
     - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2)
     - Programmable output periodic signals
     - Programmable inputs can time stamp external triggers
     - Driver and/or hardware configuration through firmware (idtcm.bin)
          - LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2))
          - Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs)
          - Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional)
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
d94ba80e RC	25	- Period output signals configurable from user space
56a1c778	26	- Low Pass Filter (LPF) access from user space
d94ba80e RC	27	- Synchronization of the Linux system time via the PPS subsystem
d94ba80e RC	28
329f0041 MCC	29	PTP hardware clock kernel API
329f0041 MCC	30	=============================
d94ba80e RC	31
	32	A PTP clock driver registers itself with the class driver. The
	33	class driver handles all of the dealings with user space. The
	34	author of a clock driver need only implement the details of
	35	programming the clock hardware. The clock driver notifies the class
	36	driver of asynchronous events (alarms and external time stamps) via
	37	a simple message passing interface.
	38
	39	The class driver supports multiple PTP clock drivers. In normal use
	40	cases, only one PTP clock is needed. However, for testing and
	41	development, it can be useful to have more than one clock in a
	42	single system, in order to allow performance comparisons.
	43
329f0041 MCC	44	PTP hardware clock user space API
329f0041 MCC	45	=================================
d94ba80e RC	46
	47	The class driver also creates a character device for each
	48	registered clock. User space can use an open file descriptor from
	49	the character device as a POSIX clock id and may call
	50	clock_gettime, clock_settime, and clock_adjtime. These calls
	51	implement the basic clock operations.
	52
	53	User space programs may control the clock using standardized
	54	ioctls. A program may query, enable, configure, and disable the
	55	ancillary clock features. User space can receive time stamped
93e9ad98	56	events via blocking read() and poll().
d94ba80e	57
329f0041 MCC	58	Writing clock drivers
329f0041 MCC	59	=====================
d94ba80e RC	60
	61	Clock drivers include include/linux/ptp_clock_kernel.h and register
	62	themselves by presenting a 'struct ptp_clock_info' to the
	63	registration method. Clock drivers must implement all of the
	64	functions in the interface. If a clock does not offer a particular
	65	ancillary feature, then the driver should just return -EOPNOTSUPP
	66	from those functions.
	67
	68	Drivers must ensure that all of the methods in interface are
	69	reentrant. Since most hardware implementations treat the time value
	70	as a 64 bit integer accessed as two 32 bit registers, drivers
	71	should use spin_lock_irqsave/spin_unlock_irqrestore to protect
	72	against concurrent access. This locking cannot be accomplished in
	73	class driver, since the lock may also be needed by the clock
	74	driver's interrupt service routine.
	75
329f0041 MCC	76	Supported hardware
	77	==================
	78
	79	* Freescale eTSEC gianfar
d94ba80e	80
d94ba80e RC	81	- 2 Time stamp external triggers, programmable polarity (opt. interrupt)
	82	- 2 Alarm registers (optional interrupt)
	83	- 3 Periodic signals (optional interrupt)
	84
329f0041 MCC	85	* National DP83640
329f0041 MCC	86
d94ba80e RC	87	- 6 GPIOs programmable as inputs or outputs
	88	- 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
	89	used as general inputs or outputs
	90	- GPIO inputs can time stamp external triggers
	91	- GPIO outputs can produce periodic signals
	92	- 1 interrupt pin
	93
329f0041 MCC	94	* Intel IXP465
329f0041 MCC	95
d94ba80e RC	96	- Auxiliary Slave/Master Mode Snapshot (optional interrupt)
d94ba80e RC	97	- Target Time (optional interrupt)
56a1c778 ML	98
	99	* Renesas (IDT) ClockMatrix™
	100
	101	- Up to 4 independent PHC channels
	102	- Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2)
	103	- Programmable output periodic signals
	104	- Programmable inputs can time stamp external triggers
	105	- Driver and/or hardware configuration through firmware (idtcm.bin)
	106	- LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2))
	107	- Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs)
	108	- Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional)