gps/soc/software/gps_system/README.md

# GPS System Port Notes

Bu notlar GPS bare-metal yaziliminin VCU118 Rocket SoC portu ve interrupt debug sureci icin yazildi.

## Uygulama akisi ve dosya sinirlari

Firmware giris noktasi [gps_system.c](gps_system.c)'dir. `main()` surucu veya
ESKF matematigi icermez; fakat sistemlerin nasil baglandigini acikca gosterir.
ESKF enable/disable, GPS WLS sonucu, timestamp'li IMU girdisi, GPS'in fusion
olcumune donusumu ve ham/duzeltilmis lat-lon bu dosyada gorunur.
Main'in GPS/IMU/fusion arasinda tasidigi mesajlar ve yasam-dongusu bayraklari
`header/gps_system.h` icindeki `gps_system_state_t` tipindedir; uygulama veri
tipleri giris noktasi C dosyasinda tekrar tanimlanmaz.

```text
gps_system.c
    -> initialize GPS, IMU and optional ESKF
    -> wfi
    -> timestamped IMU queue -> navigation_fusion prediction
    -> GPS events -> coherent WLS -> gps_nav_solution_t
    -> valid GPS -> fusion_gps_measurement_t -> navigation_fusion update
    -> navigation_fusion_output_t -> corrected lat/lon publish
```

Kaynak ve public header agaci ayni modul sinirlarini izler:

```text
header/ + src/
  gps/          acquisition, tracking, nav epoch, WLS ve GPS interrupt state
  imu/          sensor secimi, kalibrasyon ve ortak imu_sample_t yonetimi
  drivers/imu/  yalniz cihaza ozel SPI/register/INT1 kodu
  fusion/       ESKF, motion/ZUPT, NIS ve delayed-measurement replay
  adapters/     GPS->fusion ve sensor-profile->fusion donusumleri
```

UART konum/status formatlamasi `adapters/gps_system_uart` icindedir; bu sayede
`gps_system.c` telemetry format string'leriyle sismez. Buna karsilik GPS WLS
sonucunun fusion olcumune cevrilip ESKF'ye teslim edilmesi bilincli olarak
`main()` icinde gorunur kalir.

GPS kaynaklari IMU veya ESKF header'i include etmez; IMU suruculeri de
GPS/fusion header'i include etmez. Ortak trap/PLIC dispatcher harici bir IRQ
numarasi ile callback kabul eder. `BSP_PMOD_IRQ -> imu_sensor_irq_handler`
baglantisini GPS icinde hard-code etmek yerine `main`, GPS init'inden sonra ve
IMU start'indan once kaydeder. GPS ve IMU girdileri yalniz `gps_system.c`
uzerinden `navigation_fusion` API'sine verilir; tip donusumleri `adapters/`
sinirinda kalir.

ESKF'nin public girisi `fusion/navigation_fusion.h`, sensor yonetiminin public
girisi `imu/imu_sensor.h`, GPS alicisinin public girisi `gps/gps_receiver.h`dir.
Yeni sensor eklemek icin yeni bir `drivers/imu` backend'i ve sensor profil
adapter'i eklenir; GPS veya ESKF cekirdegi degistirilmez.

ISR icinde WLS veya ESKF calismaz. IMU ISR'i ornegi olcum aninda timestamp'ler
ve raw kuyruga koyar. GPS ISR'leri acquisition/tracking olaylarini kaydeder.
`wfi` sonrasi foreground bu kuyruklari tuketir. WLS sirasinda yeni IMU
interrupt'lari gelebilecegi icin IMU kuyrugu WLS'den hem once hem sonra drain
edilir; GPS update'i WLS bitis zamaninda degil capture epoch'unda uygulanir.

## Generic IMU Mimarisi (TDK ve ST)

GPS/ESKF artik dogrudan bir sensor surucusune bagli degildir. Veri yolu:

```text
TDK ICM42688 -----\
                   -> imu_sensor -> imu_calibration -> imu_sample_t
ST LSM6DSOX ------/                                      |
                                                         v
GPS receiver -> WLS -> gps_nav_solution_t -> GPS adapter -> navigation_fusion
                                                          |
                                                          v
                                           motion/ZUPT + ESKF -> fused LLH
```

- `src/drivers/imu/tdk_icm42688.c`: TDK ICM42688'e ozel SPI, register, interrupt ve
  ham-veri donusumu.
- `src/drivers/imu/st_lsm6dsox.c`: STEVAL-MKI217V1 uzerindeki ST LSM6DSOX'e ozel SPI,
  register, INT1 data-ready interrupt ve ham-veri donusumu.
- `src/imu/imu_sensor.c`: ortak init/start/stop/IRQ/service/measurement arayuzu.
- `src/imu/imu_calibration.c`: markadan bagimsiz bias, 3x3 scale/cross-axis/mounting
  donusumu ve opsiyonel sicaklik katsayisi.
- `header/imu/imu_sample.h`: driver ve IMU yonetimi ile fusion arasindaki
  sensor-markasindan bagimsiz SI mesaj sozlesmesi.
- `src/adapters/imu_fusion_profile.c`: aktif sensorun karakteristigini ESKF
  process-noise/kalibrasyon esiklerine cevirir.

Firmware isletim sistemi kullanmaz. Yeni IMU katmani `malloc` cagirmadan sensor
kuyruklarini ve butun durumunu statik ayirir. Newlib ve formatli UART destegi
nedeniyle linker'da heap alani yine bulunur; yeni sensor kodu buna guvenmez.
Karttaki 1 MiB DTIM test icin genis tutulmustur; firmware tasarim butcesi
ilerideki 512 KiB DTIM hedefidir. `auto` build iki sensor surucusunu da icerir;
kesin sensor secimi kullanilmayan surucuyu linkten cikarir.

2026-07-13 tarihli `-Os` bare-metal link boyutlari:

| Secim | text | data | bss | Toplam DTIM image |
| --- | ---: | ---: | ---: | ---: |
| `tdk` | 67,256 | 2,496 | 205,160 | 274,912 bayt |
| `st` | 66,936 | 2,496 | 199,280 | 268,712 bayt |
| `auto` | 68,888 | 2,496 | 207,560 | 278,944 bayt |

En buyuk `auto` image 512 KiB DTIM'in yaklasik yuzde 53.2'sini kullanir; stack
ve ilerideki buffer'lar icin 245,344 bayt (yaklasik 239.6 KiB) adres alani
kalir. Linker bunun 16 KiB'ini varsayilan stack icin ayirir. 1 MiB test
konfigurasyonunda gorulen ek bosluk yeni statik buffer eklemek icin gerekce
sayilmamalidir. Host unit-test executable'i bu rakamlara dahil degildir.
`auto` konfigurasyonu ayrica `BSP_DTIM_SIZE=0x00080000` ile gercekten link
edilerek 512 KiB sinirinda dogrulanmistir.

### Bare-metal sensor secimi

ESKF/fusion varsayilan olarak aciktir. GPS-only firmware icin ana uygulama
akisini degistirmeden kapatilabilir:

```sh
make -C soc/software/gps_system GPS_ESKF_ENABLE=0
```

Bu durumda GPS acquisition/tracking/WLS ve ham lat-lon yayini calismaya devam
eder; IMU stream'i ve `navigation_fusion` baslatilmaz. UART startup satirinda
`eskf_enabled` ve gercek init sonucu olan `eskf_ready` ayri alanlardir.

Otomatik WHO_AM_I algilama varsayilandir:

```sh
make -C soc/software/gps_system IMU_SENSOR=auto
```

Otomatik secimde eslesen cihaz bulunana kadar yalniz read-only WHO_AM_I probe
yapilir. TDK ve ST build'leri acikca su sekilde secilebilir:

```sh
make -C soc/software/gps_system IMU_SENSOR=tdk \
  IMU_ODR_HZ=500 IMU_ACCEL_FS_G=4 IMU_GYRO_FS_DPS=250

make -C soc/software/gps_system IMU_SENSOR=st \
  IMU_ODR_HZ=50 GPS_NAV_SOLVE_TIMER_TICKS=10 \
  IMU_ACCEL_FS_G=2 IMU_GYRO_FS_DPS=250
```

`IMU_SENSOR=stm`, `st` seciminin alias'idir. `IMU_ODR_HZ=0`,
`IMU_ACCEL_FS_G=0` ve `IMU_GYRO_FS_DPS=0` aktif surucunun guvenli varsayilanini
secer. Bu ozellikle `auto` icin onemlidir; TDK ve ST'nin ortak bir ODR degeri
yoktur. Desteklenen ODR'ler TDK icin 25/50/100/200/500/1000 Hz, ST icin
52/104/208 Hz'dir.

