Documentation/driver-api/ptp.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/ptp.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/ptp.rst
Extension
.rst
Size
5803 bytes
Lines
138
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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

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

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

Annotation

Implementation Notes