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