`IMU_ODR_HZ` fiziksel data-ready hizini secer; ST icin `50` istegi gercek 52 Hz
ayarina eslenir. Her IMU ornegi kendi monotonik CLINT timestamp'i ile ESKF
tahminine girer. 19/20 ms gibi sabit bir `dt` varsayilmaz ve CPU yuku icin ham
ornek atlanmaz. Ileride ESKF orani dusurulecekse PX4'teki gibi delta-angle ve
delta-velocity biriktiren, coning/sculling bilgisini koruyan bir downsampler
kullanilmalidir.

GPS orani bundan bagimsizdir. `GPS_NAV_SOLVE_TIMER_TICKS=5/10/50` sirasiyla
100/200/1000 ms nav-solve periyodu verir. WLS sonucu gec gelse bile olcum kendi
capture timestamp'inde fixed-lag replay ile uygulanir; yalniz
`solution_valid=true` olan GPS cozumu fusion'a girer. GPS yokken IMU ESKF'nin
process-model tahminini surdurur, fakat filtre kendine sahte konum olcumu
vermez. Global origin yoksa LLH cikisi valid degildir; origin daha once
kurulduysa sonuc yardimsiz dead-reckoning'dir ve kovaryansi zamanla buyur.

NIS kapisi tek bir aykiri GPS'in ESKF'yi suruklemesini engeller. Ancak acilista
ilk GPS fix'i kotu olup sonraki tutarli fix'ler bu ilk noktadan onlarca metre
uzakta kalirsa, yalniz hard NIS rejection kullanmak filtreyi yanlis baslangica
kilitler. Fusion engine bu nedenle ardisik reddedilen position fix'lerinin
zamansal surekliligini izler. Son başarılı fusion'dan sonra yedi saniye timeout
dolmuşsa ve en az uc fix birbirinin devamı
ise ve platform IMU/GNSS hareket vetolariyla duragan kabul ediliyorsa yalniz
ESKF konumu ve konum kovaryansi son olcume yeniden ankrajlanir;
attitude, hiz ve IMU bias state'leri korunur, gecersiz hale gelen position
cross-covariance'lari sifirlanir. Tek aykiri fix bu yolu tetiklemez. Bu davranis
100/200/1000 ms GPS oranlarinda `gps_reacquisition_test.c` ile dogrulanir ve
level-2 fusion status satirinda `recoveries=` sayaci ile gozlenir.

TDK ve ST veri-hazir interrupt'i ile calisir ve ana dongu `wfi` kullanabilir.
Genesys2 son pin planinda ortak aktif sensor interrupt girişi `JB1/V29`
uzerinden wrapper'daki 3FF synchronizer'a, oradan PLIC device 11'e gider. ST
surucusu LSM6DSOX accel data-ready olayini INT1'e yonlendirir; ISR local CLINT
timestamp'ini basta alir, latched kaynagi temizler, ayni sample'in gyro ve
sicaklik alanlarini okuyup statik SPSC kuyruğa koyar. `imu_sensor_service()`
interrupt backend'lerde no-op'tur.

Standalone LSM6DSOX SPI okuma, stationary log ve `INT1 -> JB1 -> 3FF -> PLIC
11 -> C ISR` fiziksel yolu kartta dogrulanmistir. 2026-07-16 GPS + ST + ESKF
end-to-end stationary kosusunda 6531 interrupt/sample, 467 ESKF aktarimi ve
322 kabul edilen GPS update'i goruldu; read-fail, queue overflow, missed sample
ve GPS NIS reject sayilari sifir kaldi. Ayni logun yerlesmis son bolumunde 100
ham GPS fix'inin yatay RMS sacilimi 13.62 m, son 20 fused durumun yatay RMS
sacilimi 0.39 m oldu. Bu degerler survey referansina gore mutlak dogruluk degil,
sabit anten etrafindaki repeatability olcumudur. Yuksek ODR gerekirse sonraki
gelistirme sensor FIFO + sensor timestamp veya daha yuksek CPU butcesidir;
ortak IMU arayuzu ve ESKF bunun icin degismeyecektir.

Sensor ODR'si ile GPS nav-solve periyodu birbirinden bagimsizdir. Her IMU ve GPS
olcumu ayni local monotonic CPU tick domaininde kendi olcum zamaniyla tasinir;
ESKF olaylari timestamp sirasinda isler. TDK ve ST ISR timestamp'i data-ready
kenarini yakindan temsil eder. Daha kesin ve WLS/interrupt latency'sinden
bagimsiz yuksek-ODR zamanlama gerekirse sensor FIFO timestamp'i kullanilmalidir.

### Level-1 konum UART protokolu

Her gecerli GPS navigation epoch'unda ham WLS GPS konumu yayinlanir. ESKF
duzeltilmis konumu ise GPS epoch'undan bagimsiz olarak IMU ornek sayaci
uzerinden yayinlanir:

```text
[LOCATION] source=gps lat=... lon=... height=... gdop=... pdop=... hdop=... vdop=... tdop=... tracked=... used=...
[LOCATION] source=imu_corrected lat=... lon=... height=... gdop=... pdop=... hdop=... vdop=... tdop=... tracked=... used=...
```

`tracked`, donanimda calisan tracking kanal sayisini; `used`, ilgili WLS
cozumunde kullanilan uydu sayisini belirtir. ESKF henuz kalibrasyon/origin
asamasindaysa yalniz GPS satiri yayinlanir. Origin kurulduktan sonra GPS
reddedilse veya gecici olarak kesilse de corrected konum IMU ile ilerlemeye
devam eder.

Varsayilan corrected UART periyodu bes IMU ornegidir. 50 Hz sensor hedefinde
bu yaklasik 100 ms/10 Hz demektir. Bu bolucu yalniz UART logunu seyreltir;
sensor okuma ve ESKF prediction her IMU orneginde calismaya devam eder:

```sh
# Varsayilan: 20 ms x 5 ~= 100 ms
make -C soc/software/gps_system IMU_CORRECTED_PUBLISH_EVERY_N_SAMPLES=5

# 20 ms x 2 ~= 40 ms
make -C soc/software/gps_system IMU_CORRECTED_PUBLISH_EVERY_N_SAMPLES=2

# Parent software hedefi uzerinden ayni ayar
make -C soc/software gps-system GPS_SYSTEM_IMU_PUBLISH_EVERY_N_SAMPLES=5
```

Deger en az `1` olmalidir. Secilen bolucu startup satirinda
`publish_every=` alaniyla gorulur. Eski `[NAV] position` ve periyodik
`[FUSION] lat/lon` ayrintilari daha yuksek debug seviyesindedir; level 1
parser'inin ayni konumu birden fazla kez gormesi engellenir.

Desktop `location_plotter`, `source=gps` serisini mavi ve
`source=imu_corrected` serisini kirmizi cizer. Iki kaynak arasinda zigzag yol
cizmez; corrected veri varsa CEP/RMS analizi yalniz corrected seriyle yapilir.
Linux sentetik replay loglarindaki `source=trajectory` gerçek izi yeşil çizer.

### Kalibrasyon ve sicaklik politikasi

Uc farkli duzeltme birbirinden ayridir:

1. Sensorun fabrika trim'i ve datasheet sensitivity degerleri sensor
   surucusunde kullanilir.
2. Kalici, karta ozel bias/scale/eksen/sicaklik katsayilari ortak
   `imu_calibration_t` icinde uygulanabilir. TDK ve ST ayarlari
   `calibration_by_backend[]` icinde ayri profillerdir; `auto` secimi bir
   sensorun kalibrasyonunu digerine uygulayamaz. Varsayilan deger identity +
   sifir bias'tir; yani varsayilanda olcumu degistirmez.
3. Fusion engine acilista kart sessizken iki saniyelik ornek toplar. Anlik gyro
   bias'ini, ilk roll/pitch hizalamasini ve gravity yonundeki accel kalintisini
   tahmin eder. ESKF bundan sonra residual accel/gyro bias state'lerini izler.

Sicaklik GPS/IMU fusionunun calismasi icin zorunlu degildir. Kisa sureli ve
dar sicaklik araligindaki ilk testte sicaklik yalniz olculur ve mesajda
tasinir; ESKF denklemlerini etkilemez. Uzun sure, dis ortam veya sensorun
isinmasiyla bias degisimi gorulurse sicaklik katsayilari offline loglardan
cikarilip `temperature_compensation_enabled=true` ile etkinlestirilir. Katsayi
olmadan otomatik sicaklik duzeltmesi yapmak yanlis bias uretme riski tasir.

Portable kalibrasyon matematigi Linux'ta heap kullanmadan su testle dogrulanir:

```sh
make -C soc/software/gps_system/tests clean run
```

Bu test identity davranisini, bias + 3x3 donusumu, opsiyonel sicaklik
duzeltmesini ve singular matris reddini kontrol eder. Test executable'i host
icindir ve bare-metal firmware'e linklenmez.

## Donanim Adresleri ve IRQ Map

Generated DTS/RTL'e gore GPS IP adresleri:

