Testbenches¶
For every module, bust writes tb/<module>_tb.vhd, a self-checking
testbench. It instantiates the bus endpoint <module>_<bus>_endpoint, drives
the bus with a bus functional model (BFM), drives the from_hw record,
watches the to_hw record, and checks the results with
UVVM. It does not use your <module>.vhd. This page describes what the testbench
checks, what it needs, and how to compile and run it.
bust does not write simulator scripts, so you add the testbench to your own simulation flow.
What it checks¶
The testbench entity is <module>_tb, with no ports or generics. It runs a
10 ns clock and holds the module in reset for 500 ns. It sets the base address
to 0 with G_BASE_ADDRESS, the base address check on with
G_CHECK_BASE_ADDRESS, and G_MODULE_ADDR_WIDTH two bits larger than the
registers need. It then runs one group of checks for each
kind of register below. A register that fits a row gets that row’s checks.
Register |
Checks |
|---|---|
Plain read-write: every field |
Writes 1 to every field bit, reads the same value back, and checks that |
One enumerated read-write field |
Writes the highest value of the enumeration and reads it back. |
Write-only, or |
Writes 1 to every field bit and checks that the register reads back 0. |
|
Writes |
|
Writes |
Hardware status: every field |
Drives |
|
Up to four steps, each ending with a read: a software write, also checked on |
|
Counts the strobe pulses on |
One field with |
Holds |
Last, the testbench writes and reads addresses where no register sits: an
unused register offset if there is one, an address one byte into a register
when addresses count bytes, an address above the registers, and an address with
another base address. Each access must get an
error response, and each read must return the
G_UNMAPPED_READ_DATA that the testbench sets. A plain read-write register is
then read again to check that none of these writes reached it. The testbench
also sets G_ERR_ON_BAD_ACCESS, and checks that a write to each register
software cannot write, and a read of each one it cannot read, get an error.
The groups run in the order of the table, not in register order. A register
can be in more than one group. A read-write register with a swmod field, for
example, gets both the plain read-write checks and the strobe checks.
Access modes describes the behaviour these checks expect.
The testbench does not check reset values directly. Registers that fit no row
get no checks. Examples are read-only constants (sw: ro with no hardware
writer), enumerated fields that hardware writes, and a register with a field
that software cannot access (sw: na).
This is the onread group and part of the hardware modifier group from the
testbench of the prototype example in the repository, where reg5 has an
rclr and an rset field and reg4 has a we field and a field with both
hwset and hwclr:
log(ID_LOG_HDR, "reg5: onread software side effects", C_SCOPE);
bus_write(f_addr(C_PROTOTYPE_REG5_OFFSET), 32x"00000055", "write reg5");
bus_check(f_addr(C_PROTOTYPE_REG5_OFFSET), 32x"00000055", "reg5 first read returns stored value");
bus_check(f_addr(C_PROTOTYPE_REG5_OFFSET), 32x"000000F0", "reg5 second read reflects onread");
log(ID_LOG_HDR, "reg4: hardware we overrides the stored value", C_SCOPE);
wait until falling_edge(clk);
from_hw.reg4.field0.value <= 4x"A";
from_hw.reg4.field0.we <= '1';
wait until falling_edge(clk);
from_hw.reg4.field0.we <= '0';
bus_check(f_addr(C_PROTOTYPE_REG4_OFFSET), 32x"0000010A", "reg4 reflects the hardware we override");
log(ID_LOG_HDR, "reg4: hwclr clears fields (and beats hwset)", C_SCOPE);
wait until falling_edge(clk);
from_hw.reg4.field1.set <= '1';
from_hw.reg4.field1.clr <= '1';
wait until falling_edge(clk);
from_hw.reg4.field1.set <= '0';
from_hw.reg4.field1.clr <= '0';
bus_check(f_addr(C_PROTOTYPE_REG4_OFFSET), 32x"0000000A", "reg4 reflects hwclr");
bus_write and bus_check wrap the BFM of the bus. C_PROTOTYPE_REG5_OFFSET
and C_PROTOTYPE_REG4_OFFSET are the register offsets from
<module>_regfile_pkg.
Pass or fail¶
Every check is a UVVM check with alert level error. The testbench turns off
UVVM’s other log messages and logs one header line for each group, such as
reg5: onread software side effects, so the log shows how far it got.
UVVM stops the simulation at the first error by default. The alert message names the register, the value read and the value expected.
When every check passes, the testbench prints UVVM’s alert summary, which ends with:
>> Simulation SUCCESS: No mismatch between counted and expected serious alerts
It then logs SIMULATION COMPLETED and ends the simulation with
std.env.stop. In a script, treat a non-zero exit status from the simulator,
or a UVVM FAIL line in the log, as a failure.
What it needs¶
VHDL-2008. The testbench uses context clauses, sized bit-string literals such as
32x"00000055", andstd.env.stop.The generated files from the same run, compiled into the same library as the testbench. Every generated file and the testbench refer to each other through
work.UVVM’s
uvvm_utillibrary, for logging and checks.The BFM for the bus, in a library with the name the testbench uses:
Bus |
Libraries the testbench uses |
BFM |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A Wishbone classic master BFM written into the testbench itself. |
|
|
An APB master BFM written into the testbench itself. |
The testbench uses only the BFM package of each VIP, not its VVC.
For IPBus, the generated endpoint and the starter top level also use the
ipbus library, so you need it for synthesis as well. vip_ipbus uses uvvm_util and
ipbus, so compile it after both.
Compile and run¶
In any simulator, the steps are:
Compile
uvvm_utilinto a library nameduvvm_util.Compile the libraries for your bus from the table above. For IPBus, compile
ipbusbeforevip_ipbus.Compile the generated files and the testbench into one library, in this order:
hdl/<module>_localbus_pkg.vhdhdl/<module>_regfile_pkg.vhdhdl/<module>_regfile.vhdhdl/<module>_<bus>_endpoint.vhdtb/<module>_tb.vhd
Elaborate and run
<module>_tb.
Several modules can share one library. Every package carries the module name, so the generated files of two modules do not clash.
Example with nvc¶
This example follows the scripts the bust repository uses to simulate its own examples with nvc. It is one way to do it, not something bust installs.
nvc can fetch and compile UVVM, including uvvm_util and all its VIPs, into
its own library directory, where it finds them without further options:
nvc --install uvvm
For an AXI4-Lite module, that is all you need. From the directory you gave to
-o, compile the files of the module into the default work library, then
elaborate and run the testbench:
nvc --std=08 -a example_axi/hdl/example_axi_localbus_pkg.vhd \
example_axi/hdl/example_axi_regfile_pkg.vhd \
example_axi/hdl/example_axi_regfile.vhd \
example_axi/hdl/example_axi_axi_endpoint.vhd \
example_axi/tb/example_axi_tb.vhd
nvc --std=08 -e example_axi_tb
nvc --std=08 -r example_axi_tb
SBI, Avalon-MM, Wishbone and APB modules work the same way, with their own endpoint file.
An IPBus module also needs the ipbus and vip_ipbus libraries. With
checkouts of ipbus-firmware and vip_ipbus in the same directory, compile them
into a directory libs and add it to the library search path with -L:
mkdir -p libs
nvc --std=08 --work=ipbus:libs/ipbus \
-a ipbus-firmware/components/ipbus_core/firmware/hdl/ipbus_package.vhd
nvc --std=08 -L libs --work=vip_ipbus:libs/vip_ipbus \
-a --relaxed vip_ipbus/src/ipbus_bfm_pkg.vhd
vip_ipbus needs --relaxed, because UVVM uses a shared variable as a default
parameter value, which strict VHDL-2008 does not allow. nvc takes --relaxed
only after -a. Then compile and run the module as for AXI4-Lite, with
-L libs on every command:
nvc --std=08 -L libs -a example_ipbus/hdl/example_ipbus_localbus_pkg.vhd \
example_ipbus/hdl/example_ipbus_regfile_pkg.vhd \
example_ipbus/hdl/example_ipbus_regfile.vhd \
example_ipbus/hdl/example_ipbus_ipb_endpoint.vhd \
example_ipbus/tb/example_ipbus_tb.vhd
nvc --std=08 -L libs -e example_ipbus_tb
nvc --std=08 -L libs -r example_ipbus_tb
The repository’s CI compiles and runs the generated testbenches of its
examples this way, including one for each of the six buses. It uses nvc 1.19.3,
ipbus-firmware v1.16 and a fixed commit of vip_ipbus, in the Docker image
described in sim/.