fix: close all FPGA timing — CFAR pipeline + CIC reset path (Build 19)

CFAR pipeline fix (clk_100m WNS: -0.331ns → +0.156ns):
- Pre-register col_buf reads during ST_CFAR_THR pipeline stage
- 8 pipeline registers (4 values + 4 valids) break 15-level mux tree
- Delta wires use registered values, eliminating combinatorial depth

CIC reset path fix (clk_mmcm_out0 WNS: -0.074ns → +0.068ns):
- Add reset_h input port to cic_decimator_4x_enhanced.v
- Remove internal wire reset_h = ~reset_n (LUT1 inverter was root cause)
- Wire pre-registered reset_400m from ddc_400m.v into both CIC instances
- 3 sync reset blocks changed from if(!reset_n) to if(reset_h)

Build 19 results (xc7a50tftg256-2, Vivado 2025.2):
- All 5 clock domains timing met, 0 failing endpoints
- WNS: +0.068ns (400MHz), +0.156ns (100MHz), +0.627ns (120MHz)
- Utilization: 66.67% LUT, 22.36% FF, 74% BRAM, 93.33% DSP
- Bitstream: 2,140 KB

.gitattributes

@@ -0,0 +1,21 @@
+# Enforce LF line endings for all text files going forward.
+# Existing CRLF files are left as-is to avoid polluting git blame.
+* text=auto eol=lf
+
+# Binary files — ensure git doesn't mangle these
+*.npy binary
+*.h5 binary
+*.hdf5 binary
+*.png binary
+*.jpg binary
+*.pdf binary
+*.zip binary
+*.bin binary
+*.mem binary
+*.hex binary
+*.vvp binary
+*.s2p binary
+*.s3p binary
+*.step binary
+*.FCStd binary
+*.FCBak binary

.github/workflows/ci-tests.yml

@@ -46,7 +46,9 @@ jobs:
       - name: Unit tests
         run: >
           uv run pytest
-          9_Firmware/9_3_GUI/test_radar_dashboard.py -v --tb=short
+          9_Firmware/9_3_GUI/test_GUI_V65_Tk.py
+          9_Firmware/9_3_GUI/test_v7.py
+          -v --tb=short
 
   # ===========================================================================
   # MCU Firmware Unit Tests (20 tests)

.gitignore

@@ -32,6 +32,12 @@
 9_Firmware/9_2_FPGA/tb/cosim/rtl_doppler_*.csv
 9_Firmware/9_2_FPGA/tb/cosim/compare_doppler_*.csv
 9_Firmware/9_2_FPGA/tb/cosim/rtl_multiseg_*.csv
+9_Firmware/9_2_FPGA/tb/cosim/rx_final_doppler_out.csv
+9_Firmware/9_2_FPGA/tb/cosim/rtl_mf_*.csv
+9_Firmware/9_2_FPGA/tb/cosim/compare_mf_*.csv
+
+# Golden reference outputs (regenerated by testbenches)
+9_Firmware/9_2_FPGA/tb/golden/
 
 # macOS
 .DS_Store
@@ -57,3 +63,17 @@ build*_reports/
 
 # UART capture logs (generated by tools/uart_capture.py)
 logs/
+
+# Local schematic files
+# Schematic and board files (untracked)
+4_Schematics and Boards Layout/4_6_Schematics/FMC_TestBoard/*
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.kicad_sch
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.kicad_pcb
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.bak
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.tmp
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.net
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.dcm
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.svg
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.pdf
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/*.sch-bak
+4_Schematics and Boards Layout/4_6_Schematics/Main_Board/backup/

8_Utils/Python/LUT.py

@@ -1,7 +1,10 @@
 import numpy as np
 
 # Define parameters
-fs = 120e6  # Sampling frequency
+# NOTE: This is a standalone LUT generation utility. The production chirp LUT
+# is generated by 9_Firmware/9_2_FPGA/tb/cosim/gen_chirp_mem.py with
+# CHIRP_BW=20e6 (target: 30e6 Phase 1) and DAC_CLK=120e6.
+fs = 120e6  # Sampling frequency (DAC clock from AD9523 OUT10)
 Ts = 1 / fs  # Sampling time
 Tb = 1e-6  # Burst time
 Tau = 30e-6  # Pulse repetition time

9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/ADAR1000_AGC.cpp

@@ -0,0 +1,116 @@
+// ADAR1000_AGC.cpp -- STM32 outer-loop AGC implementation
+//
+// See ADAR1000_AGC.h for architecture overview.
+
+#include "ADAR1000_AGC.h"
+#include "ADAR1000_Manager.h"
+#include "diag_log.h"
+
+#include <cstring>
+
+// ---------------------------------------------------------------------------
+// Constructor -- set all config fields to safe defaults
+// ---------------------------------------------------------------------------
+ADAR1000_AGC::ADAR1000_AGC()
+    : agc_base_gain(ADAR1000Manager::kDefaultRxVgaGain) // 30
+    , gain_step_down(4)
+    , gain_step_up(1)
+    , min_gain(0)
+    , max_gain(127)
+    , holdoff_frames(4)
+    , enabled(true)
+    , holdoff_counter(0)
+    , last_saturated(false)
+    , saturation_event_count(0)
+{
+    memset(cal_offset, 0, sizeof(cal_offset));
+}
+
+// ---------------------------------------------------------------------------
+// update -- called once per frame with the FPGA DIG_5 saturation flag
+//
+// Returns true if agc_base_gain changed (caller should then applyGain).
+// ---------------------------------------------------------------------------
+void ADAR1000_AGC::update(bool fpga_saturation)
+{
+    if (!enabled)
+        return;
+
+    last_saturated = fpga_saturation;
+
+    if (fpga_saturation) {
+        // Attack: reduce gain immediately
+        saturation_event_count++;
+        holdoff_counter = 0;
+
+        if (agc_base_gain >= gain_step_down + min_gain) {
+            agc_base_gain -= gain_step_down;
+        } else {
+            agc_base_gain = min_gain;
+        }
+
+        DIAG("AGC", "SAT detected -- gain_base -> %u  (events=%lu)",
+             (unsigned)agc_base_gain, (unsigned long)saturation_event_count);
+
+    } else {
+        // Recovery: wait for holdoff, then increase gain
+        holdoff_counter++;
+
+        if (holdoff_counter >= holdoff_frames) {
+            holdoff_counter = 0;
+
+            if (agc_base_gain + gain_step_up <= max_gain) {
+                agc_base_gain += gain_step_up;
+            } else {
+                agc_base_gain = max_gain;
+            }
+
+            DIAG("AGC", "Recovery step -- gain_base -> %u", (unsigned)agc_base_gain);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// applyGain -- write effective gain to all 16 RX VGA channels
+//
+// Uses the Manager's adarSetRxVgaGain which takes 1-based channel indices
+// (matching the convention in setBeamAngle).
+// ---------------------------------------------------------------------------
+void ADAR1000_AGC::applyGain(ADAR1000Manager &mgr)
+{
+    for (uint8_t dev = 0; dev < AGC_NUM_DEVICES; ++dev) {
+        for (uint8_t ch = 0; ch < AGC_NUM_CHANNELS; ++ch) {
+            uint8_t gain = effectiveGain(dev * AGC_NUM_CHANNELS + ch);
+            // Channel parameter is 1-based per Manager convention
+            mgr.adarSetRxVgaGain(dev, ch + 1, gain, BROADCAST_OFF);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// resetState -- clear runtime counters, preserve configuration
+// ---------------------------------------------------------------------------
+void ADAR1000_AGC::resetState()
+{
+    holdoff_counter = 0;
+    last_saturated = false;
+    saturation_event_count = 0;
+}
+
+// ---------------------------------------------------------------------------
+// effectiveGain -- compute clamped per-channel gain
+// ---------------------------------------------------------------------------
+uint8_t ADAR1000_AGC::effectiveGain(uint8_t channel_index) const
+{
+    if (channel_index >= AGC_TOTAL_CHANNELS)
+        return min_gain;  // safety fallback — OOB channels get minimum gain
+
+    int16_t raw = static_cast<int16_t>(agc_base_gain) + cal_offset[channel_index];
+
+    if (raw < static_cast<int16_t>(min_gain))
+        return min_gain;
+    if (raw > static_cast<int16_t>(max_gain))
+        return max_gain;
+
+    return static_cast<uint8_t>(raw);
+}

9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/ADAR1000_AGC.h

@@ -0,0 +1,97 @@
+// ADAR1000_AGC.h -- STM32 outer-loop AGC for ADAR1000 RX VGA gain
+//
+// Adjusts the analog VGA common-mode gain on each ADAR1000 RX channel based on
+// the FPGA's saturation flag (DIG_5 / PD13).  Runs once per radar frame
+// (~258 ms) in the main loop, after runRadarPulseSequence().
+//
+// Architecture:
+//   - Inner loop (FPGA, per-sample): rx_gain_control auto-adjusts digital
+//     gain_shift based on peak magnitude / saturation.  Range ±42 dB.
+//   - Outer loop (THIS MODULE, per-frame): reads FPGA DIG_5 GPIO.  If
+//     saturation detected, reduces agc_base_gain immediately (attack).  If no
+//     saturation for holdoff_frames, increases agc_base_gain (decay/recovery).
+//
+// Per-channel gain formula:
+//   VGA[dev][ch] = clamp(agc_base_gain + cal_offset[dev*4+ch], min_gain, max_gain)
+//
+// The cal_offset array allows per-element calibration to correct inter-channel
+// gain imbalance.  Default is all zeros (uniform gain).
+
+#ifndef ADAR1000_AGC_H
+#define ADAR1000_AGC_H
+
+#include <stdint.h>
+
+// Forward-declare to avoid pulling in the full ADAR1000_Manager header here.
+// The .cpp includes the real header.
+class ADAR1000Manager;
+
+// Number of ADAR1000 devices
+#define AGC_NUM_DEVICES   4
+// Number of channels per ADAR1000
+#define AGC_NUM_CHANNELS  4
+// Total RX channels
+#define AGC_TOTAL_CHANNELS (AGC_NUM_DEVICES * AGC_NUM_CHANNELS)
+
+class ADAR1000_AGC {
+public:
+    // --- Configuration (public for easy field-testing / GUI override) ---
+
+    // Common-mode base gain (raw ADAR1000 register value, 0-255).
+    // Default matches ADAR1000Manager::kDefaultRxVgaGain = 30.
+    uint8_t agc_base_gain;
+
+    // Per-channel calibration offset (signed, added to agc_base_gain).
+    // Index = device*4 + channel.  Default: all 0.
+    int8_t cal_offset[AGC_TOTAL_CHANNELS];
+
+    // How much to decrease agc_base_gain per frame when saturated (attack).
+    uint8_t gain_step_down;
+
+    // How much to increase agc_base_gain per frame when recovering (decay).
+    uint8_t gain_step_up;
+
+    // Minimum allowed agc_base_gain (floor).
+    uint8_t min_gain;
+
+    // Maximum allowed agc_base_gain (ceiling).
+    uint8_t max_gain;
+
+    // Number of consecutive non-saturated frames required before gain-up.
+    uint8_t holdoff_frames;
+
+    // Master enable.  When false, update() is a no-op.
+    bool enabled;
+
+    // --- Runtime state (read-only for diagnostics) ---
+
+    // Consecutive non-saturated frame counter (resets on saturation).
+    uint8_t holdoff_counter;
+
+    // True if the last update() saw saturation.
+    bool last_saturated;
+
+    // Total saturation events since reset/construction.
+    uint32_t saturation_event_count;
+
+    // --- Methods ---
+
+    ADAR1000_AGC();
+
+    // Call once per frame after runRadarPulseSequence().
+    // fpga_saturation: result of HAL_GPIO_ReadPin(GPIOD, GPIO_PIN_13) == GPIO_PIN_SET
+    void update(bool fpga_saturation);
+
+    // Apply the current gain to all 16 RX VGA channels via the Manager.
+    void applyGain(ADAR1000Manager &mgr);
+
+    // Reset runtime state (holdoff counter, saturation count) without
+    // changing configuration.
+    void resetState();
+
+    // Compute the effective gain for a specific channel index (0-15),
+    // clamped to [min_gain, max_gain].  Useful for diagnostics.
+    uint8_t effectiveGain(uint8_t channel_index) const;
+};
+
+#endif // ADAR1000_AGC_H

9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/RadarSettings.cpp

@@ -6,16 +6,16 @@ RadarSettings::RadarSettings() {
 }
 
 void RadarSettings::resetToDefaults() {
-    system_frequency = 10.0e9;    // 10 GHz
+    system_frequency = 10.5e9;    // 10.5 GHz (PLFM TX LO, ADF4382 config)
-    chirp_duration_1 = 30.0e-6;   // 30 �s
+    chirp_duration_1 = 30.0e-6;   // 30 µs
-    chirp_duration_2 = 0.5e-6;    // 0.5 �s
+    chirp_duration_2 = 0.5e-6;    // 0.5 µs
     chirps_per_position = 32;
     freq_min = 10.0e6;           // 10 MHz
     freq_max = 30.0e6;           // 30 MHz
     prf1 = 1000.0;               // 1 kHz
     prf2 = 2000.0;               // 2 kHz
-    max_distance = 50000.0;      // 50 km
+    max_distance = 3072.0;       // 3072 m (512 bins × 6 m, 3 km mode)
-    map_size = 50000.0;          // 50 km
+    map_size = 3072.0;           // 3072 m
     
     settings_valid = true;
 }
@@ -88,7 +88,7 @@ bool RadarSettings::validateSettings() {
     if (prf1 < 100 || prf1 > 10000) return false;
     if (prf2 < 100 || prf2 > 10000) return false;
     if (max_distance < 100 || max_distance > 100000) return false;
-    if (map_size < 1000 || map_size > 200000) return false;
+    if (map_size < 100 || map_size > 200000) return false;
     
     return true;
 }

9_Firmware/9_1_Microcontroller/9_1_1_C_Cpp_Libraries/USBHandler.cpp

@@ -43,6 +43,11 @@ void USBHandler::processStartFlag(const uint8_t* data, uint32_t length) {
     // Start flag: bytes [23, 46, 158, 237]
     const uint8_t START_FLAG[] = {23, 46, 158, 237};
     
+    // Guard: need at least 4 bytes to contain a start flag.
+    // Without this, length - 4 wraps to ~4 billion (uint32_t unsigned underflow)
+    // and the loop reads far past the buffer boundary.
+    if (length < 4) return;
+    
     // Check if start flag is in the received data
     for (uint32_t i = 0; i <= length - 4; i++) {
         if (memcmp(data + i, START_FLAG, 4) == 0) {

9_Firmware/9_1_Microcontroller/9_1_3_C_Cpp_Code/main.cpp

@@ -23,6 +23,7 @@
 #include "usbd_cdc_if.h"
 #include "adar1000.h"
 #include "ADAR1000_Manager.h"
+#include "ADAR1000_AGC.h"
 extern "C" {
 #include "ad9523.h"
 }
@@ -224,6 +225,7 @@ extern SPI_HandleTypeDef hspi4;
 //ADAR1000
 
 ADAR1000Manager adarManager;
+ADAR1000_AGC    outerAgc;
 static uint8_t matrix1[15][16];
 static uint8_t matrix2[15][16];
 static uint8_t vector_0[16] = {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0};
@@ -639,6 +641,7 @@ SystemError_t checkSystemHealth(void) {
         if (s0 == GPIO_PIN_RESET || s1 == GPIO_PIN_RESET) {
             current_error = ERROR_AD9523_CLOCK;
             DIAG_ERR("CLK", "AD9523 clock health check FAILED (STATUS0=%d STATUS1=%d)", s0, s1);
+            return current_error;
         }
         last_clock_check = HAL_GetTick();
     }
@@ -649,10 +652,12 @@ SystemError_t checkSystemHealth(void) {
         if (!tx_locked) {
             current_error = ERROR_ADF4382_TX_UNLOCK;
             DIAG_ERR("LO", "Health check: TX LO UNLOCKED");
+            return current_error;
         }
         if (!rx_locked) {
             current_error = ERROR_ADF4382_RX_UNLOCK;
             DIAG_ERR("LO", "Health check: RX LO UNLOCKED");
+            return current_error;
         }
     }
 
@@ -661,14 +666,14 @@ SystemError_t checkSystemHealth(void) {
         if (!adarManager.verifyDeviceCommunication(i)) {
             current_error = ERROR_ADAR1000_COMM;
             DIAG_ERR("BF", "Health check: ADAR1000 #%d comm FAILED", i);
-            break;
+            return current_error;
         }
 
         float temp = adarManager.readTemperature(i);
         if (temp > 85.0f) {
             current_error = ERROR_ADAR1000_TEMP;
             DIAG_ERR("BF", "Health check: ADAR1000 #%d OVERTEMP %.1fC > 85C", i, temp);
-            break;
+            return current_error;
         }
     }
 
@@ -678,6 +683,7 @@ SystemError_t checkSystemHealth(void) {
         if (!GY85_Update(&imu)) {
             current_error = ERROR_IMU_COMM;
             DIAG_ERR("IMU", "Health check: GY85_Update() FAILED");
+            return current_error;
         }
         last_imu_check = HAL_GetTick();
     }
@@ -689,6 +695,7 @@ SystemError_t checkSystemHealth(void) {
         if (pressure < 30000.0 || pressure > 110000.0 || isnan(pressure)) {
             current_error = ERROR_BMP180_COMM;
             DIAG_ERR("SYS", "Health check: BMP180 pressure out of range: %.0f", pressure);
+            return current_error;
         }
         last_bmp_check = HAL_GetTick();
     }
@@ -701,6 +708,7 @@ SystemError_t checkSystemHealth(void) {
     if (HAL_GetTick() - last_gps_fix > 30000) {
         current_error = ERROR_GPS_COMM;
         DIAG_WARN("SYS", "Health check: GPS no fix for >30s");
+        return current_error;
     }
 
     // 7. Check RF Power Amplifier Current
@@ -709,12 +717,12 @@ SystemError_t checkSystemHealth(void) {
             if (Idq_reading[i] > 2.5f) {
                 current_error = ERROR_RF_PA_OVERCURRENT;
                 DIAG_ERR("PA", "Health check: PA ch%d OVERCURRENT Idq=%.3fA > 2.5A", i, Idq_reading[i]);
-                break;
+                return current_error;
             }
             if (Idq_reading[i] < 0.1f) {
                 current_error = ERROR_RF_PA_BIAS;
                 DIAG_ERR("PA", "Health check: PA ch%d BIAS FAULT Idq=%.3fA < 0.1A", i, Idq_reading[i]);
-                break;
+                return current_error;
             }
         }
     }
@@ -723,6 +731,7 @@ SystemError_t checkSystemHealth(void) {
     if (temperature > 75.0f) {
         current_error = ERROR_TEMPERATURE_HIGH;
         DIAG_ERR("SYS", "Health check: System OVERTEMP %.1fC > 75C", temperature);
+        return current_error;
     }
 
     // 9. Simple watchdog check
@@ -730,6 +739,7 @@ SystemError_t checkSystemHealth(void) {
     if (HAL_GetTick() - last_health_check > 60000) {
         current_error = ERROR_WATCHDOG_TIMEOUT;
         DIAG_ERR("SYS", "Health check: Watchdog timeout (>60s since last check)");
+        return current_error;
     }
     last_health_check = HAL_GetTick();
 
@@ -875,8 +885,22 @@ void handleSystemError(SystemError_t error) {
         HAL_Delay(200);
     }
 
-    // Critical errors trigger emergency shutdown
+    // Critical errors trigger emergency shutdown.
-    if (error >= ERROR_RF_PA_OVERCURRENT && error <= ERROR_POWER_SUPPLY) {
+    //
+    // Safety-critical range: any fault that can damage the PAs or leave the
+    // system in an undefined state must cut the RF rails via Emergency_Stop().
+    // This covers:
+    //   ERROR_RF_PA_OVERCURRENT .. ERROR_POWER_SUPPLY (9..13) -- PA/supply faults
+    //   ERROR_TEMPERATURE_HIGH  (14) -- >75 C on the PA thermal sensors;
+    //                                  without cutting bias + 5V/5V5/RFPA rails
+    //                                  the GaN QPA2962 stage can thermal-runaway.
+    //   ERROR_WATCHDOG_TIMEOUT  (16) -- health-check loop has stalled (>60 s);
+    //                                  transmitter state is unknown, safest to
+    //                                  latch Emergency_Stop rather than rely on
+    //                                  IWDG reset (which re-energises the rails).
+    if ((error >= ERROR_RF_PA_OVERCURRENT && error <= ERROR_POWER_SUPPLY) ||
+        error == ERROR_TEMPERATURE_HIGH ||
+        error == ERROR_WATCHDOG_TIMEOUT) {
         DIAG_ERR("SYS", "CRITICAL ERROR (code %d: %s) -- initiating Emergency_Stop()", error, error_strings[error]);
         snprintf(error_msg, sizeof(error_msg),
                  "CRITICAL ERROR! Initiating emergency shutdown.\r\n");
@@ -919,38 +943,41 @@ bool checkSystemHealthStatus(void) {
 // Get system status for GUI
 // Get system status for GUI with 8 temperature variables
 void getSystemStatusForGUI(char* status_buffer, size_t buffer_size) {
-    char temp_buffer[200];
+    // Build status string directly in the output buffer using offset-tracked
-    char final_status[500] = "System Status: ";
+    // snprintf.  Each call returns the number of chars written (excluding NUL),
+    // so we advance 'off' and shrink 'rem' to guarantee we never overflow.
+    size_t off = 0;
+    size_t rem = buffer_size;
+    int w;
 
     // Basic status
     if (system_emergency_state) {
-        strcat(final_status, "EMERGENCY_STOP|");
+        w = snprintf(status_buffer + off, rem, "System Status: EMERGENCY_STOP|");
     } else {
-        strcat(final_status, "NORMAL|");
+        w = snprintf(status_buffer + off, rem, "System Status: NORMAL|");
     }
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // Error information
-    snprintf(temp_buffer, sizeof(temp_buffer), "LastError:%d|ErrorCount:%lu|",
+    w = snprintf(status_buffer + off, rem, "LastError:%d|ErrorCount:%lu|",
-             last_error, error_count);
+                 last_error, error_count);
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // Sensor status
-    snprintf(temp_buffer, sizeof(temp_buffer), "IMU:%.1f,%.1f,%.1f|GPS:%.6f,%.6f|ALT:%.1f|",
+    w = snprintf(status_buffer + off, rem, "IMU:%.1f,%.1f,%.1f|GPS:%.6f,%.6f|ALT:%.1f|",
-             Pitch_Sensor, Roll_Sensor, Yaw_Sensor,
+                 Pitch_Sensor, Roll_Sensor, Yaw_Sensor,
-             RADAR_Latitude, RADAR_Longitude, RADAR_Altitude);
+                 RADAR_Latitude, RADAR_Longitude, RADAR_Altitude);
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // LO Status
     bool tx_locked, rx_locked;
     ADF4382A_CheckLockStatus(&lo_manager, &tx_locked, &rx_locked);
-    snprintf(temp_buffer, sizeof(temp_buffer), "LO_TX:%s|LO_RX:%s|",
+    w = snprintf(status_buffer + off, rem, "LO_TX:%s|LO_RX:%s|",
-             tx_locked ? "LOCKED" : "UNLOCKED",
+                 tx_locked ? "LOCKED" : "UNLOCKED",
-             rx_locked ? "LOCKED" : "UNLOCKED");
+                 rx_locked ? "LOCKED" : "UNLOCKED");
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // Temperature readings (8 variables)
-    // You'll need to populate these temperature values from your sensors
-    // For now, I'll show how to format them - replace with actual temperature readings
     Temperature_1 = ADS7830_Measure_SingleEnded(&hadc3, 0);
     Temperature_2 = ADS7830_Measure_SingleEnded(&hadc3, 1);
     Temperature_3 = ADS7830_Measure_SingleEnded(&hadc3, 2);
@@ -961,11 +988,11 @@ void getSystemStatusForGUI(char* status_buffer, size_t buffer_size) {
     Temperature_8 = ADS7830_Measure_SingleEnded(&hadc3, 7);
 
     // Format all 8 temperature variables
-    snprintf(temp_buffer, sizeof(temp_buffer),
+    w = snprintf(status_buffer + off, rem,
-             "T1:%.1f|T2:%.1f|T3:%.1f|T4:%.1f|T5:%.1f|T6:%.1f|T7:%.1f|T8:%.1f|",
+                 "T1:%.1f|T2:%.1f|T3:%.1f|T4:%.1f|T5:%.1f|T6:%.1f|T7:%.1f|T8:%.1f|",
-             Temperature_1, Temperature_2, Temperature_3, Temperature_4,
+                 Temperature_1, Temperature_2, Temperature_3, Temperature_4,
-             Temperature_5, Temperature_6, Temperature_7, Temperature_8);
+                 Temperature_5, Temperature_6, Temperature_7, Temperature_8);
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
     // RF Power Amplifier status (if enabled)
     if (PowerAmplifier) {
@@ -975,18 +1002,17 @@ void getSystemStatusForGUI(char* status_buffer, size_t buffer_size) {
         }
         avg_current /= 16.0f;
 
-        snprintf(temp_buffer, sizeof(temp_buffer), "PA_AvgCurrent:%.2f|PA_Enabled:%d|",
+        w = snprintf(status_buffer + off, rem, "PA_AvgCurrent:%.2f|PA_Enabled:%d|",
-                 avg_current, PowerAmplifier);
+                     avg_current, PowerAmplifier);
-        strcat(final_status, temp_buffer);
+        if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
     }
 
     // Radar operation status
-    snprintf(temp_buffer, sizeof(temp_buffer), "BeamPos:%d|Azimuth:%d|ChirpCount:%d|",
+    w = snprintf(status_buffer + off, rem, "BeamPos:%d|Azimuth:%d|ChirpCount:%d|",
-             n, y, m);
+                 n, y, m);
-    strcat(final_status, temp_buffer);
+    if (w > 0 && (size_t)w < rem) { off += (size_t)w; rem -= (size_t)w; }
 
-    // Copy to output buffer
+    // NUL termination guaranteed by snprintf, but be safe
-    strncpy(status_buffer, final_status, buffer_size - 1);
     status_buffer[buffer_size - 1] = '\0';
 }
 
@@ -1995,12 +2021,13 @@ int main(void)
 	        HAL_UART_Transmit(&huart3, (uint8_t*)emergency_msg, strlen(emergency_msg), 1000);
 	        DIAG_ERR("SYS", "SAFE MODE ACTIVE -- blinking all LEDs, waiting for system_emergency_state clear");
 
-	        // Blink all LEDs to indicate safe mode
+	        // Blink all LEDs to indicate safe mode (500ms period, visible to operator)
 	        while (system_emergency_state) {
 	            HAL_GPIO_TogglePin(LED_1_GPIO_Port, LED_1_Pin);
 	            HAL_GPIO_TogglePin(LED_2_GPIO_Port, LED_2_Pin);
 	            HAL_GPIO_TogglePin(LED_3_GPIO_Port, LED_3_Pin);
 	            HAL_GPIO_TogglePin(LED_4_GPIO_Port, LED_4_Pin);
+	            HAL_Delay(250);
 	        }
 	        DIAG("SYS", "Exited safe mode blink loop -- system_emergency_state cleared");
 	    }
@@ -2114,6 +2141,16 @@ int main(void)
 
       runRadarPulseSequence();
 
+      /* [AGC] Outer-loop AGC: read FPGA saturation flag (DIG_5 / PD13),
+       * adjust ADAR1000 VGA common gain once per radar frame (~258 ms).
+       * Only run when AGC is enabled — otherwise leave VGA gains untouched. */
+      if (outerAgc.enabled) {
+          bool sat = HAL_GPIO_ReadPin(FPGA_DIG5_SAT_GPIO_Port,
+                                      FPGA_DIG5_SAT_Pin) == GPIO_PIN_SET;
+          outerAgc.update(sat);
+          outerAgc.applyGain(adarManager);
+      }
+
       /* [GAP-3 FIX 2] Kick hardware watchdog — if we don't reach here within
        * ~4 s, the IWDG resets the MCU automatically. */
       HAL_IWDG_Refresh(&hiwdg);

9_Firmware/9_1_Microcontroller/9_1_3_C_Cpp_Code/main.h

@@ -141,6 +141,15 @@ void Error_Handler(void);
 #define EN_DIS_RFPA_VDD_GPIO_Port GPIOD
 #define EN_DIS_COOLING_Pin GPIO_PIN_7
 #define EN_DIS_COOLING_GPIO_Port GPIOD
+
+/* FPGA digital I/O (directly connected GPIOs) */
+#define FPGA_DIG5_SAT_Pin       GPIO_PIN_13
+#define FPGA_DIG5_SAT_GPIO_Port GPIOD
+#define FPGA_DIG6_Pin           GPIO_PIN_14
+#define FPGA_DIG6_GPIO_Port     GPIOD
+#define FPGA_DIG7_Pin           GPIO_PIN_15
+#define FPGA_DIG7_GPIO_Port     GPIOD
+
 #define ADF4382_RX_CE_Pin GPIO_PIN_9
 #define ADF4382_RX_CE_GPIO_Port GPIOG
 #define ADF4382_RX_CS_Pin GPIO_PIN_10

9_Firmware/9_1_Microcontroller/tests/.gitignore

@@ -18,3 +18,10 @@ test_bug12_pa_cal_loop_inverted
 test_bug13_dac2_adc_buffer_mismatch
 test_bug14_diag_section_args
 test_bug15_htim3_dangling_extern
+test_agc_outer_loop
+test_gap3_emergency_state_ordering
+test_gap3_emergency_stop_rails
+test_gap3_idq_periodic_reread
+test_gap3_iwdg_config
+test_gap3_temperature_max
+test_gap3_overtemp_emergency_stop

9_Firmware/9_1_Microcontroller/tests/Makefile

@@ -16,10 +16,17 @@
 ################################################################################
 
 CC       := cc
+CXX      := c++
 CFLAGS   := -std=c11 -Wall -Wextra -Wno-unused-parameter -g -O0
+CXXFLAGS := -std=c++17 -Wall -Wextra -Wno-unused-parameter -g -O0
 # Shim headers come FIRST so they override real headers
 INCLUDES := -Ishims -I. -I../9_1_1_C_Cpp_Libraries
 
+# C++ library directory (AGC, ADAR1000 Manager)
+CXX_LIB_DIR := ../9_1_1_C_Cpp_Libraries
+CXX_SRCS    := $(CXX_LIB_DIR)/ADAR1000_AGC.cpp $(CXX_LIB_DIR)/ADAR1000_Manager.cpp
+CXX_OBJS    := ADAR1000_AGC.o ADAR1000_Manager.o
+
 # Real source files compiled against mock headers
 REAL_SRC := ../9_1_1_C_Cpp_Libraries/adf4382a_manager.c
 
@@ -57,16 +64,21 @@ TESTS_STANDALONE := test_bug12_pa_cal_loop_inverted \
                     test_gap3_iwdg_config \
                     test_gap3_temperature_max \
                     test_gap3_idq_periodic_reread \
-                    test_gap3_emergency_state_ordering
+                    test_gap3_emergency_state_ordering \
+                    test_gap3_overtemp_emergency_stop
 
 # Tests that need platform_noos_stm32.o + mocks
 TESTS_WITH_PLATFORM := test_bug11_platform_spi_transmit_only
 
-ALL_TESTS := $(TESTS_WITH_REAL) $(TESTS_MOCK_ONLY) $(TESTS_STANDALONE) $(TESTS_WITH_PLATFORM)
+# C++ tests (AGC outer loop)
+TESTS_WITH_CXX := test_agc_outer_loop
+
+ALL_TESTS := $(TESTS_WITH_REAL) $(TESTS_MOCK_ONLY) $(TESTS_STANDALONE) $(TESTS_WITH_PLATFORM) $(TESTS_WITH_CXX)
 
 .PHONY: all build test clean \
         $(addprefix test_,bug1 bug2 bug3 bug4 bug5 bug6 bug7 bug8 bug9 bug10 bug11 bug12 bug13 bug14 bug15) \
-        test_gap3_estop test_gap3_iwdg test_gap3_temp test_gap3_idq test_gap3_order
+        test_gap3_estop test_gap3_iwdg test_gap3_temp test_gap3_idq test_gap3_order \
+        test_gap3_overtemp
 
 all: build test
 
@@ -152,10 +164,31 @@ test_gap3_idq_periodic_reread: test_gap3_idq_periodic_reread.c
 test_gap3_emergency_state_ordering: test_gap3_emergency_state_ordering.c
 	$(CC) $(CFLAGS) $< -o $@
 
+test_gap3_overtemp_emergency_stop: test_gap3_overtemp_emergency_stop.c
+	$(CC) $(CFLAGS) $< -o $@
+
 # Tests that need platform_noos_stm32.o + mocks
 $(TESTS_WITH_PLATFORM): %: %.c $(MOCK_OBJS) $(PLATFORM_OBJ)
 	$(CC) $(CFLAGS) $(INCLUDES) $< $(MOCK_OBJS) $(PLATFORM_OBJ) -o $@
 
+# --- C++ object rules ---
+
+ADAR1000_AGC.o: $(CXX_LIB_DIR)/ADAR1000_AGC.cpp $(CXX_LIB_DIR)/ADAR1000_AGC.h
+	$(CXX) $(CXXFLAGS) $(INCLUDES) -c $< -o $@
+
+ADAR1000_Manager.o: $(CXX_LIB_DIR)/ADAR1000_Manager.cpp $(CXX_LIB_DIR)/ADAR1000_Manager.h
+	$(CXX) $(CXXFLAGS) $(INCLUDES) -c $< -o $@
+
+# --- C++ test binary rules ---
+
+test_agc_outer_loop: test_agc_outer_loop.cpp $(CXX_OBJS) $(MOCK_OBJS)
+	$(CXX) $(CXXFLAGS) $(INCLUDES) $< $(CXX_OBJS) $(MOCK_OBJS) -o $@
+
+# Convenience target
+.PHONY: test_agc
+test_agc: test_agc_outer_loop
+	./test_agc_outer_loop
+
 # --- Individual test targets ---
 
 test_bug1: test_bug1_timed_sync_init_ordering
