gps/README.md

# Rocket GPS SoC

Bu depo, RV64 Rocket cekirdegi ile GPS acquisition, tracking, navigation ve
PPS donanimini ayni SoC icinde birlestirir. Ayni tasarim VCU118, Genesys2 ve
Ti375C529 FPGA kartlarinda; ortak GPS firmware'i ise bare-metal olarak calisir.
ASIC-style RTL ve simulasyon girisi de korunur.
Upstream Rocket-Chip kaynaklari daginik kok klasorlerde tutulmaz; gerekli
upstream kaynaklar `hardware/upstream/rocket-chip/` altindadir.

Donanim; RF orneklerini alan acquisition/tracking kanallarini, atomik olcum
snapshot'larini, interrupt kaynaklarini ve PPS periferigini saglar. `gps_system`
firmware'i interrupt servislerini, LNAV/ephemeris parsing'i, coherent epoch
toplamayi, position ve Doppler WLS'i, flash persistence'i ve opsiyonel
GPS+IMU ESKF'yi yurutur. Flash bootloader uygulama imajini CRC ile denetleyip
DTIM'e tasir; GDB yolu ayni ELF'i test icin dogrudan DTIM'e yukleyebilir.

## Kisa Harita

```text
hardware/
  soc/scala/                  Proje Scala/Chisel SoC katmani
  generated/                  FIRRTL ve SystemVerilog dump alani
  fpga/vcu118/rtl/            VCU118 ek RTL
  fpga/vcu118/constraints/    VCU118 XDC
  fpga/genesys2/rtl/          Genesys2 ek RTL
  fpga/genesys2/constraints/  Genesys2 XDC
  fpga/ti375c529/rtl/         Ti375C529 ek RTL
  fpga/ti375c529/constraints/ Ti375C529 Efinity interface kaynagi
  sim/fpga/vcu118/            FPGA smoke/sim girisi
  sim/asic/rocket/            ASIC testbench, modeller, wave.do
  external/gps/rtl/           GPS RTL kaynaklari ve filelist
  upstream/rocket-chip/       Gerekli upstream Rocket-Chip src ve bootrom

soc/software/                 Bootloader, BSP, uygulamalar, flash image tool
targets/fpga/vcu118/          VCU118 build/programlama akisi
targets/fpga/genesys2/        Genesys2 build/programlama akisi
targets/fpga/ti375c529/       Ti375C529 Efinity build/programlama akisi
targets/asic/rocket/          ASIC wrapper/filelist/sim akisi
setup_tools.sh                /tools/soc-tools host araci kurulum betigi
```

`hardware/generated/`, `soc/out/`, `targets/*/out/` ve kok `out/` uretilen
ciktilardir; kalici kaynak degisiklikleri bu dizinlere yapilmamalidir.

## Destek Ozeti

| Kart | FPGA araci | SoC / ACQ / TRK | Flash ve app offset | Varsayilan RF |
|---|---|---|---|---|
| VCU118 | Vivado | 100 / 100 / 125 MHz | 128 MiB, `0x06000000` | PMOD |
| Genesys2 | Vivado | 50 / 80 / 125 MHz | 32 MiB, `0x01800000` | PMOD |
| Ti375C529 | Efinity | 100 / 100 / 125 MHz | 64 MiB, `0x00800000` | PMOD |

Kart secimi `FPGA_BOARD=<kart>` veya `BOARD=<kart>` ile yapilir. Kesin clock,
flash, UART ve RF ayarlarini varsaymak yerine once su komut kullanilmalidir:

```sh
make FPGA_BOARD=genesys2 fpga-config
```

Kart bazli ayrintilar `targets/fpga/<kart>/README.md`, yazilim ayrintilari
`soc/software/gps_system/README.md` icindedir.

## Gelistirme Araclari

Mill, JDK, CIRCT/firtool ve Z3 makineye/işletim sistemine ozel binary
paketlerdir; Git'e eklenmezler. Linux x86-64 host araclarini sabit surum ve
SHA256 kontrolleriyle `/tools/soc-tools` altina kurmak icin:

```sh
./setup_tools.sh
```

Proje araclarini ve RISC-V bare-metal toolchain'i shell'e eklemek icin:

```sh
source source.sh
make doctor
```

`source.sh`, RISC-V GCC'yi sirasiyla `RISCV_TOOLCHAIN`, `TOOLCHAIN`, proje-ici
`tools/local/riscv/bin`, `/tools/toolchain/bin`, `/tools/toolchains/bin` ve
`PATH` icinde arar. Standart olmayan bir kurulum icin:

```sh
RISCV_TOOLCHAIN=/opt/riscv source source.sh
```

Ayni ayar shell'i degistirmeden Make'e de verilebilir:

```sh
make fpga-rtl RISCV_TOOLCHAIN=/opt/riscv
```

