Kelvin UVM Testbench

This document describes the structure and usage of the UVM testbench for verifying the RvvCoreMiniVerificationAxi DUT.

Overview

This testbench provides a basic UVM environment to:

Instantiate the RvvCoreMiniVerificationAxi DUT.
Connect AXI Master, AXI Slave, and IRQ interfaces to the DUT.
Provide basic stimulus generation via UVM sequences.
Include a simple reactive AXI Slave model.
Load a binary file into the DUT's memory using backdoor access.
Kick off the DUT execution using initial AXI writes.
Check for basic test completion via DUT status signals (halted, fault) or a timeout.

Prerequisites

Synopsys VCS: This testbench is configured to run with Synopsys VCS.
UVM: VCS needs to be configured with UVM 1.2 support enabled.
Kelvin Hardware Repository: Access to the repository containing the RvvCoreMiniVerificationAxi source code is required to generate the DUT Verilog and the test binary.
Bazel: The build system used to generate the Verilog from the Chisel source in the Kelvin HW repository.
RISC-V Toolchain: A RISC-V toolchain (specifically llvm-objcopy-17 or similar) compatible with the Kelvin project is needed to generate the .bin file.

Generating the DUT (RvvCoreMiniVerificationAxi.sv)

The Verilog file for the DUT needs to be generated from the Chisel source code located in the Kelvin hardware repository.

Navigate to the root directory of your Kelvin HW repository clone:
```
cd /path/to/your/kelvin/hw/repo
```

Run the Bazel build command to emit the Verilog:

bazel build //hdl/chisel/src/kelvin:rvv_core_mini_verification_axi_cc_library_emit_verilog

The Verilog file will be generated at: bazel-bin/hdl/chisel/src/kelvin/RvvCoreMiniVerificationAxi.sv
Copy this generated RvvCoreMiniVerificationAxi.sv file to the rtl/ directory within this testbench structure.

Generating the Test Binary (program.bin)

The test program run by the DUT needs to be compiled and converted to a flat binary format.

Navigate to the Kelvin HW repository root:
```
cd /path/to/your/kelvin/hw/repo
```
Navigate to the example test directory:
```
cd tests/cocotb/tutorial
```
(Note: Adapt this path if using a different test program)
Compile the test program (this typically generates program.elf):
```
make
```
Convert the ELF file to a binary file using llvm-objcopy-17, extracting only the .text section. Note: Ensure the path to llvm-objcopy-17 is correct for your environment.
```
llvm-objcopy-17 -O binary --only-section=.text -S program.elf program.bin
```
The program.bin file is generated in the current directory (tests/cocotb/tutorial).
Copy this program.bin file to the bin/ directory of this UVM testbench structure (or update the TEST_BINARY path in the Makefile or run command).

Directory Structure

The testbench follows a standard UVM directory structure:

.
├── common/                # Common components
│   ├── kelvin_axi_master/ # Files related to the TB acting as AXI Master
│   │   ├── kelvin_axi_master_if.sv
│   │   └── kelvin_axi_master_agent_pkg.sv
│   ├── kelvin_axi_slave/  # Files related to the TB acting as AXI Slave
│   │   ├── kelvin_axi_slave_if.sv
│   │   └── kelvin_axi_slave_agent_pkg.sv
│   ├── kelvin_irq/        # Files related to the IRQ/Control interface
│   │   ├── kelvin_irq_if.sv
│   │   └── kelvin_irq_agent_pkg.sv
│   └── transaction_item/  # Transaction item definitions
│       └── transaction_item_pkg.sv
├── env/                   # UVM Environment definition
│   └── kelvin_env_pkg.sv
├── rtl/                   # DUT RTL source file(s)
│   └── RvvCoreMiniVerificationAxi.sv     # (Needs to be generated and copied here)
├── tb/                    # Top-level testbench module
│   └── kelvin_tb_top.sv
├── tests/                 # UVM Tests and Sequences
│   └── kelvin_test_pkg.sv
├── Makefile               # Makefile for compilation and simulation
├── kelvin_dv.f            # File list for compilation
└── bin/                   # Directory for test binaries
    └── program.bin        # (Needs to be generated and copied here)

