From: Jonathan Lemon <jonathan.lemon@gmail.com>
To: kuba@kernel.org, davem@davemloft.net, richardcochran@gmail.com
Cc: netdev@vger.kernel.org, kernel-team@fb.com
Subject: [PATCH net-next 18/18] docs: ABI: Add sysfs documentation for timecard
Date: Tue, 14 Sep 2021 19:16:36 -0700 [thread overview]
Message-ID: <20210915021636.153754-19-jonathan.lemon@gmail.com> (raw)
In-Reply-To: <20210915021636.153754-1-jonathan.lemon@gmail.com>
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>
---
Documentation/ABI/testing/sysfs-timecard | 174 +++++++++++++++++++++++
1 file changed, 174 insertions(+)
create mode 100644 Documentation/ABI/testing/sysfs-timecard
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 <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.
--
2.31.1
next prev parent reply other threads:[~2021-09-15 2:17 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-15 2:16 [PATCH net-next 00/18] timecard updates for v13 firmware Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 01/18] ptp: ocp: parameterize the i2c driver used Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 02/18] ptp: ocp: Parameterize the TOD information display Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 03/18] ptp: ocp: Skip I2C flash read when there is no controller Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 04/18] ptp: ocp: Skip resources with out of range irqs Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 05/18] ptp: ocp: Report error if resource registration fails Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 06/18] ptp: ocp: Add third timestamper Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 07/18] ptp: ocp: Add SMA selector and controls Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 08/18] ptp: ocp: Add IRIG-B and DCF blocks Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 09/18] ptp: ocp: Add IRIG-B output mode control Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 10/18] ptp: ocp: Add sysfs attribute utc_tai_offset Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 11/18] ptp: ocp: Separate the init and info logic Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 12/18] ptp: ocp: Add debugfs entry for timecard Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 13/18] ptp: ocp: Add NMEA output Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 14/18] ptp: ocp: Add second GNSS device Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 15/18] ptp: ocp: Enable 4th timestamper / PPS generator Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 16/18] ptp: ocp: Have FPGA fold in ns adjustment for adjtime Jonathan Lemon
2021-09-15 2:16 ` [PATCH net-next 17/18] ptp: ocp: Add timestamp window adjustment Jonathan Lemon
2021-09-15 2:16 ` Jonathan Lemon [this message]
2021-09-15 10:30 ` [PATCH net-next 00/18] timecard updates for v13 firmware patchwork-bot+netdevbpf
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210915021636.153754-19-jonathan.lemon@gmail.com \
--to=jonathan.lemon@gmail.com \
--cc=davem@davemloft.net \
--cc=kernel-team@fb.com \
--cc=kuba@kernel.org \
--cc=netdev@vger.kernel.org \
--cc=richardcochran@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).