Wi-Fi hardware-timestamping prototypes: USB RX SO_TIMESTAMPING + PCIe PHC/rtw88

Out-of-band reference tooling behind the timing findings in
docs/timing-accuracy.md. None of it is part of the devourer library build.

USB (surfaces the vendor rtl88x2cu RX hardware timestamp):
- Bump the reference/rtl88x2cu submodule to the merged CONFIG_RTW_HWTSTAMP driver
  (attaches the RX-descriptor TSF to skb_hwtstamps -> SO_TIMESTAMPING).
- tests/rx_hwtstamp_probe.c: AF_PACKET + SO_TIMESTAMPING reader.
- tests/rx_hwtstamp_validate.sh: capability check (driver swap + ethtool -T).
- tests/rx_hwtstamp_onair.sh: on-air value check against a devourer open AP.

PCIe (RTL8821CE, rtw88):
- tests/pcie_phc/: a passive PTP hardware clock off the MAC TSF over BAR2 MMIO
  (rtw88 stays bound), a gettime-latency probe, an Intel-I226 cross-check, and a
  one-hunk rtw88 RX skb_hwtstamps patch. See tests/pcie_phc/README.md.
- tests/pcie_tsf_read.c: userspace BAR2 TSF reader.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: josephnef

reference/rtl88x2cu

@@ -0,0 +1,13 @@
+# Out-of-tree build of the RTL8821CE TSF PHC prototype.
+#   make            # build against the running kernel
+#   make KDIR=/path # build against a specific kernel tree
+obj-m += rtl8821ce_phc.o
+
+KDIR ?= /lib/modules/$(shell uname -r)/build
+PWD  := $(shell pwd)
+
+all:
+	$(MAKE) -C $(KDIR) M=$(PWD) modules
+
+clean:
+	$(MAKE) -C $(KDIR) M=$(PWD) clean

tests/pcie_phc/Makefile

@@ -0,0 +1,36 @@
+# PCIe hardware-timestamping / PTP prototypes (RTL8821CE)
+
+Reference tooling behind the PCIe timing numbers in
+[`docs/timing-accuracy.md`](../../docs/timing-accuracy.md). These are kernel-side
+experiments on the Radxa X4's onboard RTL8821CE (`rtw88`), run out-of-band — they
+are **not** part of the devourer library build.
+
+## Contents
+
+- `rtl8821ce_phc.c` + `Makefile` — a passive PTP hardware clock (`/dev/ptpN`)
+  backed by the 8821CE's 802.11 MAC TSF, read over BAR2 MMIO. It does **not** bind
+  the PCI device: `rtw88` stays bound and keeps the chip alive, and the module
+  only `ioremap`s the BAR and reads the free-running TSF, exposed as a
+  disciplinable clock via `timecounter`/`cyclecounter`.
+- `validate.sh` — builds, loads, and exercises the PHC with `phc_ctl` / `phc2sys`.
+- `pcie_phc_lat.c` — measures the PHC gettime read window
+  (`PTP_SYS_OFFSET_EXTENDED`): the PCIe MMIO floor (~3.7 µs), versus tens of µs
+  for the equivalent read over USB.
+- `ptp_crosscheck.sh` — runs `ptp4l` on the board's Intel I226 Ethernet (a real
+  IEEE-1588 NIC) and cross-compares the Wi-Fi TSF PHC against it on one machine.
+- `rtw88_rx_hwtstamp.patch` — a one-hunk `rtw88` patch attaching the RX-descriptor
+  TSF to `skb_hwtstamps` before `ieee80211_rx_napi`, so a `SO_TIMESTAMPING` socket
+  reads the 802.11 hardware RX timestamp on the PCIe / `mac80211` path.
+
+## Requirements
+
+Kernel headers, `linuxptp`, and `ethtool` on the target. The MAC TSF is
+power-gated while the card is idle — bring the interface up in monitor mode (or
+associate) so the TSF is clocked before loading the PHC.
+
+## Scope
+
+These explore hardware-RX timestamping and a real PHC on the PCIe part. Two-way
+`ptp4l` over the Wi-Fi radio remains blocked on a host-reported TX-egress
+timestamp (a firmware limitation); the board's I226 Ethernet is the real-PTP
+reference. See `docs/timing-accuracy.md` for the measured results and that limit.

