Clarify func_wpfb_subband_scale_w().

libraries/dsp/wpfb/src/vhdl/wpfb_pkg.vhd

@@ -82,7 +82,8 @@ package wpfb_pkg is
   -- LOFAR2 subband filter
   -----------------------------------------------------------------------------
 
-  -- Can use guard_w = 1, because fil_backoff_w = 1 already provides sufficient input margin
+  -- Use guard_w = 1, instead of 2 to avoid overflow in first FFT stage,
+  -- because fil_backoff_w = 1 already provides sufficient FFT input margin.
 
   -- Fsub settings:
   -- . Settings used on LTS and DTS until at least March 2022
@@ -99,7 +100,7 @@ package wpfb_pkg is
                                                        true, false, true, 23, 18, 1, 24, 1, true, 54, 2, 195313,
                                                        c_fft_pipeline, c_fft_pipeline, c_fil_ppf_pipeline);
 
-  -- . Settings used in tb_tb_verify_pfb_wg with fft_out_dat_w = 19b, to preserve FFT processing gain of 4.5 bits
+  -- . Settings used in tb_tb_verify_pfb_wg with fft_out_dat_w = 19b, to preserve FFT processing gain of 5 bits
   --   - use stage_dat_w = 25 --> fil_out_dat_w = fft_in_dat_w = 24
   --   - with fft_out_dat_w = 19 --> stat_data_w = 2*19 + 18 = 56 b
   constant c_wpfb_lofar2_subbands_dts_19b : t_wpfb := (1, 1024, 0, 6,
@@ -117,10 +118,16 @@ package wpfb_pkg is
 
   -- The FFT output has more bits to be able to preserve the sensitivity of
   -- the processing gain of the FFT. The FFT has a processing gain of
-  -- sqrt(N_sub = N_fft / 2 = 512), so 4.5 bits. Therefore choose
-  -- fft_out_dat_w = fil_in_dat_w + 5 = 14 + 5 = 19b. Using fft_out_gain_w =
-  -- 1 compensates for the fil_backoff_w = 1 of the FIR filter. The
-  -- func_wpfb_subband_scale_w then thus returns 19 + 1 - (14 + 1) = 5 bits.
+  -- W_fft_proc = sqrt(N_fft = 1024), so 5 bits. Therefore choose
+  -- fft_out_dat_w = fil_in_dat_w + 5 = 14 + 5 = 19b. Using fft_out_gain_w
+  -- = 1 compensates for the fil_backoff_w = 1 of the FIR filter.
+  -- However, instead keep fft_out_dat_w = 18b to fit a 18x19 multiplier in
+  -- the SST. To preserve the sensitivity increase fft_out_gain_w by 1 at the
+  -- expense of loosing factor 2 (1 bit) in subband dynamic range. Therefore
+  -- fft_out_gain_w = 2 and the func_wpfb_subband_scale_w() then thus returns
+  -- (fft_out_dat_w + fft_out_gain_w) - (fil_in_dat_w + fil_backoff_w) =
+  -- (18 + 2) - (14 + 1) = 5 bits = W_fft_proc, to preserve the subband
+  -- sensitivity.
   function func_wpfb_subband_scale_w(wpfb : t_wpfb) return natural;
 
   -- The WPFB subband gain is the expected factor between subband amplitude
@@ -130,11 +137,12 @@ package wpfb_pkg is
   -- . DC gain of the FIR filter (= fir_filter_dc_gain ~= 1.0),
   -- . the FFT gain for a real input (= c_fft_real_input_gain_sine = 0.5) and
   -- . the extra bits to preserve the sensitivity of the FFT processing gain
-  --   (derived from wpfb).
+  --   W_fft_proc = 5b (derived from wpfb by func_wpfb_subband_scale_w()).
   -- For example:
   -- . func_wpfb_subband_gain() ~=  8 for c_wpfb_lofar2_subbands_lts_2021 and
   --                                  for c_wpfb_lofar2_subbands_dts_18b
   -- . func_wpfb_subband_gain() ~= 16 for c_wpfb_lofar2_subbands_dts_19b
+  --                                  for c_wpfb_lofar2_subbands_l2ts_18b
   function func_wpfb_subband_gain(wpfb : t_wpfb; fir_filter_dc_gain : real) return real;
 
   -- The expected WPFB SST level for subband amplitude A_sub and an integration