From abde60dd7ee4b5d8c674bd89c333044241c0ec99 Mon Sep 17 00:00:00 2001
From: Jason <83615043+JJassonn69@users.noreply.github.com>
Date: Fri, 1 May 2026 18:53:24 +0545
Subject: [PATCH] =?UTF-8?q?docs(cfar):=20PR-M.4=20=E2=80=94=20note=20Doppl?=
 =?UTF-8?q?er-window=20dependency=20on=20CFAR=20alpha?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The CFAR threshold (alpha) lives in a Q4.4 host register and is loaded
from RP_DEF_CFAR_ALPHA / _SOFT at boot (3.0 / 1.5 in Q4.4). With PR-M.2
swapping the Doppler window from a non-canonical "Hamming-ish" LUT
(PSL=-33 dB) to Dolph-Chebyshev 60 dB (PSL=-60 dB), training-cell
contamination from off-Doppler sidelobes drops by 27 dB and the
effective Pfa at the shipped alpha drops accordingly.

This commit is documentation only — defaults are not changed pre-HW.

Two operating-point options for HW bring-up:
  (a) Hold alpha — get higher Pd at lower Pfa as a free win.
  (b) Lower alpha — recover original Pfa, get even higher Pd.

Recommended bring-up procedure recorded in cfar_ca.v header:
  1. Collect noise-only frames (no targets in dwell).
  2. Measure empirical Pfa at shipped alpha=3.0 / 1.5.
  3. If Pfa < 0.5 x design target, lower alpha; otherwise hold.

Opcodes 0x23 (RP_OP_CFAR_ALPHA) and 0x2D (RP_OP_CFAR_ALPHA_SOFT) let
the host adjust at runtime without firmware change.

Files:
  * cfar_ca.v — adds "Doppler-window dependency" block to the header
    after the existing "Threshold computation" block.
  * radar_params.vh — adds a note above RP_DEF_CFAR_ALPHA pointing at
    cfar_ca.v for the rationale.
---
 9_Firmware/9_2_FPGA/cfar_ca.v       | 23 +++++++++++++++++++++++
 9_Firmware/9_2_FPGA/radar_params.vh |  6 ++++++
 2 files changed, 29 insertions(+)

diff --git a/9_Firmware/9_2_FPGA/cfar_ca.v b/9_Firmware/9_2_FPGA/cfar_ca.v
index 02e22cb..321f41c 100644
--- a/9_Firmware/9_2_FPGA/cfar_ca.v
+++ b/9_Firmware/9_2_FPGA/cfar_ca.v
@@ -42,6 +42,29 @@
  *     alpha_fpga = alpha_statistical / 16 = 0.305 → Q4.4 ≈ 0x05
  *   Or host can set alpha per training cell if it accounts for count.
  *
+ * Doppler-window dependency (PR-M, 2026-05-01):
+ *   CFAR slides through RANGE within each Doppler-bin column, so the
+ *   training-cell statistics depend on what "noise" actually looks like
+ *   in a column — which includes Doppler-window sidelobe leakage from
+ *   strong returns at OTHER Doppler bins at the same range.
+ *
+ *   With the new Dolph-Chebyshev 60 dB window (vs the old "Hamming-ish"
+ *   LUT at -33 dB peak sidelobes), sidelobe leakage drops 27 dB. Training
+ *   cells are now closer to true thermal noise; effective Pfa at the
+ *   shipped α defaults (RP_DEF_CFAR_ALPHA=3.0, ALPHA_SOFT=1.5) drops
+ *   accordingly. Two operating-point choices for HW bring-up:
+ *
+ *     (a) Hold α — accept lower Pfa, get higher Pd as a free win.
+ *     (b) Lower α — recover original Pfa, get even higher Pd.
+ *
+ *   Defaults are NOT changed in this PR. Recommended bring-up procedure:
+ *     1. Collect noise-only frames (no targets in dwell).
+ *     2. Measure empirical Pfa at shipped α=3.0/1.5.
+ *     3. If Pfa < 0.5 × design target, lower α to spec; otherwise hold.
+ *
+ *   The opcodes 0x23 (RP_OP_CFAR_ALPHA) and 0x2D (RP_OP_CFAR_ALPHA_SOFT)
+ *   let the host adjust α at runtime without firmware change.
+ *
  * Edge handling:
  *   At range boundaries where the full window doesn't fit, only available
  *   training cells are used. The noise estimate naturally reduces, raising
diff --git a/9_Firmware/9_2_FPGA/radar_params.vh b/9_Firmware/9_2_FPGA/radar_params.vh
index 99c794a..60f05bc 100644
--- a/9_Firmware/9_2_FPGA/radar_params.vh
+++ b/9_Firmware/9_2_FPGA/radar_params.vh
@@ -229,6 +229,12 @@
 // ============================================================================
 // CFAR DEFAULTS
 // ============================================================================
+// alpha defaults below are calibrated for the Dolph-Chebyshev 60 dB Doppler
+// window (PR-M, 2026-05-01). With the new -60 dB sidelobes, training cells
+// suffer ~27 dB less leakage from strong off-Doppler returns than under the
+// previous "Hamming-ish" -33 dB LUT — effective Pfa at fixed alpha drops
+// accordingly. Re-measure during HW bring-up; opcode 0x23/0x2D adjusts at
+// runtime. See cfar_ca.v "Doppler-window dependency" comment for details.
 `define RP_DEF_CFAR_GUARD           2
 `define RP_DEF_CFAR_TRAIN           8
 `define RP_DEF_CFAR_ALPHA           8'h30   // 3.0 in Q4.4