tests/pcie_phc/README.md

@@ -0,0 +1,54 @@
+// pcie_phc_lat.c — measure the PHC gettime floor of /dev/ptpN via the
+// PTP_SYS_OFFSET_EXTENDED ioctl. Each sample brackets the driver's device read
+// with a system-clock pre/post timestamp; (post - pre) is the time the PHC
+// spends reading its hardware clock — for the RTL8821CE TSF PHC that is a BAR2
+// MMIO load. This is the number that makes a PCIe PHC "tractable": ~us and low
+// jitter, versus a ~68 us jittery USB control transfer.
+//
+// Build: cc -O2 -o pcie_phc_lat pcie_phc_lat.c
+// Run:   sudo ./pcie_phc_lat /dev/ptpN [n_samples]
+#include <fcntl.h>
+#include <linux/ptp_clock.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <unistd.h>
+
+static uint64_t ns(struct ptp_clock_time t) { return t.sec * 1000000000ull + t.nsec; }
+static int cmp(const void *a, const void *b) {
+  uint64_t x = *(const uint64_t *)a, y = *(const uint64_t *)b;
+  return x < y ? -1 : x > y ? 1 : 0;
+}
+
+int main(int argc, char **argv) {
+  const char *dev = argc > 1 ? argv[1] : "/dev/ptp0";
+  int n = argc > 2 ? atoi(argv[2]) : 25;
+  if (n < 1) n = 1;
+  if (n > PTP_MAX_SAMPLES) n = PTP_MAX_SAMPLES;
+
+  int fd = open(dev, O_RDONLY);
+  if (fd < 0) { perror("open ptp"); return 1; }
+
+  struct ptp_sys_offset_extended off = {0};
+  off.n_samples = n;
+  if (ioctl(fd, PTP_SYS_OFFSET_EXTENDED, &off) < 0) { perror("PTP_SYS_OFFSET_EXTENDED"); return 1; }
+
+  uint64_t *win = malloc(sizeof(uint64_t) * n);
+  double mean = 0;
+  for (int i = 0; i < n; i++) {
+    uint64_t pre = ns(off.ts[i][0]);   // system before device read
+    uint64_t post = ns(off.ts[i][2]);  // system after device read
+    win[i] = post - pre;
+    mean += win[i];
+  }
+  mean /= n;
+  qsort(win, n, sizeof(uint64_t), cmp);
+  printf("PHC gettime read window over %d samples (%s):\n", n, dev);
+  printf("  mean=%.0f ns  p50=%llu ns  p99=%llu ns  min=%llu ns  max=%llu ns\n",
+         mean, (unsigned long long)win[n / 2], (unsigned long long)win[n * 99 / 100],
+         (unsigned long long)win[0], (unsigned long long)win[n - 1]);
+  // Also show the device (PHC) time from the middle sample, for sanity.
+  printf("  phc time (mid sample) = %llu ns\n", (unsigned long long)ns(off.ts[n / 2][1]));
+  return 0;
+}

