docs(gps): document tracking quality and Doppler pipeline

hardware/external/gps/rtl/readme.md

@@ -1,3 +1,4 @@
+# GPS RTL
 
 Take `Ankasys_Pulpissimo_SoC/pulpissimo/rtl/gps_system/hdl` folder from Ankasys_Pulpissimo_SoC svn repo, it has these subfolders:
 
@@ -16,6 +17,93 @@ trck_src:
 acq_src:
 	acqusition top and instantiated sub ips hdl codes from Hilal & Ahmet's implementations.
 
+## 20 ms Tracking Measurement Mailbox
+
+Her tracking kanali, decode edilen her GPS L1 C/A navigation biti icin bir
+atomik olcum uretir. Veri yolu:
+
+```text
+1 ms prompt I/Q
+    -> tracking_measurement (20 ornek akumulasyonu ve snapshot)
+    -> tracking clock domaininde 20 ms sabit payload
+    -> her alan icin iki FF senkronizer
+    -> iki tam PCLK settle cevrimi
+    -> tracking_wrapper APB register bankasi
+    -> measurement flag/interrupt
+    -> bare-metal software
+```
+
+`trck_src/tracking_measurement.sv` bir bit boyunca su degerleri toplar:
+
+```text
+sum_i = sum(I_prompt)
+sum_q = sum(Q_prompt)
+wbp   = sum(I_prompt^2 + Q_prompt^2)
+M     = 20 adet 1 ms prompt ornegi
+```
+
+Prompt enerji karesi lock detector'daki mevcut multiplier sonucundan alinir;
+ayni is icin ikinci bir multiplier/DSP yolu acilmaz. Bit epoch'unda total
+carrier NCO frekansi Q7 formatinda, absolute sample, remaining-code phase,
+navigation bit ve 16-bit sequence degeriyle birlikte snapshot edilir. Payload
+bir sonraki bit olcumune kadar degismez.
+
+Bu arayuz bir event FIFO'su degildir. Kaynak veri en az bir 20 ms bit boyunca
+sabit kaldigi icin wrapper her multi-bit alani mevcut `double_ff_syn` yapisindan
+gecirir, senkronize `valid` rising edge'inden sonra iki tam PCLK cevrimi bekler
+ve butun bankayi tek seferde register eder. Measurement interrupt'i APB
+snapshot'tan bir PCLK sonra uretilir; software interrupt'a girdiginde veri ve
+status stabildir. Software yine de coherent read icin sequence degerini
+payload'dan once ve sonra okuyup esitligini kontrol eder.
+
+### APB registerlari
+
+| Offset | Alan | Aciklama |
+| ---: | --- | --- |
+| `0x50` | `MEASUREMENT_META` | `[31:24]=version(1)`, `[12:8]=M`, bit 2 lock, bit 1 NAV bit, bit 0 valid |
+| `0x54` | `MEASUREMENT_SEQUENCE` | 16-bit, her 20 ms olcumde artar |
+| `0x58` | `MEASUREMENT_CARRIER_Q7` | Signed total carrier NCO frekansi, Hz icin `/128` |
+| `0x5c` | `MEASUREMENT_ABS_SAMPLE` | Olcum epoch absolute sample |
+| `0x60` | `MEASUREMENT_REM_CODE_PHASE` | 26-bit remaining-code residue |
+| `0x64` | `MEASUREMENT_SUM_I` | Signed coherent prompt-I toplami |
+| `0x68` | `MEASUREMENT_SUM_Q` | Signed coherent prompt-Q toplami |
+| `0x6c` | `MEASUREMENT_WBP_LO` | Wideband power alt 32 bit |
+| `0x70` | `MEASUREMENT_WBP_HI` | Wideband power ust bitleri |
+
+`CONTROL_REG` bit 13 measurement interrupt enable, bit 14 measurement flag
+enable'dir. `STATUS_REG` bit 7 measurement flag'dir. Genel interrupt clear
+islemi bu flag'i de temizler.
+
+### Neden Doppler IIR RTL'de degil?
+
+IIR RTL'de de uygulanabilir; her kanal icin onceki Doppler state'i, signed
+coefficient multiply, rounding/saturation ve reacquisition reset kurali
+eklenmesi yeterlidir. Mevcut tasarimda bilerek software'de tutulur:
+
+- APB bankasi ham ve tekrar analiz edilebilir carrier olcumunu korur.
+- Filtre katsayisi hareket profiline gore bitstream almadan degistirilebilir.
+- C/N0, satellite state ve WLS zaten software'de hesaplanir.
+- Filtre veri/interrupt hizini azaltmaz; measurement yine 50 Hz'dir.
+- Kart testinde kesintisiz kosuda measurement `missed`, `invalid` ve event
+  overflow sayaclari sifir kalmistir; CPU veya CDC baskisi RTL filtresi
+  gerektirmemistir.
+
+RTL filtresi ancak bu ham register sozlesmesinin yaninda ikinci bir filtered
+alan istenirse, olcum tamamen donanim icinde tuketilecekse veya software
+latency/CPU butcesi kart testinde yetersiz kalirsa anlamli olur.
+
+### RTL dogrulama
+
+Questa testleri:
+
+```bash
+make -C hardware/external/gps/rtl/trck_src/tb test
+```
+
+Testler prompt enerjisini, 20-ornek akumulasyonunu, iki ard arda bit epoch'unu,
+20 ms hold davranisini, double-FF + settle + atomik APB capture'i ve
+interrupt/status-clear yolunu kontrol eder.
+
 
 ## SVN Revision
 svn info
@@ -45,4 +133,3 @@ Last Changed Author: ankaaa
 Last Changed Rev: 89
 Last Changed Date: 2025-07-08 14:20:14 +0300 (Tue, 08 Jul 2025)
 
-