This page is very much a work in progress, with a focus on standing up a working initial configuration. There is an incredible amount of tuning that can be performed to dial in one of these systems after the fact. ====== PPS to SDP ====== There are a few effective ways to feed a PPS((pulse per second)) signal from a GNSS receiver, or other precision pulse source, into a computer. A few examples: systems with a "standard" serial port can use the DCD pin, and on many single board computers (Raspberry Pi et al) a GPIO pin can sometimes be used for PPS input. Purpose built hardware exists as well, network cards like the Solarflare SFN6322F have SMA connectors specifically for PPS in and out. In this article, we're going to be looking at the Intel i210 ethernet controller. A humble PCIe gigabit network interface from 2012 that was designed with four software defined pins (SDPs) that can be used for hardware timestamping via IEEE1588 and IEEE 802.1AS. {{::i210-sdp-pins.png?259 |}}The i210 and its software defined pins are well supported by the LinuxPTP project, and a number of folks have already put together some documentation on using its SDPs as a way to get hardware timestamps from a GNSS receiver into software like chrony or NTPsec. ===== Glossary of Terms ===== There are a lot of acronyms and initialisms in this space, so this terms table should help. ^ Term ^ Meaning ^ | SDP | software defined pin | | PPS | pulse per second | | TS | timestamp | | PTP | precise timing protocol | | PHC | PTP Hardware Clock | | SYS | system clock | ===== Prior Work & Documentation ===== In no particular order. * [[https://linuxptp.sourceforge.net/i210-rework/i210-rework.html|LinuxPTP i210 Rework Page]] * [[https://blog.dan.drown.org/apu2-ntp-server-2/|Dan Drown's APU2 NTP Server Project]] * [[https://chrony.tuxfamily.org/examples.html#_server_using_reference_clock_on_nic|Chrony documentation - Server using reference clock on NIC]] * [[https://docs.nvidia.com/networking/display/NVIDIA5TTechnologyUserManualv10/5T+Technology+(PTP,+SyncE,+and+more)+User+Manual|nvidia 5T user manual]] * [[https://febo.com/pipermail/time-nuts_lists.febo.com/2023-February/107321.html|This thread from the TimeNuts mailing list]] * [[https://wiki.gentoo.org/wiki/Chrony_with_hardware_timestamping|This gentoo wiki page has some good stuff]] ===== Software ===== My examples in this section will use Debian (or Debian derived) Linux. Just about everything here is generic and can apply to other systems, such as Gentoo, Arch, or the many RHEL derivatives. ==== testptp ==== [[https://github.com/torvalds/linux/blob/master/tools/testing/selftests/ptp/testptp.c|testptp]] is a tool that is included with the kernel source and can be easily built and run to verify the operation of a PTP source, as well as configure some parameters. Build with: gcc -static testptp.c -o testptp Show capabilities: root@ark02:~# testptp -c /dev/ptp0 capabilities: 62499999 maximum frequency adjustment (ppb) 0 programmable alarms 2 external time stamp channels 2 programmable periodic signals 1 pulse per second 4 programmable pins 0 cross timestamping 0 adjust_phase Show pin status: root@ark02:~# testptp /dev/ptp0 -l name SDP0 index 0 func 0 chan 0 name SDP1 index 1 func 0 chan 0 name SDP2 index 2 func 0 chan 0 name SDP3 index 3 func 0 chan 0 Change pin 0 (SDP0) to external input: root@ark02:~# testptp /dev/ptp0 -L0,1 set pin function okay root@ark02:~# testptp /dev/ptp0 -l name SDP0 index 0 func 1 chan 0 name SDP1 index 1 func 0 chan 0 name SDP2 index 2 func 0 chan 0 name SDP3 index 3 func 0 chan 0 Read ten timestamp events: root@ark02:~# testptp /dev/ptp0 -e 10 external time stamp request okay event index 0 at 1677526111.035729808 event index 0 at 1677526111.935764720 event index 0 at 1677526112.035768568 event index 0 at 1677526112.935803480 event index 0 at 1677526113.035807328 event index 0 at 1677526113.935842232 event index 0 at 1677526114.035846080 event index 0 at 1677526114.935880984 event index 0 at 1677526115.035884832 event index 0 at 1677526115.935919744 You may notice that there are only 5 seconds represented here - that's because in each timepulse there are two events, one for the rising edge, and then another for the falling edge, 100ms later. The i210 only reports both edges. ==== ts2phc ==== Part of the [[https://linuxptp.nwtime.org/about/|LinuxPTP]] project, [[https://linuxptp.nwtime.org/documentation/ts2phc/|ts2phc]] is a tool that synchronizes time stamps coming over the SDP with the PHC. The following command can be used to sync the incoming timestamps with the PHC. The system clock must be roughly correct for this to work correctly. The device can be specified as ''/dev/ptp#'' or ''enp2s0''. ts2phc -c /dev/ptp0 -s generic -l 7 -f /etc/linuxptp/ts2phc.conf -m -q ts2phc.conf [global] use_syslog 0 verbose 1 logging_level 6 ts2phc.pulsewidth 100000000 max_frequency 1000000 step_threshold 0.05 leapfile /usr/share/zoneinfo/leap-seconds.list [/dev/ptp0] ts2phc.channel 0 ts2phc.extts_polarity both ts2phc.pin_index 0 ts2phc.extts_correction 0 For a detailed explanation of the command line flags and config file settings, please check the [[https://linuxptp.nwtime.org/documentation/ts2phc/|ts2phc]] man page. Note that in the config file,''ts2phc.extts_polarity'' is set to ''both'' - this is the only polarity parameter that the i210 supports. === Example Output === ~ # ts2phc -c /dev/ptp0 -s generic -l 7 -f /etc/linuxptp/ts2phc.conf -m -q [2220.318]: locked item global.use_syslog as 0 ts2phc[2220.319]: config item (null).message_tag is '(null)' ts2phc[2220.319]: config item (null).verbose is 1 ts2phc[2220.319]: config item (null).use_syslog is 0 ts2phc[2220.319]: config item (null).logging_level is 7 ts2phc[2220.319]: config item eth0.ts2phc.master is 0 ts2phc[2220.319]: config item eth0.ts2phc.pin_index is 0 ts2phc[2220.319]: config item eth0.ts2phc.channel is 0 ts2phc[2220.319]: config item eth0.ts2phc.extts_polarity is 6 ts2phc[2220.319]: config item eth0.ts2phc.extts_correction is 0 ts2phc[2220.319]: config item eth0.ts2phc.pulsewidth is 100000000 ts2phc[2220.320]: config item (null).clock_servo is 0 ts2phc[2220.320]: config item (null).pi_proportional_const is 0.000000 ts2phc[2220.320]: config item (null).pi_integral_const is 0.000000 ts2phc[2220.320]: config item (null).pi_proportional_scale is 0.000000 ts2phc[2220.320]: config item (null).pi_proportional_exponent is -0.300000 ts2phc[2220.320]: config item (null).pi_proportional_norm_max is 0.700000 ts2phc[2220.320]: config item (null).pi_integral_scale is 0.000000 ts2phc[2220.320]: config item (null).pi_integral_exponent is 0.400000 ts2phc[2220.320]: config item (null).pi_integral_norm_max is 0.300000 ts2phc[2220.320]: config item (null).step_threshold is 0.050000 ts2phc[2220.320]: config item (null).first_step_threshold is 0.000020 ts2phc[2220.320]: config item (null).max_frequency is 1000000 ts2phc[2220.320]: config item (null).servo_offset_threshold is 0 ts2phc[2220.320]: config item (null).servo_num_offset_values is 10 ts2phc[2220.320]: PI servo: sync interval 1.000 kp 0.700 ki 0.300000 ts2phc[2220.320]: config item (null).free_running is 0 ts2phc[2220.320]: PPS sink eth0 has ptp index 0 ts2phc[2220.321]: UTC-TAI offset not set in system! Trying to revert to leapfile ts2phc[2220.321]: config item (null).leapfile is '(null)' ts2phc[2220.409]: eth0 SKIP extts index 0 at 1677618447.517148882 src 1677618485.77395669 ts2phc[2221.309]: adding tstamp 1677618448.417140794 to clock /dev/ptp0 ts2phc[2221.309]: /dev/ptp0 offset -37582859206 s0 freq -0 ts2phc[2221.409]: eth0 SKIP extts index 0 at 1677618448.517139874 src 1677618486.77376579 ts2phc[2222.309]: adding tstamp 1677618449.417131786 to clock /dev/ptp0 ts2phc[2222.309]: /dev/ptp0 offset -37582868214 s1 freq -9008 ts2phc[2222.409]: eth0 SKIP extts index 0 at 1677618487.099993986 src 1677618487.77376960 ts2phc[2223.309]: adding tstamp 1677618487.999993989 to clock /dev/ptp0 ts2phc[2223.309]: /dev/ptp0 offset -6011 s2 freq -15019 ts2phc[2223.409]: eth0 SKIP extts index 0 at 1677618488.099994569 src 1677618488.77372770 ts2phc[2224.309]: adding tstamp 1677618488.999999998 to clock /dev/ptp0 ts2phc[2224.309]: /dev/ptp0 offset -2 s2 freq -10813 ts2phc[2224.409]: eth0 SKIP extts index 0 at 1677618489.100000161 src 1677618489.77367493 ts2phc[2225.309]: adding tstamp 1677618490.000001797 to clock /dev/ptp0 ts2phc[2225.309]: /dev/ptp0 offset 1797 s2 freq -9015 ts2phc[2225.409]: eth0 SKIP extts index 0 at 1677618490.100001779 src 1677618490.77370482 ts2phc[2226.309]: adding tstamp 1677618491.000001804 to clock /dev/ptp0 ts2phc[2226.309]: /dev/ptp0 offset 1804 s2 freq -8469 (Note: in this instance, I've used ''-l 7'' for more verbose logging, which can be beneficial for diagnostic purposes.) ==== phc2sys ==== Also a part of LinuxPTP, [[https://linuxptp.nwtime.org/documentation/phc2sys/|phc2sys]] is a utility included as part of the linuxptp project for syncing clocks - usually syncing PHC to SYS. This tool is run after ''ts2phc'' to align the PHC with the system clock. phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -O +37 -m -q The +37 second offset aligns the clock with [[https://en.wikipedia.org/wiki/International_Atomic_Time|TAI]]. === Example Usage === ~ # phc2sys -c /dev/ptp0 -s CLOCK_REALTIME -O +37 -m -q phc2sys[2335.481]: /dev/ptp0 sys offset -148 s0 freq -10113 delay 2055 phc2sys[2336.481]: /dev/ptp0 sys offset -161 s2 freq -10126 delay 2064 phc2sys[2337.481]: /dev/ptp0 sys offset -184 s2 freq -10310 delay 2065 phc2sys[2338.481]: /dev/ptp0 sys offset 38 s2 freq -10143 delay 2068 phc2sys[2339.482]: /dev/ptp0 sys offset 47 s2 freq -10123 delay 2042 phc2sys[2340.482]: /dev/ptp0 sys offset 69 s2 freq -10087 delay 2071 phc2sys[2341.482]: /dev/ptp0 sys offset 43 s2 freq -10092 delay 2077 phc2sys[2342.483]: /dev/ptp0 sys offset 6 s2 freq -10116 delay 2074 phc2sys[2343.483]: /dev/ptp0 sys offset -5 s2 freq -10125 delay 2070 phc2sys[2344.483]: /dev/ptp0 sys offset 5 s2 freq -10117 delay 2058 phc2sys[2345.483]: /dev/ptp0 sys offset 2 s2 freq -10118 delay 2069 phc2sys[2346.484]: /dev/ptp0 sys offset -7 s2 freq -10127 delay 2069 ==== chrony ==== Example chrony configuration server time-a.nist.gov server time-a-wwv.nist.gov refclock PHC /dev/ptp0 tai refid PTP dpoll -4 poll -2 leapsectz right/UTC logdir /var/log/chrony log statistics tracking driftfile /var/lib/chrony/chrony.drift rtcsync allow cmdallow ===== Hardware ===== Thankfully, the i210 is a common and popular chip, supported in most current operating systems. It can be found on PCIe cards, as well as on the motherboards of many systems. The intel reference design PCIe card is one of the best options - it exists with both low profile and full height PCIe backets, and the software defined pins are immediately accessible via a 6 pin header. The SDP pins are rated for 3v3, which makes them very well suited to the 3v3 PPS output from many readily available GNSS modules. ^ i210 on ARK-1123H ^ i210 on PCIe Card ^ | {{::i210_amo.jpeg?400}} | {{::intel_i210_pcie.png?400}} | ^ i210 on NANO-6050 (with SDP0 wire!) ^ i210 on PC Engines apu2e0 (SDPs exposed as test pads) ^ | {{::i210_nano6050.png?400 }} | {{::i210_apu_gps.jpg?400}} |