| IP | Base address | PLIC source |
| --- | ---: | ---: |
| ACQ | `0x10020000` | `1` |
| TRCK0 | `0x10021000` | `2` |
| TRCK1 | `0x10022000` | `3` |
| TRCK2 | `0x10023000` | `4` |
| TRCK3 | `0x10024000` | `5` |
| TRCK4 | `0x10025000` | `6` |
| TRCK5 | `0x10026000` | `7` |
| TRCK6 | `0x10027000` | `8` |
| TRCK7 | `0x10028000` | `9` |
| TRCK8 | `0x10029000` | `10` |

Bu degerler `soc/software/bsp/include/bsp/soc.h` icinde BSP define olarak tutuluyor. GPS yazilimi `header/gps/gps_ip_defines.h` icinde bu BSP define'larini kullaniyor.

PLIC base:

```text
BSP_PLIC_BASE = 0x0c000000
priority      = base + 4 * source_id
pending       = base + 0x1000
enable hart0  = base + 0x2000
threshold     = base + 0x200000
claim/complete= base + 0x200004
```

`claim/complete` icin `+4` dogru. Generated TLPLIC 64-bit beat kullaniyor, claim/complete register'i threshold ile ayni beat'in upper 32-bit tarafinda.

## Yapilan Software Degisiklikleri

- GPS base adresleri ve IRQ line'lari eski SoC sabitlerinden BSP define'larina tasindi.
- Tracking IP sayisi 9'a cikarildi.
- `trck6_ip`, `trck7_ip`, `trck8_ip` ve bunlarin interrupt map'i eklendi.
- PLIC init eklendi:
  - `mtvec = gps_irq_handler`
  - PLIC threshold `0`
  - source `1..10` priority `1`
  - source `1..10` enable
  - `mie.MEIE` ve `mstatus.MIE` enable
- `gps_irq_handler()` PLIC claim ID'ye gore dispatch ediyor:
  - `1` -> ACQ ISR
  - `2..10` -> tracking index `irq_id - 2`
  - sonra PLIC complete yaziyor
- `gps_irq_handler` machine interrupt handler attribute ile derleniyor. ELF'te handler `mret` ile donuyor.
- `gps_irq_handler` ayrica 4-byte aligned ediliyor. `mtvec` base adresi 4-byte aligned olmak zorunda; RVC acik oldugu icin fonksiyon 2-byte aligned yerlesirse trap iki byte erken baslayabilir.
- `_start` basinda debug-load'dan kalan interrupt state'i temizleniyor:
  - `mie = 0`
  - `mstatus.MIE = 0`
- FPGA `gdb_load_and_run.gdb` script'i de `_start`a resume etmeden once eski debug oturumundan kalan `mie`, `mstatus.MIE`, CLINT `mtimecmp` ve stack pointer state'ini temizler. Bu, pending timer interrupt'in `_start` stack init'inden once handler'a girip stack ustu store fault uretmesini engeller.
- ACQ ISR pending clear bug'i duzeltildi:
  - Daha once ACQ sadece "acquired" dalinda pending clear ediyordu.
  - ACQ sonucu "not acquired" ise pending clear edilmiyordu.
  - Simdi ACQ pending set ise her iki durumda da clear ediliyor.
- `acq_start_loop` use-after-free bug'i duzeltildi:
  - ACQ ISR `assign_tracking()` sirasinda current acquisition node'unu listeden silebiliyor.
  - Loop WFI'dan sonra `iterator->next` okursa freed node dereference ediliyordu.
  - Simdi `next` pointer'i WFI'dan once aliniyor.

## PLIC Davranisi

Rocket-chip TLPLIC bu konfigde `LevelGateway` kullaniyor. Edge/level secen bir software mode register'i yok.

Generated/Scala davranisi:

```scala
io.plic.valid := io.interrupt && !inFlight
when (c || g.valid) { p := !c }
```

Sonuc:

- PLIC input'u PLIC clock'unda high gorurse pending setlenir.
- Pending bitleri software'den set edilebilir degil, read-only status gibi davranir.
- Software priority, enable, threshold yazar; claim okur; complete yazar.

Onemli debug notu: PLIC `claim` register okumasi side-effect'lidir. GDB ile `0x0c200004` okumak pending'i claim eder. Eger sonra complete yazilmazsa Rocket `LevelGateway` `inFlight` kalabilir ve ayni source'tan sonraki interruptlar bloklanir. Debug yaparken durum okumak icin claim register'ini okumayin.

Eger GDB ile claim yanlislikla okunduysa toparlama:

```gdb
set *(unsigned int*)0x10020000 = (*(unsigned int*)0x10020000 | 0x2)
set *(unsigned int*)0x0c200004 = 1
```

Ilk satir ACQ pending clear bitini yazar. Ikinci satir PLIC source 1 complete yazar.

## GDB Ile Dogrulanan Durum

Clean load sonrasi `acq_intr_handler_0` breakpoint'i ile gorulen durum:

```text
mcause = 0x800000000000000b   // machine external interrupt
mepc   = 0x80000e98           // WFI sonrasi
PLIC enable = 0x7fe           // source 1..10 enable
ACQ ctrl = 0x0c               // intr enable + internal pending
acq_interrupt_flag = 1
```

Dispatch sonrasi, PLIC complete oncesi:

```text
PLIC pending = 0
ACQ ctrl = 0x04               // internal pending clear, interrupt enable duruyor
acq_interrupt_flag = 1
```

PLIC complete sonrasi:

```text
PLIC pending = 0
ACQ ctrl = 0x04
```

Bu, ACQ interrupt hattinin PLIC tarafindan goruldugunu, handler'in calistigini, IP pending clear edildigini ve PLIC complete sirasinin dogru oldugunu gosteriyor.

## Mevcut Son Durum

Interrupt path artik calisiyor. Son GDB kosusunda program tekrar `acq_start_loop` icinde goruldu:

```text
pc = 0x80000e98
ACQ ctrl = 0x04
ACQ status = 0x2
PRN = 18
PLIC pending = 0
acq_interrupt_flag = 1
trck_interrupt_flag = 0
```

Bu durumda stuck sebebi interrupt degil. ACQ status bit0 `GPS_ACQ_STATUS_POS` set olmadigi icin `assign_tracking()` calismiyor ve tracking'e gecilmiyor. Yani sonraki debug konusu ACQ sonuc/status semantics'i veya RF/input tarafidir.

RF data verildikten sonra gorulen `unexpected trap mcause = 5` icin ek debug:

```text
mcause = 5                 // load access fault
mepc   = acq_start_loop + lw a1,0(s0)
mtval  = 0x2
```

Bu, acquisition linked-list iterator'unun gecersiz/freed node'a donustugunu gosterdi. Sebep `acq_start_loop` icinde WFI'dan sonra current node'un `next` alaninin okunmasiydi; ayni node ACQ ISR icinde silinebiliyor. Fix: `next` pointer'i ACQ start/WFI oncesinde saklandi.

Ayni debug sirasinda ikinci bir trap sebebi bulundu:

```text
gps_irq_handler = 0x...13c6
mtvec readback  = 0x...13c4
```

`mtvec` base 4-byte aligned oldugu icin handler 2-byte aligned adrese yerlesince trap iki byte erken basliyordu. Fix: `GPS_IRQ_HANDLER_ATTR` icine `aligned(4)` eklendi. Son dogrulamada:

```text
mtvec = 0x800013c8
pc    = acq_start_loop
mcause= 0x800000000000000b
mtval = 0
trck_interrupt_flag = 1
```

Bu kosuda `mcause=5` tekrar etmedi.

## Build ve Debug Komutlari

Build:

```sh
make -C /home/ankaoc/Desktop/rocket/rocket-chip/soc/software/gps_system \
  BUILD_DIR=/home/ankaoc/Desktop/rocket/rocket-chip/soc/out/software/gps_system \
  clean all
```

OpenOCD:

```sh
make -C /home/ankaoc/Desktop/rocket/rocket-chip fpga-debug-openocd
```

ELF'i RAM'e yukleyip calistirma:

```sh
/tools/toolchains/rvtc-medany/bin/riscv64-unknown-elf-gdb \
  -q /home/ankaoc/Desktop/rocket/rocket-chip/soc/out/software/gps_system/gps_system.elf \
  -ex "target extended-remote :3333" \
  -ex "monitor reset halt" \
  -ex "load" \
  -ex "set \$pc = _start" \
  -ex "monitor resume" \
  -ex "detach" \
  -ex "quit"
```

Durum okumak icin claim register'ini okumadan:

```gdb
target remote :3333
monitor halt
p/x $pc
p/x $mtvec
p/x $mie
p/x $mstatus
p/x $mcause
p/x $mepc
p/x *(unsigned int*)0x0c001000
p/x *(unsigned int*)0x0c002000
p/x *(unsigned int*)0x0c200000
x/16wx 0x10020000
x/20wx 0x10021000
```

