rp1-ptp-pps: add RP1 Ethernet PHC PPS utility

CMakeLists.txt

@@ -2,6 +2,8 @@ cmake_minimum_required(VERSION 3.1...3.27)
 
 project(utils)
 
+include(CTest)
+
 option(ENABLE_WERROR "Treat compiler warnings as errors" OFF)
 
 # List of subsidiary CMakeLists
@@ -16,6 +18,7 @@ add_subdirectory(ovmerge)
 add_subdirectory(pinctrl)
 add_subdirectory(piolib)
 add_subdirectory(raspinfo)
+add_subdirectory(rp1-ptp-pps)
 add_subdirectory(rpieepromab)
 add_subdirectory(rpi-gpu-usage)
 add_subdirectory(vcgencmd)

README.md

@@ -22,6 +22,7 @@ A collection of scripts and simple applications
 * [piolib](piolib/) - A library for accessing the Pi 5's PIO hardware.
 * [raspinfo](raspinfo/) - A short script to dump information about the Pi. Intended for
     the submission of bug reports.
+* [rp1-ptp-pps](rp1-ptp-pps/) - PTP timestamp input and PPS output on the RP1 Ethernet PHC.
 * [rpieepromab](rpieepromab/) - A tool to update and manage the AB EEPROM partitions
     on a device in the Pi 5 family.
 * [rpifwcrypto](rpifwcrypto/) - A command line application and shared library for the

rp1-ptp-pps/CMakeLists.txt

@@ -0,0 +1,41 @@
+cmake_minimum_required(VERSION 3.10...3.27)
+include(GNUInstallDirs)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+
+find_package(Python3 COMPONENTS Interpreter REQUIRED)
+
+add_executable(testptp testptp.c)
+target_include_directories(testptp PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)
+target_link_libraries(testptp PRIVATE m)
+
+configure_file(rp1-pps.in ${CMAKE_CURRENT_BINARY_DIR}/rp1-pps @ONLY)
+configure_file(rp1-pps.service.in ${CMAKE_CURRENT_BINARY_DIR}/rp1-pps.service @ONLY)
+configure_file(rp1-pps-duplex.service.in
+               ${CMAKE_CURRENT_BINARY_DIR}/rp1-pps-duplex.service @ONLY)
+configure_file(rp1-pps.conf.example.in
+               ${CMAKE_CURRENT_BINARY_DIR}/rp1-pps.conf.example @ONLY)
+
+install(TARGETS testptp RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+install(PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/rp1-pps
+        DESTINATION ${CMAKE_INSTALL_BINDIR})
+install(FILES rp1_pps.py phc_identity.py
+        DESTINATION ${CMAKE_INSTALL_LIBEXECDIR}/rp1-ptp-pps)
+set(RP1_PPS_SYSTEMD_UNITDIR "lib/systemd/system" CACHE STRING
+    "Directory for RP1 PPS systemd unit files")
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/rp1-pps.service
+              ${CMAKE_CURRENT_BINARY_DIR}/rp1-pps-duplex.service
+        DESTINATION ${RP1_PPS_SYSTEMD_UNITDIR})
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/rp1-pps.conf.example
+        DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/rp1-ptp-pps/examples)
+install(FILES README.md LICENSE
+        DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/rp1-ptp-pps)
+
+include(CTest)
+if(BUILD_TESTING)
+    add_test(NAME rp1-ptp-pps-runtime
+        COMMAND ${Python3_EXECUTABLE} -m unittest discover
+                -s ${CMAKE_CURRENT_SOURCE_DIR}/tests
+                -p test_rp1_pps_runtime.py)
+endif()

rp1-ptp-pps/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Byagowi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rp1-ptp-pps/README.md

@@ -0,0 +1,54 @@
+# RP1 Ethernet PHC PPS support
+
+`rp1-ptp-pps` configures the PTP hardware clock on the RP1 Ethernet MAC through
+Linux's standard PTP interface. The command-line utility uses the kernel's
+`testptp` tool. It supports selected GPIO input and output, including a mode
+with two independent rising-edge inputs and one simultaneous periodic output.
+
+The PHC driver must report two external timestamp channels, one periodic
+output channel, and 28 programmable pins. The runtime checks those capabilities
+before it maps a pin. The kernel support is under review in
+[raspberrypi/linux PR 7659](https://github.com/raspberrypi/linux/pull/7659).
+
+GPIO numbers are BCM/RP1 GPIO numbers 0 through 27, not physical header pin
+numbers. GPIO18 is physical pin 12, GPIO23 is pin 16, and GPIO24 is pin 18.
+Signals connected to a Pi GPIO must remain between 0 and 3.3 V. Do not connect
+two actively driven output pins together.
+
+Build and install from the `utils` repository:
+
+```sh
+cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr
+cmake --build build
+sudo cmake --install build
+```
+
+The standalone command prints a plan without changing hardware. Add
+`--execute` only after checking that the selected pins are wired and available:
+
+```sh
+sudo rp1-pps --mode duplex --input-gpio 18 --input-gpio2 24 \
+  --output-gpio 23 --events 8 --execute
+```
+
+To run continuously under systemd, copy
+`/usr/share/doc/rp1-ptp-pps/examples/rp1-pps.conf.example` to
+`/etc/default/rp1-pps`, edit the PHC interface and BCM GPIOs, then enable
+exactly one service. The example values use GPIO18 and prepare GPIO24 and
+GPIO23 for duplex mode. For duplex operation, enable
+`rp1-pps-duplex.service`:
+
+```sh
+sudo cp /usr/share/doc/rp1-ptp-pps/examples/rp1-pps.conf.example \
+  /etc/default/rp1-pps
+sudoedit /etc/default/rp1-pps
+sudo systemctl daemon-reload
+sudo systemctl enable --now rp1-pps-duplex.service
+```
+
+The second input uses EXTTS channel 1, which currently requires active PEROUT.
+Disable the service before removing or rewiring its GPIO connections. Rising
+edges are used by the simultaneous counter path. Its edge timing has not been
+independently calibrated, so this software makes no board-level accuracy or
+jitter guarantee. Physical validation currently covers only earlier
+sequential tests; simultaneous two-input capture is still under qualification.