ptp.rst 4.4 KB

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