Verifying VHDL

Introduction

One of the most important aspects when developing FPGA is to ensure the modules we have developed are properly tested. Depending on the language we use there are several free simulators and frameworks available.

Indeed we have looked at one of these in a past project COCOTB which allows us to use Python to test our Verilog and VHDL using either commercial or open source simulators.

Another great framework which can be used to verify FPGA designs completed in VHDL is the Universal VDHL Verification Methodology (UVVM). This frame work provides a range of features from bus functional models for commonly used interfaces such as AXI, Wishbone, GMII, Ethernet, UART, SPI, and I2C etc.

One of the great things about UVVM is that it will work with the free and open source simulator GHDL.

So in this project we are going to demonstrate how to install and setup GHDL, install and compile UVVM using GHDL and then create a simple test bench using UVVM in VS Code.

By the time this is completed we will be able to develop and verify entirely in the VS Code environment.

This will work on both Linux and Windows however, if we are using Windows we need to first install MSys. Using MSys is how we will be able to install GHDL on Windows.

Installing MSys2

The first step in installing GHDL on Windows is to downloads and install Msys2 which is available here https://www.msys2.org/

Run the installer and step through the stages of instruction.

On my laptop I left the default installation as is.

I also left the default menu shortcut as is.

I then waited a few minutes for the installation to complete.

Once the installation is completed we can close the installer.

Installing GHDL

To get started installing GHDL we need to open MSys MINGW64. Once open we need to update several of its packages first, we do this using pacman the package manager.

pacman -S base-devel

This includes tools for building, compiling and linking.

The next step is to install the tool chain which includes tools like GCC and LLVM

pacman -S --needed mingw-w64-x86_64-toolchain 

We will also want to work with repositories for saving our source and simulations so we will download git

pacman -S git 

The next step is to install GHDL there are several different backends available however, the one to use for compatibility with UVVM is the mcode version

pacman -s mingw-w64-x86_64-ghdl-mcode 

The next step is to install GTKWave which allows us to view the waveforms created by GHDL during simulation. We should only need these for debugging buy they are very useful.

pacman -S mingw-w64-x86_64-gtkwave

We can check GHDL has been installed correctly by making the following command in Msys MINGW64

ghdl -v

If you see the above the installation was successful.

Integrating GHDL within VS Code

Ideally we want to be developing and controlling our simulations from within VS Code. As GHDL is command line driven, we can integrate the Msys2 MINGW64 terminal easily within VS Code

Open the settings and navigate to terminal.integrated.profile.windows

Select open JSON file and add the following to the file.

"msys mingw64": {
"path": "C:/msys64/msys2_shell.cmd",
"args": [
"-defterm",
"-here",
"-no-start",
"-mingw64"
]
}One o

We should now be able to open a MINGW64 window just as we can with any terminal or powershell

Setting Up UVVM

The first step in setting up UVVM is to clone the directory, decide where you want your UVVM library to be installed.

Clone the repo with the git comand

 git clone https://github.com/UVVM/UVVM.git

Once downloaded the next steps are pretty simple, we need to compile the UVVM library using GHDL and then run one of the UVVM demos to make sure the libraries are all correctly compiled.

Change directory to the uvvm/scripts directory and run the script compile_all and indicate GHDL is the simulator to use.

source compile_all.sh ghdl 

Provided the UVVM libraries compile correctly, the next step is to run the demo. This is provided under the UART VVC (we will get to exactly what this in a minute).

Change directory to the bitvis_uart/scripts library.

The next step is then the demo script that will compile and simulate the example using GHDL.

 source ghdl_compile_all_and_simulate.sh

Once compilation is completed this will run the simulation, at the end of the simulation you will see a summary of the results.

What we want to do now is learn how create and work with UVVM in our designs.

UVVM Overview

As I mentioned above UVVM is an open-source framework designed to improve the process of testing and verifying FPGAdesigns written in VHDL.

Traditionally, creating VHDL-based testbenches required significant effort, often leading to ad hoc, non-reusable, and hard-to-maintain code. Or as was often the case companies creating their own internal test framework.

UVVM addresses this by providing a structured and standardized approach to testbench development, focusing on simplicity, reusability, and readability.

To achieve this UVVM provides a set of libraries and utilities to simplify verification tasks, such as transaction-based verification, logging, and synchronization. These features enable designers to create modular testbenches that can scale efficiently, regardless of the complexity of the design under test (DUT).

Key Concepts of UVVM

