-
Notifications
You must be signed in to change notification settings - Fork 0
alu_division
ALU Division is a small example of a complete Bathtub environment. It depicts a simple arithmetic logic unit (ALU) that can do integer division. This example is included in the DVCon U.S. 2024 paper, “Gherkin Implementation in SystemVerilog Brings Agile Behavior-Driven Development to UVM.” The paper contains complete code for:
- The ALU Division Gherkin feature file
- Two step definitions
- The Bathtub UVM test
This sample environment contains just enough testbench to validate that the code samples in the paper are functional. Still, this example may be instructive.
This complete example is available as an EDA Playground at bathtub_test_paper. It is open freely for viewing, but registration is required to run it.
Most the files from EDA Playground have been downloaded and committed to the GitHub repository here: https://github.com/williaml33moore/bathtub/tree/main/examples/alu_division.
EDA Playground downloads the entire playground--input and output files--in a single directory called results.
The entire results directory (minus a few unnecessary files) is committed to the repository for simplicity.
We do not recommend storing everything in a single directory like this on an actual ASIC project.
The Bathtub flow begins with a Gherkin feature file. Presumably teammates gather to discuss the behavior of a new feature and formulate their findings in a plain text file like this. The ALU Division feature file is alu_division.feature:
# This Gherkin feature file's name is alu_division.feature
Feature: Arithmetic Logic Unit division operations
The arithmetic logic unit performs integer division.
Scenario: In integer division, the remainder is discarded
Given operand A is 15 and operand B is 4
When the ALU performs the division operation
Then the result should be 3
And the DIV_BY_ZERO flag should be clear
Scenario: Attempting to divide by zero results in an error
Given operand A is 10 and operand B is 0
When the ALU performs the division operation
Then the DIV_BY_ZERO flag should be raisedIt's a functional, but very small sample that illustrates only the basics of the Gherkin language.
Comments begin with #. This comment helpfully demonstrates the convention that feature filenames end with the suffix “.feature.”
The Feature: line provides a title for the high-level feature. A feature file can have only one Feature: keyword.
The block following Feature: is free-form text for documentation purposes. It can span multiple lines.
A Scenario: is a concrete example of a discrete behavior, comprised of steps. The text is a description for documentation purposes.
The Given step is declarative and sets up this division’s operands.
The When step indicates the procedural operation being tested.
The Then step asserts the expected outcome. It is traditional to use the auxiliary verb “should” in Gherkin Then steps (“should be clear”) but it carries the same meaning as stronger verbs like “must” or “shall” in that it is considered an error if the assertion fails.
And is an alias for the preceding keyword that makes the scenario more readable than repeating the keyword Then. Gherkin has additional syntactic sugar step keywords But and *; the asterisk allows the user to create bullet lists of steps. Scenarios may have any number of Given, When, Then, And, But, and * steps in any combination.
The second scenario is an error case. Note that some lines are common between the two scenarios, differing only in literal values, illustrating that steps can be parameterized and reused across behaviors.
Leading and trailing whitespace is insignificant, but the prevailing convention is to indent keyword lines consistently.
Gherkin syntax consists solely of the keywords at the beginning of each line. The text following each keyword is arbitrary, not subject to any syntactic or grammatical requirements.
The feature file describes what our RTL should do. The RTL file is design.sv. This is very simple Verilog code for a combinational arithmetic logic unit that can add, subtract, multiply, and do integer division on two 16-bit integers. It's not intended to be realistic or synthesizable; it only needs to satisfy our sample feature file. The file contains a Verilog interface and a module.
Here is the interface:
interface alu_if ();
logic[15:0] operand_a;
logic[15:0] operand_b;
logic[3:0] operation;
logic[31:0] result;
logic[31:0] status;
modport dut (
input operand_a,
input operand_b,
input operation,
output result,
output status
);
modport driver (
output operand_a,
output operand_b,
output operation,
input result,
input status
);
modport monitor (
input operand_a,
input operand_b,
input operation,
input result,
input status
);
endinterface : alu_ifThis interface has modports for the DUT, the testbench driver, and a testbench monitor. This example doesn't have a monitor, but the modport is included for symmetry.
The DUT's interface is:
| Port | Direction | Type | Description |
|---|---|---|---|
operand_a |
input |
logic[15:0] |
operand A |
operand_b |
input |
logic[15:0] |
operand B |
operation |
input |
logic[3:0] |
opcode (0 = add, 1 = subtract, 2 = multiply, 3 = divide) |
result |
output |
logic[31:0] |
result of operation, i.e., A op B = result
|
status |
output |
logic[31:0] |
status flags following operation (bit[0] = OKAY, bit[1] = DIV_BY_ZERO error, bit[2] = invalid opcode error) |
Here is the module:
module alu (alu_if i);
localparam logic[3:0]
OP_ADD = 0,
OP_SUBTRACT = 1,
OP_MULTIPLY = 2,
OP_DIVIDE = 3;
localparam int unsigned
STATUS_OKAY = 0,
STATUS_DIV_BY_ZERO = 1,
STATUS_OP_ERR = 2;
always_comb begin
i.dut.result = 0;
i.dut.status = 0;
case (i.dut.operation)
OP_ADD : begin
i.dut.result = i.dut.operand_a + i.dut.operand_b;
i.dut.status[STATUS_OKAY] = 1;
end
OP_SUBTRACT : begin
i.dut.result = i.dut.operand_a - i.dut.operand_b;
i.dut.status[STATUS_OKAY] = 1;
end
OP_MULTIPLY : begin
i.dut.result = i.dut.operand_a * i.dut.operand_b;
i.dut.status[STATUS_OKAY] = 1;
end
OP_DIVIDE : begin
if (i.dut.operand_b != 0) begin
i.dut.result = i.dut.operand_a / i.dut.operand_b;
i.dut.status[STATUS_OKAY] = 1;
end
else begin
i.dut.result = 0;
i.dut.status[STATUS_DIV_BY_ZERO] = 1;
end
end
default : begin
i.dut.result = -1;
i.dut.status[STATUS_OP_ERR] = 1;
end
endcase
end
endmodule : aluIt's simple combinational logic that continuously outputs an arithmetic result and status based on the operand and opcode inputs.
Now that we have a DUT and its interface, we can build a testbench.
The testbench is in testbench.sv. This file consists of:
- A testbench
topmodule - A UVM environment class
- A UVM virtual sequencer class
- A UVM virtual sequence base class, compatible with the virtual sequencer
- A UVM test class
Following the familiar refrain, everything is as minimal as possible with the sole goal of validating the examples in the paper. This is not representative of best practices for a working verification environment.
module top();
import uvm_pkg::*;
typedef enum {ADD=0, SUBTRACT=1, MULTIPLY=2, DIVIDE=3} op_type;
typedef enum {OKAY=0, DIV_BY_ZERO=1, OP_ERR=2} status_type;
alu_if vif();
alu dut(vif);
initial begin
$timeformat(0, 3, "s", 20);
uvm_config_db#(virtual alu_if)::set(uvm_coreservice_t::get().get_root(), "top", "vif", vif);
run_test();
end
...
`include "alu_step_definition.svh"
endmodule : topThe top module of the simulation instantiates the DUT module and its interface, and passes the interface to the module.
The initial block stores the interface virtually in the UVM configuration database using uvm_root as context. Then it calls run_test().
The file which declares our step definitions, alu_step_definition.svh, is included near the bottom of the module.
Adding these step definitions is the only change to the top module required for Bathtub.
Step definitions are UVM sequences, so you should include or read them the same way you include or read your other sequences.
Module top defines a UVM environment class for the ALU, extending base class uvm_env:
class alu_env extends uvm_env;
`uvm_component_utils(alu_env)
alu_sequencer alu_vseqr;
virtual alu_if vif;
function new(string name, uvm_component parent);
super.new(name, parent);
endfunction : new
virtual function void build_phase(uvm_phase phase);
alu_vseqr = alu_sequencer::type_id::create("alu_vseqr", this);
endfunction : build_phase
virtual function void connect_phase(uvm_phase phase);
bit ok;
ok = uvm_config_db#(virtual alu_if)::get(uvm_coreservice_t::get().get_root(), "top", "vif", vif);
assert (ok);
assert_vif_not_null : assert (vif != null);
alu_vseqr.vif = vif;
endfunction : connect_phase
endclass : alu_envThe build phase instantiates our virtual sequencer, alu_vseqr, described in the following section.
The connect phase retrieves the virtual interface from the UVM configuration database and passes it to the virtual sequencer.
In the interest of simplicity, this environment has no additional customary components like UVM agents or scoreboards.
The environment has no dependencies on Bathtub. This environment could be used unchanged from a "normal" testbench without Bathtub.
Our UVM virtual sequencer class is as follows:
class alu_sequencer extends uvm_sequencer#(uvm_sequence_item);
`uvm_component_utils(alu_sequencer)
virtual alu_if vif;
function new (string name="alu_sequencer", uvm_component parent) ;
super.new(name, parent);
endfunction : new
endclassOur minimal testbench does not have agents, sub-sequencers, or sequence items, so the sequencer is quite small. All it needs is the DUT's virtual interface, which it gets from the environment.
Like the environment, the sequencer does not require any changes for Bathtub.
We need virtual sequences to run on our virtual sequencer. Following standard object-oriented programming practices, we declare a base class that all our sequences can extend. The base class contains common setup and convenient API methods our sequences can use to access the DUT.
class alu_base_vsequence extends uvm_sequence#(uvm_sequence_item);
`uvm_object_utils(alu_base_vsequence)
`uvm_declare_p_sequencer(alu_sequencer)
function new(string name="alu_base_vsequence");
super.new(name);
set_automatic_phase_objection(1);
endfunction : new
task set_operand_A(bit[15:0] operand_A);
`uvm_info(get_name(), "set_operand_A", UVM_MEDIUM)
p_sequencer.vif.driver.operand_a = operand_A;
endtask : set_operand_A
task set_operand_B(bit[15:0] operand_B);
`uvm_info(get_name(), "set_operand_B", UVM_MEDIUM)
p_sequencer.vif.driver.operand_b = operand_B;
endtask : set_operand_B
task do_operation(bit[3:0] operation);
`uvm_info(get_name(), "set_operation", UVM_MEDIUM)
p_sequencer.vif.driver.operation = operation;
endtask : do_operation
task get_result(output bit[31:0] result);
`uvm_info(get_name(), "get_result", UVM_MEDIUM)
result = p_sequencer.vif.driver.result;
endtask : get_result
task get_div_by_zero_flag(output bit div_by_zero_flag);
bit[31:0] status;
`uvm_info(get_name(), "get_div_by_zero_flag", UVM_MEDIUM)
status = p_sequencer.vif.driver.status;
div_by_zero_flag = status[DIV_BY_ZERO];
endtask : get_div_by_zero_flag
endclass : alu_base_vsequenceWe use the `uvm_declare_p_sequencer macro to declare a p_sequencer variable and assign it to the parent sequencer.
Instead of executing sequence items on a driver, our sequencer simply declares "setter" and "getter" accessor methods to peek and poke the signals of the virtual interface driver modport directly.
| Method | Description |
|---|---|
set_operand_A() |
Drive operand_a
|
set_operand_B() |
Drive operand_b
|
do_operation() |
Drive operation
|
get_result() |
Read result
|
get_div_by_zero_flag() |
Read status bit[1] |
Like our other components, this sequence base class is unchanged for Bathtub.
The last item in the file is the UVM test class. The test is similar to other tests, but it does require special modifications for Bathtub.
class bathtub_test extends uvm_test;
`uvm_component_utils(bathtub_test)
alu_env my_alu_env; // uvm_env containing the virtual sequencer
bathtub_pkg::bathtub bathtub;
function new(string name = "bathtub_test", uvm_component parent = null);
super.new(name, parent);
endfunction : new
virtual function void build_phase(uvm_phase phase);
bathtub = bathtub_pkg::bathtub::type_id::create("bathtub");
super.build_phase(phase);
my_alu_env = alu_env::type_id::create("my_alu_env", this);
endfunction : build_phase
task run_phase(uvm_phase phase);
bathtub.configure(my_alu_env.alu_vseqr); // Virtual sequencer
bathtub.feature_files.push_back("alu_division.feature"); // Feature file
phase.raise_objection(this);
bathtub.run_test(phase); // Run Bathtub!
phase.drop_objection(this);
endtask : run_phase
endclass : bathtub_testWe call our test class bathtub_test to signify that it runs Bathtub.
Recall that you pass this test name to the simulator on the command line, i.e., +UVM_TESTNAME=bathtub_test.
Our test extends raw base class uvm_test.
If your project has a custom base class for tests, your Bathtub test could likely extend that same custom base class.
In the build phase, our test instantiates a bathtub_pkg::bathtub object and calls it bathtub.
It also instantiates an ALU environment object.
Note that this test does not specify a default sequence to run.
It "runs" bathtub instead.
In the run phase, we configure bathtub with a handle to the virtual sequencer instance inside the environment, my_alu_env.alu_vseqr.
This way Bathtub is able to run sequences on our virtual sequencer.
Next, the run phase pushes our Gherkin feature filename alu_division.feature onto bathtub's queue of file names.
In EDA Playground, all source files are in the same directory--the simulation directory--so the pathname is relative and correct.
If the feature files were in a different directory, the filenames passed to bathtub would require correct absolute or relative pathnames.
We hard-code the filename inside the test.
Best practice would be to pass filenames into the test through some more flexible run-time means, such as a plusarg.
Finally the run phase launches bathtub with the bathtub::run_test() task, guarded by an objection.
We have a feature file, a testbench, and a test. Now we need step definitions to map the English steps in the feature file into executable SystemVerilog code. The step definitions are all in alu_step_definition.svh. Ours are all in one file, but they could be partitioned into separate files. Just make sure all the step definitions are compiled with the testbench, or else the feature file will fail.
Our feature file has seven steps:
Given operand A is 15 and operand B is 4
When the ALU performs the division operation
Then the result should be 3
And the DIV_BY_ZERO flag should be clear
Given operand A is 10 and operand B is 0
When the ALU performs the division operation
Then the DIV_BY_ZERO flag should be raisedIf we factor out the integer constants and the DIV_BY_ZERO flag value strings, we can condense that down to four parameterized steps.
Given operand A is %d and operand B is %d
When the ALU performs the division operation
Then the result should be %d
And the DIV_BY_ZERO flag should be %sThis is not the only way to refactor the step strings. For example we could have replaced the word "division" with a "%s" placeholder in order to handle different operations. For the purposes of this example, we have gone with four steps, which means we need four step definitions.
The step definitions are all UVM virtual sequences, and they all extend our virtual sequence base class alu_base_vsequence from our testbench.sv file.
Our step definitions must all implement interface class bathtub_pkg::step_definition_interface.
That is what makes them eligible to be Bathtub step definitions, and not just normal sequences.
Here is the first step definition, which sets operands A and B to given integer values.
class set_operand_A_and_B_vseq extends alu_base_vsequence implements bathtub_pkg::step_definition_interface;
`Given("operand A is %d and operand B is %d")
int operand_A, operand_B;
`uvm_object_utils(set_operand_A_and_B_vseq)
function new (string name="set_operand_A_and_B_vseq");
super.new(name);
endfunction : new
virtual task body();
// Extract the parameters
`step_parameter_get_args_begin()
operand_A = `step_parameter_get_next_arg_as(int);
operand_B = `step_parameter_get_next_arg_as(int);
`step_parameter_get_args_end
// Do the actual work using the API in the base sequence
super.set_operand_A(operand_A);
super.set_operand_B(operand_B);
endtask : body
endclass : set_operand_A_and_B_vseqThe macro `Given() associates the parameterized step string with this step definition.
The hard-working macro implements all the methods required by step_definition_interface.
We declare two local integers to hold our two operands, operand_A and operand_B.
The `uvm_object_utils macro and constructor are the "usual stuff" required when declaring UVM classes.
We override the sequence body() task to implement the step's behavior.
First we extract the actual parameters from the step string with the `step_parameter_* macros.
| Code | Description |
|---|---|
`step_parameter_get_args_begin()
|
Begin the `step_parameter_* "sandwich" |
operand_A = `step_parameter_get_next_arg_as(int);
|
Extract the first argument from the step string using the parameterized `Given string as a template |
operand_B = `step_parameter_get_next_arg_as(int);
|
Extract the next argument |
`step_parameter_get_args_end
|
End the `step_paramter_* "sandwich" |
The arguments to the `step_parameter_get_next_arg_as() macros--in this case int--must match the type declaration of the operand_A and operand_B variables so the values get converted correctly.
Lastly we call the set_operand_A() and set_operand_B() functions from our base class ("super"), passing them our two operands. (The "super" is not required; it's included here just to point out where those methods came from.)