cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

ptp.rst (4556B)

      1.. SPDX-License-Identifier: GPL-2.0
      2
      3===========================================
      4PTP 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
     29PTP 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
     44PTP 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
     58Writing 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
     76Supported hardware
     77==================
     78
     79   * Freescale eTSEC gianfar
     80
     81     - 2 Time stamp external triggers, programmable polarity (opt. interrupt)
     82     - 2 Alarm registers (optional interrupt)
     83     - 3 Periodic signals (optional interrupt)
     84
     85   * National DP83640
     86
     87     - 6 GPIOs programmable as inputs or outputs
     88     - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
     89       used as general inputs or outputs
     90     - GPIO inputs can time stamp external triggers
     91     - GPIO outputs can produce periodic signals
     92     - 1 interrupt pin
     93
     94   * Intel IXP465
     95
     96     - Auxiliary Slave/Master Mode Snapshot (optional interrupt)
     97     - Target Time (optional interrupt)
     98
     99   * Renesas (IDT) ClockMatrix™
    100
    101     - Up to 4 independent PHC channels
    102     - Integrated low pass filter (LPF), access via .adjPhase (compliant to ITU-T G.8273.2)
    103     - Programmable output periodic signals
    104     - Programmable inputs can time stamp external triggers
    105     - Driver and/or hardware configuration through firmware (idtcm.bin)
    106          - LPF settings (bandwidth, phase limiting, automatic holdover, physical layer assist (per ITU-T G.8273.2))
    107          - Programmable output PTP clocks, any frequency up to 1GHz (to other PHY/MAC time stampers, refclk to ASSPs/SoCs/FPGAs)
    108          - Lock to GNSS input, automatic switching between GNSS and user-space PHC control (optional)