Documentation/driver-api/ptp.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===========================================
   4 PTP hardware clock infrastructure for Linux
   5 ===========================================
   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
  24     - Time stamp external events
  25     - Period output signals configurable from user space
  26     - Low Pass Filter (LPF) access from user space
  27     - Synchronization of the Linux system time via the PPS subsystem
  28
  29 PTP hardware clock kernel API
  30 =============================
  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
  44 PTP hardware clock user space API
  45 =================================
  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
  56    events via blocking read() and poll().
  57
  58 Writing clock drivers
  59 =====================
  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
  76 PTP hardware clock requirements for '.adjphase'
  77 -----------------------------------------------
  78
  79    The 'struct ptp_clock_info' interface has a '.adjphase' function.
  80    This function has a set of requirements from the PHC in order to be
  81    implemented.
  82
  83      * The PHC implements a servo algorithm internally that is used to
  84        correct the offset passed in the '.adjphase' call.
  85      * When other PTP adjustment functions are called, the PHC servo
  86        algorithm is disabled.
  87
  88    **NOTE:** '.adjphase' is not a simple time adjustment functionality
  89    that 'jumps' the PHC clock time based on the provided offset. It
  90    should correct the offset provided using an internal algorithm.
  91
  92 Supported hardware
  93 ==================
  94
  95    * Freescale eTSEC gianfar
  96
  97      - 2 Time stamp external triggers, programmable polarity (opt. interrupt)
  98      - 2 Alarm registers (optional interrupt)
  99      - 3 Periodic signals (optional interrupt)
 100
 101    * National DP83640
 102
 103      - 6 GPIOs programmable as inputs or outputs
 104      - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
 105        used as general inputs or outputs
 106      - GPIO inputs can time stamp external triggers
 107      - GPIO outputs can produce periodic signals
 108      - 1 interrupt pin
 109
 110    * Intel IXP465
 111
 112      - Auxiliary Slave/Master Mode Snapshot (optional interrupt)
 113      - Target Time (optional interrupt)
 114
 115    * Renesas (IDT) ClockMatrix™
 116
 117      - Up to 4 independent PHC channels
 118      - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2)
 119      - Programmable output periodic signals
 120      - Programmable inputs can time stamp external triggers
 121      - Driver and/or hardware configuration through firmware (idtcm.bin)
 122           - LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2))
 123           - Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs)
 124           - Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional)
 125
 126    * NVIDIA Mellanox
 127
 128      - GPIO
 129           - Certain variants of ConnectX-6 Dx and later products support one
 130             GPIO which can time stamp external triggers and one GPIO to produce
 131             periodic signals.
 132           - Certain variants of ConnectX-5 and older products support one GPIO,
 133             configured to either time stamp external triggers or produce
 134             periodic signals.
 135      - PHC instances
 136           - All ConnectX devices have a free-running counter
 137           - ConnectX-6 Dx and later devices have a UTC format counter