Tekrar: `0x0c200004` claim/complete register'idir. Debug read yapmayin; okuma pending'i claim eder.

## Continuous Acquisition ve Parametric ACQ Update

Bu bolum continuous/background acquisition ve parametrik acquisition engine destegi icin yapilan son firmware degisikliklerini ozetler.

### Analiz Edilen Noktalar

- Mevcut firmware acquisition'i `acq_start_loop()` icinde calistiriyor ve 4 veya daha fazla tracking uydusu varsa yeni acquisition baslatmiyordu.
- `calculate_position()` sadece tracking sayisi 4'un altina dustugunde acquisition'i tekrar tetikliyordu.
- ACQ ISR daha once acquisition sonucunu ISR icinde isliyor, linked-list degistiriyor, tracking handoff yapiyor ve debug basiyordu.
- TRCK ISR de linked-list/node islemleri, subframe parse ve cok fazla debug isini ISR icinde yapabiliyordu.
- Navigation tarafinda tracking measurement verisinin taze olup olmadigi tick/epoch ile net kontrol edilmiyordu.
- XLSX register dokumanlari incelendi:
  - `GPS_ACQ_APB_regmap.xlsx`
  - `GPS_TRCK_APB_regmap.xlsx`
- ACQ ve TRCK register offset'leri firmware struct'lari ile karsilastirildi.

### Degisen Dosyalar

- `header/gps/gps_ip_defines.h`
- `header/gps/gps_macros.h`
- `header/gps/gps_interrupt_handlers.h`
- `header/gps/linked_list.h`
- `src/gps/gps_ip.c`
- `src/gps/gps_interrupt_handlers.c`
- `src/gps/linked_list.c`
- `gps_system.c` (onceki `gps_test.c` giris noktasi)

### Parametric Acquisition Engine Destegi

- Acquisition engine sayisi tek noktadan ayarlanabilir hale getirildi:

```c
ACQ_ENGINE_COUNT
```

- Varsayilan olarak `ACQ_ENGINE_COUNT`, BSP tarafindaki `BSP_GPS_ACQ_COUNT` degerinden gelir.
- BSP bu define'i vermiyorsa firmware default olarak 1 ACQ engine kullanir.
- ACQ base address ve interrupt line artik index uzerinden hesaplanir:

```c
GPS_ACQ_IP_BASE_ADDR(index)
GPS_ACQ_INTR_LINE(index)
```

- ACQ IP pointer ve IRQ tablolarina gecildi:

```c
acq_ips[GPS_ACQ_IP_COUNT]
acq_ips_intr_lines[GPS_ACQ_IP_COUNT]
```

- Mevcut donanim haritasinda sadece bir ACQ engine var:
  - ACQ base: `0x10020000`
  - TRCK0 base: `0x10021000`
- Bu nedenle birden fazla ACQ engine acilirsa ACQ register window'larinin tracking register window'lari ile cakismamasi icin compile-time guard eklendi.
- Multi-ACQ icin donanim/BSP tarafinda non-overlapping ACQ base/stride/IRQ bilgisi verilmesi gerekir.

### Continuous Background Acquisition

- `acq_start_loop()` artik eski blocking acquisition dongusunu calistirmiyor.
- Main loop su sekilde calisir:

```c
wfi();
gps_background_task();
calculate_position();
```

- Acquisition scheduling RISC-V timer/systick tarafindan tetiklenir.
- Tracking real-time oncelikli kalir; acquisition sadece background task icinde yeni is atar.
- Yeni scheduler:
  - bos ACQ engine arar,
  - aktif tracking uydularini tekrar acquire etmeye calismaz,
  - herhangi bir tracking IP tarafindan busy/allocated gorulen PRN'leri ACQ listesinden temizler,
  - `ACQUIRING`, `ACQUIRED`, `TRACKING` durumlarindaki PRN'leri skip eder,
  - kayip veya stale PRN'leri tekrar listeye alabilir,
  - acquisition retry icin tick tabanli delay uygular.

### Satellite State Model

Her PRN icin state tutulur:

```c
GPS_SAT_NOT_SEEN
GPS_SAT_ACQUIRING
GPS_SAT_ACQUIRED
GPS_SAT_TRACKING
GPS_SAT_LOST
GPS_SAT_STALE
```

Bu state modeli acquisition scheduler, tracking handoff ve stale measurement temizligi icin kullanilir.

PRN register degeri bu donanimda 0..31 hardware index olarak kullanilir. Bu nedenle firmware `PRN_NUMBER` alanina 0..31 yazar; 0 invalid kabul edilmez.

### ISR Safety Degisiklikleri

- ACQ ve TRCK ISR'lari sade hale getirildi.
- ISR icinde artik agir is yapilmiyor.
- ISR akisi:
  - status/control register snapshot al,
  - gerekli data register'larini oku,
  - interrupt clear yap,
  - fixed-size event queue'ya event push et,
  - cik.
- Linked-list mutation, acquisition-to-tracking handoff, subframe parse ve debug print gibi agir isler deferred/main context'e tasindi.
- Fixed-size event queue eklendi:

```c
GPS_EVENT_QUEUE_SIZE
```

- Queue overflow sayaci eklendi ve overflow debug seviyesinde raporlanir.
- ACQ event'i queue doluysa shadow result ile korunur; tracking event overflow'u sayilir.
- PLIC dispatch artik ACQ interrupt source'larini `acq_ips_intr_lines[]` tablosundan arar.
- Tracking status register'inda `INTR_PEND` set kalir fakat PLIC event'i software'e ulasmazsa, `gps_background_task()` icindeki hafif poll fallback ayni ISR snapshot yolunu cagirir. Bu fallback sadece register snapshot/clear ve fixed queue push yapar; subframe parse ve navigation islemleri yine deferred context'te kalir.

### Systick / Timer Degisiklikleri

- Machine timer interrupt path eklendi.
- `gps_systick_ticks` global tick counter olarak kullanilir.
- Systick acquisition scheduler'i periyodik olarak uyandirir.
- Timer interrupt sadece tick arttirir, scheduler pending flag set eder ve bir sonraki compare degerini programlar.
- Mevcut ayar `GPS_SYSTICK_HZ=20u`'dir. CLINT timebase board build'inden gelir:
  Genesys2'de 50 MHz SoC clock `/100` bolucu nedeniyle `500000 Hz`, VCU118'de
  100 MHz SoC clock nedeniyle `1000000 Hz` kullanilir. Her iki kartta machine
  timer interval'i gercek zamanda 50 ms'dir.
- Systick sadece bos acquisition engine'e yeni is atamak ve background maintenance yapmak icin kullanilir.
- Acquisition completion/stop systick timeout ile yapilmaz; ACQ engine normalde sadece ACQ-end interrupt ile tamamlanir.
- `GPS_ACQ_STUCK_WARN_TICKS` diagnostic-only stuck-busy warning icindir. ACQ'yi stop/restart etmez; sadece software-owned ACQ engine beklenenden uzun busy kalirsa `rf_clk`, `sample_align_i` veya `acq_end` yolunu kontrol etmek icin log basar.
- Ortak AFE yalniz `gps_startup_initialization()` sirasinda bir kez baslatilir. Per-PRN `acq_start()` AFE fazina dokunmadan sadece pending clear, PRN ve ACQ start pulse islemlerini yapar.
- Software engine'i idle gorurken ACQ donanimi busy ise scheduler yeni PRN/start yazmaz; donanim idle olana kadar yeni aramayi erteler.
- ACQ sonucu bir tracking kanalina verildiginde `tracking_allocated` software rezervasyonu donanim `BUSY` biti gec gorundu diye geri alinmaz. Rezervasyon normal tracking drop/stop interrupt'i ile serbest birakilir.

### Tracking Freshness ve Stale Data Koruma

- Tracking linked-list node'una freshness alanlari eklendi:

```c
gps_last_measurement_tick
gps_measurement_valid
gps_nav_solve_sequence
gps_last_nav_solve_pps_counter
```

- Navigation input'u hazir kabul edilmeden once su kontroller yapilir:
  - measurement valid mi,
  - lock valid mi,
  - measurement tick'i stale timeout icinde mi.
- Stale timeout:

```c
GPS_TRK_MEASUREMENT_STALE_TICKS
```

- Tracking channel lock kaybederse:
  - measurement invalid/stale yapilir,
  - PRN `GPS_SAT_LOST` durumuna alinir,
  - tracking slot bosaltilir,
  - PRN tekrar acquisition listesine eklenebilir.
- Position calculation artik stale veya unlock olmus measurement kullanmaz.
- Subframe 1'den gelen 6-bit `svhlth` alani `000000` degilse kanal tracking/nav-bit guncellemesine devam eder fakat navigation snapshot'a alinmaz. Boylece broadcast unhealthy olarak isaretlenen SV konum hesabinda kullanilmaz.
- Navigation hesaplamasi icin interrupt disable suresi kisaltildi; sadece snapshot/promote bolumleri korunuyor.

