Documentation/ptp/ptp.txt

   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)