Subversion Repositories pltbutils

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

----                                                              ----

---- PlTbUtils Fuctions and Procedures Package                    ----

----                                                              ----

---- This file is part of the PlTbUtils project                   ----

---- http://opencores.org/project,pltbutils                       ----

----                                                              ----

---- Description:                                                 ----

---- PlTbUtils is a collection of functions, procedures and       ----

---- components for easily creating stimuli and checking response ----

---- in automatic self-checking testbenches.                      ----

----                                                              ----

---- This file defines fuctions and procedures for controlling    ----

---- stimuli to a DUT and checking response.                      ----

----                                                              ----

---- To Do:                                                       ----

---- -                                                            ----

----                                                              ----

---- Author(s):                                                   ----

---- - Per Larsson, pela@opencores.org                            ----

----                                                              ----

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

----                                                              ----

---- Copyright (C) 2013 Authors and OPENCORES.ORG                 ----

----                                                              ----

---- This source file may be used and distributed without         ----

---- restriction provided that this copyright statement is not    ----

---- removed from the file and that any derivative work contains  ----

---- the original copyright notice and the associated disclaimer. ----

----                                                              ----

---- This source file is free software; you can redistribute it   ----

---- and/or modify it under the terms of the GNU Lesser General   ----

---- Public License as published by the Free Software Foundation; ----

---- either version 2.1 of the License, or (at your option) any   ----

---- later version.                                               ----

----                                                              ----

---- This source 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 Lesser General Public License for more  ----

---- details.                                                     ----

----                                                              ----

---- You should have received a copy of the GNU Lesser General    ----

---- Public License along with this source; if not, download it   ----

---- from http://www.opencores.org/lgpl.shtml                     ----

----                                                              ----

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

library ieee;

use ieee.std_logic_1164.all;

use ieee.numeric_std.all;

use std.textio.all;

use std.env.all; -- VHDL-2008

use work.txt_util.all;

use work.pltbutils_type_pkg.all; -- Use for VHDL-2002, comment out for VHDL-93