### Nav Bits + Nav Solve Akisi

- Tracking kanali ilk basladiginda nav-bits mode kullanilir:
  - `NAV_BITS_INTR_EN=1`
  - `NAV_BITS_FLAG_EN=1`
  - `NAV_SOLVE_EN=1`
  - `NAV_SOLVE_INTR_EN=0`
  - `NAV_SOLVE_FLAG_EN=0`
- Firmware nav bit interrupt'lari ile subframe verisini surekli toplar.
- Bir tracking kanali ancak IODC/IODE degerleri eslesen subframe 1, 2 ve 3 seti atomik olarak commit edildikten sonra navigation-ready olur. Subframe 4 ve 5 ilk fix'i bloke etmez; page 18 iyonosfer/UTC ve almanak verisi arka planda toplanmaya devam eder.
- En az 4 satellite icin tutarli ephemeris commit edilince nav-bit snapshot'i yalniz ephemeris uygunlugunu ve kullanilacak kanallari belirler; bu snapshot'tan pozisyon hesaplanmaz.
- Tutarlı ephemerisi hazir olan tracking kanallarinda nav-solve akisi etkinlestirilir:
  - nav bits interrupt/flag acik kalir,
  - `NAV_SOLVE_INTR_EN=1`,
  - `NAV_SOLVE_FLAG_EN=1`.
- Ilk pozisyon dahil butun pozisyon hesaplari, kanallardan senkron nav-solve tick ve `ABS_SAMPLE` geldikten sonra olusturulan coherent nav-solve snapshot'i ile yapilir.
- Nav-bit ve nav-solve handler'lari canli ephemeris deposunu ortak kullansa da her kabul edilen nav-solve event'i corrected `ABS_SAMPLE`, TOW ve o anda commit edilmis ephemerisin tam kopyasini aktif epoch snapshot'ina birlikte yazar. WLS daha sonra canli node listesinden ephemeris okumaz; araya giren nav-bit interrupt'i eski olcumle yeni ephemerisi karistiramaz.
- Coherent snapshot olusturulurken 32-bit raw `ABS_SAMPLE` degerleri en yeni sample etrafinda modulo fark ile unwrap edilir. Sayac wrap sinirinin iki tarafindaki uydular ayni pseudorange hesabinda kullanilabilir.
- Nav bits akisi ilk tutarli subframe 1..3 seti commit edildikten sonra kapatilmaz. Boylece yeni subframe 1..3 verisi ephemerisi, subframe 4 page 18 verisi iyonosfer/UTC parametrelerini guncel tutar.
- Nav-solve interrupt'lari acilmadan once TOW, parity kontrolunden gecen nav-bit HOW alanindan kurulur. Her yeni HOW'un GPS zaman farki receiver sample-counter farkiyla karsilastirilir; tek bir sureksiz HOW saglikli anchor'i degistiremez. Iki ardışık aday kendi aralarinda tutarliysa kanal reset gerektirmeden yeni zaman cizgisine gecerek toparlanir. Subframe 1 gelmeden onceki gecici hafta, ilk gecerli WN ile atomik olarak guncellenir.
- Subframe 1..3 ham kelimeleri once staging alaninda biriktirilir. IODC'nin alt 8 biti ile iki IODE alani eslesen tam set olusmadan canli ephemeris degistirilmez; yayin guncellemesi sirasinda eski/yeni ephemeris alanlari karismaz.
- Subframe 1 `toc` alani parity bitleri disarida birakilarak 16 bit okunur ve `2^4` ile olceklenir.
- Subframe 4 page 18 henuz alinmadiysa iyonosfer duzeltmesi uygulanmaz. Page 18 hazir oldugunda her navigation solve tek bir `ionoutc` kopyasi kullanir.
- Klobuchar gecikmesi WLS'nin receiver ECEF, azimut ve elevasyon hesabindan uretilir. Ilk unseeded iteration iyonosfersizdir; yaklasik receiver konumu olustuktan sonraki iteration'larda gecikme gozlenen pseudorange'dan cikarilir.
- Bundan sonra periyodik pozisyon hesaplamasi nav-solve interrupt'lari ile tetiklenir. RTL `subframe_ready` sonrasinda COUNT durumuna girer ve `NAV_SOLVE_TIMER=N` icin N adet navigation `bit_valid` darbesi sayar. Her navigation biti 20 ms oldugu icin periyot `N * 20 ms`'dir; firmware `GPS_NAV_SOLVE_TIMER_TICKS` build ayarini `gps_startup_initialization()` fonksiyonuna verir.
- Bu siralama onemlidir: RTL `nav_solve_timer` sayaci `NAV_SOLVE_EN` ve ilk gecerli `subframe_ready` ile baslar. `NAV_SOLVE_EN` nav-bit asamasinda acik tutulur; tutarli subframe 1..3 ephemerisi commit edilene kadar yalniz nav-solve interrupt/flag kapali kalir. Timer COUNT durumuna girdikten sonra sonraki subframe darbeleri sayaci sifirlamaz veya yeniden fazlamaz.
- Tracking kanallari farkli zamanlarda lock olabilir ve ilk gecerli subframe'lerini 6 saniyenin farkli katlarinda gorebilir. Timer bu nedenle ilk subframe'in HOW alanindaki 17-bit Z-count degerini kullanarak `Z_COUNT * 300 mod NAV_SOLVE_TIMER` baslangic fazini hesaplar. Hesap ALIGN durumunda 26 PCLK cevriminde ard arda modulo ile yapilir; 20 ms'lik ilk navigation bitinden cok once tamamlanir. RTL ayni GPS haftasi icinde keyfi pozitif `N` degerlerini hizalayabilir; firmware ise hafta rollover'i oncesinden aktif kalan kanallarla rollover sonrasinda katilan kanallarin da ayni fazda kalmasi icin `30240000 mod N == 0` kosulunu compile time'da zorunlu tutar. Ornegin `N=40`, `N=100`, `N=125`, `N=150`, `N=200` ve `N=300` gecerlidir; kosulu saglamayan build acik bir `#error` ile durur.
- Initial position sonrasinda subframe'lerini tamamlayan yeni tracking kanallarinda da nav bits acik tutularak nav-solve otomatik etkinlestirilir.
- Coherence kontrolu sadece software systick ile yapilmaz; periodic snapshot icin tracking node'da saklanan nav-solve interrupt sonrasi raw `ABS_SAMPLE` kullanilir. `GPS_NAV_ABS_SAMPLE_SYNC_WINDOW_MS=25` oldugu icin 4 satellite measurement'i 25 ms'den fazla ayriksa navigation solve calistirilmaz. Bu pencere interrupt skew'den cok uydu path delay farkini kapsamak icindir: 20 ms yaklasik 6000 km, 25 ms yaklasik 7500 km pseudorange farkina denk gelir. 25 ms, dusuk-elevation uydu geometrisi ve tracking jitter icin pay birakir ama 50 ms kadar gevsek degildir.
- Interrupt'lar epoch'a GPS TOW ile degil, butun kanallarda ortak olan 64-bit PPS capture counter ile atanir. Ilk olcum sabit expected maskeyi ve 30 ms bounded holdoff'u baslatir. 25 ms pencereye giren kanallar ayni fiziksel epoch'a katilir; yarim nav periyodundan uzaktaki eski/yeni capture'lar stale veya yeni epoch olarak siniflanir. Boylece bozuk bir gelecek HOW degeri epoch assembler'i kilitleyemez.
- Yalniz frozen expected maskenin tamami geldiginde snapshot sabit boyutlu iki buffer arasinda immutable olarak foreground'a devredilir. 30 ms holdoff dolan eksik epoch ve daha yeni counter geldigi anda yarim kalan eski epoch butunuyle discard edilir. Hardware mailbox birden fazla pulse'u kacirdiysa sequence/counter farki tutarli olan en yeni gercek olcum kabul edilir; elde olmayan ara olcumler sentetik olarak uretilmez. Sequence ile 64-bit capture counter uyusmazsa event yalniz rebase icin kullanilir ve epoch'a girmez.
- Immutable snapshot icindeki butun adaylar heap kullanmayan selector ile ikili TOW ve modulo-32-bit `ABS_SAMPLE` coherence kontrolunden gecirilir. En buyuk coherent kume frozen aday sayisindan bir eksik bile olsa tum epoch reddedilir; WLS icin alt kumeye dusulmez. Tamamlanan snapshot WLS sonucu basarili veya basarisiz olsa da yalniz bir kez denenir.
- Navigation snapshot ayni SVID/PRN'i ikinci kez kabul etmez. Ayni uydu iki tracking IP uzerinden frozen ready maskeye girerse aday sayisi maskeyle uyusmayacagi icin tum epoch reddedilir; ayni uydu iki kez WLS'e giremez.
- UART debug satirindaki `coherent_nav=` degeri, o anda ayni nav-solve penceresinde kullanilabilir kanal sayisini gosterir. 600 ms pozisyon gelmiyorsa `busy channels`, `ready channels` ve `coherent_nav` birlikte kontrol edilmelidir.
- Tracking ISR event queue dolarsa, her tracking IP icin son event shadow buffer'a alinir. Shadow overwrite sayaci WARN olarak loglanir; bu log gorulurse CPU nav hesaplamasi veya UART debug cikisi tracking interrupt isleme hizini geciktiriyor olabilir.
- Bir tracking kanali shadow buffer'a dustukten sonra shadow main context tarafindan tuketilene kadar ayni kanalin yeni event'leri tekrar ana queue'ya alinmaz; en yeni shadow snapshot'i korunur. Boylece daha yeni queue event'inin daha eski shadow event'inden once islenmesi ve raw sample zamaninin geriye gitmesi engellenir.
- Tracking nav-solve interrupt'lari ayni GPS epoch'unda birbirine cok yakin gelebilir. External interrupt handler bu yuzden PLIC'te bekleyen farkli GPS source ID'lerini tek ISR girisinde bounded olarak drain eder. Ayni source ID tekrar claim edilirse handler durur; bu durum level interrupt clear'in henuz donanima yansimadigini gosterir ve `PLIC repeated source while draining` WARN sayaci ile raporlanir.
- Normal nav-bit interrupt'larinda mevcut tracking node tekrar insert edilmeye calisilmaz. Bu nedenle `requested node already exists` UART spam'i normal akista gorulmemelidir; per-subframe `nav bits` logu `TRACE` seviyesine alinmistir.
- Nav solve mode'da `NAV_SOLVE_TIMER`, subframe fazindan sonra kac adet 20 ms navigation biti sayilacagini; dolayisiyla ABS_SAMPLE latch ve interrupt epoch'unu belirler. Her islenen event'te TOW `NAV_SOLVE_TIMER * 20 ms` artirilir ve GPS hafta sinirinda normalize edilir. Raw `ABS_SAMPLE` TOW artisini belirlemez; yalniz ayni nav-solve epoch'undan gelen kanallari secmek ve pseudorange olcumunu olusturmak icin kullanilir. Pseudorange hesabina giden `gps_ephems.abs_sample` receiver sample'in corrected double halidir.
- `hardware/external/gps/rtl/gps_timer/tb/nav_solve_timer_tb.sv`, RTL'nin ayni hafta icindeki genel fazlama davranisini bir kanalin digerinden tam bir subframe gec basladigi `N=40`, `N=37`, `N=512` ve `N=1` durumlariyla kontrol eder. Firmware build kurali bunlardan GPS haftasindaki `30240000` navigation biti tam bolmeyen degerleri sistem konfigurasyonu olarak reddeder.
- Tracking wrapper'daki `REM_CODE_PHASE_REG` donanimda IEEE-754 double degildir. RTL'de code NCO phase accumulator 46 bittir; software'e expose edilen kisim `rem_code_ph[45:20]` yani 26-bit integer residue'dur ve APB `PRDATA[25:0]` alanina zero-extend edilerek verilir. Bu yuzden firmware bu register'i `uint32_t` okur; `uint64_t` veya `double*` olarak MMIO okumak iki 32-bit APB read uretir ve register map ile uyumlu degildir.
- Navigation icin kullanilan corrected receiver sample formulu:

