Subversion Repositories astron_wpfb

-------------------------------------------------------------------------------

-- Author: Harm Jan Pepping : pepping at astron.nl: 2012

-- Copyright (C) 2012

-- ASTRON (Netherlands Institute for Radio Astronomy) <http://www.astron.nl/>

-- P.O.Box 2, 7990 AA Dwingeloo, The Netherlands

--

-- This program is free software: you can redistribute it and/or modify

-- it under the terms of the GNU General Public License as published by

-- the Free Software Foundation, either version 3 of the License, or

-- (at your option) any later version.

--

-- This program is distributed in the hope that it will be useful,

-- but WITHOUT ANY WARRANTY; without even the implied warranty of

-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

-- GNU General Public License for more details.

--

-- You should have received a copy of the GNU General Public License

-- along with this program.  If not, see <http://www.gnu.org/licenses/>.

--

-------------------------------------------------------------------------------

library ieee, common_pkg_lib, astron_r2sdf_fft_lib, astron_wb_fft_lib, astron_filter_lib;

use IEEE.std_logic_1164.all;

use common_pkg_lib.common_pkg.all;

use astron_r2sdf_fft_lib.rTwoSDFPkg.all;

use astron_wb_fft_lib.fft_pkg.all;

use astron_filter_lib.fil_pkg.all;