`setup_tools.sh` host tarafindaki Scala/Chisel uretim araclarini kurar. RISC-V
bare-metal toolchain buyuk ve ayri bir urun oldugu icin indirilmez; `source.sh`
tarafindan mevcut `/tools/toolchains` kurulumundan veya `RISCV_TOOLCHAIN`
degiskeninden bulunur.

## Ana Komutlar

| Hedef | Amaci |
|---|---|
| `make doctor` | JDK, Mill, firtool ve RISC-V toolchain'i kontrol eder. |
| `make fpga-config` | Secili kartin etkin clock, flash, UART ve RF ayarlarini yazar. |
| `make fpga-rtl` | Chisel/FIRRTL'den kart wrapper'i dahil SystemVerilog uretir. |
| `make fpga-bitstream` | Vivado veya Efinity sentez, place-route ve bitstream akisini calistirir. |
| `make fpga-elf-flash-image` | `APP` ELF'ini bootloader header/CRC iceren app imajina cevirir. |
| `make fpga-mcs` | Mevcut bitstream ile app imajini birlestirir; karta yazmaz. Ti375'te cikti HEX'tir. |
| `make fpga-program` | Bitstream'i FPGA SRAM'ine gecici yukler. |
| `make fpga-flash-app` | Yalniz uygulama flash bolgesini programlar. |
| `make fpga-flash-bitstream` | Yalniz konfigurasyon/bitstream bolgesini programlar. |
| `make fpga-flash-mcs` | Birlesik kalici flash imajini uretip programlar. |
| `make fpga-flash-all` | Degisen bitstream ve app bolgelerini ayri ayri programlar. |
| `make fpga-debug-openocd` | Rocket DMI icin OpenOCD/GDB sunucusunu acar. |
| `make fpga-debug-load` | Secili uygulamayi GDB ile DTIM'e yukler. |
| `make fpga-uart` | Kart UART'ini varsayilan `460800` baud ile dinler. |
| `make asic-rtl`, `make asic-sim` | ASIC-style RTL veya Questa simulasyon akisini calistirir. |

`APP` verilmezse varsayilan `hello_uart` olur. GPS firmware'i icin her build ve
programlama komutunda `APP=gps_system` acikca verilmelidir. `fpga-mcs` sonrasi
MCS/HEX dosyasini GUI ile programlamak da gecerlidir; kalici boot testi icin
kart power-cycle edilmelidir.

GPS bare-metal uygulamasini derlemek ve FPGA uzerinde GDB ile RAM'e yuklemek:

```sh
make -C soc/software app APP=gps_system
make -C targets/fpga/vcu118 debug-load APP=gps_system
```

## GPS Firmware Profilleri: ESKF ve GPS-only

`gps_system` varsayilan olarak ESKF acik (`GPS_ESKF_ENABLE=1`) ve UART
`460800` baud olacak sekilde derlenir. Kok Makefile'in kart varsayilani VCU118
oldugu icin Genesys2 komutlarinda `FPGA_BOARD=genesys2` acikca yazilmalidir.

TDK ICM42688 + GPS + ESKF iceren birlesik Genesys2 MCS/BIN:

```sh
make FPGA_BOARD=genesys2 APP=gps_system \
  GPS_ESKF_ENABLE=1 IMU_SENSOR=tdk fpga-mcs
```

Yalniz GPS acquisition/tracking, WLS, Doppler velocity ve PPS calistiran;
IMU/ESKF baslatmayan firmware:

```sh
make FPGA_BOARD=genesys2 APP=gps_system \
  GPS_ESKF_ENABLE=0 fpga-mcs
```

`GPS_ESKF_ENABLE` verilmezse deger `1`'dir. Iki komut ayni
`targets/fpga/genesys2/out/flash/genesys2_rocket.mcs` ve `.bin` yollarini
kullanir; ikinci build birincinin ciktisinin uzerine yazar.

`fpga-mcs` mevcut `.bit` dosyasini kullanip bootloader ve uygulamayi yeniden
derler. Yalniz software profili veya baud degisikligi icin sentez gerekmez.
Tracking/PPS RTL veya Chisel degistiyse once:

```sh
make FPGA_BOARD=genesys2 APP=gps_system fpga-bitstream
make FPGA_BOARD=genesys2 APP=gps_system GPS_ESKF_ENABLE=1 \
  IMU_SENSOR=tdk fpga-mcs
```

Firmware ve host UART dinleyicisinin varsayilani birlikte `460800`'dur:

```sh
make FPGA_BOARD=genesys2 fpga-uart
```

### Kalici GPS verisi

`gps_system` varsayilan olarak ephemeris flash store'u ve navigation context
store'u acik derler. Ephemeris store bos ise 32 PRN icin stale baslangic
kayitlari yazilir; bunlar zaman/fit kontrolunu gecmeden konum hesabinda
kullanilmaz ve gercek LNAV ephemeris'i geldikce yenilenir. Her boot'ta erase
yapilmaz (`GPS_EPHEMERIS_FLASH_FORCE_FORMAT=0`).