@@ -218,6 +251,9 @@ test_gap3_idq: test_gap3_idq_periodic_reread
 test_gap3_order: test_gap3_emergency_state_ordering
 	./test_gap3_emergency_state_ordering
 
+test_gap3_overtemp: test_gap3_overtemp_emergency_stop
+	./test_gap3_overtemp_emergency_stop
+
 # --- Clean ---
 
 clean:

9_Firmware/9_1_Microcontroller/tests/shims/main.h

@@ -129,6 +129,14 @@ void Error_Handler(void);
 #define GYR_INT_Pin GPIO_PIN_8
 #define GYR_INT_GPIO_Port GPIOC
 
+/* FPGA digital I/O (directly connected GPIOs) */
+#define FPGA_DIG5_SAT_Pin       GPIO_PIN_13
+#define FPGA_DIG5_SAT_GPIO_Port GPIOD
+#define FPGA_DIG6_Pin           GPIO_PIN_14
+#define FPGA_DIG6_GPIO_Port     GPIOD
+#define FPGA_DIG7_Pin           GPIO_PIN_15
+#define FPGA_DIG7_GPIO_Port     GPIOD
+
 #ifdef __cplusplus
 }
 #endif

9_Firmware/9_1_Microcontroller/tests/stm32_hal_mock.c

@@ -175,7 +175,7 @@ void HAL_Delay(uint32_t Delay)
     mock_tick += Delay;
 }
 
-HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart, uint8_t *pData,
+HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart, const uint8_t *pData,
                                      uint16_t Size, uint32_t Timeout)
 {
     spy_push((SpyRecord){

9_Firmware/9_1_Microcontroller/tests/stm32_hal_mock.h

@@ -34,6 +34,10 @@ typedef uint32_t HAL_StatusTypeDef;
 
 #define HAL_MAX_DELAY 0xFFFFFFFFU
 
+#ifndef __NOP
+#define __NOP() ((void)0)
+#endif
+
 /* ========================= GPIO Types ============================ */
 
 typedef struct {
@@ -182,7 +186,7 @@ GPIO_PinState HAL_GPIO_ReadPin(GPIO_TypeDef *GPIOx, uint16_t GPIO_Pin);
 void          HAL_GPIO_TogglePin(GPIO_TypeDef *GPIOx, uint16_t GPIO_Pin);
 uint32_t      HAL_GetTick(void);
 void          HAL_Delay(uint32_t Delay);
-HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart, uint8_t *pData, uint16_t Size, uint32_t Timeout);
+HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart, const uint8_t *pData, uint16_t Size, uint32_t Timeout);
 
 /* ========================= SPI stubs ============================== */
 

9_Firmware/9_1_Microcontroller/tests/test_agc_outer_loop.cpp

@@ -0,0 +1,361 @@
+// test_agc_outer_loop.cpp -- C++ unit tests for ADAR1000_AGC outer-loop AGC
+//
+// Tests the STM32 outer-loop AGC class that adjusts ADAR1000 VGA gain based
+// on the FPGA's saturation flag.  Uses the existing HAL mock/spy framework.
+//
+// Build: c++ -std=c++17 ... (see Makefile TESTS_WITH_CXX rule)
+
+#include <cassert>
+#include <cstdio>
+#include <cstring>
+
+// Shim headers override real STM32/diag headers
+#include "stm32_hal_mock.h"
+#include "ADAR1000_AGC.h"
+#include "ADAR1000_Manager.h"
+
+// ---------------------------------------------------------------------------
+// Linker symbols required by ADAR1000_Manager.cpp (pulled in via main.h shim)
+// ---------------------------------------------------------------------------
+uint8_t GUI_start_flag_received = 0;
+uint8_t USB_Buffer[64] = {0};
+extern "C" void Error_Handler(void) {}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+static int tests_passed = 0;
+static int tests_total  = 0;
+
+#define RUN_TEST(fn)                                                           \
+    do {                                                                        \
+        tests_total++;                                                          \
+        printf("  [%2d] %-55s ", tests_total, #fn);                            \
+        fn();                                                                   \
+        tests_passed++;                                                         \
+        printf("PASS\n");                                                       \
+    } while (0)
+
+// ---------------------------------------------------------------------------
+// Test 1: Default construction matches design spec
+// ---------------------------------------------------------------------------
+static void test_defaults()
+{
+    ADAR1000_AGC agc;
+
+    assert(agc.agc_base_gain == 30);  // kDefaultRxVgaGain
+    assert(agc.gain_step_down == 4);
+    assert(agc.gain_step_up == 1);
+    assert(agc.min_gain == 0);
+    assert(agc.max_gain == 127);
+    assert(agc.holdoff_frames == 4);
+    assert(agc.enabled == true);
+    assert(agc.holdoff_counter == 0);
+    assert(agc.last_saturated == false);
+    assert(agc.saturation_event_count == 0);
+
+    // All cal offsets zero
+    for (int i = 0; i < AGC_TOTAL_CHANNELS; ++i) {
+        assert(agc.cal_offset[i] == 0);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Test 2: Saturation reduces gain by step_down
+// ---------------------------------------------------------------------------
+static void test_saturation_reduces_gain()
+{
+    ADAR1000_AGC agc;
+    uint8_t initial = agc.agc_base_gain;  // 30
+
+    agc.update(true);  // saturation
+
+    assert(agc.agc_base_gain == initial - agc.gain_step_down);  // 26
+    assert(agc.last_saturated == true);
+    assert(agc.holdoff_counter == 0);
+}
+
+// ---------------------------------------------------------------------------
+// Test 3: Holdoff prevents premature gain-up
+// ---------------------------------------------------------------------------
+static void test_holdoff_prevents_early_gain_up()
+{
+    ADAR1000_AGC agc;
+    agc.update(true);  // saturate once -> gain = 26
+    uint8_t after_sat = agc.agc_base_gain;
+
+    // Feed (holdoff_frames - 1) clear frames — should NOT increase gain
+    for (uint8_t i = 0; i < agc.holdoff_frames - 1; ++i) {
+        agc.update(false);
+        assert(agc.agc_base_gain == after_sat);
+    }
+
+    // holdoff_counter should be holdoff_frames - 1
+    assert(agc.holdoff_counter == agc.holdoff_frames - 1);
+}
+
+// ---------------------------------------------------------------------------
+// Test 4: Recovery after holdoff period
+// ---------------------------------------------------------------------------
+static void test_recovery_after_holdoff()
+{
+    ADAR1000_AGC agc;
+    agc.update(true);  // saturate -> gain = 26
+    uint8_t after_sat = agc.agc_base_gain;
+
+    // Feed exactly holdoff_frames clear frames
+    for (uint8_t i = 0; i < agc.holdoff_frames; ++i) {
+        agc.update(false);
+    }
+
+    assert(agc.agc_base_gain == after_sat + agc.gain_step_up);  // 27
+    assert(agc.holdoff_counter == 0);  // reset after recovery
+}
+
+// ---------------------------------------------------------------------------
+// Test 5: Min gain clamping
+// ---------------------------------------------------------------------------
+static void test_min_gain_clamp()
+{
+    ADAR1000_AGC agc;
+    agc.min_gain = 10;
+    agc.agc_base_gain = 12;
+    agc.gain_step_down = 4;
+
+    agc.update(true);  // 12 - 4 = 8, but min = 10
+    assert(agc.agc_base_gain == 10);
+
+    agc.update(true);  // already at min
+    assert(agc.agc_base_gain == 10);
+}
+
+// ---------------------------------------------------------------------------
+// Test 6: Max gain clamping
+// ---------------------------------------------------------------------------
+static void test_max_gain_clamp()
+{
+    ADAR1000_AGC agc;
+    agc.max_gain = 32;
+    agc.agc_base_gain = 31;
+    agc.gain_step_up = 2;
+    agc.holdoff_frames = 1;  // immediate recovery
+
+    agc.update(false);  // 31 + 2 = 33, but max = 32
+    assert(agc.agc_base_gain == 32);
+
+    agc.update(false);  // already at max
+    assert(agc.agc_base_gain == 32);
+}
+
+// ---------------------------------------------------------------------------
+// Test 7: Per-channel calibration offsets
+// ---------------------------------------------------------------------------
+static void test_calibration_offsets()
+{
+    ADAR1000_AGC agc;
+    agc.agc_base_gain = 30;
+    agc.min_gain = 0;
+    agc.max_gain = 60;
+
+    agc.cal_offset[0]  =  5;   // 30 + 5  = 35
+    agc.cal_offset[1]  = -10;  // 30 - 10 = 20
+    agc.cal_offset[15] =  40;  // 30 + 40 = 60 (clamped to max)
+
+    assert(agc.effectiveGain(0) == 35);
+    assert(agc.effectiveGain(1) == 20);
+    assert(agc.effectiveGain(15) == 60);  // clamped to max_gain
+
+    // Negative clamp
+    agc.cal_offset[2] = -50;   // 30 - 50 = -20, clamped to min_gain = 0
+    assert(agc.effectiveGain(2) == 0);
+
+    // Out-of-range index returns min_gain
+    assert(agc.effectiveGain(16) == agc.min_gain);
+}
+
+// ---------------------------------------------------------------------------
+// Test 8: Disabled AGC is a no-op
+// ---------------------------------------------------------------------------
+static void test_disabled_noop()
+{
+    ADAR1000_AGC agc;
+    agc.enabled = false;
+    uint8_t original = agc.agc_base_gain;
+
+    agc.update(true);   // should be ignored
+    assert(agc.agc_base_gain == original);
+    assert(agc.last_saturated == false);  // not updated when disabled
+    assert(agc.saturation_event_count == 0);
+
+    agc.update(false);  // also ignored
+    assert(agc.agc_base_gain == original);
+}
+
+// ---------------------------------------------------------------------------
+// Test 9: applyGain() produces correct SPI writes
+// ---------------------------------------------------------------------------
+static void test_apply_gain_spi()
+{
+    spy_reset();
+
+    ADAR1000Manager mgr;  // creates 4 devices
+    ADAR1000_AGC agc;
+    agc.agc_base_gain = 42;
+
+    agc.applyGain(mgr);
+
+    // Each channel: adarSetRxVgaGain -> adarWrite(gain) + adarWrite(LOAD_WORKING)
+    // Each adarWrite: CS_low (GPIO_WRITE) + SPI_TRANSMIT + CS_high (GPIO_WRITE)
+    // = 3 spy records per adarWrite
+    // = 6 spy records per channel
+    // = 16 channels * 6 = 96 total spy records
+
+    // Verify SPI transmit count: 2 SPI calls per channel * 16 channels = 32
+    int spi_count = spy_count_type(SPY_SPI_TRANSMIT);
+    assert(spi_count == 32);
+
+    // Verify GPIO write count: 4 GPIO writes per channel (CS low + CS high for each of 2 adarWrite calls)
+    int gpio_writes = spy_count_type(SPY_GPIO_WRITE);
+    assert(gpio_writes == 64);  // 16 ch * 2 adarWrite * 2 GPIO each
+}
+
+// ---------------------------------------------------------------------------
+// Test 10: resetState() clears counters but preserves config
+// ---------------------------------------------------------------------------
+static void test_reset_preserves_config()
+{
+    ADAR1000_AGC agc;
+    agc.agc_base_gain = 42;
+    agc.gain_step_down = 8;
+    agc.cal_offset[3] = -5;
+
+    // Generate some state
+    agc.update(true);
+    agc.update(true);
+    assert(agc.saturation_event_count == 2);
+    assert(agc.last_saturated == true);
+
+    agc.resetState();
+
+    // State cleared
+    assert(agc.holdoff_counter == 0);
+    assert(agc.last_saturated == false);
+    assert(agc.saturation_event_count == 0);
+
+    // Config preserved
+    assert(agc.agc_base_gain == 42 - 8 - 8);  // two saturations applied before reset
+    assert(agc.gain_step_down == 8);
+    assert(agc.cal_offset[3] == -5);
+}
+
+// ---------------------------------------------------------------------------
+// Test 11: Saturation counter increments correctly
+// ---------------------------------------------------------------------------
+static void test_saturation_counter()
+{
+    ADAR1000_AGC agc;
+
+    for (int i = 0; i < 10; ++i) {
+        agc.update(true);
+    }
+    assert(agc.saturation_event_count == 10);
+
+    // Clear frames don't increment saturation count
+    for (int i = 0; i < 5; ++i) {
+        agc.update(false);
+    }
+    assert(agc.saturation_event_count == 10);
+}
+
+// ---------------------------------------------------------------------------
+// Test 12: Mixed saturation/clear sequence
+// ---------------------------------------------------------------------------
+static void test_mixed_sequence()
+{
+    ADAR1000_AGC agc;
+    agc.agc_base_gain = 30;
+    agc.gain_step_down = 4;
+    agc.gain_step_up = 1;
+    agc.holdoff_frames = 3;
+
+    // Saturate: 30 -> 26
+    agc.update(true);
+    assert(agc.agc_base_gain == 26);
+    assert(agc.holdoff_counter == 0);
+
+    // 2 clear frames (not enough for recovery)
+    agc.update(false);
+    agc.update(false);
+    assert(agc.agc_base_gain == 26);
+    assert(agc.holdoff_counter == 2);
+
+    // Saturate again: 26 -> 22, counter resets
+    agc.update(true);
+    assert(agc.agc_base_gain == 22);
+    assert(agc.holdoff_counter == 0);
+    assert(agc.saturation_event_count == 2);
+
+    // 3 clear frames -> recovery: 22 -> 23
+    agc.update(false);
+    agc.update(false);
+    agc.update(false);
+    assert(agc.agc_base_gain == 23);
+    assert(agc.holdoff_counter == 0);
+
+    // 3 more clear -> 23 -> 24
+    agc.update(false);
+    agc.update(false);
+    agc.update(false);
+    assert(agc.agc_base_gain == 24);
+}
+
+// ---------------------------------------------------------------------------
+// Test 13: Effective gain with edge-case base_gain values
+// ---------------------------------------------------------------------------
+static void test_effective_gain_edge_cases()
+{
+    ADAR1000_AGC agc;
+    agc.min_gain = 5;
+    agc.max_gain = 250;
+
+    // Base gain at zero with positive offset
+    agc.agc_base_gain = 0;
+    agc.cal_offset[0] = 3;
+    assert(agc.effectiveGain(0) == 5);  // 0 + 3 = 3, clamped to min_gain=5
+
+    // Base gain at max with zero offset
+    agc.agc_base_gain = 250;
+    agc.cal_offset[0] = 0;
+    assert(agc.effectiveGain(0) == 250);
+
+    // Base gain at max with positive offset -> clamped
+    agc.agc_base_gain = 250;
+    agc.cal_offset[0] = 10;
+    assert(agc.effectiveGain(0) == 250);  // clamped to max_gain
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+int main()
+{
+    printf("=== ADAR1000_AGC Outer-Loop Unit Tests ===\n");
+
+    RUN_TEST(test_defaults);
+    RUN_TEST(test_saturation_reduces_gain);
+    RUN_TEST(test_holdoff_prevents_early_gain_up);
+    RUN_TEST(test_recovery_after_holdoff);
+    RUN_TEST(test_min_gain_clamp);
+    RUN_TEST(test_max_gain_clamp);
+    RUN_TEST(test_calibration_offsets);
+    RUN_TEST(test_disabled_noop);
+    RUN_TEST(test_apply_gain_spi);
+    RUN_TEST(test_reset_preserves_config);
+    RUN_TEST(test_saturation_counter);
+    RUN_TEST(test_mixed_sequence);
+    RUN_TEST(test_effective_gain_edge_cases);
+
+    printf("=== Results: %d/%d passed ===\n", tests_passed, tests_total);
+    return (tests_passed == tests_total) ? 0 : 1;
+}

9_Firmware/9_1_Microcontroller/tests/test_gap3_emergency_state_ordering.c

@@ -34,22 +34,25 @@ static void Mock_Emergency_Stop(void)
     state_was_true_when_estop_called = system_emergency_state;
 }
 
-/* Error codes (subset matching main.cpp) */
+/* Error codes (subset matching main.cpp SystemError_t) */
 typedef enum {
     ERROR_NONE = 0,
     ERROR_RF_PA_OVERCURRENT = 9,
     ERROR_RF_PA_BIAS = 10,
-    ERROR_STEPPER_FAULT = 11,
+    ERROR_STEPPER_MOTOR = 11,
     ERROR_FPGA_COMM = 12,
     ERROR_POWER_SUPPLY = 13,
     ERROR_TEMPERATURE_HIGH = 14,
+    ERROR_MEMORY_ALLOC = 15,
+    ERROR_WATCHDOG_TIMEOUT = 16,
 } SystemError_t;
 
-/* Extracted critical-error handling logic (post-fix ordering) */
+/* Extracted critical-error handling logic (matches post-fix main.cpp predicate) */
 static void simulate_handleSystemError_critical(SystemError_t error)
 {
-    /* Only critical errors (PA overcurrent through power supply) trigger e-stop */
+    if ((error >= ERROR_RF_PA_OVERCURRENT && error <= ERROR_POWER_SUPPLY) ||
-    if (error >= ERROR_RF_PA_OVERCURRENT && error <= ERROR_POWER_SUPPLY) {
+        error == ERROR_TEMPERATURE_HIGH ||
+        error == ERROR_WATCHDOG_TIMEOUT) {
         /* FIX 5: set flag BEFORE calling Emergency_Stop */
         system_emergency_state = true;
         Mock_Emergency_Stop();
@@ -93,17 +96,39 @@ int main(void)
     assert(state_was_true_when_estop_called == true);
     printf("PASS\n");
 
-    /* Test 4: Non-critical error → no e-stop, flag stays false */
+    /* Test 4: Overtemp → MUST trigger e-stop (was incorrectly non-critical before fix) */
-    printf("  Test 4: Non-critical error (no e-stop)... ");
+    printf("  Test 4: Overtemp triggers e-stop... ");
     system_emergency_state = false;
     emergency_stop_called = false;
+    state_was_true_when_estop_called = false;
     simulate_handleSystemError_critical(ERROR_TEMPERATURE_HIGH);
+    assert(emergency_stop_called == true);
+    assert(system_emergency_state == true);
+    assert(state_was_true_when_estop_called == true);
+    printf("PASS\n");
+
+    /* Test 5: Watchdog timeout → MUST trigger e-stop */
+    printf("  Test 5: Watchdog timeout triggers e-stop... ");
+    system_emergency_state = false;
+    emergency_stop_called = false;
+    state_was_true_when_estop_called = false;
+    simulate_handleSystemError_critical(ERROR_WATCHDOG_TIMEOUT);
+    assert(emergency_stop_called == true);
+    assert(system_emergency_state == true);
+    assert(state_was_true_when_estop_called == true);
+    printf("PASS\n");
+
+    /* Test 6: Non-critical error (memory alloc) → no e-stop */
+    printf("  Test 6: Non-critical error (no e-stop)... ");
+    system_emergency_state = false;
+    emergency_stop_called = false;
+    simulate_handleSystemError_critical(ERROR_MEMORY_ALLOC);
     assert(emergency_stop_called == false);
     assert(system_emergency_state == false);
     printf("PASS\n");
 
-    /* Test 5: ERROR_NONE → no e-stop */
+    /* Test 7: ERROR_NONE → no e-stop */
-    printf("  Test 5: ERROR_NONE (no action)... ");
+    printf("  Test 7: ERROR_NONE (no action)... ");
     system_emergency_state = false;
     emergency_stop_called = false;
     simulate_handleSystemError_critical(ERROR_NONE);
@@ -111,6 +136,6 @@ int main(void)
     assert(system_emergency_state == false);
     printf("PASS\n");
 
-    printf("\n=== Gap-3 Fix 5: ALL TESTS PASSED ===\n\n");
+    printf("\n=== Gap-3 Fix 5: ALL 7 TESTS PASSED ===\n\n");
     return 0;
 }

9_Firmware/9_1_Microcontroller/tests/test_gap3_overtemp_emergency_stop.c

@@ -0,0 +1,119 @@
+/*******************************************************************************
+ * test_gap3_overtemp_emergency_stop.c
+ *
+ * Safety bug: handleSystemError() did not escalate ERROR_TEMPERATURE_HIGH
+ * (or ERROR_WATCHDOG_TIMEOUT) to Emergency_Stop().
+ *
+ * Before fix:  The critical-error gate was
+ *                if (error >= ERROR_RF_PA_OVERCURRENT &&
+ *                    error <= ERROR_POWER_SUPPLY) { Emergency_Stop(); }
+ *              So overtemp (code 14) and watchdog timeout (code 16) fell
+ *              through to attemptErrorRecovery()'s default branch (log and
+ *              continue), leaving the 10 W GaN PAs biased at >75 °C.
+ *
+ * After fix:   The gate also matches ERROR_TEMPERATURE_HIGH and
+ *              ERROR_WATCHDOG_TIMEOUT, so thermal and watchdog faults
+ *              latch Emergency_Stop() exactly like PA overcurrent.
+ *
+ * Test strategy:
+ *   Replicate the critical-error predicate and assert that every error
+ *   enum value which threatens RF/power safety is accepted, and that the
+ *   non-critical ones (comm, sensor, memory) are not.
+ ******************************************************************************/
+#include <assert.h>
+#include <stdio.h>
+
+/* Mirror of SystemError_t from main.cpp (keep in lockstep). */
+typedef enum {
+    ERROR_NONE = 0,
+    ERROR_AD9523_CLOCK,
+    ERROR_ADF4382_TX_UNLOCK,
+    ERROR_ADF4382_RX_UNLOCK,
+    ERROR_ADAR1000_COMM,
+    ERROR_ADAR1000_TEMP,
+    ERROR_IMU_COMM,
+    ERROR_BMP180_COMM,
+    ERROR_GPS_COMM,
+    ERROR_RF_PA_OVERCURRENT,
+    ERROR_RF_PA_BIAS,
+    ERROR_STEPPER_MOTOR,
+    ERROR_FPGA_COMM,
+    ERROR_POWER_SUPPLY,
+    ERROR_TEMPERATURE_HIGH,
+    ERROR_MEMORY_ALLOC,
+    ERROR_WATCHDOG_TIMEOUT
+} SystemError_t;
+
+/* Extracted post-fix predicate: returns 1 when Emergency_Stop() must fire. */
+static int triggers_emergency_stop(SystemError_t e)
+{
+    return ((e >= ERROR_RF_PA_OVERCURRENT && e <= ERROR_POWER_SUPPLY) ||
+            e == ERROR_TEMPERATURE_HIGH ||
+            e == ERROR_WATCHDOG_TIMEOUT);
+}
+
+int main(void)
+{
+    printf("=== Safety fix: overtemp / watchdog -> Emergency_Stop() ===\n");
+
+    /* --- Errors that MUST latch Emergency_Stop --- */
+    printf("  Test 1: ERROR_RF_PA_OVERCURRENT triggers... ");
+    assert(triggers_emergency_stop(ERROR_RF_PA_OVERCURRENT));
+    printf("PASS\n");
+
+    printf("  Test 2: ERROR_RF_PA_BIAS triggers... ");
+    assert(triggers_emergency_stop(ERROR_RF_PA_BIAS));
+    printf("PASS\n");
+
+    printf("  Test 3: ERROR_STEPPER_MOTOR triggers... ");
+    assert(triggers_emergency_stop(ERROR_STEPPER_MOTOR));
+    printf("PASS\n");
+
+    printf("  Test 4: ERROR_FPGA_COMM triggers... ");
+    assert(triggers_emergency_stop(ERROR_FPGA_COMM));
+    printf("PASS\n");
+
+    printf("  Test 5: ERROR_POWER_SUPPLY triggers... ");
+    assert(triggers_emergency_stop(ERROR_POWER_SUPPLY));
+    printf("PASS\n");
+
+    printf("  Test 6: ERROR_TEMPERATURE_HIGH triggers (regression)... ");
+    assert(triggers_emergency_stop(ERROR_TEMPERATURE_HIGH));
+    printf("PASS\n");
+
+    printf("  Test 7: ERROR_WATCHDOG_TIMEOUT triggers (regression)... ");
+    assert(triggers_emergency_stop(ERROR_WATCHDOG_TIMEOUT));
+    printf("PASS\n");
+
+    /* --- Errors that MUST NOT escalate (recoverable / informational) --- */
+    printf("  Test 8: ERROR_NONE does not trigger... ");
+    assert(!triggers_emergency_stop(ERROR_NONE));
+    printf("PASS\n");
+
+    printf("  Test 9: ERROR_AD9523_CLOCK does not trigger... ");
+    assert(!triggers_emergency_stop(ERROR_AD9523_CLOCK));
+    printf("PASS\n");
+
+    printf("  Test 10: ERROR_ADF4382_TX_UNLOCK does not trigger (recoverable)... ");
+    assert(!triggers_emergency_stop(ERROR_ADF4382_TX_UNLOCK));
+    printf("PASS\n");
+
+    printf("  Test 11: ERROR_ADAR1000_COMM does not trigger... ");
+    assert(!triggers_emergency_stop(ERROR_ADAR1000_COMM));
+    printf("PASS\n");
+
+    printf("  Test 12: ERROR_IMU_COMM does not trigger... ");
+    assert(!triggers_emergency_stop(ERROR_IMU_COMM));
+    printf("PASS\n");
+
+    printf("  Test 13: ERROR_GPS_COMM does not trigger... ");
+    assert(!triggers_emergency_stop(ERROR_GPS_COMM));
+    printf("PASS\n");
+
+    printf("  Test 14: ERROR_MEMORY_ALLOC does not trigger... ");
+    assert(!triggers_emergency_stop(ERROR_MEMORY_ALLOC));
+    printf("PASS\n");
+
+    printf("\n=== Safety fix: ALL TESTS PASSED ===\n\n");
+    return 0;
+}

9_Firmware/9_2_FPGA/adc_clk_mmcm.v

@@ -212,6 +212,11 @@ BUFG bufg_feedback (
 
 // ---- Output BUFG ----
 // Routes the jitter-cleaned 400 MHz CLKOUT0 onto a global clock network.
+// DONT_TOUCH prevents phys_opt_design AggressiveExplore from replicating this
+// BUFG into a cascaded chain (4 BUFGs in series observed in Build 26), which
+// added ~243ps of clock insertion delay and caused -187ps clock skew on the
+// NCO→DSP mixer critical path.
+(* DONT_TOUCH = "TRUE" *)
 BUFG bufg_clk400m (
     .I(clk_mmcm_out0),
     .O(clk_400m_out)

9_Firmware/9_2_FPGA/cfar_ca.v

@@ -16,9 +16,9 @@
  *
  *   Phase 2 (CFAR): After frame_complete pulse from Doppler processor,
  *     process each Doppler column independently:
- *     a) Read 64 magnitudes from BRAM for one Doppler bin (ST_COL_LOAD)
+ *     a) Read 512 magnitudes from BRAM for one Doppler bin (ST_COL_LOAD)
  *     b) Compute initial sliding window sums (ST_CFAR_INIT)
- *     c) Slide CUT through all 64 range bins:
+ *     c) Slide CUT through all 512 range bins:
  *        - 3 sub-cycles per CUT:
  *          ST_CFAR_THR: register noise_sum (mode select + cross-multiply)
  *          ST_CFAR_MUL: compute alpha * noise_sum_reg in DSP
@@ -47,21 +47,23 @@
  *   typically clutter).
  *
  * Timing:
- *   Phase 2 takes ~(66 + T + 3*64) * 32 ≈ 8500 cycles per frame @ 100 MHz
+ *   Phase 2 takes ~(514 + T + 3*512) * 32 ≈ 55000 cycles per frame @ 100 MHz
- *   = 85 µs. Frame period @ PRF=1932 Hz, 32 chirps = 16.6 ms. Fits easily.
+ *   = 0.55 ms. Frame period @ PRF=1932 Hz, 32 chirps = 16.6 ms. Fits easily.
  *   (3 cycles per CUT due to pipeline: THR → MUL → CMP)
  *
  * Resources:
- *   - 1 BRAM18K for magnitude buffer (2048 x 17 bits)
+ *   - 1 BRAM36K for magnitude buffer (16384 x 17 bits)
  *   - 1 DSP48 for alpha multiply
  *   - ~300 LUTs for FSM + sliding window + comparators
  *
  * Clock domain: clk (100 MHz, same as Doppler processor)
  */
 
+`include "radar_params.vh"
+
 module cfar_ca #(
-    parameter NUM_RANGE_BINS   = 64,
+    parameter NUM_RANGE_BINS   = `RP_NUM_RANGE_BINS,    // 512
-    parameter NUM_DOPPLER_BINS = 32,
+    parameter NUM_DOPPLER_BINS = `RP_NUM_DOPPLER_BINS,  // 32
     parameter MAG_WIDTH        = 17,
     parameter ALPHA_WIDTH      = 8,
     parameter MAX_GUARD        = 8,
@@ -74,7 +76,7 @@ module cfar_ca #(
     input wire [31:0] doppler_data,
     input wire        doppler_valid,
     input wire [4:0]  doppler_bin_in,
-    input wire [5:0]  range_bin_in,
+    input wire [`RP_RANGE_BIN_BITS-1:0] range_bin_in,  // 9-bit
     input wire        frame_complete,
 
     // ========== CONFIGURATION ==========
@@ -88,7 +90,7 @@ module cfar_ca #(
     // ========== DETECTION OUTPUTS ==========
     output reg        detect_flag,
     output reg        detect_valid,
-    output reg [5:0]  detect_range,
+    output reg [`RP_RANGE_BIN_BITS-1:0] detect_range,  // 9-bit
     output reg [4:0]  detect_doppler,
     output reg [MAG_WIDTH-1:0] detect_magnitude,
     output reg [MAG_WIDTH-1:0] detect_threshold,
@@ -103,11 +105,11 @@ module cfar_ca #(
 // INTERNAL PARAMETERS
 // ============================================================================
 localparam TOTAL_CELLS = NUM_RANGE_BINS * NUM_DOPPLER_BINS;
-localparam ADDR_WIDTH  = 11;
+localparam ADDR_WIDTH  = `RP_CFAR_MAG_ADDR_W;  // 14
 localparam COL_BITS    = 5;
-localparam ROW_BITS    = 6;
+localparam ROW_BITS    = `RP_RANGE_BIN_BITS;    // 9
-localparam SUM_WIDTH   = MAG_WIDTH + 6;  // 23 bits: sum of up to 64 magnitudes
+localparam SUM_WIDTH   = MAG_WIDTH + ROW_BITS;  // 26 bits: sum of up to 512 magnitudes
-localparam PROD_WIDTH  = SUM_WIDTH + ALPHA_WIDTH;  // 31 bits
+localparam PROD_WIDTH  = SUM_WIDTH + ALPHA_WIDTH;  // 34 bits
 localparam ALPHA_FRAC_BITS = 4;  // Q4.4
 
 // ============================================================================
@@ -136,7 +138,7 @@ wire [15:0] abs_q = dop_q[15] ? (~dop_q + 16'd1) : dop_q;
 wire [MAG_WIDTH-1:0] cur_mag = {1'b0, abs_i} + {1'b0, abs_q};
 
 // ============================================================================
-// MAGNITUDE BRAM (2048 x 17 bits)
+// MAGNITUDE BRAM (16384 x 17 bits)
 // ============================================================================
 reg                    mag_we;
 reg [ADDR_WIDTH-1:0]   mag_waddr;
@@ -153,7 +155,7 @@ always @(posedge clk) begin
 end
 
 // ============================================================================
-// COLUMN LINE BUFFER (64 x 17 bits — distributed RAM)
+// COLUMN LINE BUFFER (512 x 17 bits — BRAM)
 // ============================================================================
 reg [MAG_WIDTH-1:0] col_buf [0:NUM_RANGE_BINS-1];
 reg [ROW_BITS:0] col_load_idx;
@@ -206,20 +208,31 @@ wire lead_rem_valid = (lead_rem_idx >= 0) && (lead_rem_idx < NUM_RANGE_BINS);
 wire lag_rem_valid  = (lag_rem_idx  >= 0) && (lag_rem_idx  < NUM_RANGE_BINS);
 wire lag_add_valid  = (lag_add_idx  >= 0) && (lag_add_idx  < NUM_RANGE_BINS);
 
-// Safe col_buf read with bounds checking (combinational)
+// Safe col_buf read with bounds checking (combinational — feeds pipeline regs)
 wire [MAG_WIDTH-1:0] lead_add_val = lead_add_valid ? col_buf[lead_add_idx[ROW_BITS-1:0]] : {MAG_WIDTH{1'b0}};
 wire [MAG_WIDTH-1:0] lead_rem_val = lead_rem_valid ? col_buf[lead_rem_idx[ROW_BITS-1:0]] : {MAG_WIDTH{1'b0}};
 wire [MAG_WIDTH-1:0] lag_rem_val  = lag_rem_valid  ? col_buf[lag_rem_idx[ROW_BITS-1:0]]  : {MAG_WIDTH{1'b0}};
 wire [MAG_WIDTH-1:0] lag_add_val  = lag_add_valid  ? col_buf[lag_add_idx[ROW_BITS-1:0]]  : {MAG_WIDTH{1'b0}};
 
-// Net deltas
+// ============================================================================
-wire signed [SUM_WIDTH:0] lead_delta = (lead_add_valid ? $signed({1'b0, lead_add_val}) : 0)
+// PIPELINE REGISTERS: Break col_buf mux tree out of ST_CFAR_CMP critical path
-                                      - (lead_rem_valid ? $signed({1'b0, lead_rem_val}) : 0);
+// ============================================================================
-wire signed [1:0] lead_cnt_delta = (lead_add_valid ? 1 : 0) - (lead_rem_valid ? 1 : 0);
+// Captured in ST_CFAR_THR (col_buf indices depend only on cut_idx/r_guard/r_train,
+// all stable during THR). Used in ST_CFAR_CMP for delta/sum computation.
+// This removes ~6-8 logic levels (9-level mux tree) from the CMP critical path.
+reg [MAG_WIDTH-1:0] lead_add_val_r, lead_rem_val_r;
+reg [MAG_WIDTH-1:0] lag_rem_val_r,  lag_add_val_r;
+reg                 lead_add_valid_r, lead_rem_valid_r;
+reg                 lag_rem_valid_r,  lag_add_valid_r;
 
-wire signed [SUM_WIDTH:0] lag_delta = (lag_add_valid ? $signed({1'b0, lag_add_val}) : 0)
+// Net deltas (computed from registered col_buf values — combinational in CMP)
-                                     - (lag_rem_valid ? $signed({1'b0, lag_rem_val}) : 0);
+wire signed [SUM_WIDTH:0] lead_delta = (lead_add_valid_r ? $signed({1'b0, lead_add_val_r}) : 0)
-wire signed [1:0] lag_cnt_delta = (lag_add_valid ? 1 : 0) - (lag_rem_valid ? 1 : 0);
+                                      - (lead_rem_valid_r ? $signed({1'b0, lead_rem_val_r}) : 0);
+wire signed [1:0] lead_cnt_delta = (lead_add_valid_r ? 1 : 0) - (lead_rem_valid_r ? 1 : 0);
+
+wire signed [SUM_WIDTH:0] lag_delta = (lag_add_valid_r ? $signed({1'b0, lag_add_val_r}) : 0)
+                                     - (lag_rem_valid_r ? $signed({1'b0, lag_rem_val_r}) : 0);
+wire signed [1:0] lag_cnt_delta = (lag_add_valid_r ? 1 : 0) - (lag_rem_valid_r ? 1 : 0);
 
 // ============================================================================
 // NOISE ESTIMATE COMPUTATION (combinational for CFAR mode selection)
@@ -267,7 +280,7 @@ always @(posedge clk or negedge reset_n) begin
         state          <= ST_IDLE;
         detect_flag    <= 1'b0;
         detect_valid   <= 1'b0;
-        detect_range   <= 6'd0;
+        detect_range   <= {ROW_BITS{1'b0}};
         detect_doppler <= 5'd0;
         detect_magnitude <= {MAG_WIDTH{1'b0}};
         detect_threshold <= {MAG_WIDTH{1'b0}};
@@ -288,6 +301,14 @@ always @(posedge clk or negedge reset_n) begin
         noise_sum_reg  <= 0;
         noise_product  <= 0;
         adaptive_thr   <= 0;
+        lead_add_val_r <= 0;
+        lead_rem_val_r <= 0;
+        lag_rem_val_r  <= 0;
+        lag_add_val_r  <= 0;
+        lead_add_valid_r <= 0;
+        lead_rem_valid_r <= 0;
+        lag_rem_valid_r  <= 0;
+        lag_add_valid_r  <= 0;
         r_guard        <= 4'd2;
         r_train        <= 5'd8;
         r_alpha        <= 8'h30;
@@ -364,7 +385,7 @@ always @(posedge clk or negedge reset_n) begin
                 if (r_enable) begin
                     col_idx      <= 0;
                     col_load_idx <= 0;
-                    mag_raddr    <= {6'd0, 5'd0};
+                    mag_raddr    <= {{ROW_BITS{1'b0}}, 5'd0};
                     state        <= ST_COL_LOAD;
                 end else begin
                     state <= ST_DONE;
@@ -382,14 +403,14 @@ always @(posedge clk or negedge reset_n) begin
 
             if (col_load_idx == 0) begin
                 // First address already presented, advance to range=1
-                mag_raddr    <= {6'd1, col_idx};
+                mag_raddr    <= {{{(ROW_BITS-1){1'b0}}, 1'b1}, col_idx};
                 col_load_idx <= 1;
             end else if (col_load_idx <= NUM_RANGE_BINS) begin
                 // Capture previous read
                 col_buf[col_load_idx - 1] <= mag_rdata;
 
                 if (col_load_idx < NUM_RANGE_BINS) begin
-                    mag_raddr <= {col_load_idx[ROW_BITS-1:0] + 6'd1, col_idx};
+                    mag_raddr <= {col_load_idx[ROW_BITS-1:0] + {{(ROW_BITS-1){1'b0}}, 1'b1}, col_idx};
                 end
 
                 col_load_idx <= col_load_idx + 1;
@@ -441,6 +462,19 @@ always @(posedge clk or negedge reset_n) begin
             cfar_status <= {4'd4, 1'b0, col_idx[2:0]};
 
             noise_sum_reg <= noise_sum_comb;
+
+            // Pipeline: register col_buf reads for next CUT's window update.
+            // Indices depend only on cut_idx/r_guard/r_train (all stable here).
+            // Breaks the 9-level col_buf mux tree out of ST_CFAR_CMP.
+            lead_add_val_r   <= lead_add_val;
+            lead_rem_val_r   <= lead_rem_val;
+            lag_rem_val_r    <= lag_rem_val;
+            lag_add_val_r    <= lag_add_val;
+            lead_add_valid_r <= lead_add_valid;
+            lead_rem_valid_r <= lead_rem_valid;
+            lag_rem_valid_r  <= lag_rem_valid;
+            lag_add_valid_r  <= lag_add_valid;
+
             state <= ST_CFAR_MUL;
         end
 
@@ -513,7 +547,7 @@ always @(posedge clk or negedge reset_n) begin
             if (col_idx < NUM_DOPPLER_BINS - 1) begin
                 col_idx      <= col_idx + 1;
                 col_load_idx <= 0;
-                mag_raddr    <= {6'd0, col_idx + 5'd1};
+                mag_raddr    <= {{ROW_BITS{1'b0}}, col_idx + 5'd1};
                 state        <= ST_COL_LOAD;
             end else begin
                 state <= ST_DONE;

9_Firmware/9_2_FPGA/chirp_memory_loader_param.v

@@ -4,10 +4,6 @@ module chirp_memory_loader_param #(
     parameter LONG_Q_FILE_SEG0 = "long_chirp_seg0_q.mem",
     parameter LONG_I_FILE_SEG1 = "long_chirp_seg1_i.mem",
     parameter LONG_Q_FILE_SEG1 = "long_chirp_seg1_q.mem",
-    parameter LONG_I_FILE_SEG2 = "long_chirp_seg2_i.mem",
-    parameter LONG_Q_FILE_SEG2 = "long_chirp_seg2_q.mem",
-    parameter LONG_I_FILE_SEG3 = "long_chirp_seg3_i.mem",
-    parameter LONG_Q_FILE_SEG3 = "long_chirp_seg3_q.mem",
     parameter SHORT_I_FILE = "short_chirp_i.mem",
     parameter SHORT_Q_FILE = "short_chirp_q.mem",
     parameter DEBUG = 1
@@ -17,17 +13,17 @@ module chirp_memory_loader_param #(
     input wire [1:0] segment_select,
     input wire mem_request,
     input wire use_long_chirp,
-    input wire [9:0] sample_addr,
+    input wire [10:0] sample_addr,
     output reg [15:0] ref_i,
     output reg [15:0] ref_q,
     output reg mem_ready
 );
 
-// Memory declarations - now 4096 samples for 4 segments
+// Memory declarations — 2 long segments × 2048 = 4096 samples
 (* ram_style = "block" *) reg [15:0] long_chirp_i [0:4095];
 (* ram_style = "block" *) reg [15:0] long_chirp_q [0:4095];
-(* ram_style = "block" *) reg [15:0] short_chirp_i [0:1023];
+(* ram_style = "block" *) reg [15:0] short_chirp_i [0:2047];
-(* ram_style = "block" *) reg [15:0] short_chirp_q [0:1023];
+(* ram_style = "block" *) reg [15:0] short_chirp_q [0:2047];
 
 // Initialize memory
 integer i;
@@ -35,66 +31,47 @@ integer i;
 initial begin
     `ifdef SIMULATION
     if (DEBUG) begin
-        $display("[MEM] Starting memory initialization for 4 long chirp segments");
+        $display("[MEM] Starting memory initialization for 2 long chirp segments");
     end
     `endif
 
-    // === LOAD LONG CHIRP - 4 SEGMENTS ===
+    // === LOAD LONG CHIRP — 2 SEGMENTS ===
-    // Segment 0 (addresses 0-1023)
+    // Segment 0 (addresses 0-2047)
-    $readmemh(LONG_I_FILE_SEG0, long_chirp_i, 0, 1023);
+    $readmemh(LONG_I_FILE_SEG0, long_chirp_i, 0, 2047);
-    $readmemh(LONG_Q_FILE_SEG0, long_chirp_q, 0, 1023);
+    $readmemh(LONG_Q_FILE_SEG0, long_chirp_q, 0, 2047);
     `ifdef SIMULATION
-    if (DEBUG) $display("[MEM] Loaded long chirp segment 0 (0-1023)");
+    if (DEBUG) $display("[MEM] Loaded long chirp segment 0 (0-2047)");
     `endif
 
-    // Segment 1 (addresses 1024-2047)
+    // Segment 1 (addresses 2048-4095)
-    $readmemh(LONG_I_FILE_SEG1, long_chirp_i, 1024, 2047);
+    $readmemh(LONG_I_FILE_SEG1, long_chirp_i, 2048, 4095);
-    $readmemh(LONG_Q_FILE_SEG1, long_chirp_q, 1024, 2047);
+    $readmemh(LONG_Q_FILE_SEG1, long_chirp_q, 2048, 4095);
     `ifdef SIMULATION
-    if (DEBUG) $display("[MEM] Loaded long chirp segment 1 (1024-2047)");
+    if (DEBUG) $display("[MEM] Loaded long chirp segment 1 (2048-4095)");
-    `endif
-    
-    // Segment 2 (addresses 2048-3071)
-    $readmemh(LONG_I_FILE_SEG2, long_chirp_i, 2048, 3071);
-    $readmemh(LONG_Q_FILE_SEG2, long_chirp_q, 2048, 3071);
-    `ifdef SIMULATION
-    if (DEBUG) $display("[MEM] Loaded long chirp segment 2 (2048-3071)");
-    `endif
-    
-    // Segment 3 (addresses 3072-4095)
-    $readmemh(LONG_I_FILE_SEG3, long_chirp_i, 3072, 4095);
-    $readmemh(LONG_Q_FILE_SEG3, long_chirp_q, 3072, 4095);
-    `ifdef SIMULATION
-    if (DEBUG) $display("[MEM] Loaded long chirp segment 3 (3072-4095)");
     `endif
 
     // === LOAD SHORT CHIRP ===
-    // Load first 50 samples (0-49). Explicit range prevents iverilog warning
+    // Load first 50 samples (0-49)
-    // about insufficient words for the full [0:1023] array.
     $readmemh(SHORT_I_FILE, short_chirp_i, 0, 49);
     $readmemh(SHORT_Q_FILE, short_chirp_q, 0, 49);
     `ifdef SIMULATION
     if (DEBUG) $display("[MEM] Loaded short chirp (0-49)");
     `endif
 
-    // Zero pad remaining 974 samples (50-1023)
+    // Zero pad remaining samples (50-2047)
-    for (i = 50; i < 1024; i = i + 1) begin
+    for (i = 50; i < 2048; i = i + 1) begin
         short_chirp_i[i] = 16'h0000;
         short_chirp_q[i] = 16'h0000;
     end
     `ifdef SIMULATION
-    if (DEBUG) $display("[MEM] Zero-padded short chirp from 50-1023");
+    if (DEBUG) $display("[MEM] Zero-padded short chirp from 50-2047");
 
     // === VERIFICATION ===
     if (DEBUG) begin
         $display("[MEM] Memory loading complete. Verification samples:");
         $display("  Long[0]:     I=%h Q=%h", long_chirp_i[0], long_chirp_q[0]);
-        $display("  Long[1023]:  I=%h Q=%h", long_chirp_i[1023], long_chirp_q[1023]);
-        $display("  Long[1024]:  I=%h Q=%h", long_chirp_i[1024], long_chirp_q[1024]);
         $display("  Long[2047]:  I=%h Q=%h", long_chirp_i[2047], long_chirp_q[2047]);
         $display("  Long[2048]:  I=%h Q=%h", long_chirp_i[2048], long_chirp_q[2048]);
-        $display("  Long[3071]:  I=%h Q=%h", long_chirp_i[3071], long_chirp_q[3071]);
-        $display("  Long[3072]:  I=%h Q=%h", long_chirp_i[3072], long_chirp_q[3072]);
         $display("  Long[4095]:  I=%h Q=%h", long_chirp_i[4095], long_chirp_q[4095]);
         $display("  Short[0]:    I=%h Q=%h", short_chirp_i[0], short_chirp_q[0]);
         $display("  Short[49]:   I=%h Q=%h", short_chirp_i[49], short_chirp_q[49]);
@@ -104,8 +81,8 @@ initial begin
 end
 
 // Memory access logic
-// long_addr is combinational — segment_select[1:0] concatenated with sample_addr[9:0]
+// long_addr: segment_select[0] selects segment (0 or 1), sample_addr[10:0] selects within
-wire [11:0] long_addr = {segment_select, sample_addr};
+wire [11:0] long_addr = {segment_select[0], sample_addr};
 
 // ---- BRAM read block (sync-only, sync reset) ----
 // REQP-1839/1840 fix: BRAM output registers cannot have async resets.
@@ -128,7 +105,7 @@ always @(posedge clk) begin
             end
             `endif
         end else begin
-            // Short chirp (0-1023)
+            // Short chirp (0-2047)
             ref_i <= short_chirp_i[sample_addr];
             ref_q <= short_chirp_q[sample_addr];
 

9_Firmware/9_2_FPGA/cic_decimator_4x_enhanced.v

@@ -1,6 +1,7 @@
 module cic_decimator_4x_enhanced (
     input wire clk,                 // 400MHz input clock
     input wire reset_n,
+    input wire reset_h,             // Pre-registered active-high reset from parent (avoids LUT1 inverter)
     input wire signed [17:0] data_in,  // 18-bit input
     input wire data_valid,
     output reg signed [17:0] data_out, // 18-bit output
@@ -32,11 +33,15 @@ localparam COMB_WIDTH = 28;
 // adjacent DSP48E1 tiles — zero fabric delay, guaranteed to meet 400+ MHz
 // on 7-series regardless of speed grade.
 //
-// Active-high reset derived from reset_n (inverted).
+// Active-high reset provided by parent module (pre-registered).
 // CEP (clock enable for P register) gated by data_valid.
 // ============================================================================
 
-wire reset_h = ~reset_n;  // active-high reset for DSP48E1 RSTP
+// reset_h is now an input port from parent module (pre-registered active-high).
+// Previously: wire reset_h = ~reset_n; — this LUT1 inverter + long routing to
+// 8 DSP48E1 RSTB pins was the root cause of 400 MHz timing failure (WNS=-0.074ns).
+// The parent ddc_400m.v already has a registered reset_400m derived from
+// the 2-stage sync reset, so we use that directly.
 
 // Sign-extended input for integrator_0 C port (48-bit)
 wire [ACC_WIDTH-1:0] data_in_c = {{(ACC_WIDTH-18){data_in[17]}}, data_in};
@@ -66,13 +71,13 @@ reg signed [COMB_WIDTH-1:0] comb_delay [0:STAGES-1][0:COMB_DELAY-1];
 // Pipeline valid for comb stages 1-4: delayed by 1 cycle vs comb_pipe to
 // account for CREG+AREG+BREG pipeline inside comb_0_dsp (explicit DSP48E1).
 // Comb[0] result appears 1 cycle after data_valid_comb_pipe.
-(* keep = "true", max_fanout = 4 *) reg data_valid_comb_0_out;
+(* keep = "true", max_fanout = 16 *) reg data_valid_comb_0_out;
 
 // Enhanced control and monitoring
 reg [1:0] decimation_counter;
-(* keep = "true", max_fanout = 4 *) reg data_valid_delayed;
+(* keep = "true", max_fanout = 16 *) reg data_valid_delayed;
-(* keep = "true", max_fanout = 4 *) reg data_valid_comb;
+(* keep = "true", max_fanout = 16 *) reg data_valid_comb;
-(* keep = "true", max_fanout = 4 *) reg data_valid_comb_pipe;
+(* keep = "true", max_fanout = 16 *) reg data_valid_comb_pipe;
 reg [7:0] output_counter;
 reg [ACC_WIDTH-1:0] max_integrator_value;
 reg overflow_detected;
@@ -702,7 +707,7 @@ end
 // Sync reset: enables FDRE inference for better timing at 400 MHz.
 // Reset is already synchronous to clk via reset synchronizer in parent module.
 always @(posedge clk) begin
-    if (!reset_n) begin
+    if (reset_h) begin
         integrator_sampled <= 0;
         decimation_counter <= 0;
         data_valid_delayed <= 0;
@@ -757,7 +762,7 @@ end
 // Pipeline the valid signal for comb section
 // Sync reset: matches decimation control block reset style.
 always @(posedge clk) begin
-    if (!reset_n) begin
+    if (reset_h) begin
         data_valid_comb <= 0;
         data_valid_comb_pipe <= 0;
         data_valid_comb_0_out <= 0;
@@ -792,7 +797,7 @@ end
 //   - Each stage: comb[i] = comb[i-1] - comb_delay[i][last]
 
 always @(posedge clk) begin
-    if (!reset_n) begin
+    if (reset_h) begin
         for (i = 0; i < STAGES; i = i + 1) begin
             comb[i] <= 0;
             for (j = 0; j < COMB_DELAY; j = j + 1) begin

9_Firmware/9_2_FPGA/constraints/adc_clk_mmcm.xdc

@@ -83,3 +83,13 @@ set_false_path -through [get_pins rx_inst/adc/mmcm_inst/mmcm_adc_400m/LOCKED]
 # Waiving hold on these 8 paths (adc_d_p[0..7] → IDDR) is standard practice
 # for source-synchronous LVDS ADC interfaces using BUFIO capture.
 set_false_path -hold -from [get_ports {adc_d_p[*]}] -to [get_clocks adc_dco_p]
+
+# --------------------------------------------------------------------------
+# Timing margin for 400 MHz critical paths
+# --------------------------------------------------------------------------
+# Extra setup uncertainty forces Vivado to leave margin for temperature/voltage/
+# aging variation. Reduced from 200 ps to 100 ps after NCO→mixer pipeline
+# register fix eliminated the dominant timing bottleneck (WNS went from +0.002ns
+# to comfortable margin). 100 ps still provides ~4% guardband on the 2.5ns period.
+# This is additive to the existing jitter-based uncertainty (~53 ps).
+set_clock_uncertainty -setup -add 0.100 [get_clocks clk_mmcm_out0]

9_Firmware/9_2_FPGA/constraints/xc7a50t_ftg256.xdc

@@ -222,8 +222,16 @@ set_property IOSTANDARD LVCMOS33 [get_ports {stm32_new_*}]
 set_property IOSTANDARD LVCMOS33 [get_ports {stm32_mixers_enable}]
 # reset_n is DIG_4 (PD12) — constrained above in the RESET section
 
-# DIG_5 = H11, DIG_6 = G12, DIG_7 = H12 — available for FPGA→STM32 status
+# DIG_5 = H11, DIG_6 = G12, DIG_7 = H12 — FPGA→STM32 status outputs
-# Currently unused in RTL. Could be connected to status outputs if needed.
+# DIG_5: AGC saturation flag (PD13 on STM32)
+# DIG_6: reserved (PD14)
+# DIG_7: reserved (PD15)
+set_property PACKAGE_PIN H11 [get_ports {gpio_dig5}]
+set_property PACKAGE_PIN G12 [get_ports {gpio_dig6}]
+set_property PACKAGE_PIN H12 [get_ports {gpio_dig7}]
+set_property IOSTANDARD LVCMOS33 [get_ports {gpio_dig*}]
+set_property DRIVE 8 [get_ports {gpio_dig*}]
+set_property SLEW SLOW [get_ports {gpio_dig*}]
 
 # ============================================================================
 # ADC INTERFACE (LVDS — Bank 14, VCCO=3.3V)

9_Firmware/9_2_FPGA/ddc_400m.v

@@ -102,14 +102,19 @@ wire signed [17:0] debug_mixed_q_trunc;
 reg [7:0] signal_power_i, signal_power_q;
 
 // Internal mixing signals
-// DSP48E1 with AREG=1, BREG=1, MREG=1, PREG=1 handles all internal pipelining
+// Pipeline: NCO fabric reg (1) + DSP48E1 AREG/BREG (1) + MREG (1) + PREG (1) + retiming (1) = 5 cycles
-// Latency: 4 cycles (1 for AREG/BREG, 1 for MREG, 1 for PREG, 1 for post-DSP retiming)
+// The NCO fabric pipeline register was added to break the long NCO→DSP B-port route
+// (1.505ns routing in Build 26, WNS=+0.002ns). With BREG=1 still active inside the DSP,
+// total latency increases by 1 cycle (2.5ns at 400MHz — negligible for radar).
 wire signed [MIXER_WIDTH-1:0] adc_signed_w;
 reg signed [MIXER_WIDTH + NCO_WIDTH -1:0] mixed_i, mixed_q;
 reg mixed_valid;
 reg mixer_overflow_i, mixer_overflow_q;
-// Pipeline valid tracking: 4-stage shift register (3 for DSP48E1 + 1 for post-DSP retiming)
+// Pipeline valid tracking: 5-stage shift register (1 NCO pipe + 3 DSP48E1 + 1 retiming)
-reg [3:0] dsp_valid_pipe;
+reg [4:0] dsp_valid_pipe;
+// NCO→DSP pipeline registers — breaks the long NCO sin/cos → DSP48E1 B-port route
+// DONT_TOUCH prevents Vivado from absorbing these into the DSP or optimizing away
+(* DONT_TOUCH = "TRUE" *) reg signed [15:0] cos_nco_pipe, sin_nco_pipe;
 // Post-DSP retiming registers — breaks DSP48E1 CLK→P to fabric timing path
 // This extra pipeline stage absorbs the 1.866ns DSP output prop delay + routing,
 // ensuring WNS > 0 at 400 MHz regardless of placement seed
@@ -210,11 +215,11 @@ nco_400m_enhanced nco_core (
 //
 // Architecture:
 //   ADC data → sign-extend to 18b → DSP48E1 A-port (AREG=1 pipelines it)
-//   NCO cos/sin → sign-extend to 18b → DSP48E1 B-port (BREG=1 pipelines it)
+//   NCO cos/sin → fabric pipeline reg → DSP48E1 B-port (BREG=1 pipelines it)
 //   Multiply result captured by MREG=1, then output registered by PREG=1
 //   force_saturation override applied AFTER DSP48E1 output (not on input path)
 //
-// Latency: 3 clock cycles (AREG/BREG + MREG + PREG)
+// Latency: 4 clock cycles (1 NCO pipe + 1 AREG/BREG + 1 MREG + 1 PREG) + 1 retiming = 5 total
 // PREG=1 absorbs DSP48E1 CLK→P delay internally, preventing fabric timing violations
 // In simulation (Icarus), uses behavioral equivalent since DSP48E1 is Xilinx-only
 // ============================================================================
@@ -223,24 +228,35 @@ nco_400m_enhanced nco_core (
 assign adc_signed_w = {1'b0, adc_data, {(MIXER_WIDTH-ADC_WIDTH-1){1'b0}}} - 
                       {1'b0, {ADC_WIDTH{1'b1}}, {(MIXER_WIDTH-ADC_WIDTH-1){1'b0}}} / 2;
 
-// Valid pipeline: 4-stage shift register (3 for DSP48E1 AREG+MREG+PREG + 1 for retiming)
+// Valid pipeline: 5-stage shift register (1 NCO pipe + 3 DSP48E1 AREG+MREG+PREG + 1 retiming)
 always @(posedge clk_400m or negedge reset_n_400m) begin
     if (!reset_n_400m) begin
-        dsp_valid_pipe <= 4'b0000;
+        dsp_valid_pipe <= 5'b00000;
     end else begin
-        dsp_valid_pipe <= {dsp_valid_pipe[2:0], (nco_ready && adc_data_valid_i && adc_data_valid_q)};
+        dsp_valid_pipe <= {dsp_valid_pipe[3:0], (nco_ready && adc_data_valid_i && adc_data_valid_q)};
     end
 end
 
 `ifdef SIMULATION
 // ---- Behavioral model for Icarus Verilog simulation ----
-// Mimics DSP48E1 with AREG=1, BREG=1, MREG=1, PREG=1 (3-cycle latency)
+// Mimics NCO pipeline + DSP48E1 with AREG=1, BREG=1, MREG=1, PREG=1 (4-cycle DSP + 1 NCO pipe)
 reg signed [MIXER_WIDTH-1:0] adc_signed_reg;     // Models AREG
 reg signed [15:0] cos_pipe_reg, sin_pipe_reg;     // Models BREG
 reg signed [MIXER_WIDTH+NCO_WIDTH-1:0] mult_i_internal, mult_q_internal;  // Models MREG
 reg signed [MIXER_WIDTH+NCO_WIDTH-1:0] mult_i_reg, mult_q_reg;            // Models PREG
 
-// Stage 1: AREG/BREG equivalent
+// Stage 0: NCO pipeline — breaks long NCO→DSP route (matches synthesis fabric registers)
+always @(posedge clk_400m or negedge reset_n_400m) begin
+    if (!reset_n_400m) begin
+        cos_nco_pipe <= 0;
+        sin_nco_pipe <= 0;
+    end else begin
+        cos_nco_pipe <= cos_out;
+        sin_nco_pipe <= sin_out;
+    end
+end
+
+// Stage 1: AREG/BREG equivalent (uses pipelined NCO outputs)
 always @(posedge clk_400m or negedge reset_n_400m) begin
     if (!reset_n_400m) begin
         adc_signed_reg <= 0;
@@ -248,8 +264,8 @@ always @(posedge clk_400m or negedge reset_n_400m) begin
         sin_pipe_reg <= 0;
     end else begin
         adc_signed_reg <= adc_signed_w;
-        cos_pipe_reg <= cos_out;
+        cos_pipe_reg <= cos_nco_pipe;
-        sin_pipe_reg <= sin_out;
+        sin_pipe_reg <= sin_nco_pipe;
     end
 end
 
@@ -291,6 +307,20 @@ end
 // This guarantees AREG/BREG/MREG are used, achieving timing closure at 400 MHz
 wire [47:0] dsp_p_i, dsp_p_q;
 
+// NCO pipeline stage — breaks the long NCO sin/cos → DSP48E1 B-port route
+// (1.505ns routing observed in Build 26). These fabric registers are placed
+// near the DSP by the placer, splitting the route into two shorter segments.
+// DONT_TOUCH on the reg declaration (above) prevents absorption/retiming.
+always @(posedge clk_400m or negedge reset_n_400m) begin
+    if (!reset_n_400m) begin
+        cos_nco_pipe <= 0;
+        sin_nco_pipe <= 0;
+    end else begin
+        cos_nco_pipe <= cos_out;
+        sin_nco_pipe <= sin_out;
+    end
+end
+
 // DSP48E1 for I-channel mixer (adc_signed * cos_out)
 DSP48E1 #(
     // Feature control attributes
@@ -350,7 +380,7 @@ DSP48E1 #(
     .CEINMODE(1'b0),
     // Data ports
     .A({{12{adc_signed_w[MIXER_WIDTH-1]}}, adc_signed_w}),   // Sign-extend 18b to 30b
-    .B({{2{cos_out[15]}}, cos_out}),                          // Sign-extend 16b to 18b
+    .B({{2{cos_nco_pipe[15]}}, cos_nco_pipe}),                // Sign-extend 16b to 18b (pipelined)
     .C(48'b0),
     .D(25'b0),
     .CARRYIN(1'b0),
@@ -432,7 +462,7 @@ DSP48E1 #(
     .CED(1'b0),
     .CEINMODE(1'b0),
     .A({{12{adc_signed_w[MIXER_WIDTH-1]}}, adc_signed_w}),
-    .B({{2{sin_out[15]}}, sin_out}),
+    .B({{2{sin_nco_pipe[15]}}, sin_nco_pipe}),
     .C(48'b0),
     .D(25'b0),
     .CARRYIN(1'b0),
@@ -492,7 +522,7 @@ always @(posedge clk_400m or negedge reset_n_400m) begin
         mixer_overflow_q <= 0;
         saturation_count <= 0;
         overflow_detected <= 0;
-    end else if (dsp_valid_pipe[3]) begin
+    end else if (dsp_valid_pipe[4]) begin
         // Force saturation for testing (applied after DSP output, not on input path)
         if (force_saturation_sync) begin
             mixed_i <= 34'h1FFFFFFFF;
@@ -536,6 +566,7 @@ wire cic_valid_i, cic_valid_q;
 cic_decimator_4x_enhanced cic_i_inst (
     .clk(clk_400m),
     .reset_n(reset_n_400m),
+    .reset_h(reset_400m),
     .data_in(mixed_i[33:16]),
     .data_valid(mixed_valid),
     .data_out(cic_i_out),
@@ -545,6 +576,7 @@ cic_decimator_4x_enhanced cic_i_inst (
 cic_decimator_4x_enhanced cic_q_inst (
     .clk(clk_400m),
     .reset_n(reset_n_400m),
+    .reset_h(reset_400m),
     .data_in(mixed_q[33:16]),
     .data_valid(mixed_valid),
     .data_out(cic_q_out),

9_Firmware/9_2_FPGA/doppler_processor.v

@@ -32,13 +32,15 @@
 //     w[n] = 0.54 - 0.46 * cos(2*pi*n/15), n=0..15
 // ============================================================================
 
+`include "radar_params.vh"
+
 module doppler_processor_optimized #(
-    parameter DOPPLER_FFT_SIZE   = 16,     // FFT size per sub-frame (was 32)
+    parameter DOPPLER_FFT_SIZE   = `RP_DOPPLER_FFT_SIZE,    // 16
-    parameter RANGE_BINS         = 64,
+    parameter RANGE_BINS         = `RP_NUM_RANGE_BINS,      // 512
-    parameter CHIRPS_PER_FRAME   = 32,     // Total chirps in frame (16+16)
+    parameter CHIRPS_PER_FRAME   = `RP_CHIRPS_PER_FRAME,    // 32
-    parameter CHIRPS_PER_SUBFRAME = 16,    // Chirps per sub-frame
+    parameter CHIRPS_PER_SUBFRAME = `RP_CHIRPS_PER_SUBFRAME, // 16
     parameter WINDOW_TYPE        = 0,      // 0=Hamming, 1=Rectangular
-    parameter DATA_WIDTH         = 16
+    parameter DATA_WIDTH         = `RP_DATA_WIDTH           // 16
 )(
     input wire clk,
     input wire reset_n,
@@ -48,7 +50,7 @@ module doppler_processor_optimized #(
     output reg [31:0] doppler_output,
     output reg doppler_valid,
     output reg [4:0] doppler_bin,      // {sub_frame, bin[3:0]}
-    output reg [5:0] range_bin,
+    output reg [`RP_RANGE_BIN_BITS-1:0] range_bin,  // 9-bit
     output reg sub_frame,              // 0=long PRI, 1=short PRI
     output wire processing_active,
     output wire frame_complete,
@@ -57,16 +59,16 @@ module doppler_processor_optimized #(
 `ifdef FORMAL
     ,
     output wire [2:0]  fv_state,
-    output wire [10:0] fv_mem_write_addr,
+    output wire [`RP_DOPPLER_MEM_ADDR_W-1:0] fv_mem_write_addr,
-    output wire [10:0] fv_mem_read_addr,
+    output wire [`RP_DOPPLER_MEM_ADDR_W-1:0] fv_mem_read_addr,
-    output wire [5:0]  fv_write_range_bin,
+    output wire [`RP_RANGE_BIN_BITS-1:0]     fv_write_range_bin,
     output wire [4:0]  fv_write_chirp_index,
-    output wire [5:0]  fv_read_range_bin,
+    output wire [`RP_RANGE_BIN_BITS-1:0]     fv_read_range_bin,
     output wire [4:0]  fv_read_doppler_index,
     output wire [9:0]  fv_processing_timeout,
     output wire        fv_frame_buffer_full,
     output wire        fv_mem_we,
-    output wire [10:0] fv_mem_waddr_r
+    output wire [`RP_DOPPLER_MEM_ADDR_W-1:0] fv_mem_waddr_r
 `endif
 );
 
@@ -115,9 +117,9 @@ localparam MEM_DEPTH = RANGE_BINS * CHIRPS_PER_FRAME;
 // ==============================================
 // Control Registers
 // ==============================================
-reg [5:0] write_range_bin;
+reg [`RP_RANGE_BIN_BITS-1:0] write_range_bin;
 reg [4:0] write_chirp_index;
-reg [5:0] read_range_bin;
+reg [`RP_RANGE_BIN_BITS-1:0] read_range_bin;
 reg [4:0] read_doppler_index;
 reg frame_buffer_full;
 reg [9:0] chirps_received;
@@ -147,8 +149,8 @@ wire fft_output_last;
 // ==============================================
 // Addressing
 // ==============================================
-wire [10:0] mem_write_addr;
+wire [`RP_DOPPLER_MEM_ADDR_W-1:0] mem_write_addr;
-wire [10:0] mem_read_addr;
+wire [`RP_DOPPLER_MEM_ADDR_W-1:0] mem_read_addr;
 
 assign mem_write_addr = (write_chirp_index * RANGE_BINS) + write_range_bin;
 assign mem_read_addr = (read_doppler_index * RANGE_BINS) + read_range_bin;
@@ -180,7 +182,7 @@ reg [9:0] processing_timeout;
 
 // Memory write enable and data signals
 reg mem_we;
-reg [10:0] mem_waddr_r;
+reg [`RP_DOPPLER_MEM_ADDR_W-1:0] mem_waddr_r;
 reg [DATA_WIDTH-1:0] mem_wdata_i, mem_wdata_q;
 
 // Memory read data
@@ -531,6 +533,11 @@ xfft_16 fft_inst (
 // Status Outputs
 // ==============================================
 assign processing_active = (state != S_IDLE);
+// NOTE: frame_complete is a LEVEL, not a pulse. It is high whenever the
+// doppler processor is idle with no buffered frame. radar_receiver_final.v
+// converts this to a single-cycle rising-edge pulse before routing to
+// downstream consumers (USB FT2232H, AGC, CFAR). Do NOT connect this
+// level output directly to modules that expect a pulse.
 assign frame_complete = (state == S_IDLE && frame_buffer_full == 0);
 
 endmodule

9_Firmware/9_2_FPGA/fft_engine.v

@@ -28,13 +28,16 @@
  * Clock domain: single clock (clk), active-low async reset (reset_n).
  */
 
+// Include single source of truth for default parameters
+`include "radar_params.vh"
+
 module fft_engine #(
-    parameter N            = 1024,
+    parameter N            = `RP_FFT_SIZE,       // 2048
-    parameter LOG2N        = 10,
+    parameter LOG2N        = `RP_LOG2_FFT_SIZE,  // 11
     parameter DATA_W       = 16,
     parameter INTERNAL_W   = 32,
     parameter TWIDDLE_W    = 16,
-    parameter TWIDDLE_FILE = "fft_twiddle_1024.mem"
+    parameter TWIDDLE_FILE = "fft_twiddle_2048.mem"
 )(
     input wire clk,
     input wire reset_n,

9_Firmware/9_2_FPGA/fft_twiddle_2048.mem

@@ -0,0 +1,515 @@
+// Quarter-wave cosine ROM for 2048-point FFT
+// 512 entries, 16-bit signed Q15 ($readmemh format)
+// cos(2*pi*k/2048) for k = 0..511
+7FFF
+7FFF
+7FFE
+7FFE
+7FFD
+7FFB
+7FF9
+7FF7
+7FF5
+7FF3
+7FF0
+7FEC
+7FE9
+7FE5
+7FE1
+7FDC
+7FD8
+7FD2
+7FCD
+7FC7
+7FC1
+7FBB
+7FB4
+7FAD
+7FA6
+7F9F
+7F97
+7F8F
+7F86
+7F7D
+7F74
+7F6B
+7F61
+7F57
+7F4D
+7F42
+7F37
+7F2C
+7F21
+7F15
+7F09
+7EFC
+7EEF
+7EE2
+7ED5
+7EC7
+7EB9
+7EAB
+7E9C
+7E8D
+7E7E
+7E6F
+7E5F
+7E4F
+7E3E
+7E2E
+7E1D
+7E0B
+7DFA
+7DE8
+7DD5
+7DC3
+7DB0
+7D9D
+7D89
+7D76
+7D62
+7D4D
+7D39
+7D24
+7D0E
+7CF9
+7CE3
+7CCD
+7CB6
+7C9F
+7C88
+7C71
+7C59
+7C41
+7C29
+7C10
+7BF8
+7BDE
+7BC5
+7BAB
+7B91
+7B77
+7B5C
+7B41
+7B26
+7B0A
+7AEE
+7AD2
+7AB6
+7A99
+7A7C
+7A5F
+7A41
+7A23
+7A05
+79E6
+79C8
+79A9
+7989
+796A
+794A
+7929
+7909
+78E8
+78C7
+78A5
+7884
+7862
+783F
+781D
+77FA
+77D7
+77B3
+778F
+776B
+7747
+7722
+76FE
+76D8
+76B3
+768D
+7667
+7641
+761A
+75F3
+75CC
+75A5
+757D
+7555
+752D
+7504
+74DB
+74B2
+7488
+745F
+7435
+740A
+73E0
+73B5
+738A
+735E
+7333
+7307
+72DB
+72AE
+7281
+7254
+7227
+71F9
+71CB
+719D
+716F
+7140
+7111
+70E2
+70B2
+7083
+7053
+7022
+6FF2
+6FC1
+6F90
+6F5E
+6F2C
+6EFB
+6EC8
+6E96
+6E63
+6E30
+6DFD
+6DC9
+6D95
+6D61
+6D2D
+6CF8
+6CC3
+6C8E
+6C59
+6C23
+6BED
+6BB7
+6B81
+6B4A
+6B13
+6ADC
+6AA4
+6A6D
+6A35
+69FD
+69C4
+698B
+6952
+6919
+68E0
+68A6
+686C
+6832
+67F7
+67BC
+6781
+6746
+670A
+66CF
+6693
+6656
+661A
+65DD
+65A0
+6563
+6525
+64E8
+64AA
+646C
+642D
+63EE
+63AF
+6370
+6331
+62F1
+62B1
+6271
+6231
+61F0
+61AF
+616E
+612D
+60EB
+60AA
+6068
+6025
+5FE3
+5FA0
+5F5D
+5F1A
+5ED7
+5E93
+5E4F
+5E0B
+5DC7
+5D82
+5D3E
+5CF9
+5CB3
+5C6E
+5C28
+5BE2
+5B9C
+5B56
+5B0F
+5AC9
+5A82
+5A3B
+59F3
+59AC
+5964
+591C
+58D3
+588B
+5842
+57F9
+57B0
+5767
+571D
+56D3
+568A
+563F
+55F5
+55AA
+5560
+5515
+54C9
+547E
+5432
+53E7
+539B
+534E
+5302
+52B5
+5268
+521B
+51CE
+5181
+5133
+50E5
+5097
+5049
+4FFB
+4FAC
+4F5D
+4F0E
+4EBF
+4E70
+4E20
+4DD1
+4D81
+4D31
+4CE0
+4C90
+4C3F
+4BEE
+4B9D
+4B4C
+4AFB
+4AA9
+4A58
+4A06
+49B4
+4961
+490F
+48BC
+4869
+4816
+47C3
+4770
+471C
+46C9
+4675
+4621
+45CD
+4578
+4524
+44CF
+447A
+4425
+43D0
+437B
+4325
+42D0
+427A
+4224
+41CE
+4177
+4121
+40CA
+4073
+401D
+3FC5
+3F6E
+3F17
+3EBF
+3E68
+3E10
+3DB8
+3D60
+3D07
+3CAF
+3C56
+3BFE
+3BA5
+3B4C
+3AF2
+3A99
+3A40
+39E6
+398C
+3933
+38D9
+387E
+3824
+37CA
+376F
+3715
+36BA
+365F
+3604
+35A8
+354D
+34F2
+3496
+343A
+33DF
+3383
+3326
+32CA
+326E
+3211
+31B5
+3158
+30FB
+309E
+3041
+2FE4
+2F87
+2F2A
+2ECC
+2E6E
+2E11
+2DB3
+2D55
+2CF7
+2C99
+2C3A
+2BDC
+2B7D
+2B1F
+2AC0
+2A61
+2A02
+29A3
+2944
+28E5
+2886
+2826
+27C7
+2767
+2708
+26A8
+2648
+25E8
+2588
+2528
+24C8
+2467
+2407
+23A6
+2346
+22E5
+2284
+2223
+21C2
+2161
+2100
+209F
+203E
+1FDD
+1F7B
+1F1A
+1EB8
+1E57
+1DF5
+1D93
+1D31
+1CCF
+1C6D
+1C0B
+1BA9
+1B47
+1AE5
+1A82
+1A20
+19BE
+195B
+18F9
+1896
+1833
+17D0
+176E
+170B
+16A8
+1645
+15E2
+157F
+151C
+14B9
+1455
+13F2
+138F
+132B
+12C8
+1264
+1201
+119D
+113A
+10D6
+1072
+100F
+0FAB
+0F47
+0EE3
+0E80
+0E1C
+0DB8
+0D54
+0CF0
+0C8C
+0C28
+0BC4
+0B5F
+0AFB
+0A97
+0A33
+09CF
+096A
+0906
+08A2
+083E
+07D9
+0775
+0711
+06AC
+0648
+05E3
+057F
+051B
+04B6
+0452
+03ED
+0389
+0324
+02C0
+025B
+01F7
+0192
+012E
+00C9
+0065

9_Firmware/9_2_FPGA/fpga_self_test.v

@@ -296,7 +296,7 @@ always @(posedge clk or negedge reset_n) begin
                     state           <= ST_DONE;
                 end
             end
-            // Timeout: if no ADC data after 10000 cycles, FAIL
+            // Timeout: if no ADC data after 1000 cycles (10 us @ 100 MHz), FAIL
             step_cnt <= step_cnt + 1;
             if (step_cnt >= 10'd1000 && adc_cap_cnt == 0) begin
                 result_flags[4] <= 1'b0;

9_Firmware/9_2_FPGA/matched_filter_multi_segment.v

@@ -1,5 +1,8 @@
 `timescale 1ns / 1ps
 // matched_filter_multi_segment.v
+
+`include "radar_params.vh"
+
 module matched_filter_multi_segment (
     input wire clk,           // 100MHz
     input wire reset_n,
@@ -18,14 +21,13 @@ module matched_filter_multi_segment (
     input wire mc_new_elevation,    // Toggle for new elevation (32)
     input wire mc_new_azimuth,      // Toggle for new azimuth (50)
     
-    input wire [15:0] long_chirp_real,
+    // Reference chirp (upstream memory loader selects long/short via use_long_chirp)
-    input wire [15:0] long_chirp_imag,
+    input wire [15:0] ref_chirp_real,
-    input wire [15:0] short_chirp_real,
+    input wire [15:0] ref_chirp_imag,
-    input wire [15:0] short_chirp_imag,
     
     // Memory system interface
     output reg [1:0] segment_request,
-    output wire [9:0] sample_addr_out,  // Tell memory which sample we need
+    output wire [10:0] sample_addr_out,  // Tell memory which sample we need (11-bit for 2048)
     output reg mem_request,
     input wire mem_ready,
     
@@ -39,18 +41,18 @@ module matched_filter_multi_segment (
 );
 
 // ========== FIXED PARAMETERS ==========
-parameter BUFFER_SIZE = 1024;
+parameter BUFFER_SIZE = `RP_FFT_SIZE;              // 2048
-parameter LONG_CHIRP_SAMPLES = 3000;  // Still 3000 samples total
+parameter LONG_CHIRP_SAMPLES = 3000;               // Still 3000 samples total
-parameter SHORT_CHIRP_SAMPLES = 50;   // 0.5�s @ 100MHz
+parameter SHORT_CHIRP_SAMPLES = 50;                // 0.5 us @ 100MHz
-parameter OVERLAP_SAMPLES = 128;      // Standard for 1024-pt FFT
+parameter OVERLAP_SAMPLES = `RP_OVERLAP_SAMPLES;   // 128
-parameter SEGMENT_ADVANCE = BUFFER_SIZE - OVERLAP_SAMPLES;  // 896 samples
+parameter SEGMENT_ADVANCE = `RP_SEGMENT_ADVANCE;   // 2048 - 128 = 1920 samples
-parameter DEBUG = 1;                  // Debug output control
+parameter DEBUG = 1;                               // Debug output control
 
 // Calculate segments needed with overlap
-// For 3072 samples with 128 overlap: 
+// For 3000 samples with 128 overlap:
-// Segments = ceil((3072 - 128) / 896) = ceil(2944/896) = 4
+// Segments = ceil((3000 - 2048) / 1920) + 1 = ceil(952/1920) + 1 = 2
-parameter LONG_SEGMENTS = 4;          // Now exactly 4 segments!
+parameter LONG_SEGMENTS = `RP_LONG_SEGMENTS_3KM;   // 2 segments
-parameter SHORT_SEGMENTS = 1;         // 50 samples padded to 1024
+parameter SHORT_SEGMENTS = 1;                      // 50 samples padded to 2048
 
 // ========== FIXED INTERNAL SIGNALS ==========
 reg signed [31:0] pc_i, pc_q;
@@ -59,19 +61,19 @@ reg pc_valid;
 // Dual buffer for overlap-save — BRAM inferred for synthesis
 (* ram_style = "block" *) reg signed [15:0] input_buffer_i [0:BUFFER_SIZE-1];
 (* ram_style = "block" *) reg signed [15:0] input_buffer_q [0:BUFFER_SIZE-1];
-reg [10:0] buffer_write_ptr;
+reg [11:0] buffer_write_ptr;    // 12-bit for 0..2048
-reg [10:0] buffer_read_ptr;
+reg [11:0] buffer_read_ptr;     // 12-bit for 0..2048
 reg buffer_has_data;
 reg buffer_processing;
 reg [15:0] chirp_samples_collected;
 
 // BRAM write port signals
 reg        buf_we;
-reg [9:0]  buf_waddr;
+reg [10:0] buf_waddr;           // 11-bit for 0..2047
 reg signed [15:0] buf_wdata_i, buf_wdata_q;
 
 // BRAM read port signals
-reg [9:0]  buf_raddr;
+reg [10:0] buf_raddr;           // 11-bit for 0..2047
 reg signed [15:0] buf_rdata_i, buf_rdata_q;
 
 // State machine
@@ -94,15 +96,22 @@ reg chirp_complete;
 reg saw_chain_output;             // Flag: chain started producing output
 
 // Overlap cache — captured during ST_PROCESSING, written back in ST_OVERLAP_COPY
+// Uses sync-only write block to allow distributed RAM inference (not FFs).
+// 128 entries = distributed RAM (LUTRAM), NOT BRAM (too shallow).
 reg signed [15:0] overlap_cache_i [0:OVERLAP_SAMPLES-1];
 reg signed [15:0] overlap_cache_q [0:OVERLAP_SAMPLES-1];
 reg [7:0] overlap_copy_count;
 
+// Overlap cache write port signals (driven from FSM, used in sync-only block)
+reg        ov_we;
+reg [6:0]  ov_waddr;
+reg signed [15:0] ov_wdata_i, ov_wdata_q;
+
 // Microcontroller sync detection
 reg mc_new_chirp_prev, mc_new_elevation_prev, mc_new_azimuth_prev;
-wire chirp_start_pulse = mc_new_chirp && !mc_new_chirp_prev;
+wire chirp_start_pulse = mc_new_chirp ^ mc_new_chirp_prev;           // Toggle-to-pulse (any edge)
-wire elevation_change_pulse = mc_new_elevation && !mc_new_elevation_prev;
+wire elevation_change_pulse = mc_new_elevation ^ mc_new_elevation_prev; // Toggle-to-pulse
-wire azimuth_change_pulse = mc_new_azimuth && !mc_new_azimuth_prev;
+wire azimuth_change_pulse = mc_new_azimuth ^ mc_new_azimuth_prev;     // Toggle-to-pulse
 
 // Processing chain signals
 wire [15:0] fft_pc_i, fft_pc_q;
@@ -115,7 +124,7 @@ reg fft_input_valid;
 reg fft_start;
 
 // ========== SAMPLE ADDRESS OUTPUT ==========
-assign sample_addr_out = buffer_read_ptr;
+assign sample_addr_out = buffer_read_ptr[10:0];
 
 // ========== MICROCONTROLLER SYNC ==========
 always @(posedge clk or negedge reset_n) begin
@@ -152,6 +161,16 @@ always @(posedge clk) begin
     end
 end
 
+// ========== OVERLAP CACHE WRITE PORT (sync only — distributed RAM inference) ==========
+// Removing async reset from memory write path prevents Vivado from
+// synthesizing the 128x16 arrays as FFs + mux trees.
+always @(posedge clk) begin
+    if (ov_we) begin
+        overlap_cache_i[ov_waddr] <= ov_wdata_i;
+        overlap_cache_q[ov_waddr] <= ov_wdata_q;
+    end
+end
+
 // ========== BRAM READ PORT (synchronous, no async reset) ==========
 always @(posedge clk) begin
     buf_rdata_i <= input_buffer_i[buf_raddr];
@@ -183,12 +202,17 @@ always @(posedge clk or negedge reset_n) begin
         buf_wdata_i <= 0;
         buf_wdata_q <= 0;
         buf_raddr <= 0;
+        ov_we <= 0;
+        ov_waddr <= 0;
+        ov_wdata_i <= 0;
+        ov_wdata_q <= 0;
         overlap_copy_count <= 0;
     end else begin
         pc_valid <= 0;
         mem_request <= 0;
         fft_input_valid <= 0;
         buf_we <= 0;  // Default: no write
+        ov_we <= 0;   // Default: no overlap write
         
         case (state)
             ST_IDLE: begin
@@ -223,7 +247,7 @@ always @(posedge clk or negedge reset_n) begin
                 if (ddc_valid && buffer_write_ptr < BUFFER_SIZE) begin
                     // Store in buffer via BRAM write port
                     buf_we <= 1;
-                    buf_waddr <= buffer_write_ptr[9:0];
+                    buf_waddr <= buffer_write_ptr[10:0];
                     buf_wdata_i <= ddc_i[17:2] + ddc_i[1];
                     buf_wdata_q <= ddc_q[17:2] + ddc_q[1];
                     
@@ -244,6 +268,7 @@ always @(posedge clk or negedge reset_n) begin
                     if (!use_long_chirp) begin
                         if (chirp_samples_collected >= SHORT_CHIRP_SAMPLES - 1) begin
                             state <= ST_ZERO_PAD;
+                            chirp_complete <= 1;  // Bug A fix: mark chirp done so ST_OUTPUT exits to IDLE
                             `ifdef SIMULATION
                             $display("[MULTI_SEG_FIXED] Short chirp: collected %d samples, starting zero-pad",
                                      chirp_samples_collected + 1);
@@ -257,8 +282,8 @@ always @(posedge clk or negedge reset_n) begin
                 // missing the transition when buffer_write_ptr updates via
                 // non-blocking assignment one cycle after the last write.
                 //
-                // Overlap-save fix: fill the FULL 1024-sample buffer before
+                // Overlap-save fix: fill the FULL FFT_SIZE-sample buffer before
-                // processing.  For segment 0 this means 1024 fresh samples.
+                // processing.  For segment 0 this means FFT_SIZE fresh samples.
                 // For segments 1+, write_ptr starts at OVERLAP_SAMPLES (128)
                 // so we collect 896 new samples to fill the buffer.
                 if (use_long_chirp) begin
@@ -295,7 +320,7 @@ always @(posedge clk or negedge reset_n) begin
             ST_ZERO_PAD: begin
                 // Zero-pad remaining buffer via BRAM write port
                 buf_we <= 1;
-                buf_waddr <= buffer_write_ptr[9:0];
+                buf_waddr <= buffer_write_ptr[10:0];
                 buf_wdata_i <= 16'd0;
                 buf_wdata_q <= 16'd0;
                 buffer_write_ptr <= buffer_write_ptr + 1;
@@ -315,7 +340,7 @@ always @(posedge clk or negedge reset_n) begin
             
             ST_WAIT_REF: begin
                 // Wait for memory to provide reference coefficients
-                buf_raddr <= 10'd0;  // Pre-present addr 0 so buf_rdata is ready next cycle
+                buf_raddr <= 11'd0;  // Pre-present addr 0 so buf_rdata is ready next cycle
                 if (mem_ready) begin
                     // Start processing — buf_rdata[0] will be valid on FIRST clock of ST_PROCESSING
                     buffer_processing <= 1;
@@ -344,10 +369,12 @@ always @(posedge clk or negedge reset_n) begin
                     // 2. Request corresponding reference sample
                     mem_request <= 1'b1;
                     
-                    // 3. Cache tail samples for overlap-save
+                    // 3. Cache tail samples for overlap-save (via sync-only write port)
                     if (buffer_read_ptr >= SEGMENT_ADVANCE) begin
-                        overlap_cache_i[buffer_read_ptr - SEGMENT_ADVANCE] <= buf_rdata_i;
+                        ov_we <= 1;
-                        overlap_cache_q[buffer_read_ptr - SEGMENT_ADVANCE] <= buf_rdata_q;
+                        ov_waddr <= buffer_read_ptr - SEGMENT_ADVANCE;  // 0..OVERLAP-1
+                        ov_wdata_i <= buf_rdata_i;
+                        ov_wdata_q <= buf_rdata_q;
                     end
                     
                     // Debug every 100 samples
@@ -361,7 +388,7 @@ always @(posedge clk or negedge reset_n) begin
                     end
                     
                     // Present NEXT read address (for next cycle)
-                    buf_raddr <= buffer_read_ptr[9:0] + 10'd1;
+                    buf_raddr <= buffer_read_ptr[10:0] + 11'd1;
                     buffer_read_ptr <= buffer_read_ptr + 1;
                     
                 end else if (buffer_read_ptr >= BUFFER_SIZE) begin
@@ -382,7 +409,7 @@ always @(posedge clk or negedge reset_n) begin
             
             ST_WAIT_FFT: begin
                 // Wait for the processing chain to complete ALL outputs.
-                // The chain streams 1024 samples (fft_pc_valid=1 for 1024 clocks),
+                // The chain streams FFT_SIZE samples (fft_pc_valid=1 for FFT_SIZE clocks),
                 // then transitions to ST_DONE (9) -> ST_IDLE (0).
                 // We track when output starts (saw_chain_output) and only
                 // proceed once the chain returns to idle after outputting.
@@ -454,7 +481,7 @@ always @(posedge clk or negedge reset_n) begin
             ST_OVERLAP_COPY: begin
                 // Write one cached overlap sample per cycle to BRAM
                 buf_we <= 1;
-                buf_waddr <= {{2{1'b0}}, overlap_copy_count};
+                buf_waddr <= {{3{1'b0}}, overlap_copy_count};
                 buf_wdata_i <= overlap_cache_i[overlap_copy_count];
                 buf_wdata_q <= overlap_cache_q[overlap_copy_count];
                 
@@ -500,11 +527,9 @@ matched_filter_processing_chain m_f_p_c(
     // Chirp Selection
     .chirp_counter(chirp_counter),
     
-    // Reference Chirp Memory Interfaces
+    // Reference Chirp Memory Interface (single pair — upstream selects long/short)
-    .long_chirp_real(long_chirp_real),
+    .ref_chirp_real(ref_chirp_real),
-    .long_chirp_imag(long_chirp_imag),
+    .ref_chirp_imag(ref_chirp_imag),
-    .short_chirp_real(short_chirp_real),
-    .short_chirp_imag(short_chirp_imag),
     
     // Output
     .range_profile_i(fft_pc_i),

9_Firmware/9_2_FPGA/matched_filter_processing_chain.v

@@ -15,26 +15,28 @@
  *   .clk, .reset_n
  *   .adc_data_i, .adc_data_q, .adc_valid      <- from input buffer
  *   .chirp_counter                              <- 6-bit frame counter
- *   .long_chirp_real/imag, .short_chirp_real/imag <- reference (time-domain)
+ *   .ref_chirp_real/imag                     <- reference (time-domain)
  *   .range_profile_i, .range_profile_q, .range_profile_valid -> output
  *   .chain_state                                -> 4-bit status
  *
  * Clock domain: clk (100 MHz system clock)
  * Data format:  16-bit signed (Q15 fixed-point)
- * FFT size:     1024 points
+ * FFT size:     2048 points (parameterized via radar_params.vh)
  *
  * Pipeline states:
- *   IDLE -> FWD_FFT (collect 1024 samples + bit-reverse copy)
+ *   IDLE -> FWD_FFT (collect 2048 samples + bit-reverse copy)
  *        -> FWD_BUTTERFLY (forward FFT of signal)
  *        -> REF_BITREV (bit-reverse copy reference into work arrays)
  *        -> REF_BUTTERFLY (forward FFT of reference)
  *        -> MULTIPLY (conjugate multiply in freq domain)
  *        -> INV_BITREV (bit-reverse copy product)
  *        -> INV_BUTTERFLY (inverse FFT + 1/N scaling)
- *        -> OUTPUT (stream 1024 samples)
+ *        -> OUTPUT (stream 2048 samples)
  *        -> DONE -> IDLE
  */
 
+`include "radar_params.vh"
+
 module matched_filter_processing_chain (
     input wire clk,
     input wire reset_n,
@@ -48,10 +50,10 @@ module matched_filter_processing_chain (
     input wire [5:0] chirp_counter,
 
     // Reference chirp (time-domain, latency-aligned by upstream buffer)
-    input wire [15:0] long_chirp_real,
+    // Upstream chirp_memory_loader_param selects long/short reference
-    input wire [15:0] long_chirp_imag,
+    // via use_long_chirp — this single pair carries whichever is active.
-    input wire [15:0] short_chirp_real,
+    input wire [15:0] ref_chirp_real,
-    input wire [15:0] short_chirp_imag,
+    input wire [15:0] ref_chirp_imag,
 
     // Output: range profile (pulse-compressed)
     output wire signed [15:0] range_profile_i,
@@ -66,8 +68,8 @@ module matched_filter_processing_chain (
 // ============================================================================
 // PARAMETERS
 // ============================================================================
-localparam FFT_SIZE   = 1024;
+localparam FFT_SIZE   = `RP_FFT_SIZE;    // 2048
-localparam ADDR_BITS  = 10;    // log2(1024)
+localparam ADDR_BITS  = `RP_LOG2_FFT_SIZE; // log2(2048) = 11
 
 // State encoding (4-bit, up to 16 states)
 localparam [3:0] ST_IDLE           = 4'd0;
@@ -87,8 +89,8 @@ reg [3:0] state;
 // SIGNAL BUFFERS
 // ============================================================================
 // Input sample counter
-reg [ADDR_BITS:0] fwd_in_count;     // 0..1024
+reg [ADDR_BITS:0] fwd_in_count;     // 0..FFT_SIZE
-reg fwd_frame_done;                  // All 1024 samples received
+reg fwd_frame_done;                  // All FFT_SIZE samples received
 
 // Signal time-domain buffer
 reg signed [15:0] fwd_buf_i [0:FFT_SIZE-1];
@@ -175,7 +177,7 @@ always @(posedge clk or negedge reset_n) begin
 
         case (state)
         // ================================================================
-        // IDLE: Wait for valid ADC data, start collecting 1024 samples
+        // IDLE: Wait for valid ADC data, start collecting 2048 samples
         // ================================================================
         ST_IDLE: begin
             fwd_in_count   <= 0;
@@ -189,8 +191,8 @@ always @(posedge clk or negedge reset_n) begin
                 // Store first sample (signal + reference)
                 fwd_buf_i[0] <= $signed(adc_data_i);
                 fwd_buf_q[0] <= $signed(adc_data_q);
-                ref_buf_i[0] <= $signed(long_chirp_real);
+                ref_buf_i[0] <= $signed(ref_chirp_real);
-                ref_buf_q[0] <= $signed(long_chirp_imag);
+                ref_buf_q[0] <= $signed(ref_chirp_imag);
                 fwd_in_count <= 1;
                 state        <= ST_FWD_FFT;
             end
@@ -198,6 +200,7 @@ always @(posedge clk or negedge reset_n) begin
 
         // ================================================================
         // FWD_FFT: Collect remaining samples, then bit-reverse copy signal
+        // (2048 samples total)
         // ================================================================
         ST_FWD_FFT: begin
             if (!fwd_frame_done) begin
@@ -205,8 +208,8 @@ always @(posedge clk or negedge reset_n) begin
                 if (adc_valid && fwd_in_count < FFT_SIZE) begin
                     fwd_buf_i[fwd_in_count] <= $signed(adc_data_i);
                     fwd_buf_q[fwd_in_count] <= $signed(adc_data_q);
-                    ref_buf_i[fwd_in_count] <= $signed(long_chirp_real);
+                    ref_buf_i[fwd_in_count] <= $signed(ref_chirp_real);
-                    ref_buf_q[fwd_in_count] <= $signed(long_chirp_imag);
+                    ref_buf_q[fwd_in_count] <= $signed(ref_chirp_imag);
                     fwd_in_count <= fwd_in_count + 1;
                 end
 
@@ -437,7 +440,7 @@ always @(posedge clk or negedge reset_n) begin
                 end
             end
 
-            // Scale by 1/N (right shift by log2(1024) = 10) and store
+            // Scale by 1/N (right shift by log2(2048) = 11) and store
             for (i = 0; i < FFT_SIZE; i = i + 1) begin : ifft_scale
                 reg signed [31:0] scaled_re, scaled_im;
                 scaled_re = work_re[i] >>> ADDR_BITS;
@@ -467,7 +470,7 @@ always @(posedge clk or negedge reset_n) begin
         end
 
         // ================================================================
-        // OUTPUT: Stream out 1024 range profile samples, one per clock
+        // OUTPUT: Stream out 2048 range profile samples, one per clock
         // ================================================================
         ST_OUTPUT: begin
             if (out_count < FFT_SIZE) begin
@@ -531,16 +534,16 @@ end
 // ============================================================================
 // SYNTHESIS IMPLEMENTATION — Radix-2 DIT FFT via fft_engine
 // ============================================================================
-// Uses a single fft_engine instance (1024-pt) reused 3 times:
+// Uses a single fft_engine instance (2048-pt) reused 3 times:
 //   1. Forward FFT of signal
 //   2. Forward FFT of reference
 //   3. Inverse FFT of conjugate product
 // Conjugate multiply done via frequency_matched_filter (4-stage pipeline).
 //
 // Buffer scheme (BRAM-inferrable):
-//   sig_buf[1024]:  ADC input -> signal FFT output
+//   sig_buf[2048]:  ADC input -> signal FFT output
-//   ref_buf[1024]:  Reference input -> reference FFT output
+//   ref_buf[2048]:  Reference input -> reference FFT output
-//   prod_buf[1024]: Conjugate multiply output -> IFFT output
+//   prod_buf[2048]: Conjugate multiply output -> IFFT output
 //
 // Memory access is INSIDE always @(posedge clk) blocks (no async reset)
 // using local blocking variables. This eliminates NBA race conditions
@@ -552,12 +555,12 @@ end
 //   out_primed   — for output streaming
 // ============================================================================
 
-localparam FFT_SIZE  = 1024;
+localparam FFT_SIZE  = `RP_FFT_SIZE;    // 2048
-localparam ADDR_BITS = 10;
+localparam ADDR_BITS = `RP_LOG2_FFT_SIZE; // 11
 
 // State encoding
 localparam [3:0] ST_IDLE     = 4'd0,
-                 ST_COLLECT  = 4'd1,   // Collect 1024 ADC + ref samples
+                 ST_COLLECT  = 4'd1,   // Collect FFT_SIZE ADC + ref samples
                  ST_SIG_FFT  = 4'd2,   // Forward FFT of signal
                  ST_SIG_CAP  = 4'd3,   // Capture signal FFT output
                  ST_REF_FFT  = 4'd4,   // Forward FFT of reference
@@ -565,7 +568,7 @@ localparam [3:0] ST_IDLE     = 4'd0,
                  ST_MULTIPLY = 4'd6,   // Conjugate multiply (pipelined)
                  ST_INV_FFT  = 4'd7,   // Inverse FFT of product
                  ST_INV_CAP  = 4'd8,   // Capture IFFT output
-                 ST_OUTPUT   = 4'd9,   // Stream 1024 results
+                 ST_OUTPUT   = 4'd9,   // Stream FFT_SIZE results
                  ST_DONE     = 4'd10;
 
 reg [3:0] state;
@@ -588,11 +591,11 @@ reg signed [15:0] prod_rdata_i, prod_rdata_q;
 // ============================================================================
 // COUNTERS
 // ============================================================================
-reg [ADDR_BITS:0] collect_count;   // 0..1024 for sample collection
+reg [ADDR_BITS:0] collect_count;   // 0..FFT_SIZE for sample collection
-reg [ADDR_BITS:0] feed_count;      // 0..1024 for feeding FFT engine
+reg [ADDR_BITS:0] feed_count;      // 0..FFT_SIZE for feeding FFT engine
-reg [ADDR_BITS:0] cap_count;       // 0..1024 for capturing FFT output
+reg [ADDR_BITS:0] cap_count;       // 0..FFT_SIZE for capturing FFT output
-reg [ADDR_BITS:0] mult_count;      // 0..1024 for multiply feeding
+reg [ADDR_BITS:0] mult_count;      // 0..FFT_SIZE for multiply feeding
-reg [ADDR_BITS:0] out_count;       // 0..1024 for output streaming
+reg [ADDR_BITS:0] out_count;       // 0..FFT_SIZE for output streaming
 
 // BRAM read latency pipeline flags
 reg feed_primed;   // 1 = BRAM rdata valid for feed operations
@@ -617,7 +620,7 @@ fft_engine #(
     .DATA_W(16),
     .INTERNAL_W(32),
     .TWIDDLE_W(16),
-    .TWIDDLE_FILE("fft_twiddle_1024.mem")
+    .TWIDDLE_FILE("fft_twiddle_2048.mem")
 ) fft_inst (
     .clk(clk),
     .reset_n(reset_n),
@@ -775,16 +778,16 @@ always @(posedge clk) begin : ref_bram_port
         if (adc_valid) begin
             we      = 1'b1;
             addr    = 0;
-            wdata_i = $signed(long_chirp_real);
+            wdata_i = $signed(ref_chirp_real);
-            wdata_q = $signed(long_chirp_imag);
+            wdata_q = $signed(ref_chirp_imag);
         end
     end
     ST_COLLECT: begin
         if (adc_valid && collect_count < FFT_SIZE) begin
             we      = 1'b1;
             addr    = collect_count[ADDR_BITS-1:0];
-            wdata_i = $signed(long_chirp_real);
+            wdata_i = $signed(ref_chirp_real);
-            wdata_q = $signed(long_chirp_imag);
+            wdata_q = $signed(ref_chirp_imag);
         end
     end
     ST_REF_FFT: begin
@@ -968,7 +971,7 @@ always @(posedge clk or negedge reset_n) begin
         end
 
         // ================================================================
-        // COLLECT: Gather 1024 ADC + reference samples
+        // COLLECT: Gather 2048 ADC + reference samples
         // Writes happen in sig/ref BRAM ports (they see state==ST_COLLECT)
         // ================================================================
         ST_COLLECT: begin
@@ -977,7 +980,7 @@ always @(posedge clk or negedge reset_n) begin
             end
 
             if (collect_count == FFT_SIZE) begin
-                // All 1024 samples collected — start signal FFT
+                // All 2048 samples collected — start signal FFT
                 state       <= ST_SIG_FFT;
                 fft_start   <= 1'b1;
                 fft_inverse <= 1'b0;  // Forward FFT
@@ -1091,7 +1094,7 @@ always @(posedge clk or negedge reset_n) begin
         // ================================================================
         // MULTIPLY: Stream sig FFT and ref FFT through freq_matched_filter
         // Both sig_buf and ref_buf are read simultaneously (separate BRAM
-        // ports). Pipeline latency = 4 clocks. Feed 1024 pairs, then flush.
+        // ports). Pipeline latency = 4 clocks. Feed 2048 pairs, then flush.
         // ================================================================
         ST_MULTIPLY: begin
             if (mult_count < FFT_SIZE) begin
@@ -1180,7 +1183,7 @@ always @(posedge clk or negedge reset_n) begin
         end
 
         // ================================================================
-        // OUTPUT: Stream 1024 range profile samples
+        // OUTPUT: Stream 2048 range profile samples
         // BRAM read latency: present address, data valid next cycle.
         // ================================================================
         ST_OUTPUT: begin

9_Firmware/9_2_FPGA/mti_canceller.v

@@ -19,25 +19,33 @@
  *     mti_out_i[r] = current_i[r] - previous_i[r]
  *     mti_out_q[r] = current_q[r] - previous_q[r]
  *
- * The previous chirp's 64 range bins are stored in a small BRAM.
+ * The previous chirp's 512 range bins are stored in BRAM (inferred via
+ * sync-only read/write always blocks — NO async reset on memory arrays).
  * On the very first chirp after reset (or enable), there is no previous
  * data — output is zero (muted) for that first chirp.
  *
- * When mti_enable=0, the module is a transparent pass-through with zero
+ * When mti_enable=0, the module is a transparent pass-through.
- * latency penalty (data goes straight through combinationally registered).
  *
- * Resources:
+ * BRAM inference note:
- *   - 2 BRAM18 (64 x 16-bit I + 64 x 16-bit Q) or distributed RAM
+ *   prev_i/prev_q arrays use dedicated sync-only always blocks for read
- *   - ~30 LUTs (subtract + mux)
+ *   and write. This ensures Vivado infers BRAM (RAMB18) instead of fabric
- *   - ~40 FFs (pipeline + control)
+ *   FFs + mux trees. The registered read adds 1 cycle of latency, which
+ *   is compensated by a pipeline stage on the input data path.
+ *
+ * Resources (target):
+ *   - 2 BRAM18 (512 x 16-bit I + 512 x 16-bit Q)
+ *   - ~30 LUTs (subtract + mux + saturation)
+ *   - ~80 FFs (pipeline + control)
  *   - 0 DSP48
  *
  * Clock domain: clk (100 MHz)
  */
 
+`include "radar_params.vh"
+
 module mti_canceller #(
-    parameter NUM_RANGE_BINS = 64,
+    parameter NUM_RANGE_BINS = `RP_NUM_RANGE_BINS,    // 512
-    parameter DATA_WIDTH     = 16
+    parameter DATA_WIDTH     = `RP_DATA_WIDTH         // 16
 ) (
     input wire clk,
     input wire reset_n,
@@ -46,13 +54,13 @@ module mti_canceller #(
     input wire signed [DATA_WIDTH-1:0] range_i_in,
     input wire signed [DATA_WIDTH-1:0] range_q_in,
     input wire                         range_valid_in,
-    input wire [5:0]                   range_bin_in,
+    input wire [`RP_RANGE_BIN_BITS-1:0] range_bin_in,   // 9-bit
 
     // ========== OUTPUT (to Doppler processor) ==========
     output reg signed [DATA_WIDTH-1:0] range_i_out,
     output reg signed [DATA_WIDTH-1:0] range_q_out,
     output reg                         range_valid_out,
-    output reg [5:0]                   range_bin_out,
+    output reg [`RP_RANGE_BIN_BITS-1:0] range_bin_out,   // 9-bit
 
     // ========== CONFIGURATION ==========
     input wire mti_enable,   // 1=MTI active, 0=pass-through
@@ -62,30 +70,79 @@ module mti_canceller #(
 );
 
 // ============================================================================
-// PREVIOUS CHIRP BUFFER (64 x 16-bit I, 64 x 16-bit Q)
+// PREVIOUS CHIRP BUFFER (512 x 16-bit I, 512 x 16-bit Q)
 // ============================================================================
-// Small enough for distributed RAM on XC7A200T (64 entries).
+// BRAM-inferred on XC7A50T/200T (512 entries, sync-only read/write).
-// Using separate I/Q arrays for clean read/write.
+// Using separate I/Q arrays for clean dual-port inference.
 
-reg signed [DATA_WIDTH-1:0] prev_i [0:NUM_RANGE_BINS-1];
+(* ram_style = "block" *) reg signed [DATA_WIDTH-1:0] prev_i [0:NUM_RANGE_BINS-1];
-reg signed [DATA_WIDTH-1:0] prev_q [0:NUM_RANGE_BINS-1];
+(* ram_style = "block" *) reg signed [DATA_WIDTH-1:0] prev_q [0:NUM_RANGE_BINS-1];
+
+// ============================================================================
+// INPUT PIPELINE STAGE (1 cycle delay to match BRAM read latency)
+// ============================================================================
+// Declarations must precede the BRAM write block that references them.
+
+reg signed [DATA_WIDTH-1:0] range_i_d1, range_q_d1;
+reg                         range_valid_d1;
+reg [`RP_RANGE_BIN_BITS-1:0] range_bin_d1;
+reg                         mti_enable_d1;
+
+always @(posedge clk or negedge reset_n) begin
+    if (!reset_n) begin
+        range_i_d1     <= {DATA_WIDTH{1'b0}};
+        range_q_d1     <= {DATA_WIDTH{1'b0}};
+        range_valid_d1 <= 1'b0;
+        range_bin_d1   <= {`RP_RANGE_BIN_BITS{1'b0}};
+        mti_enable_d1  <= 1'b0;
+    end else begin
+        range_i_d1     <= range_i_in;
+        range_q_d1     <= range_q_in;
+        range_valid_d1 <= range_valid_in;
+        range_bin_d1   <= range_bin_in;
+        mti_enable_d1  <= mti_enable;
+    end
+end
+
+// ============================================================================
+// BRAM WRITE PORT (sync only — NO async reset for BRAM inference)
+// ============================================================================
+// Writes the current chirp sample into prev_i/prev_q for next chirp's
+// subtraction. Uses the delayed (d1) signals so the write happens 1 cycle
+// after the read address is presented, avoiding RAW hazards.
+
+always @(posedge clk) begin
+    if (range_valid_d1) begin
+        prev_i[range_bin_d1] <= range_i_d1;
+        prev_q[range_bin_d1] <= range_q_d1;
+    end
+end
+
+// ============================================================================
+// BRAM READ PORT (sync only — 1 cycle read latency)
+// ============================================================================
+// Address is always driven by range_bin_in (cycle 0). Read data appears
+// on prev_i_rd / prev_q_rd at cycle 1, aligned with the d1 pipeline stage.
+
+reg signed [DATA_WIDTH-1:0] prev_i_rd, prev_q_rd;
+
+always @(posedge clk) begin
+    prev_i_rd <= prev_i[range_bin_in];
+    prev_q_rd <= prev_q[range_bin_in];
+end
 
 // Track whether we have valid previous data
 reg has_previous;
 
 // ============================================================================
-// MTI PROCESSING
+// MTI PROCESSING (operates on d1 pipeline stage + BRAM read data)
 // ============================================================================
 
-// Read previous chirp data (combinational)
-wire signed [DATA_WIDTH-1:0] prev_i_rd = prev_i[range_bin_in];
-wire signed [DATA_WIDTH-1:0] prev_q_rd = prev_q[range_bin_in];
-
 // Compute difference with saturation
 // Subtraction can produce DATA_WIDTH+1 bits; saturate back to DATA_WIDTH.
-wire signed [DATA_WIDTH:0] diff_i_full = {range_i_in[DATA_WIDTH-1], range_i_in}
+wire signed [DATA_WIDTH:0] diff_i_full = {range_i_d1[DATA_WIDTH-1], range_i_d1}
                                         - {prev_i_rd[DATA_WIDTH-1], prev_i_rd};
-wire signed [DATA_WIDTH:0] diff_q_full = {range_q_in[DATA_WIDTH-1], range_q_in}
+wire signed [DATA_WIDTH:0] diff_q_full = {range_q_d1[DATA_WIDTH-1], range_q_d1}
                                         - {prev_q_rd[DATA_WIDTH-1], prev_q_rd};
 
 // Saturate to DATA_WIDTH bits
@@ -105,32 +162,28 @@ assign diff_q_sat = (diff_q_full > $signed({{2{1'b0}}, {(DATA_WIDTH-1){1'b1}}}))
                   : diff_q_full[DATA_WIDTH-1:0];
 
 // ============================================================================
-// MAIN LOGIC
+// MAIN OUTPUT LOGIC (operates on d1 pipeline stage)
 // ============================================================================
 always @(posedge clk or negedge reset_n) begin
     if (!reset_n) begin
         range_i_out     <= {DATA_WIDTH{1'b0}};
         range_q_out     <= {DATA_WIDTH{1'b0}};
         range_valid_out <= 1'b0;
-        range_bin_out   <= 6'd0;
+        range_bin_out   <= {`RP_RANGE_BIN_BITS{1'b0}};
         has_previous    <= 1'b0;
         mti_first_chirp <= 1'b1;
     end else begin
         // Default: no valid output
         range_valid_out <= 1'b0;
 
-        if (range_valid_in) begin
+        if (range_valid_d1) begin
-            // Always store current sample as "previous" for next chirp
+            // Output path — range_bin is from the delayed pipeline
-            prev_i[range_bin_in] <= range_i_in;
+            range_bin_out <= range_bin_d1;
-            prev_q[range_bin_in] <= range_q_in;
 
-            // Output path
+            if (!mti_enable_d1) begin
-            range_bin_out <= range_bin_in;
-
-            if (!mti_enable) begin
                 // Pass-through mode: no MTI processing
-                range_i_out     <= range_i_in;
+                range_i_out     <= range_i_d1;
-                range_q_out     <= range_q_in;
+                range_q_out     <= range_q_d1;
                 range_valid_out <= 1'b1;
                 // Reset first-chirp state when MTI is disabled
                 has_previous    <= 1'b0;
@@ -144,7 +197,7 @@ always @(posedge clk or negedge reset_n) begin
                 range_valid_out <= 1'b1;
 
                 // After last range bin of first chirp, mark previous as valid
-                if (range_bin_in == NUM_RANGE_BINS - 1) begin
+                if (range_bin_d1 == NUM_RANGE_BINS - 1) begin
                     has_previous    <= 1'b1;
                     mti_first_chirp <= 1'b0;
                 end

9_Firmware/9_2_FPGA/radar_mode_controller.v

@@ -1,5 +1,7 @@
 `timescale 1ns / 1ps
 
+`include "radar_params.vh"
+
 /**
  * radar_mode_controller.v
  *
@@ -18,12 +20,18 @@
  *   - 32 chirps per elevation
  *   - 31 elevations per azimuth
  *   - 50 azimuths per full scan
- *   - Each chirp: Long chirp → Listen → Guard → Short chirp → Listen
  *
- * Modes of operation:
+ * Chirp sequence depends on range_mode (host_range_mode, opcode 0x20):
+ *   range_mode 2'b00 (3 km):  All short chirps only. Long chirp blind zone
+ *     (4500 m) exceeds 3 km max range, so long chirps are useless.
+ *   range_mode 2'b01 (long-range): Dual chirp — Long chirp → Listen → Guard
+ *     → Short chirp → Listen. First half of chirps_per_elev are long, second
+ *     half are short (blind-zone fill).
+ *
+ * Modes of operation (host_radar_mode, opcode 0x01):
  *   mode[1:0]:
  *     2'b00 = STM32-driven (pass through stm32 toggle signals)
- *     2'b01 = Free-running auto-scan (internal timing)
+ *     2'b01 = Free-running auto-scan (internal timing, short chirps only)
  *     2'b10 = Single-chirp (fire one chirp per trigger, for debug)
  *     2'b11 = Reserved
  *
@@ -31,9 +39,9 @@
  */
 
 module radar_mode_controller #(
-    parameter CHIRPS_PER_ELEVATION = 32,
+    parameter CHIRPS_PER_ELEVATION  = `RP_DEF_CHIRPS_PER_ELEV,
     parameter ELEVATIONS_PER_AZIMUTH = 31,
-    parameter AZIMUTHS_PER_SCAN = 50,
+    parameter AZIMUTHS_PER_SCAN     = 50,
 
     // Timing in 100 MHz clock cycles
     // Long chirp: 30us = 3000 cycles at 100 MHz
@@ -41,18 +49,24 @@ module radar_mode_controller #(
     // Guard: 175.4us = 17540 cycles
     // Short chirp: 0.5us = 50 cycles
     // Short listen: 174.5us = 17450 cycles
-    parameter LONG_CHIRP_CYCLES   = 3000,
+    parameter LONG_CHIRP_CYCLES   = `RP_DEF_LONG_CHIRP_CYCLES,
-    parameter LONG_LISTEN_CYCLES  = 13700,
+    parameter LONG_LISTEN_CYCLES  = `RP_DEF_LONG_LISTEN_CYCLES,
-    parameter GUARD_CYCLES        = 17540,
+    parameter GUARD_CYCLES        = `RP_DEF_GUARD_CYCLES,
-    parameter SHORT_CHIRP_CYCLES  = 50,
+    parameter SHORT_CHIRP_CYCLES  = `RP_DEF_SHORT_CHIRP_CYCLES,
-    parameter SHORT_LISTEN_CYCLES = 17450
+    parameter SHORT_LISTEN_CYCLES = `RP_DEF_SHORT_LISTEN_CYCLES
 ) (
     input wire clk,
     input wire reset_n,
 
-    // Mode selection
+    // Mode selection (host_radar_mode, opcode 0x01)
     input wire [1:0] mode,          // 00=STM32, 01=auto, 10=single, 11=rsvd
 
+    // Range mode (host_range_mode, opcode 0x20)
+    // Determines chirp type selection in pass-through and auto-scan modes.
+    //   2'b00 = 3 km  (all short chirps — long blind zone > max range)
+    //   2'b01 = Long-range (dual chirp: first half long, second half short)
+    input wire [1:0] range_mode,
+
     // STM32 pass-through inputs (active in mode 00)
     input wire stm32_new_chirp,
     input wire stm32_new_elevation,
@@ -61,10 +75,8 @@ module radar_mode_controller #(
     // Single-chirp trigger (active in mode 10)
     input wire trigger,
 
-    // Gap 2: Runtime-configurable timing inputs from host USB commands.
+    // Runtime-configurable timing inputs from host USB commands.
     // When connected, these override the compile-time parameters.
-    // When left at default (tied to parameter values at instantiation),
-    // behavior is identical to pre-Gap-2.
     input wire [15:0] cfg_long_chirp_cycles,
     input wire [15:0] cfg_long_listen_cycles,
     input wire [15:0] cfg_guard_cycles,
@@ -156,7 +168,7 @@ always @(posedge clk or negedge reset_n) begin
     if (!reset_n) begin
         scan_state      <= S_IDLE;
         timer           <= 18'd0;
-        use_long_chirp  <= 1'b1;
+        use_long_chirp  <= 1'b0;  // Default short chirp (safe for 3 km mode)
         mc_new_chirp    <= 1'b0;
         mc_new_elevation <= 1'b0;
         mc_new_azimuth  <= 1'b0;
@@ -172,7 +184,12 @@ always @(posedge clk or negedge reset_n) begin
         // ================================================================
         // MODE 00: STM32-driven pass-through
         // The STM32 firmware controls timing; we just detect toggle edges
-        // and forward them to the receiver chain.
+        // and forward them to the receiver chain. Chirp type is determined
+        // by range_mode:
+        //   range_mode 00 (3 km):  ALL chirps are short (long blind zone
+        //     4500 m exceeds 3072 m max range, so long chirps are useless).
+        //   range_mode 01 (long-range): First half of chirps_per_elev are
+        //     long, second half are short (blind-zone fill).
         // ================================================================
         2'b00: begin
             // Reset auto-scan state
@@ -182,9 +199,29 @@ always @(posedge clk or negedge reset_n) begin
             // Pass through toggle signals
             if (stm32_chirp_toggle) begin
                 mc_new_chirp <= ~mc_new_chirp;  // Toggle output
-                use_long_chirp <= 1'b1;         // Default to long chirp
 
-                // Track chirp count (Gap 2: use runtime cfg_chirps_per_elev)
+                // Determine chirp type based on range_mode
+                case (range_mode)
+                `RP_RANGE_MODE_3KM: begin
+                    // 3 km mode: all short chirps
+                    use_long_chirp <= 1'b0;
+                end
+                `RP_RANGE_MODE_LONG: begin
+                    // Long-range: first half long, second half short.
+                    // chirps_per_elev is typically 32 (16 long + 16 short).
+                    // Use cfg_chirps_per_elev[5:1] as the halfway point.
+                    if (chirp_count < {1'b0, cfg_chirps_per_elev[5:1]})
+                        use_long_chirp <= 1'b1;
+                    else
+                        use_long_chirp <= 1'b0;
+                end
+                default: begin
+                    // Reserved modes: default to short chirp (safe)
+                    use_long_chirp <= 1'b0;
+                end
+                endcase
+
+                // Track chirp count
                 if (chirp_count < cfg_chirps_per_elev - 1)
                     chirp_count <= chirp_count + 1;
                 else
@@ -217,21 +254,33 @@ always @(posedge clk or negedge reset_n) begin
         // ================================================================
         // MODE 01: Free-running auto-scan
         // Internally generates chirp timing matching the transmitter.
+        // For 3 km mode (range_mode 00): short chirps only. The long chirp
+        // blind zone (4500 m) exceeds the 3072 m max range, making long
+        // chirps useless. State machine skips S_LONG_CHIRP/LISTEN/GUARD.
+        // For long-range mode (range_mode 01): full dual-chirp sequence.
+        // NOTE: Auto-scan is primarily for bench testing without STM32.
         // ================================================================
         2'b01: begin
             case (scan_state)
             S_IDLE: begin
                 // Start first chirp immediately
-                scan_state     <= S_LONG_CHIRP;
+                timer           <= 18'd0;
-                timer          <= 18'd0;
+                chirp_count     <= 6'd0;
-                use_long_chirp <= 1'b1;
-                mc_new_chirp   <= ~mc_new_chirp;  // Toggle to start chirp
-                chirp_count    <= 6'd0;
                 elevation_count <= 6'd0;
-                azimuth_count  <= 6'd0;
+                azimuth_count   <= 6'd0;
+                mc_new_chirp    <= ~mc_new_chirp;  // Toggle to start chirp
+
+                // For 3 km mode, skip directly to short chirp
+                if (range_mode == `RP_RANGE_MODE_3KM) begin
+                    scan_state     <= S_SHORT_CHIRP;
+                    use_long_chirp <= 1'b0;
+                end else begin
+                    scan_state     <= S_LONG_CHIRP;
+                    use_long_chirp <= 1'b1;
+                end
 
                 `ifdef SIMULATION
-                $display("[MODE_CTRL] Auto-scan starting");
+                $display("[MODE_CTRL] Auto-scan starting, range_mode=%0d", range_mode);
                 `endif
             end
 
@@ -285,13 +334,19 @@ always @(posedge clk or negedge reset_n) begin
 
             S_ADVANCE: begin
                 // Advance chirp/elevation/azimuth counters
-                // (Gap 2: use runtime cfg_chirps_per_elev)
                 if (chirp_count < cfg_chirps_per_elev - 1) begin
                     // Next chirp in current elevation
                     chirp_count  <= chirp_count + 1;
                     mc_new_chirp <= ~mc_new_chirp;
-                    scan_state   <= S_LONG_CHIRP;
+
-                    use_long_chirp <= 1'b1;
+                    // For 3 km mode: short chirps only, skip long phases
+                    if (range_mode == `RP_RANGE_MODE_3KM) begin
+                        scan_state     <= S_SHORT_CHIRP;
+                        use_long_chirp <= 1'b0;
+                    end else begin
+                        scan_state     <= S_LONG_CHIRP;
+                        use_long_chirp <= 1'b1;
+                    end
                 end else begin
                     chirp_count <= 6'd0;
 
@@ -300,8 +355,14 @@ always @(posedge clk or negedge reset_n) begin
                         elevation_count  <= elevation_count + 1;
                         mc_new_chirp     <= ~mc_new_chirp;
                         mc_new_elevation <= ~mc_new_elevation;
-                        scan_state       <= S_LONG_CHIRP;
+
-                        use_long_chirp   <= 1'b1;
+                        if (range_mode == `RP_RANGE_MODE_3KM) begin
+                            scan_state     <= S_SHORT_CHIRP;
+                            use_long_chirp <= 1'b0;
+                        end else begin
+                            scan_state     <= S_LONG_CHIRP;
+                            use_long_chirp <= 1'b1;
+                        end
                     end else begin
                         elevation_count <= 6'd0;
 
@@ -311,8 +372,14 @@ always @(posedge clk or negedge reset_n) begin
                             mc_new_chirp     <= ~mc_new_chirp;
                             mc_new_elevation <= ~mc_new_elevation;
                             mc_new_azimuth   <= ~mc_new_azimuth;
-                            scan_state       <= S_LONG_CHIRP;
+
-                            use_long_chirp   <= 1'b1;
+                            if (range_mode == `RP_RANGE_MODE_3KM) begin
+                                scan_state     <= S_SHORT_CHIRP;
+                                use_long_chirp <= 1'b0;
+                            end else begin
+                                scan_state     <= S_LONG_CHIRP;
+                                use_long_chirp <= 1'b1;
+                            end
                         end else begin
                             // Full scan complete — restart
                             azimuth_count   <= 6'd0;
@@ -320,8 +387,14 @@ always @(posedge clk or negedge reset_n) begin
                             mc_new_chirp    <= ~mc_new_chirp;
                             mc_new_elevation <= ~mc_new_elevation;
                             mc_new_azimuth  <= ~mc_new_azimuth;
-                            scan_state      <= S_LONG_CHIRP;
+
-                            use_long_chirp  <= 1'b1;
+                            if (range_mode == `RP_RANGE_MODE_3KM) begin
+                                scan_state     <= S_SHORT_CHIRP;
+                                use_long_chirp <= 1'b0;
+                            end else begin
+                                scan_state     <= S_LONG_CHIRP;
+                                use_long_chirp <= 1'b1;
+                            end
 
                             `ifdef SIMULATION
                             $display("[MODE_CTRL] Full scan complete, restarting");
@@ -337,16 +410,27 @@ always @(posedge clk or negedge reset_n) begin
 
         // ================================================================
         // MODE 10: Single-chirp (debug mode)
-        // Fire one long chirp per trigger pulse, no scanning.
+        // Fire one chirp per trigger pulse, no scanning.
+        // Chirp type depends on range_mode:
+        //   3 km:  short chirp only
+        //   Long-range: long chirp (for testing long-chirp path)
         // ================================================================
         2'b10: begin
             case (scan_state)
             S_IDLE: begin
                 if (trigger_pulse) begin
-                    scan_state     <= S_LONG_CHIRP;
+                    timer        <= 18'd0;
-                    timer          <= 18'd0;
+                    mc_new_chirp <= ~mc_new_chirp;
-                    use_long_chirp <= 1'b1;
+
-                    mc_new_chirp   <= ~mc_new_chirp;
+                    if (range_mode == `RP_RANGE_MODE_3KM) begin
+                        // 3 km: fire short chirp
+                        scan_state     <= S_SHORT_CHIRP;
+                        use_long_chirp <= 1'b0;
+                    end else begin
+                        // Long-range: fire long chirp
+                        scan_state     <= S_LONG_CHIRP;
+                        use_long_chirp <= 1'b1;
+                    end
                 end
             end
 
@@ -363,7 +447,27 @@ always @(posedge clk or negedge reset_n) begin
                 if (timer < cfg_long_listen_cycles - 1)
                     timer <= timer + 1;
                 else begin
-                    // Single chirp done, return to idle
+                    // Single long chirp done, return to idle
+                    timer      <= 18'd0;
+                    scan_state <= S_IDLE;
+                end
+            end
+
+            S_SHORT_CHIRP: begin
+                use_long_chirp <= 1'b0;
+                if (timer < cfg_short_chirp_cycles - 1)
+                    timer <= timer + 1;
+                else begin
+                    timer <= 18'd0;
+                    scan_state <= S_SHORT_LISTEN;
+                end
+            end
+
+            S_SHORT_LISTEN: begin
+                if (timer < cfg_short_listen_cycles - 1)
+                    timer <= timer + 1;
+                else begin
+                    // Single short chirp done, return to idle
                     timer      <= 18'd0;
                     scan_state <= S_IDLE;
                 end

9_Firmware/9_2_FPGA/radar_params.vh

@@ -0,0 +1,228 @@
+// ============================================================================
+// radar_params.vh — Single Source of Truth for AERIS-10 FPGA Parameters
+// ============================================================================
+//
+// ALL modules in the FPGA processing chain MUST `include this file instead of
+// hardcoding range bins, segment counts, chirp samples, or timing values.
+//
+// This file uses `define macros (not localparam) so it can be included at any
+// scope. Each consuming module should include this file inside its body and
+// optionally alias macros to localparams for readability.
+//
+// BOARD VARIANTS:
+//   SUPPORT_LONG_RANGE = 0  (50T, USB_MODE=1)  — 3 km mode only
+//   SUPPORT_LONG_RANGE = 1  (200T, USB_MODE=0) — 3 km + 20 km modes
+//
+// RADAR MODES (runtime, via host_radar_mode register, opcode 0x01):
+//   2'b00 = STM32 pass-through (production — STM32 controls chirp timing)
+//   2'b01 = Auto-scan 3 km     (FPGA-timed, short chirps only)
+//   2'b10 = Single-chirp debug (one long chirp per trigger)
+//   2'b11 = Reserved / idle
+//
+// RANGE MODES (runtime, via host_range_mode register, opcode 0x20):
+//   2'b00 = 3 km   (default — pass-through treats all chirps as short)
+//   2'b01 = Long-range (pass-through: first half long, second half short)
+//   2'b10 = Reserved
+//   2'b11 = Reserved
+//
+// USAGE:
+//   `include "radar_params.vh"
+//   Then reference `RP_FFT_SIZE, `RP_NUM_RANGE_BINS, etc.
+//
+// PHYSICAL CONSTANTS (derived from hardware):
+//   ADC clock:           400 MSPS
+//   CIC decimation:      4x
+//   Processing rate:     100 MSPS (post-DDC)
+//   Range per sample:    c / (2 * 100e6) = 1.5 m
+//   FFT size:            2048
+//   Decimation factor:   4  (2048 FFT bins -> 512 output range bins)
+//   Range per dec. bin:  1.5 m * 4 = 6.0 m
+//   Max range (3 km):    512 * 6.0 = 3072 m
+//   Carrier frequency:   10.5 GHz
+//   IF frequency:        120 MHz
+//
+// CHIRP BANDWIDTH (Phase 1 target — currently 20 MHz, planned 30 MHz):
+//   Range resolution:    c / (2 * BW)
+//     20 MHz -> 7.5 m
+//     30 MHz -> 5.0 m
+//   NOTE: Range resolution is independent of range-per-bin. Resolution
+//   determines the minimum separation between two targets; range-per-bin
+//   determines the spatial sampling grid.
+// ============================================================================
+
+`ifndef RADAR_PARAMS_VH
+`define RADAR_PARAMS_VH
+
+// ============================================================================
+// BOARD VARIANT — set at synthesis time, NOT runtime
+// ============================================================================
+// Default to 50T (conservative). Override in top-level or synthesis script:
+//   +define+SUPPORT_LONG_RANGE
+// or via Vivado: set_property verilog_define {SUPPORT_LONG_RANGE} [current_fileset]
+
+// Note: SUPPORT_LONG_RANGE is a flag define (ifdef/ifndef), not a value.
+// `ifndef SUPPORT_LONG_RANGE means 50T (no long range).
+// `ifdef SUPPORT_LONG_RANGE means 200T (long range supported).
+
+// ============================================================================
+// FFT AND PROCESSING CONSTANTS (fixed, both modes)
+// ============================================================================
+
+`define RP_FFT_SIZE             2048    // Range FFT points per segment
+`define RP_LOG2_FFT_SIZE        11      // log2(2048)
+`define RP_OVERLAP_SAMPLES      128     // Overlap between adjacent segments
+`define RP_SEGMENT_ADVANCE      1920    // FFT_SIZE - OVERLAP = 2048 - 128
+`define RP_DECIMATION_FACTOR    4       // Range bin decimation (2048 -> 512)
+`define RP_NUM_RANGE_BINS       512     // FFT_SIZE / DECIMATION_FACTOR
+`define RP_RANGE_BIN_BITS       9       // ceil(log2(512))
+`define RP_DOPPLER_FFT_SIZE     16      // Per sub-frame Doppler FFT
+`define RP_CHIRPS_PER_FRAME     32      // Total chirps (16 long + 16 short)
+`define RP_CHIRPS_PER_SUBFRAME  16      // Chirps per Doppler sub-frame
+`define RP_NUM_DOPPLER_BINS     32      // 2 sub-frames * 16 = 32
+`define RP_DATA_WIDTH           16      // ADC/processing data width
+
+// ============================================================================
+// 3 KM MODE PARAMETERS (both 50T and 200T)
+// ============================================================================
+
+`define RP_LONG_CHIRP_SAMPLES_3KM   3000    // 30 us at 100 MSPS
+`define RP_LONG_SEGMENTS_3KM        2       // ceil((3000-2048)/1920) + 1 = 2
+`define RP_SHORT_CHIRP_SAMPLES      50      // 0.5 us at 100 MSPS (same both modes)
+`define RP_SHORT_SEGMENTS           1       // Single segment for short chirp
+
+// Derived 3 km limits
+`define RP_MAX_RANGE_3KM            3072    // 512 bins * 6 m = 3072 m
+
+// ============================================================================
+// 20 KM MODE PARAMETERS (200T only — Phase 2)
+// ============================================================================
+
+`define RP_LONG_CHIRP_SAMPLES_20KM  13700   // 137 us at 100 MSPS (= listen window)
+`define RP_LONG_SEGMENTS_20KM       8       // 1 + ceil((13700-2048)/1920) = 1 + 7 = 8
+`define RP_OUTPUT_RANGE_BINS_20KM   4096    // 8 segments * 512 dec. bins each
+
+// Derived 20 km limits
+`define RP_MAX_RANGE_20KM           24576   // 4096 bins * 6 m = 24576 m
+
+// ============================================================================
+// MAX VALUES (for sizing buffers — compile-time, based on board variant)
+// ============================================================================
+
+`ifdef SUPPORT_LONG_RANGE
+  `define RP_MAX_SEGMENTS           8
+  `define RP_MAX_OUTPUT_BINS        4096
+  `define RP_MAX_CHIRP_SAMPLES      13700
+`else
+  `define RP_MAX_SEGMENTS           2
+  `define RP_MAX_OUTPUT_BINS        512
+  `define RP_MAX_CHIRP_SAMPLES      3000
+`endif
+
+// ============================================================================
+// BIT WIDTHS (derived from MAX values)
+// ============================================================================
+
+// Segment index: ceil(log2(MAX_SEGMENTS))
+//   50T:  log2(2) = 1 bit  (use 2 for safety)
+//   200T: log2(8) = 3 bits
+`ifdef SUPPORT_LONG_RANGE
+  `define RP_SEGMENT_IDX_WIDTH      3
+  `define RP_RANGE_BIN_WIDTH_MAX    12      // ceil(log2(4096))
+  `define RP_DOPPLER_MEM_ADDR_W     17      // ceil(log2(4096*32)) = 17
+  `define RP_CFAR_MAG_ADDR_W        17      // ceil(log2(4096*32)) = 17
+`else
+  `define RP_SEGMENT_IDX_WIDTH      2
+  `define RP_RANGE_BIN_WIDTH_MAX    9       // ceil(log2(512))
+  `define RP_DOPPLER_MEM_ADDR_W     14      // ceil(log2(512*32)) = 14
+  `define RP_CFAR_MAG_ADDR_W        14      // ceil(log2(512*32)) = 14
+`endif
+
+// Derived depths (for memory declarations)
+// Usage: reg [15:0] mem [0:`RP_DOPPLER_MEM_DEPTH-1];
+`define RP_DOPPLER_MEM_DEPTH    (`RP_MAX_OUTPUT_BINS * `RP_CHIRPS_PER_FRAME)
+`define RP_CFAR_MAG_DEPTH       (`RP_MAX_OUTPUT_BINS * `RP_NUM_DOPPLER_BINS)
+
+// ============================================================================
+// CHIRP TIMING DEFAULTS (100 MHz clock cycles)
+// ============================================================================
+// Reset defaults for host-configurable timing registers.
+// Match radar_mode_controller.v parameters and main.cpp STM32 defaults.
+
+`define RP_DEF_LONG_CHIRP_CYCLES    3000    // 30 us
+`define RP_DEF_LONG_LISTEN_CYCLES   13700   // 137 us
+`define RP_DEF_GUARD_CYCLES         17540   // 175.4 us
+`define RP_DEF_SHORT_CHIRP_CYCLES   50      // 0.5 us
+`define RP_DEF_SHORT_LISTEN_CYCLES  17450   // 174.5 us
+`define RP_DEF_CHIRPS_PER_ELEV      32
+
+// ============================================================================
+// BLIND ZONE CONSTANTS (informational, for comments and GUI)
+// ============================================================================
+// Long chirp blind zone:  c * 30 us / 2 = 4500 m
+// Short chirp blind zone: c * 0.5 us / 2 = 75 m
+
+`define RP_LONG_BLIND_ZONE_M        4500
+`define RP_SHORT_BLIND_ZONE_M       75
+
+// ============================================================================
+// PHYSICAL CONSTANTS (integer-scaled for Verilog — use in comments/assertions)
+// ============================================================================
+// Range per ADC sample:     1.5 m  (stored as 15 in units of 0.1 m)
+// Range per decimated bin:  6.0 m  (stored as 60 in units of 0.1 m)
+// Processing rate:         100 MSPS
+
+`define RP_RANGE_PER_SAMPLE_DM      15      // 1.5 m in decimeters
+`define RP_RANGE_PER_BIN_DM         60      // 6.0 m in decimeters
+`define RP_PROCESSING_RATE_MHZ      100
+
+// ============================================================================
+// AGC DEFAULTS
+// ============================================================================
+`define RP_DEF_AGC_TARGET           200
+`define RP_DEF_AGC_ATTACK           1
+`define RP_DEF_AGC_DECAY            1
+`define RP_DEF_AGC_HOLDOFF          4
+
+// ============================================================================
+// CFAR DEFAULTS
+// ============================================================================
+`define RP_DEF_CFAR_GUARD           2
+`define RP_DEF_CFAR_TRAIN           8
+`define RP_DEF_CFAR_ALPHA           8'h30   // 3.0 in Q4.4
+`define RP_DEF_CFAR_MODE            2'b00   // CA-CFAR
+
+// ============================================================================
+// DETECTION DEFAULTS
+// ============================================================================
+`define RP_DEF_DETECT_THRESHOLD     10000
+
+// ============================================================================
+// RADAR MODE ENCODING (host_radar_mode, opcode 0x01)
+// ============================================================================
+`define RP_MODE_STM32_PASSTHROUGH   2'b00
+`define RP_MODE_AUTO_3KM            2'b01
+`define RP_MODE_SINGLE_DEBUG        2'b10
+`define RP_MODE_RESERVED            2'b11
+
+// ============================================================================
+// RANGE MODE ENCODING (host_range_mode, opcode 0x20)
+// ============================================================================
+`define RP_RANGE_MODE_3KM           2'b00
+`define RP_RANGE_MODE_LONG          2'b01
+`define RP_RANGE_MODE_RSVD2         2'b10
+`define RP_RANGE_MODE_RSVD3         2'b11
+
+// ============================================================================
+// STREAM CONTROL (host_stream_control, opcode 0x04, 6-bit)
+// ============================================================================
+// Bits [2:0]: Stream enable mask
+//   Bit 0 = range profile stream
+//   Bit 1 = doppler map stream
+//   Bit 2 = cfar/detection stream
+// Bits [5:3]: Stream format control
+//   Bit 3 = mag_only    (0=I/Q pairs, 1=Manhattan magnitude only)
+//   Bit 4 = sparse_det  (0=dense detection flags, 1=sparse detection list)
+//   Bit 5 = reserved (was frame_decimate, not needed with mag-only fitting)
+`define RP_STREAM_CTRL_DEFAULT      6'b001_111  // all streams, mag-only mode
+
+`endif // RADAR_PARAMS_VH

9_Firmware/9_2_FPGA/radar_receiver_final.v

@@ -1,5 +1,7 @@
 `timescale 1ns / 1ps
 
+`include "radar_params.vh"
+
 module radar_receiver_final (
     input wire clk,           // 100MHz    
 	 input wire reset_n,
@@ -17,17 +19,22 @@ module radar_receiver_final (
     output wire [31:0] doppler_output,
     output wire doppler_valid,
     output wire [4:0] doppler_bin,
-    output wire [5:0] range_bin,
+    output wire [`RP_RANGE_BIN_BITS-1:0] range_bin,  // 9-bit
     
-    // Matched filter range profile output (for USB)
+    // Raw matched-filter output (debug/bring-up)
     output wire signed [15:0] range_profile_i_out,
     output wire signed [15:0] range_profile_q_out,
     output wire range_profile_valid_out,
 
+    // Decimated 512-bin range profile (for USB bulk frames / downstream consumers)
+    output wire [15:0] decimated_range_mag_out,
+    output wire decimated_range_valid_out,
+    
     // Host command inputs (Gap 4: USB Read Path, CDC-synchronized)
     // CDC-synchronized in radar_system_top.v before reaching here
     input wire [1:0] host_mode,      // Radar mode: 00=STM32, 01=auto-scan, 10=single-chirp
     input wire host_trigger,          // Single-chirp trigger pulse (1 clk cycle)
+    input wire [1:0] host_range_mode, // Range mode: 00=3km (short only), 01=long-range (dual chirp)
 
     // Gap 2: Host-configurable chirp timing (CDC-synchronized in radar_system_top.v)
     input wire [15:0] host_long_chirp_cycles,
@@ -42,6 +49,13 @@ module radar_receiver_final (
     // [2:0]=shift amount: 0..7 bits. Default 0 = pass-through.
     input wire [3:0] host_gain_shift,
 
+    // AGC configuration (opcodes 0x28-0x2C, active only when agc_enable=1)
+    input wire        host_agc_enable,      // 0x28: 0=manual, 1=auto AGC
+    input wire [7:0]  host_agc_target,      // 0x29: target peak magnitude
+    input wire [3:0]  host_agc_attack,      // 0x2A: gain-down step on clipping
+    input wire [3:0]  host_agc_decay,       // 0x2B: gain-up step when weak
+    input wire [3:0]  host_agc_holdoff,     // 0x2C: frames before gain-up
+
     // STM32 toggle signals for mode 00 (STM32-driven) pass-through.
     // These are CDC-synchronized in radar_system_top.v / radar_transmitter.v
     // before reaching this module. In mode 00, the RX mode controller uses
@@ -60,7 +74,12 @@ module radar_receiver_final (
     // ADC raw data tap (clk_100m domain, post-DDC, for self-test / debug)
     output wire [15:0] dbg_adc_i,            // DDC output I (16-bit signed, 100 MHz)
     output wire [15:0] dbg_adc_q,            // DDC output Q (16-bit signed, 100 MHz)
-    output wire        dbg_adc_valid         // DDC output valid (100 MHz)
+    output wire        dbg_adc_valid,        // DDC output valid (100 MHz)
+
+    // AGC status outputs (for status readback / STM32 outer loop)
+    output wire [7:0]  agc_saturation_count, // Per-frame clipped sample count
+    output wire [7:0]  agc_peak_magnitude,   // Per-frame peak (upper 8 bits)
+    output wire [3:0]  agc_current_gain      // Effective gain_shift encoding
 );
 
 // ========== INTERNAL SIGNALS ==========
@@ -86,11 +105,13 @@ wire adc_valid_sync;
 // Gain-controlled signals (between DDC output and matched filter)
 wire signed [15:0] gc_i, gc_q;
 wire gc_valid;
-wire [7:0] gc_saturation_count;  // Diagnostic: clipped sample counter
+wire [7:0] gc_saturation_count;  // Diagnostic: per-frame clipped sample counter
+wire [7:0] gc_peak_magnitude;    // Diagnostic: per-frame peak magnitude
+wire [3:0] gc_current_gain;      // Diagnostic: effective gain_shift
 
-// Reference signals for the processing chain
+// Reference signal for the processing chain (carries long OR short ref
-wire [15:0] long_chirp_real, long_chirp_imag;
+// depending on use_long_chirp — selected by chirp_memory_loader_param)
-wire [15:0] short_chirp_real, short_chirp_imag;
+wire [15:0] ref_chirp_real, ref_chirp_imag;
 
 // ========== DOPPLER PROCESSING SIGNALS ==========
 wire [31:0] range_data_32bit;
@@ -102,20 +123,36 @@ wire [31:0] doppler_spectrum;
 wire doppler_spectrum_valid;
 wire [4:0] doppler_bin_out;
 wire doppler_processing;
-wire doppler_frame_done;
+
+// frame_complete from doppler_processor is a LEVEL signal (high whenever
+// state == S_IDLE && !frame_buffer_full). Downstream consumers (USB FT2232H,
+// AGC, CFAR) expect a single-cycle PULSE. Convert here at the source so all
+// consumers are safe.
+wire doppler_frame_done_level;  // raw level from doppler_processor
+reg  doppler_frame_done_prev;
+wire doppler_frame_done;        // rising-edge pulse (1 clk cycle)
+
+always @(posedge clk or negedge reset_n) begin
+    if (!reset_n)
+        doppler_frame_done_prev <= 1'b0;
+    else
+        doppler_frame_done_prev <= doppler_frame_done_level;
+end
+
+assign doppler_frame_done = doppler_frame_done_level & ~doppler_frame_done_prev;
 assign doppler_frame_done_out = doppler_frame_done;
 
 // ========== RANGE BIN DECIMATOR SIGNALS ==========
 wire signed [15:0] decimated_range_i;
 wire signed [15:0] decimated_range_q;
 wire decimated_range_valid;
-wire [5:0] decimated_range_bin;
+wire [`RP_RANGE_BIN_BITS-1:0] decimated_range_bin;  // 9-bit
 
 // ========== MTI CANCELLER SIGNALS ==========
 wire signed [15:0] mti_range_i;
 wire signed [15:0] mti_range_q;
 wire mti_range_valid;
-wire [5:0] mti_range_bin;
+wire [`RP_RANGE_BIN_BITS-1:0] mti_range_bin;  // 9-bit
 wire mti_first_chirp;
 
 // ========== RADAR MODE CONTROLLER SIGNALS ==========
@@ -133,6 +170,7 @@ radar_mode_controller rmc (
     .clk(clk),
     .reset_n(reset_n),
     .mode(host_mode),                     // Controlled by host via USB (default: 2'b01 auto-scan)
+    .range_mode(host_range_mode),          // Range mode: 00=3km, 01=long-range (drives chirp type)
     .stm32_new_chirp(stm32_new_chirp_rx),
     .stm32_new_elevation(stm32_new_elevation_rx),
     .stm32_new_azimuth(stm32_new_azimuth_rx),
@@ -160,7 +198,7 @@ wire clk_400m;
 // the buffered 400MHz DCO clock via adc_dco_bufg, avoiding duplicate
 // IBUFDS instantiations on the same LVDS clock pair.
 
-// 1. ADC + CDC + AGC
+// 1. ADC + CDC + Digital Gain
 
 // CMOS Output Interface (400MHz Domain)
 wire [7:0] adc_data_cmos;  // 8-bit ADC data (CMOS, from ad9484_interface_400m)
@@ -222,9 +260,10 @@ ddc_input_interface ddc_if (
     .data_sync_error()
 );
 
-// 2b. Digital Gain Control (Fix 3)
+// 2b. Digital Gain Control with AGC
 // Host-configurable power-of-2 shift between DDC output and matched filter.
-// Default gain_shift=0 → pass-through (no behavioral change from baseline).
+// Default gain_shift=0, agc_enable=0 → pass-through (no behavioral change).
+// When agc_enable=1: auto-adjusts gain per frame based on peak/saturation.
 rx_gain_control gain_ctrl (
     .clk(clk),
     .reset_n(reset_n),
@@ -232,14 +271,25 @@ rx_gain_control gain_ctrl (
     .data_q_in(adc_q_scaled),
     .valid_in(adc_valid_sync),
     .gain_shift(host_gain_shift),
+    // AGC configuration
+    .agc_enable(host_agc_enable),
+    .agc_target(host_agc_target),
+    .agc_attack(host_agc_attack),
+    .agc_decay(host_agc_decay),
+    .agc_holdoff(host_agc_holdoff),
+    // Frame boundary from Doppler processor
+    .frame_boundary(doppler_frame_done),
+    // Outputs
     .data_i_out(gc_i),
     .data_q_out(gc_q),
     .valid_out(gc_valid),
-    .saturation_count(gc_saturation_count)
+    .saturation_count(gc_saturation_count),
+    .peak_magnitude(gc_peak_magnitude),
+    .current_gain(gc_current_gain)
 );
 
 // 3. Dual Chirp Memory Loader
-wire [9:0] sample_addr_from_chain;
+wire [10:0] sample_addr_from_chain;
 
 chirp_memory_loader_param chirp_mem (
     .clk(clk),
@@ -253,20 +303,9 @@ chirp_memory_loader_param chirp_mem (
     .mem_ready(mem_ready)
 );
 
-// Sample address generator
-reg [9:0] sample_addr_reg;
-always @(posedge clk or negedge reset_n) begin
-    if (!reset_n) begin
-        sample_addr_reg <= 0;
-    end else if (mem_request) begin
-        sample_addr_reg <= sample_addr_reg + 1;
-        if (sample_addr_reg == 1023) sample_addr_reg <= 0;
-    end
-end
-// sample_addr_wire removed — was unused implicit wire (synthesis warning)
-
 // 4. CRITICAL: Reference Chirp Latency Buffer
-// This aligns reference data with FFT output (2159 cycle delay)
+// This aligns reference data with FFT output (3187 cycle delay)
+// TODO: verify empirically during hardware bring-up with correlation test
 wire [15:0] delayed_ref_i, delayed_ref_q;
 wire mem_ready_delayed;
 
@@ -282,11 +321,10 @@ latency_buffer #(
     .valid_out(mem_ready_delayed)
 );
 
-// Assign delayed reference signals
+// Assign delayed reference signals (single pair — chirp_memory_loader_param
-assign long_chirp_real = delayed_ref_i;
+// selects long/short reference upstream via use_long_chirp)
-assign long_chirp_imag = delayed_ref_q;
+assign ref_chirp_real = delayed_ref_i;
-assign short_chirp_real = delayed_ref_i;
+assign ref_chirp_imag = delayed_ref_q;
-assign short_chirp_imag = delayed_ref_q;
 
 // 5. Dual Chirp Matched Filter
 
@@ -298,6 +336,12 @@ wire range_valid;
 assign range_profile_i_out = range_profile_i;
 assign range_profile_q_out = range_profile_q;
 assign range_profile_valid_out = range_valid;
+// Manhattan magnitude: |I| + |Q|, saturated to 16 bits
+wire [15:0] abs_mti_i = mti_range_i[15] ? (~mti_range_i + 16'd1) : mti_range_i;
+wire [15:0] abs_mti_q = mti_range_q[15] ? (~mti_range_q + 16'd1) : mti_range_q;
+wire [16:0] manhattan_sum = {1'b0, abs_mti_i} + {1'b0, abs_mti_q};
+assign decimated_range_mag_out = manhattan_sum[16] ? 16'hFFFF : manhattan_sum[15:0];
+assign decimated_range_valid_out = mti_range_valid;
 
 matched_filter_multi_segment mf_dual (
     .clk(clk),
@@ -310,10 +354,8 @@ matched_filter_multi_segment mf_dual (
     .mc_new_chirp(mc_new_chirp),
     .mc_new_elevation(mc_new_elevation),
     .mc_new_azimuth(mc_new_azimuth),
-	 .long_chirp_real(delayed_ref_i),      // From latency buffer
+	 .ref_chirp_real(delayed_ref_i),       // From latency buffer (long or short ref)
-    .long_chirp_imag(delayed_ref_q),
+    .ref_chirp_imag(delayed_ref_q),
-    .short_chirp_real(delayed_ref_i),     // Same for short chirp
-    .short_chirp_imag(delayed_ref_q),
     .segment_request(segment_request),
     .mem_request(mem_request),
 	 .sample_addr_out(sample_addr_from_chain),
@@ -324,11 +366,11 @@ matched_filter_multi_segment mf_dual (
 );
 
 // ========== CRITICAL: RANGE BIN DECIMATOR ==========
-// Convert 1024 range bins to 64 bins for Doppler
+// Convert 2048 range bins to 512 bins for Doppler
 range_bin_decimator #(
-    .INPUT_BINS(1024),
+    .INPUT_BINS(`RP_FFT_SIZE),              // 2048
-    .OUTPUT_BINS(64),
+    .OUTPUT_BINS(`RP_NUM_RANGE_BINS),       // 512
-    .DECIMATION_FACTOR(16)
+    .DECIMATION_FACTOR(`RP_DECIMATION_FACTOR)  // 4
 ) range_decim (
     .clk(clk),
     .reset_n(reset_n),
@@ -340,7 +382,7 @@ range_bin_decimator #(
     .range_valid_out(decimated_range_valid),
     .range_bin_index(decimated_range_bin),
     .decimation_mode(2'b01),           // Peak detection mode
-    .start_bin(10'd0),
+    .start_bin(11'd0),
     .watchdog_timeout()                // Diagnostic — unconnected (monitored via ILA if needed)
 );
 
@@ -349,8 +391,8 @@ range_bin_decimator #(
 // H(z) = 1 - z^{-1} → null at DC Doppler, removes stationary clutter.
 // When host_mti_enable=0: transparent pass-through.
 mti_canceller #(
-    .NUM_RANGE_BINS(64),
+    .NUM_RANGE_BINS(`RP_NUM_RANGE_BINS),    // 512
-    .DATA_WIDTH(16)
+    .DATA_WIDTH(`RP_DATA_WIDTH)             // 16
 ) mti_inst (
     .clk(clk),
     .reset_n(reset_n),
@@ -404,10 +446,10 @@ assign range_data_valid = mti_range_valid;
 
 // ========== DOPPLER PROCESSOR ==========
 doppler_processor_optimized #(
-    .DOPPLER_FFT_SIZE(16),
+    .DOPPLER_FFT_SIZE(`RP_DOPPLER_FFT_SIZE),        // 16
-    .RANGE_BINS(64),
+    .RANGE_BINS(`RP_NUM_RANGE_BINS),                // 512
-    .CHIRPS_PER_FRAME(32),
+    .CHIRPS_PER_FRAME(`RP_CHIRPS_PER_FRAME),        // 32
-    .CHIRPS_PER_SUBFRAME(16)
+    .CHIRPS_PER_SUBFRAME(`RP_CHIRPS_PER_SUBFRAME)   // 16
 ) doppler_proc (
     .clk(clk),
     .reset_n(reset_n),
@@ -423,7 +465,7 @@ doppler_processor_optimized #(
     
     // Status
     .processing_active(doppler_processing),
-    .frame_complete(doppler_frame_done),
+    .frame_complete(doppler_frame_done_level),
     .status()
 );
 
@@ -474,4 +516,9 @@ assign dbg_adc_i     = adc_i_scaled;
 assign dbg_adc_q     = adc_q_scaled;
 assign dbg_adc_valid = adc_valid_sync;
 
+// ========== AGC STATUS OUTPUTS ==========
+assign agc_saturation_count = gc_saturation_count;
+assign agc_peak_magnitude   = gc_peak_magnitude;
+assign agc_current_gain     = gc_current_gain;
+
 endmodule

9_Firmware/9_2_FPGA/radar_system_top.v

@@ -1,5 +1,7 @@
 `timescale 1ns / 1ps
 
+`include "radar_params.vh"
+
 /**
  * radar_system_top.v
  * 
@@ -122,10 +124,16 @@ module radar_system_top (
     output wire [31:0] dbg_doppler_data,
     output wire dbg_doppler_valid,
     output wire [4:0] dbg_doppler_bin,
-    output wire [5:0] dbg_range_bin,
+    output wire [`RP_RANGE_BIN_BITS-1:0] dbg_range_bin,
     
     // System status
-    output wire [3:0] system_status
+    output wire [3:0] system_status,
+
+    // FPGA→STM32 GPIO outputs (DIG_5..DIG_7 on 50T board)
+    // Used by STM32 outer AGC loop to read saturation state without USB polling.
+    output wire gpio_dig5,          // DIG_5 (H11→PD13): AGC saturation flag (1=clipping detected)
+    output wire gpio_dig6,          // DIG_6 (G12→PD14): reserved (tied low)
+    output wire gpio_dig7           // DIG_7 (H12→PD15): reserved (tied low)
 );
 
 // ============================================================================
@@ -170,9 +178,11 @@ wire tx_current_chirp_sync_valid;
 wire [31:0] rx_doppler_output;
 wire rx_doppler_valid;
 wire [4:0] rx_doppler_bin;
-wire [5:0] rx_range_bin;
+wire [`RP_RANGE_BIN_BITS-1:0] rx_range_bin;
 wire [31:0] rx_range_profile;
 wire rx_range_valid;
+wire [15:0] rx_range_profile_decimated;
+wire rx_range_profile_decimated_valid;
 wire [15:0] rx_doppler_real;
 wire [15:0] rx_doppler_imag;
 wire rx_doppler_data_valid;
@@ -187,6 +197,11 @@ wire [15:0] rx_dbg_adc_i;
 wire [15:0] rx_dbg_adc_q;
 wire        rx_dbg_adc_valid;
 
+// AGC status from receiver (for status readback and GPIO)
+wire [7:0]  rx_agc_saturation_count;
+wire [7:0]  rx_agc_peak_magnitude;
+wire [3:0]  rx_agc_current_gain;
+
 // Data packing for USB
 wire [31:0] usb_range_profile;
 wire usb_range_valid;
@@ -212,7 +227,7 @@ wire [15:0] usb_cmd_value;
 reg [1:0]  host_radar_mode;
 reg        host_trigger_pulse;
 reg [15:0] host_detect_threshold;  // (was host_cfar_threshold)
-reg [2:0]  host_stream_control;
+reg [5:0]  host_stream_control;
 
 // Fix 3: Digital gain control register
 // [3]=direction: 0=amplify, 1=attenuate. [2:0]=shift amount 0..7.
@@ -239,13 +254,12 @@ reg        host_status_request;       // Opcode 0xFF (self-clearing pulse)
 localparam DOPPLER_FRAME_CHIRPS = 32; // Total chirps per Doppler frame
 reg        chirps_mismatch_error;     // Set if host tried to set chirps != FFT size
 
-// Fix 7: Range-mode register (opcode 0x20)
+// Range-mode register (opcode 0x20)
-// Future-proofing for 3km/10km antenna switching.
+// Controls chirp type selection in the mode controller:
-//   2'b00 = Auto (default — system selects based on scene)
+//   2'b00 = 3 km mode (all short chirps — long blind zone > max range)
-//   2'b01 = Short-range (3km)
+//   2'b01 = Long-range (dual chirp: first half long, second half short)
-//   2'b10 = Long-range (10km)
+//   2'b10 = Reserved
 //   2'b11 = Reserved
-// Currently a configuration store only — antenna/timing switching TBD.
 reg [1:0]  host_range_mode;
 
 // CFAR configuration registers (host-configurable via USB)
@@ -259,6 +273,13 @@ reg        host_cfar_enable;      // Opcode 0x25: 1=CFAR, 0=simple threshold
 reg        host_mti_enable;       // Opcode 0x26: 1=MTI active, 0=pass-through
 reg [2:0]  host_dc_notch_width;   // Opcode 0x27: DC notch ±width bins (0=off, 1..7)
 
+// AGC configuration registers (host-configurable via USB, opcodes 0x28-0x2C)
+reg        host_agc_enable;       // Opcode 0x28: 0=manual gain, 1=auto AGC
+reg [7:0]  host_agc_target;       // Opcode 0x29: target peak magnitude (default 200)
+reg [3:0]  host_agc_attack;       // Opcode 0x2A: gain-down step on clipping (default 1)
+reg [3:0]  host_agc_decay;        // Opcode 0x2B: gain-up step when weak (default 1)
+reg [3:0]  host_agc_holdoff;      // Opcode 0x2C: frames to wait before gain-up (default 4)
+
 // Board bring-up self-test registers (opcode 0x30 trigger, 0x31 readback)
 reg        host_self_test_trigger;  // Opcode 0x30: self-clearing pulse
 wire       self_test_busy;
@@ -501,14 +522,16 @@ radar_receiver_final rx_inst (
     .doppler_bin(rx_doppler_bin),
     .range_bin(rx_range_bin),
     
-    // Matched filter range profile (for USB)
+    // Range-profile outputs
     .range_profile_i_out(rx_range_profile[15:0]),
     .range_profile_q_out(rx_range_profile[31:16]),
     .range_profile_valid_out(rx_range_valid),
+    .decimated_range_mag_out(rx_range_profile_decimated),
+    .decimated_range_valid_out(rx_range_profile_decimated_valid),
     
-    // Host command inputs (Gap 4: USB Read Path)
     .host_mode(host_radar_mode),
     .host_trigger(host_trigger_pulse),
+    .host_range_mode(host_range_mode),
     // Gap 2: Host-configurable chirp timing
     .host_long_chirp_cycles(host_long_chirp_cycles),
     .host_long_listen_cycles(host_long_listen_cycles),
@@ -518,6 +541,12 @@ radar_receiver_final rx_inst (
     .host_chirps_per_elev(host_chirps_per_elev),
     // Fix 3: digital gain control
     .host_gain_shift(host_gain_shift),
+    // AGC configuration (opcodes 0x28-0x2C)
+    .host_agc_enable(host_agc_enable),
+    .host_agc_target(host_agc_target),
+    .host_agc_attack(host_agc_attack),
+    .host_agc_decay(host_agc_decay),
+    .host_agc_holdoff(host_agc_holdoff),
     // STM32 toggle signals for RX mode controller (mode 00 pass-through).
     // These are the raw GPIO inputs — the RX mode controller's edge detectors
     // (inside radar_mode_controller) handle debouncing/edge detection.
@@ -532,7 +561,11 @@ radar_receiver_final rx_inst (
     // ADC debug tap (for self-test / bring-up)
     .dbg_adc_i(rx_dbg_adc_i),
     .dbg_adc_q(rx_dbg_adc_q),
-    .dbg_adc_valid(rx_dbg_adc_valid)
+    .dbg_adc_valid(rx_dbg_adc_valid),
+    // AGC status outputs
+    .agc_saturation_count(rx_agc_saturation_count),
+    .agc_peak_magnitude(rx_agc_peak_magnitude),
+    .agc_current_gain(rx_agc_current_gain)
 );
 
 // ============================================================================
@@ -568,7 +601,7 @@ assign dc_notch_active = (host_dc_notch_width != 3'd0) &&
 wire [31:0] notched_doppler_data  = dc_notch_active ? 32'd0 : rx_doppler_output;
 wire        notched_doppler_valid = rx_doppler_valid;
 wire [4:0]  notched_doppler_bin   = rx_doppler_bin;
-wire [5:0]  notched_range_bin     = rx_range_bin;
+wire [`RP_RANGE_BIN_BITS-1:0]  notched_range_bin     = rx_range_bin;
 
 // ============================================================================
 // CFAR DETECTOR (replaces simple threshold detector)
@@ -579,7 +612,7 @@ wire [5:0]  notched_range_bin     = rx_range_bin;
 
 wire cfar_detect_flag;
 wire cfar_detect_valid;
-wire [5:0]  cfar_detect_range;
+wire [`RP_RANGE_BIN_BITS-1:0]  cfar_detect_range;
 wire [4:0]  cfar_detect_doppler;
 wire [16:0] cfar_detect_magnitude;
 wire [16:0] cfar_detect_threshold;
@@ -670,9 +703,10 @@ end
 // DATA PACKING FOR USB
 // ============================================================================
 
-// Range profile from matched filter output (wired through radar_receiver_final)
+// USB range profile must match the advertised 512-bin frame payload, so source it
-assign usb_range_profile = rx_range_profile;
+// from the decimated range stream that feeds Doppler rather than raw MF samples.
-assign usb_range_valid = rx_range_valid;
+assign usb_range_profile = {16'd0, rx_range_profile_decimated};
+assign usb_range_valid = rx_range_profile_decimated_valid;
 
 assign usb_doppler_real = rx_doppler_real;
 assign usb_doppler_imag = rx_doppler_imag;
@@ -744,7 +778,13 @@ if (USB_MODE == 0) begin : gen_ft601
         // Self-test status readback
         .status_self_test_flags(self_test_flags_latched),
         .status_self_test_detail(self_test_detail_latched),
-        .status_self_test_busy(self_test_busy)
+        .status_self_test_busy(self_test_busy),
+
+        // AGC status readback
+        .status_agc_current_gain(rx_agc_current_gain),
+        .status_agc_peak_magnitude(rx_agc_peak_magnitude),
+        .status_agc_saturation_count(rx_agc_saturation_count),
+        .status_agc_enable(host_agc_enable)
     );
 
     // FT2232H ports unused in FT601 mode — tie off
@@ -769,6 +809,11 @@ end else begin : gen_ft2232h
         .cfar_detection(usb_detect_flag),
         .cfar_valid(usb_detect_valid),
 
+        // Bulk frame protocol inputs
+        .range_bin_in(notched_range_bin),
+        .doppler_bin_in(notched_doppler_bin),
+        .frame_complete(rx_frame_complete),
+
         // FT2232H Interface
         .ft_data(ft_data),
         .ft_rxf_n(ft_rxf_n),
@@ -805,7 +850,13 @@ end else begin : gen_ft2232h
         // Self-test status readback
         .status_self_test_flags(self_test_flags_latched),
         .status_self_test_detail(self_test_detail_latched),
-        .status_self_test_busy(self_test_busy)
+        .status_self_test_busy(self_test_busy),
+
+        // AGC status readback
+        .status_agc_current_gain(rx_agc_current_gain),
+        .status_agc_peak_magnitude(rx_agc_peak_magnitude),
+        .status_agc_saturation_count(rx_agc_saturation_count),
+        .status_agc_enable(host_agc_enable)
     );
 
     // FT601 ports unused in FT2232H mode — tie off
@@ -871,7 +922,7 @@ always @(posedge clk_100m_buf or negedge sys_reset_n) begin
         host_radar_mode    <= 2'b01;   // Default: auto-scan
         host_trigger_pulse <= 1'b0;
         host_detect_threshold <= 16'd10000; // Default threshold
-        host_stream_control <= 3'b111;    // Default: all streams enabled
+        host_stream_control <= `RP_STREAM_CTRL_DEFAULT; // Default: all streams, mag-only mode
         host_gain_shift     <= 4'd0;      // Default: pass-through (no gain change)
         // Gap 2: chirp timing defaults (match radar_mode_controller parameters)
         host_long_chirp_cycles  <= 16'd3000;
@@ -882,7 +933,7 @@ always @(posedge clk_100m_buf or negedge sys_reset_n) begin
         host_chirps_per_elev    <= 6'd32;
         host_status_request     <= 1'b0;
         chirps_mismatch_error   <= 1'b0;
-        host_range_mode         <= 2'b00;     // Default: auto
+        host_range_mode         <= 2'b00;     // Default: 3 km mode (all short chirps)
         // CFAR defaults (disabled by default — backward-compatible)
         host_cfar_guard         <= 4'd2;      // 2 guard cells each side
         host_cfar_train         <= 5'd8;      // 8 training cells each side
@@ -892,6 +943,12 @@ always @(posedge clk_100m_buf or negedge sys_reset_n) begin
         // Ground clutter removal defaults (disabled — backward-compatible)
         host_mti_enable         <= 1'b0;      // MTI off
         host_dc_notch_width     <= 3'd0;      // DC notch off
+        // AGC defaults (disabled — backward-compatible with manual gain)
+        host_agc_enable         <= 1'b0;      // AGC off (manual gain)
+        host_agc_target         <= 8'd200;    // Target peak magnitude
+        host_agc_attack         <= 4'd1;      // 1-step gain-down on clipping
+        host_agc_decay          <= 4'd1;      // 1-step gain-up when weak
+        host_agc_holdoff        <= 4'd4;      // 4 frames before gain-up
         // Self-test defaults
         host_self_test_trigger  <= 1'b0;      // Self-test idle
     end else begin
@@ -903,7 +960,7 @@ always @(posedge clk_100m_buf or negedge sys_reset_n) begin
                 8'h01: host_radar_mode     <= usb_cmd_value[1:0];
                 8'h02: host_trigger_pulse  <= 1'b1;
                 8'h03: host_detect_threshold <= usb_cmd_value;
-                8'h04: host_stream_control <= usb_cmd_value[2:0];
+                8'h04: host_stream_control <= usb_cmd_value[5:0];
                 // Gap 2: chirp timing configuration
                 8'h10: host_long_chirp_cycles  <= usb_cmd_value;
                 8'h11: host_long_listen_cycles <= usb_cmd_value;
@@ -926,7 +983,7 @@ always @(posedge clk_100m_buf or negedge sys_reset_n) begin
                     end
                 end
                 8'h16: host_gain_shift         <= usb_cmd_value[3:0];  // Fix 3: digital gain
-                8'h20: host_range_mode         <= usb_cmd_value[1:0];  // Fix 7: range mode
+                8'h20: host_range_mode         <= usb_cmd_value[1:0];  // Range mode
                 // CFAR configuration opcodes
                 8'h21: host_cfar_guard         <= usb_cmd_value[3:0];
                 8'h22: host_cfar_train         <= usb_cmd_value[4:0];
@@ -936,6 +993,12 @@ always @(posedge clk_100m_buf or negedge sys_reset_n) begin
                 // Ground clutter removal opcodes
                 8'h26: host_mti_enable         <= usb_cmd_value[0];
                 8'h27: host_dc_notch_width     <= usb_cmd_value[2:0];
+                // AGC configuration opcodes
+                8'h28: host_agc_enable         <= usb_cmd_value[0];
+                8'h29: host_agc_target         <= usb_cmd_value[7:0];
+                8'h2A: host_agc_attack         <= usb_cmd_value[3:0];
+                8'h2B: host_agc_decay          <= usb_cmd_value[3:0];
+                8'h2C: host_agc_holdoff        <= usb_cmd_value[3:0];
                 // Board bring-up self-test opcodes
                 8'h30: host_self_test_trigger  <= 1'b1;  // Trigger self-test
                 8'h31: host_status_request     <= 1'b1;  // Self-test readback (status alias)
@@ -978,6 +1041,16 @@ end
 
 assign system_status = status_reg;
 
+// ============================================================================
+// FPGA→STM32 GPIO OUTPUTS (DIG_5, DIG_6, DIG_7)
+// ============================================================================
+// DIG_5: AGC saturation flag — high when per-frame saturation_count > 0.
+//        STM32 reads PD13 to detect clipping and adjust ADAR1000 VGA gain.
+// DIG_6, DIG_7: Reserved (tied low for future use).
+assign gpio_dig5 = (rx_agc_saturation_count != 8'd0);
+assign gpio_dig6 = 1'b0;
+assign gpio_dig7 = 1'b0;
+
 // ============================================================================
 // DEBUG AND VERIFICATION
 // ============================================================================

9_Firmware/9_2_FPGA/radar_system_top_50t.v

@@ -76,7 +76,12 @@ module radar_system_top_50t (
     output wire ft_rd_n,              // Read strobe (active low)
     output wire ft_wr_n,              // Write strobe (active low)
     output wire ft_oe_n,              // Output enable / bus direction
-    output wire ft_siwu               // Send Immediate / WakeUp
+    output wire ft_siwu,              // Send Immediate / WakeUp
+
+    // ===== FPGA→STM32 GPIO (Bank 15: 3.3V) =====
+    output wire gpio_dig5,            // DIG_5 (H11→PD13): AGC saturation flag
+    output wire gpio_dig6,            // DIG_6 (G12→PD14): reserved
+    output wire gpio_dig7             // DIG_7 (H12→PD15): reserved
 );
 
     // ===== Tie-off wires for unconstrained FT601 inputs (inactive with USB_MODE=1) =====
@@ -207,7 +212,12 @@ module radar_system_top_50t (
         .dbg_doppler_valid      (dbg_doppler_valid_nc),
         .dbg_doppler_bin        (dbg_doppler_bin_nc),
         .dbg_range_bin          (dbg_range_bin_nc),
-        .system_status          (system_status_nc)
+        .system_status          (system_status_nc),
+
+        // ----- FPGA→STM32 GPIO (DIG_5..DIG_7) -----
+        .gpio_dig5              (gpio_dig5),
+        .gpio_dig6              (gpio_dig6),
+        .gpio_dig7              (gpio_dig7)
     );
 
 endmodule

9_Firmware/9_2_FPGA/range_bin_decimator.v

@@ -3,7 +3,7 @@
 /**
  * range_bin_decimator.v
  *
- * Reduces 1024 range bins from the matched filter output down to 64 bins
+ * Reduces 2048 range bins from the matched filter output down to 512 bins
  * for the Doppler processor. Supports multiple decimation modes:
  *
  *   Mode 2'b00: Simple decimation (take every Nth sample)
@@ -11,29 +11,31 @@
  *   Mode 2'b10: Averaging (sum group and divide by N)
  *   Mode 2'b11: Reserved
  *
- * Interface contract (from radar_receiver_final.v line 229):
+ * Interface contract (from radar_receiver_final.v):
  *   .clk, .reset_n
- *   .range_i_in, .range_q_in, .range_valid_in   ← from matched_filter output
+ *   .range_i_in, .range_q_in, .range_valid_in   <- from matched_filter output
- *   .range_i_out, .range_q_out, .range_valid_out → to Doppler processor
+ *   .range_i_out, .range_q_out, .range_valid_out -> to Doppler processor
- *   .range_bin_index                             → 6-bit output bin index
+ *   .range_bin_index                             -> 9-bit output bin index
- *   .decimation_mode                             ← 2-bit mode select
+ *   .decimation_mode                             <- 2-bit mode select
- *   .start_bin                                   ← 10-bit start offset
+ *   .start_bin                                   <- 11-bit start offset
  *
  * start_bin usage:
  *   When start_bin > 0, the decimator skips the first 'start_bin' valid
  *   input samples before beginning decimation. This allows selecting a
- *   region of interest within the 1024 range bins (e.g., to focus on
+ *   region of interest within the 2048 range bins (e.g., to focus on
  *   near-range or far-range targets). When start_bin = 0 (default),
- *   all 1024 bins are processed starting from bin 0.
+ *   all 2048 bins are processed starting from bin 0.
  *
  * Clock domain: clk (100 MHz)
- * Decimation: 1024 → 64 (factor of 16)
+ * Decimation: 2048 -> 512 (factor of 4)
  */
 
+`include "radar_params.vh"
+
 module range_bin_decimator #(
-    parameter INPUT_BINS        = 1024,
+    parameter INPUT_BINS        = `RP_FFT_SIZE,          // 2048
-    parameter OUTPUT_BINS       = 64,
+    parameter OUTPUT_BINS       = `RP_NUM_RANGE_BINS,    // 512
-    parameter DECIMATION_FACTOR = 16
+    parameter DECIMATION_FACTOR = `RP_DECIMATION_FACTOR  // 4
 ) (
     input wire clk,
     input wire reset_n,
@@ -47,11 +49,11 @@ module range_bin_decimator #(
     output reg signed [15:0] range_i_out,
     output reg signed [15:0] range_q_out,
     output reg range_valid_out,
-    output reg [5:0] range_bin_index,
+    output reg [`RP_RANGE_BIN_BITS-1:0] range_bin_index,  // 9-bit
 
     // Configuration
     input wire [1:0] decimation_mode,  // 00=decimate, 01=peak, 10=average
-    input wire [9:0] start_bin,        // First input bin to process
+    input wire [10:0] start_bin,       // First input bin to process (11-bit for 2048)
 
     // Diagnostics
     output reg watchdog_timeout        // Pulses high for 1 cycle on watchdog reset
@@ -59,10 +61,10 @@ module range_bin_decimator #(
 `ifdef FORMAL
     ,
     output wire [2:0]  fv_state,
-    output wire [9:0]  fv_in_bin_count,
+    output wire [10:0] fv_in_bin_count,
-    output wire [3:0]  fv_group_sample_count,
+    output wire [1:0]  fv_group_sample_count,
-    output wire [5:0]  fv_output_bin_count,
+    output wire [8:0]  fv_output_bin_count,
-    output wire [9:0]  fv_skip_count
+    output wire [10:0] fv_skip_count
 `endif
 );
 
@@ -75,12 +77,12 @@ localparam WATCHDOG_LIMIT = 10'd256;
 // INTERNAL SIGNALS
 // ============================================================================
 
-// Input bin counter (0..1023)
+// Input bin counter (0..2047)
-reg [9:0] in_bin_count;
+reg [10:0] in_bin_count;
 
 // Group tracking
-reg [3:0] group_sample_count;  // 0..15 within current group of 16
+reg [1:0] group_sample_count;   // 0..3 within current group of 4
-reg [5:0] output_bin_count;    // 0..63 output bin index
+reg [8:0] output_bin_count;     // 0..511 output bin index
 
 // State machine
 reg [2:0] state;
@@ -91,7 +93,7 @@ localparam ST_EMIT    = 3'd3;
 localparam ST_DONE    = 3'd4;
 
 // Skip counter for start_bin
-reg [9:0] skip_count;
+reg [10:0] skip_count;
 
 // Watchdog counter — counts consecutive clocks with no range_valid_in
 reg [9:0] watchdog_count;
@@ -107,7 +109,7 @@ assign fv_skip_count         = skip_count;
 // ============================================================================
 // PEAK DETECTION (Mode 01)
 // ============================================================================
-// Track the sample with the largest magnitude in the current group of 16
+// Track the sample with the largest magnitude in the current group of 4
 reg signed [15:0] peak_i, peak_q;
 reg [16:0] peak_mag;  // |I| + |Q| approximation
 wire [16:0] cur_mag;
@@ -120,8 +122,8 @@ assign cur_mag = {1'b0, abs_i} + {1'b0, abs_q};
 // ============================================================================
 // AVERAGING (Mode 10)
 // ============================================================================
-// Accumulate I and Q separately, then divide by DECIMATION_FACTOR (>>4)
+// Accumulate I and Q separately, then divide by DECIMATION_FACTOR (>>2)
-reg signed [19:0] sum_i, sum_q;  // 16 + 4 guard bits for sum of 16 values
+reg signed [17:0] sum_i, sum_q;  // 16 + 2 guard bits for sum of 4 values
 
 // ============================================================================
 // SIMPLE DECIMATION (Mode 00)
@@ -135,21 +137,21 @@ reg signed [15:0] decim_i, decim_q;
 always @(posedge clk or negedge reset_n) begin
     if (!reset_n) begin
         state             <= ST_IDLE;
-        in_bin_count      <= 10'd0;
+        in_bin_count      <= 11'd0;
-        group_sample_count <= 4'd0;
+        group_sample_count <= 2'd0;
-        output_bin_count  <= 6'd0;
+        output_bin_count  <= 9'd0;
-        skip_count        <= 10'd0;
+        skip_count        <= 11'd0;
         watchdog_count    <= 10'd0;
         watchdog_timeout  <= 1'b0;
         range_valid_out   <= 1'b0;
         range_i_out       <= 16'd0;
         range_q_out       <= 16'd0;
-        range_bin_index   <= 6'd0;
+        range_bin_index   <= {`RP_RANGE_BIN_BITS{1'b0}};
         peak_i            <= 16'd0;
         peak_q            <= 16'd0;
         peak_mag          <= 17'd0;
-        sum_i             <= 20'd0;
+        sum_i             <= 18'd0;
-        sum_q             <= 20'd0;
+        sum_q             <= 18'd0;
         decim_i           <= 16'd0;
         decim_q           <= 16'd0;
     end else begin
@@ -162,33 +164,33 @@ always @(posedge clk or negedge reset_n) begin
         // IDLE: Wait for first valid input
         // ================================================================
         ST_IDLE: begin
-            in_bin_count       <= 10'd0;
+            in_bin_count       <= 11'd0;
-            group_sample_count <= 4'd0;
+            group_sample_count <= 2'd0;
-            output_bin_count   <= 6'd0;
+            output_bin_count   <= 9'd0;
-            skip_count         <= 10'd0;
+            skip_count         <= 11'd0;
             watchdog_count     <= 10'd0;
             peak_i             <= 16'd0;
             peak_q             <= 16'd0;
             peak_mag           <= 17'd0;
-            sum_i              <= 20'd0;
+            sum_i              <= 18'd0;
-            sum_q              <= 20'd0;
+            sum_q              <= 18'd0;
 
             if (range_valid_in) begin
-                in_bin_count <= 10'd1;
+                in_bin_count <= 11'd1;
 
-                if (start_bin > 10'd0) begin
+                if (start_bin > 11'd0) begin
                     // Need to skip 'start_bin' samples first
-                    skip_count <= 10'd1;
+                    skip_count <= 11'd1;
                     state      <= ST_SKIP;
                 end else begin
                     // No skip — process first sample immediately
                     state              <= ST_PROCESS;
-                    group_sample_count <= 4'd1;
+                    group_sample_count <= 2'd1;
 
                     // Mode-specific first sample handling
                     case (decimation_mode)
                     2'b00: begin  // Simple decimation — check if center sample
-                        if (4'd0 == (DECIMATION_FACTOR / 2)) begin
+                        if (2'd0 == (DECIMATION_FACTOR / 2)) begin
                             decim_i <= range_i_in;
                             decim_q <= range_q_in;
                         end
@@ -199,8 +201,8 @@ always @(posedge clk or negedge reset_n) begin
                         peak_mag <= cur_mag;
                     end
                     2'b10: begin  // Averaging
-                        sum_i <= {{4{range_i_in[15]}}, range_i_in};
+                        sum_i <= {{2{range_i_in[15]}}, range_i_in};
-                        sum_q <= {{4{range_q_in[15]}}, range_q_in};
+                        sum_q <= {{2{range_q_in[15]}}, range_q_in};
                     end
                     default: ;
                     endcase
@@ -219,11 +221,11 @@ always @(posedge clk or negedge reset_n) begin
                 if (skip_count >= start_bin) begin
                     // Done skipping — this sample is the first to process
                     state              <= ST_PROCESS;
-                    group_sample_count <= 4'd1;
+                    group_sample_count <= 2'd1;
 
                     case (decimation_mode)
                     2'b00: begin
-                        if (4'd0 == (DECIMATION_FACTOR / 2)) begin
+                        if (2'd0 == (DECIMATION_FACTOR / 2)) begin
                             decim_i <= range_i_in;
                             decim_q <= range_q_in;
                         end
@@ -234,8 +236,8 @@ always @(posedge clk or negedge reset_n) begin
                         peak_mag <= cur_mag;
                     end
                     2'b10: begin
-                        sum_i <= {{4{range_i_in[15]}}, range_i_in};
+                        sum_i <= {{2{range_i_in[15]}}, range_i_in};
-                        sum_q <= {{4{range_q_in[15]}}, range_q_in};
+                        sum_q <= {{2{range_q_in[15]}}, range_q_in};
                     end
                     default: ;
                     endcase
@@ -281,8 +283,8 @@ always @(posedge clk or negedge reset_n) begin
                     end
                 end
                 2'b10: begin  // Averaging
-                    sum_i <= sum_i + {{4{range_i_in[15]}}, range_i_in};
+                    sum_i <= sum_i + {{2{range_i_in[15]}}, range_i_in};
-                    sum_q <= sum_q + {{4{range_q_in[15]}}, range_q_in};
+                    sum_q <= sum_q + {{2{range_q_in[15]}}, range_q_in};
                 end
                 default: ;
                 endcase
@@ -291,7 +293,7 @@ always @(posedge clk or negedge reset_n) begin
                 if (group_sample_count == DECIMATION_FACTOR - 1) begin
                     // Group complete — emit output
                     state <= ST_EMIT;
-                    group_sample_count <= 4'd0;
+                    group_sample_count <= 2'd0;
                 end else if (in_bin_count >= INPUT_BINS - 1) begin
                     // Overflow guard: consumed all input bins but group
                     // is not yet complete. Stop to prevent corruption of
@@ -331,9 +333,9 @@ always @(posedge clk or negedge reset_n) begin
                 range_i_out <= peak_i;
                 range_q_out <= peak_q;
             end
-            2'b10: begin  // Averaging (sum >> 4 = divide by 16)
+            2'b10: begin  // Averaging (sum >> 2 = divide by 4)
-                range_i_out <= sum_i[19:4];
+                range_i_out <= sum_i[17:2];
-                range_q_out <= sum_q[19:4];
+                range_q_out <= sum_q[17:2];
             end
             default: begin
                 range_i_out <= 16'd0;
@@ -345,8 +347,8 @@ always @(posedge clk or negedge reset_n) begin
             peak_i   <= 16'd0;
             peak_q   <= 16'd0;
             peak_mag <= 17'd0;
-            sum_i    <= 20'd0;
+            sum_i    <= 18'd0;
-            sum_q    <= 20'd0;
+            sum_q    <= 18'd0;
 
             // Advance output bin
             output_bin_count <= output_bin_count + 1;
@@ -358,12 +360,12 @@ always @(posedge clk or negedge reset_n) begin
                 // If we already have valid input waiting, process it immediately
                 if (range_valid_in) begin
                     state              <= ST_PROCESS;
-                    group_sample_count <= 4'd1;
+                    group_sample_count <= 2'd1;
                     in_bin_count       <= in_bin_count + 1;
 
                     case (decimation_mode)
                     2'b00: begin
-                        if (4'd0 == (DECIMATION_FACTOR / 2)) begin
+                        if (2'd0 == (DECIMATION_FACTOR / 2)) begin
                             decim_i <= range_i_in;
                             decim_q <= range_q_in;
                         end
@@ -374,20 +376,20 @@ always @(posedge clk or negedge reset_n) begin
                         peak_mag <= cur_mag;
                     end
                     2'b10: begin
-                        sum_i <= {{4{range_i_in[15]}}, range_i_in};
+                        sum_i <= {{2{range_i_in[15]}}, range_i_in};
-                        sum_q <= {{4{range_q_in[15]}}, range_q_in};
+                        sum_q <= {{2{range_q_in[15]}}, range_q_in};
                     end
                     default: ;
                     endcase
                 end else begin
                     state <= ST_PROCESS;
-                    group_sample_count <= 4'd0;
+                    group_sample_count <= 2'd0;
                 end
             end
         end
 
         // ================================================================
-        // DONE: All 64 output bins emitted, return to idle
+        // DONE: All 512 output bins emitted, return to idle
         // ================================================================
         ST_DONE: begin
             state <= ST_IDLE;

9_Firmware/9_2_FPGA/run_regression.sh

@@ -253,11 +253,141 @@ run_lint_static() {
     fi
 }
 
+# ---------------------------------------------------------------------------
+# Helper: compile, run, and compare a matched-filter co-sim scenario
+#   run_mf_cosim <scenario_name> <define_flag>
+# ---------------------------------------------------------------------------
+run_mf_cosim() {
+    local name="$1"
+    local define="$2"
+    local vvp="tb/tb_mf_cosim_${name}.vvp"
+    local scenario_lower="$name"
+
+    printf "  %-45s " "MF Co-Sim ($name)"
+
+    # Compile — build command as string to handle optional define
+    local cmd="iverilog -g2001 -DSIMULATION"
+    if [[ -n "$define" ]]; then
+        cmd="$cmd $define"
+    fi
+    cmd="$cmd -o $vvp tb/tb_mf_cosim.v matched_filter_processing_chain.v fft_engine.v chirp_memory_loader_param.v"
+
+    if ! eval "$cmd" 2>/tmp/iverilog_err_$$; then
+        echo -e "${RED}COMPILE FAIL${NC}"
+        ERRORS="$ERRORS\n  MF Co-Sim ($name): compile error ($(head -1 /tmp/iverilog_err_$$))"
+        FAIL=$((FAIL + 1))
+        return
+    fi
+
+    # Run TB
+    local output
+    output=$(timeout 120 vvp "$vvp" 2>&1) || true
+    rm -f "$vvp"
+
+    # Check TB internal pass/fail
+    local tb_fail
+    tb_fail=$(echo "$output" | grep -Ec '^\[FAIL' || true)
+    if [[ "$tb_fail" -gt 0 ]]; then
+        echo -e "${RED}FAIL${NC} (TB internal failure)"
+        ERRORS="$ERRORS\n  MF Co-Sim ($name): TB internal failure"
+        FAIL=$((FAIL + 1))
+        return
+    fi
+
+    # Run Python compare
+    if command -v python3 >/dev/null 2>&1; then
+        local compare_out
+        local compare_rc=0
+        compare_out=$(python3 tb/cosim/compare_mf.py "$scenario_lower" 2>&1) || compare_rc=$?
+        if [[ "$compare_rc" -ne 0 ]]; then
+            echo -e "${RED}FAIL${NC} (compare_mf.py mismatch)"
+            ERRORS="$ERRORS\n  MF Co-Sim ($name): Python compare failed"
+            FAIL=$((FAIL + 1))
+            return
+        fi
+    else
+        echo -e "${YELLOW}SKIP${NC} (RTL passed, python3 not found — compare skipped)"
+        SKIP=$((SKIP + 1))
+        return
+    fi
+
+    echo -e "${GREEN}PASS${NC} (RTL + Python compare)"
+    PASS=$((PASS + 1))
+}
+
+# ---------------------------------------------------------------------------
+# Helper: compile, run, and compare a Doppler co-sim scenario
+#   run_doppler_cosim <scenario_name> <define_flag>
+# ---------------------------------------------------------------------------
+run_doppler_cosim() {
+    local name="$1"
+    local define="$2"
+    local vvp="tb/tb_doppler_cosim_${name}.vvp"
+
+    printf "  %-45s " "Doppler Co-Sim ($name)"
+
+    # Compile — build command as string to handle optional define
+    local cmd="iverilog -g2001 -DSIMULATION"
+    if [[ -n "$define" ]]; then
+        cmd="$cmd $define"
+    fi
+    cmd="$cmd -o $vvp tb/tb_doppler_cosim.v doppler_processor.v xfft_16.v fft_engine.v"
+
+    if ! eval "$cmd" 2>/tmp/iverilog_err_$$; then
+        echo -e "${RED}COMPILE FAIL${NC}"
+        ERRORS="$ERRORS\n  Doppler Co-Sim ($name): compile error ($(head -1 /tmp/iverilog_err_$$))"
+        FAIL=$((FAIL + 1))
+        return
+    fi
+
+    # Run TB
+    local output
+    output=$(timeout 120 vvp "$vvp" 2>&1) || true
+    rm -f "$vvp"
+
+    # Check TB internal pass/fail
+    local tb_fail
+    tb_fail=$(echo "$output" | grep -Ec '^\[FAIL' || true)
+    if [[ "$tb_fail" -gt 0 ]]; then
+        echo -e "${RED}FAIL${NC} (TB internal failure)"
+        ERRORS="$ERRORS\n  Doppler Co-Sim ($name): TB internal failure"
+        FAIL=$((FAIL + 1))
+        return
+    fi
+
+    # Run Python compare
+    if command -v python3 >/dev/null 2>&1; then
+        local compare_out
+        local compare_rc=0
+        compare_out=$(python3 tb/cosim/compare_doppler.py "$name" 2>&1) || compare_rc=$?
+        if [[ "$compare_rc" -ne 0 ]]; then
+            echo -e "${RED}FAIL${NC} (compare_doppler.py mismatch)"
+            ERRORS="$ERRORS\n  Doppler Co-Sim ($name): Python compare failed"
+            FAIL=$((FAIL + 1))
+            return
+        fi
+    else
+        echo -e "${YELLOW}SKIP${NC} (RTL passed, python3 not found — compare skipped)"
+        SKIP=$((SKIP + 1))
+        return
+    fi
+
+    echo -e "${GREEN}PASS${NC} (RTL + Python compare)"
+    PASS=$((PASS + 1))
+}
+
 # ---------------------------------------------------------------------------
 # Helper: compile and run a single testbench
 #   run_test <name> <vvp_path> <iverilog_args...>
 # ---------------------------------------------------------------------------
 run_test() {
+    # Optional: --timeout=N as first arg overrides default 120s
+    local timeout_secs=120
+    if [[ "$1" == --timeout=* ]]; then
+        timeout_secs="${1#--timeout=}"
+        shift
+    fi
+
     local name="$1"
     local vvp="$2"
     shift 2
@@ -275,7 +405,7 @@ run_test() {
 
     # Run
     local output
-    output=$(timeout 120 vvp "$vvp" 2>&1) || true
+    output=$(timeout "$timeout_secs" vvp "$vvp" 2>&1) || true
 
     # Count PASS/FAIL in output (testbenches use explicit [PASS]/[FAIL] markers)
     local test_pass test_fail
@@ -367,9 +497,9 @@ run_test "Chirp Contract" \
     tb/tb_chirp_ctr_reg.vvp \
     tb/tb_chirp_contract.v plfm_chirp_controller.v
 
-run_test "Doppler Processor (DSP48)" \
+run_doppler_cosim "stationary"   ""
-    tb/tb_doppler_reg.vvp \
+run_doppler_cosim "moving"       "-DSCENARIO_MOVING"
-    tb/tb_doppler_cosim.v doppler_processor.v xfft_16.v fft_engine.v
+run_doppler_cosim "two_targets"  "-DSCENARIO_TWO"
 
 run_test "Threshold Detector (detection bugs)" \
     tb/tb_threshold_detector.vvp \
@@ -416,30 +546,31 @@ run_test "Full-Chain Real-Data (decim→Doppler, exact match)" \
     doppler_processor.v xfft_16.v fft_engine.v
 
 if [[ "$QUICK" -eq 0 ]]; then
-    # Golden generate
+    # NOTE: The "Receiver golden generate/compare" pair was REMOVED because
-    run_test "Receiver (golden generate)" \
+    # it was self-blessing: both passes ran the same RTL with the same
-        tb/tb_rx_golden_reg.vvp \
+    # deterministic stimulus, so the test always passed regardless of bugs.
-        -DGOLDEN_GENERATE \
+    # Real co-sim coverage is provided by:
-        tb/tb_radar_receiver_final.v radar_receiver_final.v \
+    #   - tb_doppler_realdata.v  (committed Python golden hex, exact match)
-        radar_mode_controller.v tb/ad9484_interface_400m_stub.v \
+    #   - tb_fullchain_realdata.v (committed Python golden hex, exact match)
-        ddc_400m.v nco_400m_enhanced.v cic_decimator_4x_enhanced.v \
+    # A proper full-pipeline co-sim (DDC→MF→Decim→Doppler vs Python) is
-        cdc_modules.v fir_lowpass.v ddc_input_interface.v \
+    # planned as a replacement (Phase C of CI test plan).
-        chirp_memory_loader_param.v latency_buffer.v \
-        matched_filter_multi_segment.v matched_filter_processing_chain.v \
-        range_bin_decimator.v doppler_processor.v xfft_16.v fft_engine.v \
-        rx_gain_control.v mti_canceller.v
 
-    # Golden compare
+    # Receiver integration (structural + bounds + pulse assertions)
-    run_test "Receiver (golden compare)" \
+    # Tests the full RX pipeline: ADC stub → DDC → MF → Decim → Doppler
-        tb/tb_rx_compare_reg.vvp \
+    # Verifies doppler_frame_done is a single-cycle pulse (catches
-        tb/tb_radar_receiver_final.v radar_receiver_final.v \
+    # level-vs-pulse wiring bugs at module boundaries).
-        radar_mode_controller.v tb/ad9484_interface_400m_stub.v \
+    run_test --timeout=600 "Receiver Integration (tb_radar_receiver_final)" \
+        tb/tb_rx_final_reg.vvp \
+        tb/tb_radar_receiver_final.v \
+        radar_receiver_final.v tb/ad9484_interface_400m_stub.v \
         ddc_400m.v nco_400m_enhanced.v cic_decimator_4x_enhanced.v \
         cdc_modules.v fir_lowpass.v ddc_input_interface.v \
+        rx_gain_control.v \
         chirp_memory_loader_param.v latency_buffer.v \
         matched_filter_multi_segment.v matched_filter_processing_chain.v \
-        range_bin_decimator.v doppler_processor.v xfft_16.v fft_engine.v \
+        range_bin_decimator.v mti_canceller.v \
-        rx_gain_control.v mti_canceller.v
+        doppler_processor.v xfft_16.v fft_engine.v \
+        radar_mode_controller.v
 
     # Full system top (monitoring-only, legacy)
     run_test "System Top (radar_system_tb)" \
@@ -469,12 +600,28 @@ if [[ "$QUICK" -eq 0 ]]; then
         usb_data_interface.v edge_detector.v radar_mode_controller.v \
         rx_gain_control.v cfar_ca.v mti_canceller.v fpga_self_test.v
 else
-    echo "  (skipped receiver golden + system top + E2E — use without --quick)"
+    echo "  (skipped system top + E2E — use without --quick)"
-    SKIP=$((SKIP + 4))
+    SKIP=$((SKIP + 2))
 fi
 
 echo ""
 
+# ===========================================================================
+# PHASE 2b: MATCHED FILTER CO-SIMULATION (RTL vs Python golden reference)
+# Runs tb_mf_cosim.v for 4 scenarios, then compare_mf.py validates output
+# against committed Python golden CSV files. In SIMULATION mode, thresholds
+# are generous (behavioral vs fixed-point twiddles differ) — validates
+# state machine mechanics, output count, and energy sanity.
+# ===========================================================================
+echo "--- PHASE 2b: Matched Filter Co-Sim ---"
+
+run_mf_cosim "chirp"   ""
+run_mf_cosim "dc"      "-DSCENARIO_DC"
+run_mf_cosim "impulse" "-DSCENARIO_IMPULSE"
+run_mf_cosim "tone5"   "-DSCENARIO_TONE5"
+
+echo ""
+
 # ===========================================================================
 # PHASE 3: UNIT TESTS — Signal Processing
 # ===========================================================================

9_Firmware/9_2_FPGA/rx_gain_control.v

@@ -3,19 +3,32 @@
 /**
  * rx_gain_control.v
  *
- * Host-configurable digital gain control for the receive path.
+ * Digital gain control with optional per-frame automatic gain control (AGC)
- * Placed between DDC output (ddc_input_interface) and matched filter input.
+ * for the receive path. Placed between DDC output and matched filter input.
  *
- * Features:
+ * Manual mode (agc_enable=0):
- *   - Bidirectional power-of-2 gain shift (arithmetic shift)
+ *   - Uses host_gain_shift directly (backward-compatible, no behavioral change)
  *   - gain_shift[3]   = direction: 0 = left shift (amplify), 1 = right shift (attenuate)
  *   - gain_shift[2:0] = amount: 0..7 bits
- *   - Symmetric saturation to ±32767 on overflow (left shift only)
+ *   - Symmetric saturation to ±32767 on overflow
- *   - Saturation counter: 8-bit, counts samples that clipped (wraps at 255)
- *   - 1-cycle latency, valid-in/valid-out pipeline
- *   - Zero-overhead pass-through when gain_shift == 0
  *
- * Intended insertion point in radar_receiver_final.v:
+ * AGC mode (agc_enable=1):
+ *   - Per-frame automatic gain adjustment based on peak/saturation metrics
+ *   - Internal signed gain: -7 (max attenuation) to +7 (max amplification)
+ *   - On frame_boundary:
+ *       * If saturation detected: gain -= agc_attack (fast, immediate)
+ *       * Else if peak < target after holdoff frames: gain += agc_decay (slow)
+ *       * Else: hold current gain
+ *   - host_gain_shift serves as initial gain when AGC first enabled
+ *
+ * Status outputs (for readback via status_words):
+ *   - current_gain[3:0]: effective gain_shift encoding (manual or AGC)
+ *   - peak_magnitude[7:0]: per-frame peak |sample| (upper 8 bits of 15-bit value)
+ *   - saturation_count[7:0]: per-frame clipped sample count (capped at 255)
+ *
+ * Timing: 1-cycle data latency, valid-in/valid-out pipeline.
+ *
+ * Insertion point in radar_receiver_final.v:
  *   ddc_input_interface → rx_gain_control → matched_filter_multi_segment
  */
 
@@ -28,27 +41,75 @@ module rx_gain_control (
     input  wire signed [15:0] data_q_in,
     input  wire               valid_in,
 
-    // Gain configuration (from host via USB command)
+    // Host gain configuration (from USB command opcode 0x16)
-    // [3]   = direction: 0=amplify (left shift), 1=attenuate (right shift)
+    // [3]=direction: 0=amplify (left shift), 1=attenuate (right shift)
-    // [2:0] = shift amount: 0..7 bits
+    // [2:0]=shift amount: 0..7 bits. Default 0x00 = pass-through.
+    // In AGC mode: serves as initial gain on AGC enable transition.
     input  wire [3:0]  gain_shift,
 
+    // AGC configuration inputs (from host via USB, opcodes 0x28-0x2C)
+    input  wire        agc_enable,     // 0x28: 0=manual gain, 1=auto AGC
+    input  wire [7:0]  agc_target,     // 0x29: target peak magnitude (unsigned, default 200)
+    input  wire [3:0]  agc_attack,     // 0x2A: attenuation step on clipping (default 1)
+    input  wire [3:0]  agc_decay,      // 0x2B: amplification step when weak (default 1)
+    input  wire [3:0]  agc_holdoff,    // 0x2C: frames to wait before gain-up (default 4)
+
+    // Frame boundary pulse (1 clk cycle, from edge detector in radar_receiver_final)
+    input  wire        frame_boundary,
+
     // Data output (to matched filter)
     output reg  signed [15:0] data_i_out,
     output reg  signed [15:0] data_q_out,
     output reg                valid_out,
 
-    // Diagnostics
+    // Diagnostics / status readback
-    output reg  [7:0]  saturation_count  // Number of clipped samples (wraps at 255)
+    output reg  [7:0]  saturation_count,  // Per-frame clipped sample count (capped at 255)
+    output reg  [7:0]  peak_magnitude,    // Per-frame peak |sample| (upper 8 bits of 15-bit)
+    output reg  [3:0]  current_gain       // Current effective gain_shift (for status readback)
 );
 
-// Decompose gain_shift
+// =========================================================================
-wire       shift_right = gain_shift[3];
+// INTERNAL AGC STATE
-wire [2:0] shift_amt   = gain_shift[2:0];
+// =========================================================================
 
-// -------------------------------------------------------------------------
+// Signed internal gain: -7 (max attenuation) to +7 (max amplification)
-// Combinational shift + saturation
+// Stored as 4-bit signed (range -8..+7, clamped to -7..+7)
-// -------------------------------------------------------------------------
+reg signed [3:0] agc_gain;
+
+// Holdoff counter: counts frames without saturation before allowing gain-up
+reg [3:0] holdoff_counter;
+
+// Per-frame accumulators (running, reset on frame_boundary)
+reg [7:0]  frame_sat_count;    // Clipped samples this frame
+reg [14:0] frame_peak;         // Peak |sample| this frame (15-bit unsigned)
+
+// Previous AGC enable state (for detecting 0→1 transition)
+reg agc_enable_prev;
+
+// Combinational helpers for inclusive frame-boundary snapshot
+// (used when valid_in and frame_boundary coincide)
+reg wire_frame_sat_incr;
+reg wire_frame_peak_update;
+
+// =========================================================================
+// EFFECTIVE GAIN SELECTION
+// =========================================================================
+
+// Convert between signed internal gain and the gain_shift[3:0] encoding.
+//   gain_shift[3]=0, [2:0]=N → amplify by N bits (internal gain = +N)
+//   gain_shift[3]=1, [2:0]=N → attenuate by N bits (internal gain = -N)
+
+// Effective gain_shift used for the actual shift operation
+wire [3:0] effective_gain;
+assign effective_gain = agc_enable ? current_gain : gain_shift;
+
+// Decompose effective gain for shift logic
+wire       shift_right = effective_gain[3];
+wire [2:0] shift_amt   = effective_gain[2:0];
+
+// =========================================================================
+// COMBINATIONAL SHIFT + SATURATION
+// =========================================================================
 // Use wider intermediates to detect overflow on left shift.
 // 24 bits is enough: 16 + 7 shift = 23 significant bits max.
 
@@ -69,26 +130,153 @@ wire signed [15:0] sat_i = overflow_i ? (shifted_i[23] ? -16'sd32768 : 16'sd3276
 wire signed [15:0] sat_q = overflow_q ? (shifted_q[23] ? -16'sd32768 : 16'sd32767)
                                       : shifted_q[15:0];
 
-// -------------------------------------------------------------------------
+// =========================================================================
-// Registered output stage (1-cycle latency)
+// PEAK MAGNITUDE TRACKING (combinational)
-// -------------------------------------------------------------------------
+// =========================================================================
+// Absolute value of signed 16-bit: flip sign bit if negative.
+// Result is 15-bit unsigned [0, 32767]. (We ignore -32768 → 32767 edge case.)
+wire [14:0] abs_i = data_i_in[15] ? (~data_i_in[14:0] + 15'd1) : data_i_in[14:0];
+wire [14:0] abs_q = data_q_in[15] ? (~data_q_in[14:0] + 15'd1) : data_q_in[14:0];
+wire [14:0] max_iq = (abs_i > abs_q) ? abs_i : abs_q;
+
+// =========================================================================
+// SIGNED GAIN ↔ GAIN_SHIFT ENCODING CONVERSION
+// =========================================================================
+// Convert signed agc_gain to gain_shift[3:0] encoding
+function [3:0] signed_to_encoding;
+    input signed [3:0] g;
+    begin
+        if (g >= 0)
+            signed_to_encoding = {1'b0, g[2:0]};       // amplify
+        else
+            signed_to_encoding = {1'b1, (~g[2:0]) + 3'd1}; // attenuate: -g
+    end
+endfunction
+
+// Convert gain_shift[3:0] encoding to signed gain
+function signed [3:0] encoding_to_signed;
+    input [3:0] enc;
+    begin
+        if (enc[3] == 1'b0)
+            encoding_to_signed = {1'b0, enc[2:0]};     // +0..+7
+        else
+            encoding_to_signed = -$signed({1'b0, enc[2:0]}); // -1..-7
+    end
+endfunction
+
+// =========================================================================
+// CLAMPING HELPER
+// =========================================================================
+// Clamp a wider signed value to [-7, +7]
+function signed [3:0] clamp_gain;
+    input signed [4:0] val;  // 5-bit to handle overflow from add
+    begin
+        if (val > 5'sd7)
+            clamp_gain = 4'sd7;
+        else if (val < -5'sd7)
+            clamp_gain = -4'sd7;
+        else
+            clamp_gain = val[3:0];
+    end
+endfunction
+
+// =========================================================================
+// REGISTERED OUTPUT + AGC STATE MACHINE
+// =========================================================================
 always @(posedge clk or negedge reset_n) begin
     if (!reset_n) begin
+        // Data path
         data_i_out       <= 16'sd0;
         data_q_out       <= 16'sd0;
         valid_out        <= 1'b0;
+        // Status outputs
         saturation_count <= 8'd0;
+        peak_magnitude   <= 8'd0;
+        current_gain     <= 4'd0;
+        // AGC internal state
+        agc_gain         <= 4'sd0;
+        holdoff_counter  <= 4'd0;
+        frame_sat_count  <= 8'd0;
+        frame_peak       <= 15'd0;
+        agc_enable_prev  <= 1'b0;
     end else begin
-        valid_out <= valid_in;
+        // Track AGC enable transitions
+        agc_enable_prev <= agc_enable;
 
+        // Compute inclusive metrics: if valid_in fires this cycle,
+        // include current sample in the snapshot taken at frame_boundary.
+        // This avoids losing the last sample when valid_in and
+        // frame_boundary coincide (NBA last-write-wins would otherwise
+        // snapshot stale values then reset, dropping the sample entirely).
+        wire_frame_sat_incr = (valid_in && (overflow_i || overflow_q)
+                               && (frame_sat_count != 8'hFF));
+        wire_frame_peak_update = (valid_in && (max_iq > frame_peak));
+
+        // ---- Data pipeline (1-cycle latency) ----
+        valid_out <= valid_in;
         if (valid_in) begin
             data_i_out <= sat_i;
             data_q_out <= sat_q;
 
-            // Count clipped samples (either channel clipping counts as 1)
+            // Per-frame saturation counting
-            if ((overflow_i || overflow_q) && (saturation_count != 8'hFF))
+            if ((overflow_i || overflow_q) && (frame_sat_count != 8'hFF))
-                saturation_count <= saturation_count + 8'd1;
+                frame_sat_count <= frame_sat_count + 8'd1;
+
+            // Per-frame peak tracking (pre-gain, measures input signal level)
+            if (max_iq > frame_peak)
+                frame_peak <= max_iq;
         end
+
+        // ---- Frame boundary: AGC update + metric snapshot ----
+        if (frame_boundary) begin
+            // Snapshot per-frame metrics INCLUDING current sample if valid_in
+            saturation_count <= wire_frame_sat_incr
+                                ? (frame_sat_count + 8'd1)
+                                : frame_sat_count;
+            peak_magnitude   <= wire_frame_peak_update
+                                ? max_iq[14:7]
+                                : frame_peak[14:7];
+
+            // Reset per-frame accumulators for next frame
+            frame_sat_count <= 8'd0;
+            frame_peak      <= 15'd0;
+
+            if (agc_enable) begin
+                // AGC auto-adjustment at frame boundary
+                // Use inclusive counts/peaks (accounting for simultaneous valid_in)
+                if (wire_frame_sat_incr || frame_sat_count > 8'd0) begin
+                    // Clipping detected: reduce gain immediately (attack)
+                    agc_gain <= clamp_gain($signed({agc_gain[3], agc_gain}) -
+                                           $signed({1'b0, agc_attack}));
+                    holdoff_counter <= agc_holdoff;  // Reset holdoff
+                end else if ((wire_frame_peak_update ? max_iq[14:7] : frame_peak[14:7])
+                             < agc_target) begin
+                    // Signal too weak: increase gain after holdoff expires
+                    if (holdoff_counter == 4'd0) begin
+                        agc_gain <= clamp_gain($signed({agc_gain[3], agc_gain}) +
+                                               $signed({1'b0, agc_decay}));
+                    end else begin
+                        holdoff_counter <= holdoff_counter - 4'd1;
+                    end
+                end else begin
+                    // Signal in good range, no saturation: hold gain
+                    // Reset holdoff so next weak frame has to wait again
+                    holdoff_counter <= agc_holdoff;
+                end
+            end
+        end
+
+        // ---- AGC enable transition: initialize from host gain ----
+        if (agc_enable && !agc_enable_prev) begin
+            agc_gain        <= encoding_to_signed(gain_shift);
+            holdoff_counter <= agc_holdoff;
+        end
+
+        // ---- Update current_gain output ----
+        if (agc_enable)
+            current_gain <= signed_to_encoding(agc_gain);
+        else
+            current_gain <= gain_shift;
     end
 end
 

9_Firmware/9_2_FPGA/scripts/50t/build_50t.tcl

@@ -120,9 +120,10 @@ set_property CLOCK_DEDICATED_ROUTE FALSE [get_nets {ft_clkout_IBUF}]
 
 # ---- Run implementation steps ----
 opt_design -directive Explore
-place_design -directive Explore
+place_design -directive ExtraNetDelay_high
+phys_opt_design -directive AggressiveExplore
+route_design -directive AggressiveExplore
 phys_opt_design -directive AggressiveExplore
-route_design -directive Explore
 phys_opt_design -directive AggressiveExplore
 
 set impl_elapsed [expr {[clock seconds] - $impl_start}]

9_Firmware/9_2_FPGA/tb/cosim/compare_doppler.py

@@ -34,8 +34,8 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 # =============================================================================
 
 DOPPLER_FFT = 32
-RANGE_BINS = 64
+RANGE_BINS = 512
-TOTAL_OUTPUTS = RANGE_BINS * DOPPLER_FFT  # 2048
+TOTAL_OUTPUTS = RANGE_BINS * DOPPLER_FFT  # 16384
 SUBFRAME_SIZE = 16
 
 SCENARIOS = {
@@ -246,7 +246,7 @@ def compare_scenario(name, config, base_dir):
     # ---- Pass/Fail ----
     checks = []
 
-    checks.append(('RTL output count == 2048', count_ok))
+    checks.append(('RTL output count == 16384', count_ok))
 
     energy_ok = (ENERGY_RATIO_MIN < energy_ratio < ENERGY_RATIO_MAX)
     checks.append((f'Energy ratio in bounds '

9_Firmware/9_2_FPGA/tb/cosim/compare_mf.py

@@ -36,7 +36,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 # Configuration
 # =============================================================================
 
-FFT_SIZE = 1024
+FFT_SIZE = 2048
 
 SCENARIOS = {
     'chirp': {
@@ -243,7 +243,7 @@ def compare_scenario(scenario_name, config, base_dir):
 
     # Check 2: RTL produced expected sample count
     correct_count = len(rtl_i) == FFT_SIZE
-    checks.append(('Correct output count (1024)', correct_count))
+    checks.append(('Correct output count (2048)', correct_count))
 
     # Check 3: Energy ratio within generous bounds
     # Allow very wide range since twiddle differences cause large gain variation

9_Firmware/9_2_FPGA/tb/cosim/fpga_model.py

@@ -709,15 +709,24 @@ class DDCInputInterface:
 # FFT Engine (1024-point radix-2 DIT, in-place, 32-bit internal)
 # =============================================================================
 
-def load_twiddle_rom(filepath=None):
+def load_twiddle_rom(filepath=None, n=2048):
     """
-    Load 256-entry quarter-wave cosine ROM from hex file.
+    Load quarter-wave cosine ROM from hex file.
-    Returns list of 256 signed 16-bit integers.
+    Returns list of N/4 signed 16-bit integers.
+
+    For N=2048: loads fft_twiddle_2048.mem (512 entries).
+    For N=1024: loads fft_twiddle_1024.mem (256 entries).
+    For N=16:   loads fft_twiddle_16.mem (4 entries).
     """
     if filepath is None:
         # Default path relative to this file
         base = os.path.dirname(os.path.abspath(__file__))
-        filepath = os.path.join(base, '..', '..', 'fft_twiddle_1024.mem')
+        if n == 2048:
+            filepath = os.path.join(base, '..', '..', 'fft_twiddle_2048.mem')
+        elif n == 16:
+            filepath = os.path.join(base, '..', '..', 'fft_twiddle_16.mem')
+        else:
+            filepath = os.path.join(base, '..', '..', 'fft_twiddle_1024.mem')
 
     values = []
     with open(filepath) as f:
@@ -759,17 +768,17 @@ class FFTEngine:
     """
     Bit-accurate model of fft_engine.v
 
-    1024-point radix-2 DIT FFT/IFFT.
+    2048-point radix-2 DIT FFT/IFFT.
     Internal: 32-bit signed working data.
     Twiddle: 16-bit Q15 from quarter-wave cosine ROM.
     Butterfly: multiply 32x16->49 bits, >>>15, add/subtract.
     Output: saturate 32->16 bits. IFFT also >>>LOG2N before saturate.
     """
 
-    def __init__(self, n=1024, twiddle_file=None):
+    def __init__(self, n=2048, twiddle_file=None):
         self.N = n
         self.LOG2N = n.bit_length() - 1
-        self.cos_rom = load_twiddle_rom(twiddle_file)
+        self.cos_rom = load_twiddle_rom(twiddle_file, n=n)
         # Working memory (32-bit signed I/Q pairs)
         self.mem_re = [0] * n
         self.mem_im = [0] * n
@@ -942,21 +951,21 @@ class MatchedFilterChain:
     Uses a single FFTEngine instance (as in RTL, engine is reused).
     """
 
-    def __init__(self, fft_size=1024, twiddle_file=None):
+    def __init__(self, fft_size=2048, twiddle_file=None):
         self.fft_size = fft_size
         self.fft = FFTEngine(n=fft_size, twiddle_file=twiddle_file)
         self.conj_mult = FreqMatchedFilter()
 
     def process(self, sig_re, sig_im, ref_re, ref_im):
         """
-        Run matched filter on 1024-sample signal + reference.
+        Run matched filter on signal + reference.
 
         Args:
-            sig_re/im: signal I/Q (16-bit signed, 1024 samples)
+            sig_re/im: signal I/Q (16-bit signed, fft_size samples)
-            ref_re/im: reference chirp I/Q (16-bit signed, 1024 samples)
+            ref_re/im: reference chirp I/Q (16-bit signed, fft_size samples)
 
         Returns:
-            (range_profile_re, range_profile_im): 1024 x 16-bit signed
+            (range_profile_re, range_profile_im): fft_size x 16-bit signed
         """
         # Forward FFT of signal
         sig_fft_re, sig_fft_im = self.fft.compute(sig_re, sig_im, inverse=False)
@@ -984,27 +993,27 @@ class RangeBinDecimator:
     Bit-accurate model of range_bin_decimator.v
 
     Three modes:
-      00: Simple decimation (take center sample at index 8)
+      00: Simple decimation (take center sample at index 2)
       01: Peak detection (max |I|+|Q|)
-      10: Averaging (sum >> 4, truncation)
+      10: Averaging (sum >> 2, truncation)
       11: Reserved (output 0)
     """
 
-    DECIMATION_FACTOR = 16
+    DECIMATION_FACTOR = 4
-    OUTPUT_BINS = 64
+    OUTPUT_BINS = 512
 
     @staticmethod
     def decimate(range_re, range_im, mode=1, start_bin=0):
         """
-        Decimate 1024 range bins to 64.
+        Decimate 2048 range bins to 512.
 
         Args:
-            range_re/im: 1024 x signed 16-bit
+            range_re/im: 2048 x signed 16-bit
             mode: 0=center, 1=peak, 2=average, 3=zero
-            start_bin: first input bin to process (0-1023)
+            start_bin: first input bin to process (0-2047)
 
         Returns:
-            (out_re, out_im): 64 x signed 16-bit
+            (out_re, out_im): 512 x signed 16-bit
         """
         out_re = []
         out_im = []
@@ -1052,9 +1061,9 @@ class RangeBinDecimator:
                     if idx < len(range_re):
                         sum_re += sign_extend(range_re[idx] & 0xFFFF, 16)
                         sum_im += sign_extend(range_im[idx] & 0xFFFF, 16)
-                # Truncate (arithmetic right shift by 4), take 16 bits
+                # Truncate (arithmetic right shift by 2), take 16 bits
-                out_re.append(sign_extend((sum_re >> 4) & 0xFFFF, 16))
+                out_re.append(sign_extend((sum_re >> 2) & 0xFFFF, 16))
-                out_im.append(sign_extend((sum_im >> 4) & 0xFFFF, 16))
+                out_im.append(sign_extend((sum_im >> 2) & 0xFFFF, 16))
 
             else:
                 # Mode 3: reserved, output 0
@@ -1090,7 +1099,7 @@ class DopplerProcessor:
     """
 
     DOPPLER_FFT_SIZE = 16     # Per sub-frame
-    RANGE_BINS = 64
+    RANGE_BINS = 512
     CHIRPS_PER_FRAME = 32
     CHIRPS_PER_SUBFRAME = 16
 
@@ -1126,11 +1135,11 @@ class DopplerProcessor:
         Process one complete Doppler frame using dual 16-pt FFTs.
 
         Args:
-            chirp_data_i: 2D array [32 chirps][64 range bins] of signed 16-bit I
+            chirp_data_i: 2D array [32 chirps][512 range bins] of signed 16-bit I
-            chirp_data_q: 2D array [32 chirps][64 range bins] of signed 16-bit Q
+            chirp_data_q: 2D array [32 chirps][512 range bins] of signed 16-bit Q
 
         Returns:
-            (doppler_map_i, doppler_map_q): 2D arrays [64 range bins][32 doppler bins]
+            (doppler_map_i, doppler_map_q): 2D arrays [512 range bins][32 doppler bins]
                                             of signed 16-bit
                                             Bins 0-15 = sub-frame 0 (long PRI)
                                             Bins 16-31 = sub-frame 1 (short PRI)
@@ -1213,7 +1222,7 @@ class SignalChain:
     IF_FREQ = 120_000_000    # IF frequency
     FTW_120MHZ = 0x4CCCCCCD  # Phase increment for 120 MHz at 400 MSPS
 
-    def __init__(self, twiddle_file_1024=None, twiddle_file_16=None):
+    def __init__(self, twiddle_file_2048=None, twiddle_file_16=None):
         self.nco = NCO()
         self.mixer = Mixer()
         self.cic_i = CICDecimator()
@@ -1221,7 +1230,7 @@ class SignalChain:
         self.fir_i = FIRFilter()
         self.fir_q = FIRFilter()
         self.ddc_interface = DDCInputInterface()
-        self.matched_filter = MatchedFilterChain(fft_size=1024, twiddle_file=twiddle_file_1024)
+        self.matched_filter = MatchedFilterChain(fft_size=2048, twiddle_file=twiddle_file_2048)
         self.range_decimator = RangeBinDecimator()
         self.doppler = DopplerProcessor(twiddle_file_16=twiddle_file_16)
 

9_Firmware/9_2_FPGA/tb/cosim/gen_chirp_mem.py

@@ -2,34 +2,22 @@
 """
 gen_chirp_mem.py — Generate all chirp .mem files for AERIS-10 FPGA.
 
-Generates the 10 chirp .mem files used by chirp_memory_loader_param.v:
+Generates the 6 chirp .mem files used by chirp_memory_loader_param.v:
-  - long_chirp_seg{0,1,2,3}_{i,q}.mem  (8 files, 1024 lines each)
+  - long_chirp_seg{0,1}_{i,q}.mem  (4 files, 2048 lines each)
-  - short_chirp_{i,q}.mem              (2 files, 50 lines each)
+  - short_chirp_{i,q}.mem          (2 files, 50 lines each)
 
 Long chirp:
   The 3000-sample baseband chirp (30 us at 100 MHz system clock) is
-  segmented into 4 blocks of 1024 samples.  Each segment covers a
+  segmented into 2 blocks of 2048 samples.  Each segment covers a
   different time window of the chirp:
-    seg0: samples   0 .. 1023
+    seg0: samples    0 .. 2047
-    seg1: samples 1024 .. 2047
+    seg1: samples 2048 .. 4095  (only 952 valid chirp samples; 1096 zeros)
-    seg2: samples 2048 .. 3071  (only 952 valid chirp samples; 72 zeros)
-    seg3: all zeros (seg3 starts at sample 3072, past chirp end at 3000)
 
-  Wait — actually the memory loader stores 4*1024 = 4096 contiguous
+  The memory loader stores 2*2048 = 4096 contiguous samples indexed
-  samples indexed by {segment_select[1:0], sample_addr[9:0]}.  The
+  by {segment_select[0], sample_addr[10:0]}.  The long chirp has
-  long chirp has 3000 samples, so:
+  3000 samples, so:
-    seg0: chirp[0..1023]
+    seg0: chirp[0..2047] — all valid data
-    seg1: chirp[1024..2047]
+    seg1: chirp[2048..2999] + 1096 zeros (samples past chirp end)
-    seg2: chirp[2048..2999] + 24 zeros  (samples 2048..3071 but chirp
-          ends at 2999, so indices 3000..3071 relative to full chirp
-          => mem indices 952..1023 in seg2 file are zero)
-
-  Wait, let me re-count.  seg2 covers global indices 2048..3071.
-  The chirp has samples 0..2999 (3000 samples).  So seg2 has valid
-  data at global indices 2048..2999 = 952 valid samples (seg2 file
-  indices 0..951), then zeros at file indices 952..1023 (72 zeros).
-
-  seg3 covers global indices 3072..4095, all past chirp end => all zeros.
 
 Short chirp:
   50 samples (0.5 us at 100 MHz), same chirp formula with
@@ -56,10 +44,10 @@ CHIRP_BW = 20e6           # 20 MHz sweep bandwidth
 FS_SYS = 100e6            # System clock (100 MHz, post-CIC)
 T_LONG_CHIRP = 30e-6      # 30 us long chirp duration
 T_SHORT_CHIRP = 0.5e-6    # 0.5 us short chirp duration
-FFT_SIZE = 1024
+FFT_SIZE = 2048
 LONG_CHIRP_SAMPLES = int(T_LONG_CHIRP * FS_SYS)   # 3000
 SHORT_CHIRP_SAMPLES = int(T_SHORT_CHIRP * FS_SYS)  # 50
-LONG_SEGMENTS = 4
+LONG_SEGMENTS = 2
 SCALE = 0.9               # Q15 scaling factor (matches radar_scene.py)
 Q15_MAX = 32767
 
@@ -187,13 +175,14 @@ def main():
     # Check magnitude envelope
     max(math.sqrt(i*i + q*q) for i, q in zip(long_i, long_q, strict=False))
 
-    # Check seg3 zero padding
+    # Check seg1 zero padding (samples 3000-4095 should be zero)
-    seg3_i_path = os.path.join(MEM_DIR, 'long_chirp_seg3_i.mem')
+    seg1_i_path = os.path.join(MEM_DIR, 'long_chirp_seg1_i.mem')
-    with open(seg3_i_path) as f:
+    with open(seg1_i_path) as f:
-        seg3_lines = [line.strip() for line in f if line.strip()]
+        seg1_lines = [line.strip() for line in f if line.strip()]
-    nonzero_seg3 = sum(1 for line in seg3_lines if line != '0000')
+    # Indices 952..2047 in seg1 (global 3000..4095) should be zero
+    nonzero_tail = sum(1 for line in seg1_lines[952:] if line != '0000')
 
-    if nonzero_seg3 == 0:
+    if nonzero_tail == 0:
         pass
     else:
         pass

9_Firmware/9_2_FPGA/tb/cosim/gen_doppler_golden.py

@@ -35,9 +35,9 @@ from radar_scene import Target, generate_doppler_frame
 
 DOPPLER_FFT_SIZE = 16     # Per sub-frame
 DOPPLER_TOTAL_BINS = 32   # Total output (2 sub-frames x 16)
-RANGE_BINS = 64
+RANGE_BINS = 512
 CHIRPS_PER_FRAME = 32
-TOTAL_SAMPLES = CHIRPS_PER_FRAME * RANGE_BINS  # 2048
+TOTAL_SAMPLES = CHIRPS_PER_FRAME * RANGE_BINS  # 16384
 
 
 # =============================================================================

9_Firmware/9_2_FPGA/tb/cosim/gen_mf_cosim_golden.py

@@ -30,7 +30,7 @@ from fpga_model import (
 )
 
 
-FFT_SIZE = 1024
+FFT_SIZE = 2048
 
 
 def load_hex_16bit(filepath):
@@ -143,9 +143,13 @@ def main():
         bb_q = load_hex_16bit(bb_q_path)
         ref_i = load_hex_16bit(ref_i_path)
         ref_q = load_hex_16bit(ref_q_path)
+        # Zero-pad to FFT_SIZE if shorter (legacy 1024-entry files → 2048)
+        for lst in [bb_i, bb_q, ref_i, ref_q]:
+            while len(lst) < FFT_SIZE:
+                lst.append(0)
         r = generate_case("chirp", bb_i, bb_q, ref_i, ref_q,
                           "Radar chirp: 2 targets (500m, 1500m) vs ref chirp",
-                          base_dir)
+                          base_dir, write_inputs=True)
         results.append(r)
     else:
         pass

9_Firmware/9_2_FPGA/tb/cosim/gen_multiseg_golden.py

@@ -5,8 +5,8 @@ gen_multiseg_golden.py
 Generate golden reference data for matched_filter_multi_segment co-simulation.
 
 Tests the overlap-save segmented convolution wrapper:
-  - Long chirp: 3072 samples (4 segments x 1024, with 128-sample overlap)
+  - Long chirp: 3072 samples (2 segments x 2048, with overlap)
-  - Short chirp: 50 samples zero-padded to 1024 (1 segment)
+  - Short chirp: 50 samples zero-padded to 2048 (1 segment)
 
 The matched_filter_processing_chain is already verified bit-perfect.
 This test validates that the multi_segment wrapper:
@@ -17,7 +17,7 @@ This test validates that the multi_segment wrapper:
 
 Strategy:
   - Generate known input data (identifiable per-segment patterns)
-  - Generate per-segment reference chirp data (1024 samples each)
+  - Generate per-segment reference chirp data (2048 samples each)
   - Run each segment through MatchedFilterChain independently in Python
   - Compare RTL multi-segment outputs against per-segment Python outputs
 
@@ -64,7 +64,7 @@ def generate_long_chirp_test():
       - buffer_write_ptr starts at 0 (from ST_IDLE reset)
       - Collects 896 samples into positions [0:895]
       - Positions [896:1023] remain zero (from initial block)
-      - Processes full 1024-sample buffer
+      - Processes full 2048-sample buffer
 
     For segment 1 (ST_NEXT_SEGMENT):
       - Copies input_buffer[SEGMENT_ADVANCE+i] to input_buffer[i] for i=0..127
@@ -89,7 +89,7 @@ def generate_long_chirp_test():
                           positions 0-895: input data
                           positions 896-1023: zeros from initial block
 
-    Processing chain sees: 1024 samples = [data[0:895], zeros[896:1023]]
+    Processing chain sees: 2048 samples = [data[0:1919], zeros[1920:2047]]
 
     OVERLAP-SAVE (ST_NEXT_SEGMENT):
       - Copies buffer[SEGMENT_ADVANCE+i] -> buffer[i] for i=0..OVERLAP-1
@@ -105,12 +105,12 @@ def generate_long_chirp_test():
         It was 896 after segment 0, then continues: 896+768 = 1664
 
     Actually I realize the overlap-save implementation in this RTL has an issue:
-    For segment 0, the buffer is only partially filled (896 out of 1024),
+    For segment 0, the buffer is only partially filled (1920 out of 2048),
     with zeros in positions 896-1023. The "overlap" that gets carried to
     segment 1 is those zeros, not actual signal data.
 
     A proper overlap-save would:
-    1. Fill the entire 1024-sample buffer for each segment
+    1. Fill the entire 2048-sample buffer for each segment
     2. The overlap region is the LAST 128 samples of the previous segment
 
     But this RTL only fills 896 samples per segment and relies on the
@@ -140,7 +140,7 @@ def generate_long_chirp_test():
     [768 new data samples at positions [128:895]] +
     [128 stale/zero samples at positions [896:1023]]
 
-    This is NOT standard overlap-save. It's a 1024-pt buffer but only
+    This is NOT standard overlap-save. It's a 2048-pt buffer but only
     896 positions are "active" for triggering, and positions 896-1023
     are never filled after init.
 
@@ -153,22 +153,16 @@ def generate_long_chirp_test():
     """
 
     # Parameters matching RTL
-    BUFFER_SIZE = 1024
+    BUFFER_SIZE = 2048
     OVERLAP_SAMPLES = 128
-    SEGMENT_ADVANCE = BUFFER_SIZE - OVERLAP_SAMPLES  # 896
+    SEGMENT_ADVANCE = BUFFER_SIZE - OVERLAP_SAMPLES  # 1920
-    LONG_SEGMENTS = 4
+    LONG_SEGMENTS = 2
 
-    # Total input samples needed:
+    # Total input samples needed: seg0 needs 1920, seg1 needs 1792 (3712 total).
-    # Segment 0: 896 samples (ptr goes from 0 to 896)
+    # chirp_complete triggers at chirp_samples_collected >= LONG_CHIRP_SAMPLES-1 (2999),
-    # Segment 1: 768 samples (ptr goes from 128 to 896)
+    # so the last segment may be truncated. We generate 3800 samples to be safe.
-    # Segment 2: 768 samples (ptr goes from 128 to 896)
-    # Segment 3: 768 samples (ptr goes from 128 to 896)
-    # Total: 896 + 3*768 = 896 + 2304 = 3200
-    # But chirp_complete triggers at chirp_samples_collected >= LONG_CHIRP_SAMPLES-1 = 2999
-    # So the last segment may be truncated.
-    # Let's generate 3072 input samples (to be safe, more than 3000).
 
-    TOTAL_SAMPLES = 3200  # More than enough for 4 segments
+    TOTAL_SAMPLES = 3800  # More than enough for 2 segments
 
     # Generate input signal: identifiable pattern per segment
     # Use a tone at different frequencies for each expected segment region
@@ -184,7 +178,7 @@ def generate_long_chirp_test():
         input_q.append(saturate(val_q, 16))
 
     # Generate per-segment reference chirps (just use known patterns)
-    # Each segment gets a different reference (1024 samples each)
+    # Each segment gets a different reference (2048 samples each)
     ref_segs_i = []
     ref_segs_q = []
     for seg in range(LONG_SEGMENTS):
@@ -202,7 +196,7 @@ def generate_long_chirp_test():
         ref_segs_q.append(ref_q)
 
     # Now simulate the RTL's overlap-save algorithm in Python
-    mf_chain = MatchedFilterChain(fft_size=1024)
+    mf_chain = MatchedFilterChain(fft_size=2048)
 
     # Simulate the buffer exactly as RTL does it
     input_buffer_i = [0] * BUFFER_SIZE
@@ -310,7 +304,7 @@ def generate_long_chirp_test():
         f.write('segment,bin,golden_i,golden_q\n')
         for seg in range(LONG_SEGMENTS):
             out_re, out_im = segment_results[seg]
-            for b in range(1024):
+            for b in range(2048):
                 f.write(f'{seg},{b},{out_re[b]},{out_im[b]}\n')
 
 
@@ -321,9 +315,9 @@ def generate_short_chirp_test():
     """
     Generate test data for single-segment short chirp.
 
-    Short chirp: 50 samples of data, zero-padded to 1024.
+    Short chirp: 50 samples of data, zero-padded to 2048.
     """
-    BUFFER_SIZE = 1024
+    BUFFER_SIZE = 2048
     SHORT_SAMPLES = 50
 
     # Generate 50-sample input
@@ -336,7 +330,7 @@ def generate_short_chirp_test():
         input_i.append(saturate(val_i, 16))
         input_q.append(saturate(val_q, 16))
 
-    # Zero-pad to 1024 (as RTL does in ST_ZERO_PAD)
+    # Zero-pad to 2048 (as RTL does in ST_ZERO_PAD)
     # Note: padding computed here for documentation; actual buffer uses buf_i/buf_q below
     _padded_i = list(input_i) + [0] * (BUFFER_SIZE - SHORT_SAMPLES)
     _padded_q = list(input_q) + [0] * (BUFFER_SIZE - SHORT_SAMPLES)
@@ -359,7 +353,7 @@ def generate_short_chirp_test():
             buf_i.append(0)
             buf_q.append(0)
 
-    # Reference chirp (1024 samples)
+    # Reference chirp (2048 samples)
     ref_i = []
     ref_q = []
     for n in range(BUFFER_SIZE):
@@ -370,7 +364,7 @@ def generate_short_chirp_test():
         ref_q.append(saturate(val_q, 16))
 
     # Process through MF chain
-    mf_chain = MatchedFilterChain(fft_size=1024)
+    mf_chain = MatchedFilterChain(fft_size=2048)
     out_re, out_im = mf_chain.process(buf_i, buf_q, ref_i, ref_q)
 
     # Write hex files
@@ -394,7 +388,7 @@ def generate_short_chirp_test():
     csv_path = os.path.join(out_dir, 'multiseg_short_golden.csv')
     with open(csv_path, 'w') as f:
         f.write('bin,golden_i,golden_q\n')
-        for b in range(1024):
+        for b in range(2048):
             f.write(f'{b},{out_re[b]},{out_im[b]}\n')
 
     return out_re, out_im
@@ -409,7 +403,7 @@ if __name__ == '__main__':
         # Find peak
         max_mag = 0
         peak_bin = 0
-        for b in range(1024):
+        for b in range(2048):
             mag = abs(out_re[b]) + abs(out_im[b])
             if mag > max_mag:
                 max_mag = mag
@@ -418,7 +412,7 @@ if __name__ == '__main__':
     short_re, short_im = generate_short_chirp_test()
     max_mag = 0
     peak_bin = 0
-    for b in range(1024):
+    for b in range(2048):
         mag = abs(short_re[b]) + abs(short_im[b])
         if mag > max_mag:
             max_mag = mag