package pltbutils_func_pkg is

  -- See the package body for a description of the functions and procedures.

  constant C_PLTBUTILS_STRLEN  : natural := 80;

  constant C_PLTBUTILS_TIMEOUT : time    := 10 sec;

  constant C_WAIT_BEFORE_STOP_TIME : time := 1 us;

  -- Counters for number of checks and number of errors

  -- VHDL-2002:

  shared variable v_pltbutils_test_num  : pltbutils_p_integer_t;

  shared variable v_pltbutils_test_name : pltbutils_p_string_t;

  shared variable v_pltbutils_info      : pltbutils_p_string_t;

  shared variable v_pltbutils_chk_cnt   : pltbutils_p_integer_t;

  shared variable v_pltbutils_err_cnt   : pltbutils_p_integer_t;

  shared variable v_pltbutils_stop_sim  : pltbutils_p_std_logic_t;

  -- VHDL-1993:

  --shared variable v_pltbutils_test_num  : natural := 0;

  --shared variable v_pltbutils_test_name : string(1 to C_PLTBUTILS_STRLEN) := (others => ' ');

  --shared variable v_pltbutils_info      : string(1 to C_PLTBUTILS_STRLEN) := (others => ' ');

  --shared variable v_pltbutils_chk_cnt   : natural := 0;

  --shared variable v_pltbutils_err_cnt   : natural := 0;

  --shared variable v_pltbutils_stop_sim  : std_logic := '0';

  -- Global status- and control signal

  type pltbutils_sc_t is

    record

      test_num  : natural;

      test_name : string(1 to C_PLTBUTILS_STRLEN);

      info      : string(1 to C_PLTBUTILS_STRLEN);

      chk_cnt   : natural;

      err_cnt   : natural;

      stop_sim  : std_logic;

    end record;

  signal pltbutils_sc : pltbutils_sc_t;

  -- startsim 

  procedure startsim(

    constant testcase_name      : in    string;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  -- endsim

  procedure endsim(

    signal   pltbutils_sc        : out pltbutils_sc_t;

    constant show_success_fail   : in   boolean := false;

    constant force               : in boolean := false

  );

  -- testname

  procedure testname(

    constant num                : in    integer := -1;

    constant name               : in    string;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure testname(

    constant name               : in    string;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  -- print, printv, print2

  procedure print(

    constant active             : in    boolean;

    signal   s                  : out   string;

    constant txt                : in    string

  );

  procedure print(

    signal   s                  : out   string;

    constant txt                : in    string

  );

  procedure printv(

    constant active             : in    boolean;

    variable s                  : out   string;

    constant txt                : in    string

  );

  procedure printv(

    variable s                  : out   string;

    constant txt                : in    string

  );

  procedure printv(

    constant active             : in    boolean;

    variable s                  : inout pltbutils_p_string_t;

    constant txt                : in    string

  );

  procedure printv(

    variable s                  : inout pltbutils_p_string_t;

    constant txt                : in    string

  );

  procedure print(

    constant active             : in    boolean;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant txt                : in    string

  );

  procedure print(

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant txt                : in    string

  );

  procedure print2(

    constant active             : in    boolean;

    signal   s                  : out   string;

    constant txt                : in    string

  );

  procedure print2(

    signal   s                  : out   string;

    constant txt                : in    string

  );

  procedure print2(

    constant active             : in    boolean;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant txt                : in    string

  );

  procedure print2(

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant txt                : in    string

  );

  -- waitclks

  procedure waitclks(

    constant N                  : in    natural;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  -- waitsig

  procedure waitsig(

    signal   s                  : in    integer;

    constant value              : in    integer;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  procedure waitsig(

    signal   s                  : in    std_logic;

    constant value              : in    std_logic;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  procedure waitsig(

    signal   s                  : in    std_logic;

    constant value              : in    integer;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  procedure waitsig(

    signal   s                  : in    std_logic_vector;

    constant value              : in    std_logic_vector;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  procedure waitsig(

    signal   s                  : in    std_logic_vector;

    constant value              : in    integer;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  procedure waitsig(

    signal   s                  : in    unsigned;

    constant value              : in    unsigned;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  procedure waitsig(

    signal   s                  : in    unsigned;

    constant value              : in    integer;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  procedure waitsig(

    signal   s                  : in    signed;

    constant value              : in    signed;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  procedure waitsig(

    signal   s                  : in    signed;

    constant value              : in    integer;

    signal   clk                : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t;

    constant falling            : in    boolean := false;

    constant timeout            : in    time    := C_PLTBUTILS_TIMEOUT

  );

  -- check

  procedure check(

    constant rpt                : in    string;

    constant data               : in    integer;

    constant expected           : in    integer;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    std_logic;

    constant expected           : in    std_logic;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    std_logic;

    constant expected           : in    integer;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    std_logic_vector;

    constant expected           : in    std_logic_vector;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    std_logic_vector;

    constant expected           : in    std_logic_vector;

    constant mask               : in    std_logic_vector;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    std_logic_vector;

    constant expected           : in    integer;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    std_logic_vector;

    constant expected           : in    integer;

    constant mask               : in    std_logic_vector;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    unsigned;

    constant expected           : in    unsigned;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    unsigned;

    constant expected           : in    integer;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    signed;

    constant expected           : in    signed;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant data               : in    signed;

    constant expected           : in    integer;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  procedure check(

    constant rpt                : in    string;

    constant expr               : in    boolean;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  );

  -- pltbutils internal procedure(s), do not call from user's code

  procedure pltbutils_sc_update(

    signal pltbutils_sc : out pltbutils_sc_t

  );

end package pltbutils_func_pkg;

package body pltbutils_func_pkg is

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

  -- startsim

  --

  -- procedure startsim(

  --   constant testcase_name      : in    string;

  --   signal   pltbutils_sc       : out   pltbutils_sc_t

  -- )

  --

  -- Displays a message at start of simulation message, and initializes

  -- PlTbUtils' global status and control signal.

  -- Call startsim() only once.

  --

  -- Arguments:

  --   testcase_name            Name of the test case, e.g. "tc1".

  --

  --   pltbutils_sc             PlTbUtils' global status- and control signal.

  --                            Must be set to pltbutils_sc.

  --

  -- NOTE:

  -- The start-of-simulation message is not only intended to be informative

  -- for humans. It is also intended to be searched for by scripts,

  -- e.g. for collecting results from a large number of regression tests.

  -- For this reason, the message must be consistent and unique.

  --

  -- DO NOT MODIFY the message "--- START OF SIMULATION ---".

  -- DO NOT OUTPUT AN IDENTICAL MESSAGE anywhere else.

  --

  -- Example:

  -- startsim("tc1", pltbutils_sc);

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

  procedure startsim(

    constant testcase_name      : in    string;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  ) is

    variable dummy : integer;

  begin

    printv(v_pltbutils_info, testcase_name);

    print(lf & "--- START OF SIMULATION ---");

    print("Testcase: " & testcase_name);

    print(time'image(now));

    -- VHDL-2002:

    v_pltbutils_stop_sim.clr;

    v_pltbutils_test_num.clr;

    v_pltbutils_test_name.set("START OF SIMULATION");

    v_pltbutils_chk_cnt.clr;

    v_pltbutils_err_cnt.clr;

    pltbutils_sc_update(pltbutils_sc);

    -- VHDL-1993:

    --v_pltbutils_stop_sim := '0';

    --v_pltbutils_test_num := 0;

    --printv(v_pltbutils_test_name, "START OF SIMULATION");

    --v_pltbutils_chk_cnt := 0;

    --v_pltbutils_err_cnt := 0;

    --pltbutils_sc_update(pltbutils_sc);

  end procedure startsim;

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

  -- endsim

  --

  -- procedure endsim(

  --   signal   pltbutils_sc       : out pltbutils_sc_t;

  --   constant show_success_fail  : in  boolean := false;

  --   constant force              : in  boolean := false

  -- )

  --

  -- Displays a message at end of simulation message, presents the simulation

  -- results, and stops the simulation. 

  -- Call endsim() it only once.

  --

  -- Arguments: 

  --   pltbutils_sc             PlTbUtils' global status- and control signal.

  --                            Must be set to pltbutils_sc.

  --

  --   show_success_fail        If true, endsim() shows "*** SUCCESS ***", 

  --                            "*** FAIL ***", or "*** NO CHECKS ***".

  --                            Optional, default is false.

  --

  --   force                    If true, forces the simulation to stop using an

  --                            assert failure statement. Use this option only

  --                            if the normal way of stopping the simulation

  --                            doesn't work (see below).

  --                            Optional, default is false.

  --

  -- The testbench should be designed so that all clocks stop when endsim()

  -- sets the signal stop_sim to '1'. This should stop the simulator.

  -- In some cases, that doesn't work, then set the force argument to true, which

  -- causes a false assert failure, which should stop the simulator.

  -- Scripts searching transcript logs for errors and failures, should ignore

  -- the failure with "--- FORCE END OF SIMULATION ---" as part of the report.

  --

  -- NOTE:

  -- The end-of-simulation messages and success/fail messages are not only

  -- intended to be informative for humans. They are also intended to be

  -- searched for by scripts, e.g. for collecting results from a large number

  -- of regression tests.

  -- For this reason, the message must be consistent and unique.

  --

  -- DO NOT MODIFY the messages "--- END OF SIMULATION ---", 

  -- "*** SUCCESS ***", "*** FAIL ***", "*** NO CHECKS ***".

  -- DO NOT OUTPUT IDENTICAL MESSAGES anywhere else.

  --

  -- Examples:

  -- endsim(pltbutils_sc);

  -- endsim(pltbutils_sc, true);

  -- endsim(pltbutils_sc, true, true);

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

  procedure endsim(

    signal   pltbutils_sc       : out pltbutils_sc_t;

    constant show_success_fail  : in  boolean := false;

    constant force              : in  boolean := false

  ) is

    variable l : line;

  begin

    printv(v_pltbutils_info, "");

    print(lf & "--- END OF SIMULATION ---");

    print("Note: the results presented below are based on the PlTbUtil's check() procedure calls.");

    print("      The design may contain more errors, for which there are no check() calls.");

    write(l, now, right, 14);

    writeline(output, l);

    write(l, v_pltbutils_chk_cnt.value, right, 11); -- VHDL-2002

    --write(l, v_pltbutils_chk_cnt, right, 11); -- VHDL-1993

    write(l, string'(" Checks"));

    writeline(output, l);

    write(l, v_pltbutils_err_cnt.value, right, 11); -- VHDL-2002

    --write(l, v_pltbutils_chk_cnt, right, 11); -- VHDL-1993

    write(l, string'(" Errors"));

    writeline(output, l);

    if show_success_fail then

       if v_pltbutils_err_cnt.value = 0 and v_pltbutils_chk_cnt.value > 0 then -- VHDL-2002

       --if v_pltbutils_err_cnt = 0 and v_pltbutils_chk_cnt > 0 then -- VHDL-1993

        print("*** SUCCESS ***");

      elsif v_pltbutils_chk_cnt.value > 0 then -- VHDL-2002

      --elsif v_pltbutils_chk_cnt > 0 then -- VHDL-1993

        print("*** FAIL ***");

      else

        print("*** NO CHECKS ***");

      end if;

    end if;

    -- VHDL-2002:

    v_pltbutils_stop_sim.set('1');

    v_pltbutils_test_num.clr;

    v_pltbutils_test_name.set("END OF SIMULATION");

    -- VHDL-1993:

    --v_pltbutils_stop_sim := '1';

    --v_pltbutils_test_num := 0;

    --printv(v_pltbutils_test_name, "END OF SIMULATION");

    pltbutils_sc_update(pltbutils_sc);

    wait for C_WAIT_BEFORE_STOP_TIME;

    stop(0); -- VHDL-2008

    assert not force

    report "--- FORCE END OF SIMULATION ---" &

           " (ignore this false failure message, it's not a real failure)"

    severity failure;

    wait;

  end procedure endsim;

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

  -- testname

  --

  -- procedure testname(

  --   constant num                : in    integer := -1;

  --   constant name               : in    string;

  --   signal   pltbutils_sc       : out   pltbutils_sc_t

  -- ) 

  --

  -- Sets a number (optional) and a name for a test. The number and name will

  -- be printed to the screen, and displayed in the simulator's waveform

  -- window. 

  -- The test number and name is also included if there errors reported by the

  -- check() procedure calls.

  --

  -- Arguments: 

  --   num                      Test number. Optional, default is to increment

  --                            the current test number.

  --

  --   name                     Test name.

  --

  --   pltbutils_sc             PlTbUtils' global status- and control signal.

  --                            Must be set to pltbutils_sc.

  --

  -- If the test number is omitted, a new test number is automatically

  -- computed by incrementing the current test number. 

  -- Manually setting the test number may make it easier to find the test code

  -- in the testbench code, though.

  --

  -- Examples:

  -- testname("Reset test", pltbutils_sc);

  -- testname(1, "Reset test", pltbutils_sc);

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

  procedure testname(

    constant num                : in    integer := -1;

    constant name               : in    string;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  ) is

  begin

    -- VHDL-2002:

    if num = -1 then

      v_pltbutils_test_num.inc;

    else

      v_pltbutils_test_num.set(num);

    end if;

    v_pltbutils_test_name.set(name);

    pltbutils_sc_update(pltbutils_sc);

    print("Test " & str(v_pltbutils_test_num.value) & ": " & name);

    -- VHDL-1993:

    --if num = -1 then

    --  b_pltbutils_test_num := v_pltbutils_test_num + 1;

    --else

    --  v_pltbutils_test_num  := num;

    --end if;

    --printv(v_pltbutils_test_name, name);

    --pltbutils_sc_update(pltbutils_sc);

    --print("Test " & str(v_pltbutils_test_num) & ": " & name);

  end procedure testname;

  procedure testname(

    constant name               : in    string;

    signal   pltbutils_sc       : out   pltbutils_sc_t

  ) is

  begin

    testname(-1, name, pltbutils_sc);

  end procedure testname;

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

  -- print printv print2

  --

  -- procedure print(   

  --   signal   s                  : out   string;

  --   constant txt                : in    string

  -- ) 

  --

  -- procedure print(   

  --   constant active             : in    boolean;

  --   signal   s                  : out   string;

  --   constant txt                : in    string

  -- ) 

  --

  -- procedure print(

  --   signal   pltbutils_sc       : out   pltbutils_sc_t;

  --   constant txt                : in    string

  -- )

  --

  -- procedure print(

  --   constant active             : in    boolean;

  --   signal   pltbutils_sc       : out   pltbutils_sc_t;

  --   constant txt                : in    string

  -- )

  --

  -- procedure printv(

  --   variable s                  : out   string;

  --   constant txt                : in    string

  -- )

  --

  -- procedure printv(

  --   constant active             : in    boolean;

  --   variable s                  : out   string;

  --   constant txt                : in    string

  -- )

  --

  -- procedure print2(    

  --   signal   s                  : out   string;

  --   constant txt                : in    string

  -- )

  --

  -- procedure print2(    

  --   constant active             : in    boolean;

  --   signal   s                  : out   string;

  --   constant txt                : in    string

  -- )

  --

  -- procedure print2(    

  --   signal   pltbutils          : out   pltbutils_sc_t;

  --   constant txt                : in    string

  -- )

  --

  -- procedure print2(    

  --   constant active             : in    boolean;

  --   signal   pltbutils          : out   pltbutils_sc_t;

  --   constant txt                : in    string

  -- )

  --

  -- print() prints text messages to a signal for viewing in the simulator's

  -- waveform window. printv() does the same thing, but to a variable instead.

  -- print2() prints both to a signal and to the transcript window. 

  -- The type of the output can be string or pltbutils_sc_t.

  -- If the type is pltbutils_sc_t, the name can be no other than pltbutils_sc.

  --

  -- Arguments: 

  --   s                        Signal or variable of type string to be 

  --                            printed to.

  --

  --   txt                      The text.

  --

  --   active                   The text is only printed if active is true.

  --                            Useful for debug switches, etc.

  --

  --   pltbutils_sc             PlTbUtils' global status- and control signal 

  --                            of type pltbutils_sc_t. 

  --                            The name must be no other than pltbutils_sc.

  --

  -- If the string txt  is longer than the signal s, the text will be truncated.

  -- If txt  is shorter, s will be padded with spaces.

  --

  -- Examples:

  -- print(msg, "Hello, world"); -- Prints to signal msg

  -- print(G_DEBUG, msg, "Hello, world"); -- Prints to signal msg if 

  --                                      -- generic G_DEBUG is true

  -- printv(v_msg, "Hello, world"); -- Prints to variable msg

  -- print(pltbutils_sc, "Hello, world"); -- Prints to "info" in waveform window

  -- print2(msg, "Hello, world"); -- Prints to signal and transcript window 

  -- print(pltbutils_sc, "Hello, world"); -- Prints to "info" in waveform and

  --                                      -- transcript windows

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

  procedure print(

    constant active             : in    boolean;

    signal   s                  : out   string;

    constant txt                : in    string

  ) is

    variable j : positive := txt 'low;

  begin

    if active then

      for i in s'range loop

        if j <= txt 'high then

          s(i) <= txt (j);

        else

          s(i) <= ' ';

        end if;

        j := j + 1;

      end loop;

    end if;

  end procedure print;

  procedure print(

    signal   s                  : out   string;

    constant txt                : in    string

  ) is

  begin

    print(true, s, txt);

  end procedure print;

  procedure printv(

    constant active             : in    boolean;

    variable s                  : out   string;

    constant txt                : in    string

  ) is

    variable j : positive := txt 'low;

  begin

    if active then

      for i in s'range loop

        if j <= txt 'high then

          s(i) := txt (j);

        else

          s(i) := ' ';

        end if;

        j := j + 1;

      end loop;

    end if;