tests/pcie_phc/pcie_phc_lat.c

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# ptp_crosscheck.sh — on the radxa-x4, (1) show the Intel I226 Ethernet doing
+# real IEEE-1588 hardware PTP, and (2) cross-compare the 8821CE Wi-Fi TSF PHC
+# against that real PTP clock on the SAME machine — quantifying the Wi-Fi TSF's
+# frequency error and short-term stability versus genuine PTP hardware, with no
+# second machine and no network dependency.
+#
+#   sudo tests/pcie_phc/ptp_crosscheck.sh
+set -uo pipefail
+cd "$(dirname "$0")"
+ETH=enp2s0
+WIF=wlp1s0
+MOD=rtl8821ce_phc
+
+cleanup() {
+  echo "[xchk] cleanup"
+  sudo pkill -x ptp4l phc2sys 2>/dev/null
+  sudo rmmod "$MOD" 2>/dev/null
+  sudo ip link set "$WIF" down 2>/dev/null
+  sudo iw dev "$WIF" set type managed 2>/dev/null
+  sudo ip link set "$WIF" up 2>/dev/null
+  command -v nmcli >/dev/null && sudo nmcli dev set "$WIF" managed yes 2>/dev/null
+}
+trap cleanup EXIT
+
+# --- find the igc (Ethernet) PHC ---
+IGC_PTP=""
+for d in /sys/class/ptp/ptp*; do
+  n=$(cat "$d/clock_name" 2>/dev/null)
+  case "$n" in
+    rtl8821ce_tsf) : ;;                        # skip ours if already loaded
+    *) [ -e "/dev/$(basename "$d")" ] && IGC_PTP="/dev/$(basename "$d")" ;;
+  esac
+done
+echo "[xchk] Ethernet (I226) PHC = ${IGC_PTP:-<none>}"
+
+# --- 1. prove the I226 does hardware-timestamped PTP ---
+echo "[xchk] === ptp4l on $ETH (I226): does it use HARDWARE timestamping? ==="
+sudo timeout 8 ptp4l -i "$ETH" -m 2>&1 | grep -iE "clock|hardware|selected|MASTER|assuming|state" | head -6 || true
+
+# --- put the Wi-Fi MAC in monitor mode so the TSF ticks, then load our PHC ---
+echo "[xchk] arming Wi-Fi TSF PHC"
+sudo pkill -x wpa_supplicant 2>/dev/null
+command -v nmcli >/dev/null && sudo nmcli dev set "$WIF" managed no 2>/dev/null
+sleep 1
+sudo ip link set "$WIF" down; sudo iw dev "$WIF" set type monitor 2>/dev/null; sudo ip link set "$WIF" up
+sudo iw dev "$WIF" set channel 6 2>/dev/null
+sleep 1
+make -s >/dev/null 2>&1
+sudo rmmod "$MOD" 2>/dev/null
+sudo insmod "./$MOD.ko" || { echo "[xchk] PHC insmod failed"; exit 1; }
+sleep 1
+WIF_PTP=""
+for d in /sys/class/ptp/ptp*; do
+  [ "$(cat "$d/clock_name" 2>/dev/null)" = "rtl8821ce_tsf" ] && WIF_PTP="/dev/$(basename "$d")"
+done
+echo "[xchk] Wi-Fi TSF PHC = ${WIF_PTP:-<none>}"
+[ -z "$WIF_PTP" ] && { echo "[xchk] no Wi-Fi PHC"; exit 1; }
+[ -z "$IGC_PTP" ] && { echo "[xchk] no Ethernet PHC to compare against"; exit 1; }
+
+# --- 2. cross-compare: discipline the Wi-Fi PHC to the I226 hardware clock.
+# The Wi-Fi PHC is the slave (system + I226 untouched). Steady-state:
+#   'freq' ~= the Wi-Fi crystal's frequency error vs the I226 (ppb)
+#   'offset' jitter ~= the Wi-Fi TSF short-term stability vs real PTP hardware ---
+echo "[xchk] === phc2sys: Wi-Fi TSF ($WIF_PTP) vs real PTP hardware ($IGC_PTP), ~25 s ==="
+sudo timeout 27 phc2sys -s "$IGC_PTP" -c "$WIF_PTP" -O 0 -m 2>&1 | grep -iE "offset" | tail -20 || true
+echo "[xchk] done"