diff options
author | Mauro Carvalho Chehab <mchehab+samsung@kernel.org> | 2019-06-12 14:52:57 -0300 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2019-06-14 14:31:27 -0600 |
commit | 329f00415a424063c23f75ff77f7d9c67916324d (patch) | |
tree | 7696a2f0d47621aedb06bb1d60ffe8ea203262bd /Documentation/driver-api/ptp.rst | |
parent | 28aedd7ee214eb63a2e6924b5ec2b081aa7b3953 (diff) | |
download | linux-329f00415a424063c23f75ff77f7d9c67916324d.tar.gz linux-329f00415a424063c23f75ff77f7d9c67916324d.tar.bz2 linux-329f00415a424063c23f75ff77f7d9c67916324d.zip |
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 <mchehab+samsung@kernel.org>
Acked-by: Richard Cochran <richardcochran@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/driver-api/ptp.rst')
-rw-r--r-- | Documentation/driver-api/ptp.rst | 96 |
1 files changed, 96 insertions, 0 deletions
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) |