Running the Testbench using the Makefile

The provided Makefile simplifies the compilation and simulation process.

1. Compilation:

Command: make compile
Action: Creates necessary directories (sim_work, logs, waves), and compiles the DUT and testbench using VCS based on kelvin_dv.f. Creates the sim_work/simv executable.

Expected Output:

--- Compiling with VCS ---
Chronologic VCS simulator copyright 1991-202X
Contains Synopsys proprietary information.
Compiler version ...
... (VCS compilation messages) ...
Top Level Modules:
        kelvin_tb_top
TimeScale is 1ns / 1ps
--- Compilation Finished ---

Check sim_work/logs/compile.log for detailed messages and errors.

2. Running the Simulation:

Command (Default Test): make run
- Runs the default test (kelvin_base_test) defined in the Makefile.
- Uses the default binary (bin/program.bin).
- Uses UVM_MEDIUM verbosity.

Command (Specific Test & Binary):

make run UVM_TESTNAME=<your_specific_test> TEST_BINARY=/path/to/another.bin UVM_VERBOSITY=UVM_HIGH

Overrides the default test name, binary path, and verbosity level.

Action: Executes the compiled simv executable with the specified UVM runtime options.

Expected Output:

--- Running Simulation ---
Test:      kelvin_base_test
Binary:    bin/program.bin
Verbosity: UVM_MEDIUM
Timeout:   20000 ns
Plusargs:  +UVM_TESTNAME=kelvin_base_test +TEST_BINARY=bin/program.bin +UVM_VERBOSITY=UVM_MEDIUM +TEST_TIMEOUT=20000
Log File:  sim_work/logs/kelvin_base_test.log
Wave File: sim_work/waves/kelvin_base_test.fsdb
Chronologic VCS simulator copyright 1991-202X
Contains Synopsys proprietary information.
Simulator version ... ; Runtime version ...
UVM_INFO @ 0: reporter [RNTST] Running test kelvin_base_test...
... (UVM simulation messages based on verbosity) ...
UVM_INFO tests/kelvin_test_pkg.sv(LINE#) @ TIME: uvm_test_top.env.m_master_agent.sequencer@@req_pc [kelvin_kickoff_write_seq] Kickoff Write 1 (PC=0x00000034) sent to addr 0x00030004
...
UVM_INFO tests/kelvin_test_pkg.sv(LINE#) @ TIME: uvm_test_top [kelvin_base_test] DUT halted signal observed
UVM_INFO tests/kelvin_test_pkg.sv(LINE#) @ TIME: uvm_test_top [kelvin_base_test] Run phase finishing
--- UVM Report Summary ---
...
UVM_INFO tests/kelvin_test_pkg.sv(LINE#) @ TIME: uvm_test_top [kelvin_base_test] ** UVM TEST PASSED **
--- Simulation Finished ---

Look for the ** UVM TEST PASSED ** or ** UVM TEST FAILED ** message at the end of the simulation log (sim_work/logs/<testname>.log).
If enabled, a waveform file (sim_work/waves/<testname>.fsdb) will be generated.

3. Cleaning:

Command: make clean
Action: Removes the sim_work directory and other simulation-generated files (simv, csrc, logs, waveforms, etc.). kelvin_dv.f is not removed if it's checked in.

Expected Output:

--- Cleaning Simulation Files ---
rm -rf sim_work simv* csrc* *.log* *.key *.vpd *.fsdb ucli.key DVEfiles/ verdiLog/ novas.*

This README should help you get started with compiling and running the basic test for the RvvCoreMiniVerificationAxi DUT. Remember to complete the remaining TODOs in the UVM code itself.