| Kart | Navigation context | Ephemeris store |
|---|---:|---:|
| Genesys2 | `0x01FC0000` | `0x01FE0000` |
| VCU118 | `0x07FC0000` | `0x07FE0000` |
| Ti375C529 | `0x03FC0000` | `0x03FE0000` |

Ilgili build ayarlari `GPS_NAV_CONTEXT_ENABLE`,
`GPS_EPHEMERIS_FLASH_ENABLE` ve `GPS_EPHEMERIS_FLASH_SEED_INITIAL`'dir.

### UART GPS durum satirlari

`[TRK] tracked satellites` aktif ve lock durumundaki tracking kanallarini
gosterir. `[NAV] epoch funnel` ise bir konum epoch'unun asamalarini ayirir:

```text
tracked     aktif/locked tracking kanali
ready       gecerli ephemeris, HOW time anchor ve taze olcumu olan kanal
candidates  tamamlanmis ayni epoch snapshot'ina giren kanal
coherent    zaman/coherence kontrolunden gecen kanal
fix         en az WLS minimumu ile nav solve calistirilabildi
```

Bu nedenle `tracked` sayisinin `ready` sayisindan buyuk olmasi tek basina
interrupt hatasi degildir. `fix=1` WLS denemesinin girdisinin hazir oldugunu
gosterir; basarili `[LOCATION]` sonucunu tek basina garanti etmez.
`eph_reject/eph_hit/eph_miss`,
`assembly_failed/deadline/overwrite` sayaclari kaybin ephemeris mi yoksa epoch
assembly tarafinda mi oldugunu ayirmak icindir. Firmware revizyonu acilista
`[FUSION] init build=...` alaninda gorulur; beklenen log yoksa once karta
yuklenen build bu alanla dogrulanmalidir.

### Doppler, WLS ve ESKF veri yolu

```text
tracking loop, her 20 ms:
  carrier Q7 + 20 prompt I/Q + wideband power + ABS_SAMPLE/code phase
      -> sabit tracking snapshot
      -> synchronizer + APB-domain atomik register + interrupt
      -> C/N0 ve Doppler/range-rate donusumu
      -> ham Doppler + tek-kanal FDE ile C/N0-weighted velocity WLS
      -> ECEF velocity + 3x3 covariance + receiver clock drift
      -> ECEF->ENU adapter
      -> ayri velocity NIS gate
      -> ayni capture epoch'unda 15-state ESKF update
      -> daha yeni IMU history replay
```

RTL Doppler veya C/N0 uzerinde IIR yapmaz; ham ve 20 ms sabit snapshot'i
software'e verir. Software ayni PRN icin C/N0'yi `alpha=0.2` ile yumusatir;
Doppler'in hem ham de `alpha=0.05` IIR sonucu korunur. L1 range-rate
`-doppler_hz * c / 1575420000` ile hesaplanir. Ham yol tek-kanal
leave-one-out FDE'li velocity WLS'ten ESKF'ye, filtreli yol ayri velocity
WLS'ten yalniz PPS clock-bias drift predictor'una gider. PPS'in ana faz/zaman
olcumu position WLS `clock_bias_m` sonucudur; Doppler yalniz 200 ms epoch'lar
arasindaki turev prediction'ina ve kalite siniflandirmasina yardim eder. Her
iki velocity WLS state'i `[vx, vy, vz, receiver_clock_drift_mps]`'dir; uydu
LOS hizi ve broadcast satellite clock drift observation'dan ayrilir. C/N0,
range-rate agirligini belirler; post-fit residual gerekirse formal
covariance'i yalniz buyutur.

Klasik mutlak-pseudorange GNSS modelinde receiver zaman hatasi
`delta_t_r(t)` ise:

```text
code WLS 4. state:     b_r     = c * delta_t_r             [metre]
Doppler WLS 4. state:  bdot_r  = c * d(delta_t_r)/dt       [metre/saniye]
b_r(t + dt) ~= b_r(t) + bdot_r * dt
```

Burada `bdot_r`, receiver oscillator frequency error'inin range-rate
birimindeki ortak etkisidir. Ornegin `0.1 ppm` yaklasik `29.98 m/s` eder;
Doppler WLS bu ortak terimi uydu yonune gore degisen gercek `vx/vy/vz`
hareketinden ayirir.

Bu projede onemli bir datum farki vardir: position WLS'e verilen capture
zamanlarindan ortak receiver zamani cikarilir ve `STARTOFFSET` eklenir. Bu
nedenle `solution.clock_bias_m`, saf `c*delta_t_r` degil, yaklasik
`c*STARTOFFSET - reference_range` olan referans-uyduya bagli goreli
datumdur. Doppler WLS'nin dorduncu bilinmeyeni yine uydulara ortak receiver
clock/frequency drift'tir; fakat iki fit arasinda
`clock_bias_m(t+dt)=clock_bias_m(t)+clock_drift_mps*dt` kisiti kurulmaz.
Fit'ler ayri measurement/normal-equation kullanir. Doppler WLS, LOS
vektorleri icin position WLS'nin guncel receiver konumuna baglidir.