package wpfb_pkg is

  -- Parameters for the (wideband) poly phase filter. 

  type t_wpfb is record

    -- General parameters for the wideband poly phase filter

    wb_factor         : natural;        -- = default 4, wideband factor

    nof_points        : natural;        -- = 1024, N point FFT (Also the number of subbands for the filter part)

    nof_chan          : natural;        -- = default 0, defines the number of channels (=time-multiplexed input signals): nof channels = 2**nof_chan     

    nof_wb_streams    : natural;        -- = 1, the number of parallel wideband streams. The filter coefficients are shared on every wb-stream.

    -- Parameters for the poly phase filter

    nof_taps          : natural;        -- = 16, the number of FIR taps per subband

    fil_backoff_w     : natural;        -- = 0, number of bits for input backoff to avoid output overflow

    fil_in_dat_w      : natural;        -- = 8, number of input bits

    fil_out_dat_w     : natural;        -- = 16, number of output bits

    coef_dat_w        : natural;        -- = 16, data width of the FIR coefficients

    -- Parameters for the FFT         

    use_reorder       : boolean;        -- = false for bit-reversed output, true for normal output

    use_fft_shift     : boolean;        -- = false for [0, pos, neg] bin frequencies order, true for [neg, 0, pos] bin frequencies order in case of complex input

    use_separate      : boolean;        -- = false for complex input, true for two real inputs

    fft_in_dat_w      : natural;        -- = 16, number of input bits

    fft_out_dat_w     : natural;        -- = 16, number of output bits >= (fil_in_dat_w=8) + log2(nof_points=1024)/2 = 13

    fft_out_gain_w    : natural;        -- = 0, output gain factor applied after the last stage output, before requantization to out_dat_w

    stage_dat_w       : natural;        -- = 18, number of bits that are used inter-stage

    guard_w           : natural;  -- = 2, guard used to avoid overflow in first FFT stage, compensated in last guard_w nof FFT stages. 

                                  --   on average the gain per stage is 2 so guard_w = 1, but the gain can be 1+sqrt(2) [Lyons section

                                  --   12.3.2], therefore use input guard_w = 2.

    guard_enable      : boolean;  -- = true when input needs guarding, false when input requires no guarding but scaling must be

                                  --   skipped at the last stage(s) compensate for input guard (used in wb fft with pipe fft section

                                  --   doing the input guard and par fft section doing the output compensation)

    -- Parameters for the statistics

    stat_data_w       : positive;       -- = 56

    stat_data_sz      : positive;       -- = 2

    nof_blk_per_sync  : natural;        -- = 800000, number of FFT output blocks per sync interval, used to pass on BSN

    -- Pipeline parameters for both poly phase filter and FFT. These are heritaged from the filter and fft libraries.  

    pft_pipeline      : t_fft_pipeline;     -- Pipeline settings for the pipelined FFT

    fft_pipeline      : t_fft_pipeline;     -- Pipeline settings for the parallel FFT

    fil_pipeline      : t_fil_ppf_pipeline; -- Pipeline settings for the filter units 

  end record;

  -----------------------------------------------------------------------------

  -- Apertif application specfic settings

  -----------------------------------------------------------------------------

  -- For reference Fsub, actual setting is done in the apertif_unb1_bn_filterbank design:

  -- * wb_factor        = 4      : wideband factor

  --   nof_points       = 1024   : N point FFT

  --   nof_chan         = 0      : nof channels = 2**nof_chan = 1

  --   nof_wb_streams   = 1      : 1 two real wb stream per WPFB, because the subband filterbank uses 2 independent instances of WPFB 

  -- * nof_taps         = 16     : number of FIR taps in the subband filterbank

  --   fil_backoff_w    = 1      : backoff input to fit temporary PFIR output overshoot that can occur even though DC gain is 1

  --   fil_in_dat_w     = 8      : ADC data width

  --   fil_out_dat_w    = 16     : = fft_in_dat_w

  --   coef_dat_w       = 16     : width of the subband FIR coefficients

  -- * use_reorder      = true   : must be true  for two real input FFT

  --   use_fft_shift    = false  : must be false for two real input FFT

  --   use_separate     = true   : must be true  for two real input FFT

  --   fft_in_dat_w     = 16     : = c_dsp_mult_w-guard_w = 18-2

  --   fft_out_dat_w    = 16     : subband data width in the transpose transport and at the BF input

  --   fft_out_gain_w   = 1      : compensate for divide by 2 in separate function for two real input FFT

  --   stage_dat_w      = 18     : = c_dsp_mult_w, number of bits that are used inter-stage

  --   guard_w          = 2      : must be 2 to avoid overflow in first FFT stage

  --   guard_enable     = true   : must be true to enable input guard_w

  -- * stat_data_w      = 56     : could be 52 = 2*16+1 - 1 + ceil_log2(781250)

  --                               . 2*fft_out_dat_w for product

  --                               . +1 for complex product

  --                               . -1 to skip double sign

  --                               . +ceil_log2(Nint) for accumlation bit growth

  --   stat_data_sz     = 2      : must be 2 to fit stat_data_w in two 32 bit words

  --   nof_blk_per_sync = 800000 : number of FFT output blocks per sync interval

  -- Fsub settings:

  -- . fil_backoff_w = 1 instead of 0 to avoid the overflow that occurs for WG with --ampl >= 119 and e.g. --sub 65, --chan 4,

  --   see svn -r 18800 log of node_apertif_unb1_bn_filterbank

  -- . fft_out_dat_w = 16 by internal dp_requantize will not overflow, so no need to use external dp_requantize with clipping

  -- . fft_out_gain_w = 1 instead of 0 to compensate for 1/2 in separate.

  constant c_wpfb_apertif_subbands : t_wpfb := (4, 1024, 0, 1,

                                                16, 1, 8, 16, 16,

                                                true, false, true, 16, 16, 1, c_dsp_mult_w, 2, true, 56, 2, 800000,

                                                c_fft_pipeline, c_fft_pipeline, c_fil_ppf_pipeline);

  -- For reference Fchan_x, actual setting is done in the apertif_unb1_correlator design:

  -- * wb_factor        = 1      : wideband factor

  --   nof_points       = 64     : N point FFT

  --   nof_chan         = 1      : nof channels = 2**nof_chan = 2 multiplex streams

  --   nof_wb_streams   = 12     : 12 complex streams per WPFB, that all share the FIR coefficients

  -- * nof_taps         = 8      : number of FIR taps in the channel filterbank

  --   fil_backoff_w    = 0      : backoff input to fit temporary PFIR output overshoot can occur even though DC gain is 1

  --   fil_in_dat_w     = 8      : keep at 8, also when Apertif BF outputs 6 bit beamlet data, because that is sign extended to 8b

  --   fil_out_dat_w    = 16     : = fft_in_dat_w

  --   coef_dat_w       = 9      : width of the channel FIR coefficients

  -- * use_reorder      = false  : use true to have [0, pos, neg] frequency bin order for complex input FFT

  --   use_fft_shift    = false  : use false to keep [0, pos, neg] frequency bin order

  --   use_separate     = false  : must be false for complex input FFT

  --   fft_in_dat_w     = 16     : = c_dsp_mult_w-guard_w = 18-2

  --   fft_out_dat_w    = 9      : to fit correlator input width

  --   fft_out_gain_w   = 0      : keep at 0 for complex input input FFT

  --   stage_dat_w      = 18     : = c_dsp_mult_w, number of bits that are used inter-stage

  --   guard_w          = 2      : must be 2 to avoid overflow in first FFT stage

  --   guard_enable     = true   : must be true to enable input guard_w

  -- * stat_data_w      = 56     : could be 32 = 2*9+1 - 1 + ceil_log2(781250/64):

  --                               . 2*fft_out_dat_w for product

  --                               . +1 for complex product

  --                               . -1 to skip double sign

  --                               . +ceil_log2(Nint) for accumlation bit growth

  --   stat_data_sz     = 2      : keep two 32b-word, even if stat_data_w could fit in one 32b-word

  --   nof_blk_per_sync = 12500  : = 800000/64, number of FFT output blocks per sync interval

  -- Fchan_x settings in node_apertif_unb1_correlator_processing.vhd:

  -- . fil_backoff_w = 0, because for the Fchan there appears no PFIR output overshoot in practise using WG data

  -- . use_reorder = false and use_fft_shift = false, because channel index bit flip and FFT shift are done in

  --   apertif_unb1_correlator_vis_offload

  -- . fft_out_dat_w = 18, because in there is a separate dp_requantize to get from 18b --> 9b in

  --   node_apertif_unb1_correlator_processing, this dp_requantize uses symmertical clipping.

  CONSTANT c_wpfb_apertif_channels : t_wpfb := (1, 64, 1, 12,

                                                8, 0, 8, 16, 9,

                                                false, false, false, 16, 18, 0, c_dsp_mult_w, 2, true, 56, 2, 12500,

                                                c_fft_pipeline, c_fft_pipeline, c_fil_ppf_pipeline);

  -- Fchan_sc3 settings:

  -- . Arts SC3 uses the Fchan fine channels from Apertif X. Therefore to allow commensal Arts SC3 the Apertif X

  --   will have to use use_reorder = true and use_fft_shift = true.

  -- . Arts SC4 at half Stokes rate, so with nof_blk_per_sync = 12500 and nof_points = 64, has same rate as

  --   Arts SC3. At full rate Arts SC4 would have nof_blk_per_sync = 25000 and nof_points = 32.

  -- . fft_out_dat_w = 9, because Arts SC3 uses the fine channels from Apertif X.

  constant c_wpfb_arts_channels_sc3 : t_wpfb := (1, 64, 1, 12,

                                                 8, 0, 8, 16, 9,

                                                 true, true, false, 16, 9, 0, c_dsp_mult_w, 2, true, 56, 2, 12500,

                                                 c_fft_pipeline, c_fft_pipeline, c_fil_ppf_pipeline);

  -- Fchan_sc4 settings in arts_unb1_sc4_processing.vhd svn -r 19337:

  -- . fft_out_dat_w = 9 for Arts SC3, but can be 12 to preserve more LSbit for SC4. However this is not necessary,

  --   because the 9b are already sufficient to maintain sensitivity

  -- . fft_out_gain_w = 2 to fit 2 more LSbits which is possible because fft_out_dat_w = 12. However if

  --   fft_out_dat_w = 9, then fft_out_gain_w must be 0 to avoid output overflow. Instead the factor 2**2

  --   then needs to be accommodated at the input of the subsequent IQUV, IAB or TAB processing.

  -- . Using fft_out_dat_w = 12 instead of 9 and fft_out_gain_w = 2 instead of 0 created 12 - 9 - 2 = 1 bit more

  --   dynamic range. Therefore it may not be necessary to use fine channel symmetrical clipping using an external

  --   dp_requantize, like in Apertif X.

  CONSTANT c_wpfb_arts_channels_sc4 : t_wpfb  := (1, 64, 1, 12,

                                                  8, 0, 8, 16, 9,

                                                  true, true, false, 16, 12, 2, c_dsp_mult_w, 2, true, 56, 2, 12500,

                                                  c_fft_pipeline, c_fft_pipeline, c_fil_ppf_pipeline);

  -- Conclusion:

  -- . To support fine channel offload to Arts SC3 the Apertif X settings will have to use use_reorder = true

  --   and use_fft_shift = true

  -- . It seems fine to keep the Arts SC4 settings fft_out_dat_w = 12 and fft_out_gain_w = 2 and no fine channel

  --   clipping.

  -- . Arts SC3 will use the same settings as Apertif X so fft_out_dat_w = 9 and fft_out_gain_w = 0 and fine 

  --   channel clipping. The input of the subsequent IQUV, IAB or TAB processing in arts_unb2b_sc3 may need to

  --   be shifted by fft_out_gain_w compared to how it is connected in Arts SC4.

  -- Estimate maximum number of blocks of latency between WPFB input and output

  function func_wpfb_maximum_sop_latency(wpfb : t_wpfb) return natural;

  function func_wpfb_set_nof_block_per_sync(wpfb : t_wpfb; nof_block_per_sync : NATURAL) return t_wpfb;

