librx888: short-transfer / PPS-window accounting

[ringof]

Why

The current stats (ok_xfers, bad_xfers, bytes_out) can't see the one failure mode that worries people most: PCLK edges silently lost between the ADC and the GPIF. From the FX3's perspective those samples never existed — no overrun fires, no counter increments.

rx888-firmware is moving toward GPIF-side PPS injection: the state machine watches a PPS CTL pin and forces a DMA commit on the rising edge. Sample data stays pristine — the marker lives in the DMA framing, as a USB transfer shorter than the configured buffer size. Bytes between consecutive short transfers = PCLK edges per PPS interval = should be exactly fs. Any deficit = ADC→GPIF silent drop, localised.

This patch lands the host-side detector first, so we can calibrate the instrument and confirm it produces the same answer across repeated captures before the firmware feature ships. Once it does, the same code goes live with no driver change.

What

New rx888_stats_t fields:

• full_xfers, short_xfers, zero_xfers
• min_actual_len, max_actual_len, expected_xfer_bytes
• bytes_in_window, last_window_bytes

Pure classification logic in src/pps_audit.h (no atomics, no I/O). librx888 owns one pps_audit_t per device, mutated only by the writer thread; values mirrored to atomic fields for rx888_get_stats(). With stock firmware that never short-commits, short_xfers stays at 0.

Synthetic debug mode via cfg.debug_synthetic_pps_every (default 0). When >0, every Nth completed transfer is classified as a forced short, exercising the detector end-to-end against firmware that does not (yet) force commits. Real sample data is unaffected.

rx888_stream -v prints full, short, last_window every second.

Tests

• tests/pps_audit_test.c — unit tests for the pure classification: all-full, natural shorts, two-window math, force_short, zero-length handling, synthetic-pattern coverage
• tests/librx888_api.c — extended for the new config default and stats fields
• make check and make check-asan both green

Determinism check (next step)

Before trusting the detector against real drops, we need to confirm the host-side measurement is repeatable. Plan: run rx888_stream for fixed duration N times against healthy hardware, assert bytes_out, bad_xfers, short_xfers (with debug_synthetic_pps_every=K) converge across runs. If they don't, there's noise in the instrument to chase before we can attribute any short-transfer event to a real ADC slip.

What this doesn't do (yet)

• No firmware dependency. Stock firmware never produces short transfers in steady state, so this is dormant until the GPIF-side PPS commit lands.
• No GETSTATS / 0xB7 integration. Once firmware exposes a pps_commits counter, the driver should cross-check it against short_xfers to detect any misclassification.
• No iqrecord integration. The run.json could record short-transfer boundaries so post-hoc verification can assert marker_interval_bytes == fs × 2; deferred.

Draft until determinism testing on real hardware lands.

---

Generated by Claude Code