ESKF; ENU position/velocity, quaternion attitude, accel bias ve gyro bias
iceren 15 hata durumlu filtredir. Her timestamp'li IMU ornegi prediction'a
girer. Gecikmis GPS position ve Doppler velocity olcumleri kendi capture
epoch'unda uygulanir, ardindan daha yeni IMU history replay edilir. Position
ve velocity'nin ayri NIS kapilari vardir; kotu Doppler ayni epoch'taki gecerli
position update'ini iptal etmez. Durağanlik supervisor'u uygun oldugunda ZUPT
ve zero-gyro update uygular; GPS kesintisinde filtre sahte konum olcumu
uretmeden dead-reckoning yapar ve covariance buyur.

C/N0, geometri, WLS clock sigma, integrity ve Doppler residual metrikleri PPS
software'inin `acquire/precision/robust/holdover` profilini de secer. PPS
donanimi bu metrikleri dogrudan yorumlamaz; software v2.2 mailbox ile PI
`Kp/Ki`, slew ve lock esiklerini atomik olarak gunceller. Ayrintilar:

- `hardware/external/gps/rtl/trck_src/README.md`
- `soc/software/gps_system/README.md`
- `soc/software/fusion/README.md`
- `hardware/external/gps/rtl/pps/README.md`
- `soc/software/pps_python/README.md`

Alt girisler:

```sh
make -C hardware/soc help
make -C hardware/fpga/vcu118/rtl help
make -C hardware/sim/fpga/vcu118 help
make -C targets/fpga/vcu118 help
make -C targets/fpga/genesys2 help
make -C targets/fpga/ti375c529 help
make -C targets/asic/rocket help
```

## FPGA Kart Secimi ve RF Girisi

FPGA karti kok Makefile'dan `FPGA_BOARD` ile secilir:

```sh
make FPGA_BOARD=vcu118 fpga-config
make FPGA_BOARD=genesys2 fpga-config
make FPGA_BOARD=ti375c529 fpga-config
```

Top-level `BOARD=...` alias'i da desteklenir. Orneklerde Genesys2 kullanilir:

```sh
make BOARD=genesys2 fpga-config
```

Top-level hedeflerde tireli isimler tercih edilir (`fpga-program` gibi).
Yanlislikla underscore kullanilmasi durumunda yaygin FPGA hedefleri icin
alias'lar da vardir (`fpga_program`, `fpga_debug_openocd` gibi).

`fpga-config` secilen kartin clock, flash, UART, DTIM ve RF ayarlarini
gosterir. Genesys2 ve VCU118'de RF kaynagi `RF_INPUT_MODE` ile secilir:

```text
RF_INPUT_MODE=pmod       Varsayilan. Harici 4-bit RF data + RF clock PMOD'dan gelir.
RF_INPUT_MODE=generated  Dahili RF clock uretilir, RF data sifira baglanir.
RF_INPUT_MODE=ethernet   Kart bazli raw-Ethernet RF streamer path'i.
```

## MAX2771 EVKIT PMOD Baglantisi

MAX2771, mevcut standart PMOD SPI'dan ayri bir uc-telli seri IP ve MMIO
peripheralidir. MAX2771 IP tabani `0x10016000`, mevcut PMOD SPI tabani ise
`0x10015000` adresindedir. Iki arayuzun portlari ve kart pinleri birbirinden
bagimsizdir.

Genesys2 icin MAX2771 EVKIT, PMOD `JB` grubuna baglanir:

| MAX2771 sinyali | FPGA yonu | Genesys2 PMOD | FPGA pini | Elektrik standardi |
|---|---|---|---|---|
| `SCLK` | cikis | `JB2` | `V30` | LVCMOS33 |
| `CSN` | cikis | `JB3` | `V25` | LVCMOS33 |
| `SDATA` | yazmada cikis, okumada giris | `JB4` | `W26` | LVCMOS33 |

Okuma komutunda FPGA, R/W bitinden sonraki turnaround baslangicinda `SDATA`
surucusunu high-Z yapar ve ayni `JB4` pinini giris olarak ornekler. Yazmada
ayni pin cikis olarak kullanilir. EVKIT ve kart GND hatlari ortaklanmalidir.

VCU118 icin ayrilan bos PMOD0/J52 pinleri:

| MAX2771 sinyali | FPGA yonu | VCU118 PMOD | Header pini | FPGA pini | FPGA I/O standardi |
|---|---|---|---|---|---|
| `SCLK` | cikis | `PMOD0_5` | `J52.4` | `AU16` | LVCMOS18 |
| `CSN` | cikis | `PMOD0_6` | `J52.6` | `AT15` | LVCMOS18 |
| `SDATA` | yazmada cikis, okumada giris | `PMOD0_7` | `J52.8` | `AT16` | LVCMOS18 |