• Modularity and Reusability: UVVM encourages breaking down the testbench into reusable components, such as test harness, test sequencers and verification components. This modular approach reduces duplication and simplifies testing.
• Verification Components (VCs): UVVM introduces the concept of standardized Verification Components, which encapsulate specific functionalities (e.g., drivers, monitors) for DUT interfaces. These components can be reused in multiple projects, saving time and effort
• Command-Based Test Sequences: UVVM enables a structured test flow through command-based sequencers. Test sequences can be written in a human-readable and hierarchical format, making it easier to define and debug test cases.
• Logging and Reporting: UVVM has built-in logging and reporting utilities, making it straightforward to trace test execution, debug issues, and ensure compliance with verification requirements.
• Coverage and Randomization: UVVM supports functional coverage and constrained random testing, which are essential for achieving high test quality. These features allow for comprehensive verification and uncovering of corner cases. We can combine this with GHDLs ability to perform code coverage, also enabling metric on the test benches performance.

When it comes to creating out test benches in UVVM the approach is to take a hierarchical one.

• Highest Level - Test Bench or multiple test benches depending upon the complexity of the task. The test bench looks very much like a script and controls the sequence of commands and checks applied to the VVCs in the test harness.
• Test Harness - This is the structural level of the test bench and contains the unit under test with its IOs connected to the VVCs which will be providing stimulus and receiving outputs.
• DUT - The top level of the DUT with its internal hierarchy below.

UVVM Example

Similar to the UVVM demo we are going to create a example based around a UART it enables us to use VVCs and talk about some of the key concepts required to create a testbench.

