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: 22+ 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-11-06 22:25 ` kernel test robot
2021-11-06 22:25 ` kernel test robot
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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.