Documentation/ABI/testing/sysfs-timecard

   1 What:           /sys/class/timecard/
   2 Date:           September 2021
   3 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
   4 Description:    This directory contains files and directories
   5                 providing a standardized interface to the ancillary
   6                 features of the OpenCompute timecard.
   7
   8 What:           /sys/class/timecard/ocpN/
   9 Date:           September 2021
  10 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
  11 Description:    This directory contains the attributes of the Nth timecard
  12                 registered.
  13
  14 What:           /sys/class/timecard/ocpN/available_clock_sources
  15 Date:           September 2021
  16 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
  17 Description:    (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
  28 What:           /sys/class/timecard/ocpN/available_sma_inputs
  29 Date:           September 2021
  30 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
  31 Description:    (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
  51 What:           /sys/class/timecard/ocpN/available_sma_outputs
  52 Date:           May 2021
  53 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
  54 Description:    (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
  72 What:           /sys/class/timecard/ocpN/clock_source
  73 Date:           September 2021
  74 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
  75 Description:    (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
  79 What:           /sys/class/timecard/ocpN/clock_status_drift
  80 Date:           March 2022
  81 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
  82 Description:    (RO) Contains the current drift value used by the firmware
  83                 for internal disciplining of the atomic clock.
  84
  85 What:           /sys/class/timecard/ocpN/clock_status_offset
  86 Date:           March 2022
  87 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
  88 Description:    (RO) Contains the current offset value used by the firmware
  89                 for internal disciplining of the atomic clock.
  90
  91 What:           /sys/class/timecard/ocpN/freqX
  92 Date:           March 2022
  93 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
  94 Description:    (RO) Optional directory containing the sysfs nodes for
  95                 frequency counter <X>.
  96
  97 What:           /sys/class/timecard/ocpN/freqX/frequency
  98 Date:           March 2022
  99 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 100 Description:    (RO) Contains the measured frequency over the specified
 101                 measurement period.
 102
 103 What:           /sys/class/timecard/ocpN/freqX/seconds
 104 Date:           March 2022
 105 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 106 Description:    (RW) Specifies the number of seconds from 0-255 that the
 107                 frequency should be measured over.  Write 0 to disable.
 108
 109 What:           /sys/class/timecard/ocpN/genX
 110 Date:           March 2022
 111 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 112 Description:    (RO) Optional directory containing the sysfs nodes for
 113                 frequency generator <X>.
 114
 115 What:           /sys/class/timecard/ocpN/genX/duty
 116 Date:           March 2022
 117 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 118 Description:    (RO) Specifies the signal duty cycle as a percentage from 1-99.
 119
 120 What:           /sys/class/timecard/ocpN/genX/period
 121 Date:           March 2022
 122 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 123 Description:    (RO) Specifies the signal period in nanoseconds.
 124
 125 What:           /sys/class/timecard/ocpN/genX/phase
 126 Date:           March 2022
 127 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 128 Description:    (RO) Specifies the signal phase offset in nanoseconds.
 129
 130 What:           /sys/class/timecard/ocpN/genX/polarity
 131 Date:           March 2022
 132 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 133 Description:    (RO) Specifies the signal polarity, either 1 or 0.
 134
 135 What:           /sys/class/timecard/ocpN/genX/running
 136 Date:           March 2022
 137 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 138 Description:    (RO) Either 0 or 1, showing if the signal generator is running.
 139
 140 What:           /sys/class/timecard/ocpN/genX/start
 141 Date:           March 2022
 142 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 143 Description:    (RO) Shows the time in <sec>.<nsec> that the signal generator
 144                 started running.
 145
 146 What:           /sys/class/timecard/ocpN/genX/signal
 147 Date:           March 2022
 148 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 149 Description:    (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
 170 What:           /sys/class/timecard/ocpN/gnss_sync
 171 Date:           September 2021
 172 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 173 Description:    (RO) Indicates whether a valid GNSS signal is received,
 174                 or when the signal was lost.
 175
 176 What:           /sys/class/timecard/ocpN/i2c
 177 Date:           September 2021
 178 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 179 Description:    This optional attribute links to the associated i2c device.
 180
 181 What:           /sys/class/timecard/ocpN/irig_b_mode
 182 Date:           September 2021
 183 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 184 Description:    (RW) An integer from 0-7 indicating the timecode format
 185                 of the IRIG-B output signal: B00<n>
 186
 187 What:           /sys/class/timecard/ocpN/pps
 188 Date:           September 2021
 189 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 190 Description:    This optional attribute links to the associated PPS device.
 191
 192 What:           /sys/class/timecard/ocpN/ptp
 193 Date:           September 2021
 194 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 195 Description:    This attribute links to the associated PTP device.
 196
 197 What:           /sys/class/timecard/ocpN/serialnum
 198 Date:           September 2021
 199 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 200 Description:    (RO) Provides the serial number of the timecard.
 201
 202 What:           /sys/class/timecard/ocpN/sma1
 203 What:           /sys/class/timecard/ocpN/sma2
 204 What:           /sys/class/timecard/ocpN/sma3
 205 What:           /sys/class/timecard/ocpN/sma4
 206 Date:           September 2021
 207 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 208 Description:    (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
 233 What:           /sys/class/timecard/ocpN/tod_correction
 234 Date:           March 2022
 235 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 236 Description:    (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
 243 What:           /sys/class/timecard/ocpN/ts_window_adjust
 244 Date:           September 2021
 245 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 246 Description:    (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
 261 What:           /sys/class/timecard/ocpN/tty
 262 Date:           August 2024
 263 Contact:        Vadim Fedorenko <vadim.fedorenko@linux.dev>
 264 Description:    (RO) Directory containing the sysfs nodes for TTY attributes
 265
 266 What:           /sys/class/timecard/ocpN/tty/ttyGNSS
 267 What:           /sys/class/timecard/ocpN/tty/ttyGNSS2
 268 Date:           August 2024
 269 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 270 Description:    (RO) These optional attributes contain names of the TTY serial
 271                 ports associated with the GNSS devices.
 272
 273 What:           /sys/class/timecard/ocpN/tty/ttyMAC
 274 Date:           August 2024
 275 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 276 Description:    (RO) This optional attribute contains name of the TTY serial
 277                 port associated with the Miniature Atomic Clock.
 278
 279 What:           /sys/class/timecard/ocpN/tty/ttyNMEA
 280 Date:           August 2024
 281 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 282 Description:    (RO) This optional attribute contains name of the TTY serial
 283                 port which outputs the PHC time in NMEA ZDA format.
 284
 285 What:           /sys/class/timecard/ocpN/utc_tai_offset
 286 Date:           September 2021
 287 Contact:        Jonathan Lemon <jonathan.lemon@gmail.com>
 288 Description:    (RW) The DCF and IRIG output signals are in UTC, while the
 289                 TimeCard operates on TAI.  This attribute allows setting the
 290                 offset in seconds, which is added to the TAI timebase for
 291                 these formats.
 292
 293                 The offset may be changed by writing an unsigned integer.