Files

T

Jason 1e284767cd fix(test,docs): remove dead xfft_32 files, update test infra for dual-16 FFT, add regression guide

- Remove xfft_32.v, tb_xfft_32.v, and fft_twiddle_32.mem (dead code
  since PR #33 moved Doppler to dual 16-pt FFT architecture)
- Update run_regression.sh: xfft_16 in PROD_RTL, remove xfft_32 from
  EXTRA_RTL and all compile commands
- Update tb_fft_engine.v to test with N=16 / fft_twiddle_16.mem
- Update validate_mem_files.py: validate fft_twiddle_16.mem instead of 32
- Update testbenches and golden data from main_cleanup branch to match
  dual-16 architecture (tb_doppler_cosim, tb_doppler_realdata,
  tb_fullchain_realdata, tb_fullchain_mti_cfar_realdata, tb_system_e2e,
  radar_receiver_final, golden_doppler.mem)
- Update CONTRIBUTING.md with full regression test instructions covering
  FPGA, MCU, GUI, co-simulation, and formal verification

Regression: 23/23 FPGA, 20/20 MCU, 57/58 GUI, 56/56 mem validation,
all co-sim scenarios PASS.

2026-04-07 02:51:48 +03:00

4.6 KiB

Raw Blame History

Contributing to PLFM_RADAR (AERIS-10)

Thanks for your interest in the project! This guide covers the basics for getting a change reviewed and merged.

Getting started

Fork the repository and create a topic branch from develop.
Keep generated outputs (Vivado projects, bitstreams, build logs) out of version control — the .gitignore already covers most of these.

Repository layout

Path	Contents
`4_Schematics and Boards Layout/`	KiCad schematics, Gerbers, BOM/CPL
`9_Firmware/9_2_FPGA/`	Verilog RTL, constraints, testbenches, build scripts
`9_Firmware/9_2_FPGA/formal/`	SymbiYosys formal-verification wrappers
`9_Firmware/9_2_FPGA/scripts/`	Vivado TCL build & debug scripts
`9_Firmware/9_3_GUI/`	Python radar dashboard (Tkinter + matplotlib)
`docs/`	GitHub Pages documentation site

Before submitting a pull request

Python — verify syntax: python3 -m py_compile <file>
Verilog — if you have Vivado, run the relevant build*.tcl; if not, note which scripts your change affects
Whitespace — git diff --check should be clean
Keep PRs focused: one logical change per PR is easier to review
Run the regression tests (see below)

Running regression tests

After any change, run the relevant test suites to verify nothing is broken. All commands assume you are at the repository root.

Prerequisites

Tool	Used by	Install
Icarus Verilog (`iverilog`)	FPGA regression	`brew install icarus-verilog` / `apt install iverilog`
Python 3.8+	GUI tests, co-sim	Usually pre-installed
GNU Make	MCU tests	Usually pre-installed
SymbiYosys (`sby`)	Formal verification	Optional — see SymbiYosys docs

FPGA regression (RTL lint + unit/integration/signal-processing tests)

cd 9_Firmware/9_2_FPGA
bash run_regression.sh

This runs four phases:

Phase	What it checks
0 — Lint	`iverilog -Wall` on all production RTL + static regex checks
1 — Changed Modules	Unit tests for individual blocks (CIC, Doppler, CFAR, etc.)
2 — Integration	DDC chain, receiver golden-compare, system-top, end-to-end
3 — Signal Processing	FFT engine, NCO, FIR, matched filter chain
4 — Infrastructure	CDC modules, edge detector, USB interface, range-bin decimator, mode controller

All tests must pass (exit code 0). Advisory lint warnings (e.g., case without default) are non-blocking.

MCU unit tests

cd 9_Firmware/9_1_Microcontroller/tests
make clean && make all

Runs 20 C-based unit tests covering safety, bug-fix, and gap-3 tests. Every test binary must exit 0.

GUI / dashboard tests

cd 9_Firmware/9_3_GUI
python3 -m pytest test_radar_dashboard.py -v
# or without pytest:
python3 -m unittest test_radar_dashboard -v

57+ protocol and rendering tests. The test_record_and_stop test requires h5py and will be skipped if it is not installed.

Co-simulation (Python vs RTL golden comparison)

Run from the co-sim directory after a successful FPGA regression (the regression generates the RTL CSV outputs that the co-sim scripts compare against):

cd 9_Firmware/9_2_FPGA/tb/cosim

# Validate all .mem files (twiddles, chirp ROMs, addressing)
python3 validate_mem_files.py

# DDC chain: RTL vs Python model (5 scenarios)
python3 compare.py dc
python3 compare.py single_target
python3 compare.py multi_target
python3 compare.py noise_only
python3 compare.py sine_1mhz

# Doppler processor: RTL vs golden reference
python3 compare_doppler.py stationary

# Matched filter: RTL vs Python model (4 scenarios)
python3 compare_mf.py all

Each script prints PASS/FAIL per scenario and exits non-zero on failure.

Formal verification (optional)

Requires SymbiYosys (sby), Yosys, and a solver (z3 or boolector):

cd 9_Firmware/9_2_FPGA/formal
sby -f fv_doppler_processor.sby
sby -f fv_radar_mode_controller.sby

Quick checklist

Before pushing, confirm:

bash run_regression.sh — all phases pass
make all (MCU tests) — 20/20 pass
python3 -m unittest test_radar_dashboard -v — all pass
python3 validate_mem_files.py — all checks pass
python3 compare.py dc && python3 compare_doppler.py stationary && python3 compare_mf.py all
git diff --check — no whitespace issues

Areas where help is especially welcome

See the list in README.md.

Questions?

Open a GitHub issue — that way the discussion is visible to everyone.

4.6 KiB Raw Blame History