feat(pps): add adaptive disciplined timing loop

soc/software/gps_system/README.md

@@ -1173,7 +1173,8 @@ Bu timer/scheduler yavasligi degildir. Firmware start ediyor; tamamlanma icin RF
   darbesi uretir. Bu olay `ABS_SAMPLE` ve `REM_CODE_PHASE` latch'iyle aynidir;
   subframe-ready PPS timestamp'i olusturmaz.
 - `leastSquaresSTD()` ayni basarili epoch'un `[x, y, z, b]` sonucunu verir.
-  Minimum corrected-ABS kanalinin receive-time ankraji su sekilde kurulur:
+  Ilk cozumde en erken corrected-ABS kanali zaman datum'u secilir; ayni SVID
+  coherent snapshot'ta kaldigi surece referans korunur. Receive-time ankraji:
 
 ```text
 T_rx = TOW_ref + POSTPONE_TOW + STARTOFFSET/1000 - b/c
@@ -1182,12 +1183,108 @@ T_rx = TOW_ref + POSTPONE_TOW + STARTOFFSET/1000 - b/c
 - `POSTPONE_TOW=0.160 s`, takip eden subframe'dan parity icin beklenen sekiz
   bitin gecikmesidir ve yazilim tarafinda tam bir kez uygulanir. PPS RTL bu
   degeri tekrar eklemez.
-- Bu GPS zamani, ayni minimum-ABS kanalinin 125 MHz capture counter'i ile atomik
+- Bu GPS zamani, ayni kalici referans kanalinin 125 MHz capture counter'i ile atomik
   APB mailbox uzerinden eslenir. Ilk cozum coarse-align, sonraki cozumler Q2.46
   dusuk bant genislikli PI rate discipline yapar. WLS/APB calisma suresi faz
   hatasi olarak kullanilmaz.
+- Tracking capture olayi integer RF sample kenarinda olustugu halde WLS,
+  `ABS_SAMPLE - REM_CODE_PHASE/1.023e6` alt-sample zamanini kullanir. Yazilim
+  mailbox `EPOCH_COUNTER` degerinden ayni fractional sample gecikmesini
+  `round(fraction * 125e6/16.367981e6)` ile cikarir. Boylece WLS zamani ile
+  hardware epoch'u ayni code boundary'ye referans olur; 125 MHz integer
+  mailbox yuvarlamasindan en fazla 4 ns kalir.
+- HOW/sample sureklilik kontrolu kartin fiziksel `16.367981 MHz` RF frekansini
+  kullanir. Periyodik nav-solve TOW'u receiver propagation/range-rate
+  degisiminden uretilmez; sample farki yalniz olay numarasini dogrular ve TOW
+  bilinen 200 ms transmit-time grid'ine snap edilir.
+- Donanimdaki kontrol filtresi PI loop'un kendisidir; ayri bir phase-IIR veya
+  D terimi yoktur. Yazilim `TDOP/GDOP`, formal clock-bias sigma, kullanilan
+  uydu sayisi, C/N0, chi-square/FDE ve Doppler velocity residual'ina gore
+  `acquire`, `precision`, `robust` ve `holdover` profillerini histerezisle
+  secer. Profil gecisinde `Kp`, `Ki`, `max-slew` ve v2.2 lock esikleri bir
+  sonraki mailbox commit'inde birlikte yakalanir; normal geciste integrator
+  korunur. Lock almak icin bes ardisik residual `64 ns` icinde olmalidir;
+  uretim release esigi tek seyrek WLS/capture sicrama pulse kaybettirmesin
+  diye `1.024 us` tutulur. Watchdog, quality holdover ve `20 ppm` slew clamp
+  buyuk arizalari ayri olarak sinirlar.
+- Yazilim filtresi PI'nin yerine gecmez. Yalnizca 5 Hz WLS clock-bias
+  olcumunde Doppler clock-drift prediction, bounded innovation ve aykiri
+  olcum reddi yapar. Ilk yerlesmede commit'ler coarse ve PPS invalid tutulur.
+  Periyodik background watchdog iki saniye yeni referans gelmezse cikis
+  validligini holdover ile kapatir; fakat ayni referans geri gelirse Doppler
+  prediction ve donanim PI state'i 30 saniyeye kadar korunur. Referans SVID
+  degisimi veya 30 saniyeyi asan bosluk coarse re-anchor yapar. PPS v2.2
+  holdover aktifken normal PI commit'ini uygulamadigi icin recovery'de butun
+  shadow word'ler once yazilir, holdover commit toggle'inin hemen oncesinde
+  birakilir ve ilk taze olcum PI'ya girer. Fiziksel PPS held rate ile
+  kesintisiz yurur; `STATUS.VALID` PI apply'dan yalniz bounded
+  synchronizer/commit-pipeline gecikmesi kadar once gorunebilir.
+- PPS v2.2 `LOOP_CONFIG` register'i `0x88` adresindedir. Eski v2.1 bitstream
+  algilanirsa yazilim bu register'a dokunmaz; dinamik Q2.46 `Kp/Ki/max-slew`
+  yazimi mevcut register'larla calismaya devam eder.
 - 125 MHz fiziksel kenar grid'i 8 ns'dir. Generated VCU118 ve Genesys2 top'lari
   `gps_pps` output'unu expose eder. VCU118 icin PPS PMOD1/J53.8 (`R29`),
   Genesys2 icin PMOD JC10 (`AK28`) pinine atanmistir. Board testinde
   Gray/PCLK capture pipeline sabit offset'i ve
   clock-tree/I/O gecikmesi olculup kalibre edilmelidir.
+
+### PPS Sentetik Dogrulama (2026-07-25)
+
+Python modeli ve Linux C testi ayni Q32/Q46 PI, kalite histerezisi, Doppler
+prediction, holdover ve lock politikasini kullanir. Ayrica donanim phase-IIR
+kullanilmaz. Test matrisi temiz/320 ns WLS noise, 650 ns zayif geometri,
+baslangicta 1.1 us noise sonra temiz sinyal, aralikli 900 ns noise burstleri,
+uydu kaybi ve geri gelmesi, 15 saniyelik state-korumali ve 30 saniye ustu
+coarse WLS kesintisi, Doppler kaybi, multipath
+basamagi, profil sicramalari, +18 ppm slew siniri ve +25 ppm sinir disi
+osilatoru kapsar.
+
+Monte Carlo sonucunda hedeflenen senaryolarin tamami lock/recovery sagladi.
+Normal kart-noise senaryosunda 50/50 kosu lock oldu ve 125 MHz edge
+quantization dahil bir saniyelik jitter p95 `13.62 ns` bulundu. Baslangicta
+yuksek noise sonra temiz sinyal senaryosunda 30/30, noise-burst senaryosunda
+30/30, iki uydu-kaybi araligi bulunan senaryoda 30/30 recovery goruldu.
+`+18 ppm` 30/30 yerlesirken `+25 ppm`, `20 ppm` clamp disinda oldugu icin
+0/10 lock uretti; yani saturation yanlis-valid olusturmadi. Bunlar sentetik
+loop/jitter sonuclaridir; mutlak UTC/GPS faz dogrulugu icin karttaki sabit
+capture/I/O offset'i ve gercek multipath halen osiloskop/time-interval olcumu
+gerektirir.
+
+### PPS Kart Dogrulamasi (2026-07-25, Genesys2)
+
+- Kartta okunan RTL surumu `0x00020200`; dinamik `LOOP_CONFIG=0x08800800`
+  mailbox'i ve diagnostic snapshot calisti.
+- Eski `16.368 MHz` zaman donusumu 6 saniyede yaklasik `6.97 us` hata
+  uretiyordu. Fiziksel `16.367981 MHz` donusumu ve 200 ms transmit-grid snap
+  sonrasinda 6 saniyelik mikro-saniye sawtooth kayboldu.
+- Fractional capture duzeltmesi kartta epoch'a gore `0..64 ns` uygulandi
+  (son deger 8 ns grid'ine yuvarlanir). Duzeltmeden onceki uzun lock
+  penceresinde internal commit residual'i yaklasik `20.9 ns` median mutlak ve
+  `62.8 ns` p95 idi. Duzeltmeden sonraki precision penceresinde median mutlak
+  residual yaklasik `17 ns`, RMS `26 ns` ve p95 yaklasik `55 ns` oldu.
+- Ilk kart yaziliminda iki saniyeyi asan normal coherent-WLS scheduling
+  bosluklari filtreyi coarse resetliyordu; bu PPS'in periyodik olarak
+  4--5 update invalid kalmasina yol acti. Esigi validlik watchdog'undan
+  ayirdiktan sonra `seq=10551 -> 10561` araliginda `pulse=2174 -> 2186`
+  ile yaklasik 12 saniyelik gercek kart boslugu goruldu. Buna ragmen
+  `mode=tracking`, `locked=1`, status `0x80f` ve PI integrator kesintisiz
+  kaldi; coarse commit veya faz basamagi olusmadi.
+- Her WLS commit'inin loglandigi `pps-fullrate` tanisinda `seq=16090..17631`
+  arasinda 1514 commit izlendi. Ilk lock'tan sonra coarse veya unlock olmadi.
+  `seq>=16250` icin 1355 locked residual'in median mutlak degeri `17.29 ns`,
+  RMS'i `34.17 ns`, p95'i `52.76 ns`, p99'u `67.24 ns` oldu. Bu sayilar
+  fiziksel PPS pin jitter'i degil, 5 Hz WLS commit residual'idir.
+- Ayni tanida quality'nin robust'a dustugu tek bir commit'te `750.93 ns`
+  residual goruldu ve bir sonraki 200 ms commit'te normale dondu. Robust
+  `1.024 us` release esigi gereksiz pulse kaybini onledi. Daha once precision
+  `512 ns` release ile gorulen tek kisa unlock nedeniyle uretim precision
+  esigi de `1.024 us` yapildi; acquisition kosulu bes ardisik `<=64 ns`
+  olarak kaldi. Son `pps-final` kart okumasinda `LOOP_CONFIG=0x05800800`,
+  `CONTROL=0x3`, valid/locked status `0x80f` goruldu ve kontrollu holdover
+  denemesinden sonra ilk normal commit ile control/valid geri geldi.
+- Bu `hw_phase`, 5 Hz WLS reference commit residual'idir ve dogrudan fiziksel
+  1PPS kenar jitter'i degildir. Ayni pencerede proportional rate terimi
+  yaklasik `9.6 ppb RMS` idi; sentetik 125 MHz edge modeli kart-noise
+  senaryosunda bir saniyelik jitter p95 `13.62 ns` veriyor. `15--20 ns`
+  fiziksel hedef makuldur fakat pin uzerinde scope/TIC ile GPS-disiplinli
+  harici referansa karsi olculmeden saglandi diye raporlanmamalidir.