VCU118'in U41 level shifter'i PMOD header tarafini 3.3 V'a cevirir. Mevcut
standart PMOD SPI pinleri degistirilmemistir:

Ti375C529, PMOD0/J13'te RF veri ve saatinden arta kalan uc pini kullanir:

| MAX2771 sinyali | FPGA yonu | Ti375C529 PMOD | FPGA pini | Elektrik standardi |
|---|---|---|---|---|
| `SCLK` | cikis | `J13.1` | `G15` | 3.3_V_LVCMOS |
| `CSN` | cikis | `J13.8` | `A11` | 3.3_V_LVCMOS |
| `SDATA` | yazmada cikis, okumada giris | `J13.9` | `A13` | 3.3_V_LVCMOS |

| Kart | Standart PMOD SPI CSN/MOSI/MISO/SCLK | MAX2771 CSN/SDATA/SCLK |
|---|---|---|
| Genesys2 | `JC1/JC2/JC3/JC4` | `JB3/JB4/JB2` |
| VCU118 | `J53.1/J53.3/J53.5/J53.7` | `J52.6/J52.8/J52.4` |
| Ti375C529 | `J14.1/J14.2/J14.3/J14.4` | `J13.8/J13.9/J13.1` |

MAX2771 register varsayilanlarini yazip tek-hat `SDATA` uzerinden geri okuyarak
dogrulayan bare-metal uygulama:

```sh
make -C targets/fpga/genesys2 software APP=max2771_spi_test
```

Test MAX2771 register `0x0`-`0xA` icerigini veri sayfasindaki degerlerle
degistirir. EVKIT uzerindeki MAX32625 kontrolcusunun seri hatlari test boyunca
high-Z olmali ve EVKIT GUI ayni anda kullanilmamalidir.

Ti375C529 Efinity wrapper'i su anda yalniz harici PMOD RF girisini kullanir;
bu kartta `RF_INPUT_MODE=pmod` birakilmalidir. `generated` ve `ethernet`
yollari Ti375C529 wrapper'ina henuz uygulanmamistir.

Top-level FPGA wrapper'lar elle yazilmaz; `targets/fpga/*/tools/gen_*_wrapper.py`
scriptleri tarafindan uretilir. Genesys2 ve VCU118'de RF secimi RTL `ifdef`
ile degil, generator parametresi ile yapilir. `make rtl` ve Vivado `build.tcl`
ayni `RF_INPUT_MODE` degerini wrapper generator'a gecirir.

Varsayilan `pmod` modunda Ethernet RF IP/RTL okunmaz ve top'ta Ethernet PHY
portlari olusmaz. Ethernet RF akisi gerektiginde:

```sh
make -C targets/fpga/vcu118 bitstream RF_INPUT_MODE=ethernet
sudo make -C targets/fpga/vcu118 eth-rf-send

make -C targets/fpga/genesys2 bitstream RF_INPUT_MODE=ethernet
sudo make -C targets/fpga/genesys2 eth-rf-send
```

PMOD RF pinleri ve voltajlari:

```text
Genesys2 JA, connector ve FPGA tarafi 3.3 V:
  port              FPGA pin  PMOD pin  FPGA I/O   PMOD header level
  rf_clk_pmod       U27       JA[0]     LVCMOS33   3.3 V
  rf_data_pmod[0]   U28       JA[1]     LVCMOS33   3.3 V
  rf_data_pmod[1]   T26       JA[2]     LVCMOS33   3.3 V
  rf_data_pmod[2]   T27       JA[3]     LVCMOS33   3.3 V
  rf_data_pmod[3]   T22       JA[4]     LVCMOS33   3.3 V

VCU118 PMOD0/J52, connector tarafi 3.3 V, FPGA U1 tarafi U41 level shifter
uzerinden 1.8 V bank/LVCMOS18:
  port              FPGA pin  PMOD pin       FPGA I/O   PMOD header level
  rf_clk_pmod       AY14      PMOD0_0 J52.1  LVCMOS18   3.3 V
  rf_data_pmod[0]   AY15      PMOD0_1 J52.3  LVCMOS18   3.3 V
  rf_data_pmod[1]   AW15      PMOD0_2 J52.5  LVCMOS18   3.3 V
  rf_data_pmod[2]   AV15      PMOD0_3 J52.7  LVCMOS18   3.3 V
  rf_data_pmod[3]   AV16      PMOD0_4 J52.2  LVCMOS18   3.3 V

Ti375C529 PMOD0/J13, connector ve FPGA tarafi 3.3 V:
  port              FPGA pin  PMOD pin  FPGA resource       FPGA I/O
  rf_clk            A12       J13.10    GPIOR_95_CLK12      3.3_V_LVCMOS
  rf_data[0]        G16       J13.2     GPIOR_89            3.3_V_LVCMOS
  rf_data[1]        F16       J13.3     GPIOR_90            3.3_V_LVCMOS
  rf_data[2]        F17       J13.4     GPIOR_91            3.3_V_LVCMOS
  rf_data[3]        G17       J13.7     GPIOR_92            3.3_V_LVCMOS
```

