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