1 What: /sys/class/timecard/ 1 What: /sys/class/timecard/
2 Date: September 2021 2 Date: September 2021
3 Contact: Jonathan Lemon <jonathan.lemon@ 3 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
4 Description: This directory contains files 4 Description: This directory contains files and directories
5 providing a standardized inter 5 providing a standardized interface to the ancillary
6 features of the OpenCompute ti 6 features of the OpenCompute timecard.
7 7
8 What: /sys/class/timecard/ocpN/ 8 What: /sys/class/timecard/ocpN/
9 Date: September 2021 9 Date: September 2021
10 Contact: Jonathan Lemon <jonathan.lemon@ 10 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
11 Description: This directory contains the at 11 Description: This directory contains the attributes of the Nth timecard
12 registered. 12 registered.
13 13
14 What: /sys/class/timecard/ocpN/avail 14 What: /sys/class/timecard/ocpN/available_clock_sources
15 Date: September 2021 15 Date: September 2021
16 Contact: Jonathan Lemon <jonathan.lemon@ 16 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
17 Description: (RO) The list of available tim 17 Description: (RO) The list of available time sources that the PHC
18 uses for clock adjustments. 18 uses for clock adjustments.
19 19
20 ==== ======================== 20 ==== =================================================
21 NONE no adjustments 21 NONE no adjustments
22 PPS adjustments come from th 22 PPS adjustments come from the PPS1 selector (default)
23 TOD adjustments from the GNS 23 TOD adjustments from the GNSS/TOD module
24 IRIG adjustments from externa 24 IRIG adjustments from external IRIG-B signal
25 DCF adjustments from externa 25 DCF adjustments from external DCF signal
26 ==== ======================== 26 ==== =================================================
27 27
28 What: /sys/class/timecard/ocpN/avail 28 What: /sys/class/timecard/ocpN/available_sma_inputs
29 Date: September 2021 29 Date: September 2021
30 Contact: Jonathan Lemon <jonathan.lemon@ 30 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
31 Description: (RO) Set of available destinat 31 Description: (RO) Set of available destinations (sinks) for a SMA
32 input signal. 32 input signal.
33 33
34 ===== ======================= 34 ===== ================================================
35 10Mhz signal is used as the 1 35 10Mhz signal is used as the 10Mhz reference clock
36 PPS1 signal is sent to the P 36 PPS1 signal is sent to the PPS1 selector
37 PPS2 signal is sent to the P 37 PPS2 signal is sent to the PPS2 selector
38 TS1 signal is sent to times 38 TS1 signal is sent to timestamper 1
39 TS2 signal is sent to times 39 TS2 signal is sent to timestamper 2
40 TS3 signal is sent to times 40 TS3 signal is sent to timestamper 3
41 TS4 signal is sent to times 41 TS4 signal is sent to timestamper 4
42 IRIG signal is sent to the I 42 IRIG signal is sent to the IRIG-B module
43 DCF signal is sent to the D 43 DCF signal is sent to the DCF module
44 FREQ1 signal is sent to frequ 44 FREQ1 signal is sent to frequency counter 1
45 FREQ2 signal is sent to frequ 45 FREQ2 signal is sent to frequency counter 2
46 FREQ3 signal is sent to frequ 46 FREQ3 signal is sent to frequency counter 3
47 FREQ4 signal is sent to frequ 47 FREQ4 signal is sent to frequency counter 4
48 None signal input is disable 48 None signal input is disabled
49 ===== ======================= 49 ===== ================================================
50 50
51 What: /sys/class/timecard/ocpN/avail 51 What: /sys/class/timecard/ocpN/available_sma_outputs
52 Date: May 2021 52 Date: May 2021
53 Contact: Jonathan Lemon <jonathan.lemon@ 53 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
54 Description: (RO) Set of available sources 54 Description: (RO) Set of available sources for a SMA output signal.
55 55
56 ===== ======================= 56 ===== ================================================
57 10Mhz output is from the 10Mh 57 10Mhz output is from the 10Mhz reference clock
58 PHC output PPS is from the 58 PHC output PPS is from the PHC clock
59 MAC output PPS is from the 59 MAC output PPS is from the Miniature Atomic Clock
60 GNSS1 output PPS is from the 60 GNSS1 output PPS is from the first GNSS module
61 GNSS2 output PPS is from the 61 GNSS2 output PPS is from the second GNSS module
62 IRIG output is from the PHC, 62 IRIG output is from the PHC, in IRIG-B format
63 DCF output is from the PHC, 63 DCF output is from the PHC, in DCF format
64 GEN1 output is from frequenc 64 GEN1 output is from frequency generator 1
65 GEN2 output is from frequenc 65 GEN2 output is from frequency generator 2
66 GEN3 output is from frequenc 66 GEN3 output is from frequency generator 3
67 GEN4 output is from frequenc 67 GEN4 output is from frequency generator 4
68 GND output is GND 68 GND output is GND
69 VCC output is VCC 69 VCC output is VCC
70 ===== ======================= 70 ===== ================================================
71 71
72 What: /sys/class/timecard/ocpN/clock 72 What: /sys/class/timecard/ocpN/clock_source
73 Date: September 2021 73 Date: September 2021
74 Contact: Jonathan Lemon <jonathan.lemon@ 74 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
75 Description: (RW) Contains the current sync 75 Description: (RW) Contains the current synchronization source used by
76 the PHC. May be changed by wr 76 the PHC. May be changed by writing one of the listed
77 values from the available_cloc 77 values from the available_clock_sources attribute set.
78 78
79 What: /sys/class/timecard/ocpN/clock 79 What: /sys/class/timecard/ocpN/clock_status_drift
80 Date: March 2022 80 Date: March 2022
81 Contact: Jonathan Lemon <jonathan.lemon@ 81 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
82 Description: (RO) Contains the current drif 82 Description: (RO) Contains the current drift value used by the firmware
83 for internal disciplining of t 83 for internal disciplining of the atomic clock.
84 84
85 What: /sys/class/timecard/ocpN/clock 85 What: /sys/class/timecard/ocpN/clock_status_offset
86 Date: March 2022 86 Date: March 2022
87 Contact: Jonathan Lemon <jonathan.lemon@ 87 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
88 Description: (RO) Contains the current offs 88 Description: (RO) Contains the current offset value used by the firmware
89 for internal disciplining of t 89 for internal disciplining of the atomic clock.
90 90
91 What: /sys/class/timecard/ocpN/freqX 91 What: /sys/class/timecard/ocpN/freqX
92 Date: March 2022 92 Date: March 2022
93 Contact: Jonathan Lemon <jonathan.lemon@ 93 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
94 Description: (RO) Optional directory contai 94 Description: (RO) Optional directory containing the sysfs nodes for
95 frequency counter <X>. 95 frequency counter <X>.
96 96
97 What: /sys/class/timecard/ocpN/freqX 97 What: /sys/class/timecard/ocpN/freqX/frequency
98 Date: March 2022 98 Date: March 2022
99 Contact: Jonathan Lemon <jonathan.lemon@ 99 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
100 Description: (RO) Contains the measured fre 100 Description: (RO) Contains the measured frequency over the specified
101 measurement period. 101 measurement period.
102 102
103 What: /sys/class/timecard/ocpN/freqX 103 What: /sys/class/timecard/ocpN/freqX/seconds
104 Date: March 2022 104 Date: March 2022
105 Contact: Jonathan Lemon <jonathan.lemon@ 105 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
106 Description: (RW) Specifies the number of s 106 Description: (RW) Specifies the number of seconds from 0-255 that the
107 frequency should be measured o 107 frequency should be measured over. Write 0 to disable.
108 108
109 What: /sys/class/timecard/ocpN/genX 109 What: /sys/class/timecard/ocpN/genX
110 Date: March 2022 110 Date: March 2022
111 Contact: Jonathan Lemon <jonathan.lemon@ 111 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
112 Description: (RO) Optional directory contai 112 Description: (RO) Optional directory containing the sysfs nodes for
113 frequency generator <X>. 113 frequency generator <X>.
114 114
115 What: /sys/class/timecard/ocpN/genX/ 115 What: /sys/class/timecard/ocpN/genX/duty
116 Date: March 2022 116 Date: March 2022
117 Contact: Jonathan Lemon <jonathan.lemon@ 117 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
118 Description: (RO) Specifies the signal duty 118 Description: (RO) Specifies the signal duty cycle as a percentage from 1-99.
119 119
120 What: /sys/class/timecard/ocpN/genX/ 120 What: /sys/class/timecard/ocpN/genX/period
121 Date: March 2022 121 Date: March 2022
122 Contact: Jonathan Lemon <jonathan.lemon@ 122 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
123 Description: (RO) Specifies the signal peri 123 Description: (RO) Specifies the signal period in nanoseconds.
124 124
125 What: /sys/class/timecard/ocpN/genX/ 125 What: /sys/class/timecard/ocpN/genX/phase
126 Date: March 2022 126 Date: March 2022
127 Contact: Jonathan Lemon <jonathan.lemon@ 127 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
128 Description: (RO) Specifies the signal phas 128 Description: (RO) Specifies the signal phase offset in nanoseconds.
129 129
130 What: /sys/class/timecard/ocpN/genX/ 130 What: /sys/class/timecard/ocpN/genX/polarity
131 Date: March 2022 131 Date: March 2022
132 Contact: Jonathan Lemon <jonathan.lemon@ 132 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
133 Description: (RO) Specifies the signal pola 133 Description: (RO) Specifies the signal polarity, either 1 or 0.
134 134
135 What: /sys/class/timecard/ocpN/genX/ 135 What: /sys/class/timecard/ocpN/genX/running
136 Date: March 2022 136 Date: March 2022
137 Contact: Jonathan Lemon <jonathan.lemon@ 137 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
138 Description: (RO) Either 0 or 1, showing if 138 Description: (RO) Either 0 or 1, showing if the signal generator is running.
139 139
140 What: /sys/class/timecard/ocpN/genX/ 140 What: /sys/class/timecard/ocpN/genX/start
141 Date: March 2022 141 Date: March 2022
142 Contact: Jonathan Lemon <jonathan.lemon@ 142 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
143 Description: (RO) Shows the time in <sec>.< 143 Description: (RO) Shows the time in <sec>.<nsec> that the signal generator
144 started running. 144 started running.
145 145
146 What: /sys/class/timecard/ocpN/genX/ 146 What: /sys/class/timecard/ocpN/genX/signal
147 Date: March 2022 147 Date: March 2022
148 Contact: Jonathan Lemon <jonathan.lemon@ 148 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
149 Description: (RW) Used to start the signal 149 Description: (RW) Used to start the signal generator, and summarize
150 the current status. 150 the current status.
151 151
152 The signal generator may be st 152 The signal generator may be started by writing the signal
153 period, followed by the option 153 period, followed by the optional signal values. If the
154 optional values are not provid 154 optional values are not provided, they default to the current
155 settings, which may be obtaine 155 settings, which may be obtained from the other sysfs nodes.
156 156
157 period [duty [phase [polar 157 period [duty [phase [polarity]]]
158 158
159 echo 500000000 > signal 159 echo 500000000 > signal # 1/2 second period
160 echo 1000000 40 100 > signal 160 echo 1000000 40 100 > signal
161 echo 0 > signal 161 echo 0 > signal # turn off generator
162 162
163 Period and phase are specified 163 Period and phase are specified in nanoseconds. Duty cycle is
164 a percentage from 1-99. Polar 164 a percentage from 1-99. Polarity is 1 or 0.
165 165
166 Reading this node will return: 166 Reading this node will return:
167 167
168 period duty phase polarity 168 period duty phase polarity start_time
169 169
170 What: /sys/class/timecard/ocpN/gnss_ 170 What: /sys/class/timecard/ocpN/gnss_sync
171 Date: September 2021 171 Date: September 2021
172 Contact: Jonathan Lemon <jonathan.lemon@ 172 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
173 Description: (RO) Indicates whether a valid 173 Description: (RO) Indicates whether a valid GNSS signal is received,
174 or when the signal was lost. 174 or when the signal was lost.
175 175
176 What: /sys/class/timecard/ocpN/i2c 176 What: /sys/class/timecard/ocpN/i2c
177 Date: September 2021 177 Date: September 2021
178 Contact: Jonathan Lemon <jonathan.lemon@ 178 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
179 Description: This optional attribute links 179 Description: This optional attribute links to the associated i2c device.
180 180
181 What: /sys/class/timecard/ocpN/irig_ 181 What: /sys/class/timecard/ocpN/irig_b_mode
182 Date: September 2021 182 Date: September 2021
183 Contact: Jonathan Lemon <jonathan.lemon@ 183 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
184 Description: (RW) An integer from 0-7 indic 184 Description: (RW) An integer from 0-7 indicating the timecode format
185 of the IRIG-B output signal: B 185 of the IRIG-B output signal: B00<n>
186 186
187 What: /sys/class/timecard/ocpN/pps 187 What: /sys/class/timecard/ocpN/pps
188 Date: September 2021 188 Date: September 2021
189 Contact: Jonathan Lemon <jonathan.lemon@ 189 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
190 Description: This optional attribute links 190 Description: This optional attribute links to the associated PPS device.
191 191
192 What: /sys/class/timecard/ocpN/ptp 192 What: /sys/class/timecard/ocpN/ptp
193 Date: September 2021 193 Date: September 2021
194 Contact: Jonathan Lemon <jonathan.lemon@ 194 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
195 Description: This attribute links to the as 195 Description: This attribute links to the associated PTP device.
196 196
197 What: /sys/class/timecard/ocpN/seria 197 What: /sys/class/timecard/ocpN/serialnum
198 Date: September 2021 198 Date: September 2021
199 Contact: Jonathan Lemon <jonathan.lemon@ 199 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
200 Description: (RO) Provides the serial numbe 200 Description: (RO) Provides the serial number of the timecard.
201 201
202 What: /sys/class/timecard/ocpN/sma1 202 What: /sys/class/timecard/ocpN/sma1
203 What: /sys/class/timecard/ocpN/sma2 203 What: /sys/class/timecard/ocpN/sma2
204 What: /sys/class/timecard/ocpN/sma3 204 What: /sys/class/timecard/ocpN/sma3
205 What: /sys/class/timecard/ocpN/sma4 205 What: /sys/class/timecard/ocpN/sma4
206 Date: September 2021 206 Date: September 2021
207 Contact: Jonathan Lemon <jonathan.lemon@ 207 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
208 Description: (RW) These attributes specify 208 Description: (RW) These attributes specify the direction of the signal
209 on the associated SMA connecto 209 on the associated SMA connectors, and also the signal sink
210 or source. 210 or source.
211 211
212 The display format of the attr 212 The display format of the attribute is a space separated
213 list of signals, prefixed by t 213 list of signals, prefixed by the input/output direction.
214 214
215 The signal direction may be ch 215 The signal direction may be changed (if supported) by
216 prefixing the signal list with 216 prefixing the signal list with either "in:" or "out:".
217 If neither prefix is present, 217 If neither prefix is present, then the direction is unchanged.
218 218
219 The output signal may be chang 219 The output signal may be changed by writing one of the listed
220 values from the available_sma_ 220 values from the available_sma_outputs attribute set.
221 221
222 The input destinations may be 222 The input destinations may be changed by writing multiple
223 values from the available_sma_ 223 values from the available_sma_inputs attribute set,
224 separated by spaces. If there 224 separated by spaces. If there are duplicated input
225 destinations between connector 225 destinations between connectors, the lowest numbered SMA
226 connector is given priority. 226 connector is given priority.
227 227
228 Note that not all input combin 228 Note that not all input combinations may make sense.
229 229
230 The 10Mhz reference clock inpu 230 The 10Mhz reference clock input is currently only valid
231 on SMA1 and may not be combine 231 on SMA1 and may not be combined with other destination sinks.
232 232
233 What: /sys/class/timecard/ocpN/tod_c 233 What: /sys/class/timecard/ocpN/tod_correction
234 Date: March 2022 234 Date: March 2022
235 Contact: Jonathan Lemon <jonathan.lemon@ 235 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
236 Description: (RW) The incoming GNSS signal 236 Description: (RW) The incoming GNSS signal is in UTC time, and the NMEA
237 format messages do not provide 237 format messages do not provide a TAI offset. This sets the
238 correction value for the incom 238 correction value for the incoming time.
239 239
240 If UBX_LS is enabled, this sho 240 If UBX_LS is enabled, this should be 0, and the offset is
241 taken from the UBX-NAV-TIMELS 241 taken from the UBX-NAV-TIMELS message.
242 242
243 What: /sys/class/timecard/ocpN/ts_wi 243 What: /sys/class/timecard/ocpN/ts_window_adjust
244 Date: September 2021 244 Date: September 2021
245 Contact: Jonathan Lemon <jonathan.lemon@ 245 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
246 Description: (RW) When retrieving the PHC w 246 Description: (RW) When retrieving the PHC with the PTP SYS_OFFSET_EXTENDED
247 ioctl, a system timestamp is m 247 ioctl, a system timestamp is made before and after the PHC
248 time is retrieved. The midpoi 248 time is retrieved. The midpoint between the two system
249 timestamps is usually taken to 249 timestamps is usually taken to be the SYS time associated
250 with the PHC time. This estim 250 with the PHC time. This estimate may be wrong, as it depends
251 on PCI latencies, and when the 251 on PCI latencies, and when the PHC time was latched
252 252
253 The attribute value reduces th 253 The attribute value reduces the end timestamp by the given
254 number of nanoseconds, so the 254 number of nanoseconds, so the computed midpoint matches the
255 retrieved PHC time. 255 retrieved PHC time.
256 256
257 The initial value is set based 257 The initial value is set based on measured PCI latency and
258 the estimated point where the 258 the estimated point where the FPGA latches the PHC time. This
259 value may be changed by writin 259 value may be changed by writing an unsigned integer.
260 260
261 What: /sys/class/timecard/ocpN/tty 261 What: /sys/class/timecard/ocpN/tty
262 Date: August 2024 262 Date: August 2024
263 Contact: Vadim Fedorenko <vadim.fedorenk 263 Contact: Vadim Fedorenko <vadim.fedorenko@linux.dev>
264 Description: (RO) Directory containing the 264 Description: (RO) Directory containing the sysfs nodes for TTY attributes
265 265
266 What: /sys/class/timecard/ocpN/tty/t 266 What: /sys/class/timecard/ocpN/tty/ttyGNSS
267 What: /sys/class/timecard/ocpN/tty/t 267 What: /sys/class/timecard/ocpN/tty/ttyGNSS2
268 Date: August 2024 268 Date: August 2024
269 Contact: Jonathan Lemon <jonathan.lemon@ 269 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
270 Description: (RO) These optional attributes 270 Description: (RO) These optional attributes contain names of the TTY serial
271 ports associated with the GNSS 271 ports associated with the GNSS devices.
272 272
273 What: /sys/class/timecard/ocpN/tty/t 273 What: /sys/class/timecard/ocpN/tty/ttyMAC
274 Date: August 2024 274 Date: August 2024
275 Contact: Jonathan Lemon <jonathan.lemon@ 275 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
276 Description: (RO) This optional attribute c 276 Description: (RO) This optional attribute contains name of the TTY serial
277 port associated with the Minia 277 port associated with the Miniature Atomic Clock.
278 278
279 What: /sys/class/timecard/ocpN/tty/t 279 What: /sys/class/timecard/ocpN/tty/ttyNMEA
280 Date: August 2024 280 Date: August 2024
281 Contact: Jonathan Lemon <jonathan.lemon@ 281 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
282 Description: (RO) This optional attribute c 282 Description: (RO) This optional attribute contains name of the TTY serial
283 port which outputs the PHC tim 283 port which outputs the PHC time in NMEA ZDA format.
284 284
285 What: /sys/class/timecard/ocpN/utc_t 285 What: /sys/class/timecard/ocpN/utc_tai_offset
286 Date: September 2021 286 Date: September 2021
287 Contact: Jonathan Lemon <jonathan.lemon@ 287 Contact: Jonathan Lemon <jonathan.lemon@gmail.com>
288 Description: (RW) The DCF and IRIG output s 288 Description: (RW) The DCF and IRIG output signals are in UTC, while the
289 TimeCard operates on TAI. Thi 289 TimeCard operates on TAI. This attribute allows setting the
290 offset in seconds, which is ad 290 offset in seconds, which is added to the TAI timebase for
291 these formats. 291 these formats.
292 292
293 The offset may be changed by w 293 The offset may be changed by writing an unsigned integer.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.