VCU118'de disaridan PMOD header'a 3.3 V seviye verilir. FPGA U1 package
pinlerine dogrudan 3.3 V uygulanmaz; o tarafta XDC `LVCMOS18` kullanir.

Ti375C529'de AX2771 `rf_clk` hatti mutlaka J13 pin 10'a baglanmalidir. Bu pin
global-clock girisidir. J13 pin 1 / G15 (`GPIOR_88_PLLIN1`) MAX2771 `SCLK`
cikisidir; dedicated fabric GCLK olmadigi icin RF saati oradan alinmaz.

PMOD SPI portu her RF modunda aktiftir ve ayri MMIO register block olarak
`0x10015000` adresindedir. Kart uzerindeki konfig flash SPI'si `0x10014000`
adresinde kalir. Yazilim driver'i single/quad calisma modunu `ctrl.bit2`
uzerinden secer; single modda `dq[0]` MOSI, `dq[1]` MISO olarak kullanilir ve
`dq[2:3]` high-Z kalir. Quad modda `dq[3:0]` birlikte kullanilir.

```text
Genesys2 PMOD JC, connector ve FPGA tarafi 3.3 V:
  port              FPGA pin  PMOD pin  FPGA I/O   PMOD header level
  pmod_spi_csn      AC26      JC1       LVCMOS33   3.3 V
  pmod_spi_dq[0]    AJ27      JC2 MOSI  LVCMOS33   3.3 V
  pmod_spi_dq[1]    AH30      JC3 MISO  LVCMOS33   3.3 V
  pmod_spi_sck      AK29      JC4 SCK   LVCMOS33   3.3 V
  pmod_spi_dq[2]    AD26      JC7       LVCMOS33   3.3 V
  pmod_spi_dq[3]    AG30      JC8       LVCMOS33   3.3 V

VCU118 PMOD1/J53, connector tarafi 3.3 V, FPGA U1 tarafi U42 level shifter
uzerinden 1.2 V bank/LVCMOS12:
  port              FPGA pin  PMOD pin          FPGA I/O   PMOD header level
  pmod_spi_csn      N28       PMOD1_0 J53.1     LVCMOS12   3.3 V
  pmod_spi_dq[0]    M30       PMOD1_1 J53.3 MOSI LVCMOS12  3.3 V
  pmod_spi_dq[1]    N30       PMOD1_2 J53.5 MISO LVCMOS12  3.3 V
  pmod_spi_sck      P30       PMOD1_3 J53.7 SCK  LVCMOS12  3.3 V
  pmod_spi_dq[2]    P29       PMOD1_4 J53.2     LVCMOS12   3.3 V
  pmod_spi_dq[3]    L31       PMOD1_5 J53.4     LVCMOS12   3.3 V

Ti375C529 PMOD1/J14, connector ve FPGA tarafi 3.3 V:
  port              FPGA pin  PMOD pin      FPGA resource       FPGA I/O
  pmod_spi_csn      B12       J14.1         GPIOR_96_CLK13      3.3_V_LVCMOS
  pmod_spi_dq[0]    C14       J14.2 MOSI    GPIOR_97            3.3_V_LVCMOS
  pmod_spi_dq[1]    C13       J14.3 MISO    GPIOR_98            3.3_V_LVCMOS
  pmod_spi_sck      C12       J14.4 SCK     GPIOR_99            3.3_V_LVCMOS
  pmod_spi_dq[2]    D12       J14.7         GPIOR_100           3.3_V_LVCMOS
  pmod_spi_dq[3]    F12       J14.8         GPIOR_101_PLLIN1    3.3_V_LVCMOS
```

Sensorden gelen external interrupt hatti SPI'dan bagimsizdir. `pmod_irq`
top-level input'u olarak PMOD'a alinir ve PLIC'te `BSP_PMOD_IRQ` (`11`)
ID'siyle gorunur.

```text
Genesys2:
  port       FPGA pin  PMOD pin  FPGA I/O   PMOD header level
  pmod_irq  AK30      JC9       LVCMOS33   3.3 V

VCU118:
  port       FPGA pin  PMOD pin        FPGA I/O   PMOD header level
  pmod_irq  M31       PMOD1_6 J53.6   LVCMOS12   3.3 V

Ti375C529:
  port       FPGA pin  PMOD pin  FPGA resource  FPGA I/O
  pmod_irq   D13       J14.9     GPIOR_102      3.3_V_LVCMOS
  gps_pps    E13       J14.10    GPIOR_103      3.3_V_LVCMOS
```

