From d7050a2b85ffbc0a2c36326028d6aa9784d6694d Mon Sep 17 00:00:00 2001 From: Jonathan Lemon Date: Tue, 14 Sep 2021 19:16:36 -0700 Subject: 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 Signed-off-by: David S. Miller --- Documentation/ABI/testing/sysfs-timecard | 174 +++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-timecard (limited to 'Documentation/ABI') diff --git a/Documentation/ABI/testing/sysfs-timecard b/Documentation/ABI/testing/sysfs-timecard new file mode 100644 index 000000000000..97f6773794a5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-timecard @@ -0,0 +1,174 @@ +What: /sys/class/timecard/ +Date: September 2021 +Contact: Jonathan Lemon +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 +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 +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 +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 +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 +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 +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 +Description: This optional attribute links to the associated i2c device. + +What: /sys/class/timecard/ocpN/irig_b_mode +Date: September 2021 +Contact: Jonathan Lemon +Description: (RW) An integer from 0-7 indicating the timecode format + of the IRIG-B output signal: B00 + +What: /sys/class/timecard/ocpN/pps +Date: September 2021 +Contact: Jonathan Lemon +Description: This optional attribute links to the associated PPS device. + +What: /sys/class/timecard/ocpN/ptp +Date: September 2021 +Contact: Jonathan Lemon +Description: This attribute links to the associated PTP device. + +What: /sys/class/timecard/ocpN/serialnum +Date: September 2021 +Contact: Jonathan Lemon +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 +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 +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 +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 +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 +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 +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. -- cgit