0001 What: /sys/class/timecard/
0002 Date: September 2021
0003 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0004 Description: This directory contains files and directories
0005 providing a standardized interface to the ancillary
0006 features of the OpenCompute timecard.
0007
0008 What: /sys/class/timecard/ocpN/
0009 Date: September 2021
0010 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0011 Description: This directory contains the attributes of the Nth timecard
0012 registered.
0013
0014 What: /sys/class/timecard/ocpN/available_clock_sources
0015 Date: September 2021
0016 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0017 Description: (RO) The list of available time sources that the PHC
0018 uses for clock adjustments.
0019
0020 ==== =================================================
0021 NONE no adjustments
0022 PPS adjustments come from the PPS1 selector (default)
0023 TOD adjustments from the GNSS/TOD module
0024 IRIG adjustments from external IRIG-B signal
0025 DCF adjustments from external DCF signal
0026 ==== =================================================
0027
0028 What: /sys/class/timecard/ocpN/available_sma_inputs
0029 Date: September 2021
0030 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0031 Description: (RO) Set of available destinations (sinks) for a SMA
0032 input signal.
0033
0034 ===== ================================================
0035 10Mhz signal is used as the 10Mhz reference clock
0036 PPS1 signal is sent to the PPS1 selector
0037 PPS2 signal is sent to the PPS2 selector
0038 TS1 signal is sent to timestamper 1
0039 TS2 signal is sent to timestamper 2
0040 TS3 signal is sent to timestamper 3
0041 TS4 signal is sent to timestamper 4
0042 IRIG signal is sent to the IRIG-B module
0043 DCF signal is sent to the DCF module
0044 FREQ1 signal is sent to frequency counter 1
0045 FREQ2 signal is sent to frequency counter 2
0046 FREQ3 signal is sent to frequency counter 3
0047 FREQ4 signal is sent to frequency counter 4
0048 None signal input is disabled
0049 ===== ================================================
0050
0051 What: /sys/class/timecard/ocpN/available_sma_outputs
0052 Date: May 2021
0053 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0054 Description: (RO) Set of available sources for a SMA output signal.
0055
0056 ===== ================================================
0057 10Mhz output is from the 10Mhz reference clock
0058 PHC output PPS is from the PHC clock
0059 MAC output PPS is from the Miniature Atomic Clock
0060 GNSS1 output PPS is from the first GNSS module
0061 GNSS2 output PPS is from the second GNSS module
0062 IRIG output is from the PHC, in IRIG-B format
0063 DCF output is from the PHC, in DCF format
0064 GEN1 output is from frequency generator 1
0065 GEN2 output is from frequency generator 2
0066 GEN3 output is from frequency generator 3
0067 GEN4 output is from frequency generator 4
0068 GND output is GND
0069 VCC output is VCC
0070 ===== ================================================
0071
0072 What: /sys/class/timecard/ocpN/clock_source
0073 Date: September 2021
0074 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0075 Description: (RW) Contains the current synchronization source used by
0076 the PHC. May be changed by writing one of the listed
0077 values from the available_clock_sources attribute set.
0078
0079 What: /sys/class/timecard/ocpN/clock_status_drift
0080 Date: March 2022
0081 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0082 Description: (RO) Contains the current drift value used by the firmware
0083 for internal disciplining of the atomic clock.
0084
0085 What: /sys/class/timecard/ocpN/clock_status_offset
0086 Date: March 2022
0087 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0088 Description: (RO) Contains the current offset value used by the firmware
0089 for internal disciplining of the atomic clock.
0090
0091 What: /sys/class/timecard/ocpN/freqX
0092 Date: March 2022
0093 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0094 Description: (RO) Optional directory containing the sysfs nodes for
0095 frequency counter <X>.
0096
0097 What: /sys/class/timecard/ocpN/freqX/frequency
0098 Date: March 2022
0099 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0100 Description: (RO) Contains the measured frequency over the specified
0101 measurement period.
0102
0103 What: /sys/class/timecard/ocpN/freqX/seconds
0104 Date: March 2022
0105 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0106 Description: (RW) Specifies the number of seconds from 0-255 that the
0107 frequency should be measured over. Write 0 to disable.
0108
0109 What: /sys/class/timecard/ocpN/genX
0110 Date: March 2022
0111 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0112 Description: (RO) Optional directory containing the sysfs nodes for
0113 frequency generator <X>.
0114
0115 What: /sys/class/timecard/ocpN/genX/duty
0116 Date: March 2022
0117 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0118 Description: (RO) Specifies the signal duty cycle as a percentage from 1-99.
0119
0120 What: /sys/class/timecard/ocpN/genX/period
0121 Date: March 2022
0122 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0123 Description: (RO) Specifies the signal period in nanoseconds.
0124
0125 What: /sys/class/timecard/ocpN/genX/phase
0126 Date: March 2022
0127 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0128 Description: (RO) Specifies the signal phase offset in nanoseconds.
0129
0130 What: /sys/class/timecard/ocpN/genX/polarity
0131 Date: March 2022
0132 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0133 Description: (RO) Specifies the signal polarity, either 1 or 0.
0134
0135 What: /sys/class/timecard/ocpN/genX/running
0136 Date: March 2022
0137 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0138 Description: (RO) Either 0 or 1, showing if the signal generator is running.
0139
0140 What: /sys/class/timecard/ocpN/genX/start
0141 Date: March 2022
0142 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0143 Description: (RO) Shows the time in <sec>.<nsec> that the signal generator
0144 started running.
0145
0146 What: /sys/class/timecard/ocpN/genX/signal
0147 Date: March 2022
0148 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0149 Description: (RW) Used to start the signal generator, and summarize
0150 the current status.
0151
0152 The signal generator may be started by writing the signal
0153 period, followed by the optional signal values. If the
0154 optional values are not provided, they default to the current
0155 settings, which may be obtained from the other sysfs nodes.
0156
0157 period [duty [phase [polarity]]]
0158
0159 echo 500000000 > signal # 1/2 second period
0160 echo 1000000 40 100 > signal
0161 echo 0 > signal # turn off generator
0162
0163 Period and phase are specified in nanoseconds. Duty cycle is
0164 a percentage from 1-99. Polarity is 1 or 0.
0165
0166 Reading this node will return:
0167
0168 period duty phase polarity start_time
0169
0170 What: /sys/class/timecard/ocpN/gnss_sync
0171 Date: September 2021
0172 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0173 Description: (RO) Indicates whether a valid GNSS signal is received,
0174 or when the signal was lost.
0175
0176 What: /sys/class/timecard/ocpN/i2c
0177 Date: September 2021
0178 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0179 Description: This optional attribute links to the associated i2c device.
0180
0181 What: /sys/class/timecard/ocpN/irig_b_mode
0182 Date: September 2021
0183 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0184 Description: (RW) An integer from 0-7 indicating the timecode format
0185 of the IRIG-B output signal: B00<n>
0186
0187 What: /sys/class/timecard/ocpN/pps
0188 Date: September 2021
0189 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0190 Description: This optional attribute links to the associated PPS device.
0191
0192 What: /sys/class/timecard/ocpN/ptp
0193 Date: September 2021
0194 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0195 Description: This attribute links to the associated PTP device.
0196
0197 What: /sys/class/timecard/ocpN/serialnum
0198 Date: September 2021
0199 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0200 Description: (RO) Provides the serial number of the timecard.
0201
0202 What: /sys/class/timecard/ocpN/sma1
0203 What: /sys/class/timecard/ocpN/sma2
0204 What: /sys/class/timecard/ocpN/sma3
0205 What: /sys/class/timecard/ocpN/sma4
0206 Date: September 2021
0207 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0208 Description: (RW) These attributes specify the direction of the signal
0209 on the associated SMA connectors, and also the signal sink
0210 or source.
0211
0212 The display format of the attribute is a space separated
0213 list of signals, prefixed by the input/output direction.
0214
0215 The signal direction may be changed (if supported) by
0216 prefixing the signal list with either "in:" or "out:".
0217 If neither prefix is present, then the direction is unchanged.
0218
0219 The output signal may be changed by writing one of the listed
0220 values from the available_sma_outputs attribute set.
0221
0222 The input destinations may be changed by writing multiple
0223 values from the available_sma_inputs attribute set,
0224 separated by spaces. If there are duplicated input
0225 destinations between connectors, the lowest numbered SMA
0226 connector is given priority.
0227
0228 Note that not all input combinations may make sense.
0229
0230 The 10Mhz reference clock input is currently only valid
0231 on SMA1 and may not be combined with other destination sinks.
0232
0233 What: /sys/class/timecard/ocpN/tod_correction
0234 Date: March 2022
0235 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0236 Description: (RW) The incoming GNSS signal is in UTC time, and the NMEA
0237 format messages do not provide a TAI offset. This sets the
0238 correction value for the incoming time.
0239
0240 If UBX_LS is enabled, this should be 0, and the offset is
0241 taken from the UBX-NAV-TIMELS message.
0242
0243 What: /sys/class/timecard/ocpN/ts_window_adjust
0244 Date: September 2021
0245 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0246 Description: (RW) When retrieving the PHC with the PTP SYS_OFFSET_EXTENDED
0247 ioctl, a system timestamp is made before and after the PHC
0248 time is retrieved. The midpoint between the two system
0249 timestamps is usually taken to be the SYS time associated
0250 with the PHC time. This estimate may be wrong, as it depends
0251 on PCI latencies, and when the PHC time was latched
0252
0253 The attribute value reduces the end timestamp by the given
0254 number of nanoseconds, so the computed midpoint matches the
0255 retrieved PHC time.
0256
0257 The initial value is set based on measured PCI latency and
0258 the estimated point where the FPGA latches the PHC time. This
0259 value may be changed by writing an unsigned integer.
0260
0261 What: /sys/class/timecard/ocpN/ttyGNSS
0262 What: /sys/class/timecard/ocpN/ttyGNSS2
0263 Date: September 2021
0264 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0265 Description: These optional attributes link to the TTY serial ports
0266 associated with the GNSS devices.
0267
0268 What: /sys/class/timecard/ocpN/ttyMAC
0269 Date: September 2021
0270 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0271 Description: This optional attribute links to the TTY serial port
0272 associated with the Miniature Atomic Clock.
0273
0274 What: /sys/class/timecard/ocpN/ttyNMEA
0275 Date: September 2021
0276 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0277 Description: This optional attribute links to the TTY serial port
0278 which outputs the PHC time in NMEA ZDA format.
0279
0280 What: /sys/class/timecard/ocpN/utc_tai_offset
0281 Date: September 2021
0282 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
0283 Description: (RW) The DCF and IRIG output signals are in UTC, while the
0284 TimeCard operates on TAI. This attribute allows setting the
0285 offset in seconds, which is added to the TAI timebase for
0286 these formats.
0287
0288 The offset may be changed by writing an unsigned integer.