Ti375C529'de `gps_pps` J14.10 uzerinden cikan 3.3 V PPS sinyalidir;
`pmod_irq` ise J14.9 uzerinden FPGA'ya girer.

Bu pinler mod bazli companion XDC dosyalarinda tutulur:
`hardware/fpga/genesys2/constraints/genesys2_pmod_rf.xdc`,
`hardware/fpga/vcu118/constraints/vcu118_pmod_rf.xdc`,
`hardware/fpga/genesys2/constraints/genesys2_pmod_spi.xdc`,
`hardware/fpga/vcu118/constraints/vcu118_pmod_spi.xdc`,
`hardware/fpga/genesys2/constraints/genesys2_pmod_irq.xdc`,
`hardware/fpga/vcu118/constraints/vcu118_pmod_irq.xdc`,
`hardware/fpga/genesys2/constraints/genesys2_ethernet.xdc` ve
`hardware/fpga/vcu118/constraints/vcu118_ethernet.xdc`. Ti375C529 pinleri,
I/O standartlari, PLL'ler ve hard-JTAG baglantisi tek Efinity interface
scriptinde tutulur:
`hardware/fpga/ti375c529/constraints/ti375c529_rocket.isf`.

### Ti375C529 kart uzeri baglantilar

Ti375C529 development kit'te Rocket sistem saati kart uzerindeki 100 MHz
osilatorden, GPS isleme saatleri ise AX2771'in J13.10 uzerindeki
16.367981 MHz RF saatinden uretilir. SW3 active-low Rocket resetidir. FTDI
UART varsayilan olarak 460800 baud ve mevcut Linux enumeration'inda
`/dev/ttyUSB2` kullanir. Birden fazla kart veya farkli enumeration icin
`UART_PORT=...` ve `FTDI_URL=...` ile override edilebilir.

Lower 512-Mbit konfig flash'i kart icinde su pinlere baglidir; PMOD'a kablo
cekilmez:

```text
port          FPGA pin  FPGA resource
flash_csn     A7        GPIOB_N_38 / SSL_N
flash_sck     G6        GPIOB_P_39 / CCK
flash_dq[0]   H4        GPIOB_N_40 / CDI0
flash_dq[1]   H5        GPIOB_P_40 / CDI1
flash_dq[2]   G5        GPIOB_N_39 / CDI2
flash_dq[3]   B7        GPIOB_P_38 / CDI3
```

Efinity `JTAG_USER1`, mevcut Rocket DMI tunnel protokolunu kullanir. Host
OpenOCD build'inde `riscv set_bscan_tunnel_ir` destegi bulunmalidir; Efinity
ile gelen OpenOCD yerine uyumlu host OpenOCD kullanilir. OpenOCD 0.12 icin
gerekli host yamasi
`targets/fpga/ti375c529/flow/debug/openocd-0.12-ti375-bscan.patch`
dosyasindadir. Ayrintili Efinity, clock, JTAG ve dogrulama notlari icin
`targets/fpga/ti375c529/README.md` dosyasina bakin.

## FPGA Flash ve MCS Akislari

Bu hedefler kok Makefile'dan secilen karta yonlenir. Genesys2 icin
`BOARD=genesys2`, VCU118 icin `BOARD=vcu118`, Ti375C529 icin
`BOARD=ti375c529` kullanilir. `APP` verilmezse varsayilan uygulama
`hello_uart` olur.

Sadece ELF'i derleyip bootloader'in okuyacagi flash-format app imajina cevirmek:

```sh
make BOARD=genesys2 APP=hello_uart fpga-elf-flash-image
```

Bu akista ELF dogrudan MCS'e girmez. Once su dosya uretilir:

```text
soc/out/flash/hello_uart.flash.bin
```

Yeni bitstream ve yeni aplikasyon ile birlesik MCS/BIN olusturmak:

```sh
make BOARD=genesys2 APP=hello_uart fpga-bitstream fpga-mcs
```

Genesys2 ciktilari:

```text
targets/fpga/genesys2/out/bitstream/genesys2_rocket.bit
targets/fpga/genesys2/out/flash/genesys2_rocket.mcs
targets/fpga/genesys2/out/flash/genesys2_rocket.bin
```

Birlesik MCS'i olusturup kart flash'ina yazmak:

```sh
make BOARD=genesys2 APP=hello_uart fpga-flash-mcs
```

Yeni bitstream de uretilsin, sonra birlesik MCS flash'a yazilsin:

```sh
make BOARD=genesys2 APP=hello_uart fpga-bitstream fpga-flash-mcs
```

Sadece bitstream region'ini kart flash'ina yazmak:

```sh
make BOARD=genesys2 fpga-flash-bitstream
```

Yeni bitstream uretip sadece bitstream region'ini yazmak:

```sh
make BOARD=genesys2 fpga-bitstream fpga-flash-bitstream
```

ELF'i flash formatina cevirip sadece app region'ini kart flash'ina yazmak:

```sh
make BOARD=genesys2 APP=hello_uart fpga-flash-app
```

