From bf63d64533015ff4eb95d70b667ba739821c3d0e Mon Sep 17 00:00:00 2001
From: Jason <83615043+JJassonn69@users.noreply.github.com>
Date: Thu, 30 Apr 2026 10:08:34 +0545
Subject: [PATCH] AUDIT-S17: document fir_lowpass +4.96 dB DC gain and
 CIC-droop comp
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The coefficient ROM has a deliberate positive DC pre-emphasis. Sum of
32 signed coefficients = 231,944; with the output slice at
accumulator[34:17] (effective Q17), DC gain = 231944 / 2^17 = 1.7696
= +4.96 dB. Bit-exact against the in-header golden-model line
(DC=5000 → 8847).

The +4.96 dB pre-emphasis compensates the upstream 4-stage CIC's
~3-4 dB passband droop. Without this note in the header, a future
engineer rebuilding the filter from a clean FIR design tool would
silently lose the pre-emphasis; AGC/saturation budgets in downstream
stages must also account for the +4.96 dB rather than assume 0 dB.

Audit's original "+7 dB" estimate was directionally correct but
quantitatively wrong (no Q-format reconciles to +7 dB; Q15 → +17 dB,
Q16 → +11 dB, Q17 → +4.96 dB). Documented at the verified +4.96 dB.

No coefficient or RTL change. Verified: full FPGA regression
41/41 PASS, 0 lint errors (FIR Lowpass: 13 checks PASS).
---
 9_Firmware/9_2_FPGA/fir_lowpass.v | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/9_Firmware/9_2_FPGA/fir_lowpass.v b/9_Firmware/9_2_FPGA/fir_lowpass.v
index 7351249..cc35e9d 100644
--- a/9_Firmware/9_2_FPGA/fir_lowpass.v
+++ b/9_Firmware/9_2_FPGA/fir_lowpass.v
@@ -40,6 +40,26 @@
 // output bit-slice are unchanged from the unfolded design (compare against
 // ±2^(ACCUM_WIDTH-2) = ±2^34, slice [ACCUM_WIDTH-2 : DATA_WIDTH-1] =
 // [34:17]) so downstream signal levels and headroom stay the same.
+//
+// DC gain & filter shape (AUDIT-S17): the coefficient ROM has a deliberate
+// positive DC pre-emphasis. Sum of 32 signed coefficients = 231,944. With
+// the output slice taken at accumulator[34:17], effective Q-format is Q17,
+// so DC gain = 231944 / 2^17 = 1.7696 = +4.96 dB. This is bit-exact against
+// the in-line golden-model line above (DC=5000 in → 8847 out:
+// 231944 × 5000 = 1,159,720,000; >>17 = 8847).
+//
+// The +4.96 dB pre-emphasis compensates CIC droop: the upstream 4-stage
+// CIC at decimation factor 4 has ~3-4 dB of passband droop near Nyquist,
+// partially offset by this FIR's positive DC gain so the cascade response
+// is flatter than the CIC alone. Operational implication: AGC and
+// saturation budgets in downstream stages (DDC → CIC → FIR → MF) must
+// account for the +4.96 dB FIR gain — a clean 0 dB FIR assumption would
+// under-budget headroom by ~5 dB.
+//
+// Coefficients are intentionally NOT regenerated from a clean FIR design
+// tool; they are kept bit-exact with the unfolded predecessor so the
+// existing golden-model test stays valid. Touching them would invalidate
+// that contract and would silently shift downstream signal levels.
 // ============================================================================
 
 module fir_lowpass_parallel_enhanced (