Subversion Repositories dp_pkg

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

--

-- Copyright (C) 2010

-- 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;

USE IEEE.STD_LOGIC_1164.ALL;

USE IEEE.numeric_std.ALL;

USE common_pkg_lib.common_pkg.ALL;

PACKAGE dp_stream_pkg Is

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

  -- General DP stream record defintion

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

  -- Remarks:

  -- * Choose smallest maximum SOSI slv lengths that fit all use cases, because unconstrained record fields slv is not allowed

  -- * The large SOSI data field width of 256b has some disadvantages:

  --   . about 10% extra simulation time and PC memory usage compared to 72b (measured using tb_unb_tse_board)

  --   . a 256b number has 64 hex digits in the Wave window which is awkward because of the leading zeros when typically

  --     only 32b are used, fortunately integer representation still works OK (except 0 which is shown as blank).

  --   However the alternatives are not attractive, because they affect the implementation of the streaming

  --   components that use the SOSI record. Alternatives are e.g.:

  --   . define an extra long SOSI data field ldata[255:0] in addition to the existing data[71:0] field

  --   . use the array of SOSI records to contain wider data, all with the same SOSI control field values

  --   . define another similar SOSI record with data[255:0].

  --   Therefore define data width as 256b, because the disadvantages are acceptable and the benefit is great, because all

  --   streaming components can remain as they are.

  -- * Added sync and bsn to SOSI to have timestamp information with the data

  -- * Added re and im to SOSI to support complex data for DSP

  -- * The sosi fields can be labeled in diffent groups: ctrl, info and data as shown in comment at the t_dp_sosi definition.

  --   This grouping is useful for functions that operate on a t_dp_sosi signal.

  -- * The info fields are valid at the sop or at the eop, but typically they hold their last active value to avoid unnessary

  --   toggling and to ease viewing in the wave window.

  CONSTANT c_dp_stream_bsn_w      : NATURAL :=  64;  -- 64 is sufficient to count blocks of data for years

  CONSTANT c_dp_stream_data_w     : NATURAL := 768;  -- 72 is sufficient for max word 8 * 9-bit. 576 supports half rate DDR4 bus data width. The current 768 is enough for wide single clock SLVs (e.g. headers)

  CONSTANT c_dp_stream_dsp_data_w : NATURAL :=  64;  -- 64 is sufficient for DSP data, including complex power accumulates

  CONSTANT c_dp_stream_empty_w    : NATURAL :=  16;  --  8 is sufficient for max 256 symbols per data word, still use 16 bit to be able to count c_dp_stream_data_w in bits

  CONSTANT c_dp_stream_channel_w  : NATURAL :=  32;  -- 32 is sufficient for several levels of hierarchy in mapping types of streams on to channels 

  CONSTANT c_dp_stream_error_w    : NATURAL :=  32;  -- 32 is sufficient for several levels of hierarchy in mapping error numbers, e.g. 32 different one-hot encoded errors, bit [0] = 0 = OK

  CONSTANT c_dp_stream_ok         : NATURAL := 0;  -- SOSI err field OK value

  CONSTANT c_dp_stream_err        : NATURAL := 1;  -- SOSI err field error value /= OK

  CONSTANT c_dp_stream_rl         : NATURAL := 1;  -- SISO default data path stream ready latency RL = 1

  TYPE t_dp_siso IS RECORD  -- Source In or Sink Out

    ready    : STD_LOGIC;   -- fine cycle based flow control using ready latency RL >= 0

    xon      : STD_LOGIC;   -- coarse typically block based flow control using xon/xoff

  END RECORD;

  TYPE t_dp_sosi IS RECORD  -- Source Out or Sink In

    sync     : STD_LOGIC;                                           -- ctrl

    bsn      : STD_LOGIC_VECTOR(c_dp_stream_bsn_w-1 DOWNTO 0);      -- info at sop      (block sequence number)

    data     : STD_LOGIC_VECTOR(c_dp_stream_data_w-1 DOWNTO 0);     -- data

    re       : STD_LOGIC_VECTOR(c_dp_stream_dsp_data_w-1 DOWNTO 0); -- data

    im       : STD_LOGIC_VECTOR(c_dp_stream_dsp_data_w-1 DOWNTO 0); -- data

    valid    : STD_LOGIC;                                           -- ctrl

    sop      : STD_LOGIC;                                           -- ctrl

    eop      : STD_LOGIC;                                           -- ctrl

    empty    : STD_LOGIC_VECTOR(c_dp_stream_empty_w-1 DOWNTO 0);    -- info at eop

    channel  : STD_LOGIC_VECTOR(c_dp_stream_channel_w-1 DOWNTO 0);  -- info at sop

    err      : STD_LOGIC_VECTOR(c_dp_stream_error_w-1 DOWNTO 0);    -- info at eop (name field 'err' to avoid the 'error' keyword)

  END RECORD;

  -- Initialise signal declarations with c_dp_stream_rst/rdy to ease the interpretation of slv fields with unused bits

  CONSTANT c_dp_siso_rst   : t_dp_siso := ('0', '0');

  CONSTANT c_dp_siso_x     : t_dp_siso := ('X', 'X');

  CONSTANT c_dp_siso_hold  : t_dp_siso := ('0', '1');

  CONSTANT c_dp_siso_rdy   : t_dp_siso := ('1', '1');

  CONSTANT c_dp_siso_flush : t_dp_siso := ('1', '0');

  CONSTANT c_dp_sosi_rst   : t_dp_sosi := ('0', (OTHERS=>'0'), (OTHERS=>'0'), (OTHERS=>'0'), (OTHERS=>'0'), '0', '0', '0', (OTHERS=>'0'), (OTHERS=>'0'), (OTHERS=>'0'));

  CONSTANT c_dp_sosi_x     : t_dp_sosi := ('X', (OTHERS=>'X'), (OTHERS=>'X'), (OTHERS=>'X'), (OTHERS=>'X'), 'X', 'X', 'X', (OTHERS=>'X'), (OTHERS=>'X'), (OTHERS=>'X'));

  -- Use integers instead of slv for monitoring purposes (integer range limited to 31 bit plus sign bit)

  TYPE t_dp_sosi_integer IS RECORD

    sync     : STD_LOGIC;

    bsn      : NATURAL;

    data     : INTEGER;

    re       : INTEGER;

    im       : INTEGER;

    valid    : STD_LOGIC;

    sop      : STD_LOGIC;

    eop      : STD_LOGIC;

    empty    : NATURAL;

    channel  : NATURAL;

    err      : NATURAL;

  END RECORD;

  -- Use unsigned instead of slv for monitoring purposes beyond the integer range of t_dp_sosi_integer

  TYPE t_dp_sosi_unsigned IS RECORD

    sync     : STD_LOGIC;

    bsn      : UNSIGNED(c_dp_stream_bsn_w-1 DOWNTO 0);

    data     : UNSIGNED(c_dp_stream_data_w-1 DOWNTO 0);

    re       : UNSIGNED(c_dp_stream_dsp_data_w-1 DOWNTO 0);

    im       : UNSIGNED(c_dp_stream_dsp_data_w-1 DOWNTO 0);

    valid    : STD_LOGIC;

    sop      : STD_LOGIC;

    eop      : STD_LOGIC;

    empty    : UNSIGNED(c_dp_stream_empty_w-1 DOWNTO 0);

    channel  : UNSIGNED(c_dp_stream_channel_w-1 DOWNTO 0);

    err      : UNSIGNED(c_dp_stream_error_w-1 DOWNTO 0);

  END RECORD;

  CONSTANT c_dp_sosi_unsigned_rst  : t_dp_sosi_unsigned := ('0', (OTHERS=>'0'), (OTHERS=>'0'), (OTHERS=>'0'), (OTHERS=>'0'), '0', '0', '0', (OTHERS=>'0'), (OTHERS=>'0'), (OTHERS=>'0'));

  CONSTANT c_dp_sosi_unsigned_ones : t_dp_sosi_unsigned := ('1',

                                                            TO_UNSIGNED(1, c_dp_stream_bsn_w),

                                                            TO_UNSIGNED(1, c_dp_stream_data_w),

                                                            TO_UNSIGNED(1, c_dp_stream_dsp_data_w),

                                                            TO_UNSIGNED(1, c_dp_stream_dsp_data_w),

                                                            '1', '1', '1',

                                                            TO_UNSIGNED(1, c_dp_stream_empty_w),

                                                            TO_UNSIGNED(1, c_dp_stream_channel_w),

                                                            TO_UNSIGNED(1, c_dp_stream_error_w));

  -- Use boolean to define whether a t_dp_siso, t_dp_sosi field is used ('1') or not ('0')

  TYPE t_dp_siso_sl IS RECORD

    ready    : STD_LOGIC;

    xon      : STD_LOGIC;

  END RECORD;

  TYPE t_dp_sosi_sl IS RECORD

    sync     : STD_LOGIC;

    bsn      : STD_LOGIC;

    data     : STD_LOGIC;

    re       : STD_LOGIC;

    im       : STD_LOGIC;

    valid    : STD_LOGIC;

    sop      : STD_LOGIC;

    eop      : STD_LOGIC;

    empty    : STD_LOGIC;

    channel  : STD_LOGIC;

    err      : STD_LOGIC;

  END RECORD;

  CONSTANT c_dp_siso_sl_rst  : t_dp_siso_sl := ('0', '0');

  CONSTANT c_dp_siso_sl_ones : t_dp_siso_sl := ('1', '1');

  CONSTANT c_dp_sosi_sl_rst  : t_dp_sosi_sl := ('0', '0', '0', '0', '0', '0', '0', '0', '0', '0', '0');

  CONSTANT c_dp_sosi_sl_ones : t_dp_sosi_sl := ('1', '1', '1', '1', '1', '1', '1', '1', '1', '1', '1');

  -- Multi port or multi register array for DP stream records

  TYPE t_dp_siso_arr IS ARRAY (INTEGER RANGE <>) OF t_dp_siso;

  TYPE t_dp_sosi_arr IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi;

  TYPE t_dp_sosi_integer_arr  IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_integer;

  TYPE t_dp_sosi_unsigned_arr IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_unsigned;

  TYPE t_dp_siso_sl_arr IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_sl;

  TYPE t_dp_sosi_sl_arr IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_sl;

  -- Multi port or multi register slv arrays for DP stream records fields

  TYPE t_dp_bsn_slv_arr      IS ARRAY (INTEGER RANGE <>) OF STD_LOGIC_VECTOR(c_dp_stream_bsn_w-1 DOWNTO 0);

  TYPE t_dp_data_slv_arr     IS ARRAY (INTEGER RANGE <>) OF STD_LOGIC_VECTOR(c_dp_stream_data_w-1 DOWNTO 0);

  TYPE t_dp_dsp_data_slv_arr IS ARRAY (INTEGER RANGE <>) OF STD_LOGIC_VECTOR(c_dp_stream_dsp_data_w-1 DOWNTO 0);

  TYPE t_dp_empty_slv_arr    IS ARRAY (INTEGER RANGE <>) OF STD_LOGIC_VECTOR(c_dp_stream_empty_w-1 DOWNTO 0);

  TYPE t_dp_channel_slv_arr  IS ARRAY (INTEGER RANGE <>) OF STD_LOGIC_VECTOR(c_dp_stream_channel_w-1 DOWNTO 0);

  TYPE t_dp_error_slv_arr    IS ARRAY (INTEGER RANGE <>) OF STD_LOGIC_VECTOR(c_dp_stream_error_w-1 DOWNTO 0);

  -- Multi-dimemsion array types with fixed LS-dimension

  TYPE t_dp_siso_2arr_1 IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_arr(0 DOWNTO 0);

  TYPE t_dp_sosi_2arr_1 IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(0 DOWNTO 0);

  -- . 2 dimensional array with 2 fixed LS sosi/siso interfaces (dp_split, dp_concat)

  TYPE t_dp_siso_2arr_2 IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_arr(1 DOWNTO 0);

  TYPE t_dp_sosi_2arr_2 IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(1 DOWNTO 0);

  TYPE t_dp_siso_2arr_3 IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_arr(2 DOWNTO 0);

  TYPE t_dp_sosi_2arr_3 IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(2 DOWNTO 0);

  TYPE t_dp_siso_2arr_4 IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_arr(3 DOWNTO 0);

  TYPE t_dp_sosi_2arr_4 IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(3 DOWNTO 0);

  TYPE t_dp_siso_2arr_8 IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_arr(7 DOWNTO 0);

  TYPE t_dp_sosi_2arr_8 IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(7 DOWNTO 0);

  TYPE t_dp_siso_2arr_9 IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_arr(8 DOWNTO 0);

  TYPE t_dp_sosi_2arr_9 IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(8 DOWNTO 0);

  TYPE t_dp_siso_2arr_12 IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_arr(11 DOWNTO 0);

  TYPE t_dp_sosi_2arr_12 IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(11 DOWNTO 0);

  TYPE t_dp_siso_3arr_4_2 IS ARRAY (INTEGER RANGE <>) OF t_dp_siso_2arr_2(3 DOWNTO 0);

  TYPE t_dp_sosi_3arr_4_2 IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_2arr_2(3 DOWNTO 0);

  -- 2-dimensional streaming array type:

  -- Note:

  --   This t_*_mat is less useful then a t_*_2arr array of arrays, because assignments can only be done per element (i.e. not per row). However for t_*_2arr

  --   the arrays dimension must be fixed, so these t_*_2arr types are application dependent and need to be defined where used. 

  TYPE t_dp_siso_mat IS ARRAY (INTEGER RANGE <>, INTEGER RANGE <>) OF t_dp_siso;

  TYPE t_dp_sosi_mat IS ARRAY (INTEGER RANGE <>, INTEGER RANGE <>) OF t_dp_sosi;

  -- Check sosi.valid against siso.ready

  PROCEDURE proc_dp_siso_alert(CONSTANT c_ready_latency : IN    NATURAL;

                               SIGNAL   clk             : IN    STD_LOGIC;

                               SIGNAL   sosi            : IN    t_dp_sosi;

                               SIGNAL   siso            : IN    t_dp_siso;

                               SIGNAL   ready_reg       : INOUT STD_LOGIC_VECTOR);

  -- Default RL=1

  PROCEDURE proc_dp_siso_alert(SIGNAL   clk             : IN    STD_LOGIC;

                               SIGNAL   sosi            : IN    t_dp_sosi;

                               SIGNAL   siso            : IN    t_dp_siso;

                               SIGNAL   ready_reg       : INOUT STD_LOGIC_VECTOR);

  -- SOSI/SISO array version

  PROCEDURE proc_dp_siso_alert(CONSTANT c_ready_latency : IN    NATURAL;

                               SIGNAL   clk             : IN    STD_LOGIC;

                               SIGNAL   sosi_arr        : IN    t_dp_sosi_arr;

                               SIGNAL   siso_arr        : IN    t_dp_siso_arr;

                               SIGNAL   ready_reg       : INOUT STD_LOGIC_VECTOR);

  -- SOSI/SISO array version with RL=1

  PROCEDURE proc_dp_siso_alert(SIGNAL   clk             : IN    STD_LOGIC;

                               SIGNAL   sosi_arr        : IN    t_dp_sosi_arr;

                               SIGNAL   siso_arr        : IN    t_dp_siso_arr;

                               SIGNAL   ready_reg       : INOUT STD_LOGIC_VECTOR);

  -- Resize functions to fit an integer or an SLV in the corresponding t_dp_sosi field width

  -- . Use these functions to assign sosi data TO a record field

  -- . Use the range selection [n-1 DOWNTO 0] to assign sosi data FROM a record field to an slv

  -- . The unused sosi data field bits could remain undefined 'X', because the unused bits in the fields are not used at all. 

  --   Typically the sosi data are treated as unsigned in the record field, so extended with '0'. However for interpretating

  --   signed data in the simulation wave window it is easier to use sign extension in the record field. Therefore TO_DP_SDATA

  --   and RESIZE_DP_SDATA are defined as well.

  FUNCTION TO_DP_BSN(     n : NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION TO_DP_DATA(    n : INTEGER) RETURN STD_LOGIC_VECTOR;  -- use integer to support 32 bit range, so -1 = 0xFFFFFFFF = +2**32-1

  FUNCTION TO_DP_SDATA(   n : INTEGER) RETURN STD_LOGIC_VECTOR;  -- use integer to support 32 bit range and signed

  FUNCTION TO_DP_UDATA(   n : INTEGER) RETURN STD_LOGIC_VECTOR;  -- alias of TO_DP_DATA()

  FUNCTION TO_DP_DSP_DATA(n : INTEGER) RETURN STD_LOGIC_VECTOR;  -- for re and im fields, signed data

  FUNCTION TO_DP_DSP_UDATA(n: INTEGER) RETURN STD_LOGIC_VECTOR;  -- for re and im fields, unsigned data (useful to carry indices)

  FUNCTION TO_DP_EMPTY(   n : NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION TO_DP_CHANNEL( n : NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION TO_DP_ERROR(   n : NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION RESIZE_DP_BSN(     vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;

  FUNCTION RESIZE_DP_DATA(    vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;  -- set unused MSBits to '0'

  FUNCTION RESIZE_DP_SDATA(   vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;  -- sign extend unused MSBits

  FUNCTION RESIZE_DP_XDATA(   vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;  -- set unused MSBits to 'X'

  FUNCTION RESIZE_DP_DSP_DATA(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;  -- sign extend unused MSBits of re and im fields

  FUNCTION RESIZE_DP_EMPTY(   vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;

  FUNCTION RESIZE_DP_CHANNEL( vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;

  FUNCTION RESIZE_DP_ERROR(   vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;

  FUNCTION INCR_DP_DATA(    vec : STD_LOGIC_VECTOR; dec : INTEGER; w : NATURAL) RETURN STD_LOGIC_VECTOR;  -- unsigned vec(w-1:0) + dec

  FUNCTION INCR_DP_SDATA(   vec : STD_LOGIC_VECTOR; dec : INTEGER; w : NATURAL) RETURN STD_LOGIC_VECTOR;  --   signed vec(w-1:0) + dec

  FUNCTION INCR_DP_DSP_DATA(vec : STD_LOGIC_VECTOR; dec : INTEGER; w : NATURAL) RETURN STD_LOGIC_VECTOR;  --   signed vec(w-1:0) + dec

  FUNCTION REPLICATE_DP_DATA(  seq  : STD_LOGIC_VECTOR                 ) RETURN STD_LOGIC_VECTOR;  -- replicate seq as often as fits in c_dp_stream_data_w

  FUNCTION UNREPLICATE_DP_DATA(data : STD_LOGIC_VECTOR; seq_w : NATURAL) RETURN STD_LOGIC_VECTOR;  -- unreplicate data to width seq_w, return low seq_w bits and set mismatch MSbits bits to '1'

  FUNCTION TO_DP_SOSI_UNSIGNED(sync, valid, sop, eop : STD_LOGIC; bsn, data, re, im, empty, channel, err : UNSIGNED) RETURN t_dp_sosi_unsigned;

  -- Keep part of head data and combine part of tail data, use the other sosi from head_sosi

  FUNCTION func_dp_data_shift_first(head_sosi, tail_sosi : t_dp_sosi; symbol_w, nof_symbols_per_data, nof_symbols_from_tail              : NATURAL) RETURN t_dp_sosi;

  -- Shift and combine part of previous data and this data, use the other sosi from prev_sosi

  FUNCTION func_dp_data_shift(      prev_sosi, this_sosi : t_dp_sosi; symbol_w, nof_symbols_per_data, nof_symbols_from_this              : NATURAL) RETURN t_dp_sosi;

  -- Shift part of tail data and account for input empty

  FUNCTION func_dp_data_shift_last(            tail_sosi : t_dp_sosi; symbol_w, nof_symbols_per_data, nof_symbols_from_tail, input_empty : NATURAL) RETURN t_dp_sosi;

  -- Determine resulting empty if two streams are concatenated or split

  FUNCTION func_dp_empty_concat(head_empty, tail_empty : STD_LOGIC_VECTOR; nof_symbols_per_data : NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION func_dp_empty_split(input_empty, head_empty : STD_LOGIC_VECTOR; nof_symbols_per_data : NATURAL) RETURN STD_LOGIC_VECTOR;

  -- Multiplex the t_dp_sosi_arr based on the valid, assuming that at most one input is active valid.

  FUNCTION func_dp_sosi_arr_mux(dp : t_dp_sosi_arr) RETURN t_dp_sosi;

  -- Determine the combined logical value of corresponding STD_LOGIC fields in t_dp_*_arr (for all elements or only for the mask[]='1' elements)

  FUNCTION func_dp_stream_arr_and(dp : t_dp_siso_arr; mask : STD_LOGIC_VECTOR; str : STRING) RETURN STD_LOGIC;

  FUNCTION func_dp_stream_arr_and(dp : t_dp_sosi_arr; mask : STD_LOGIC_VECTOR; str : STRING) RETURN STD_LOGIC;

  FUNCTION func_dp_stream_arr_and(dp : t_dp_siso_arr;                          str : STRING) RETURN STD_LOGIC;

  FUNCTION func_dp_stream_arr_and(dp : t_dp_sosi_arr;                          str : STRING) RETURN STD_LOGIC;

  FUNCTION func_dp_stream_arr_or( dp : t_dp_siso_arr; mask : STD_LOGIC_VECTOR; str : STRING) RETURN STD_LOGIC;

  FUNCTION func_dp_stream_arr_or( dp : t_dp_sosi_arr; mask : STD_LOGIC_VECTOR; str : STRING) RETURN STD_LOGIC;

  FUNCTION func_dp_stream_arr_or( dp : t_dp_siso_arr;                          str : STRING) RETURN STD_LOGIC;

  FUNCTION func_dp_stream_arr_or( dp : t_dp_sosi_arr;                          str : STRING) RETURN STD_LOGIC;

  -- Functions to set or get a STD_LOGIC field as a STD_LOGIC_VECTOR to or from an siso or an sosi array

  FUNCTION func_dp_stream_arr_set(dp : t_dp_siso_arr; slv : STD_LOGIC_VECTOR; str : STRING) RETURN t_dp_siso_arr;

  FUNCTION func_dp_stream_arr_set(dp : t_dp_sosi_arr; slv : STD_LOGIC_VECTOR; str : STRING) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_set(dp : t_dp_siso_arr; sl  : STD_LOGIC;        str : STRING) RETURN t_dp_siso_arr;

  FUNCTION func_dp_stream_arr_set(dp : t_dp_sosi_arr; sl  : STD_LOGIC;        str : STRING) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_get(dp : t_dp_siso_arr;                         str : STRING) RETURN STD_LOGIC_VECTOR;

  FUNCTION func_dp_stream_arr_get(dp : t_dp_sosi_arr;                         str : STRING) RETURN STD_LOGIC_VECTOR;

  -- Functions to select elements from two siso or two sosi arrays (sel[] = '1' selects a, sel[] = '0' selects b)

  FUNCTION func_dp_stream_arr_select(sel : STD_LOGIC_VECTOR; a,                 b : t_dp_siso)     RETURN t_dp_siso_arr;

  FUNCTION func_dp_stream_arr_select(sel : STD_LOGIC_VECTOR; a,                 b : t_dp_sosi)     RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_select(sel : STD_LOGIC_VECTOR; a : t_dp_siso_arr; b : t_dp_siso)     RETURN t_dp_siso_arr;

  FUNCTION func_dp_stream_arr_select(sel : STD_LOGIC_VECTOR; a : t_dp_sosi_arr; b : t_dp_sosi)     RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_select(sel : STD_LOGIC_VECTOR; a : t_dp_siso;     b : t_dp_siso_arr) RETURN t_dp_siso_arr;

  FUNCTION func_dp_stream_arr_select(sel : STD_LOGIC_VECTOR; a : t_dp_sosi;     b : t_dp_sosi_arr) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_select(sel : STD_LOGIC_VECTOR; a,                 b : t_dp_siso_arr) RETURN t_dp_siso_arr;

  FUNCTION func_dp_stream_arr_select(sel : STD_LOGIC_VECTOR; a,                 b : t_dp_sosi_arr) RETURN t_dp_sosi_arr;

  -- Fix reversed buses due to connecting TO to DOWNTO range arrays. 

  FUNCTION func_dp_stream_arr_reverse_range(in_arr : t_dp_sosi_arr) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_reverse_range(in_arr : t_dp_siso_arr) RETURN t_dp_siso_arr;

  -- Functions to combinatorially hold the data fields and to set or reset the control fields in an sosi array

  FUNCTION func_dp_stream_arr_combine_data_info_ctrl(dp : t_dp_sosi_arr; info, ctrl : t_dp_sosi) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_set_info(              dp : t_dp_sosi_arr; info       : t_dp_sosi) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_set_control(           dp : t_dp_sosi_arr;       ctrl : t_dp_sosi) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_arr_reset_control(         dp : t_dp_sosi_arr                        ) RETURN t_dp_sosi_arr;

  -- Reset sosi ctrl and preserve the sosi data (to avoid unnecessary data toggling and to ease data view in Wave window)

  FUNCTION func_dp_stream_reset_control(dp : t_dp_sosi) RETURN t_dp_sosi;

  -- Functions to combinatorially determine the maximum and minimum sosi bsn[w-1:0] value in the sosi array (for all elements or only for the mask[]='1' elements)

  FUNCTION func_dp_stream_arr_bsn_max(dp : t_dp_sosi_arr; mask : STD_LOGIC_VECTOR; w : NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION func_dp_stream_arr_bsn_max(dp : t_dp_sosi_arr;                          w : NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION func_dp_stream_arr_bsn_min(dp : t_dp_sosi_arr; mask : STD_LOGIC_VECTOR; w : NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION func_dp_stream_arr_bsn_min(dp : t_dp_sosi_arr;                          w : NATURAL) RETURN STD_LOGIC_VECTOR;

  -- Function to copy the BSN of one valid stream to all output streams. 

  FUNCTION func_dp_stream_arr_copy_valid_bsn(dp : t_dp_sosi_arr; mask : STD_LOGIC_VECTOR) RETURN t_dp_sosi_arr;

  -- Functions to combinatorially handle channels

  -- Note that the *_select and *_remove function are equivalent to dp_demux with g_combined=TRUE

  FUNCTION func_dp_stream_channel_set   (st_sosi : t_dp_sosi; ch : NATURAL) RETURN t_dp_sosi;  -- select channel nr, add the channel field

  FUNCTION func_dp_stream_channel_select(st_sosi : t_dp_sosi; ch : NATURAL) RETURN t_dp_sosi;  -- select channel nr, skip the channel field

  FUNCTION func_dp_stream_channel_remove(st_sosi : t_dp_sosi; ch : NATURAL) RETURN t_dp_sosi;  -- skip channel nr

  -- Functions to combinatorially handle the error field

  FUNCTION func_dp_stream_error_set(st_sosi : t_dp_sosi; n : NATURAL) RETURN t_dp_sosi;  -- force err = 0, is OK

  -- Functions to combinatorially handle the BSN field

  FUNCTION func_dp_stream_bsn_set(st_sosi : t_dp_sosi; bsn : STD_LOGIC_VECTOR) RETURN t_dp_sosi;

  -- Functions to combine sosi fields

  FUNCTION func_dp_stream_combine_info_and_data(info, data : t_dp_sosi) RETURN t_dp_sosi;

  -- Functions to convert sosi fields

  FUNCTION func_dp_stream_slv_to_integer(slv_sosi : t_dp_sosi; w : NATURAL) RETURN t_dp_sosi_integer;

  -- Functions to set the DATA, RE and IM field in a stream.

  FUNCTION func_dp_stream_set_data(dp : t_dp_sosi;     slv : STD_LOGIC_VECTOR; str : STRING                         ) RETURN t_dp_sosi;

  FUNCTION func_dp_stream_set_data(dp : t_dp_sosi_arr; slv : STD_LOGIC_VECTOR; str : STRING                         ) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_set_data(dp : t_dp_sosi_arr; slv : STD_LOGIC_VECTOR; str : STRING; mask : STD_LOGIC_VECTOR) RETURN t_dp_sosi_arr;

   -- Functions to rewire between concatenated sosi.data and concatenated sosi.re,im

   -- . data_order_im_re defines the concatenation order data = im&re or re&im

   -- . nof_data defines the number of concatenated streams that are concatenated in the sosi.data or sosi.re,im

   -- . rewire nof_data streams from data  to re,im and force data = X  to show that sosi data    is used

   -- . rewire nof_data streams from re,im to data  and force re,im = X to show that sosi complex is used

  FUNCTION func_dp_stream_complex_to_data(dp : t_dp_sosi; data_w : NATURAL; nof_data : NATURAL; data_order_im_re : BOOLEAN) RETURN t_dp_sosi;

  FUNCTION func_dp_stream_complex_to_data(dp : t_dp_sosi; data_w : NATURAL; nof_data : NATURAL                            ) RETURN t_dp_sosi;  -- data_order_im_re = TRUE

  FUNCTION func_dp_stream_complex_to_data(dp : t_dp_sosi; data_w : NATURAL                                                ) RETURN t_dp_sosi;  -- data_order_im_re = TRUE, nof_data = 1

  FUNCTION func_dp_stream_data_to_complex(dp : t_dp_sosi; data_w : NATURAL; nof_data : NATURAL; data_order_im_re : BOOLEAN) RETURN t_dp_sosi;

  FUNCTION func_dp_stream_data_to_complex(dp : t_dp_sosi; data_w : NATURAL; nof_data : NATURAL                            ) RETURN t_dp_sosi;  -- data_order_im_re = TRUE

  FUNCTION func_dp_stream_data_to_complex(dp : t_dp_sosi; data_w : NATURAL                                                ) RETURN t_dp_sosi;  -- data_order_im_re = TRUE, nof_data = 1

  FUNCTION func_dp_stream_complex_to_data(dp_arr : t_dp_sosi_arr; data_w : NATURAL; nof_data : NATURAL; data_order_im_re : BOOLEAN) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_complex_to_data(dp_arr : t_dp_sosi_arr; data_w : NATURAL; nof_data : NATURAL                            ) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_complex_to_data(dp_arr : t_dp_sosi_arr; data_w : NATURAL                                                ) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_data_to_complex(dp_arr : t_dp_sosi_arr; data_w : NATURAL; nof_data : NATURAL; data_order_im_re : BOOLEAN) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_data_to_complex(dp_arr : t_dp_sosi_arr; data_w : NATURAL; nof_data : NATURAL                            ) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_data_to_complex(dp_arr : t_dp_sosi_arr; data_w : NATURAL                                                ) RETURN t_dp_sosi_arr;

  -- Concatenate the data and complex re,im fields from a SOSI array into a single SOSI stream (assumes streams are in sync)

  FUNCTION func_dp_stream_concat(snk_in_arr : t_dp_sosi_arr; data_w : NATURAL) RETURN t_dp_sosi; -- Concat SOSI_ARR data into single SOSI

  FUNCTION func_dp_stream_concat(src_in     : t_dp_siso; nof_streams : NATURAL) RETURN t_dp_siso_arr; -- Wire single SISO to SISO_ARR

  -- Reconcatenate the data and complex re,im fields from a SOSI array from nof_data*in_w to nof_data*out_w

  -- . data_representation = "SIGNED"   treat sosi.data field as signed

  --                         "UNSIGNED" treat sosi.data field as unsigned

  --                         "COMPLEX"  treat sosi.data field as complex concatenated

  -- . data_order_im_re = TRUE  then "COMPLEX" data = im&re

  --                      FALSE then "COMPLEX" data = re&im

  --                      ignore when data_representation /= "COMPLEX"

  FUNCTION func_dp_stream_reconcat(snk_in     : t_dp_sosi;     in_w, out_w, nof_data : NATURAL; data_representation : STRING; data_order_im_re : BOOLEAN) RETURN t_dp_sosi;

  FUNCTION func_dp_stream_reconcat(snk_in     : t_dp_sosi;     in_w, out_w, nof_data : NATURAL; data_representation : STRING                            ) RETURN t_dp_sosi;

  FUNCTION func_dp_stream_reconcat(snk_in_arr : t_dp_sosi_arr; in_w, out_w, nof_data : NATURAL; data_representation : STRING; data_order_im_re : BOOLEAN) RETURN t_dp_sosi_arr;

  FUNCTION func_dp_stream_reconcat(snk_in_arr : t_dp_sosi_arr; in_w, out_w, nof_data : NATURAL; data_representation : STRING                            ) RETURN t_dp_sosi_arr;

  -- Deconcatenate data and complex re,im fields from SOSI into SOSI array

  FUNCTION func_dp_stream_deconcat(snk_in      : t_dp_sosi; nof_streams, data_w : NATURAL) RETURN t_dp_sosi_arr; -- Deconcat SOSI data

  FUNCTION func_dp_stream_deconcat(src_out_arr : t_dp_siso_arr) RETURN t_dp_siso; -- Wire SISO_ARR(0) to single SISO 

END dp_stream_pkg;

PACKAGE BODY dp_stream_pkg IS

  -- Check sosi.valid against siso.ready

  PROCEDURE proc_dp_siso_alert(CONSTANT c_ready_latency : IN    NATURAL;

                               SIGNAL   clk             : IN    STD_LOGIC;

                               SIGNAL   sosi            : IN    t_dp_sosi;

                               SIGNAL   siso            : IN    t_dp_siso;

                               SIGNAL   ready_reg       : INOUT STD_LOGIC_VECTOR) IS

  BEGIN

    ready_reg(0) <= siso.ready;

    -- Register siso.ready in c_ready_latency registers

    IF rising_edge(clk) THEN

      -- Check DP sink

      IF sosi.valid = '1' AND ready_reg(c_ready_latency) = '0' THEN

        REPORT "RL ERROR" SEVERITY FAILURE;

      END IF;

      ready_reg( 1 TO c_ready_latency) <= ready_reg( 0 TO c_ready_latency-1);

    END IF;

  END proc_dp_siso_alert;

  -- Default RL=1

  PROCEDURE proc_dp_siso_alert(SIGNAL   clk             : IN    STD_LOGIC;

                               SIGNAL   sosi            : IN    t_dp_sosi;

                               SIGNAL   siso            : IN    t_dp_siso;

                               SIGNAL   ready_reg       : INOUT STD_LOGIC_VECTOR) IS

  BEGIN

    proc_dp_siso_alert(1, clk, sosi, siso, ready_reg);

  END proc_dp_siso_alert;

  -- SOSI/SISO array version

  PROCEDURE proc_dp_siso_alert(CONSTANT c_ready_latency : IN    NATURAL;

                               SIGNAL   clk             : IN    STD_LOGIC;

                               SIGNAL   sosi_arr        : IN    t_dp_sosi_arr;

                               SIGNAL   siso_arr        : IN    t_dp_siso_arr;

                               SIGNAL   ready_reg       : INOUT STD_LOGIC_VECTOR) IS

  BEGIN

    FOR i IN 0 TO sosi_arr'LENGTH-1 LOOP

      ready_reg(i*(c_ready_latency+1)) <= siso_arr(i).ready; -- SLV is used as an array: nof_streams*(0..c_ready_latency)

    END LOOP;

    -- Register siso.ready in c_ready_latency registers

    IF rising_edge(clk) THEN

      FOR i IN 0 TO sosi_arr'LENGTH-1 LOOP

        -- Check DP sink

        IF sosi_arr(i).valid = '1' AND ready_reg(i*(c_ready_latency+1)+1) = '0' THEN

          REPORT "RL ERROR" SEVERITY FAILURE;

        END IF;

        ready_reg(i*(c_ready_latency+1)+1 TO i*(c_ready_latency+1)+c_ready_latency) <=  ready_reg(i*(c_ready_latency+1) TO i*(c_ready_latency+1)+c_ready_latency-1);

      END LOOP;

    END IF;

  END proc_dp_siso_alert;

  -- SOSI/SISO array version with RL=1

  PROCEDURE proc_dp_siso_alert(SIGNAL   clk             : IN    STD_LOGIC;

                               SIGNAL   sosi_arr        : IN    t_dp_sosi_arr;

                               SIGNAL   siso_arr        : IN    t_dp_siso_arr;

                               SIGNAL   ready_reg       : INOUT STD_LOGIC_VECTOR) IS

  BEGIN

    proc_dp_siso_alert(1, clk, sosi_arr, siso_arr, ready_reg);

  END proc_dp_siso_alert;

  -- Resize functions to fit an integer or an SLV in the corresponding t_dp_sosi field width

  FUNCTION TO_DP_BSN(n : NATURAL) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(TO_SVEC(n, 32), c_dp_stream_bsn_w);

  END TO_DP_BSN;

  FUNCTION TO_DP_DATA(n : INTEGER) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(TO_SVEC(n, 32), c_dp_stream_data_w);

  END TO_DP_DATA;

  FUNCTION TO_DP_SDATA(n : INTEGER) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_SVEC(TO_SVEC(n, 32), c_dp_stream_data_w);

  END TO_DP_SDATA;

  FUNCTION TO_DP_UDATA(n : INTEGER) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN TO_DP_DATA(n);

  END TO_DP_UDATA;

  FUNCTION TO_DP_DSP_DATA(n : INTEGER) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_SVEC(TO_SVEC(n, 32), c_dp_stream_dsp_data_w);

  END TO_DP_DSP_DATA;

  FUNCTION TO_DP_DSP_UDATA(n : INTEGER) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(TO_SVEC(n, 32), c_dp_stream_dsp_data_w);

  END TO_DP_DSP_UDATA;

  FUNCTION TO_DP_EMPTY(n : NATURAL) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN TO_UVEC(n, c_dp_stream_empty_w);

  END TO_DP_EMPTY;

  FUNCTION TO_DP_CHANNEL(n : NATURAL) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN TO_UVEC(n, c_dp_stream_channel_w);

  END TO_DP_CHANNEL;

  FUNCTION TO_DP_ERROR(n : NATURAL) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN TO_UVEC(n, c_dp_stream_error_w);

  END TO_DP_ERROR;

  FUNCTION RESIZE_DP_BSN(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(vec, c_dp_stream_bsn_w);

  END RESIZE_DP_BSN;

  FUNCTION RESIZE_DP_DATA(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(vec, c_dp_stream_data_w);

  END RESIZE_DP_DATA;

  FUNCTION RESIZE_DP_SDATA(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_SVEC(vec, c_dp_stream_data_w);

  END RESIZE_DP_SDATA;

  FUNCTION RESIZE_DP_XDATA(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

    VARIABLE v_vec : STD_LOGIC_VECTOR(c_dp_stream_data_w-1 DOWNTO 0) := (OTHERS=>'X');

  BEGIN

    v_vec(vec'LENGTH-1 DOWNTO 0) := vec;

    RETURN v_vec;

  END RESIZE_DP_XDATA;

  FUNCTION RESIZE_DP_DSP_DATA(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_SVEC(vec, c_dp_stream_dsp_data_w);

  END RESIZE_DP_DSP_DATA;

  FUNCTION RESIZE_DP_EMPTY(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(vec, c_dp_stream_empty_w);

  END RESIZE_DP_EMPTY;

  FUNCTION RESIZE_DP_CHANNEL(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(vec, c_dp_stream_channel_w);

  END RESIZE_DP_CHANNEL;

  FUNCTION RESIZE_DP_ERROR(vec : STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(vec, c_dp_stream_error_w);

  END RESIZE_DP_ERROR;

  FUNCTION INCR_DP_DATA(vec : STD_LOGIC_VECTOR; dec : INTEGER; w : NATURAL) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_DP_DATA(STD_LOGIC_VECTOR(UNSIGNED(vec(w-1 DOWNTO 0)) + dec));

  END INCR_DP_DATA;

  FUNCTION INCR_DP_SDATA(vec : STD_LOGIC_VECTOR; dec : INTEGER; w : NATURAL) RETURN STD_LOGIC_VECTOR IS