The UART Source code

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
use ieee.math_real.all;
use work.adiuvo_uart.all;
entity uart is generic (
reset_level : std_logic := '0'; -- reset level which causes a reset
clk_freq    : natural := 100_000_000; -- oscillator frequency
baud_rate   : natural := 115200 -- baud rate
);
port (
--!System Inputs
clk   : in std_logic;
reset : in std_logic;
--!External Interfaces
rx : in std_logic;
tx  : out std_logic;
--! Master AXIS Interface
m_axis_tready : in std_logic;
m_axis_tdata  : out std_logic_vector(7 downto 0);
m_axis_tvalid : out std_logic;
--! Slave AXIS Interface
s_axis_tready : out std_logic;
s_axis_tdata  : in std_logic_vector(7 downto 0);
s_axis_tvalid : in std_logic
);
end entity;
architecture rtl of uart is
constant bit_period : integer := (clk_freq/baud_rate) - 1;
type cntrl_fsm is (idle, set_tx,wait_tx);
type rx_fsm is (idle, start, sample, check, wait_axis);
signal current_state : cntrl_fsm; --:= idle;
signal rx_state : rx_fsm;-- := idle;
signal baud_counter : unsigned(vector_size(real(clk_freq), real(baud_rate)) downto 0) := (others => '0'); --timer for outgoing signals
signal baud_en : std_logic := '0';
signal meta_reg : std_logic_vector(3 downto 0) := (others => '0'); -- fe detection too
signal capture : std_logic_vector(7 downto 0) := (others => '0'); -- data and parity
signal bit_count : integer range 0 to 1023 := 0;
signal pos_count : integer range 0 to 15 := 0;
signal running : std_logic := '0';
signal load_tx : std_logic := '0';
signal complete : std_logic := '0';
signal tx_reg : std_logic_vector(11 downto 0) := (others => '0');
signal tmr_reg : std_logic_vector(11 downto 0) := (others => '0');
signal payload : std_logic_vector(7 downto 0) := (others => '0');
constant zero  : std_logic_vector(tmr_reg'range) := (others => '0');
begin
process (reset, clk)
begin
if reset = reset_level then
current_state <= idle;
payload       <= (others => '0');
load_tx <= '0';
elsif rising_edge(clk) then
load_tx <= '0';
case current_state is
when idle =>
if s_axis_tvalid = '1' then
current_state <= set_tx;
load_tx       <= '1';
payload       <= s_axis_tdata;
end if;
when set_tx =>
current_state <= wait_tx;
when wait_tx =>
if complete = '1' then
current_state <= idle;
end if;
when others =>
current_state <= idle;
end case;
end if;
end process;
s_axis_tready <= '1' when (current_state = idle) else '0';
process (reset, clk)
--! baud counter for output TX
begin
if reset = reset_level then
baud_counter <= (others => '0');
baud_en      <= '0';
elsif rising_edge(clk) then
baud_en <= '0';
if (load_tx = '1') then
baud_counter <= (others => '0');
elsif (baud_counter = bit_period) then
baud_en      <= '1';
baud_counter <= (others => '0');
else
baud_counter <= baud_counter + 1;
end if;
end if;
end process;
process (reset, clk)
--!metastability protection rx signal
begin
if reset = reset_level then
meta_reg <= (others => '1');
elsif rising_edge(clk) then
meta_reg <= meta_reg(meta_reg'high - 1 downto meta_reg'low) & rx;
end if;
end process;
process (reset, clk)
begin
if reset = reset_level then
pos_count <= 0;
bit_count <= 0;
capture     <= (others => '0');
rx_state    <= idle;
m_axis_tvalid <= '0';
m_axis_tdata     <= (others => '0');
elsif rising_edge(clk) then
case rx_state is
when idle =>
m_axis_tvalid  <= '0';
if meta_reg(meta_reg'high downto meta_reg'high - 1) = fe_det then
pos_count <= 0;
bit_count <= 0;
capture  <= (others => '0');
rx_state <= start;
end if;
when start =>
if bit_count = bit_period then
bit_count <= 0;
rx_state  <= sample;
else
bit_count <= bit_count + 1;
end if;
when sample =>
bit_count <= bit_count + 1;
rx_state  <= sample;
if bit_count = (bit_period/2) and (pos_count < 8) then
capture <= meta_reg(meta_reg'high) & capture(capture'high downto capture'low + 1);
elsif bit_count = bit_period then
if pos_count = 8 then
rx_state <= check;
else
pos_count <= pos_count + 1;
bit_count <= 0;
end if;
end if;
when check =>
if parity(capture) = '1' then
m_axis_tvalid <= '1';
m_axis_tdata  <= capture(7 downto 0);
rx_state      <= wait_axis;
else
m_axis_tvalid <= '1';
m_axis_tdata  <= capture(7 downto 0);
rx_state      <= wait_axis;
end if;
when wait_axis =>
if m_axis_tready = '1' then
m_axis_tvalid <= '0';
rx_state      <= idle;
end if;
end case;
end if;
end process;
op_uart : process (reset, clk)
begin
if reset = reset_level then
tx_reg  <= (others => '1');
tmr_reg <= (others => '0');
elsif rising_edge(clk) then
if load_tx = '1' then
tx_reg  <= stop_bit & not(parity(payload)) & payload & start_bit ;
tmr_reg <= (others => '1');
elsif baud_en = '1' then
tx_reg  <= '1' & tx_reg(tx_reg'high downto tx_reg'low + 1);
tmr_reg <= tmr_reg(tmr_reg'high - 1 downto tmr_reg'low) & '0';
end if;
end if;
end process;
tx       <= tx_reg(tx_reg'low);
complete <= '1' when (tmr_reg = zero and current_state = wait_tx) else '0';
end architecture;

The UART Package

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
use ieee.math_real.all;
package adiuvo_uart is
function vector_size(clk_freq, baud_rate : real) return integer;
function parity (a : std_logic_vector) return std_logic;
constant fe_det     : std_logic_vector(1 downto 0) := "10";
constant start_bit  : std_logic := '0';
constant stop_bit   : std_logic_vector := "11";
end package;
package body adiuvo_uart is
function vector_size(clk_freq, baud_rate : real) return integer is
variable div : real;
variable res : real;
begin
div := (clk_freq/baud_rate);
res := CEIL(LOG(div)/LOG(2.0));
return integer(res - 1.0);
end;
function parity (a : std_logic_vector) return std_logic is
variable y : std_logic := '0';
begin
for i in a'range loop
y := y xor a(i);
end loop;
return y;
end parity;
end package body adiuvo_uart;

The DUT will be UART which has AXI Stream interfaces, this will be connected to loop back in this example and the UART VVC used to transmit data into the UART and receive data from the UART.

We will also use a UART Monitor which will monitor TX and RX lines to ensure the bit rate is correct and there are no errors e.g. parity errors.

While the Test Harness Code looks as below

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
library uvvm_vvc_framework;
use uvvm_vvc_framework.ti_vvc_framework_support_pkg.all;
library uvvm_util;
context uvvm_util.uvvm_util_context; -- t_channel (RX/TX)
library bitvis_vip_uart;
context bitvis_vip_uart.vvc_context;
use bitvis_vip_uart.monitor_cmd_pkg.all;
library bitvis_uart;
library bitvis_vip_clock_generator;
entity uart_th is generic(
G_BIT_PERIOD   : time
);
end entity;
architecture th of uart_th is
constant C_UART_TX_VVC   : natural := 1;
constant C_UART_RX_VVC   : natural := 1;
constant C_CLOCK_GEN_VVC : natural := 1;
constant C_CLK_FREQ     : natural := 100_000_000;
constant C_BAUD_RATE    : natural := 115200;
constant C_RESET_LEVEL  : std_logic := '1';
constant C_CLK_PERIOD   : time := 10 ns;
signal clk : std_logic := '0';
signal arst : std_logic := '0';
-- UART VVC signals
signal rx : std_logic := '1'; --input
signal tx : std_logic := '1'; --output
signal axis_tdata : std_logic_vector(7 downto 0);
signal axis_tvalid : std_logic;
signal axis_tready : std_logic;
constant C_UART_MONITOR_INTERFACE_CONFIG : t_uart_interface_config := (
bit_time => G_BIT_PERIOD,
num_data_bits => 8,
parity => PARITY_ODD,
num_stop_bits => STOP_BITS_ONE
);
constant C_UART_MONITOR_CONFIG : t_uart_monitor_config := (
scope_name => (1 to 12 => "UART Monitor", others => NUL),
msg_id_panel => C_UART_MONITOR_MSG_ID_PANEL_DEFAULT,
interface_config => C_UART_MONITOR_INTERFACE_CONFIG,
transaction_display_time => 0 ns
);
begin
i_ti_uvvm_engine : entity uvvm_vvc_framework.ti_uvvm_engine;
uart_inst : entity work.uart
generic map (
reset_level => C_RESET_LEVEL,
clk_freq => C_CLK_FREQ,
baud_rate => C_BAUD_RATE
)
port map (
clk => clk,
reset => arst,
rx => rx,
tx => tx,
m_axis_tready => axis_tready,
m_axis_tdata => axis_tdata,
m_axis_tvalid => axis_tvalid,
s_axis_tready => axis_tready,
s_axis_tdata => axis_tdata,
s_axis_tvalid => axis_tvalid
);
i1_uart_monitor : entity bitvis_vip_uart.uart_monitor
generic map(
GC_INSTANCE_IDX => 1,
GC_MONITOR_CONFIG => C_UART_MONITOR_CONFIG
)
port map(
uart_dut_tx => rx,
uart_dut_rx => tx
);
i1_uart_vvc : entity bitvis_vip_uart.uart_vvc
generic map(
GC_INSTANCE_IDX => 1
)
port map(
uart_vvc_rx => tx, --crossed over
uart_vvc_tx => rx
);
i_clock_generator_vvc : entity bitvis_vip_clock_generator.clock_generator_vvc
generic map(
GC_INSTANCE_IDX => C_CLOCK_GEN_VVC,
GC_CLOCK_NAME => "Clock",
GC_CLOCK_PERIOD => C_CLK_PERIOD,
GC_CLOCK_HIGH_TIME => C_CLK_PERIOD / 2
)
port map(
clk => clk
);
arst <= '1', '0' after 5 * C_CLK_PERIOD;
end architecture;

The test bench then looks as below

library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;
library uvvm_util;
context uvvm_util.uvvm_util_context;
library uvvm_vvc_framework;
use uvvm_vvc_framework.ti_vvc_framework_support_pkg.all;
library bitvis_vip_uart;
context bitvis_vip_uart.vvc_context;
use bitvis_vip_uart.monitor_cmd_pkg.all;
library bitvis_vip_clock_generator;
context bitvis_vip_clock_generator.vvc_context;
entity uart_tb is
end entity uart_tb;
-- Test bench architecture
architecture tb of uart_tb is
constant C_BIT_PERIOD   : time := 8.68055 us;
constant C_SCOPE         : string := C_TB_SCOPE_DEFAULT;
constant C_MONITOR_SCOPE : string := "UART Monitor";
begin
i_test_harness : entity work.uart_th
generic map(C_BIT_PERIOD)
;
Stim : process
procedure test (void : t_void) is
variable v_data : std_logic_vector(7 downto 0);
begin
for i in 1 to 255 loop
v_data := std_logic_vector(to_unsigned(i, v_data'length));
-- Request UART TX VVC write
uart_transmit(UART_VVCT, 1, TX, v_data, "UART TX");
uart_expect(UART_VVCT, 1, RX, v_data,"Expect data from DUT UART instance 1", 1, 10 ms, ERROR, C_SCOPE);
await_completion(UART_VVCT, 1, RX, 22 * C_BIT_PERIOD);
insert_delay(UART_VVCT, 1, TX, C_BIT_PERIOD, "Insert delay before next UART TX");
end loop;
end procedure;
begin
await_uvvm_initialization(VOID);
start_clock(CLOCK_GENERATOR_VVCT, 1, "Start clock generator");
-- Set verbosity level
disable_log_msg(ALL_MESSAGES);
enable_log_msg(ID_LOG_HDR);
enable_log_msg(ID_LOG_HDR_XL);
enable_log_msg(ID_SEQUENCER);
enable_log_msg(ID_SEQUENCER_SUB);
enable_log_msg(ID_UVVM_SEND_CMD);
enable_log_msg(ID_AWAIT_UVVM_COMPLETION);
disable_log_msg(UART_VVCT, 1, RX, ALL_MESSAGES);
disable_log_msg(UART_VVCT, 1, TX, ALL_MESSAGES);
-- Print the configuration to the log
report_global_ctrl(VOID);
report_msg_id_panel(VOID);
log(ID_LOG_HDR, "Configure UART Monitor", C_SCOPE);
shared_uart_monitor_config(TX, 1).scope_name(1 to C_MONITOR_SCOPE'length) := C_MONITOR_SCOPE;
shared_uart_monitor_config(RX, 1).scope_name(1 to C_MONITOR_SCOPE'length) := C_MONITOR_SCOPE;
log(ID_LOG_HDR, "Configure UART VVC 1", C_SCOPE);
-- use shared variable defined with VVC Methods Package to configure the UART
--============================================================================================================
shared_uart_vvc_config(RX, 1).bfm_config.bit_time := C_BIT_PERIOD;
shared_uart_vvc_config(TX, 1).bfm_config.bit_time := C_BIT_PERIOD;
shared_uart_vvc_config(RX, 1).bfm_config.num_stop_bits := STOP_BITS_ONE;
shared_uart_vvc_config(TX, 1).bfm_config.num_stop_bits := STOP_BITS_ONE;
shared_uart_vvc_config(RX, 1).bfm_config.parity := PARITY_ODD;
shared_uart_vvc_config(TX, 1).bfm_config.parity := PARITY_ODD;
await_uvvm_completion(1000 ns, ERROR, 1 ns, REPORT_ALERT_COUNTERS_FINAL, REPORT_SCOREBOARDS, REPORT_VVCS, C_SCOPE);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
--tests
test(VOID);
await_uvvm_completion(10000 ns, ERROR, 1 ns, REPORT_ALERT_COUNTERS_FINAL, REPORT_SCOREBOARDS, REPORT_VVCS, C_SCOPE);
log(ID_LOG_HDR, "SIMULATION COMPLETED", C_SCOPE);
-- Finish the simulation
std.env.stop;
wait; -- to stop completely
end process;
end architecture;

This code sets up the UVVM logging and then uses a procedure which interacts with the VVCs in the TH.

Using procedures like this enables a procedure to be written for each test to be applied. These can then be tied back to the test requirements.

To be able to compile and run the test bench we need to write some scripts which will call GHDL.

I decided to write two scripts one which compiles the source code, the second which runs the simulation.

echo "Compiling RTL"
ghdl -a --std=08 -frelaxed-rules -Wno-hide -Wno-shared --work=work --workdir=./work ./src/uart_pkg.vhd
ghdl -a --std=08 -frelaxed-rules -Wno-hide -Wno-shared --work=work --workdir=./work ./src/uart.vhd

echo "Compiling TH"
ghdl -a --std=08 -frelaxed-rules -Wno-hide -Wno-shared --work=work --workdir=./work -P../uvvm/UVVM/script/ghdl ./tb/uart_th.vhd
ghdl -a --std=08 -frelaxed-rules -Wno-hide -Wno-shared --work=work --workdir=./work -P../uvvm/UVVM/script/ghdl ./tb/uart_tb.vhd

When compiling the DUT, TH and TB we do not want to have to recompile each time the UVVM libraries. As such we can ise the -P option to point GHDL to where the compiled UVVM GHDL libraries are. These were created in the Setting Up UVVM element above.

To run the simulation and generate a GTK waveform view I created the script below.

ghdl -e --std=08 -frelaxed-rules --work=work --workdir=./work -P../uvvm/UVVM/script/ghdl uart_tb --wave=sim.ghw

ghdl -r --std=08 -frelaxed-rules --work=work --workdir=./work -P../uvvm/UVVM/script/ghdl uart_tb --wave=sim.ghw

Running this will show the test bench applying and checking a incrementing count from 1 to 255 sent and received over the UART.

The final summary of the reuslts.

The GTK Waveform shows the incrementing count on the AXI Stream data channel and the RX and TX wavefroms.

Wrap Up

Writing the RTL is often said to be the easy part verification is what can take up most of the development time. Done well verification makes the integration on the hardware go very smoothly as a significant element of the technical risk has been reduced. Done badly then the integration on hardware will be very painful and you will end up doing a lot of the verification again.