docs: ABI: Add sysfs documentation for timecard

This patch describes the sysfs interface implemented by the
ptp_ocp driver, under /sys/class/timecard.

Signed-off-by: Jonathan Lemon <jonathan.lemon@gmail.com>
Signed-off-by: David S. Miller <davem@davemloft.net>

diff --git a/Documentation/ABI/testing/sysfs-timecard b/Documentation/ABI/testing/sysfs-timecard
new file mode 100644 (file)
index 0000000..97f6773
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-timecard
@@ -0,0 +1,174 @@
+What:          /sys/class/timecard/
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   This directory contains files and directories
+               providing a standardized interface to the ancillary
+               features of the OpenCompute timecard.
+
+What:          /sys/class/timecard/ocpN/
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   This directory contains the attributes of the Nth timecard
+               registered.
+
+What:          /sys/class/timecard/ocpN/available_clock_sources
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RO) The list of available time sources that the PHC
+               uses for clock adjustments.
+
+               ====  =================================================
+                NONE  no adjustments
+                PPS   adjustments come from the PPS1 selector (default)
+                TOD   adjustments from the GNSS/TOD module
+                IRIG  adjustments from external IRIG-B signal
+                DCF   adjustments from external DCF signal
+                ====  =================================================
+
+What:          /sys/class/timecard/ocpN/available_sma_inputs
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RO) Set of available destinations (sinks) for a SMA
+               input signal.
+
+                =====  ================================================
+                10Mhz  signal is used as the 10Mhz reference clock
+                PPS1   signal is sent to the PPS1 selector
+                PPS2   signal is sent to the PPS2 selector
+                TS1    signal is sent to timestamper 1
+                TS2    signal is sent to timestamper 2
+                IRIG   signal is sent to the IRIG-B module
+                DCF    signal is sent to the DCF module
+                =====  ================================================
+
+What:          /sys/class/timecard/ocpN/available_sma_outputs
+Date:          May 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RO) Set of available sources for a SMA output signal.
+
+                =====  ================================================
+                10Mhz  output is from the 10Mhz reference clock
+                PHC    output PPS is from the PHC clock
+                MAC    output PPS is from the Miniature Atomic Clock
+                GNSS   output PPS is from the GNSS module
+                GNSS2  output PPS is from the second GNSS module
+                IRIG   output is from the PHC, in IRIG-B format
+                DCF    output is from the PHC, in DCF format
+                =====  ================================================
+
+What:          /sys/class/timecard/ocpN/clock_source
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RW) Contains the current synchronization source used by
+               the PHC.  May be changed by writing one of the listed
+               values from the available_clock_sources attribute set.
+
+What:          /sys/class/timecard/ocpN/gnss_sync
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RO) Indicates whether a valid GNSS signal is received,
+               or when the signal was lost.
+
+What:          /sys/class/timecard/ocpN/i2c
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   This optional attribute links to the associated i2c device.
+
+What:          /sys/class/timecard/ocpN/irig_b_mode
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RW) An integer from 0-7 indicating the timecode format
+               of the IRIG-B output signal: B00<n>
+
+What:          /sys/class/timecard/ocpN/pps
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   This optional attribute links to the associated PPS device.
+
+What:          /sys/class/timecard/ocpN/ptp
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   This attribute links to the associated PTP device.
+
+What:          /sys/class/timecard/ocpN/serialnum
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RO) Provides the serial number of the timecard.
+
+What:          /sys/class/timecard/ocpN/sma1
+What:          /sys/class/timecard/ocpN/sma2
+What:          /sys/class/timecard/ocpN/sma3
+What:          /sys/class/timecard/ocpN/sma4
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RW) These attributes specify the direction of the signal
+               on the associated SMA connectors, and also the signal sink
+               or source.
+
+               The display format of the attribute is a space separated
+               list of signals, prefixed by the input/output direction.
+
+               The signal direction may be changed (if supported) by
+               prefixing the signal list with either "in:" or "out:".
+               If neither prefix is present, then the direction is unchanged.
+
+               The output signal may be changed by writing one of the listed
+               values from the available_sma_outputs attribute set.
+
+               The input destinations may be changed by writing multiple
+               values from the available_sma_inputs attribute set,
+               separated by spaces.  If there are duplicated input
+               destinations between connectors, the lowest numbered SMA
+               connector is given priority.
+
+               Note that not all input combinations may make sense.
+
+               The 10Mhz reference clock input is currently only valid
+               on SMA1 and may not be combined with other destination sinks.
+
+What:          /sys/class/timecard/ocpN/ts_window_adjust
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RW) When retrieving the PHC with the PTP SYS_OFFSET_EXTENDED
+               ioctl, a system timestamp is made before and after the PHC
+               time is retrieved.  The midpoint between the two system
+               timestamps is usually taken to be the SYS time associated
+               with the PHC time.  This estimate may be wrong, as it depends
+               on PCI latencies, and when the PHC time was latched
+
+               The attribute value reduces the end timestamp by the given
+               number of nanoseconds, so the computed midpoint matches the
+               retrieved PHC time.
+
+               The initial value is set based on measured PCI latency and
+               the estimated point where the FPGA latches the PHC time.  This
+               value may be changed by writing an unsigned integer.
+
+What:          /sys/class/timecard/ocpN/ttyGNSS
+What:          /sys/class/timecard/ocpN/ttyGNSS2
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   These optional attributes link to the TTY serial ports
+               associated with the GNSS devices.
+
+What:          /sys/class/timecard/ocpN/ttyMAC
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   This optional attribute links to the TTY serial port
+               associated with the Miniature Atomic Clock.
+
+What:          /sys/class/timecard/ocpN/ttyNMEA
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   This optional attribute links to the TTY serial port
+               which outputs the PHC time in NMEA ZDA format.
+
+What:          /sys/class/timecard/ocpN/utc_tai_offset
+Date:          September 2021
+Contact:       Jonathan Lemon <jonathan.lemon@gmail.com>
+Description:   (RW) The DCF and IRIG output signals are in UTC, while the
+               TimeCard operates on TAI.  This attribute allows setting the
+               offset in seconds, which is added to the TAI timebase for
+               these formats.
+
+               The offset may be changed by writing an unsigned integer.