end package wpfb_pkg;

package body wpfb_pkg is

  function func_wpfb_maximum_sop_latency(wpfb : t_wpfb) return natural is

    constant c_nof_channels : natural := 2**wpfb.nof_chan;

    constant c_block_size   : natural := c_nof_channels * wpfb.nof_points / wpfb.wb_factor;

    constant c_block_dly    : natural := 10;

  begin

    -- The prefilter, pipelined FFT, pipelined reorder and the wideband separate reorder

    -- cause block latency.

    -- The parallel FFT has no block latency.

    -- The parallel FFT reorder is merely a rewiring and causes no latency.

    -- ==> This yields maximim 4 block latency

    -- ==> Add one extra block latency to round up

    -- Each block in the Wideband FFT also introduces about c_block_dly clock cycles of

    -- pipeline latency.

    -- ==> This yields maximum ( 5 * c_block_dly ) / c_block_size of block latency

    return 4 + 1 + (5 * c_block_dly) / c_block_size;

  end func_wpfb_maximum_sop_latency;

  -- Overwrite nof_block_per_sync field in wpfb (typically for faster simulation)

  function func_wpfb_set_nof_block_per_sync(wpfb : t_wpfb; nof_block_per_sync : NATURAL) return t_wpfb is

    variable v_wpfb : t_wpfb;

  begin

    v_wpfb := wpfb;

    v_wpfb.nof_blk_per_sync := nof_block_per_sync;

    return v_wpfb;

  end func_wpfb_set_nof_block_per_sync;

end wpfb_pkg;