```c
corrected_abs_sample = (double)ABS_SAMPLE - ((double)REM_CODE_PHASE_REG / CODE_FREQ_BASIS);
```

  `REM_CODE_PHASE_REG` pozitif crossing residue olarak yakalandigi icin isaret eksi kullanilir: code boundary, raw `ABS_SAMPLE` sample kenarindan `REM_CODE_PHASE_REG / CODE_FREQ_BASIS` sample kadar once gerceklesmistir. Raw `ABS_SAMPLE` yine `gps_last_nav_solve_abs_sample` icinde saklanir ve wrap/coherence delta hesaplari icin kullanilir; corrected double sadece pseudorange/navigation hesabina girer.
- Least-squares `A` matrisi satirlari geometric range ile normalize edilir. Pseudorange ile normalize etmek DOP ve pozisyon hesaplamasini bozabilir.
- WLS weight artik yalniz elevation'a bagli degildir. Subframe 1'den parse edilen URA/SVA index nominal metre degerine cevrilir ve her satellite icin asagidaki model kullanilir:

```text
variance = ura_sigma_m^2 + (3.0 m / sin(max(elevation, 10 deg)))^2
weight   = 1 / variance
```

  Ilk receiver konumu henuz yoksa ilk iteration URA-only weight kullanir. Azimut/elevation olustuktan sonra URA ve elevation birlikte kullanilir. Relative weight'ler her iteration en buyuk weight `1.0` olacak sekilde normalize edilir. URA index 15 accuracy prediction saglamadigi veya `svhlth` alani sifir olmadigi icin uygun olmayan satellite navigation-ready snapshot'a alinmaz.
- Formuldeki `3.0 m`, GPS yayini veya ICD tarafindan verilen bir deger degildir. Mevcut donanim canli signal-quality olcumu saglamadigi icin secilmis, konservatif ve tune edilmesi gereken zenith residual sigma varsayimidir. Elevation 90 derecede `3 m`, 30 derecede `6 m`, 10 derece ve altinda yaklasik `17.3 m` sigma uretir.
- Tracking donanimindan ileride C/N0 veya SNR geldiginde ham register degeri dogrudan `3.0` yerine yazilmamalidir. Once gercek pseudorange/code tracking hatasina karsilik gelen metre cinsinden `sigma_cn0` degerine kalibre edilmelidir. Hedef measurement modeli asagidaki yapida olmalidir:

```text
variance = ura_sigma_m^2 + sigma_cn0_m^2 + sigma_residual_atmosphere_m^2
weight   = 1 / variance
```

  Kalibre edilmis C/N0 modeli dusuk-elevation signal degradation ve multipath etkisini yeterince temsil ederse mevcut `3 m / sin(elevation)` terimi kaldirilabilir. Bunlari tam temsil etmiyorsa ayni terim daha kucuk bir residual-atmosphere tabani olarak korunur; iki model ayni belirsizligi iki kez saymamalidir. EKF eklendiginde ayni toplam variance satellite measurement covariance `R` icinde kullanilmalidir.
- Konum cozumu URA/elevation agirlikli WLS kullanmaya devam eder; raporlanan DOP degerleri ise bu normalize relative weight'lerden uretilmez. GDOP/PDOP/TDOP agirliksiz geometri matrisinden, HDOP/VDOP de ayni covariance ECEF'ten lokal ENU eksenlerine donduruldukten sonra hesaplanir. Boylece loglanan degerler klasik geometrik DOP anlamini korur.
- Troposfer correction her satellite icin bagimsiz hesaplanir ve dort satellite ile de aktiftir. Ilk konumsuz iteration sabit baslangic correction'i kullanir; receiver konumu olustuktan sonra elevation ve metre cinsinden receiver height modele verilir. Model kilometre bekledigi icin height donusumu yapilir ve dusuk elevation'da gecerli olabilen 5 m uzeri delay degerleri artik keyfi olarak sifirlanmaz.
- Troposfer modelindeki mevcut `1013 hPa` basinc, `293 K` sicaklik ve `%50` bagil nem degerleri gecici fallback sabitleridir. Ileride gercek barometre/basinc, sicaklik ve nem sensorleri sisteme baglanacak; model her navigation cozumunde son gecerli sensor snapshot'indan beslenecektir. Sensor arayuzu modele basinci `hPa`, sicakligi `K` ve bagil nemi `%` olarak vermeli; birim donusumleri sensor surucusu ile navigation modeli arasinda tek bir yerde yapilmalidir. Sensor verisi henuz hazir degilse veya kullanilamiyorsa mevcut sabit atmosfer degerleriyle correction devam edecektir.
- Least-squares veya DOP inverse matrisi singular/invalid olursa firmware artik `print_mat(NULL)` veya NULL matrix uzerinden load fault uretmez. Bu epoch sessizce skip edilir; ayrinti sadece `DEBUG_TRACE` seviyesinde gorulur ve onceki gecerli position bozularak 20 km ziplamaya zorlanmaz.

### Navigation Veri Yolu Notlari

