From 329f00415a424063c23f75ff77f7d9c67916324d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 12 Jun 2019 14:52:57 -0300 Subject: docs: ptp.txt: convert to ReST and move to driver-api The conversion is trivial: just adjust title markups. In order to avoid conflicts, let's add an :orphan: tag to it, to be removed when this file gets added to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Richard Cochran Signed-off-by: Jonathan Corbet --- Documentation/driver-api/ptp.rst | 96 +++++++++++++++++++++++++++++++ Documentation/networking/timestamping.txt | 2 +- Documentation/ptp/ptp.txt | 86 --------------------------- MAINTAINERS | 2 +- 4 files changed, 98 insertions(+), 88 deletions(-) create mode 100644 Documentation/driver-api/ptp.rst delete mode 100644 Documentation/ptp/ptp.txt diff --git a/Documentation/driver-api/ptp.rst b/Documentation/driver-api/ptp.rst new file mode 100644 index 000000000000..b6e65d66d37a --- /dev/null +++ b/Documentation/driver-api/ptp.rst @@ -0,0 +1,96 @@ +:orphan: + +=========================================== +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 + - 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 + 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. + +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) diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt index bbdaf8990031..8dd6333c3270 100644 --- a/Documentation/networking/timestamping.txt +++ b/Documentation/networking/timestamping.txt @@ -368,7 +368,7 @@ ts[1] used to hold hardware timestamps converted to system time. Instead, expose the hardware clock device on the NIC directly as a HW PTP clock source, to allow time conversion in userspace and optionally synchronize system time with a userspace PTP stack such -as linuxptp. For the PTP clock API, see Documentation/ptp/ptp.txt. +as linuxptp. For the PTP clock API, see Documentation/driver-api/ptp.rst. Note that if the SO_TIMESTAMP or SO_TIMESTAMPNS option is enabled together with SO_TIMESTAMPING using SOF_TIMESTAMPING_SOFTWARE, a false diff --git a/Documentation/ptp/ptp.txt b/Documentation/ptp/ptp.txt deleted file mode 100644 index 11e904ee073f..000000000000 --- a/Documentation/ptp/ptp.txt +++ /dev/null @@ -1,86 +0,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 - - 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 - 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. - -** 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) diff --git a/MAINTAINERS b/MAINTAINERS index aae3bd8a19f4..5fe44d5d82b4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12765,7 +12765,7 @@ L: netdev@vger.kernel.org S: Maintained W: http://linuxptp.sourceforge.net/ F: Documentation/ABI/testing/sysfs-ptp -F: Documentation/ptp/* +F: Documentation/driver-api/ptp.rst F: drivers/net/phy/dp83640* F: drivers/ptp/* F: include/linux/ptp_cl* -- cgit