PTP hardware clock infrastructure for Linux

Linux PTP hardware clock infrastructure 개요

이 문서는 Linux에 IEEE 1588 PTP(Precision Time Protocol) clock 지원을 도입한 infrastructure를 설명합니다. `SO_TIMESTAMPING` socket option과 함께 사용하면 PTP userspace program 작성, Linux와 외부 clock 동기화, PTP hardware clock의 부가 기능 사용을 표준화할 수 있습니다.

새 class driver는 특정 clock driver가 사용할 kernel interface와 userspace interface를 모두 제공합니다. Hardware별 driver는 실제 clock programming을 담당하고, class driver는 공통 기능과 userspace 노출을 담당합니다.

기본 clock operation에는 시간 설정, 시간 조회, 주어진 offset만큼 clock을 atomic하게 이동하는 동작, clock frequency 조정이 포함됩니다. 부가 기능에는 외부 event timestamp, userspace에서 설정 가능한 periodic output signal, userspace용 Low Pass Filter(LPF) 접근, PPS subsystem을 통한 Linux system time 동기화가 포함됩니다.

.. 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

PTP clock driver는 class driver에 자신을 등록합니다. Class driver가 userspace와의 모든 상호작용을 처리하므로 clock driver 작성자는 해당 hardware를 programming하는 세부 사항만 구현하면 됩니다.

Clock driver는 alarm과 외부 timestamp 같은 asynchronous event를 단순한 message-passing interface로 class driver에 알립니다. 이 분리는 hardware interrupt 처리와 공통 userspace ABI를 깔끔하게 나눕니다.

Class driver는 여러 PTP clock driver를 동시에 지원합니다. 일반적인 사용에서는 PTP clock 하나면 충분하지만, 시험과 개발에서는 한 system에 여러 clock을 두고 성능을 비교할 수 있습니다.

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 userspace API

Class driver는 등록된 clock마다 character device를 만듭니다. Userspace는 이 character device에서 얻은 열린 file descriptor를 POSIX clock ID로 사용하고 `clock_gettime()`, `clock_settime()`, `clock_adjtime()`를 호출할 수 있습니다. 이 호출들이 기본 clock operation을 구현합니다.

표준화된 `ioctl`을 사용하면 부가 clock 기능을 조회하고, 활성화하고, 설정하고, 비활성화할 수 있습니다. Timestamp가 붙은 event는 blocking `read()`와 `poll()`을 통해 받을 수 있습니다.

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().

PTP clock driver 작성과 동시성

Clock driver는 `include/linux/ptp_clock_kernel.h`를 include하고 registration method에 `struct ptp_clock_info`를 제공해 자신을 등록합니다. Interface에 정의된 function은 모두 구현해야 하며, hardware가 특정 부가 기능을 제공하지 않으면 해당 function에서 `-EOPNOTSUPP`를 반환해야 합니다.

모든 interface method는 reentrant해야 합니다. 많은 hardware가 64-bit time 값을 두 개의 32-bit register로 나누어 접근하므로, 동시 접근 중 값이 찢어지는 것을 막기 위해 `spin_lock_irqsave()`와 `spin_unlock_irqrestore()`로 보호해야 합니다.

이 locking은 class driver에서 대신 수행할 수 없습니다. 같은 lock을 clock driver의 interrupt service routine에서도 사용해야 할 수 있으므로, hardware 접근과 interrupt context를 아는 개별 driver가 lock의 소유권을 가져야 합니다.

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.

`.adjphase` 구현 요구사항

`struct ptp_clock_info` interface에는 `.adjphase` function이 있습니다. 이를 구현하려면 PHC(PTP Hardware Clock)가 전달된 offset을 보정하는 servo algorithm을 내부에 구현해야 합니다.

다른 PTP adjustment function이 호출되면 PHC의 servo algorithm은 비활성화되어야 합니다. 여러 보정 경로가 동시에 clock을 제어하지 않도록 상태 전환을 명확히 해야 합니다.

중요하게도 `.adjphase`는 전달된 offset만큼 PHC 시간을 즉시 뛰게 만드는 단순한 time adjustment가 아닙니다. 내부 algorithm이 offset을 점진적으로 교정하는 phase servo 기능이어야 합니다.

PTP hardware clock requirements for '.adjphase'
-----------------------------------------------

   The 'struct ptp_clock_info' interface has a '.adjphase' function.
   This function has a set of requirements from the PHC in order to be
   implemented.

     * The PHC implements a servo algorithm internally that is used to
       correct the offset passed in the '.adjphase' call.
     * When other PTP adjustment functions are called, the PHC servo
       algorithm is disabled.

   **NOTE:** '.adjphase' is not a simple time adjustment functionality
   that 'jumps' the PHC clock time based on the provided offset. It
   should correct the offset provided using an internal algorithm.

지원 hardware와 제공 기능

Freescale eTSEC gianfar는 polarity를 programming할 수 있는 외부 timestamp trigger 2개, alarm register 2개, periodic signal 3개를 제공합니다. 각 항목의 interrupt는 선택 사항입니다.

National DP83640은 input 또는 output으로 설정 가능한 GPIO 6개와 LED, JTAG, clock 전용 기능을 가진 GPIO 6개를 제공합니다. 전용 GPIO도 일반 input/output으로 쓸 수 있습니다. GPIO input은 외부 trigger에 timestamp를 붙이고, GPIO output은 periodic signal을 만들며, interrupt pin은 1개입니다.

Intel IXP465는 Auxiliary Slave/Master Mode Snapshot과 Target Time 기능을 제공하며 두 기능 모두 interrupt는 선택 사항입니다.

Renesas (IDT) ClockMatrix는 독립 PHC channel을 최대 4개 제공하고, ITU-T G.8273.2를 준수하는 `.adjPhase` 경유 integrated LPF, programmable periodic output, external trigger timestamp input을 지원합니다. `idtcm.bin` firmware로 driver와 hardware를 설정할 수 있습니다.

ClockMatrix firmware 설정에는 LPF bandwidth, phase limiting, automatic holdover, ITU-T G.8273.2 physical-layer assist가 포함됩니다. 다른 PHY/MAC timestamper와 ASSP, SoC, FPGA의 reference clock에 제공할 PTP clock output은 최대 1 GHz까지 설정할 수 있습니다. GNSS input lock과 GNSS 및 userspace PHC control 사이의 자동 전환도 선택적으로 지원합니다.

NVIDIA Mellanox에서 일부 ConnectX-6 Dx 이후 제품은 외부 trigger timestamp용 GPIO 하나와 periodic signal 출력용 GPIO 하나를 지원합니다. 일부 ConnectX-5 이전 제품은 GPIO 하나를 두 기능 중 하나로 설정합니다. 모든 ConnectX device에는 free-running counter가 있고, ConnectX-6 Dx 이후에는 UTC format counter도 있습니다.

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)

   * NVIDIA Mellanox

     - GPIO
          - Certain variants of ConnectX-6 Dx and later products support one
            GPIO which can time stamp external triggers and one GPIO to produce
            periodic signals.
          - Certain variants of ConnectX-5 and older products support one GPIO,
            configured to either time stamp external triggers or produce
            periodic signals.
     - PHC instances
          - All ConnectX devices have a free-running counter
          - ConnectX-6 Dx and later devices have a UTC format counter