- Azimut ve elevasyon hesaplari aktif olarak elevation/URA weight ve Klobuchar correction icin kullanilir. `az` ve `el` heap matrisleri de doldurulur fakat mevcut solver bu matrisleri daha sonra okumaz. Satellite bazli metric arayuzu eklendiginde bu degerler matris yerine kalici metric kaydina tasinabilir.
- `rho0`/`range_t` eski range ve range-rate yolundan kalmistir. `computeRange()` icinde `rho` alanlarini dolduran eski blok kapali oldugu icin mevcut position-only akista `rho0` allocate edilir fakat sonuc uretmez.
- `velocities` matrisi gelecekte Doppler/receiver-velocity veya EKF icin anlamlidir. Mevcut `satpos()` velocity hesaplamadigi ve aktif `computeRange()` bu matrise yazmadigi icin bugunku position solve'da kullanilmaz.
- `computeRange()` icinde aktif parametreler `psTVLTime`, `sat_no`, `eph`, `clockCorr` ve `satellitePositions`'dir. `rho`, `ionoutc`, `xyz`, `tempPos` ve `velocities` eski genis API'den kalmistir. Ionosphere correction artik receiver azimut/elevasyonu hazir oldugunda WLS icinde uygulanir.
- Ephemeris alanlarinin mevcut isimleri ile ICD anlamlari su sekildedir: `omgdot` gercekte `Omega0`, `omg0` gercekte argument of perigee `omega`, `omgkdot` gercekte `OmegaDot` degeridir. `satpos()` bunlari dogru matematiksel yerde kullanir; konu su an hesap hatasi degil, ileride yapilacak kontrollu isim duzeltmesidir.
- `POSTPONE_TOW=0.160` donanim/pipeline zaman kalibrasyonunun bir parcasidir; kaynagi dogrulanmadan kaldirilmamalidir.
- Ilk nav-solve interrupt'i geldiginde o anda allocated, hardware busy ve nav-solve interrupt'i etkin olan kanallar epoch'un sabit bekleme maskesine alinir. Unlock interrupt'i gelen kanal artik tracked olmadigi icin bekleme maskesinden cikarilir; epoch ortasinda navigation-ready olan yeni kanal ise aktif maskeyi buyutmez ve sonraki epoch'tan itibaren beklenir. Kalan beklenen kanallarin tamami gelirse snapshot son interrupt'ta hemen yayinlanir. 30 ms holdoff dolarsa veya daha yeni fiziksel epoch baslarsa eksik eski epoch WLS calistirilmadan discard edilir; eski ve yeni olcumler birlestirilmez.
- Interrupt bekleme maskesi tamamlandiktan sonra frozen kanallarin tumu ortak TOW/`ABS_SAMPLE` kumesinde degilse epoch reddedilir. Selector'in buldugu daha kucuk alt kume yalniz diagnostic bilgidir ve WLS girdisi olamaz.
- Dort uydu 3D konum + receiver clock bias icin minimum ve yeterlidir. Bu durumda
  `dof=N-4=0` oldugu icin WLS konumu publish edilir fakat residual chi-square
  integrity bayragi false kalir. Bes veya daha fazla uyduda publish icin mevcut
  chi-square gecis kosulu uygulanir. Boylece `solution_valid` ile
  `integrity_available/pass` ayni kavram olarak kullanilmaz.
- Broadcast SV health filtresi uygulanir. Sonraki integrity adimi ephemeris age/fit interval ve post-fit residual metriklerini eklemektir. En az bes satellite olmadan tek hatali olcumu residual ile guvenilir sekilde ayirmak mumkun degildir.

### Debug Mesajlari

- Yeni kategorili log macro yapisi eklendi:

```c
GPS_LOG(level, category, ...)
```

- Kategoriler:
  - `ACQ`
  - `TRK`
  - `ISR`
  - `NAV`
  - `SCHED`
  - `MEM`
  - `HWREG`
  - `FUSION`
  - `LOCATION`
- Debug seviyeleri kumulatiftir; secilen seviye kendisini ve daha dusuk
  seviyeleri gosterir:

| `GPS_DEBUG_LEVEL` | Eklenen cikti |
| ---: | --- |
| `1` | Temel telemetri: ham GPS/WLS `[LOCATION] source=gps`, gecerliyse ESKF `[LOCATION] source=imu_corrected`, DOP degerleri ve sifir tabanli donanim kanal numaralarini tasiyan `[TRK] tracked satellites=... prn_indices=[...]` (`0` = GPS PRN `G01`). Baslangicta fusion/IMU konfigurasyonu da bir kez yazilir. |
| `2` | Gelecekteki ek status ayrintilari icin ayrilmistir. Su an level 2'ye ozel mesaj yoktur; pratikte level 1 ile ayni ciktiyi verir. |
| `3` | Level 1'e ek olarak acquisition/tracking/navigation durum gecisleri, warning/error mesajlari, integrity bilgileri ve periyodik ayrintili `[FUSION] state=...` durumu. |
| `4` | Level 3'e ek olarak performans, scheduler, nav-bit/parser, uydu/olcum ve dusuk seviye TRACE tanilari. UART yuku en yuksek seviyedir. |

`Makefile` varsayilanlari `GPS_DEBUG=1` ve `GPS_DEBUG_LEVEL=4`'tur. Bu nedenle
dogrudan parametresiz `make`, debug loglarini derler ve dort seviyenin tamamini
acar. Yalniz temel GPS/ESKF konumu ve tracked-satellite telemetrisi icin:

```sh
make GPS_DEBUG=1 GPS_DEBUG_LEVEL=1 GPS_ESKF_ENABLE=1
```

Butun UART debug mesajlarini derleme disinda birakmak icin `GPS_DEBUG=0`
kullanilir. Komut satirinda veya ust build'de verilen degerler `?=` ile
tanimlanan Makefile varsayilanlarini ezer.

- Core ACQ/TRCK/ISR path'inde yuksek frekansli uncategorized debug print'ler azaltildi.

### Memory Safety

- ISR path'inde dynamic allocation yok.
- Event queue static/fixed-size.
- ACQ engine index, tracking channel index ve PRN icin defensive bounds check'ler eklendi.
- Linked-list allocation path'lerinde malloc failure kontrolu eklendi.
- Dynamic allocation halen linked-list ve navigation/math tarafinda mevcut, fakat ISR icinden cagrilmiyor.

### Register Map Dogrulama

XLSX register dokumanlarina gore dogrulananlar:

- ACQ offset'leri firmware ile uyumlu:
  - control `0x00`
  - PRN `0x04`
  - peak `0x08`
  - code phase `0x0c`
  - absolute sample `0x10`
  - status `0x14`
  - doppler `0x18`
- ACQ status bitleri:
  - acquired bit
  - busy bit
- TRCK offset'leri firmware ile uyumlu:
  - control `0x00`
  - PRN `0x04`
  - code phase `0x08`
  - absolute sample `0x0c`
  - status `0x10`
  - doppler `0x14`
  - nav data `0x18..0x3c`
  - timeout `0x40`
  - nav timer `0x44`
  - reserved `0x48`
  - remaining code phase `0x4c`
- Interrupt clear davranisi write-one toggle/clear seklinde ele alindi.
- TRCK XLSX icinde NAV_SOLVE flag aciklamasi ambiguous/copy-paste gibi gorunuyor; RTL davranisina gore nav timer solve flag olarak yorumlandi.

### Donanima Yeni ACQ/TRCK IP Eklenirse Software'de Nereler Degisir

Donanimda ACQ veya TRCK instance sayisi, base address'i, stride'i veya interrupt source'u degisirse once software BSP map'i guncellenmeli. Bu proje icin ana software giris noktasi:

```text
soc/software/bsp/include/bsp/soc.h
```

Bu dosya generated ise kalici degisiklik icin generator veya hardware config tarafindaki source-of-truth da guncellenmeli; aksi halde BSP tekrar generate edilince manuel degisiklikler kaybolur.

Mevcut BSP GPS map'i:

```c
#define BSP_GPS_ACQ_BASE          0x10020000UL
#define BSP_GPS_TRCK0_BASE        0x10021000UL
#define BSP_GPS_TRCK_STRIDE       0x00001000UL
#define BSP_GPS_TRCK_COUNT        9UL
#define BSP_GPS_ACQ_IRQ           1UL
#define BSP_GPS_TRCK0_IRQ         2UL
#define BSP_GPS_TRCK_IRQ_STRIDE   1UL
```

#### ACQ IP Eklemek

Uniform ACQ address/IRQ stride varsa `soc.h` icinde su define'lar verilmelidir:

```c
#define BSP_GPS_ACQ_BASE          0x10020000UL
#define BSP_GPS_ACQ_COUNT         2UL
#define BSP_GPS_ACQ_STRIDE        0x00001000UL
#define BSP_GPS_ACQ_IRQ           1UL
#define BSP_GPS_ACQ_IRQ_STRIDE    1UL
```

Eger ACQ engine'ler tracking bolgesinden once arka arkaya yerlestiriliyorsa `BSP_GPS_TRCK0_BASE` de yeni ACQ penceresinden sonra baslamalidir. Ornek iki ACQ engine icin:

```c
#define BSP_GPS_ACQ_BASE          0x10020000UL
#define BSP_GPS_ACQ_COUNT         2UL
#define BSP_GPS_ACQ_STRIDE        0x00001000UL
#define BSP_GPS_TRCK0_BASE        0x10022000UL
#define BSP_GPS_ACQ_IRQ           1UL
#define BSP_GPS_TRCK0_IRQ         3UL
```

