Subversion Repositories astron_mm

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

--

-- Copyright 2020

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

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

-- 

-- Licensed under the Apache License, Version 2.0 (the "License");

-- you may not use this file except in compliance with the License.

-- You may obtain a copy of the License at

-- 

--     http://www.apache.org/licenses/LICENSE-2.0

-- 

-- Unless required by applicable law or agreed to in writing, software

-- distributed under the License is distributed on an "AS IS" BASIS,

-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

-- See the License for the specific language governing permissions and

-- limitations under the License.

--

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

LIBRARY IEEE, common_pkg_lib;

USE IEEE.STD_LOGIC_1164.ALL;

USE IEEE.NUMERIC_STD.ALL;

USE common_pkg_lib.common_pkg.ALL;

USE common_pkg_lib.common_str_pkg.ALL;

-- Purpose:

-- . Dynamically map record-like field structures onto SLVs.

-- Description:

-- . The MM register is defined by mm_fields.vhd.

-- . The MM register consists of "RO" = input fields (status) and "RW" = output fields (control) in

--   arbitrary order. The entire register is kept in a word_arr slv. The functions can extract the

--   "RO" fields into a slv_in and the "RW" fields into a slv_out. Hence the slv_in'LENGTH +

--   slv_out'LENGTH = word_arr'LENGTH.

--

-- . Advantages:

--   . Replaces non-generic (dedicated) records;

--   . Field widths are variable

-- Remarks:

PACKAGE common_field_pkg IS

  CONSTANT c_common_field_name_len    : NATURAL := 64;

  CONSTANT c_common_field_default_len : NATURAL := 256;

  TYPE t_common_field IS RECORD

    name     : STRING(1 TO c_common_field_name_len);

    mode     : STRING(1 TO 2);

    size     : POSITIVE;

    default  : STD_LOGIC_VECTOR(c_common_field_default_len-1 DOWNTO 0);

  END RECORD;

  TYPE t_common_field_arr IS ARRAY(INTEGER RANGE <>) OF t_common_field;

  FUNCTION field_name_pad(name: STRING) RETURN STRING;

  FUNCTION field_default(slv_in: STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR;

  FUNCTION field_default(nat_in: NATURAL) RETURN STD_LOGIC_VECTOR;

  FUNCTION field_map_defaults(field_arr : t_common_field_arr) RETURN STD_LOGIC_VECTOR;  -- returns slv_out

  FUNCTION field_mode        (field_arr : t_common_field_arr; name: STRING     ) RETURN STRING;

  FUNCTION field_size        (field_arr : t_common_field_arr; name: STRING     ) RETURN NATURAL;

  FUNCTION field_hi          (field_arr : t_common_field_arr; name: STRING     ) RETURN INTEGER;

  FUNCTION field_hi          (field_arr : t_common_field_arr; index: NATURAL   ) RETURN NATURAL;

  FUNCTION field_lo          (field_arr : t_common_field_arr; name: STRING     ) RETURN NATURAL;

  FUNCTION field_lo          (field_arr : t_common_field_arr; index: NATURAL   ) RETURN NATURAL;

  FUNCTION field_slv_len     (field_arr : t_common_field_arr                   ) RETURN NATURAL;

  FUNCTION field_slv_in_len  (field_arr : t_common_field_arr                   ) RETURN NATURAL;

  FUNCTION field_slv_out_len (field_arr : t_common_field_arr                   ) RETURN NATURAL;

  FUNCTION field_nof_words   (field_arr : t_common_field_arr; word_w : NATURAL ) RETURN NATURAL;

  FUNCTION field_map_in      (field_arr : t_common_field_arr; slv        : STD_LOGIC_VECTOR; word_w : NATURAL ; mode : STRING) RETURN STD_LOGIC_VECTOR;  -- returns word_arr

  FUNCTION field_map_out     (field_arr : t_common_field_arr; word_arr   : STD_LOGIC_VECTOR; word_w : NATURAL                ) RETURN STD_LOGIC_VECTOR;  -- returns slv_out

  FUNCTION field_map         (field_arr : t_common_field_arr; word_arr_in: STD_LOGIC_VECTOR; word_arr_out: STD_LOGIC_VECTOR; word_w : NATURAL) RETURN STD_LOGIC_VECTOR;  -- returns word_arr

  FUNCTION field_ovr_arr(field_arr : t_common_field_arr; ovr_init: STD_LOGIC_VECTOR) RETURN t_common_field_arr;

  FUNCTION field_exists(field_arr : t_common_field_arr; name: STRING) RETURN BOOLEAN;

  FUNCTION field_arr_set_mode(field_arr : t_common_field_arr; mode : STRING) RETURN t_common_field_arr;

  FUNCTION sel_a_b(sel : BOOLEAN; a, b : t_common_field_arr ) RETURN t_common_field_arr;

END common_field_pkg;

PACKAGE BODY common_field_pkg IS

  FUNCTION field_name_pad(name: STRING) RETURN STRING IS

  BEGIN

    RETURN pad(name, c_common_field_name_len, ' ');

  END field_name_pad;

  FUNCTION field_default(slv_in: STD_LOGIC_VECTOR) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN RESIZE_UVEC(slv_in, c_common_field_default_len);

  END field_default;

  FUNCTION field_default(nat_in: NATURAL) RETURN STD_LOGIC_VECTOR IS

  BEGIN

    RETURN TO_UVEC(nat_in, c_common_field_default_len);

  END field_default;

  FUNCTION field_map_defaults(field_arr : t_common_field_arr) RETURN STD_LOGIC_VECTOR IS

    VARIABLE v_slv_out : STD_LOGIC_VECTOR(field_slv_out_len(field_arr)-1 DOWNTO 0);

  BEGIN

    FOR f IN 0 TO field_arr'HIGH LOOP

      IF field_arr(f).mode="RW" THEN

        v_slv_out( field_hi(field_arr, field_arr(f).name) DOWNTO field_lo(field_arr, field_arr(f).name)) := field_arr(f).default(field_arr(f).size-1 DOWNTO 0);

      END IF;

    END LOOP;

    RETURN v_slv_out;

  END field_map_defaults;

  FUNCTION field_mode(field_arr : t_common_field_arr; name: STRING) RETURN STRING IS

  -- Returns the mode string of the passed (via name) field

  BEGIN

    IF field_exists(field_arr, name) THEN

      FOR i IN 0 TO field_arr'HIGH LOOP

        IF field_arr(i).name=field_name_pad(name) THEN

          RETURN field_arr(i).mode;

        END IF;

      END LOOP;

    ELSE

      RETURN "-1";

    END IF;

  END field_mode;

  FUNCTION field_size(field_arr : t_common_field_arr; name: STRING) RETURN NATURAL IS

  -- Returns the size of the passed (via name) field

  BEGIN

    FOR i IN 0 TO field_arr'HIGH LOOP

      IF field_arr(i).name=field_name_pad(name) THEN

        RETURN field_arr(i).size;

      END IF;

    END LOOP;

  END field_size;

  FUNCTION field_hi(field_arr : t_common_field_arr; name: STRING) RETURN INTEGER IS

  -- Returns the high (=left) bit range index of the field within the field_arr interpreted as concatenated IN or OUT SLV

    VARIABLE v_acc_hi : NATURAL := 0;

  BEGIN

    IF field_exists(field_arr, name) THEN

      FOR i IN 0 TO field_arr'HIGH LOOP

        IF field_arr(i).mode=field_mode(field_arr, name) THEN  -- increment index only for the "RO" = IN or the "RW" = OUT

          v_acc_hi := v_acc_hi + field_arr(i).size;

          IF field_arr(i).name = field_name_pad(name) THEN

            RETURN v_acc_hi-1;

          END IF;

        END IF;

      END LOOP;

    ELSE --field does not exist; return -1 which results in null array

      RETURN -1;

    END IF;

  END field_hi;

  FUNCTION field_hi(field_arr : t_common_field_arr; index : NATURAL) RETURN NATURAL IS

  -- Returns the high (=left) bit range index of the field within the field_arr interpreted as concatenated SLV

    VARIABLE v_acc_hi : NATURAL := 0;

  BEGIN

    FOR i IN 0 TO index LOOP

      v_acc_hi := v_acc_hi + field_arr(i).size;

      IF i = index THEN

        RETURN v_acc_hi-1;

      END IF;

    END LOOP;

  END field_hi;

  FUNCTION field_lo(field_arr : t_common_field_arr; name: STRING) RETURN NATURAL IS

  -- Returns the low (=right) bit range index of the field within the field_arr interpreted as concatenated IN or OUT SLV

    VARIABLE v_acc_hi : NATURAL := 0;

  BEGIN

    IF field_exists(field_arr, name) THEN

      FOR i IN 0 TO field_arr'HIGH LOOP

        IF field_arr(i).mode=field_mode(field_arr, name) THEN  -- increment index only for the "RO" = IN or the "RW" = OUT

          v_acc_hi := v_acc_hi + field_arr(i).size;

          IF field_arr(i).name = field_name_pad(name) THEN

            RETURN v_acc_hi-field_arr(i).size;

          END IF;

        END IF;

      END LOOP;

    ELSE

      RETURN 0;

    END IF;

  END field_lo;

  FUNCTION field_lo(field_arr : t_common_field_arr; index : NATURAL) RETURN NATURAL IS

  -- Returns the low (=right) bit range index of the field within the field_arr interpreted as concatenated SLV

    VARIABLE v_acc_hi : NATURAL := 0;

  BEGIN

    FOR i IN 0 TO index LOOP

      v_acc_hi := v_acc_hi + field_arr(i).size;

      IF i = index THEN

        RETURN v_acc_hi-field_arr(i).size;

      END IF;

    END LOOP;

  END field_lo;

  FUNCTION field_slv_len(field_arr : t_common_field_arr) RETURN NATURAL IS

  -- Return the total length of all fields in field_arr

    VARIABLE v_len : NATURAL := 0;

  BEGIN

    FOR i IN 0 TO field_arr'HIGH LOOP

      v_len := v_len + field_arr(i).size;

    END LOOP;

    RETURN v_len;

  END field_slv_len;

  FUNCTION field_slv_in_len(field_arr : t_common_field_arr) RETURN NATURAL IS

  -- Return the total length of the input fields in field_arr (= all "RO")

    VARIABLE v_len : NATURAL := 0;

  BEGIN

    FOR f IN 0 TO field_arr'HIGH LOOP

      IF field_arr(f).mode="RO" THEN

        v_len := v_len + field_arr(f).size;

      END IF;

    END LOOP;

    RETURN v_len;

  END field_slv_in_len;

  FUNCTION field_slv_out_len(field_arr : t_common_field_arr) RETURN NATURAL IS

  -- Return the total length of the output fields in field_arr (= all "RW")

    VARIABLE v_len : NATURAL := 0;

  BEGIN

    FOR f IN 0 TO field_arr'HIGH LOOP

      IF field_arr(f).mode="RW" THEN

        v_len := v_len + field_arr(f).size;

      END IF;

    END LOOP;

    RETURN v_len;

  END field_slv_out_len;

  FUNCTION field_nof_words(field_arr : t_common_field_arr; word_w : NATURAL) RETURN NATURAL IS

  -- Return the number of words (of width word_w) required to hold field_arr

    VARIABLE v_word_cnt      : NATURAL := 0;

    VARIABLE v_nof_reg_words : NATURAL;

  BEGIN

    FOR f IN 0 TO field_arr'HIGH LOOP

      -- Get the number of register words this field spans

      v_nof_reg_words := ceil_div(field_arr(f).size, word_w);

      FOR w IN 0 TO v_nof_reg_words-1 LOOP

        v_word_cnt := v_word_cnt +1;

      END LOOP;

    END LOOP;

    RETURN v_word_cnt;

  END field_nof_words;

  FUNCTION field_map_in(field_arr : t_common_field_arr; slv: STD_LOGIC_VECTOR; word_w : NATURAL; mode : STRING) RETURN STD_LOGIC_VECTOR IS

  -- Re-map a field SLV into a larger SLV, support mapping both the slv_in or the slv_out that dependents on mode; each field starting at a word boundary (word_w)

    VARIABLE v_word_arr : STD_LOGIC_VECTOR(field_nof_words(field_arr, word_w)*word_w-1 DOWNTO 0) := (OTHERS=>'0');

    VARIABLE v_word_cnt : NATURAL := 0;

  BEGIN

    FOR f IN 0 TO field_arr'HIGH LOOP

       -- Only extract the fields that are inputs

      IF field_arr(f).mode=mode THEN  -- if mode="RO" then slv = slv_in, else if mode="RW" then slv = slv_out

        -- Extract the field 

        v_word_arr( v_word_cnt*word_w+field_arr(f).size-1 DOWNTO v_word_cnt*word_w) := slv( field_hi(field_arr, field_arr(f).name) DOWNTO field_lo(field_arr, field_arr(f).name) );

      END IF;

      -- Calculate the correct word offset for the next field

      v_word_cnt  := v_word_cnt + ceil_div(field_arr(f).size, word_w);

    END LOOP;

    RETURN v_word_arr;

  END field_map_in;

  FUNCTION field_map_out(field_arr : t_common_field_arr; word_arr: STD_LOGIC_VECTOR; word_w : NATURAL) RETURN STD_LOGIC_VECTOR IS

  -- Reverse of field_map_in

    VARIABLE v_slv_out  : STD_LOGIC_VECTOR(field_slv_out_len(field_arr)-1 DOWNTO 0) := (OTHERS=>'0');

    VARIABLE v_word_cnt : NATURAL := 0;

  BEGIN

    FOR f IN 0 TO field_arr'HIGH LOOP

      -- Only extract the fields that are outputs 

      IF field_arr(f).mode="RW" THEN

        -- Extract the field 

        v_slv_out( field_hi(field_arr, field_arr(f).name) DOWNTO field_lo(field_arr, field_arr(f).name)) := word_arr( v_word_cnt*word_w+field_arr(f).size-1 DOWNTO v_word_cnt*word_w);

      END IF;

      -- Calculate the correct word offset for the next field

      v_word_cnt  := v_word_cnt + ceil_div(field_arr(f).size, word_w);

    END LOOP;

    RETURN v_slv_out;

  END field_map_out;

  FUNCTION field_map(field_arr : t_common_field_arr; word_arr_in: STD_LOGIC_VECTOR; word_arr_out: STD_LOGIC_VECTOR; word_w : NATURAL) RETURN STD_LOGIC_VECTOR IS

  -- Create one SLV consisting of both read-only and output-readback fields, e.g. as input to an MM reg

    VARIABLE v_word_arr : STD_LOGIC_VECTOR(field_nof_words(field_arr, word_w)*word_w-1 DOWNTO 0);

    VARIABLE v_word_cnt : NATURAL := 0;

  BEGIN

    -- Wire the entire SLV to the input SLV by default

    v_word_arr := word_arr_in;

    -- Now re-assign the words that need to be read back from word_arr_out

    FOR f IN 0 TO field_arr'HIGH LOOP

      IF field_arr(f).mode="RW" THEN

        v_word_arr( v_word_cnt*word_w+field_arr(f).size-1 DOWNTO v_word_cnt*word_w):= word_arr_out( v_word_cnt*word_w+field_arr(f).size-1 DOWNTO v_word_cnt*word_w);

      END IF;

      -- Calculate the correct word offset for the next field

      v_word_cnt := v_word_cnt + ceil_div(field_arr(f).size, word_w);

    END LOOP;

    RETURN v_word_arr;

  END field_map;

  FUNCTION field_ovr_arr(field_arr : t_common_field_arr; ovr_init: STD_LOGIC_VECTOR) RETURN t_common_field_arr IS

  -- Copy field_arr but change widths to 1 to create a 1-bit override field for each field in field_arr.

    VARIABLE v_ovr_field_arr : t_common_field_arr(field_arr'RANGE);

  BEGIN

    v_ovr_field_arr:= field_arr;

    FOR i IN field_arr'RANGE LOOP

      v_ovr_field_arr(i).size := 1;

      v_ovr_field_arr(i).default := field_default(slv(ovr_init(i)));

    END LOOP;

    RETURN v_ovr_field_arr;

  END field_ovr_arr;

  FUNCTION field_exists(field_arr : t_common_field_arr; name: STRING) RETURN BOOLEAN IS

  BEGIN

    FOR i IN field_arr'RANGE LOOP

      IF field_arr(i).name=field_name_pad(name) THEN

        RETURN TRUE;

      END IF;

    END LOOP;

  RETURN FALSE;

  END field_exists;

  FUNCTION field_arr_set_mode(field_arr : t_common_field_arr; mode : STRING) RETURN t_common_field_arr IS

    VARIABLE v_field_arr : t_common_field_arr(field_arr'RANGE);

  BEGIN

    v_field_arr := field_arr;

    FOR i IN field_arr'RANGE LOOP

      v_field_arr(i).mode := mode;

    END LOOP;

    RETURN v_field_arr;

  END field_arr_set_mode;

  FUNCTION sel_a_b(sel :BOOLEAN; a, b : t_common_field_arr) RETURN t_common_field_arr IS

  BEGIN

    IF sel = TRUE THEN

      RETURN a;

    ELSE

      RETURN b;

    END IF;

  END;

END common_field_pkg;