`fpga-flash`, `fpga-flash-app` icin alias'tir:

```sh
make BOARD=genesys2 APP=hello_uart fpga-flash
```

Degisen bitstream ve app region'larini ayri MCS'lerle programlamak:

```sh
make BOARD=genesys2 APP=hello_uart fpga-flash-all
```

Flash programlama bittikten sonra FPGA her zaman otomatik olarak flash'taki
kullanici bitstream'inden yeniden baslamaz. Kartin kalici flash'tan boot
etmesini test etmek icin power-cycle/reconfigure yapin; sadece RAM/SRAM'e
hemen yuklemek icin `fpga-program` kullanin:

```sh
make BOARD=genesys2 fpga-program
```

OpenOCD baslarken `LIBUSB_ERROR_BUSY` gorulurse JTAG kablosunu Vivado
`hw_server` tutuyordur. Hardware Manager'i kapatin veya bu prosesleri durdurun:

```sh
pkill -u "$USER" -x hw_server || true
pkill -u "$USER" -x cs_server || true
make BOARD=genesys2 fpga-debug-openocd
```

Genesys2 flash yerlesimi:

```text
bitstream offset: 0x00000000
app offset:       0x01800000
flash size:       32 MiB
interface:        SPIx4
```

### Ti375C529 Efinity build ve flash

Efinity `/tools/efinix/efinity`, `/tools/Efinix/efinity`, `/opt`, kullanici
dizini ve `tools/local/efinity` altinda aranir. Farkli bir kurulum
`EFINITY_HOME=/path/to/efinity/<version>` ile secilebilir. `fpga-bitstream`,
uzun RTL elaborasyonundan once kurulumdaki `bin/setup.sh` ve
`scripts/efx_run.py` dosyalarini kontrol eder. Build, SRAM'e gecici programlama
ve kart tespiti kokten su sekilde yapilir:

```sh
make FPGA_BOARD=ti375c529 fpga-config
make FPGA_BOARD=ti375c529 fpga-bitstream
make -C targets/fpga/ti375c529 detect
make FPGA_BOARD=ti375c529 fpga-program
```

Ti375C529'de repository genelindeki `fpga-mcs` hedef adi korunur fakat cikti
Xilinx MCS/BIN degil, Efinity raw HEX'tir. Lower 512-Mbit flash yerlesimi:

```text
configuration offset: 0x00000000
app offset:           0x00800000
flash size:           64 MiB
interface:            active-x1 configuration / user-mode quad SPI
```

Konfig ve uygulama imajlarini uretmek ve programlamak icin:

```sh
make FPGA_BOARD=ti375c529 APP=hello_uart fpga-mcs
make FPGA_BOARD=ti375c529 APP=hello_uart fpga-flash-app
make FPGA_BOARD=ti375c529 fpga-flash-bitstream
make FPGA_BOARD=ti375c529 APP=hello_uart fpga-flash-mcs
```

Ciktilar:

```text
targets/fpga/ti375c529/out/bitstream/ti375c529_rocket.bit
targets/fpga/ti375c529/out/bitstream/ti375c529_rocket.hex
targets/fpga/ti375c529/out/flash/ti375c529_rocket.hex
targets/fpga/ti375c529/out/flash/ti375c529_rocket.json
```

Flash programlama Efinity'nin Ti375'e uygun JTAG-to-SPI bridge'ini gecici
olarak yukler. Gercek persistent boot testi icin programlamadan sonra karta
power-cycle uygulanmalidir. GDB ile DTIM'e yukleme ve UART dinleme:

```sh
make FPGA_BOARD=ti375c529 fpga-debug-openocd
make FPGA_BOARD=ti375c529 APP=hello_uart fpga-debug-load
make FPGA_BOARD=ti375c529 fpga-uart
```

## GPS Reset Davranisi

OpenOCD/GDB `monitor reset` yolu Rocket debug module `ndmreset` sinyalini
assert eder. FPGA top wrapper'lari bu sinyali SoC resetine katar; bu reset hem
Rocket core'a hem APB peripheral tarafina gider.

GPS APB entegrasyonu reseti tek tel olarak kullanmaz. `APBGpsBlock` icinde
`ResetCatchAndSync` ile APB/PCLK, acquisition 80 MHz, tracking 125 MHz ve
RF/AFE clock domainleri icin ayri active-low resetler uretilir. Assert async,
deassert ilgili clock domaininde 3 kademe senkronizedir. APB register wrapper
lari `PRESETN` ile resetlenir; `acq_top`, `trck_top` ve `afe_top` ise kendi
clock domain resetleriyle resetlenir.

Not: Senkron deassert icin ilgili clock calismalidir. PMOD/RF clock yoksa
RF/AFE domain reseti release olmaz; bu reset acisindan beklenen davranistir.

Detayli dosya haritasi icin `PROJECT_LAYOUT.md` ve `hardware/README.md`.