ACQ tarafinda normal durumda `src/gps/gps_ip.c` icinde manuel pointer eklemek gerekmez. Startup'ta `gps_init_acq_tables()` su helper'lari kullanarak tabloyu doldurur:

```c
GPS_ACQ_IP_BASE_ADDR(index)
GPS_ACQ_INTR_LINE(index)
```

ACQ engine sayisi firmware tarafinda tek noktadan `header/gps/gps_ip_defines.h` icindeki `ACQ_ENGINE_COUNT` ile kontrol edilir. Varsayilan olarak `BSP_GPS_ACQ_COUNT` kullanilir. Donanim/BSP dogru count veriyorsa ekstra override gerekmez.

Eger ACQ address veya IRQ offset'leri uniform degilse, mevcut `base + index * stride` modeli yeterli degildir. Bu durumda:

- `soc.h` icinde her ACQ icin explicit base/IRQ define'i eklenmeli, ornek `BSP_GPS_ACQ0_BASE`, `BSP_GPS_ACQ1_BASE`.
- `header/gps/gps_ip_defines.h` icindeki `GPS_ACQ_IP_BASE_ADDR(index)` ve `GPS_ACQ_INTR_LINE(index)` helper'lari explicit tablo veya switch ile guncellenmeli.
- `src/gps/gps_ip.c` icindeki `gps_init_acq_tables()` explicit base/IRQ tablolarini kullanacak sekilde guncellenmeli.

ACQ register layout'u degisirse sadece count/base degistirmek yetmez. Su alanlar da XLSX/RTL'e gore kontrol edilmelidir:

- `gps_acq_t` struct layout'u,
- `GPS_ACQ_*` control bitleri,
- `GPS_ACQ_STATUS_POS`,
- `GPS_ACQ_BUSY_POS`,
- interrupt clear/pending semantics.
- PRN encoding'i. Mevcut donanim 0..31 PRN index bekliyor.

#### TRCK IP Eklemek

Uniform tracking channel address/IRQ stride varsa `soc.h` icinde su define'lar guncellenmelidir:

```c
#define BSP_GPS_TRCK0_BASE        0x10022000UL
#define BSP_GPS_TRCK_STRIDE       0x00001000UL
#define BSP_GPS_TRCK_COUNT        10UL
#define BSP_GPS_TRCK0_IRQ         3UL
#define BSP_GPS_TRCK_IRQ_STRIDE   1UL
```

Tracking tarafinda mevcut firmware bazi yerlerde hala manuel channel entry'leri kullaniyor. `BSP_GPS_TRCK_COUNT` arttirilinca su dosyalarda yeni kanal icin entry eklenmelidir:

- `header/gps/gps_ip_defines.h`
  - `TRCK9_IP_BASE_ADDR`, `TRCK10_IP_BASE_ADDR`, ...
  - `TRCK9_INTR_LINE`, `TRCK10_INTR_LINE`, ...
- `src/gps/gps_ip.c`
  - `trck9_ip`, `trck10_ip`, ...
  - `trck_ips[]` array'ine yeni pointer'lar,
  - `trck_ips_intr_lines[]` array'ine yeni IRQ line'lar.
- `src/gps/gps_interrupt_handlers.c`
  - dosya sonundaki `DEFINE_TRCK_INTR_HANDLER(9)`, `DEFINE_TRCK_INTR_HANDLER(10)`, ... wrapper'lari.

`GPS_TRCK_IP_COUNT`, `BSP_GPS_TRCK_COUNT` uzerinden gelir ve loop/array boyutlari bu count'u kullanir. Ancak yukaridaki manuel array initializer'lar ve handler wrapper'lari yeni count ile uyumlu olmak zorundadir.

Eger TRCK address veya IRQ offset'leri uniform degilse, mevcut `BSP_GPS_TRCK0_BASE + index * BSP_GPS_TRCK_STRIDE` ve `BSP_GPS_TRCK0_IRQ + index * BSP_GPS_TRCK_IRQ_STRIDE` modeli yeterli degildir. Bu durumda:

- BSP'ye her tracking channel icin explicit base/IRQ define'i eklenmeli.
- `header/gps/gps_ip_defines.h` icindeki `TRCKn_IP_BASE_ADDR` ve `TRCKn_INTR_LINE` define'lari explicit degerlerden gelmeli.
- `src/gps/gps_ip.c` icindeki `trck_ips[]` ve `trck_ips_intr_lines[]` array'leri bu explicit define'lari kullanmali.

TRCK register layout'u degisirse su alanlar XLSX/RTL'e gore tekrar kontrol edilmelidir:

- `gps_trck_t` struct layout'u,
- `GPS_TRCK_*` control bitleri,
- `GPS_TRCK_*` status bitleri,
- nav data register araligi,
- timeout/nav timer offset'leri,
- interrupt clear/pending semantics.

#### Degisiklik Sonrasi Kontrol Listesi

- ACQ register window'lari TRCK register window'lari ile cakismiyor mu?
- PLIC source ID'leri donanim interrupt map'i ile birebir ayni mi?
- `BSP_GPS_ACQ_IRQ`, `BSP_GPS_TRCK0_IRQ` ve stride degerleri PLIC tarafinda beklenen source ID'lere gidiyor mu?
- `ACQ_ENGINE_COUNT` ve `GPS_TRCK_IP_COUNT` yeni donanim sayilari ile uyumlu mu?
- `GPS_EVENT_QUEUE_SIZE`, toplam ACQ + TRCK interrupt yogunlugu icin yeterli mi?
- Build sonrasi `make clean all` basarili mi?
- Board uzerinde ACQ completion, TRCK nav bits, unlock ve nav solve interrupt'lari tek tek dogrulandi mi?

### Build Validation

Degisikliklerden sonra build alindi:

```sh
make clean all
```

Build basarili oldu ve ELF uretildi:

```text
build/gps_system.elf
```

Kalan warning'ler:

- mevcut volatile qualifier warning'leri,
- nav/math dosyalarinda unused variable/parameter warning'leri,
- linker tarafinda RWX LOAD segment warning'i,
- eski ASCII/comment formatting warning'i.

### 2026-07-08 ACQ Debug Notu

`make fpga_debug_load APP=gps_system GDB=/usr/bin/gdb-multiarch` sonrasi GDB ile dogrulanan durum:

- Scheduler `acq_start()` fonksiyonuna giriyor; yani acquisition start yazisi yapiliyor.
- ACQ0 register snapshot:
  - `PRN_NUMBER=0`
  - `STATUS_REG=0x2`
  - `ACQ_BUSY=1`
  - PLIC pending bit yok
  - ACQ internal pending bit yok
- Bu durum firmware'in acquisition'i baslattigini, fakat ACQ RTL'in henuz acquisition-end interrupt uretmedigini gosterir.

RTL'de `acq_top.sv` akisi:

- `ACQ_START` geldikten sonra ACQ `S_WR_DATA` state'ine gecer ve `busy=1` olur.
- `S_WR_DATA` cikisi `afe_clk` domainindeki `sample_align_i` ve RF buffer write tamamlanmasina baglidir.
- `rf_clk` board uzerinde yoksa veya `sample_align_i` uretilmiyorsa `wr_mem_end` gelmez.
- Bu durumda ACQ busy high kalir ve `acq_end` uretilmedigi icin ACQ interrupt gelmez.

Bu timer/scheduler yavasligi degildir. Firmware start ediyor; tamamlanma icin RF/AFE clock ve sample-align path'i board uzerinde dogrulanmalidir.

### Kalan Riskler ve Board-Level Test Ihtiyaci

- Mevcut donanim/BSP tek ACQ engine expose ediyor. Birden fazla ACQ engine icin hardware/BSP register map'i guncellenmeli.
- ACQ normal completion tamamen `acq_end` interrupt'ina baglidir. RF clock veya sample-align yoksa ACQ busy stuck kalir; firmware bunu warning olarak raporlar ama ACQ'yi timeout ile tamamlanmis saymaz.
- Event queue dolarsa tracking event kaybi olabilir; overflow sayiliyor ve loglaniyor.
- ACQ interrupt queue doluysa shadow result korunuyor, fakat cok sik ACQ completion durumunda board uzerinde stres test gerekli.
- Navigation freshness kontrolu eklendi, fakat tum kanallar icin tam epoch-aligned double-buffer modeli eklenmedi.
- CLINT timer cadence, PLIC interrupt siralamasi ve ACQ/TRCK back-to-back interrupt davranisi board uzerinde dogrulanmali.

### PPS Entegrasyonu

- PPS APB periferigi `0x1002a000` adresindedir ve PLIC interrupt kullanmaz.
- Her tracking wrapper, yalniz `nav_solve_timer_reached` olayinda PPS capture
  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:

```text
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
  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.
- 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.