ift - User contributions [en]

Bitvis UVVM VHDL Verification Component Framework

2017-01-25T14:28:52Z

Ogr043: /* What's in the folders? */

This wiki page is heavily based on the Powerpoint-presentation found [http://bitvis.no/media/15298/Simple_TB_step_by_step.pps here].<ref>UVVM LICENSE AGREEMENT
IMPORTANT - READ BEFORE USING OR COPYING.
THIS IS THE MIT LICENSE, see https://opensource.org/licenses/MIT
------------------------------------------------------------------

Copyright (c) 2016 by Bitvis AS

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of
the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</ref>

== Introduction ==

Bitvis UVVM VVC Framework is a complete framework for making VHDL testbenches for
verification of FPGA and ASIC desing. You can download the complete code-base, examples and simulations scripts from the [http://bitvis.no/products/uvvm-vvc-framework/ Bitvis web page].

=== What's in the folders? ===
[[File:20160302215840!1.png|thumb]]

The download includes severals folders:
* bitvis_irqc - example VHDL design + testbench
* bitvis_uart - example VHDL design + testbench
* bitvis_vip_sbi - Verification IP(VIP) for simple bus interface(SBI)
* bitvis_vip_uart - VIP for UART TX and RX
* uvvm_util - UVVM utility library - sufficient for simple testbenches
* uvvm_vvc_framework - Framework for more advanced tutorials

=== IRQC ===
[[File:irqc.png|thumb]]
The provided example VHDL design is a simple interrupt controller with several internal registers, a bus interface and some input and output signals.

[[File:irqc2.png|350px]]

== UVVM Utility Library - Testbench creation ==
Copy the folders bitvis_irqc, bitvis_vip_sbi and uvvm_util to another location before editing the files.
=== Generate TB entity with DUT instantiated ===
Our TB entity can in many cases be generated from several tools. Notepad++ (among other) supports plugins that enables copying an entity and pasting it as an instantiation, and also as a complete testbench template. However, we will change some of our signals so that they fit the VIP SBI BFM. The signals to and from the CPU will be converted to t_sbi_if record, which is a type that includes all the SBI signals (cs, addr, rd, wr, wdata, ready and rdata).

<pre>
--Standard libraries
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;

-- Library enabling control of the simulation from VHDL. Eg. std.env.stop
library STD;
use std.env.all;

-- Obviously the UVVM library
library uvvm_util;
context uvvm_util.uvvm_util_context;

-- We will use this library later when implementing the Bus Functional Model
-- Includes among much else the record type t_sbi_if and many functions
-- If other buses are used, you will have to change this library
library bitvis_vip_sbi;
use bitvis_vip_sbi.sbi_bfm_pkg.all;

-- This file includes definitions of everything from registers to record types
use work.irqc_pif_pkg.all;

-- Test case entity
entity irqc_tb is
end entity;

-- Test case architecture
architecture func of irqc_tb is

-- DSP interface and general control signals
signal clk : std_logic := '0';
signal arst : std_logic := '0';
-- CPU interface
-- t_sbi_if is from the verification IP SBI
-- init_sbi_if_signals initialize the inputs to 0 and the outputs to Z
signal sbi_if : t_sbi_if(addr(2 downto 0), wdata(7 downto 0), rdata(7 downto 0)) := init_sbi_if_signals(3, 8);

-- Interrupt related signals
signal irq_source : std_logic_vector(C_NUM_SOURCES-1 downto 0) := (others => '0');
signal irq2cpu : std_logic := '0';
signal irq2cpu_ack : std_logic := '0';

begin

-----------------------------------------------------------------------------
-- Instantiate DUT
-----------------------------------------------------------------------------
i_irqc: entity work.irqc
port map (
-- DSP interface and general control signals
clk => clk,
arst => arst,
-- CPU interface
cs => sbi_if.cs, -- NOTICE THE SIGNALS ARE NOW SBI_IF
addr => sbi_if.addr,
wr => sbi_if.wr,
rd => sbi_if.rd,
din => sbi_if.wdata,
dout => sbi_if.rdata,
-- Interrupt related signals
irq_source => irq_source,
irq2cpu => irq2cpu,
irq2cpu_ack => irq2cpu_ack
);

end func;
</pre>

=== Add support process for clock generation ===
We now have to add a support process that controls the clock. This has to allow enabling/disabling from the test sequencer. We add the following before "begin" in our architecture:
<pre>
-- Added for clock generation
signal clock_ena : boolean := false;

constant C_CLK_PERIOD : time := 10 ns;

procedure clock_gen(
signal clock_signal : inout std_logic;
signal clock_ena : in boolean;
constant clock_period : in time
) is
variable v_first_half_clk_period : time := C_CLK_PERIOD / 2;
begin
loop
if not clock_ena then
wait until clock_ena;
end if;
wait for v_first_half_clk_period;
clock_signal <= not clock_signal;
wait for (clock_period - v_first_half_clk_period);
clock_signal <= not clock_signal;
end loop;
end;
</pre>

Our clock can now be activated from the test sequencer (this will be added in the next step):
<pre>
-- After begin in the architecture
clock_gen(clk, clock_ena, C_CLK_PERIOD);

-- Inside the test sequencer process
clock_ena <= true;
</pre>

=== Add test sequencer process ===
The next step is to add the test sequencer process. This process controls everything from initialization to termination of the simulation.

<pre>
-- Set upt clock generator
clock_gen(clk, clock_ena, C_CLK_PERIOD);

------------------------------------------------
-- PROCESS: p_main
------------------------------------------------
p_main : process
-- The scope tells you where log messages originates - C_SCOPE tells us they originate from the default test sequencer scope
constant C_SCOPE : string := C_TB_SCOPE_DEFAULT;
-- This is where we will add some procedures later to simplify the tests

begin

--Print the configuration to the log
report_global_ctrl(VOID);
report_msg_id_panel(VOID);

enable_log_msg(ALL_MESSAGES);
--disable_log_msg
--enable_log_msg(ID_LOG_HDR);

log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
------------------------------------------------------------
clock_ena <= true; -- to start clock generator

------------------------------------------------------------
-- End the simulation
wait for 1000 ns; -- to allow some time for completion
report_alert_counters(FINAL); -- Report final counters and print conclusion for simulation (Success/Fail)
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);

--Finish the simulation
std.env.stop;
wait; -- to stop completely
end process p_main;
</pre>

==Simulation==
We now have the skeleton of the testbench, which we will develop further. But now, let's see if everything works. Bitvis have created simulation scripts for the IRQC example that compiles everything we need, from the source files of the VHDL design, to the testbench (if you called the file irqc_tb.vhd and placed it in the tb-folder) and the SBI BFM and the UVVM library. Open up QuestaSim/ModelSim.
Change directory to the script folder:
<pre>
cd ~/phys321/bitviswiki/bitvis_irqc/script
do compile_and_sim_all.do
</pre>

This will present our result in the transcript windows, but also write _Log.txt file which includes all the information we have asked for. We see that we get the results from the following code:
<pre>
report_global_ctrl(VOID);
report_msg_id_panel(VOID);
enable_log_msg(ALL_MESSAGES);
log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
report_alert_counters(FINAL);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
</pre>
Commenting these out will result in an empty log.

== Verbosity control ==
We want to able to control the amount of information in our logs, and the framework enables us to prioritize messages based on ID. This makes it easy to turn on or off the information we want.
To turn on a specific ID
<pre>
enable_log_msg(IDNAME);
</pre>

Turn off:
<pre>
disable_log_msg(IDNAME);
</pre>

For writing a message to a certain log ID:
<pre>
log(IDNAME, "MESSAGE HERE", C_SCOPE);
</pre>
Remember that C_SCOPE just tells us that the message originated from the default scope and will look like "TB seq." in the log file.

Exampled IDs:
* ID_LOG_HDR, -- ONLY allowed in test sequencer, Log section headers
* ID_SEQUENCER, -- ONLY allowed in test sequencer, Normal log (not log headers)
* ID_BFM, -- Used inside a BFM (to log BFM access)
* ID_CLOCK_GEN, -- Used for logging when clock generators are enabled or disabled
* ALL_MESSAGES -- Applies to ALL message ID apart from ID_NEVER

You'll find all the different ID's in the UVVM Utility Library Quick Reference or defined in uvvm_util/adaptions_pkg.vhd. This also where C_TB_SCOPE_DEFAULT is defined.

== Implement first tests ==
[[File:tb.png|thumb|upright=0.35]]
We want to check and verify that our testbench is up and running and to verify our first tests of the DUT. This means that we have to able to set all our signals passive, apply a reset signal and then check the default outputs of the DUT.

Instead of setting all our signals passive one-by-one in our test sequencer we declare a procedure in our p_main process(this is done before begin):
<pre>
procedure set_inputs_passive(
dummy : t_void) is --dummy variable is included only to allow calling the procedure with parenthesis for readability
begin
sbi_if.cs <= '0';
sbi_if.addr <= (others => '0');
sbi_if.wr <= '0';
sbi_if.rd <= '0';
sbi_if.wdata <= (others => '0');
irq_source <= (others => '0');
irq2cpu_ack <= '0';
log(ID_SEQUENCER_SUB, "All inputs set passive", C_SCOPE);
end;
</pre>

Note that the procedure declaration also includes a dummy variable parameter. This means that we will be able to call the procedure with the more readable:

<pre>
set_inputs_passive(VOID);
</pre>

Rather than:
<pre>
set_inputs_passive;
</pre>
which is more ambigious.

We may also would like to send pulses on different signals, f.ex. sending a pulse on our reset to see if it behaves like intended. We therefore can include a pulse procedure:
<pre>
procedure pulse(
signal target : inout std_logic_vector;
constant pulse_value : in std_logic_vector;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= pulse_value;
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= pulse_value;
wait for 0 ns; -- Delta cycle only
end if;
target(target'range) <= (others => '0');
log(ID_SEQUENCER_SUB, "Pulsed to " & to_string(pulse_value, HEX, AS_IS, INCL_RADIX) & ". " & msg, C_SCOPE);
end;
</pre>

In the above example the test sequencer is required to inform the procedure of what value the pulse is to take. The call to the procedure would take the following form:
<pre>
pulse(arst, 'Z', clk, 10, "Log message - Im pulsing the value 'Z'");
</pre>
But a more specific overload can be created where pulse always takes value '1':
<pre>
procedure pulse(
signal target : inout std_logic;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string
) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= '1';
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= '1';
wait for 0 ns; -- Delta cycle only
end if;
target <= '0';
log(ID_SEQUENCER_SUB, msg, C_SCOPE);
end;
</pre>

These procedures can now be called directly from our test sequence:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "pulsed reset-signal - active for 10T");
</pre>

To check signal values we can use the built-in check function check_value():
<pre>
check_value(irq2cpu, 'X', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
</pre>
The above call checks if the signal irq2cpu is 'X', and obviously fail if everything works correctly and gives the following message:

[[File:error.png|700px]]

If we want we can change the number of errors logged before the simulation stops:
<pre>
set_alert_stop_limit(ERROR, 3);
</pre>

We now have all the tools needed for the first tests in our sequencer:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "Pulsed reset-signal - active for 10T");

check_value(C_NUM_SOURCES > 0, FAILURE, "Must be at least 1 interrupt source", C_SCOPE);
check_value(C_NUM_SOURCES <= 8, TB_WARNING, "This TB is only checking IRQC with up to 8 interrupt sources", C_SCOPE);

log(ID_LOG_HDR, "Check defaults on output ports", C_SCOPE);
------------------------------------------------------------
check_value(irq2cpu, '0', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
check_value(sbi_if.rdata, x"00", ERROR, "Register data bus output must be default passive");
</pre>

This will give us the following log:

[[File:sim.png|800px]]

This information may only interesting initially and for debug, and can be turned on or off by use of ID.

== Subprograms ==
Some of our testbench code will be repeated several times and the testbench may therefore benefit from creating several subprograms. Obvious examples for our IRQC is:
- Register access
- Signal checkers
- Interrupt source pulsing?
- Interrupt acknowledge pulsing?
- (Report/log method)
- (Alert-handling)
- (reset, set_passive, ...)

We've already created and declared set_passive and pulse procedures, but we could f.ex create overloads for UVVM procedures:
<pre>
-- Log overloads for simplification
procedure log(
msg : string) is
begin
log(ID_SEQUENCER, msg, C_SCOPE);
end;
</pre>

Let's say that it is probable that we'll want to change the number of interrupt sources that the controller can handle. We will then want to able to easily change vectors to the appropriate size. One way is to declare procedures that can trim and fit vectors. This way we can simply change a constant to change the number of sources.

<pre>
subtype t_irq_source is std_logic_vector(C_NUM_SOURCES-1 downto 0);

-- Trim (cut) a given vector to fit the number of irq sources (i.e. pot. reduce width)
function trim(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return t_irq_source is
variable v_result : std_logic_vector(source'length-1 downto 0) := source;
begin
return v_result(num_bits-1 downto 0);
end;

-- Fit a given vector to the number of irq sources by masking with zeros above irq width
function fit(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return std_logic_vector is
variable v_result : std_logic_vector(source'length-1 downto 0) := (others => '0');
variable v_source : std_logic_vector(source'length-1 downto 0) := source;
begin
v_result(num_bits-1 downto 0) := v_source(num_bits-1 downto 0);
return v_result;
end;
</pre>

All IRQC-dedicated subprograms should be declared locally, but more common (f.ex bus-specific) should be declared in common package that can be shared with other.

== Register access ==
To access the IRQC's registers we need to go through the actual process of writing and reading data from them. Fortunately, Bitvis have already taken the responsibility of writing the BFM for the SBI. This doesn't mean that we doesn't have to understand what's going on, since we'll have to write our own BFM's for other buses that we use(Avalon, AXI, etc). '''January 2017 Bitvis announced that they released VVC for Avalon-MM and AXI4-lite.''' So we should investigate the BFM procedures. We want to check register values:
<pre>
procedure sbi_check (
constant addr_value : in unsigned;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level := error;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_check";
constant proc_call : string := "sbi_check(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_exp, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
-- Helper variables
variable v_data_value : std_logic_vector(rdata'length - 1 downto 0);
variable v_check_ok : boolean;
variable v_clk_cycles_waited : natural := 0;
begin
sbi_read(addr_value, v_data_value, msg, clk, cs, addr, rd, wr, ready, rdata, scope, msg_id_panel, config, proc_name);

-- Compare values, but ignore any leading zero's if widths are different.
-- Use ID_NEVER so that check_value method does not log when check is OK,
-- log it here instead.
v_check_ok := check_value(v_data_value, data_exp, alert_level, msg, scope, HEX_BIN_IF_INVALID, SKIP_LEADING_0, ID_NEVER, msg_id_panel, proc_call);
if v_check_ok then
log(config.id_for_bfm, proc_call & "=> OK, read data = " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
end if;
end procedure;
</pre>

We see that sbi_check() calls sbi_read() before it checks if the read value is the expected value.

<pre>
procedure sbi_read (
constant addr_value : in unsigned;
variable data_value : out std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT;
constant proc_name : in string := "sbi_read" -- overwrite if called from other procedure like sbi_check
) is
constant proc_call : string := "sbi_read(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_data_value : std_logic_vector(data_value'range);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '0';
rd <= '1';
addr <= v_normalised_addr;
wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
rd <= '0';
v_data_value := rdata;
data_value := v_data_value;
if proc_name = "sbi_read" then
log(config.id_for_bfm, proc_call & "=> " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
else
-- Log will be handled by calling procedure (e.g. sbi_check)
end if;
end procedure;
</pre>

We don't want to (and probably shouldnt) call the sbi_check and providing all the parameters each time. Some of this can be solved by the overloads with more standard parameters, and with our own check procedures declared locally in our testbench:
<pre>
procedure check(
constant addr_value : in natural;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level;
constant msg : in string) is
begin
sbi_check(to_unsigned(addr_value, sbi_if.addr'length), data_exp, alert_level, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

The write procedure is also very handy and should be understood:
<pre>
procedure sbi_write (
constant addr_value : in unsigned;
constant data_value : in std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal wdata : inout std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_write";
constant proc_call : string := "sbi_write(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalise to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_normalised_data : std_logic_vector(wdata'length-1 downto 0) :=
normalize_and_check(data_value, wdata, ALLOW_NARROWER, "data_value", "sbi_core_in.wdata", msg);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '1';
rd <= '0';
addr <= v_normalised_addr;
wdata <= v_normalised_data;

wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
wr <= '0';
log(config.id_for_bfm, proc_call & " completed. " & msg, scope, msg_id_panel);
end procedure;
</pre>

We will create a local overload of this too:
<pre>
procedure write(
constant addr_value : in natural;
constant data_value : in std_logic_vector;
constant msg : in string) is
begin
sbi_write(to_unsigned(addr_value, sbi_if.addr'length), data_value, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

All this enables us to handle transactions at a high level. See Bitvis documentation for how to write your own BFM and what it should include(sanity checks, etc).

[[File:bfm.png|550px]]

== Checking register write and read ==
Now we're enabled to write to and read from the registers. The register addresses are defined in the IRQC package file irqc_pif_bkg.vhd. Notice that we also use the previously declared overloaded version of log() and fit().

<pre>
log(ID_LOG_HDR, "Check register defaults and access (write + read)", C_SCOPE);
------------------------------------------------------------
log("\nChecking Register defaults");
check(C_ADDR_IRR, x"00", ERROR, "IRR default");
check(C_ADDR_IER, x"00", ERROR, "IER default");
check(C_ADDR_IPR, x"00", ERROR, "IPR default");
check(C_ADDR_IRQ2CPU_ALLOWED, x"00", ERROR, "IRQ2CPU_ALLOWED default");

log("\nChecking Register Write/Read");
write(C_ADDR_IER, fit(x"55"), "IER");
check(C_ADDR_IER, fit(x"55"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"AA"), "IER");
check(C_ADDR_IER, fit(x"AA"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"00"), "IER");
check(C_ADDR_IER, fit(x"00"), ERROR, "IER pure readback");
</pre>

This check will give us a nice log if everything turns out ok:

[[File:sim2.png|700px]]

However, if there's an error:

[[File:error2.png|700px]]

== Further tests ==

Now that we've tested register read/write, we should test the trigger/clear mechanism. No further adding of procedures are necessary.
<pre>
log(ID_LOG_HDR, "Check register trigger/clear mechanism", C_SCOPE);
------------------------------------------------------------
write(C_ADDR_ITR, fit(x"AA"), "ITR : Set interrupts");
check(C_ADDR_IRR, fit(x"AA"), ERROR, "IRR");
write(C_ADDR_ITR, fit(x"55"), "ITR : Set more interrupts");
check(C_ADDR_IRR, fit(x"FF"), ERROR, "IRR");
write(C_ADDR_ICR, fit(x"71"), "ICR : Clear interrupts");
check(C_ADDR_IRR, fit(x"8E"), ERROR, "IRR");
write(C_ADDR_ICR, fit(x"85"), "ICR : Clear interrupts");
check(C_ADDR_IRR, fit(x"0A"), ERROR, "IRR");
write(C_ADDR_ITR, fit(x"55"), "ITR : Set more interrupts");
check(C_ADDR_IRR, fit(x"5F"), ERROR, "IRR");
write(C_ADDR_ICR, fit(x"5F"), "ICR : Clear interrupts");
check(C_ADDR_IRR, fit(x"00"), ERROR, "IRR");
</pre>

The UVVM Utility Library provides all necessary functions and procedures to do further tests. F.ex. we should send pulses on the irq_source signal to check if the design behaves correctly.

<pre>
log(ID_LOG_HDR, "Check interrupt sources, IER, IPR and irq2cpu", C_SCOPE);
------------------------------------------------------------
log("\nChecking interrupts and IRR");
write(C_ADDR_ICR, fit(x"FF"), "ICR : Clear all interrupts");
pulse(irq_source, trim(x"AA"), clk, 1, "Pulse irq_source 1T");
check(C_ADDR_IRR, fit(x"AA"), ERROR, "IRR after irq pulses");
pulse(irq_source, trim(x"01"), clk, 1, "Add more interrupts");
check(C_ADDR_IRR, fit(x"AB"), ERROR, "IRR after irq pulses");
pulse(irq_source, trim(x"A1"), clk, 1, "Repeat same interrupts");
check(C_ADDR_IRR, fit(x"AB"), ERROR, "IRR after irq pulses");
pulse(irq_source, trim(x"54"), clk, 1, "Add remaining interrupts");
check(C_ADDR_IRR, fit(x"FF"), ERROR, "IRR after irq pulses");
write(C_ADDR_ICR, fit(x"AA"), "ICR : Clear half the interrupts");
pulse(irq_source, trim(x"A0"), clk, 1, "Add more interrupts");
check(C_ADDR_IRR, fit(x"F5"), ERROR, "IRR after irq pulses");
write(C_ADDR_ICR, fit(x"FF"), "ICR : Clear all interrupts");
check(C_ADDR_IRR, fit(x"00"), ERROR, "IRR after clearing all");
</pre>

=== Check stable ===
Another test provided by UVVM is check_stable(). This function enables us to test if a signal is holding the same value for a minimum provided time. We must declare a variable that holds the time from which we want to test if the signal is stable:

<pre>
v_time_stamp := now; -- time from which irq2cpu should be stable off until triggered
</pre>

Later we're now able to test if the signal has been holding the same value the whole period:
<pre>
check_stable(irq2cpu, (now - v_time_stamp), ERROR, "No spikes allowed on irq2cpu", C_SCOPE);
</pre>

Remember to declare the variable in the process:

<pre>
variable v_time_stamp : time := 0 ns;
</pre>

=== Await value ===
To check if a signal gets the expected value within a specified time value we use await_vale(). The test below throws an error if irq2cpu doesn't obtain the value '1' within 0 ns(!). Therefore expected immediately:

<pre>
await_value(irq2cpu, '1', 0 ns, C_CLK_PERIOD, ERROR, "Interrupt expected immediately", C_SCOPE);
</pre>

=== Other useful functions ===

Check the UVVM Utility Library Quick Reference for syntax details.

==== await_change() ====
Expects and waits for a change on the given signal, inside a given time window.

==== check_value_in_range() ====
Throws an error of the signal value is outside the specified minimum and maximum values.

== UVVM VVC ==
Guide coming....

== UVVM LICENCE AGREEMENT ==
{{reflist}}

2016-04-12T10:20:22Z

Ogr043: File uploaded with MsUpload

File uploaded with MsUpload

Layout XL and IHP SG13S

2016-04-12T10:15:03Z

Ogr043:

Layout XL and IHP SG13S

2016-04-12T10:14:43Z

Ogr043:

File:Partial2.png

2016-04-12T10:14:21Z

Ogr043: File uploaded with MsUpload

File uploaded with MsUpload

File:Partial.png

2016-04-12T10:14:21Z

Ogr043: File uploaded with MsUpload

File uploaded with MsUpload

File:Pinplacement.png

2016-04-12T10:06:18Z

Ogr043: File uploaded with MsUpload

File uploaded with MsUpload

File:Result.png

2016-04-12T09:59:58Z

Ogr043: File uploaded with MsUpload

File uploaded with MsUpload

2016-01-28T15:20:54Z

Ogr043:

This wiki page is heavily based on the Powerpoint-presentation found [http://bitvis.no/media/15298/Simple_TB_step_by_step.pps here].<ref>''LibreOffice For Starters'', First Edition, Flexible Minds, Manchester, 2002, p. 18</ref>

== Introduction ==

Bitvis UVVM VVC Framework is a complete framework for making VHDL testbenches for
verification of FPGA and ASIC desing. You can download the complete code-base, examples and simulations scripts from the [http://bitvis.no/products/uvvm-vvc-framework/ Bitvis web page].

=== What's in the folders? ===
[[File:1.png|thumb]]

The download includes severals folders:
* bitvis_irqc - example VHDL design + testbench
* bitvis_uart - example VHDL design + testbench
* bitvis_vip_sbi - Verification IP(VIP) for simple bus interface(SBI)
* bitvis_vip_uart - VIP for UART TX and RX
* uvvm_util - UVVM utility library - sufficient for simple testbenches
* uvvm_vvc_framework - Framework for more advanced tutorials

=== IRQC ===
[[File:irqc.png|thumb]]
The provided example VHDL design is a simple interrupt controller with several internal registers, a bus interface and some input and output signals.

[[File:irqc2.png|350px]]

== Testbench creation ==
Copy the folders bitvis_irqc, bitvis_vip_sbi and uvvm_util to another location before editing the files.
=== Generate TB entity with DUT instantiated ===
Our TB entity can in many cases be generated from several tools. Notepad++ (among other) supports plugins that enables copying an entity and pasting it as an instantiation, and also as a complete testbench template. However, we will change some of our signals so that they fit the VIP SBI BFM. The signals to and from the CPU will be converted to t_sbi_if record, which is a type that includes all the SBI signals (cs, addr, rd, wr, wdata, ready and rdata).

<pre>
--Standard libraries
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;

-- Libraries used for string handling in UVVM
library STD;
use std.env.all;

-- Obviously the UVVM library
library uvvm_util;
context uvvm_util.uvvm_util_context;

-- We will use this library later when implementing the Bus Functional Model
-- Includes among much else the record type t_sbi_if and many functions
-- If other buses are used, you will have to change this library
library bitvis_vip_sbi;
use bitvis_vip_sbi.sbi_bfm_pkg.all;

-- This file includes definitions of everything from registers to record types
use work.irqc_pif_pkg.all;

-- Test case entity
entity irqc_tb is
end entity;

-- Test case architecture
architecture func of irqc_tb is

-- DSP interface and general control signals
signal clk : std_logic := '0';
signal arst : std_logic := '0';
-- CPU interface
-- t_sbi_if is from the verification IP SBI
-- init_sbi_if_signals initialize the inputs to 0 and the outputs to Z
signal sbi_if : t_sbi_if(addr(2 downto 0), wdata(7 downto 0), rdata(7 downto 0)) := init_sbi_if_signals(3, 8);

-- Interrupt related signals
signal irq_source : std_logic_vector(C_NUM_SOURCES-1 downto 0) := (others => '0');
signal irq2cpu : std_logic := '0';
signal irq2cpu_ack : std_logic := '0';

begin

-----------------------------------------------------------------------------
-- Instantiate DUT
-----------------------------------------------------------------------------
i_irqc: entity work.irqc
port map (
-- DSP interface and general control signals
clk => clk,
arst => arst,
-- CPU interface
cs => sbi_if.cs, -- NOTICE THE SIGNALS ARE NOW SBI_IF
addr => sbi_if.addr,
wr => sbi_if.wr,
rd => sbi_if.rd,
din => sbi_if.wdata,
dout => sbi_if.rdata,
-- Interrupt related signals
irq_source => irq_source,
irq2cpu => irq2cpu,
irq2cpu_ack => irq2cpu_ack
);

end func;
</pre>

=== Add support process for clock generation ===
We now have to add a support process that controls the clock. This has to allow enabling/disabling from the test sequencer. We add the following before "begin" in our architecture:
<pre>
-- Added for clock generation
signal clock_ena : boolean := false;

constant C_CLK_PERIOD : time := 10 ns;

procedure clock_gen(
signal clock_signal : inout std_logic;
signal clock_ena : in boolean;
constant clock_period : in time
) is
variable v_first_half_clk_period : time := C_CLK_PERIOD / 2;
begin
loop
if not clock_ena then
wait until clock_ena;
end if;
wait for v_first_half_clk_period;
clock_signal <= not clock_signal;
wait for (clock_period - v_first_half_clk_period);
clock_signal <= not clock_signal;
end loop;
end;
</pre>

Our clock can now be activated from the test sequencer (this will be added in the next step):
<pre>
-- After begin in the architecture
clock_gen(clk, clock_ena, C_CLK_PERIOD);

-- Inside the test sequencer process
clock_ena <= true;
</pre>

=== Add test sequencer process ===
The next step is to add the test sequencer process. This process controls everything from initialization to termination of the simulation.

<pre>
-- Set upt clock generator
clock_gen(clk, clock_ena, C_CLK_PERIOD);

------------------------------------------------
-- PROCESS: p_main
------------------------------------------------
p_main : process
-- The scope tells you where log messages originates - C_SCOPE tells us they originate from the default test sequencer scope
constant C_SCOPE : string := C_TB_SCOPE_DEFAULT;
-- This is where we will add some procedures later to simplify the tests

begin

--Print the configuration to the log
report_global_ctrl(VOID);
report_msg_id_panel(VOID);

enable_log_msg(ALL_MESSAGES);
--disable_log_msg
--enable_log_msg(ID_LOG_HDR);

log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
------------------------------------------------------------
clock_ena <= true; -- to start clock generator

------------------------------------------------------------
-- End the simulation
wait for 1000 ns; -- to allow some time for completion
report_alert_counters(FINAL); -- Report final counters and print conclusion for simulation (Success/Fail)
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);

--Finish the simulation
std.env.stop;
wait; -- to stop completely
end process p_main;
</pre>

==Simulation==
We now have the skeleton of the testbench, which we will develop further. But now, let's see if everything works. Bitvis have created simulation scripts for the IRQC example that compiles everything we need, from the source files of the VHDL design, to the testbench (if you called the file irqc_tb.vhd and placed it in the tb-folder) and the SBI BFM and the UVVM library. Open up QuestaSim/ModelSim.
Change directory to the script folder:
<pre>
cd ~/phys321/bitviswiki/bitvis_irqc/script
do compile_and_sim_all.do
</pre>

This will present our result in the transcript windows, but also write _Log.txt file which includes all the information we have asked for. We see that we get the results from the following code:
<pre>
report_global_ctrl(VOID);
report_msg_id_panel(VOID);
enable_log_msg(ALL_MESSAGES);
log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
report_alert_counters(FINAL);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
</pre>
Commenting these out will result in an empty log.

== Verbosity control ==
We want to able to control the amount of information in our logs, and the framework enables us to prioritize messages based on ID. This makes it easy to turn on or off the information we want.
To turn on a specific ID
<pre>
enable_log_msg(IDNAME);
</pre>

Turn off:
<pre>
disable_log_msg(IDNAME);
</pre>

For writing a message to a certain log ID:
<pre>
log(IDNAME, "MESSAGE HERE", C_SCOPE);
</pre>
Remember that C_SCOPE just tells us that the message originated from the default scope and will look like "TB seq." in the log file.

Exampled IDs:
* ID_LOG_HDR, -- ONLY allowed in test sequencer, Log section headers
* ID_SEQUENCER, -- ONLY allowed in test sequencer, Normal log (not log headers)
* ID_BFM, -- Used inside a BFM (to log BFM access)
* ID_CLOCK_GEN, -- Used for logging when clock generators are enabled or disabled
* ALL_MESSAGES -- Applies to ALL message ID apart from ID_NEVER

You'll find all the different ID's in the UVVM Utility Library Quick Reference or defined in uvvm_util/adaptions_pkg.vhd. This also where C_TB_SCOPE_DEFAULT is defined.

== Implement first tests ==
[[File:tb.png|thumb|upright=0.35]]
We want to check and verify that our testbench is up and running and to verify our first tests of the DUT. This means that we have to able to set all our signals passive, apply a reset signal and then check the default outputs of the DUT.

Instead of setting all our signals passive one-by-one in our test sequencer we declare a procedure in our p_main process(this is done before begin):
<pre>
procedure set_inputs_passive(
dummy : t_void) is --dummy variable is included only to allow calling the procedure with parenthesis for readability
begin
sbi_if.cs <= '0';
sbi_if.addr <= (others => '0');
sbi_if.wr <= '0';
sbi_if.rd <= '0';
sbi_if.wdata <= (others => '0');
irq_source <= (others => '0');
irq2cpu_ack <= '0';
log(ID_SEQUENCER_SUB, "All inputs set passive", C_SCOPE);
end;
</pre>

Note that the procedure declaration also includes a dummy variable parameter. This means that we will be able to call the procedure with the more readable:

<pre>
set_inputs_passive(VOID);
</pre>

Rather than:
<pre>
set_inputs_passive;
</pre>
which is more ambigious.

We may also would like to send pulses on different signals, f.ex. sending a pulse on our reset to see if it behaves like intended. We therefore can include a pulse procedure:
<pre>
procedure pulse(
signal target : inout std_logic_vector;
constant pulse_value : in std_logic_vector;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= pulse_value;
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= pulse_value;
wait for 0 ns; -- Delta cycle only
end if;
target(target'range) <= (others => '0');
log(ID_SEQUENCER_SUB, "Pulsed to " & to_string(pulse_value, HEX, AS_IS, INCL_RADIX) & ". " & msg, C_SCOPE);
end;
</pre>

In the above example the test sequencer is required to inform the procedure of what value the pulse is to take. The call to the procedure would take the following form:
<pre>
pulse(arst, 'Z', clk, 10, "Log message - Im pulsing the value 'Z'");
</pre>
But a more specific overload can be created where pulse always takes value '1':
<pre>
procedure pulse(
signal target : inout std_logic;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string
) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= '1';
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= '1';
wait for 0 ns; -- Delta cycle only
end if;
target <= '0';
log(ID_SEQUENCER_SUB, msg, C_SCOPE);
end;
</pre>

These procedures can now be called directly from our test sequence:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "pulsed reset-signal - active for 10T");
</pre>

To check signal values we can use the built-in check function check_value():
<pre>
check_value(irq2cpu, 'X', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
</pre>
The above call checks if the signal irq2cpu is 'X', and obviously fail if everything works correctly and gives the following message:

[[File:error.png|700px]]

If we want we can change the number of errors logged before the simulation stops:
<pre>
set_alert_stop_limit(ERROR, 3);
</pre>

We now have all the tools needed for the first tests in our sequencer:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "Pulsed reset-signal - active for 10T");

check_value(C_NUM_SOURCES > 0, FAILURE, "Must be at least 1 interrupt source", C_SCOPE);
check_value(C_NUM_SOURCES <= 8, TB_WARNING, "This TB is only checking IRQC with up to 8 interrupt sources", C_SCOPE);

log(ID_LOG_HDR, "Check defaults on output ports", C_SCOPE);
------------------------------------------------------------
check_value(irq2cpu, '0', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
check_value(sbi_if.rdata, x"00", ERROR, "Register data bus output must be default passive");
</pre>

This will give us the following log:

[[File:sim.png|800px]]

This information may only interesting initially and for debug, and can be turned on or off by use of ID.

== Subprograms ==
Some of our testbench code will be repeated several times and the testbench may therefore benefit from creating several subprograms. Obvious examples for our IRQC is:
- Register access
- Signal checkers
- Interrupt source pulsing?
- Interrupt acknowledge pulsing?
- (Report/log method)
- (Alert-handling)
- (reset, set_passive, ...)

We've already created and declared set_passive and pulse procedures, but we could f.ex create overloads for UVVM procedures:
<pre>
-- Log overloads for simplification
procedure log(
msg : string) is
begin
log(ID_SEQUENCER, msg, C_SCOPE);
end;
</pre>

Let's say that it is probable that we'll want to change the number of interrupt sources that the controller can handle. We will then want to able to easily change vectors to the appropriate size. One way is to declare procedures that can trim and fit vectors. This way we can simply change a constant to change the number of sources.

<pre>
subtype t_irq_source is std_logic_vector(C_NUM_SOURCES-1 downto 0);

-- Trim (cut) a given vector to fit the number of irq sources (i.e. pot. reduce width)
function trim(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return t_irq_source is
variable v_result : std_logic_vector(source'length-1 downto 0) := source;
begin
return v_result(num_bits-1 downto 0);
end;

-- Fit a given vector to the number of irq sources by masking with zeros above irq width
function fit(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return std_logic_vector is
variable v_result : std_logic_vector(source'length-1 downto 0) := (others => '0');
variable v_source : std_logic_vector(source'length-1 downto 0) := source;
begin
v_result(num_bits-1 downto 0) := v_source(num_bits-1 downto 0);
return v_result;
end;
</pre>

All IRQC-dedicated subprograms should be declared locally, but more common (f.ex bus-specific) should be declared in common package that can be shared with other.

== Register access ==
To access the IRQC's registers we need to go through the actual process of writing and reading data from them. Fortunately, Bitvis have already taken the responsibility of writing the BFM for the SBI. This doesn't mean that we doesn't have to understand what's going on, since we'll have to write our own BFM's for other buses that we use(Avalon, AXI, etc). So we should investigate the BFM procedures. We want to check register values:
<pre>
procedure sbi_check (
constant addr_value : in unsigned;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level := error;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_check";
constant proc_call : string := "sbi_check(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_exp, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
-- Helper variables
variable v_data_value : std_logic_vector(rdata'length - 1 downto 0);
variable v_check_ok : boolean;
variable v_clk_cycles_waited : natural := 0;
begin
sbi_read(addr_value, v_data_value, msg, clk, cs, addr, rd, wr, ready, rdata, scope, msg_id_panel, config, proc_name);

-- Compare values, but ignore any leading zero's if widths are different.
-- Use ID_NEVER so that check_value method does not log when check is OK,
-- log it here instead.
v_check_ok := check_value(v_data_value, data_exp, alert_level, msg, scope, HEX_BIN_IF_INVALID, SKIP_LEADING_0, ID_NEVER, msg_id_panel, proc_call);
if v_check_ok then
log(config.id_for_bfm, proc_call & "=> OK, read data = " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
end if;
end procedure;
</pre>

We see that sbi_check() calls sbi_read() before it checks if the read value is the expected value.

<pre>
procedure sbi_read (
constant addr_value : in unsigned;
variable data_value : out std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT;
constant proc_name : in string := "sbi_read" -- overwrite if called from other procedure like sbi_check
) is
constant proc_call : string := "sbi_read(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_data_value : std_logic_vector(data_value'range);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '0';
rd <= '1';
addr <= v_normalised_addr;
wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
rd <= '0';
v_data_value := rdata;
data_value := v_data_value;
if proc_name = "sbi_read" then
log(config.id_for_bfm, proc_call & "=> " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
else
-- Log will be handled by calling procedure (e.g. sbi_check)
end if;
end procedure;
</pre>

We don't want to (and probably shouldnt) call the sbi_check and providing all the parameters each time. Some of this can be solved by the overloads with more standard parameters, and with our own check procedures declared locally in our testbench:
<pre>
procedure check(
constant addr_value : in natural;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level;
constant msg : in string) is
begin
sbi_check(to_unsigned(addr_value, sbi_if.addr'length), data_exp, alert_level, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

The write procedure is also very handy and should be understood:
<pre>
procedure sbi_write (
constant addr_value : in unsigned;
constant data_value : in std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal wdata : inout std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_write";
constant proc_call : string := "sbi_write(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalise to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_normalised_data : std_logic_vector(wdata'length-1 downto 0) :=
normalize_and_check(data_value, wdata, ALLOW_NARROWER, "data_value", "sbi_core_in.wdata", msg);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '1';
rd <= '0';
addr <= v_normalised_addr;
wdata <= v_normalised_data;

wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
wr <= '0';
log(config.id_for_bfm, proc_call & " completed. " & msg, scope, msg_id_panel);
end procedure;
</pre>

We will create a local overload of this too:
<pre>
procedure write(
constant addr_value : in natural;
constant data_value : in std_logic_vector;
constant msg : in string) is
begin
sbi_write(to_unsigned(addr_value, sbi_if.addr'length), data_value, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

All this enables us to handle transactions at a high level. See Bitvis documentation for how to write your own BFM and what it should include(sanity checks, etc).

[[File:bfm.png|550px]]

== Checking register write and read ==
Now we're enabled to write to and read from the registers. The register addresses are defined in the IRQC package file irqc_pif_bkg.vhd. Notice that we also use the previously declared overloaded version of log() and fit().

<pre>
log(ID_LOG_HDR, "Check register defaults and access (write + read)", C_SCOPE);
------------------------------------------------------------
log("\nChecking Register defaults");
check(C_ADDR_IRR, x"00", ERROR, "IRR default");
check(C_ADDR_IER, x"00", ERROR, "IER default");
check(C_ADDR_IPR, x"00", ERROR, "IPR default");
check(C_ADDR_IRQ2CPU_ALLOWED, x"00", ERROR, "IRQ2CPU_ALLOWED default");

log("\nChecking Register Write/Read");
write(C_ADDR_IER, fit(x"55"), "IER");
check(C_ADDR_IER, fit(x"55"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"AA"), "IER");
check(C_ADDR_IER, fit(x"AA"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"00"), "IER");
check(C_ADDR_IER, fit(x"00"), ERROR, "IER pure readback");
</pre>

This check will give us a nice log if everything turns out ok:

[[File:sim2.png|700px]]

However, if there's an error:

[[File:error2.png|700px]]

== UVVM LICENCE AGREEMENT ==
{{reflist}}

Bitvis UVVM VHDL Verification Component Framework

2016-01-28T15:18:21Z

Ogr043:

This wiki page is heavily based on the Powerpoint-presentation found [http://bitvis.no/media/15298/Simple_TB_step_by_step.pps here].<ref name=UVVM />

== Introduction ==

Bitvis UVVM VVC Framework is a complete framework for making VHDL testbenches for
verification of FPGA and ASIC desing. You can download the complete code-base, examples and simulations scripts from the [http://bitvis.no/products/uvvm-vvc-framework/ Bitvis web page].

=== What's in the folders? ===
[[File:1.png|thumb]]

The download includes severals folders:
* bitvis_irqc - example VHDL design + testbench
* bitvis_uart - example VHDL design + testbench
* bitvis_vip_sbi - Verification IP(VIP) for simple bus interface(SBI)
* bitvis_vip_uart - VIP for UART TX and RX
* uvvm_util - UVVM utility library - sufficient for simple testbenches
* uvvm_vvc_framework - Framework for more advanced tutorials

=== IRQC ===
[[File:irqc.png|thumb]]
The provided example VHDL design is a simple interrupt controller with several internal registers, a bus interface and some input and output signals.

[[File:irqc2.png|350px]]

== Testbench creation ==
Copy the folders bitvis_irqc, bitvis_vip_sbi and uvvm_util to another location before editing the files.
=== Generate TB entity with DUT instantiated ===
Our TB entity can in many cases be generated from several tools. Notepad++ (among other) supports plugins that enables copying an entity and pasting it as an instantiation, and also as a complete testbench template. However, we will change some of our signals so that they fit the VIP SBI BFM. The signals to and from the CPU will be converted to t_sbi_if record, which is a type that includes all the SBI signals (cs, addr, rd, wr, wdata, ready and rdata).

<pre>
--Standard libraries
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;

-- Libraries used for string handling in UVVM
library STD;
use std.env.all;

-- Obviously the UVVM library
library uvvm_util;
context uvvm_util.uvvm_util_context;

-- We will use this library later when implementing the Bus Functional Model
-- Includes among much else the record type t_sbi_if and many functions
-- If other buses are used, you will have to change this library
library bitvis_vip_sbi;
use bitvis_vip_sbi.sbi_bfm_pkg.all;

-- This file includes definitions of everything from registers to record types
use work.irqc_pif_pkg.all;

-- Test case entity
entity irqc_tb is
end entity;

-- Test case architecture
architecture func of irqc_tb is

-- DSP interface and general control signals
signal clk : std_logic := '0';
signal arst : std_logic := '0';
-- CPU interface
-- t_sbi_if is from the verification IP SBI
-- init_sbi_if_signals initialize the inputs to 0 and the outputs to Z
signal sbi_if : t_sbi_if(addr(2 downto 0), wdata(7 downto 0), rdata(7 downto 0)) := init_sbi_if_signals(3, 8);

-- Interrupt related signals
signal irq_source : std_logic_vector(C_NUM_SOURCES-1 downto 0) := (others => '0');
signal irq2cpu : std_logic := '0';
signal irq2cpu_ack : std_logic := '0';

begin

-----------------------------------------------------------------------------
-- Instantiate DUT
-----------------------------------------------------------------------------
i_irqc: entity work.irqc
port map (
-- DSP interface and general control signals
clk => clk,
arst => arst,
-- CPU interface
cs => sbi_if.cs, -- NOTICE THE SIGNALS ARE NOW SBI_IF
addr => sbi_if.addr,
wr => sbi_if.wr,
rd => sbi_if.rd,
din => sbi_if.wdata,
dout => sbi_if.rdata,
-- Interrupt related signals
irq_source => irq_source,
irq2cpu => irq2cpu,
irq2cpu_ack => irq2cpu_ack
);

end func;
</pre>

=== Add support process for clock generation ===
We now have to add a support process that controls the clock. This has to allow enabling/disabling from the test sequencer. We add the following before "begin" in our architecture:
<pre>
-- Added for clock generation
signal clock_ena : boolean := false;

constant C_CLK_PERIOD : time := 10 ns;

procedure clock_gen(
signal clock_signal : inout std_logic;
signal clock_ena : in boolean;
constant clock_period : in time
) is
variable v_first_half_clk_period : time := C_CLK_PERIOD / 2;
begin
loop
if not clock_ena then
wait until clock_ena;
end if;
wait for v_first_half_clk_period;
clock_signal <= not clock_signal;
wait for (clock_period - v_first_half_clk_period);
clock_signal <= not clock_signal;
end loop;
end;
</pre>

Our clock can now be activated from the test sequencer (this will be added in the next step):
<pre>
-- After begin in the architecture
clock_gen(clk, clock_ena, C_CLK_PERIOD);

-- Inside the test sequencer process
clock_ena <= true;
</pre>

=== Add test sequencer process ===
The next step is to add the test sequencer process. This process controls everything from initialization to termination of the simulation.

<pre>
-- Set upt clock generator
clock_gen(clk, clock_ena, C_CLK_PERIOD);

------------------------------------------------
-- PROCESS: p_main
------------------------------------------------
p_main : process
-- The scope tells you where log messages originates - C_SCOPE tells us they originate from the default test sequencer scope
constant C_SCOPE : string := C_TB_SCOPE_DEFAULT;
-- This is where we will add some procedures later to simplify the tests

begin

--Print the configuration to the log
report_global_ctrl(VOID);
report_msg_id_panel(VOID);

enable_log_msg(ALL_MESSAGES);
--disable_log_msg
--enable_log_msg(ID_LOG_HDR);

log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
------------------------------------------------------------
clock_ena <= true; -- to start clock generator

------------------------------------------------------------
-- End the simulation
wait for 1000 ns; -- to allow some time for completion
report_alert_counters(FINAL); -- Report final counters and print conclusion for simulation (Success/Fail)
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);

--Finish the simulation
std.env.stop;
wait; -- to stop completely
end process p_main;
</pre>

==Simulation==
We now have the skeleton of the testbench, which we will develop further. But now, let's see if everything works. Bitvis have created simulation scripts for the IRQC example that compiles everything we need, from the source files of the VHDL design, to the testbench (if you called the file irqc_tb.vhd and placed it in the tb-folder) and the SBI BFM and the UVVM library. Open up QuestaSim/ModelSim.
Change directory to the script folder:
<pre>
cd ~/phys321/bitviswiki/bitvis_irqc/script
do compile_and_sim_all.do
</pre>

This will present our result in the transcript windows, but also write _Log.txt file which includes all the information we have asked for. We see that we get the results from the following code:
<pre>
report_global_ctrl(VOID);
report_msg_id_panel(VOID);
enable_log_msg(ALL_MESSAGES);
log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
report_alert_counters(FINAL);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
</pre>
Commenting these out will result in an empty log.

== Verbosity control ==
We want to able to control the amount of information in our logs, and the framework enables us to prioritize messages based on ID. This makes it easy to turn on or off the information we want.
To turn on a specific ID
<pre>
enable_log_msg(IDNAME);
</pre>

Turn off:
<pre>
disable_log_msg(IDNAME);
</pre>

For writing a message to a certain log ID:
<pre>
log(IDNAME, "MESSAGE HERE", C_SCOPE);
</pre>
Remember that C_SCOPE just tells us that the message originated from the default scope and will look like "TB seq." in the log file.

Exampled IDs:
* ID_LOG_HDR, -- ONLY allowed in test sequencer, Log section headers
* ID_SEQUENCER, -- ONLY allowed in test sequencer, Normal log (not log headers)
* ID_BFM, -- Used inside a BFM (to log BFM access)
* ID_CLOCK_GEN, -- Used for logging when clock generators are enabled or disabled
* ALL_MESSAGES -- Applies to ALL message ID apart from ID_NEVER

You'll find all the different ID's in the UVVM Utility Library Quick Reference or defined in uvvm_util/adaptions_pkg.vhd. This also where C_TB_SCOPE_DEFAULT is defined.

== Implement first tests ==
[[File:tb.png|thumb|upright=0.35]]
We want to check and verify that our testbench is up and running and to verify our first tests of the DUT. This means that we have to able to set all our signals passive, apply a reset signal and then check the default outputs of the DUT.

Instead of setting all our signals passive one-by-one in our test sequencer we declare a procedure in our p_main process(this is done before begin):
<pre>
procedure set_inputs_passive(
dummy : t_void) is --dummy variable is included only to allow calling the procedure with parenthesis for readability
begin
sbi_if.cs <= '0';
sbi_if.addr <= (others => '0');
sbi_if.wr <= '0';
sbi_if.rd <= '0';
sbi_if.wdata <= (others => '0');
irq_source <= (others => '0');
irq2cpu_ack <= '0';
log(ID_SEQUENCER_SUB, "All inputs set passive", C_SCOPE);
end;
</pre>

Note that the procedure declaration also includes a dummy variable parameter. This means that we will be able to call the procedure with the more readable:

<pre>
set_inputs_passive(VOID);
</pre>

Rather than:
<pre>
set_inputs_passive;
</pre>
which is more ambigious.

We may also would like to send pulses on different signals, f.ex. sending a pulse on our reset to see if it behaves like intended. We therefore can include a pulse procedure:
<pre>
procedure pulse(
signal target : inout std_logic_vector;
constant pulse_value : in std_logic_vector;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= pulse_value;
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= pulse_value;
wait for 0 ns; -- Delta cycle only
end if;
target(target'range) <= (others => '0');
log(ID_SEQUENCER_SUB, "Pulsed to " & to_string(pulse_value, HEX, AS_IS, INCL_RADIX) & ". " & msg, C_SCOPE);
end;
</pre>

In the above example the test sequencer is required to inform the procedure of what value the pulse is to take. The call to the procedure would take the following form:
<pre>
pulse(arst, 'Z', clk, 10, "Log message - Im pulsing the value 'Z'");
</pre>
But a more specific overload can be created where pulse always takes value '1':
<pre>
procedure pulse(
signal target : inout std_logic;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string
) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= '1';
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= '1';
wait for 0 ns; -- Delta cycle only
end if;
target <= '0';
log(ID_SEQUENCER_SUB, msg, C_SCOPE);
end;
</pre>

These procedures can now be called directly from our test sequence:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "pulsed reset-signal - active for 10T");
</pre>

To check signal values we can use the built-in check function check_value():
<pre>
check_value(irq2cpu, 'X', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
</pre>
The above call checks if the signal irq2cpu is 'X', and obviously fail if everything works correctly and gives the following message:

[[File:error.png|700px]]

If we want we can change the number of errors logged before the simulation stops:
<pre>
set_alert_stop_limit(ERROR, 3);
</pre>

We now have all the tools needed for the first tests in our sequencer:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "Pulsed reset-signal - active for 10T");

check_value(C_NUM_SOURCES > 0, FAILURE, "Must be at least 1 interrupt source", C_SCOPE);
check_value(C_NUM_SOURCES <= 8, TB_WARNING, "This TB is only checking IRQC with up to 8 interrupt sources", C_SCOPE);

log(ID_LOG_HDR, "Check defaults on output ports", C_SCOPE);
------------------------------------------------------------
check_value(irq2cpu, '0', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
check_value(sbi_if.rdata, x"00", ERROR, "Register data bus output must be default passive");
</pre>

This will give us the following log:

[[File:sim.png|800px]]

This information may only interesting initially and for debug, and can be turned on or off by use of ID.

== Subprograms ==
Some of our testbench code will be repeated several times and the testbench may therefore benefit from creating several subprograms. Obvious examples for our IRQC is:
- Register access
- Signal checkers
- Interrupt source pulsing?
- Interrupt acknowledge pulsing?
- (Report/log method)
- (Alert-handling)
- (reset, set_passive, ...)

We've already created and declared set_passive and pulse procedures, but we could f.ex create overloads for UVVM procedures:
<pre>
-- Log overloads for simplification
procedure log(
msg : string) is
begin
log(ID_SEQUENCER, msg, C_SCOPE);
end;
</pre>

Let's say that it is probable that we'll want to change the number of interrupt sources that the controller can handle. We will then want to able to easily change vectors to the appropriate size. One way is to declare procedures that can trim and fit vectors. This way we can simply change a constant to change the number of sources.

<pre>
subtype t_irq_source is std_logic_vector(C_NUM_SOURCES-1 downto 0);

-- Trim (cut) a given vector to fit the number of irq sources (i.e. pot. reduce width)
function trim(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return t_irq_source is
variable v_result : std_logic_vector(source'length-1 downto 0) := source;
begin
return v_result(num_bits-1 downto 0);
end;

-- Fit a given vector to the number of irq sources by masking with zeros above irq width
function fit(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return std_logic_vector is
variable v_result : std_logic_vector(source'length-1 downto 0) := (others => '0');
variable v_source : std_logic_vector(source'length-1 downto 0) := source;
begin
v_result(num_bits-1 downto 0) := v_source(num_bits-1 downto 0);
return v_result;
end;
</pre>

All IRQC-dedicated subprograms should be declared locally, but more common (f.ex bus-specific) should be declared in common package that can be shared with other.

== Register access ==
To access the IRQC's registers we need to go through the actual process of writing and reading data from them. Fortunately, Bitvis have already taken the responsibility of writing the BFM for the SBI. This doesn't mean that we doesn't have to understand what's going on, since we'll have to write our own BFM's for other buses that we use(Avalon, AXI, etc). So we should investigate the BFM procedures. We want to check register values:
<pre>
procedure sbi_check (
constant addr_value : in unsigned;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level := error;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_check";
constant proc_call : string := "sbi_check(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_exp, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
-- Helper variables
variable v_data_value : std_logic_vector(rdata'length - 1 downto 0);
variable v_check_ok : boolean;
variable v_clk_cycles_waited : natural := 0;
begin
sbi_read(addr_value, v_data_value, msg, clk, cs, addr, rd, wr, ready, rdata, scope, msg_id_panel, config, proc_name);

-- Compare values, but ignore any leading zero's if widths are different.
-- Use ID_NEVER so that check_value method does not log when check is OK,
-- log it here instead.
v_check_ok := check_value(v_data_value, data_exp, alert_level, msg, scope, HEX_BIN_IF_INVALID, SKIP_LEADING_0, ID_NEVER, msg_id_panel, proc_call);
if v_check_ok then
log(config.id_for_bfm, proc_call & "=> OK, read data = " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
end if;
end procedure;
</pre>

We see that sbi_check() calls sbi_read() before it checks if the read value is the expected value.

<pre>
procedure sbi_read (
constant addr_value : in unsigned;
variable data_value : out std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT;
constant proc_name : in string := "sbi_read" -- overwrite if called from other procedure like sbi_check
) is
constant proc_call : string := "sbi_read(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_data_value : std_logic_vector(data_value'range);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '0';
rd <= '1';
addr <= v_normalised_addr;
wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
rd <= '0';
v_data_value := rdata;
data_value := v_data_value;
if proc_name = "sbi_read" then
log(config.id_for_bfm, proc_call & "=> " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
else
-- Log will be handled by calling procedure (e.g. sbi_check)
end if;
end procedure;
</pre>

We don't want to (and probably shouldnt) call the sbi_check and providing all the parameters each time. Some of this can be solved by the overloads with more standard parameters, and with our own check procedures declared locally in our testbench:
<pre>
procedure check(
constant addr_value : in natural;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level;
constant msg : in string) is
begin
sbi_check(to_unsigned(addr_value, sbi_if.addr'length), data_exp, alert_level, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

The write procedure is also very handy and should be understood:
<pre>
procedure sbi_write (
constant addr_value : in unsigned;
constant data_value : in std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal wdata : inout std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_write";
constant proc_call : string := "sbi_write(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalise to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_normalised_data : std_logic_vector(wdata'length-1 downto 0) :=
normalize_and_check(data_value, wdata, ALLOW_NARROWER, "data_value", "sbi_core_in.wdata", msg);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '1';
rd <= '0';
addr <= v_normalised_addr;
wdata <= v_normalised_data;

wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
wr <= '0';
log(config.id_for_bfm, proc_call & " completed. " & msg, scope, msg_id_panel);
end procedure;
</pre>

We will create a local overload of this too:
<pre>
procedure write(
constant addr_value : in natural;
constant data_value : in std_logic_vector;
constant msg : in string) is
begin
sbi_write(to_unsigned(addr_value, sbi_if.addr'length), data_value, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

All this enables us to handle transactions at a high level. See Bitvis documentation for how to write your own BFM and what it should include(sanity checks, etc).

[[File:bfm.png|550px]]

== Checking register write and read ==
Now we're enabled to write to and read from the registers. The register addresses are defined in the IRQC package file irqc_pif_bkg.vhd. Notice that we also use the previously declared overloaded version of log() and fit().

<pre>
log(ID_LOG_HDR, "Check register defaults and access (write + read)", C_SCOPE);
------------------------------------------------------------
log("\nChecking Register defaults");
check(C_ADDR_IRR, x"00", ERROR, "IRR default");
check(C_ADDR_IER, x"00", ERROR, "IER default");
check(C_ADDR_IPR, x"00", ERROR, "IPR default");
check(C_ADDR_IRQ2CPU_ALLOWED, x"00", ERROR, "IRQ2CPU_ALLOWED default");

log("\nChecking Register Write/Read");
write(C_ADDR_IER, fit(x"55"), "IER");
check(C_ADDR_IER, fit(x"55"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"AA"), "IER");
check(C_ADDR_IER, fit(x"AA"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"00"), "IER");
check(C_ADDR_IER, fit(x"00"), ERROR, "IER pure readback");
</pre>

This check will give us a nice log if everything turns out ok:

[[File:sim2.png|700px]]

However, if there's an error:

[[File:error2.png|700px]]

== UVVM LICENCE AGREEMENT ==
{{reflist|
refs=
<ref name=UVVM>This is the jukeboxes reference.</ref>
}}

Bitvis UVVM VHDL Verification Component Framework

2016-01-28T15:16:55Z

Ogr043: /* UVVM LICENCE AGREEMENT */

Bitvis UVVM VHDL Verification Component Framework

2016-01-28T15:16:06Z

Ogr043:

This wiki page is heavily based on the Powerpoint-presentation found [http://bitvis.no/media/15298/Simple_TB_step_by_step.pps here].<ref name=UVVM />

== Introduction ==

Bitvis UVVM VVC Framework is a complete framework for making VHDL testbenches for
verification of FPGA and ASIC desing. You can download the complete code-base, examples and simulations scripts from the [http://bitvis.no/products/uvvm-vvc-framework/ Bitvis web page].

=== What's in the folders? ===
[[File:1.png|thumb]]

The download includes severals folders:
* bitvis_irqc - example VHDL design + testbench
* bitvis_uart - example VHDL design + testbench
* bitvis_vip_sbi - Verification IP(VIP) for simple bus interface(SBI)
* bitvis_vip_uart - VIP for UART TX and RX
* uvvm_util - UVVM utility library - sufficient for simple testbenches
* uvvm_vvc_framework - Framework for more advanced tutorials

=== IRQC ===
[[File:irqc.png|thumb]]
The provided example VHDL design is a simple interrupt controller with several internal registers, a bus interface and some input and output signals.

[[File:irqc2.png|350px]]

== Testbench creation ==
Copy the folders bitvis_irqc, bitvis_vip_sbi and uvvm_util to another location before editing the files.
=== Generate TB entity with DUT instantiated ===
Our TB entity can in many cases be generated from several tools. Notepad++ (among other) supports plugins that enables copying an entity and pasting it as an instantiation, and also as a complete testbench template. However, we will change some of our signals so that they fit the VIP SBI BFM. The signals to and from the CPU will be converted to t_sbi_if record, which is a type that includes all the SBI signals (cs, addr, rd, wr, wdata, ready and rdata).

<pre>
--Standard libraries
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;

-- Libraries used for string handling in UVVM
library STD;
use std.env.all;

-- Obviously the UVVM library
library uvvm_util;
context uvvm_util.uvvm_util_context;

-- We will use this library later when implementing the Bus Functional Model
-- Includes among much else the record type t_sbi_if and many functions
-- If other buses are used, you will have to change this library
library bitvis_vip_sbi;
use bitvis_vip_sbi.sbi_bfm_pkg.all;

-- This file includes definitions of everything from registers to record types
use work.irqc_pif_pkg.all;

-- Test case entity
entity irqc_tb is
end entity;

-- Test case architecture
architecture func of irqc_tb is

-- DSP interface and general control signals
signal clk : std_logic := '0';
signal arst : std_logic := '0';
-- CPU interface
-- t_sbi_if is from the verification IP SBI
-- init_sbi_if_signals initialize the inputs to 0 and the outputs to Z
signal sbi_if : t_sbi_if(addr(2 downto 0), wdata(7 downto 0), rdata(7 downto 0)) := init_sbi_if_signals(3, 8);

-- Interrupt related signals
signal irq_source : std_logic_vector(C_NUM_SOURCES-1 downto 0) := (others => '0');
signal irq2cpu : std_logic := '0';
signal irq2cpu_ack : std_logic := '0';

begin

-----------------------------------------------------------------------------
-- Instantiate DUT
-----------------------------------------------------------------------------
i_irqc: entity work.irqc
port map (
-- DSP interface and general control signals
clk => clk,
arst => arst,
-- CPU interface
cs => sbi_if.cs, -- NOTICE THE SIGNALS ARE NOW SBI_IF
addr => sbi_if.addr,
wr => sbi_if.wr,
rd => sbi_if.rd,
din => sbi_if.wdata,
dout => sbi_if.rdata,
-- Interrupt related signals
irq_source => irq_source,
irq2cpu => irq2cpu,
irq2cpu_ack => irq2cpu_ack
);

end func;
</pre>

=== Add support process for clock generation ===
We now have to add a support process that controls the clock. This has to allow enabling/disabling from the test sequencer. We add the following before "begin" in our architecture:
<pre>
-- Added for clock generation
signal clock_ena : boolean := false;

constant C_CLK_PERIOD : time := 10 ns;

procedure clock_gen(
signal clock_signal : inout std_logic;
signal clock_ena : in boolean;
constant clock_period : in time
) is
variable v_first_half_clk_period : time := C_CLK_PERIOD / 2;
begin
loop
if not clock_ena then
wait until clock_ena;
end if;
wait for v_first_half_clk_period;
clock_signal <= not clock_signal;
wait for (clock_period - v_first_half_clk_period);
clock_signal <= not clock_signal;
end loop;
end;
</pre>

Our clock can now be activated from the test sequencer (this will be added in the next step):
<pre>
-- After begin in the architecture
clock_gen(clk, clock_ena, C_CLK_PERIOD);

-- Inside the test sequencer process
clock_ena <= true;
</pre>

=== Add test sequencer process ===
The next step is to add the test sequencer process. This process controls everything from initialization to termination of the simulation.

<pre>
-- Set upt clock generator
clock_gen(clk, clock_ena, C_CLK_PERIOD);

------------------------------------------------
-- PROCESS: p_main
------------------------------------------------
p_main : process
-- The scope tells you where log messages originates - C_SCOPE tells us they originate from the default test sequencer scope
constant C_SCOPE : string := C_TB_SCOPE_DEFAULT;
-- This is where we will add some procedures later to simplify the tests

begin

--Print the configuration to the log
report_global_ctrl(VOID);
report_msg_id_panel(VOID);

enable_log_msg(ALL_MESSAGES);
--disable_log_msg
--enable_log_msg(ID_LOG_HDR);

log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
------------------------------------------------------------
clock_ena <= true; -- to start clock generator

------------------------------------------------------------
-- End the simulation
wait for 1000 ns; -- to allow some time for completion
report_alert_counters(FINAL); -- Report final counters and print conclusion for simulation (Success/Fail)
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);

--Finish the simulation
std.env.stop;
wait; -- to stop completely
end process p_main;
</pre>

==Simulation==
We now have the skeleton of the testbench, which we will develop further. But now, let's see if everything works. Bitvis have created simulation scripts for the IRQC example that compiles everything we need, from the source files of the VHDL design, to the testbench (if you called the file irqc_tb.vhd and placed it in the tb-folder) and the SBI BFM and the UVVM library. Open up QuestaSim/ModelSim.
Change directory to the script folder:
<pre>
cd ~/phys321/bitviswiki/bitvis_irqc/script
do compile_and_sim_all.do
</pre>

This will present our result in the transcript windows, but also write _Log.txt file which includes all the information we have asked for. We see that we get the results from the following code:
<pre>
report_global_ctrl(VOID);
report_msg_id_panel(VOID);
enable_log_msg(ALL_MESSAGES);
log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
report_alert_counters(FINAL);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
</pre>
Commenting these out will result in an empty log.

== Verbosity control ==
We want to able to control the amount of information in our logs, and the framework enables us to prioritize messages based on ID. This makes it easy to turn on or off the information we want.
To turn on a specific ID
<pre>
enable_log_msg(IDNAME);
</pre>

Turn off:
<pre>
disable_log_msg(IDNAME);
</pre>

For writing a message to a certain log ID:
<pre>
log(IDNAME, "MESSAGE HERE", C_SCOPE);
</pre>
Remember that C_SCOPE just tells us that the message originated from the default scope and will look like "TB seq." in the log file.

Exampled IDs:
* ID_LOG_HDR, -- ONLY allowed in test sequencer, Log section headers
* ID_SEQUENCER, -- ONLY allowed in test sequencer, Normal log (not log headers)
* ID_BFM, -- Used inside a BFM (to log BFM access)
* ID_CLOCK_GEN, -- Used for logging when clock generators are enabled or disabled
* ALL_MESSAGES -- Applies to ALL message ID apart from ID_NEVER

You'll find all the different ID's in the UVVM Utility Library Quick Reference or defined in uvvm_util/adaptions_pkg.vhd. This also where C_TB_SCOPE_DEFAULT is defined.

== Implement first tests ==
[[File:tb.png|thumb|upright=0.35]]
We want to check and verify that our testbench is up and running and to verify our first tests of the DUT. This means that we have to able to set all our signals passive, apply a reset signal and then check the default outputs of the DUT.

Instead of setting all our signals passive one-by-one in our test sequencer we declare a procedure in our p_main process(this is done before begin):
<pre>
procedure set_inputs_passive(
dummy : t_void) is --dummy variable is included only to allow calling the procedure with parenthesis for readability
begin
sbi_if.cs <= '0';
sbi_if.addr <= (others => '0');
sbi_if.wr <= '0';
sbi_if.rd <= '0';
sbi_if.wdata <= (others => '0');
irq_source <= (others => '0');
irq2cpu_ack <= '0';
log(ID_SEQUENCER_SUB, "All inputs set passive", C_SCOPE);
end;
</pre>

Note that the procedure declaration also includes a dummy variable parameter. This means that we will be able to call the procedure with the more readable:

<pre>
set_inputs_passive(VOID);
</pre>

Rather than:
<pre>
set_inputs_passive;
</pre>
which is more ambigious.

We may also would like to send pulses on different signals, f.ex. sending a pulse on our reset to see if it behaves like intended. We therefore can include a pulse procedure:
<pre>
procedure pulse(
signal target : inout std_logic_vector;
constant pulse_value : in std_logic_vector;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= pulse_value;
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= pulse_value;
wait for 0 ns; -- Delta cycle only
end if;
target(target'range) <= (others => '0');
log(ID_SEQUENCER_SUB, "Pulsed to " & to_string(pulse_value, HEX, AS_IS, INCL_RADIX) & ". " & msg, C_SCOPE);
end;
</pre>

In the above example the test sequencer is required to inform the procedure of what value the pulse is to take. The call to the procedure would take the following form:
<pre>
pulse(arst, 'Z', clk, 10, "Log message - Im pulsing the value 'Z'");
</pre>
But a more specific overload can be created where pulse always takes value '1':
<pre>
procedure pulse(
signal target : inout std_logic;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string
) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= '1';
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= '1';
wait for 0 ns; -- Delta cycle only
end if;
target <= '0';
log(ID_SEQUENCER_SUB, msg, C_SCOPE);
end;
</pre>

These procedures can now be called directly from our test sequence:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "pulsed reset-signal - active for 10T");
</pre>

To check signal values we can use the built-in check function check_value():
<pre>
check_value(irq2cpu, 'X', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
</pre>
The above call checks if the signal irq2cpu is 'X', and obviously fail if everything works correctly and gives the following message:

[[File:error.png|700px]]

If we want we can change the number of errors logged before the simulation stops:
<pre>
set_alert_stop_limit(ERROR, 3);
</pre>

We now have all the tools needed for the first tests in our sequencer:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "Pulsed reset-signal - active for 10T");

check_value(C_NUM_SOURCES > 0, FAILURE, "Must be at least 1 interrupt source", C_SCOPE);
check_value(C_NUM_SOURCES <= 8, TB_WARNING, "This TB is only checking IRQC with up to 8 interrupt sources", C_SCOPE);

log(ID_LOG_HDR, "Check defaults on output ports", C_SCOPE);
------------------------------------------------------------
check_value(irq2cpu, '0', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
check_value(sbi_if.rdata, x"00", ERROR, "Register data bus output must be default passive");
</pre>

This will give us the following log:

[[File:sim.png|800px]]

This information may only interesting initially and for debug, and can be turned on or off by use of ID.

== Subprograms ==
Some of our testbench code will be repeated several times and the testbench may therefore benefit from creating several subprograms. Obvious examples for our IRQC is:
- Register access
- Signal checkers
- Interrupt source pulsing?
- Interrupt acknowledge pulsing?
- (Report/log method)
- (Alert-handling)
- (reset, set_passive, ...)

We've already created and declared set_passive and pulse procedures, but we could f.ex create overloads for UVVM procedures:
<pre>
-- Log overloads for simplification
procedure log(
msg : string) is
begin
log(ID_SEQUENCER, msg, C_SCOPE);
end;
</pre>

Let's say that it is probable that we'll want to change the number of interrupt sources that the controller can handle. We will then want to able to easily change vectors to the appropriate size. One way is to declare procedures that can trim and fit vectors. This way we can simply change a constant to change the number of sources.

<pre>
subtype t_irq_source is std_logic_vector(C_NUM_SOURCES-1 downto 0);

-- Trim (cut) a given vector to fit the number of irq sources (i.e. pot. reduce width)
function trim(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return t_irq_source is
variable v_result : std_logic_vector(source'length-1 downto 0) := source;
begin
return v_result(num_bits-1 downto 0);
end;

-- Fit a given vector to the number of irq sources by masking with zeros above irq width
function fit(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return std_logic_vector is
variable v_result : std_logic_vector(source'length-1 downto 0) := (others => '0');
variable v_source : std_logic_vector(source'length-1 downto 0) := source;
begin
v_result(num_bits-1 downto 0) := v_source(num_bits-1 downto 0);
return v_result;
end;
</pre>

All IRQC-dedicated subprograms should be declared locally, but more common (f.ex bus-specific) should be declared in common package that can be shared with other.

== Register access ==
To access the IRQC's registers we need to go through the actual process of writing and reading data from them. Fortunately, Bitvis have already taken the responsibility of writing the BFM for the SBI. This doesn't mean that we doesn't have to understand what's going on, since we'll have to write our own BFM's for other buses that we use(Avalon, AXI, etc). So we should investigate the BFM procedures. We want to check register values:
<pre>
procedure sbi_check (
constant addr_value : in unsigned;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level := error;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_check";
constant proc_call : string := "sbi_check(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_exp, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
-- Helper variables
variable v_data_value : std_logic_vector(rdata'length - 1 downto 0);
variable v_check_ok : boolean;
variable v_clk_cycles_waited : natural := 0;
begin
sbi_read(addr_value, v_data_value, msg, clk, cs, addr, rd, wr, ready, rdata, scope, msg_id_panel, config, proc_name);

-- Compare values, but ignore any leading zero's if widths are different.
-- Use ID_NEVER so that check_value method does not log when check is OK,
-- log it here instead.
v_check_ok := check_value(v_data_value, data_exp, alert_level, msg, scope, HEX_BIN_IF_INVALID, SKIP_LEADING_0, ID_NEVER, msg_id_panel, proc_call);
if v_check_ok then
log(config.id_for_bfm, proc_call & "=> OK, read data = " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
end if;
end procedure;
</pre>

We see that sbi_check() calls sbi_read() before it checks if the read value is the expected value.

<pre>
procedure sbi_read (
constant addr_value : in unsigned;
variable data_value : out std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT;
constant proc_name : in string := "sbi_read" -- overwrite if called from other procedure like sbi_check
) is
constant proc_call : string := "sbi_read(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_data_value : std_logic_vector(data_value'range);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '0';
rd <= '1';
addr <= v_normalised_addr;
wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
rd <= '0';
v_data_value := rdata;
data_value := v_data_value;
if proc_name = "sbi_read" then
log(config.id_for_bfm, proc_call & "=> " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
else
-- Log will be handled by calling procedure (e.g. sbi_check)
end if;
end procedure;
</pre>

We don't want to (and probably shouldnt) call the sbi_check and providing all the parameters each time. Some of this can be solved by the overloads with more standard parameters, and with our own check procedures declared locally in our testbench:
<pre>
procedure check(
constant addr_value : in natural;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level;
constant msg : in string) is
begin
sbi_check(to_unsigned(addr_value, sbi_if.addr'length), data_exp, alert_level, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

The write procedure is also very handy and should be understood:
<pre>
procedure sbi_write (
constant addr_value : in unsigned;
constant data_value : in std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal wdata : inout std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_write";
constant proc_call : string := "sbi_write(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalise to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_normalised_data : std_logic_vector(wdata'length-1 downto 0) :=
normalize_and_check(data_value, wdata, ALLOW_NARROWER, "data_value", "sbi_core_in.wdata", msg);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '1';
rd <= '0';
addr <= v_normalised_addr;
wdata <= v_normalised_data;

wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
wr <= '0';
log(config.id_for_bfm, proc_call & " completed. " & msg, scope, msg_id_panel);
end procedure;
</pre>

We will create a local overload of this too:
<pre>
procedure write(
constant addr_value : in natural;
constant data_value : in std_logic_vector;
constant msg : in string) is
begin
sbi_write(to_unsigned(addr_value, sbi_if.addr'length), data_value, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

All this enables us to handle transactions at a high level. See Bitvis documentation for how to write your own BFM and what it should include(sanity checks, etc).

[[File:bfm.png|550px]]

== Checking register write and read ==
Now we're enabled to write to and read from the registers. The register addresses are defined in the IRQC package file irqc_pif_bkg.vhd. Notice that we also use the previously declared overloaded version of log() and fit().

<pre>
log(ID_LOG_HDR, "Check register defaults and access (write + read)", C_SCOPE);
------------------------------------------------------------
log("\nChecking Register defaults");
check(C_ADDR_IRR, x"00", ERROR, "IRR default");
check(C_ADDR_IER, x"00", ERROR, "IER default");
check(C_ADDR_IPR, x"00", ERROR, "IPR default");
check(C_ADDR_IRQ2CPU_ALLOWED, x"00", ERROR, "IRQ2CPU_ALLOWED default");

log("\nChecking Register Write/Read");
write(C_ADDR_IER, fit(x"55"), "IER");
check(C_ADDR_IER, fit(x"55"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"AA"), "IER");
check(C_ADDR_IER, fit(x"AA"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"00"), "IER");
check(C_ADDR_IER, fit(x"00"), ERROR, "IER pure readback");
</pre>

This check will give us a nice log if everything turns out ok:

[[File:sim2.png|700px]]

However, if there's an error:

[[File:error2.png|700px]]

== UVVM LICENCE AGREEMENT ==
{{reflist|refs=<ref name=UVVM>UVVM LICENSE AGREEMENT
IMPORTANT - READ BEFORE USING OR COPYING.
THIS IS THE MIT LICENSE, see https://opensource.org/licenses/MIT
------------------------------------------------------------------

Copyright (c) 2016 by Bitvis AS

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of
the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</ref>
}}

Bitvis UVVM VHDL Verification Component Framework

2016-01-28T15:02:15Z

Ogr043:

<pre>
-- Copyright (c) 2016 by Bitvis AS. All rights reserved.
-- You should have received a copy of the license file containing the MIT License (see LICENSE.TXT), if not,
-- contact Bitvis AS <support@bitvis.no>.
-- UVVM AND ANY PART THEREOF ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
-- INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-- WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH UVVM.
--========================================================================================================================
</pre>
This wiki page steals heavily from the Powerpoint-presentation found [http://bitvis.no/media/15298/Simple_TB_step_by_step.pps here].

== Introduction ==

Bitvis UVVM VVC Framework is a complete framework for making VHDL testbenches for
verification of FPGA and ASIC desing. You can download the complete code-base, examples and simulations scripts from the [http://bitvis.no/products/uvvm-vvc-framework/ Bitvis web page].

=== What's in the folders? ===
[[File:1.png|thumb]]

The download includes severals folders:
* bitvis_irqc - example VHDL design + testbench
* bitvis_uart - example VHDL design + testbench
* bitvis_vip_sbi - Verification IP(VIP) for simple bus interface(SBI)
* bitvis_vip_uart - VIP for UART TX and RX
* uvvm_util - UVVM utility library - sufficient for simple testbenches
* uvvm_vvc_framework - Framework for more advanced tutorials

=== IRQC ===
[[File:irqc.png|thumb]]
The provided example VHDL design is a simple interrupt controller with several internal registers, a bus interface and some input and output signals.

[[File:irqc2.png|350px]]

== Testbench creation ==
Copy the folders bitvis_irqc, bitvis_vip_sbi and uvvm_util to another location before editing the files.
=== Generate TB entity with DUT instantiated ===
Our TB entity can in many cases be generated from several tools. Notepad++ (among other) supports plugins that enables copying an entity and pasting it as an instantiation, and also as a complete testbench template. However, we will change some of our signals so that they fit the VIP SBI BFM. The signals to and from the CPU will be converted to t_sbi_if record, which is a type that includes all the SBI signals (cs, addr, rd, wr, wdata, ready and rdata).

<pre>
--Standard libraries
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;

-- Libraries used for string handling in UVVM
library STD;
use std.env.all;

-- Obviously the UVVM library
library uvvm_util;
context uvvm_util.uvvm_util_context;

-- We will use this library later when implementing the Bus Functional Model
-- Includes among much else the record type t_sbi_if and many functions
-- If other buses are used, you will have to change this library
library bitvis_vip_sbi;
use bitvis_vip_sbi.sbi_bfm_pkg.all;

-- This file includes definitions of everything from registers to record types
use work.irqc_pif_pkg.all;

-- Test case entity
entity irqc_tb is
end entity;

-- Test case architecture
architecture func of irqc_tb is

-- DSP interface and general control signals
signal clk : std_logic := '0';
signal arst : std_logic := '0';
-- CPU interface
-- t_sbi_if is from the verification IP SBI
-- init_sbi_if_signals initialize the inputs to 0 and the outputs to Z
signal sbi_if : t_sbi_if(addr(2 downto 0), wdata(7 downto 0), rdata(7 downto 0)) := init_sbi_if_signals(3, 8);

-- Interrupt related signals
signal irq_source : std_logic_vector(C_NUM_SOURCES-1 downto 0) := (others => '0');
signal irq2cpu : std_logic := '0';
signal irq2cpu_ack : std_logic := '0';

begin

-----------------------------------------------------------------------------
-- Instantiate DUT
-----------------------------------------------------------------------------
i_irqc: entity work.irqc
port map (
-- DSP interface and general control signals
clk => clk,
arst => arst,
-- CPU interface
cs => sbi_if.cs, -- NOTICE THE SIGNALS ARE NOW SBI_IF
addr => sbi_if.addr,
wr => sbi_if.wr,
rd => sbi_if.rd,
din => sbi_if.wdata,
dout => sbi_if.rdata,
-- Interrupt related signals
irq_source => irq_source,
irq2cpu => irq2cpu,
irq2cpu_ack => irq2cpu_ack
);

end func;
</pre>

=== Add support process for clock generation ===
We now have to add a support process that controls the clock. This has to allow enabling/disabling from the test sequencer. We add the following before "begin" in our architecture:
<pre>
-- Added for clock generation
signal clock_ena : boolean := false;

constant C_CLK_PERIOD : time := 10 ns;

procedure clock_gen(
signal clock_signal : inout std_logic;
signal clock_ena : in boolean;
constant clock_period : in time
) is
variable v_first_half_clk_period : time := C_CLK_PERIOD / 2;
begin
loop
if not clock_ena then
wait until clock_ena;
end if;
wait for v_first_half_clk_period;
clock_signal <= not clock_signal;
wait for (clock_period - v_first_half_clk_period);
clock_signal <= not clock_signal;
end loop;
end;
</pre>

Our clock can now be activated from the test sequencer (this will be added in the next step):
<pre>
-- After begin in the architecture
clock_gen(clk, clock_ena, C_CLK_PERIOD);

-- Inside the test sequencer process
clock_ena <= true;
</pre>

=== Add test sequencer process ===
The next step is to add the test sequencer process. This process controls everything from initialization to termination of the simulation.

<pre>
-- Set upt clock generator
clock_gen(clk, clock_ena, C_CLK_PERIOD);

------------------------------------------------
-- PROCESS: p_main
------------------------------------------------
p_main : process
-- The scope tells you where log messages originates - C_SCOPE tells us they originate from the default test sequencer scope
constant C_SCOPE : string := C_TB_SCOPE_DEFAULT;
-- This is where we will add some procedures later to simplify the tests

begin

--Print the configuration to the log
report_global_ctrl(VOID);
report_msg_id_panel(VOID);

enable_log_msg(ALL_MESSAGES);
--disable_log_msg
--enable_log_msg(ID_LOG_HDR);

log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
------------------------------------------------------------
clock_ena <= true; -- to start clock generator

------------------------------------------------------------
-- End the simulation
wait for 1000 ns; -- to allow some time for completion
report_alert_counters(FINAL); -- Report final counters and print conclusion for simulation (Success/Fail)
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);

--Finish the simulation
std.env.stop;
wait; -- to stop completely
end process p_main;
</pre>

==Simulation==
We now have the skeleton of the testbench, which we will develop further. But now, let's see if everything works. Bitvis have created simulation scripts for the IRQC example that compiles everything we need, from the source files of the VHDL design, to the testbench (if you called the file irqc_tb.vhd and placed it in the tb-folder) and the SBI BFM and the UVVM library. Open up QuestaSim/ModelSim.
Change directory to the script folder:
<pre>
cd ~/phys321/bitviswiki/bitvis_irqc/script
do compile_and_sim_all.do
</pre>

This will present our result in the transcript windows, but also write _Log.txt file which includes all the information we have asked for. We see that we get the results from the following code:
<pre>
report_global_ctrl(VOID);
report_msg_id_panel(VOID);
enable_log_msg(ALL_MESSAGES);
log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
report_alert_counters(FINAL);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
</pre>
Commenting these out will result in an empty log.

== Verbosity control ==
We want to able to control the amount of information in our logs, and the framework enables us to prioritize messages based on ID. This makes it easy to turn on or off the information we want.
To turn on a specific ID
<pre>
enable_log_msg(IDNAME);
</pre>

Turn off:
<pre>
disable_log_msg(IDNAME);
</pre>

For writing a message to a certain log ID:
<pre>
log(IDNAME, "MESSAGE HERE", C_SCOPE);
</pre>
Remember that C_SCOPE just tells us that the message originated from the default scope and will look like "TB seq." in the log file.

Exampled IDs:
* ID_LOG_HDR, -- ONLY allowed in test sequencer, Log section headers
* ID_SEQUENCER, -- ONLY allowed in test sequencer, Normal log (not log headers)
* ID_BFM, -- Used inside a BFM (to log BFM access)
* ID_CLOCK_GEN, -- Used for logging when clock generators are enabled or disabled
* ALL_MESSAGES -- Applies to ALL message ID apart from ID_NEVER

You'll find all the different ID's in the UVVM Utility Library Quick Reference or defined in uvvm_util/adaptions_pkg.vhd. This also where C_TB_SCOPE_DEFAULT is defined.

== Implement first tests ==
[[File:tb.png|thumb|upright=0.35]]
We want to check and verify that our testbench is up and running and to verify our first tests of the DUT. This means that we have to able to set all our signals passive, apply a reset signal and then check the default outputs of the DUT.

Instead of setting all our signals passive one-by-one in our test sequencer we declare a procedure in our p_main process(this is done before begin):
<pre>
procedure set_inputs_passive(
dummy : t_void) is --dummy variable is included only to allow calling the procedure with parenthesis for readability
begin
sbi_if.cs <= '0';
sbi_if.addr <= (others => '0');
sbi_if.wr <= '0';
sbi_if.rd <= '0';
sbi_if.wdata <= (others => '0');
irq_source <= (others => '0');
irq2cpu_ack <= '0';
log(ID_SEQUENCER_SUB, "All inputs set passive", C_SCOPE);
end;
</pre>

Note that the procedure declaration also includes a dummy variable parameter. This means that we will be able to call the procedure with the more readable:

<pre>
set_inputs_passive(VOID);
</pre>

Rather than:
<pre>
set_inputs_passive;
</pre>
which is more ambigious.

We may also would like to send pulses on different signals, f.ex. sending a pulse on our reset to see if it behaves like intended. We therefore can include a pulse procedure:
<pre>
procedure pulse(
signal target : inout std_logic_vector;
constant pulse_value : in std_logic_vector;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= pulse_value;
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= pulse_value;
wait for 0 ns; -- Delta cycle only
end if;
target(target'range) <= (others => '0');
log(ID_SEQUENCER_SUB, "Pulsed to " & to_string(pulse_value, HEX, AS_IS, INCL_RADIX) & ". " & msg, C_SCOPE);
end;
</pre>

In the above example the test sequencer is required to inform the procedure of what value the pulse is to take. The call to the procedure would take the following form:
<pre>
pulse(arst, 'Z', clk, 10, "Log message - Im pulsing the value 'Z'");
</pre>
But a more specific overload can be created where pulse always takes value '1':
<pre>
procedure pulse(
signal target : inout std_logic;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string
) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= '1';
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= '1';
wait for 0 ns; -- Delta cycle only
end if;
target <= '0';
log(ID_SEQUENCER_SUB, msg, C_SCOPE);
end;
</pre>

These procedures can now be called directly from our test sequence:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "pulsed reset-signal - active for 10T");
</pre>

To check signal values we can use the built-in check function check_value():
<pre>
check_value(irq2cpu, 'X', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
</pre>
The above call checks if the signal irq2cpu is 'X', and obviously fail if everything works correctly and gives the following message:

[[File:error.png|700px]]

If we want we can change the number of errors logged before the simulation stops:
<pre>
set_alert_stop_limit(ERROR, 3);
</pre>

We now have all the tools needed for the first tests in our sequencer:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "Pulsed reset-signal - active for 10T");

check_value(C_NUM_SOURCES > 0, FAILURE, "Must be at least 1 interrupt source", C_SCOPE);
check_value(C_NUM_SOURCES <= 8, TB_WARNING, "This TB is only checking IRQC with up to 8 interrupt sources", C_SCOPE);

log(ID_LOG_HDR, "Check defaults on output ports", C_SCOPE);
------------------------------------------------------------
check_value(irq2cpu, '0', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
check_value(sbi_if.rdata, x"00", ERROR, "Register data bus output must be default passive");
</pre>

This will give us the following log:

[[File:sim.png|800px]]

This information may only interesting initially and for debug, and can be turned on or off by use of ID.

== Subprograms ==
Some of our testbench code will be repeated several times and the testbench may therefore benefit from creating several subprograms. Obvious examples for our IRQC is:
- Register access
- Signal checkers
- Interrupt source pulsing?
- Interrupt acknowledge pulsing?
- (Report/log method)
- (Alert-handling)
- (reset, set_passive, ...)

We've already created and declared set_passive and pulse procedures, but we could f.ex create overloads for UVVM procedures:
<pre>
-- Log overloads for simplification
procedure log(
msg : string) is
begin
log(ID_SEQUENCER, msg, C_SCOPE);
end;
</pre>

Let's say that it is probable that we'll want to change the number of interrupt sources that the controller can handle. We will then want to able to easily change vectors to the appropriate size. One way is to declare procedures that can trim and fit vectors. This way we can simply change a constant to change the number of sources.

<pre>
subtype t_irq_source is std_logic_vector(C_NUM_SOURCES-1 downto 0);

-- Trim (cut) a given vector to fit the number of irq sources (i.e. pot. reduce width)
function trim(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return t_irq_source is
variable v_result : std_logic_vector(source'length-1 downto 0) := source;
begin
return v_result(num_bits-1 downto 0);
end;

-- Fit a given vector to the number of irq sources by masking with zeros above irq width
function fit(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return std_logic_vector is
variable v_result : std_logic_vector(source'length-1 downto 0) := (others => '0');
variable v_source : std_logic_vector(source'length-1 downto 0) := source;
begin
v_result(num_bits-1 downto 0) := v_source(num_bits-1 downto 0);
return v_result;
end;
</pre>

All IRQC-dedicated subprograms should be declared locally, but more common (f.ex bus-specific) should be declared in common package that can be shared with other.

== Register access ==
To access the IRQC's registers we need to go through the actual process of writing and reading data from them. Fortunately, Bitvis have already taken the responsibility of writing the BFM for the SBI. This doesn't mean that we doesn't have to understand what's going on, since we'll have to write our own BFM's for other buses that we use(Avalon, AXI, etc). So we should investigate the BFM procedures. We want to check register values:
<pre>
procedure sbi_check (
constant addr_value : in unsigned;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level := error;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_check";
constant proc_call : string := "sbi_check(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_exp, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
-- Helper variables
variable v_data_value : std_logic_vector(rdata'length - 1 downto 0);
variable v_check_ok : boolean;
variable v_clk_cycles_waited : natural := 0;
begin
sbi_read(addr_value, v_data_value, msg, clk, cs, addr, rd, wr, ready, rdata, scope, msg_id_panel, config, proc_name);

-- Compare values, but ignore any leading zero's if widths are different.
-- Use ID_NEVER so that check_value method does not log when check is OK,
-- log it here instead.
v_check_ok := check_value(v_data_value, data_exp, alert_level, msg, scope, HEX_BIN_IF_INVALID, SKIP_LEADING_0, ID_NEVER, msg_id_panel, proc_call);
if v_check_ok then
log(config.id_for_bfm, proc_call & "=> OK, read data = " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
end if;
end procedure;
</pre>

We see that sbi_check() calls sbi_read() before it checks if the read value is the expected value.

<pre>
procedure sbi_read (
constant addr_value : in unsigned;
variable data_value : out std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT;
constant proc_name : in string := "sbi_read" -- overwrite if called from other procedure like sbi_check
) is
constant proc_call : string := "sbi_read(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_data_value : std_logic_vector(data_value'range);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '0';
rd <= '1';
addr <= v_normalised_addr;
wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
rd <= '0';
v_data_value := rdata;
data_value := v_data_value;
if proc_name = "sbi_read" then
log(config.id_for_bfm, proc_call & "=> " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
else
-- Log will be handled by calling procedure (e.g. sbi_check)
end if;
end procedure;
</pre>

We don't want to (and probably shouldnt) call the sbi_check and providing all the parameters each time. Some of this can be solved by the overloads with more standard parameters, and with our own check procedures declared locally in our testbench:
<pre>
procedure check(
constant addr_value : in natural;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level;
constant msg : in string) is
begin
sbi_check(to_unsigned(addr_value, sbi_if.addr'length), data_exp, alert_level, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

The write procedure is also very handy and should be understood:
<pre>
procedure sbi_write (
constant addr_value : in unsigned;
constant data_value : in std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal wdata : inout std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_write";
constant proc_call : string := "sbi_write(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalise to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_normalised_data : std_logic_vector(wdata'length-1 downto 0) :=
normalize_and_check(data_value, wdata, ALLOW_NARROWER, "data_value", "sbi_core_in.wdata", msg);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '1';
rd <= '0';
addr <= v_normalised_addr;
wdata <= v_normalised_data;

wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
wr <= '0';
log(config.id_for_bfm, proc_call & " completed. " & msg, scope, msg_id_panel);
end procedure;
</pre>

We will create a local overload of this too:
<pre>
procedure write(
constant addr_value : in natural;
constant data_value : in std_logic_vector;
constant msg : in string) is
begin
sbi_write(to_unsigned(addr_value, sbi_if.addr'length), data_value, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

All this enables us to handle transactions at a high level. See Bitvis documentation for how to write your own BFM and what it should include(sanity checks, etc).

[[File:bfm.png|550px]]

== Checking register write and read ==
Now we're enabled to write to and read from the registers. The register addresses are defined in the IRQC package file irqc_pif_bkg.vhd. Notice that we also use the previously declared overloaded version of log() and fit().

<pre>
log(ID_LOG_HDR, "Check register defaults and access (write + read)", C_SCOPE);
------------------------------------------------------------
log("\nChecking Register defaults");
check(C_ADDR_IRR, x"00", ERROR, "IRR default");
check(C_ADDR_IER, x"00", ERROR, "IER default");
check(C_ADDR_IPR, x"00", ERROR, "IPR default");
check(C_ADDR_IRQ2CPU_ALLOWED, x"00", ERROR, "IRQ2CPU_ALLOWED default");

log("\nChecking Register Write/Read");
write(C_ADDR_IER, fit(x"55"), "IER");
check(C_ADDR_IER, fit(x"55"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"AA"), "IER");
check(C_ADDR_IER, fit(x"AA"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"00"), "IER");
check(C_ADDR_IER, fit(x"00"), ERROR, "IER pure readback");
</pre>

This check will give us a nice log if everything turns out ok:

[[File:sim2.png|700px]]

However, if there's an error:

[[File:error2.png|700px]]

Bitvis UVVM VHDL Verification Component Framework

2016-01-28T14:44:41Z

Ogr043: /* Checking register write and read */

<pre>
-- Copyright (c) 2016 by Bitvis AS. All rights reserved.
-- You should have received a copy of the license file containing the MIT License (see LICENSE.TXT), if not,
-- contact Bitvis AS <support@bitvis.no>.
-- UVVM AND ANY PART THEREOF ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
-- INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-- WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH UVVM.
--========================================================================================================================
</pre>
This wiki page steals heavily from the Powerpoint-presentation found [http://bitvis.no/media/15298/Simple_TB_step_by_step.pps here].

== Introduction ==

Bitvis UVVM VVC Framework is a complete framework for making VHDL testbenches for
verification of FPGA and ASIC desing. You can download the complete code-base, examples and simulations scripts from the [http://bitvis.no/products/uvvm-vvc-framework/ Bitvis web page].

=== What's in the folders? ===
[[File:1.png|thumb]]

The download includes severals folders:
* bitvis_irqc - example VHDL design + testbench
* bitvis_uart - example VHDL design + testbench
* bitvis_vip_sbi - Verification IP(VIP) for simple bus interface(SBI)
* bitvis_vip_uart - VIP for UART TX and RX
* uvvm_util - UVVM utility library - sufficient for simple testbenches
* uvvm_vvc_framework - Framework for more advanced tutorials

=== IRQC ===
[[File:irqc.png|thumb]]
The provided example VHDL design is a simple interrupt controller with several internal registers, a bus interface and some input and output signals.

[[File:irqc2.png|350px]]

== Testbench creation ==
Copy the folders bitvis_irqc, bitvis_vip_sbi and uvvm_util to another location before editing the files.
=== Generate TB entity with DUT instantiated ===
Our TB entity can in many cases be generated from several tools. Notepad++ (among other) supports plugins that enables copying an entity and pasting it as an instantiation, and also as a complete testbench template. However, we will change some of our signals so that they fit the VIP SBI BFM. The signals to and from the CPU will be converted to t_sbi_if record, which is a type that includes all the SBI signals (cs, addr, rd, wr, wdata, ready and rdata).

<pre>
--Standard libraries
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;

-- Libraries used for string handling in UVVM
library STD;
use std.env.all;

-- Obviously the UVVM library
library uvvm_util;
context uvvm_util.uvvm_util_context;

-- We will use this library later when implementing the Bus Functional Model
-- Includes among much else the record type t_sbi_if and many functions
-- If other buses are used, you will have to change this library
library bitvis_vip_sbi;
use bitvis_vip_sbi.sbi_bfm_pkg.all;

-- This file includes definitions of everything from registers to record types
use work.irqc_pif_pkg.all;

-- Test case entity
entity irqc_tb is
end entity;

-- Test case architecture
architecture func of irqc_tb is

-- DSP interface and general control signals
signal clk : std_logic := '0';
signal arst : std_logic := '0';
-- CPU interface
-- t_sbi_if is from the verification IP SBI
-- init_sbi_if_signals initialize the inputs to 0 and the outputs to Z
signal sbi_if : t_sbi_if(addr(2 downto 0), wdata(7 downto 0), rdata(7 downto 0)) := init_sbi_if_signals(3, 8);

-- Interrupt related signals
signal irq_source : std_logic_vector(C_NUM_SOURCES-1 downto 0) := (others => '0');
signal irq2cpu : std_logic := '0';
signal irq2cpu_ack : std_logic := '0';

begin

-----------------------------------------------------------------------------
-- Instantiate DUT
-----------------------------------------------------------------------------
i_irqc: entity work.irqc
port map (
-- DSP interface and general control signals
clk => clk,
arst => arst,
-- CPU interface
cs => sbi_if.cs, -- NOTICE THE SIGNALS ARE NOW SBI_IF
addr => sbi_if.addr,
wr => sbi_if.wr,
rd => sbi_if.rd,
din => sbi_if.wdata,
dout => sbi_if.rdata,
-- Interrupt related signals
irq_source => irq_source,
irq2cpu => irq2cpu,
irq2cpu_ack => irq2cpu_ack
);

end func;
</pre>

=== Add support process for clock generation ===
We now have to add a support process that controls the clock. This has to allow enabling/disabling from the test sequencer. We add the following before "begin" in our architecture:
<pre>
-- Added for clock generation
signal clock_ena : boolean := false;

constant C_CLK_PERIOD : time := 10 ns;

procedure clock_gen(
signal clock_signal : inout std_logic;
signal clock_ena : in boolean;
constant clock_period : in time
) is
variable v_first_half_clk_period : time := C_CLK_PERIOD / 2;
begin
loop
if not clock_ena then
wait until clock_ena;
end if;
wait for v_first_half_clk_period;
clock_signal <= not clock_signal;
wait for (clock_period - v_first_half_clk_period);
clock_signal <= not clock_signal;
end loop;
end;
</pre>

Our clock can now be activated from the test sequencer (this will be added in the next step):
<pre>
-- After begin in the architecture
clock_gen(clk, clock_ena, C_CLK_PERIOD);

-- Inside the test sequencer process
clock_ena <= true;
</pre>

=== Add test sequencer process ===
The next step is to add the test sequencer process. This process controls everything from initialization to termination of the simulation.

<pre>
-- Set upt clock generator
clock_gen(clk, clock_ena, C_CLK_PERIOD);

------------------------------------------------
-- PROCESS: p_main
------------------------------------------------
p_main : process
-- The scope tells you where log messages originates - C_SCOPE tells us they originate from the default test sequencer scope
constant C_SCOPE : string := C_TB_SCOPE_DEFAULT;
-- This is where we will add some procedures later to simplify the tests

begin

--Print the configuration to the log
report_global_ctrl(VOID);
report_msg_id_panel(VOID);

enable_log_msg(ALL_MESSAGES);
--disable_log_msg
--enable_log_msg(ID_LOG_HDR);

log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
------------------------------------------------------------
clock_ena <= true; -- to start clock generator

------------------------------------------------------------
-- End the simulation
wait for 1000 ns; -- to allow some time for completion
report_alert_counters(FINAL); -- Report final counters and print conclusion for simulation (Success/Fail)
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);

--Finish the simulation
std.env.stop;
wait; -- to stop completely
end process p_main;
</pre>

==Simulation==
We now have the skeleton of the testbench, which we will develop further. But now, let's see if everything works. Bitvis have created simulation scripts for the IRQC example that compiles everything we need, from the source files of the VHDL design, to the testbench (if you called the file irqc_tb.vhd and placed it in the tb-folder) and the SBI BFM and the UVVM library. Open up QuestaSim/ModelSim.
Change directory to the script folder:
<pre>
cd ~/phys321/bitviswiki/bitvis_irqc/script
do compile_and_sim_all.do
</pre>

This will present our result in the transcript windows, but also write _Log.txt file which includes all the information we have asked for. We see that we get the results from the following code:
<pre>
report_global_ctrl(VOID);
report_msg_id_panel(VOID);
enable_log_msg(ALL_MESSAGES);
log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
report_alert_counters(FINAL);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
</pre>
Commenting these out will result in an empty log.

== Verbosity control ==
We want to able to control the amount of information in our logs, and the framework enables us to prioritize messages based on ID. This makes it easy to turn on or off the information we want.
To turn on a specific ID
<pre>
enable_log_msg(IDNAME);
</pre>

Turn off:
<pre>
disable_log_msg(IDNAME);
</pre>

For writing a message to a certain log ID:
<pre>
log(IDNAME, "MESSAGE HERE", C_SCOPE);
</pre>
Remember that C_SCOPE just tells us that the message originated from the default scope and will look like "TB seq." in the log file.

Exampled IDs:
* ID_LOG_HDR, -- ONLY allowed in test sequencer, Log section headers
* ID_SEQUENCER, -- ONLY allowed in test sequencer, Normal log (not log headers)
* ID_BFM, -- Used inside a BFM (to log BFM access)
* ID_CLOCK_GEN, -- Used for logging when clock generators are enabled or disabled
* ALL_MESSAGES -- Applies to ALL message ID apart from ID_NEVER

You'll find all the different ID's in the UVVM Utility Library Quick Reference or defined in uvvm_util/adaptions_pkg.vhd. This also where C_TB_SCOPE_DEFAULT is defined.

== Implement first tests ==
[[File:tb.png|thumb|upright=0.35]]
We want to check and verify that our testbench is up and running and to verify our first tests of the DUT. This means that we have to able to set all our signals passive, apply a reset signal and then check the default outputs of the DUT.

Instead of setting all our signals passive one-by-one in our test sequencer we declare a procedure in our p_main process(this is done before begin):
<pre>
procedure set_inputs_passive(
dummy : t_void) is --dummy variable is included only to allow calling the procedure with parenthesis for readability
begin
sbi_if.cs <= '0';
sbi_if.addr <= (others => '0');
sbi_if.wr <= '0';
sbi_if.rd <= '0';
sbi_if.wdata <= (others => '0');
irq_source <= (others => '0');
irq2cpu_ack <= '0';
log(ID_SEQUENCER_SUB, "All inputs set passive", C_SCOPE);
end;
</pre>

Note that the procedure declaration also includes a dummy variable parameter. This means that we will be able to call the procedure with the more readable:

<pre>
set_inputs_passive(VOID);
</pre>

Rather than:
<pre>
set_inputs_passive;
</pre>
which is more ambigious.

We may also would like to send pulses on different signals, f.ex. sending a pulse on our reset to see if it behaves like intended. We therefore can include a pulse procedure:
<pre>
procedure pulse(
signal target : inout std_logic_vector;
constant pulse_value : in std_logic_vector;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= pulse_value;
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= pulse_value;
wait for 0 ns; -- Delta cycle only
end if;
target(target'range) <= (others => '0');
log(ID_SEQUENCER_SUB, "Pulsed to " & to_string(pulse_value, HEX, AS_IS, INCL_RADIX) & ". " & msg, C_SCOPE);
end;
</pre>

In the above example the test sequencer is required to inform the procedure of what value the pulse is to take. The call to the procedure would take the following form:
<pre>
pulse(arst, 'Z', clk, 10, "Log message - Im pulsing the value 'Z'");
</pre>
But a more specific overload can be created where pulse always takes value '1':
<pre>
procedure pulse(
signal target : inout std_logic;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string
) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= '1';
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= '1';
wait for 0 ns; -- Delta cycle only
end if;
target <= '0';
log(ID_SEQUENCER_SUB, msg, C_SCOPE);
end;
</pre>

These procedures can now be called directly from our test sequence:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "pulsed reset-signal - active for 10T");
</pre>

To check signal values we can use the built-in check function check_value():
<pre>
check_value(irq2cpu, 'X', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
</pre>
The above call checks if the signal irq2cpu is 'X', and obviously fail if everything works correctly and gives the following message:

[[File:error.png|700px]]

If we want we can change the number of errors logged before the simulation stops:
<pre>
set_alert_stop_limit(ERROR, 3);
</pre>

We now have all the tools needed for the first tests in our sequencer:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "Pulsed reset-signal - active for 10T");

check_value(C_NUM_SOURCES > 0, FAILURE, "Must be at least 1 interrupt source", C_SCOPE);
check_value(C_NUM_SOURCES <= 8, TB_WARNING, "This TB is only checking IRQC with up to 8 interrupt sources", C_SCOPE);

log(ID_LOG_HDR, "Check defaults on output ports", C_SCOPE);
------------------------------------------------------------
check_value(irq2cpu, '0', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
check_value(sbi_if.rdata, x"00", ERROR, "Register data bus output must be default passive");
</pre>

This will give us the following log:

[[File:sim.png|800px]]

This information may only interesting initially and for debug, and can be turned on or off by use of ID.

== Subprograms ==
Some of our testbench code will be repeated several times and the testbench may therefore benefit from creating several subprograms. Obvious examples for our IRQC is:
- Register access
- Signal checkers
- Interrupt source pulsing?
- Interrupt acknowledge pulsing?
- (Report/log method)
- (Alert-handling)
- (reset, set_passive, ...)

We've already created and declared set_passive and pulse procedures, but we could f.ex create overloads for UVVM procedures:
<pre>
-- Log overloads for simplification
procedure log(
msg : string) is
begin
log(ID_SEQUENCER, msg, C_SCOPE);
end;
</pre>

Let's say that it is probable that we'll want to change the number of interrupt sources that the controller can handle. We will then want to able to easily change vectors to the appropriate size. One way is to declare procedures that can trim and fit vectors. This way we can simply change a constant to change the number of sources.

<pre>
subtype t_irq_source is std_logic_vector(C_NUM_SOURCES-1 downto 0);

-- Trim (cut) a given vector to fit the number of irq sources (i.e. pot. reduce width)
function trim(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return t_irq_source is
variable v_result : std_logic_vector(source'length-1 downto 0) := source;
begin
return v_result(num_bits-1 downto 0);
end;

-- Fit a given vector to the number of irq sources by masking with zeros above irq width
function fit(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return std_logic_vector is
variable v_result : std_logic_vector(source'length-1 downto 0) := (others => '0');
variable v_source : std_logic_vector(source'length-1 downto 0) := source;
begin
v_result(num_bits-1 downto 0) := v_source(num_bits-1 downto 0);
return v_result;
end;
</pre>

All IRQC-dedicated subprograms should be declared locally, but more common (f.ex bus-specific) should be declared in common package that can be shared with other.

== Register access ==
To access the IRQC's registers we need to go through the actual process of writing and reading data from them. Fortunately, Bitvis have already taken the responsibility of writing the BFM for the SBI. This doesn't mean that we doesn't have to understand what's going on, since we'll have to write our own BFM's for other buses that we use(Avalon, AXI, etc). So we should investigate the BFM procedures. We want to check register values:
<pre>
procedure sbi_check (
constant addr_value : in unsigned;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level := error;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_check";
constant proc_call : string := "sbi_check(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_exp, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
-- Helper variables
variable v_data_value : std_logic_vector(rdata'length - 1 downto 0);
variable v_check_ok : boolean;
variable v_clk_cycles_waited : natural := 0;
begin
sbi_read(addr_value, v_data_value, msg, clk, cs, addr, rd, wr, ready, rdata, scope, msg_id_panel, config, proc_name);

-- Compare values, but ignore any leading zero's if widths are different.
-- Use ID_NEVER so that check_value method does not log when check is OK,
-- log it here instead.
v_check_ok := check_value(v_data_value, data_exp, alert_level, msg, scope, HEX_BIN_IF_INVALID, SKIP_LEADING_0, ID_NEVER, msg_id_panel, proc_call);
if v_check_ok then
log(config.id_for_bfm, proc_call & "=> OK, read data = " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
end if;
end procedure;
</pre>

We see that sbi_check() calls sbi_read() before it checks if the read value is the expected value.

<pre>
procedure sbi_read (
constant addr_value : in unsigned;
variable data_value : out std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT;
constant proc_name : in string := "sbi_read" -- overwrite if called from other procedure like sbi_check
) is
constant proc_call : string := "sbi_read(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_data_value : std_logic_vector(data_value'range);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '0';
rd <= '1';
addr <= v_normalised_addr;
wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
rd <= '0';
v_data_value := rdata;
data_value := v_data_value;
if proc_name = "sbi_read" then
log(config.id_for_bfm, proc_call & "=> " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
else
-- Log will be handled by calling procedure (e.g. sbi_check)
end if;
end procedure;
</pre>

We don't want to (and probably shouldnt) call the sbi_check and providing all the parameters each time. Some of this can be solved by the overloads with more standard parameters, and with our own check procedures declared locally in our testbench:
<pre>
procedure check(
constant addr_value : in natural;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level;
constant msg : in string) is
begin
sbi_check(to_unsigned(addr_value, sbi_if.addr'length), data_exp, alert_level, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

The write procedure is also very handy and should be understood:
<pre>
procedure sbi_write (
constant addr_value : in unsigned;
constant data_value : in std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal wdata : inout std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_write";
constant proc_call : string := "sbi_write(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalise to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_normalised_data : std_logic_vector(wdata'length-1 downto 0) :=
normalize_and_check(data_value, wdata, ALLOW_NARROWER, "data_value", "sbi_core_in.wdata", msg);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '1';
rd <= '0';
addr <= v_normalised_addr;
wdata <= v_normalised_data;

wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
wr <= '0';
log(config.id_for_bfm, proc_call & " completed. " & msg, scope, msg_id_panel);
end procedure;
</pre>

We will create a local overload of this too:
<pre>
procedure write(
constant addr_value : in natural;
constant data_value : in std_logic_vector;
constant msg : in string) is
begin
sbi_write(to_unsigned(addr_value, sbi_if.addr'length), data_value, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

All this enables us to handle transactions at a high level. See Bitvis documentation for how to write your own BFM and what it should include(sanity checks, etc).

[[File:bfm.png|550px]]

== Checking register write and read ==
Now we're enabled to write to and read from the registers. The register addresses are defined in the IRQC package file irqc_pif_bkg.vhd. Notice that we also use the previously declared overloaded version of log() and fit().

<pre>
log(ID_LOG_HDR, "Check register defaults and access (write + read)", C_SCOPE);
------------------------------------------------------------
log("\nChecking Register defaults");
check(C_ADDR_IRR, x"00", ERROR, "IRR default");
check(C_ADDR_IER, x"00", ERROR, "IER default");
check(C_ADDR_IPR, x"00", ERROR, "IPR default");
check(C_ADDR_IRQ2CPU_ALLOWED, x"00", ERROR, "IRQ2CPU_ALLOWED default");

log("\nChecking Register Write/Read");
write(C_ADDR_IER, fit(x"55"), "IER");
check(C_ADDR_IER, fit(x"55"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"AA"), "IER");
check(C_ADDR_IER, fit(x"AA"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"00"), "IER");
check(C_ADDR_IER, fit(x"00"), ERROR, "IER pure readback");
</pre>

This check will give us a nice log if everything turns out ok:

[[File:sim2.png|400px]]

However, if there's an error:

[[File:error2.png|400px]]

File:Error2.png

2016-01-28T14:44:35Z

Ogr043: File uploaded with MsUpload

File uploaded with MsUpload

File:Sim2.png

2016-01-28T14:43:10Z

Ogr043: File uploaded with MsUpload

File uploaded with MsUpload

Bitvis UVVM VHDL Verification Component Framework

2016-01-28T14:40:28Z

Ogr043: /* Subprograms */

<pre>
-- Copyright (c) 2016 by Bitvis AS. All rights reserved.
-- You should have received a copy of the license file containing the MIT License (see LICENSE.TXT), if not,
-- contact Bitvis AS <support@bitvis.no>.
-- UVVM AND ANY PART THEREOF ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
-- INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-- WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH UVVM.
--========================================================================================================================
</pre>
This wiki page steals heavily from the Powerpoint-presentation found [http://bitvis.no/media/15298/Simple_TB_step_by_step.pps here].

== Introduction ==

Bitvis UVVM VVC Framework is a complete framework for making VHDL testbenches for
verification of FPGA and ASIC desing. You can download the complete code-base, examples and simulations scripts from the [http://bitvis.no/products/uvvm-vvc-framework/ Bitvis web page].

=== What's in the folders? ===
[[File:1.png|thumb]]

The download includes severals folders:
* bitvis_irqc - example VHDL design + testbench
* bitvis_uart - example VHDL design + testbench
* bitvis_vip_sbi - Verification IP(VIP) for simple bus interface(SBI)
* bitvis_vip_uart - VIP for UART TX and RX
* uvvm_util - UVVM utility library - sufficient for simple testbenches
* uvvm_vvc_framework - Framework for more advanced tutorials

=== IRQC ===
[[File:irqc.png|thumb]]
The provided example VHDL design is a simple interrupt controller with several internal registers, a bus interface and some input and output signals.

[[File:irqc2.png|350px]]

== Testbench creation ==
Copy the folders bitvis_irqc, bitvis_vip_sbi and uvvm_util to another location before editing the files.
=== Generate TB entity with DUT instantiated ===
Our TB entity can in many cases be generated from several tools. Notepad++ (among other) supports plugins that enables copying an entity and pasting it as an instantiation, and also as a complete testbench template. However, we will change some of our signals so that they fit the VIP SBI BFM. The signals to and from the CPU will be converted to t_sbi_if record, which is a type that includes all the SBI signals (cs, addr, rd, wr, wdata, ready and rdata).

<pre>
--Standard libraries
library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;

-- Libraries used for string handling in UVVM
library STD;
use std.env.all;

-- Obviously the UVVM library
library uvvm_util;
context uvvm_util.uvvm_util_context;

-- We will use this library later when implementing the Bus Functional Model
-- Includes among much else the record type t_sbi_if and many functions
-- If other buses are used, you will have to change this library
library bitvis_vip_sbi;
use bitvis_vip_sbi.sbi_bfm_pkg.all;

-- This file includes definitions of everything from registers to record types
use work.irqc_pif_pkg.all;

-- Test case entity
entity irqc_tb is
end entity;

-- Test case architecture
architecture func of irqc_tb is

-- DSP interface and general control signals
signal clk : std_logic := '0';
signal arst : std_logic := '0';
-- CPU interface
-- t_sbi_if is from the verification IP SBI
-- init_sbi_if_signals initialize the inputs to 0 and the outputs to Z
signal sbi_if : t_sbi_if(addr(2 downto 0), wdata(7 downto 0), rdata(7 downto 0)) := init_sbi_if_signals(3, 8);

-- Interrupt related signals
signal irq_source : std_logic_vector(C_NUM_SOURCES-1 downto 0) := (others => '0');
signal irq2cpu : std_logic := '0';
signal irq2cpu_ack : std_logic := '0';

begin

-----------------------------------------------------------------------------
-- Instantiate DUT
-----------------------------------------------------------------------------
i_irqc: entity work.irqc
port map (
-- DSP interface and general control signals
clk => clk,
arst => arst,
-- CPU interface
cs => sbi_if.cs, -- NOTICE THE SIGNALS ARE NOW SBI_IF
addr => sbi_if.addr,
wr => sbi_if.wr,
rd => sbi_if.rd,
din => sbi_if.wdata,
dout => sbi_if.rdata,
-- Interrupt related signals
irq_source => irq_source,
irq2cpu => irq2cpu,
irq2cpu_ack => irq2cpu_ack
);

end func;
</pre>

=== Add support process for clock generation ===
We now have to add a support process that controls the clock. This has to allow enabling/disabling from the test sequencer. We add the following before "begin" in our architecture:
<pre>
-- Added for clock generation
signal clock_ena : boolean := false;

constant C_CLK_PERIOD : time := 10 ns;

procedure clock_gen(
signal clock_signal : inout std_logic;
signal clock_ena : in boolean;
constant clock_period : in time
) is
variable v_first_half_clk_period : time := C_CLK_PERIOD / 2;
begin
loop
if not clock_ena then
wait until clock_ena;
end if;
wait for v_first_half_clk_period;
clock_signal <= not clock_signal;
wait for (clock_period - v_first_half_clk_period);
clock_signal <= not clock_signal;
end loop;
end;
</pre>

Our clock can now be activated from the test sequencer (this will be added in the next step):
<pre>
-- After begin in the architecture
clock_gen(clk, clock_ena, C_CLK_PERIOD);

-- Inside the test sequencer process
clock_ena <= true;
</pre>

=== Add test sequencer process ===
The next step is to add the test sequencer process. This process controls everything from initialization to termination of the simulation.

<pre>
-- Set upt clock generator
clock_gen(clk, clock_ena, C_CLK_PERIOD);

------------------------------------------------
-- PROCESS: p_main
------------------------------------------------
p_main : process
-- The scope tells you where log messages originates - C_SCOPE tells us they originate from the default test sequencer scope
constant C_SCOPE : string := C_TB_SCOPE_DEFAULT;
-- This is where we will add some procedures later to simplify the tests

begin

--Print the configuration to the log
report_global_ctrl(VOID);
report_msg_id_panel(VOID);

enable_log_msg(ALL_MESSAGES);
--disable_log_msg
--enable_log_msg(ID_LOG_HDR);

log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
------------------------------------------------------------
clock_ena <= true; -- to start clock generator

------------------------------------------------------------
-- End the simulation
wait for 1000 ns; -- to allow some time for completion
report_alert_counters(FINAL); -- Report final counters and print conclusion for simulation (Success/Fail)
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);

--Finish the simulation
std.env.stop;
wait; -- to stop completely
end process p_main;
</pre>

==Simulation==
We now have the skeleton of the testbench, which we will develop further. But now, let's see if everything works. Bitvis have created simulation scripts for the IRQC example that compiles everything we need, from the source files of the VHDL design, to the testbench (if you called the file irqc_tb.vhd and placed it in the tb-folder) and the SBI BFM and the UVVM library. Open up QuestaSim/ModelSim.
Change directory to the script folder:
<pre>
cd ~/phys321/bitviswiki/bitvis_irqc/script
do compile_and_sim_all.do
</pre>

This will present our result in the transcript windows, but also write _Log.txt file which includes all the information we have asked for. We see that we get the results from the following code:
<pre>
report_global_ctrl(VOID);
report_msg_id_panel(VOID);
enable_log_msg(ALL_MESSAGES);
log(ID_LOG_HDR, "Start Simulation of TB for IRQC", C_SCOPE);
report_alert_counters(FINAL);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
</pre>
Commenting these out will result in an empty log.

== Verbosity control ==
We want to able to control the amount of information in our logs, and the framework enables us to prioritize messages based on ID. This makes it easy to turn on or off the information we want.
To turn on a specific ID
<pre>
enable_log_msg(IDNAME);
</pre>

Turn off:
<pre>
disable_log_msg(IDNAME);
</pre>

For writing a message to a certain log ID:
<pre>
log(IDNAME, "MESSAGE HERE", C_SCOPE);
</pre>
Remember that C_SCOPE just tells us that the message originated from the default scope and will look like "TB seq." in the log file.

Exampled IDs:
* ID_LOG_HDR, -- ONLY allowed in test sequencer, Log section headers
* ID_SEQUENCER, -- ONLY allowed in test sequencer, Normal log (not log headers)
* ID_BFM, -- Used inside a BFM (to log BFM access)
* ID_CLOCK_GEN, -- Used for logging when clock generators are enabled or disabled
* ALL_MESSAGES -- Applies to ALL message ID apart from ID_NEVER

You'll find all the different ID's in the UVVM Utility Library Quick Reference or defined in uvvm_util/adaptions_pkg.vhd. This also where C_TB_SCOPE_DEFAULT is defined.

== Implement first tests ==
[[File:tb.png|thumb|upright=0.35]]
We want to check and verify that our testbench is up and running and to verify our first tests of the DUT. This means that we have to able to set all our signals passive, apply a reset signal and then check the default outputs of the DUT.

Instead of setting all our signals passive one-by-one in our test sequencer we declare a procedure in our p_main process(this is done before begin):
<pre>
procedure set_inputs_passive(
dummy : t_void) is --dummy variable is included only to allow calling the procedure with parenthesis for readability
begin
sbi_if.cs <= '0';
sbi_if.addr <= (others => '0');
sbi_if.wr <= '0';
sbi_if.rd <= '0';
sbi_if.wdata <= (others => '0');
irq_source <= (others => '0');
irq2cpu_ack <= '0';
log(ID_SEQUENCER_SUB, "All inputs set passive", C_SCOPE);
end;
</pre>

Note that the procedure declaration also includes a dummy variable parameter. This means that we will be able to call the procedure with the more readable:

<pre>
set_inputs_passive(VOID);
</pre>

Rather than:
<pre>
set_inputs_passive;
</pre>
which is more ambigious.

We may also would like to send pulses on different signals, f.ex. sending a pulse on our reset to see if it behaves like intended. We therefore can include a pulse procedure:
<pre>
procedure pulse(
signal target : inout std_logic_vector;
constant pulse_value : in std_logic_vector;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= pulse_value;
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= pulse_value;
wait for 0 ns; -- Delta cycle only
end if;
target(target'range) <= (others => '0');
log(ID_SEQUENCER_SUB, "Pulsed to " & to_string(pulse_value, HEX, AS_IS, INCL_RADIX) & ". " & msg, C_SCOPE);
end;
</pre>

In the above example the test sequencer is required to inform the procedure of what value the pulse is to take. The call to the procedure would take the following form:
<pre>
pulse(arst, 'Z', clk, 10, "Log message - Im pulsing the value 'Z'");
</pre>
But a more specific overload can be created where pulse always takes value '1':
<pre>
procedure pulse(
signal target : inout std_logic;
signal clock_signal : in std_logic;
constant num_periods : in natural;
constant msg : in string
) is
begin
if num_periods > 0 then
wait until falling_edge(clock_signal);
target <= '1';
for i in 1 to num_periods loop
wait until falling_edge(clock_signal);
end loop;
else
target <= '1';
wait for 0 ns; -- Delta cycle only
end if;
target <= '0';
log(ID_SEQUENCER_SUB, msg, C_SCOPE);
end;
</pre>

These procedures can now be called directly from our test sequence:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "pulsed reset-signal - active for 10T");
</pre>

To check signal values we can use the built-in check function check_value():
<pre>
check_value(irq2cpu, 'X', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
</pre>
The above call checks if the signal irq2cpu is 'X', and obviously fail if everything works correctly and gives the following message:

[[File:error.png|700px]]

If we want we can change the number of errors logged before the simulation stops:
<pre>
set_alert_stop_limit(ERROR, 3);
</pre>

We now have all the tools needed for the first tests in our sequencer:
<pre>
set_inputs_passive(VOID);
pulse(arst, clk, 10, "Pulsed reset-signal - active for 10T");

check_value(C_NUM_SOURCES > 0, FAILURE, "Must be at least 1 interrupt source", C_SCOPE);
check_value(C_NUM_SOURCES <= 8, TB_WARNING, "This TB is only checking IRQC with up to 8 interrupt sources", C_SCOPE);

log(ID_LOG_HDR, "Check defaults on output ports", C_SCOPE);
------------------------------------------------------------
check_value(irq2cpu, '0', ERROR, "Interrupt to CPU must be default inactive", C_SCOPE);
check_value(sbi_if.rdata, x"00", ERROR, "Register data bus output must be default passive");
</pre>

This will give us the following log:

[[File:sim.png|800px]]

This information may only interesting initially and for debug, and can be turned on or off by use of ID.

== Subprograms ==
Some of our testbench code will be repeated several times and the testbench may therefore benefit from creating several subprograms. Obvious examples for our IRQC is:
- Register access
- Signal checkers
- Interrupt source pulsing?
- Interrupt acknowledge pulsing?
- (Report/log method)
- (Alert-handling)
- (reset, set_passive, ...)

We've already created and declared set_passive and pulse procedures, but we could f.ex create overloads for UVVM procedures:
<pre>
-- Log overloads for simplification
procedure log(
msg : string) is
begin
log(ID_SEQUENCER, msg, C_SCOPE);
end;
</pre>

Let's say that it is probable that we'll want to change the number of interrupt sources that the controller can handle. We will then want to able to easily change vectors to the appropriate size. One way is to declare procedures that can trim and fit vectors. This way we can simply change a constant to change the number of sources.

<pre>
subtype t_irq_source is std_logic_vector(C_NUM_SOURCES-1 downto 0);

-- Trim (cut) a given vector to fit the number of irq sources (i.e. pot. reduce width)
function trim(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return t_irq_source is
variable v_result : std_logic_vector(source'length-1 downto 0) := source;
begin
return v_result(num_bits-1 downto 0);
end;

-- Fit a given vector to the number of irq sources by masking with zeros above irq width
function fit(
constant source : std_logic_vector;
constant num_bits : positive := C_NUM_SOURCES)
return std_logic_vector is
variable v_result : std_logic_vector(source'length-1 downto 0) := (others => '0');
variable v_source : std_logic_vector(source'length-1 downto 0) := source;
begin
v_result(num_bits-1 downto 0) := v_source(num_bits-1 downto 0);
return v_result;
end;
</pre>

All IRQC-dedicated subprograms should be declared locally, but more common (f.ex bus-specific) should be declared in common package that can be shared with other.

== Register access ==
To access the IRQC's registers we need to go through the actual process of writing and reading data from them. Fortunately, Bitvis have already taken the responsibility of writing the BFM for the SBI. This doesn't mean that we doesn't have to understand what's going on, since we'll have to write our own BFM's for other buses that we use(Avalon, AXI, etc). So we should investigate the BFM procedures. We want to check register values:
<pre>
procedure sbi_check (
constant addr_value : in unsigned;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level := error;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_check";
constant proc_call : string := "sbi_check(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_exp, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
-- Helper variables
variable v_data_value : std_logic_vector(rdata'length - 1 downto 0);
variable v_check_ok : boolean;
variable v_clk_cycles_waited : natural := 0;
begin
sbi_read(addr_value, v_data_value, msg, clk, cs, addr, rd, wr, ready, rdata, scope, msg_id_panel, config, proc_name);

-- Compare values, but ignore any leading zero's if widths are different.
-- Use ID_NEVER so that check_value method does not log when check is OK,
-- log it here instead.
v_check_ok := check_value(v_data_value, data_exp, alert_level, msg, scope, HEX_BIN_IF_INVALID, SKIP_LEADING_0, ID_NEVER, msg_id_panel, proc_call);
if v_check_ok then
log(config.id_for_bfm, proc_call & "=> OK, read data = " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
end if;
end procedure;
</pre>

We see that sbi_check() calls sbi_read() before it checks if the read value is the expected value.

<pre>
procedure sbi_read (
constant addr_value : in unsigned;
variable data_value : out std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal rdata : in std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT;
constant proc_name : in string := "sbi_read" -- overwrite if called from other procedure like sbi_check
) is
constant proc_call : string := "sbi_read(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalize to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_data_value : std_logic_vector(data_value'range);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '0';
rd <= '1';
addr <= v_normalised_addr;
wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
rd <= '0';
v_data_value := rdata;
data_value := v_data_value;
if proc_name = "sbi_read" then
log(config.id_for_bfm, proc_call & "=> " & to_string(v_data_value, HEX, SKIP_LEADING_0, INCL_RADIX) & ". " & msg, scope, msg_id_panel);
else
-- Log will be handled by calling procedure (e.g. sbi_check)
end if;
end procedure;
</pre>

We don't want to (and probably shouldnt) call the sbi_check and providing all the parameters each time. Some of this can be solved by the overloads with more standard parameters, and with our own check procedures declared locally in our testbench:
<pre>
procedure check(
constant addr_value : in natural;
constant data_exp : in std_logic_vector;
constant alert_level : in t_alert_level;
constant msg : in string) is
begin
sbi_check(to_unsigned(addr_value, sbi_if.addr'length), data_exp, alert_level, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

The write procedure is also very handy and should be understood:
<pre>
procedure sbi_write (
constant addr_value : in unsigned;
constant data_value : in std_logic_vector;
constant msg : in string;
signal clk : in std_logic;
signal cs : inout std_logic;
signal addr : inout unsigned;
signal rd : inout std_logic;
signal wr : inout std_logic;
signal ready : in std_logic;
signal wdata : inout std_logic_vector;
constant scope : in string := C_SCOPE;
constant msg_id_panel : in t_msg_id_panel := shared_msg_id_panel;
constant config : in t_sbi_bfm_config := C_SBI_BFM_CONFIG_DEFAULT
) is
constant proc_name : string := "sbi_write";
constant proc_call : string := "sbi_write(A:" & to_string(addr_value, HEX, AS_IS, INCL_RADIX) &
", " & to_string(data_value, HEX, AS_IS, INCL_RADIX) & ")";
-- Normalise to the DUT addr/data widths
variable v_normalised_addr : unsigned(addr'length-1 downto 0) :=
normalize_and_check(addr_value, addr, ALLOW_WIDER_NARROWER, "addr_value", "sbi_core_in.addr", msg);
variable v_normalised_data : std_logic_vector(wdata'length-1 downto 0) :=
normalize_and_check(data_value, wdata, ALLOW_NARROWER, "data_value", "sbi_core_in.wdata", msg);
variable v_clk_cycles_waited : natural := 0;
begin
wait_until_given_time_after_rising_edge(clk, config.clock_period/4);
cs <= '1';
wr <= '1';
rd <= '0';
addr <= v_normalised_addr;
wdata <= v_normalised_data;

wait for config.clock_period;
while (config.use_ready_signal and ready = '0') loop
if v_clk_cycles_waited = 0 then
log(config.id_for_bfm_wait, proc_call & " waiting for response (sbi ready=0)" & msg, scope, msg_id_panel);
end if;
wait for config.clock_period;
v_clk_cycles_waited := v_clk_cycles_waited + 1;
check_value(v_clk_cycles_waited <= config.max_wait_cycles, config.max_wait_cycles_severity,
": Timeout while waiting for sbi ready", scope, ID_NEVER, msg_id_panel, proc_call);
end loop;

cs <= '0';
wr <= '0';
log(config.id_for_bfm, proc_call & " completed. " & msg, scope, msg_id_panel);
end procedure;
</pre>

We will create a local overload of this too:
<pre>
procedure write(
constant addr_value : in natural;
constant data_value : in std_logic_vector;
constant msg : in string) is
begin
sbi_write(to_unsigned(addr_value, sbi_if.addr'length), data_value, msg,
clk, sbi_if, C_SCOPE);
end;
</pre>

All this enables us to handle transactions at a high level. See Bitvis documentation for how to write your own BFM and what it should include(sanity checks, etc).

[[File:bfm.png|550px]]

== Checking register write and read ==
Now we're enabled to write to and read from the registers. The register addresses are defined in the IRQC package file irqc_pif_bkg.vhd. Notice that we also use the previously declared overloaded version of log().

<pre>
log(ID_LOG_HDR, "Check register defaults and access (write + read)", C_SCOPE);
------------------------------------------------------------
log("\nChecking Register defaults");
check(C_ADDR_IRR, x"00", ERROR, "IRR default");
check(C_ADDR_IER, x"00", ERROR, "IER default");
check(C_ADDR_IPR, x"00", ERROR, "IPR default");
check(C_ADDR_IRQ2CPU_ALLOWED, x"00", ERROR, "IRQ2CPU_ALLOWED default");

log("\nChecking Register Write/Read");
write(C_ADDR_IER, fit(x"55"), "IER");
check(C_ADDR_IER, fit(x"55"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"AA"), "IER");
check(C_ADDR_IER, fit(x"AA"), ERROR, "IER pure readback");
write(C_ADDR_IER, fit(x"00"), "IER");
check(C_ADDR_IER, fit(x"00"), ERROR, "IER pure readback");
</pre>