gps/soc/software/pps_end_to_end_validation/README.md

GPS PPS end-to-end Linux validation

This package is a deterministic, causal validation of the project timing path from synthetic GPS LNAV data to the physical PPS edge. It exists separately from pps_python, whose models concentrate on WLS noise, oscillator behavior, and adaptive-loop performance.

The validation does not use Linux wall-clock scheduling. The 1 kHz, 50 bit/s, RF-sample, PCLK, and 125 MHz events advance from synthetic timestamps, making the signed absolute-time result repeatable on a normal Linux host.

What is modeled

The model follows the current firmware and RTL conventions:

1. It generates deterministic GPS LNAV subframes with D29*/D30* data inversion and valid parity for all ten 30-bit words.
2. Each navigation bit is expanded to twenty 1 kHz prompt-sign samples.
3. The bit_gen.sv 40 ms 1 -> 0 transition acquisition, majority decision, 20 ms bit_valid cadence, and registered ABS_SAMPLE behavior are applied.
4. The tracking wrapper's chronological 2 + 300 + 8 = 310 bit window, preamble search, parity check, load_sigs, and subframe interrupt ordering are applied.
5. nav_solve_timer is initialized from HOW Z-count and counts later bit-valid events. Navigation-solve interrupt, PPS counter capture, capture sequence, and a 32-bit RF ABS_SAMPLE wrap are exercised.
6. Firmware reconstructs periodic TOW from the HOW/sample anchor and evaluates TOW + POSTPONE_TOW + STARTOFFSET - b/c.
7. The timestamped 125 MHz PPS peripheral performs coarse/normal mapping, ignores synthetic CPU/APB delay as phase, acquires lock after five valid updates, and generates integer-second edges.
8. DUT edges are compared with an independent trusted PPS. Optional DUT and trusted-output delays make board, cable, and vendor delay sign explicit.

This is a digital epoch-path validation, not an RF waveform simulator. The existing pps_python tests continue to cover WLS, oscillator, PI, adaptive quality, and holdover behavior.

Run

From soc/software:

python3 -m pps_end_to_end_validation.pps_end_to_end
python3 -m unittest pps_end_to_end_validation/test_pps_end_to_end.py

The default command executes the diagnostic matrix:

scenario                 bits  correction  reference error  DUT - trusted PPS
current-rtl/160ms            9      160 ms    -20.000032 ms     +20.000032 ms
current-bit/160ms            8      160 ms     -0.000032 ms      +0.000032 ms
current-rtl/180ms            9      180 ms     -0.000032 ms      +0.000032 ms

Positive DUT - trusted PPS means the project output is late. The default 32 ns remainder is the explicitly configured four-tick PCLK capture pipeline; it is not part of the LNAV-bit mismatch.

Run one scenario or obtain machine-readable output:

python3 -m pps_end_to_end_validation.pps_end_to_end \
  --mode current-rtl --postpone-ms 160 --json

python3 -m pps_end_to_end_validation.pps_end_to_end \
  --mode current-bit \
  --dut-output-delay-ns 12 \
  --trusted-output-delay-ns 35

20 ms diagnosis

The current tracking wrapper shifts the current bit into shift_reg_n, while its preamble/parity predicate reads the preceding shift_reg_p. On the eighth following preamble bit, the validator therefore sees only the previous seven bits. The register contains all eight after the edge, but the bit-valid edge condition has ended. Validation occurs on the ninth bit, 20 ms later.

The implemented interface is consequently:

current RTL delivery       9 * 20 ms = 180 ms
firmware POSTPONE_TOW      8 * 20 ms = 160 ms
signed epoch mismatch                    20 ms

With the current bitstream, POSTPONE_TOW=0.180 is a firmware-only workaround and must be used consistently by both satellite-state and PPS calculations. It is 180 ms, not 190 ms. The preferred permanent correction is to validate a candidate window containing the current eighth bit and retain the intended 160 ms firmware compensation.

The validation intentionally does not modify production RTL or firmware.

Other regression coverage

The unit tests verify:

• parity-valid LNAV round-trip and rejection after one corrupted data bit;
• 1 kHz prompt-sign to 50 bit/s generation and the registered 1 ms sample lag;
• ninth-bit delivery in current RTL and eighth-bit delivery in the candidate implementation;
• constant signed PPS error over successive physical edges;
• 180 ms firmware compatibility with current RTL;
• invariance to synthetic CPU/APB stalls when capture timestamps are used;
• DUT-versus-trusted output-delay sign; and
• rejection behavior for the firmware-permitted NAV_SOLVE_TIMER=40 case.

The N=40 case divides the GPS week but not a 300-bit subframe. When firmware refreshes the HOW/sample anchor after six seconds, the timer phase is half a solve period away from that anchor and the current N * 20 ms snap rejects otherwise valid solves. Production N=10 divides 300 and is unaffected.

If general timer periods are required, reconstruct elapsed time on the fundamental 20 ms navigation-bit grid. A narrower compatibility restriction is to accept only periods for which 300 % N == 0.

Hardware confirmation

Before selecting a production correction:

1. Probe bit_valid, the final preamble bits, preamble_ok, parity result, and load_sigs with ILA.
2. Count whether delivery is on following bit 8 or 9 in the flashed bitstream.
3. Measure DUT and trusted PPS with a common time-interval counter and record the sign. The diagnosis predicts a DUT edge approximately 20 ms late.
4. Apply only nanosecond-scale output/cable calibration after the epoch mismatch is removed.