All of that was necessary because SystemVerilog didn’t have a way to extend coverage groups natively. In contrast, the e language makes it possible to modify coverage definitions from anywhere in the verification environment. Getting anything similar in SystemVerilog required quite a bit of pre-planning and infrastructure code.

With the release of IEEE Std 1800-2023, SystemVerilog finally got a new language feature in this area. Section 19.4.1 Embedded covergroup inheritance describes that it’s now possible for a covergroup to extend another covergroup. This is great news, if it means we can express what we need without all of the scaffolding we had to put in place before.

In this post, let’s have a look at what covergroup extends brings to the table and see how much of what I wrote back then has become obsolete.

The Original Example

Let’s start by revisiting the example from the original post series. We had a simple RISC CPU that supported four operations (ADD, SUB, MUL and DIV) on eight registers (R0 to R7). Here’s what our initial coverage looked like:

class coverage_collector;

    covergroup cg with function sample(operation_e operation, register_e op1, register_e op2, register_e dest);
        coverpoint operation;
        coverpoint op1;
        coverpoint op2;
        coverpoint dest;

        operation_vs_op1 : cross operation, op1;
        operation_vs_op2 : cross operation, op2;
        operation_vs_dest : cross operation, dest;

        same_reg_both_ops : coverpoint (op1 == op2);
        same_reg_op1_and_dest : coverpoint (op1 == dest);
        same_reg_op2_and_dest : coverpoint (op2 == dest);
        same_reg_both_ops_and_dest : coverpoint (op1 == dest && op2 == dest);

        option.per_instance = 1;
    endgroup

    // ...
endclass

Notice that we’re now using the with function sample(...) construct. This allows us to avoid polluting our class with member variables that don’t actually represent the object’s state, but are just used for “argument passing” to the coverpoint expressions.

Variant with Fewer Operations

The original posts introduced a variant of the CPU which dropped the MUL and DIV instructions. They showed how to customize the coverage model for it, by using hooks to control the contents of the operation coverpoint’s ignore bins.

With covergroup extends, this becomes really straightforward:

class no_mul_div_coverage_collector extends coverage_collector;

    covergroup extends cg;
        coverpoint operation {
            ignore_bins mul_div = { MUL, DIV };
        }
    endgroup

endclass

We can now customize the ignore bins without having to set up any infrastructure for future extensions. Notice that we don’t need to specify the arguments for sample(...) again. The extended covergroup inherits the signature from the base, so no need for boilerplate code.

But here’s where things get tricky. If we compile and run this code, we’ll notice something interesting: the crosses still include all the multiplication and division bins. This is because the cross definitions in the base class still use the base class’s definition of the operation coverpoint, not our refined version. Initially, I thought that this was a bug in the tool, but actually things are working as specified in the standard:

Even if a coverage point in the base covergroup does not contribute to the computation, a cross […] in the base covergroup that includes that base coverpoint still contributes to the computation unless there is a cross with the same name in the derived covergroup.

To fix this, we need to redeclare the crosses:

class no_mul_div_coverage_collector extends coverage_collector;

    covergroup extends cg;
        // ...

        operation_vs_op1 : cross operation, op1;
        operation_vs_op2 : cross operation, op2;
        operation_vs_dest : cross operation, dest;
    endgroup

endclass

This feels a bit unsatisfying. From the point of view of class inheritance, coverpoints behave like non‑virtual functions: the derived coverpoint hides the original operation definition in the derived class’s scope rather than overriding it for the base class. Since the base class’s crosses still reference the original operation, we have to hide those too by redeclaring them.

In e, when extending a coverage item, the crosses that reference that item use the updated definition. The folks on the IEEE 1800 committee could have used the e language as a reference when designing embedded covergroup inheritance, but, for reasons I don’t know, they decided to implement different semantics. I can’t think of any use case where keeping base crosses bound to base coverpoints is actually helpful. The example above shows the opposite. If you know of a situation where this behavior is desirable, please tell me in a comment.

Variant with Fewer Registers: More of the Same

Let’s look at another variant from the original post series, where our CPU only implements registers R0 through R3. We have to adapt our coverage to ignore the higher-numbered registers. Following the same pattern as before, we extend the covergroup and add ignore bins:

class fewer_regs_coverage_collector extends coverage_collector;

    covergroup extends cg;
        coverpoint op1 {
            ignore_bins r4_to_r7 = { R4, R5, R6, R7 };
        }
        coverpoint op2 {
            ignore_bins r4_to_r7 = { R4, R5, R6, R7 };
        }
        coverpoint dest {
            ignore_bins r4_to_r7 = { R4, R5, R6, R7 };
        }

        operation_vs_op1 : cross operation, op1;
        operation_vs_op2 : cross operation, op2;
        operation_vs_dest : cross operation, dest;
    endgroup

endclass

Again, we need to redeclare all the crosses that involve the modified coverpoints. The whole point of using covergroup extends was to avoid having to write too much code. Granted, this is boilerplate code, so it’s simpler than having to build the infrastructure for extensibility, but forgetting to redeclare crosses is easy to overlook and can potentially create work for us in the future.

Combining Variants: Where Things Break Down

Now here’s where we hit a wall. In the original post series, we looked at a final CPU variant that had both limitations: only four registers and only addition and subtraction. With single inheritance, we can’t cleanly combine both extensions.

We could create a new class that extends one of them and adds the other ignores. For example:

class fewer_regs_no_mul_div_coverage_collector extends no_mul_div_coverage_collector;

    covergroup extends cg;
        coverpoint op1 {
            ignore_bins r4_to_r7 = { R4, R5, R6, R7 };
        }
        coverpoint op2 {
            ignore_bins r4_to_r7 = { R4, R5, R6, R7 };
        }
        coverpoint dest {
            ignore_bins r4_to_r7 = { R4, R5, R6, R7 };
        }

        operation_vs_op1 : cross operation, op1;
        operation_vs_op2 : cross operation, op2;
        operation_vs_dest : cross operation, dest;
    endgroup

endclass

But this just means duplicating code. We’ve essentially reimplemented the functionality in fewer_regs_coverage_collector. Of course, in this case we could switch where we start the inheritance tree, by creating a no_mul_div_fewer_regs_coverage_collector which extends fewer_regs_coverage_collector, because this way we have less code to duplicate. This is still a compromise, though. The problem isn’t only the amount of duplicated code, but also the fact that we have to remember to look for it if we ever need to change it.

We could try to use the mixin pattern (which I’ve written about before) to work around this, but that comes with its own set of problems and added complexity.

The dynamic variant with policy classes that I described in the second post of the original series handled this more elegantly. It allowed us to pass multiple policy objects and compose their filtering behavior. This is a classic example of how inheritance can’t beat composition.

When Requirements Change: Redeclaring Means Rewriting From Scratch

The problems don’t stop at crosses. There’s another subtlety that makes modifying existing coverpoints more painful than it looks.

Let’s say that during development, the requirements for our CPU change such that R0 is now a hardwired zero register. This means it can never be the destination of an instruction. We have to update the base coverage model to capture this:

class coverage_collector;

    covergroup cg with function sample(operation_e operation, register_e op1, register_e op2, register_e dest);
        coverpoint dest {
            ignore_bins r0_cannot_be_dest = { R0 };
        }

        // ...
    endgroup

    // ...
endclass

For the fewer_regs_coverage_collector class, if we were to check the bins of the dest coverpoint, we would unexpectedly find that R0 is still included. This is because we’re redeclaring the coverpoint: we’re not extending what’s already there, we’re replacing it entirely. There’s no way to refer to the existing bins from the base coverpoint and just add to them. We have to write it all out again:

class fewer_regs_coverage_collector extends coverage_collector;

    covergroup extends cg;
        coverpoint dest {
            ignore_bins r0_cannot_be_dest = { R0 };
            ignore_bins r4_to_r7 = { R4, R5, R6, R7 };
        }

        // ...
    endgroup

endclass

In e, the prev keyword lets us reference the previous (base) definition of a cover item, so we can include its existing bin expressions without repeating them. This is another area where the folks on the IEEE 1800 committee could have taken a page from the e language book, but SystemVerilog has no equivalent construct. When we redeclare a coverpoint, we start from a blank slate.

For the case where we have both fewer registers and no MUL and DIV operations, since we copied and pasted code from fewer_regs_coverage_collector, we have to fix it there as well:

class fewer_regs_no_mul_div_coverage_collector extends no_mul_div_coverage_collector;

    covergroup extends cg;
        coverpoint dest {
            ignore_bins r0_cannot_be_dest = { R0 };
            ignore_bins r4_to_r7 = { R4, R5, R6, R7 };
        }

        // ...
    endgroup

endclass

Because the change was fresh, it was easy to remember to update this code. If a lot of time had passed from when we originally wrote it, we might not have been so lucky.

The same issue applies to crosses. If any of the crosses that we were redeclaring had its own ignore bins, we’d have to duplicate those too. The need to redeclare coverage group members is actually more problematic than we initially thought. (I would have liked to show an example of this by having some ignore bins defined in a cross, but the tool which supports covergroup extends doesn’t have good support for defining cross bins.)

Adding New Coverage: Where covergroup extends Shines

So far we’ve been looking at the rough edges. Let me end on a more positive note, because covergroup extends is genuinely well-suited for one thing: adding coverage items that are missing from the base class entirely.

Let’s assume that the original coverage model is part of a reusable library for CPU verification, which we can’t modify. The same_reg_* coverpoints only track whether two registers happen to be the same, but they’re never crossed against the operation type and the register value. That’s potentially interesting coverage, for example “Does a SUB instruction ever write back into R1 after it read the first operand also from R1?”.

We can layer these crosses on top without touching the base class at all:

class enhanced_coverage_collector extends coverage_collector;

    covergroup extends cg;
        operation_vs_same_op1_and_op2 : cross operation, op1, same_reg_both_ops;
        operation_vs_same_dest_and_op1 : cross operation, dest, same_reg_op1_and_dest;
        operation_vs_same_dest_and_op2 : cross operation, dest, same_reg_op2_and_dest;
        operation_vs_same_dest_and_both_ops : cross operation, dest, same_reg_both_ops_and_dest;
    endgroup

endclass

Without covergroup extends, we would have had to rewrite the entire covergroup: all its coverpoint definitions, all their bins, and all its crosses.

(You might notice that the crosses look a bit unusual. Ideally we would cross op1 directly with op2, or dest with op1, and filter to keep only the bins where they are equal. I tried doing exactly that, using the with syntax from section 19.6.1.2 Cross bin with covergroup expressions. When this didn’t work, I tried to instead cross with the boolean same_reg_* coverpoints and to use the older binsof ... intersect syntax from section 19.6.1 Defining cross coverage bins. This also didn’t work, so I stopped trying to filter out the cases where the registers are not the same. The result is not as clean, but it’s good enough for the purpose of demonstrating covergroup extends.)

Conclusion

So how much of what I wrote back in 2015 has become obsolete? Pretty much none of it, as it turns out.

Embedded covergroup inheritance is a welcome addition to SystemVerilog. It’s a good feature, but some questionable design decisions stop it from being great.

For adding new coverpoints and crosses on top of a base model, it works cleanly, with minimal boilerplate, and no need to touch the original class. This use case alone makes it worth knowing about.

For modifying existing coverage, however, the story is less rosy. Redeclaring a coverpoint replaces it entirely and there is no way to build on what the base already defined. Also, since crosses don’t automatically track changes to the coverpoints they are composed of, any cross that involves a redeclared coverpoint must itself be redeclared.

For composable, modification-heavy scenarios, the policy class approach from the original post series still holds its ground. The two techniques are best treated as complements rather than replacements for each other.

One practical caveat: simulator support for covergroup extends is still far from universal. If you want to experiment with the examples in this post, they might not work in your tool of choice. If that’s the case, I’d encourage you to ask your EDA vendor to implement this feature. The more teams make the request, the higher the chances it gets worked on.

As always, you can find the code for this post on GitHub. Thanks for reading and see you next time!

A UVM test usually starts a certain sequence during its run phase (but other run-time phases could also be used). Let’s assume that we have three sequences: some_sequence, some_other_sequence and yet_another_sequence, which we each want to start from its own test.

Here’s an example of a test that starts some_sequence:

class test_that_executes_some_sequence extends uvm_test;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  virtual task run_phase(uvm_phase phase);
    some_sequence seq = some_sequence::type_id::create("seq", this);
    phase.raise_objection(this);
    seq.start(null);
    phase.drop_objection(this);
  endtask

  `uvm_component_utils(test_that_executes_some_sequence)

endclass

A test that starts some_other_sequence is:

class test_that_executes_some_other_sequence extends uvm_test;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  virtual task run_phase(uvm_phase phase);
    some_other_sequence seq = some_other_sequence::type_id::create("seq", this);
    phase.raise_objection(this);
    seq.start(null);
    phase.drop_objection(this);
  endtask

  `uvm_component_utils(test_that_executes_some_other_sequence)

endclass

Finally, a test that starts yet_another_sequence is:

class test_that_executes_yet_another_sequence extends uvm_test;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  virtual task run_phase(uvm_phase phase);
    yet_another_sequence seq = yet_another_sequence::type_id::create("seq", this);
    phase.raise_objection(this);
    seq.start(null);
    phase.drop_objection(this);
  endtask

  `uvm_component_utils(test_that_executes_yet_another_sequence)

endclass

That’s a pretty impressive amount of code just to say “start each of the three sequences in its own test”. The amount is not necessarily the problem, but coupled with the fact that there is a lot of duplication makes it become one. It’s not immediately obvious whether the three files differ by more than just the sequence and test names or whether there are any hidden tweaks which make them behave slightly differently.

We would like to achieve something like the following pseudo-code:

create_test_that_starts(some_sequence)
create_test_that_starts(some_other_sequence)
create_test_that_starts(yet_another_sequence)

This way we know that the tests only differ in the sequence being started. Even cooler would be to be able to specify tests using loops:

for seq in [some_sequence, some_other_sequence, yet_another_sequence]:
    create_test_that_starts(seq)

This matches the natural language description of our problem statement: “start each of the three sequences in its own test”.

One possible solution would be to use macros, but these generally suffer from an array of issues, like lack of clarity as to how and where they should be used, poor error messages when writing code that doesn’t compile, lack of debug capabilities, etc.

Another widespread solution for such problems in the industry is to use code generation. I’m generally skeptical of code generation of this sort, which usually means passing the buck to some other half baked scripts. These scripts would be in a different language, so they would require us to either spin off or duplicate information we need in SystemVerilog. They also wouldn’t integrate as well into the overall development and execution flow.

We’ll look at an alternative way of defining tests, which doesn’t suffer from the problems of the “traditional” approaches. We won’t just look at the finished code, but take a journey through the steps required to build it.

Before we begin, let’s do a crash course in how UVM starts tests. UVM uses the value of +UVM_TESTNAME as a type name when it instructs the factory to create the test. Conceptually, it does the following:

string test_type_name = get_value_of_plusarg("UVM_TESTNAME");
uvm_component test = uvm_factory()::get().create_component_by_name(test_type_name);

Users define their test classes and register them with the factory using the uvm_component_utils macro. This makes it possible for the test type name to be used as an argument to +UVM_TESTNAME.

To reduce the amount of code we need, we want to consolidate the duplicated code into a single place. If we look at the tests, they only differ by the type of the seq variable, which holds the sequence to start. We can create a shared template by using a class that is parameterized by the sequence type:

class test_that_executes_sequence_via_param #(type SEQ = int) extends uvm_test;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  virtual task run_phase(uvm_phase phase);
    SEQ seq = SEQ::type_id::create("seq", this);
    phase.raise_objection(this);
    seq.start(null);
    phase.drop_objection(this);
  endtask

  `uvm_component_param_utils(test_that_executes_sequence_via_param #(SEQ))

endclass

While the uvm_component_param_utils macro will register the class with the UVM factory, it will not register it using a type name. Since we don’t have type names, we won’t have anything to pass to +UVM_TESTNAME to select tests.

We could create subclasses of the parameterized class, where we pass the desired sequence type for the SEQ parameter, and register those with the factory. For example, for some_sequence we would have:

class test_that_executes_some_sequence_using_param
    extends test_that_executes_sequence_via_param #(some_sequence);

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  `uvm_component_utils(test_that_executes_some_sequence_using_param)

endclass

This is still a pretty large amount of boilerplate. Granted, this is code that might not ever change. We could do a little better, though.

The uvm_component_utils macro maps type names to “real” classes using the uvm_component_registry class. If we were to expand the code for uvm_component_utils(test_that_executes_some_sequence_using_param) we would see uvm_component_registry #(test_that_executes_some_sequence_using_param, "test_that_executes_some_sequence_using_param"). This instructs the factory to create a component of type test_that_executes_some_sequence_using_param whenever the string "test_that_executes_some_sequence_using_param" is supplied as a type name.

The exact way this is done is kind of all over the place. The underlying class that the factory uses is called uvm_object_wrapper. It declares two functions, create_object() and create_component(), which the factory uses to create instances. The uvm_component_registry class extends uvm_object_wrapper and implements its create_component() function, but it also has many other functions related to registering itself with the factory and handling type overrides. A cleaner implementation would have been for uvm_component_registry to be its own class, that doesn’t extend uvm_object_wrapper, that instead creates an instance of a uvm_object_wrapper and registers it with the factory instead of itself. This would have provided a better separation of concerns.

We want to create our own mapping, which instructs the factory to create a component of type test_that_executes_sequence_via_param #(some_sequence) whenever the string "test_that_executes_some_sequence_using_param" is supplied as a type name. The easiest way to do this is by creating own own class that extends uvm_component_registry with the appropriate parameters:

class wrapper_for_test_that_executes_some_sequence_using_param
    extends uvm_component_registry #(test_that_executes_sequence_via_param #(some_sequence), "test_that_executes_some_sequence_using_param");
endclass

This class just has to exist. The code in uvm_component_registry will take care of instructing the UVM factory to produce an instance of the test class parameterized with some_sequence when test_that_executes_some_sequence_using_param is passed as a value for +UVM_TESTNAME.

While using parameterization solves a part of the boilerplate issue by having the aspect of “starting sequences” in a single class, it still requires us to write the wrapper classes necessary for factory registration by hand. We can’t implement any kind of looping over the sequences we want to start from tests, as we set out to do.

We have to transpose our code from using types and parameterization to some kind of dynamic constructs. If we go back to test_test_that_executes_sequence_via_param, we see that the type of sequence is not at all relevant to starting it. All uvm_sequences have a start() task, which can be used by the test to start it:

  virtual task run_phase(uvm_phase phase);
    uvm_sequence seq = create_seq();
    phase.raise_objection(this);
    seq.start(null);
    phase.drop_objection(this);
  endtask

We just need a way of creating sequences without hard-coding the exact type. Luckily, the UVM factory already has us covered here. Remember that uvm_object_utils creates a subclass of uvm_object_wrapper that can create the “real” type:

uvm_sequence seq;
uvm_object_wrapper seq_wrapper = some_sequence::get_type()
$cast(result, seq_wrapper.create_object("seq"));

Instead of hard coding the sequence type in the test, so the test can create an instance of that sequence itself, we can instead supply it with a uvm_object_wrapper that produces that sequence:

class test_that_executes_sequence_via_constructor extends uvm_test;

  local const uvm_object_wrapper seq_wrapper;

  function new(string name, uvm_component parent, uvm_object_wrapper seq_wrapper);
    super.new(name, parent);
    this.seq_wrapper = seq_wrapper;
  endfunction

  virtual task run_phase(uvm_phase phase);
    uvm_sequence seq = create_seq();
    phase.raise_objection(this);
    seq.start(null);
    phase.drop_objection(this);
  endtask

  local function uvm_sequence create_seq();
    uvm_sequence result;
    if (!$cast(result, seq_wrapper.create_object("seq")))
      `uvm_fatal("TEST", "Cannot construct sequence from supplied wrapper")
    return result;
  endfunction

endclass

Notice that we have to check at run time whether the seq_wrapper we got can really produce an object of type uvm_sequence. In other programming languages, which take class parameterization seriously and where it’s not just an afterthought, it is possible to enforce this compile time. This would be done by declaring the seq_wrapper argument as being a uvm_object_wrapper of a type that extends uvm_sequence. The syntax could look something like the following:

function new(uvm_object_wrapper #(? extends uvm_sequence) seq_wrapper)

For reference, in Java this language feature is called an upper bounded wildcard.

The tricky part is figuring out how to supply the sequence wrapper. We’ve already talked about how the factory uses uvm_object_wrappers to perform the actual creation and maps type names to such objects.

Let’s look at how we would create a uvm_object_wrapper that creates a test that starts some_sequence and registers itself with the name "test_that_executes_some_sequence_using_constructor". The first thing we need to implement is the create_component() function:

class wrapper_for_test_that_executes_some_sequence_using_constructor
    extends uvm_object_wrapper;

  virtual function uvm_component create_component(string name, uvm_component parent);
    test_that_executes_sequence_via_constructor result = new(name, parent, some_sequence::get_type());
    return result;
  endfunction

endclass

The uvm_object_wrapper class also provides a get_type_name() function, which is supposed to return the name of type being wrapped. I noticed that if we don’t implement this function, we get some annoying prints in the console, so let’s do this as well:

class wrapper_for_test_that_executes_some_sequence_using_constructor
    extends uvm_object_wrapper;

  virtual function string get_type_name();
    return "test_that_executes_some_sequence_using_constructor";
  endfunction

  // ...

endclass

Last, but not least, we should also register this wrapper with the UVM factory, so it knows how to produce instances when "test_that_executes_some_sequence_using_constructor" is used as a type name. This is more or less a copy/paste of how uvm_component_registry does it:

class wrapper_for_test_that_executes_some_sequence_using_constructor
    extends uvm_object_wrapper;

  local static wrapper_for_test_that_executes_some_sequence_using_constructor me = get();

  local function new();
  endfunction

  static function wrapper_for_test_that_executes_some_sequence_using_constructor get();
    if (me == null) begin
  	  uvm_coreservice_t cs = uvm_coreservice_t::get();
  	  uvm_factory factory = cs.get_factory();
      me = new();
      factory.register(me);
    end
    return me;
  endfunction

  // ...

endclass

It’s worth discussing about how registration is actually triggered. Notice that the me variable is static, but has a initial value. This value is computed during static initialization, which happens very early within a simulation, before any processes (e.g. from initial or always blocks) are executed.

If we were to have to write a uvm_object_wrapper for each of the sequences we want to start, we’d end up with a lot of boilerplate. This is exactly what we want to avoid.

We notice that we can pass the sequence wrapper as an argument to the test wrapper itself:

class wrapper_for_test_that_executes_sequence_using_constructor
    extends uvm_object_wrapper;

  local const uvm_object_wrapper seq_wrapper;

  function new(uvm_object_wrapper seq_wrapper);
    this.seq_wrapper = seq_wrapper;
  endfunction

  virtual function string get_type_name();
    return $sformatf("test_that_executes_%s_using_constructor", seq_wrapper.get_type_name());
  endfunction

  virtual function uvm_component create_component(string name, uvm_component parent);
    test_that_executes_sequence_via_constructor result = new(name, parent, seq_wrapper);
    return result;
  endfunction

endclass

We can extract the code for factory registration to a different class, which is responsible for registering tests for the sequences we want to start:

class tests_that_execute_each_sequence;

  local static bit test_for_some_other_sequence_registered = register_test(some_other_sequence::get_type());
  local static bit test_for_yet_another_sequence_registered = register_test(yet_another_sequence::get_type());

  local static function bit register_test(uvm_object_wrapper seq_wrapper);
    uvm_coreservice_t cs = uvm_coreservice_t::get();
  	uvm_factory factory = cs.get_factory();
    wrapper_for_test_that_executes_sequence_using_constructor test_wrapper = new(seq_wrapper);
    factory.register(test_wrapper);
    return 1;
  endfunction

endclass

Notice that the register_test() function returns a bit, but the value is always 1. This is so that it can be used as an initial value for a static helper variable, so that the function is called during static initialization.

The tests_that_execute_each_sequence class does a bit much, though. It knows how to register tests with the factory, but is also registers the tests we want.

We can extract the code for registration into an own class:

class test_builder;

  local const wrapper_for_test_that_executes_sequence_using_constructor test_wrapper;

  local function new(uvm_object_wrapper seq_wrapper);
    test_wrapper = new(seq_wrapper);
  endfunction

  static function test_builder for_sequence_type(uvm_object_wrapper seq_wrapper);
    test_builder result = new(seq_wrapper);
    return result;
  endfunction

  function bit register();
    uvm_coreservice_t cs = uvm_coreservice_t::get();
  	uvm_factory factory = cs.get_factory();
    factory.register(test_wrapper);
    return 1;
  endfunction

endclass

Registering tests for the sequences is a bit cleaner, because we’re not distracted by the actual test builder code.

class tests_that_execute_each_sequence;

  local static bit test_for_some_other_sequence_registered
      = test_builder::for_sequence_type(some_other_sequence::get_type()).register();
  local static bit test_for_yet_another_sequence_registered
      = test_builder::for_sequence_type(yet_another_sequence::get_type()).register();

endclass

Now it starts to become obvious that we can use a loop to register the tests:

class tests_that_execute_each_sequence;

  local static bit tests_registered = register_tests();

  local static function bit register_tests();
    uvm_object_wrapper seqs[] = '{
        some_sequence::get_type(),
        some_other_sequence::get_type(),
        yet_another_sequence::get_type() };

    foreach (seqs[i])
      void'(test_builder::for_sequence_type(seqs[i]).register());
  endfunction

endclass

While it’s very convenient to use loops, being able to use procedural code to define tests is extremely powerful. It makes it possible to do things like to conditionally define tests based on conditions known to the testbench (for example, whether a feature is present in the DUT) or to read some input file and define tests based on that. The space of possibilities is huge.

To reap the benefits of dynamic test creation, we would want to integrate the code from above into our own projects. The test_builder class and its associated classes feel as if they shouldn’t depend on any kind of user code and that they could be reusable.

One thing a uvm_test also does, that we completely left out of the examples, is to instantiate the rest of the verification environment (i.e. the agents, scoreboards, etc.). The examples we’ve looked at so far completely ignore this fact. We’ll emulate it with an info message in the build phase:

virtual class abstract_test extends uvm_test;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  virtual function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    `uvm_info("TEST", "Building TB...", UVM_NONE)
  endfunction

endclass

The test_builder registers tests of the type test_that_executes_sequence, which only knows how to start sequences, but knows nothing about TB creation. In order to combine the two, test_that_executes_sequence can become a mixin, allowing the user to include it onto their abstract_test class:

class test_that_executes_sequence #(type T = uvm_test) extends T;

    // ...

endclass

Naturally, the parameter has to propagate to the other classes as well:

class wrapper_for_test_that_executes_sequence #(type T = uvm_test) extends uvm_object_wrapper;

  virtual function uvm_component create_component(string name, uvm_component parent);
    test_that_executes_sequence #(T) result = new(name, parent, seq_wrapper);
    return result;
  endfunction

  // ...

endclass

class test_builder #(type T = uvm_test);

  local const wrapper_for_test_that_executes_sequence #(T) test_wrapper;

  static function test_builder #(T) for_sequence_type(uvm_object_wrapper seq_wrapper);
    test_builder #(T) result = new(seq_wrapper);
    return result;
  endfunction

  // ...

endclass

This allows users to layer test building onto their own code:

class tests_that_execute_each_sequence;

  local static function bit register_tests();
    // ...
    foreach (seqs[i])
      void'(test_builder #(abstract_test)::for_sequence_type(seqs[i]).register());
  endfunction

  // ...

endclass

At the moment, I see the test builder as more of a pattern, instead of a reusable library, because there’s not much code there to reuse directly. A full example can be found at https://github.com/verification-gentleman-blog/creating-uvm-tests-dynamically. It can serve as the basis for implementing the pattern in your own projects.

In a future post, I’m going to show you how to use dynamic test creation to layer constraints onto a random test, in order to target certain areas of the design space. Be sure to subscribe if you don’t want to miss it.

The Verification Gentleman Blog will be moving from Blogger.

Why?

While Blogger was a great platform to start on, especially considering the fact that it’s 100% free, I feel that I’ve outgrown it.

The interface is very arcane and it’s very difficult to do any kind of customization. For example, setting up syntax highlighting required fiddling with a lot of things to get it working and even then the results aren’t all that great. It’s very easy to mess up the entire blog and not be able to restore it to a previous version.

Writing posts requires too much manual intervention. It all went downhill when Windows Live Writer stopped working, which meant that edits had to be done in the web interface. I spent quite some time setting up a flow to generate the HTML for Blogger using Pelican, but this still requires a lot of manual steps. Since previews have to be done from the web interface, any kind of change requires an update of the post’s source, generation of the HTML, copy/pasting the HTML into the Blogger web interface and re-inspecting the preview. This is very time consuming and draining. Working with images or any other kinds of external content is also a pain.

Blogger currently only supports comments from Google users. It used to support more authentication sources, but apparently these got dropped a while ago. Coupled with the fact that a lot of people have deleted their Google accounts, a lot of comments ended up as being posted by “Unknown” or “Anonymous”.

Incidentally, I thought I’d write this post in the Blogger web interface directly, to save time. While working on it, Blogger was nice enough to throw out all of my content and I had to start from scratch.

What does this mean for readers?

I have started to migrate the blog’s content to Jekyll, a static site generator. The blog’s appearance will change, but the URL will stay the same. I’ll try to keep any of the existing links working, but I might miss a few. If this is the case, please let me know so I can fix them. The current Blogger-based blog will still be available at https://verificationgentleman.blogspot.com for a while, though I do plan to eventually take it down.

The main thing that will change for readers is the handling of comments. I didn’t want to use a third party service, like Disqus, because these would require users to create new accounts with them in order to post. They also usually serve ads, sometimes very questionable ones I hear. I settled on Discourse, because it integrates very well with static sites. If you want to post comments, you’ll have to register at https://discourse.verificationgentleman.com/. The cool thing about Discourse is that it supports OAuth, so if you don’t want to sign up using an email and a password, you can use your Google, Facebook or GitHub account.

I’ve migrated all existing comments to Discourse. I’ve created dummy accounts for all comment authors. The user names for these account have a “_ifb” suffix (which stands for “imported from Blogger” - this had to be short, because Discourse only supports a maximum length of 20 characters). The names also contain “(Imported from Blogger)”. If you create an account and want your old comments assigned to you, you can drop me a private message and we can make it happen.

I still have to sort out the RSS feed, but this should be a minor issue. Email subscriptions have already stopped working, because FeedBurner killed support for them this summer. I’ll look into getting this working again, but it’s not that easy to find free services for this.

I also don’t have a replacement for the contact form at the moment. A private message on Discourse should be an acceptable alternative for the time being.

Closing

Static site generators are much easier to work with, requiring fewer manual steps. Hopefully I’ll have to spend less time managing the blog and more time writing content for it.

I thought long and hard about which one of the verification environments should come first. While it might have made more sense to start with simulation, as this is what is probably most familiar to many of you, excitement got the better of me and I decided to go with formal verification.

Description of the Design Under Test

Let’s have a look at the design we’ll be verifying. My goal was to keep the design as simple as possible, so that it doesn’t require a lot of effort to understand, but for it to have a few interesting quirks that make verifying it (especially using simulation) a bit more complicated.

Our design under test (DUT) will be a device that can process shapes by performing various operations on them. It can process circles, rectangles and triangles. As operations, it can compute the perimeter or the area of the shape. For rectangles, it can also figure out if a given one is a square. We can only perform this query on a rectangle, though, so it won’t be possible to ask, for example, whether a circle is a square. It can also figure out whether a triangle is equilateral or whether it is isosceles. As before, these queries can only be performed on triangles.

Our design will have a single special function register (SFR), called CTRL. The CTRL register will be used to configure the type of shape to process and the operation to perform on it. It will have the following layout:

The contents of the SHAPE field are one-hot encoded:

The coding of the OPERATION field is a bit more complicated:

The uppermost three bits define which shapes can be combined with the operation. Operations that contain 000 in these bits can be used with any shape. In all other cases, these bits will contain the code for the shape on which the operation can be performed.

Writing a reserved value for any of the fields will cause the write to be ignored, in which case the SFR will keep its value. Writing an illegal combination of SHAPE and OPERATION values will also cause the write to be ignored.

To make things more interesting, the DUT provides a way of changing the operation without changing the shape. This is done by writing the special value 111 to the SHAPE field, together with the new value of OPERATION. We’ll call this special value KEEP_SHAPE. Having this mechanism makes it easier for software to only update the OPERATION field, without having to do a read-modify-write of the CTRL register. The resulting value of the SFR after this write operation has to contain a legal combination, otherwise the write will be ignored. For example, it is allowed to write KEEP_SHAPE together with IS_ISOSCELES if CTRL.SHAPE is TRIANGLE, because it would result in (TRIANGLE, IS_ISOCELES), which is a legal combination. A write of KEEP_SHAPE together with IS_SQUARE would be ignored in the previous situation, as this would result in (TRIANGLE, IS_SQUARE), which is an illegal combination.

A similar mechanism exists for the OPERATION field, where the special value 111_1111, called KEEP_OPERATION, behaves like KEEP_SHAPE.

A real design would need some more SFRs to configure the shapes and to read out the results. For simplicity, we’ll skip those and focus our verification efforts on the CTRL register.

Our design will have a simple bus interface:

module shape_processor(
    input bit rst_n,
    input bit clk,

    input bit write,
    input bit [31:0] write_data,

    input bit read,
    output bit [31:0] read_data
    );

I didn’t include an address signal to keep things simple. All bus operations will always target the CTRL register.

You can find the full code here, including the verification environment, if you want to dig deeper into it or to experiment with it yourself.

Formal Verification

Before we start writing anything, let’s stop for a second and think about what we want to achieve. It’s true that we could write a few assertions about what the design is supposed whenever this or that is written. This would mean focusing on the implementation.

What is the most important thing that the design requirements try to ensure? All of them are there to make sure that the DUT is always in a legal configuration, where it can properly perform its function. Requirements like “writes with reserved values are ignored” or “writes with illegal combinations are ignored” merely serve to support this core requirement. The cool thing about formal verification is that we can focus on these core requirements.

To check these core requirements, we’ll use a gray-box verification approach. We’ll look directly at the internal DUT SFR. This way we can start writing properties without having to write any kind of infrastructure for the bus interface.

Of course, we could create a separate model of the DUT SFRs and write our properties using that. We could update it based on the bus operations that execute on the interface, similarly to how we would do it in a UVM-based testbench. This would not only require extra effort to implement the model and the monitoring, but it would increase the state space, making it more difficult for the tool to achieve proofs.

I was previously against any kind of white-box at block level, but I have since softened my stance, including when doing simulation. I now find it to be an acceptable trade-off, as long as it is done responsibly and in moderation. It should also only be done on parts of the design that are architecturally “visible” and that are relatively stable.

When accessing the values of the DUT’s internal CTRL register, we should try to protect ourselves from any implementation specific aspects that might change unexpectedly and cause a lot of rework on our side. For example, the designer might choose to define a single 32 bit vector, where the bit positions for the fields might match those in the specification. They might decide to have two separate signals, one for each field. There are many possibilities to choose from.

We can define our “references” to the internal signals using the following let statements:

let shape_in_sfr = shape_processor.ctrl_sfr.shape;
let operation_in_sfr = shape_processor.ctrl_sfr.operation;

Our design currently uses a struct for the CTRL register, but if this were to ever change, we would only need to update these let statements.

To make our code more readable, we should model the encodings for the SFR fields using enums:

typedef enum bit [2:0] {
  CIRCLE = 'b001,
  RECTANGLE = 'b010,
  TRIANGLE = 'b100,
  KEEP_SHAPE = '1
} shape_e;

typedef enum bit [6:0] {
  PERIMETER = 'b000_0000,
  AREA = 'b000_0001,
  IS_SQUARE = 'b010_0000,
  IS_EQUILATERAL = 'b100_0000,
  IS_ISOSCELES = 'b100_0001,
  KEEP_OPERATION = '1
} operation_e;

With the infrastructure laid out, it’s time to get to work! The most basic check we can do is to ensure that the values of the CTRL SFR fields will never have any of the reserved values. For the SHAPE field we would have the following assertion:

no_reserved_shapes_in_sfr: assert property (
    !is_reserved_shape(shape_in_sfr));

The is_reserved_shape(...) function will return 1 when it is supplied a value that doesn’t match any of the values defined in the shape_e type:

function bit is_reserved_shape(bit [2:0] val);
  return !(val inside { KEEP_SHAPE, CIRCLE, RECTANGLE, TRIANGLE });
endfunction

(Ideally, we would have used a $cast(...) to check whether the bit vector argument can be converted to the desired enum type, but I couldn’t get this to work.)

If the DUT would not properly validate the value of the SHAPE field before writing it, then the assertion from above would catch it.

We would also need a similar assertion for the OPERATION field:

no_reserved_operations_in_sfr: assert property (
    !is_reserved_operation(operation_in_sfr));

While KEEP_SHAPE and KEEP_OPERATION are defined write values for the CTRL fields, it is not possible for the SFR to contain any of these values. We can check that the DUT doesn’t latch KEEP_SHAPE by mistake using the following assertion:

no_keep_shape_in_sfr: assert property (
    shape_in_sfr != KEEP_SHAPE);

Also, for KEEP_OPERATION we would have:

no_keep_operation_in_sfr: assert property (
    operation_in_sfr != KEEP_OPERATION);

We also want to ensure that we only ever see legal combinations in the CTRL SFR. For this, we need an extra assertion:

only_legal_combinations_in_sfr: assert property (
    is_legal_combination(shape_in_sfr, operation_in_sfr));

The is_legal_combination(...) function models the rules that govern which SHAPES can be combined with which OPERATIONS:

function bit is_legal_combination(shape_e shape, operation_e operation);
  if (operation inside { PERIMETER, AREA })
    return 1;
  if (operation == IS_SQUARE)
    return shape == RECTANGLE;
  if (operation inside { IS_EQUILATERAL, IS_ISOSCELES })
    return shape == TRIANGLE;
  return 0;
endfunction

Ideally such modeling code should not be a one-to-one copy of the RTL code. Where the RTL compares bits, the modeling code uses enum values, which also makes it very readable.

It’s not the task of the is_legal_combination(...) function to model the behavior of KEEP_SHAPE or of KEEP_OPERATION. It should never be called with any of these values. The fact that it returns 0 if any of these values is passed as an argument is an implementation artifact. Normally, in simulation, I would trigger a fatal error in such cases, to make it clear to the caller that it’s doing something wrong. Sadly, I couldn’t get the tool to do this.

The assertions we wrote up to now will prove that our DUT can never be put in a faulty configuration. Unfortunately, they will also hold for a DUT that completely ignores writes (assuming, of course, that it comes out of reset with a legal combination of fields). This is because we haven’t made it a requirement for the DUT to update its fields based on the write data presented to it. We only said that should it update its fields, the resulting values must satisfy the assertions we wrote.

A very cheap way of making sure that the DUT updates its fields is to write a cover property that proves that each (proper) value of the SHAPE and OPERATION fields can be stored in the SFR. We’ll use the term “proper” to refer to all modes other than the two KEEP_* modes.

We can check that a CIRCLE can be seen in the SHAPE field using the following cover:

circle_in_sfr: cover property (
    shape_in_sfr == CIRCLE);

This won’t bring us much if CIRCLE is the reset value of the field. Simply coming out reset will be enough to show us a trace. We should also check that we can see a RECTANGLE or a TRIANGLE:

rectangle_in_sfr: cover property (
    shape_in_sfr == RECTANGLE);

triangle_in_sfr: cover property (
    shape_in_sfr == TRIANGLE);

The DUT will have to be able to update the field, otherwise we won’t get traces for all of the properties.

We’re assuming that the CTRL register can be reset, otherwise the tool could just show us the DUT starting up with any SHAPE value. In this case the covers would be trivially reachable. The starting value could also be a reserved value, though, which would be caught by our assertions. Indirectly, we are ensuring that the SFR is reset. Moreover, if the SFR would not have a reset signal, then the tool would generally warn us about this.

We should give the OPERATION field the same treatment to make sure that all its proper values are reachable. Writing a cover for each possible operation, like we did for shapes, could get pretty tedious, though. To save typing we could use a generate statement and have the tool do the looping for us:

for (genvar operation = 0; operation < 2**$bits(operation_e); operation++) begin
  if (operation inside { PERIMETER, AREA, IS_SQUARE, IS_EQUILATERAL, IS_ISOSCELES }) begin
    operation_in_sfr_seen: cover property (
        operation_in_sfr == operation);
  end
end

The code suffers from some SystemVerilog limitations. Genvars are integers, so the names of the generated blocks won’t be very suggestive because they’ll contain the numeric values of the enum literals, not the literals themselves. It’s also not possible to loop over enums directly, which makes the code longer and invites duplication. (The SystemVerilog syntax for looping over enums is not that great anyway, but at least it can handle changes in the enum type.)

The assertions that we wrote up to now for the internal SFR values, together with the covers, give us a very solid base. They provide enough guidance to implement the design properly and to avoid many non-trivial bugs. If we had high confidence in our designer and a good testing setup at the integration level we could probably stop here. If we were to go for the gold and verify the design completely we would still need a few more properties.

Since we’re doing gray-box verification, we should also check that the SFR contents are delivered on the read data bus when a bus read is performed.

When working with the bus data, it would be really annoying to have to fiddle with bit positions to figure out what shape or operation we are getting as a result of the read. To help us extract the fields, we can define a struct with the same layout as the CTRL register:

typedef struct packed {
  bit [12:0] reserved1;
  bit [2:0] SHAPE;
  bit [8:0] reserved0;
  bit [6:0] OPERATION;
} ctrl_sfr_reg;

We can convert the read data to this type, for easy access to the fields using the . operator:

ctrl_sfr_reg read_data_as_ctrl_sfr;
assign read_data_as_ctrl_sfr = read_data;

To make the code that uses them shorter, we can define some let statements for the read values of the fields, like we did for the internal SFR:

let shape_on_read_bus = read_data_as_ctrl_sfr.SHAPE;
let operation_on_read_bus = read_data_as_ctrl_sfr.OPERATION;

Now we can write an assertion for each of the fields:

shape_delivered_as_read_data: assert property (
    read |-> shape_on_read_bus == shape_in_sfr);

operation_delivered_as_read_data: assert property (
    read |-> operation_on_read_bus == operation_in_sfr);

We haven’t said anything about the behavior of the KEEP_SHAPE mode. For this, we’ll have to look at the data being written on the bus.

Before we look at the write data, though, we can write another assertion. We can check that the SFR is only ever updated as a result of a bus write:

sfr_constant_if_no_write: assert property (
    !write |=> $stable(shape_processor.ctrl_sfr));

If the DUT were to change the value of the SFR when, for example, no access is taking place, this assertion would fail. This is a very powerful check, which is also very simple to write. It’s pretty typical to find bugs where the RTL code doesn’t properly sample the bus control signals.

We can do the same trick for the write data that we did with the read data, in order to get the values of the fields:

ctrl_sfr_reg write_data_as_ctrl_sfr;
assign write_data_as_ctrl_sfr = write_data;

let shape_on_write_bus = write_data_as_ctrl_sfr.SHAPE;
let operation_on_write_bus = write_data_as_ctrl_sfr.OPERATION;

Now we can check that when we try to write KEEP_SHAPE, the value of the DUT’s SFR doesn’t change:

shape_constant_if_keep_shape_write: assert property (
    write && shape_on_write_bus == KEEP_SHAPE |=>
        $stable(shape_in_sfr));

We can do the same for KEEP_OPERATION:

operation_constant_if_keep_operation_write: assert property (
    write && operation_on_write_bus == KEEP_OPERATION  |=>
        $stable(operation_in_sfr));

The previous assertions don’t say anything about what should happen with the other field whenever a KEEP_* is written. For example, a DUT that completely ignores a write that contains KEEP_SHAPE and keeps the value of OPERATION as well will also satisfy the assertions. We can write a cover property to see that the DUT can update the value of OPERATION in such cases:

operation_updated_when_keep_shape: cover property (
    write && shape_on_write_bus == KEEP_SHAPE ##1 $changed(operation_in_sfr));

This cover will fail if the DUT completely ignores writes with KEEP_SHAPE.

Naturally, we can write a similar cover property for KEEP_OPERATION:

shape_updated_when_keep_operation: cover property (
    write && operation_on_write_bus == KEEP_OPERATION ##1 $changed(shape_in_sfr));

The properties we have don’t fully specify what should happen whenever we try to write a reserved value to one of the fields. A DUT that treats a write with a reserved SHAPE value the same way it treats a KEEP_SHAPE will also pass all checks. To solve this, we can add the following assertions:

sfr_constant_if_reserved_shape_write: assert property (
    write && is_reserved_shape(shape_on_write_bus) |=>
        $stable(shape_processor.ctrl_sfr));

sfr_constant_if_reserved_operation_write: assert property (
    write && is_reserved_operation(operation_on_write_bus) |=>
        $stable(shape_processor.ctrl_sfr));

With these assertions, we make sure that writes that contain reserved values are completely ignored.

It’s becoming more and more difficult to find a DUT that fulfills these properties, but doesn’t fulfill the specification. The kinds of faulty implementations that these properties won’t catch are starting to look like intentional mistakes. We’ve reached another point where we could probably just stop, but still be able to get a good night’s sleep, knowing that the design is in very good shape. We could also write a few more properties and leave no stone unturned where bugs could hide.

Let’s recall that whenever an illegal combination of SHAPE and OPERATION values is written, the DUT is supposed to ignore it. If, however, the DUT were to write some default combination into the SFR in such a case, for example the reset value of (CIRCLE, PERIMETER), then none of the properties we have would fail. This doesn’t sound like the kind of mistake a designer would make when building the design from scratch. It might be an issue if a previous version of the specification used to require this behavior, in which case it would be possible to overlook the new requirement.

Writing a single assertion for this might get a bit more complicated because of the KEEP_* values, but we can split the problem into multiple cases.

First, we should check that illegal combinations of proper modes are ignored:

sfr_constant_if_illegal_combination_write_of_proper_modes: assert property (
    write && shape_on_write_bus != KEEP_SHAPE && operation_on_write_bus != KEEP_OPERATION
        && !is_legal_combination(shape_on_write_bus, operation_on_write_bus) |=>
            $stable(shape_processor.ctrl_sfr));

The fact that we already have the is_legal_combination(...) function which can operate on proper modes will nudge us into thinking about this behavior as an own case.

The next case we have is when we are writing KEEP_SHAPE, but the resulting combination would be illegal. This can also be implemented using the is_legal_combination(...) function, but instead of taking the bus value for the shape, we take the value in the SFR:

sfr_constant_if_illegal_combination_write_of_keep_shape: assert property (
    write && shape_on_write_bus == KEEP_SHAPE
        && !is_legal_combination(shape_in_sfr, operation_on_write_bus) |=>
            $stable(shape_processor.ctrl_sfr));

Of course, we have to do the same for KEEP_OPERATION:

sfr_constant_if_illegal_combination_write_of_keep_operation: assert property (
    write && operation_on_write_bus == KEEP_OPERATION
        && !is_legal_combination(shape_on_write_bus, operation_in_sfr) |=>
            $stable(shape_processor.ctrl_sfr));

Now we can prove that the DUT always ignores illegal writes, regardless of the reason (either reserved value or illegal combination), as we have properties for each of the cases.

I’m having a really difficult time coming up with a faulty implementation that still passes the current set of properties. The best I can come up with at this point is a design that somehow writes a “twisted” version of the data given to it: instead of writing CIRCLE, it writes RECTANGLE and vice-versa, but only when also trying to write PERIMETER (otherwise we might get illegal combination in the SFR).

For this design maybe it isn’t that important to check that writes properly update the SFR fields, as there isn’t much that much room for error. For a design where one of the shapes can be disabled via a separate SFR bit I could see it becoming very important. Let’s imagine, for example, that the CIRCLE shape could be disabled depending on whether the pi computation unit is powered off. If this design also has a bug where it disables the TRIANGLE shape as well, we would not be able to find this if we only cover that the SHAPE field can be TRIANGLE. This is because the tool could always show us such traces when the pi computation unit is turned on.

To weed out any remaining pathological design behaviors we can write one more pair of assertions: that legal writes, that are supposed to update the SFR, do so properly for each of the fields. Here’s what the assertion would look like for SHAPE:

legal_write_data_written_to_shape: assert property (
    write && is_legal_ctrl_write_data() |=>
        shape_in_sfr == $past(shape_on_write_bus));

While we were able to write multiple assertions when dealing with the cases where the write had to be ignored, in this case we have to write one assertion. We have to model what it means for the write data to be legal and this means describing all the properties required of it. None of the fields are allowed to contain reserved values and the combination of fields is supposed to be legal:

function bit is_legal_ctrl_write_data();
  return !is_reserved_shape(shape_on_write_bus)
      && !is_reserved_operation(operation_on_write_bus)
      && is_legal_ctrl_write_data_combination();
endfunction

The combination being legal is defined differently, depending on whether we are dealing with a KEEP_* or with a proper mode:

function bit is_legal_ctrl_write_data_combination();
  if (shape_on_write_bus == KEEP_SHAPE)
    return is_legal_combination(shape_in_sfr, operation_on_write_bus);
  if (operation_on_write_bus == KEEP_OPERATION)
    return is_legal_combination(shape_on_write_bus, operation_in_sfr);
  return is_legal_combination(shape_on_write_bus, operation_on_write_bus);
endfunction

If we try to prove this assertion, we’ll notice that it fails. It will complain that it can’t write KEEP_SHAPE into the SFR. This is because KEEP_SHAPE is not a value that leads to an update of the SHAPE field. We have to exclude this case and then the assertion will pass:

legal_write_data_written_to_shape: assert property (
    write && is_legal_ctrl_write_data() && shape_on_write_bus != KEEP_SHAPE |=>
        shape_in_sfr == $past(shape_on_write_bus));

Now imagine that the design would have contained the same bug. We could have let something slip through, since this assertion would have passed. Fortunately, even if this were the case, we still have the assertions on the internal SFR, which disallow KEEP_SHAPE as a value. This is the power of thinking about the core requirements of the design!

It’s not that we wouldn’t be able to do something similar in simulation. We could very well write checks on the internal SFR, alongside our register modeling which describes which writes are legal and which are not. It’s just that we probably wouldn’t, because our thinking is very focused on describing cause/effect relationships. We would probably stop after finishing with our register modeling and move on to the next thing.

For completeness, we also need a property for the OPERATION field:

legal_write_data_written_to_operation: assert property (
    write && is_legal_ctrl_write_data() && operation_on_write_bus != KEEP_OPERATION |=>
        operation_in_sfr == $past(operation_on_write_bus));

Before we end, I would like to revisit illegal writes that are supposed to be ignored. Now that we have a is_legal_ctrl_write_data() function, we could use it to write a single assertion to handle all cases of illegal writes, which are supposed to be ignored:

sfr_constant_if_illegal_write: assert property (
    write && !is_legal_ctrl_write_data() |=>
        $stable(shape_processor.ctrl_sfr));

This could replace the other assertions that we have that handle each illegal case separately.

Depending on the situation, it might be more advantageous to have either a single assertion for a requirement or to split it into multiple assertions. Multiple assertions are easier to debug and might be easier for the tool to prove (at least for big designs), because we are asking it to give us answers to slightly easier questions. Writing a single assertion has the advantage that it requires less code. It’s easier to handle changes to the requirements when there are less places to update.

For this design I would go with the single property.

Conclusions

We’ve seen how formal verification nudges us to think about requirements, not about how to implement a testbench that is a faithful representation of the design.

We made our properties very readable and modular, which allowed us to tackle the verification task in incremental chunks. We should strive to avoid replicating the design and to make the properties read like sentences in the specification. In the end, our property checking environment doesn’t have many more lines of code than the design itself.

We also saw that formal verification doesn’t have to be an “all or nothing” proposition. Depending on our level of risk aversion we could decide to live with only a sub-set of checks, but still get high design quality. We can focus on the things that are truly important or difficult and not spend too much effort on the parts that are unlikely to have bugs.

Stay tuned for part 2, where we’ll build a UVM testbench for the same design.

A good constrained random test suite contains a mixture of tests with varying degrees of randomness. This is achieved by progressively adding constraints to tests to reduce their randomness. This is best explained with an example.

Let’s assume we’re verifying a device that can handle read and write accesses to locations in its address map. These accesses can either be done in secure mode or in non-secure mode. We model an access using a UVM sequence item:

class sequence_item extends uvm_sequence_item;

  typedef enum {
    READ,
    WRITE
  } direction_e;

  typedef enum {
    SECURE,
    NONSECURE
  } sec_mode_e;

  rand direction_e direction;
  rand bit [31:0] address;
  rand sec_mode_e sec_mode;

  // ...
endclass

Not all accesses are legal and illegal accesses would be rejected by the device.

Only certain address ranges are mapped, while accesses to unmapped addresses are illegal. If we were to write a test that only accesses mapped addresses, we would have to add the following constraints to generated items:

constraint only_mapped_addresses {
  address inside {
      [CODE_START_ADDR:CODE_END_ADDR],
      [SRAM_START_ADDR:SRAM_END_ADDR],
      [PERIPHERAL_START_ADDR:PERIPHERAL_END_ADDR] };
}

Our device also only allows writes to aligned addresses. For a 32-bit bus, this would mean that the lowest two address bits have to be 0:

constraint only_writes_to_aligned_addresses {
  direction == WRITE;
  address[1:0] == 0;
}

Lastly, certain ranges of our device’s address map are restricted to secure code. Let’s assume that the address map is split into 16 regions of 256 MB each. Within each of these regions, the lower half is reserved for secure accesses. This means that bit 27 of the address is always 0 for a secure access:

constraint only_secure_accesses_to_lower_half_of_range {
  sec_mode == SECURE;
  address[27] == 0;
}

The test suite for this device would contain a random test where unconstrained items are generated. One test would be directed toward generating accesses to mapped addresses, another test would only perform writes to aligned addresses, while another test would perform only secure accesses. At the same time, we would also need tests that lie at the intersection of the three features, so we would want tests that do pairwise combinations: aligned writes to mapped addresses, aligned writes in secure mode and secure access to mapped addresses. Finally, we also need a test that combines all three and only does secure writes to mapped addresses.

(While a real test suite would definitely need a lot more classes of tests, this post isn’t focused on verification planning, but on the mechanical aspects of implementing a robust constraint management strategy, so please ignore the simplicity of the example.)

It might be the case that these behaviors will get tweaked over time as the project moves forward or as a new derivative of the device is developed. The address map might change as regions are moved, removed or resized, or new regions are added. The bus width might change, which would change which addresses are aligned, or we could get a feature request to implement writes of other granularities (e.g. half-word). The definition of secure regions could also change or they could become configurable via special function registers. Any of these changes should be easy to handle and shouldn’t require massive changes to the verification code.

Let’s skip the obvious idea of putting all constraints into the sequence item class and activating/deactivating them selectively based on the test. This won’t scale for real projects, where we would have many more constraints, which would make the code unreadable.

Using mixins

Quite a while back I wrote about how to use mixins to manage constraints.

The mixin approach is flexible, because it allows us to handle each aspect individually. Instead of having all constraints in a single class, we can have one mixin for each constrained feature.

We need one for mapped addresses:

class only_mapped_addresses_mixin #(type T = sequence_item) extends T;

  constraint only_mapped_addresses {
    address inside {
        [CODE_START_ADDR:CODE_END_ADDR],
        [SRAM_START_ADDR:SRAM_END_ADDR],
        [PERIPHERAL_START_ADDR:PERIPHERAL_END_ADDR] };
  }

  // ...
endclass

We also need one for writes:

class only_legal_writes_mixin #(type T = sequence_item) extends T;

  constraint only_writes_to_aligned_addresses {
    direction == WRITE;
    address[1:0] == 0;
  }

  // ...
endclass

Finally, we need a mixin for secure accesses:

class only_legal_secure_accesses_mixin #(type T = sequence_item) extends T;

  constraint only_secure_accesses_to_lower_half_of_range {
    sec_mode == SECURE;
    address[27] == 0;
  }

  // ...
endclass

Assuming that we have a random test that starts regular sequence items, we would use these mixins to write our more directed tests by replacing the original sequence item type with one with constraints mixed in.

The test that only accesses mapped addresses would do the following factory override:

class test_mapped_addresses extends test_all_random;

  protected virtual function void set_factory_overrides();
    sequence_item::type_id::set_type_override(
        only_mapped_addresses_mixin #(sequence_item)::get_type());
  endfunction

  // ...
endclass

The other two feature tests would look similar, but would use their respective mixins.

To only perform writes to mapped addresses we would need to chain the two mixins:

class test_legal_writes_to_mapped_addresses extends test_all_random;

  protected virtual function void set_factory_overrides();
    sequence_item::type_id::set_type_override(
        only_legal_writes_mixin #(only_mapped_addresses_mixin #(sequence_item))::get_type());
  endfunction

  // ...
endclass

Of course, we would do the same to handle the other two pairs.

Similarly, we could use the same principle to combine all three features:

class test_legal_writes_to_mapped_addresses_in_secure_mode extends test_all_random;

  protected virtual function void set_factory_overrides();
    sequence_item::type_id::set_type_override(
        only_legal_writes_mixin #(
            only_mapped_addresses_mixin #(
                only_legal_secure_accesses_mixin #(sequence_item)))::get_type());
  endfunction

  // ...
endclass

The mixin approach comes with some issues, though.

Constraints are always polymorphic, so we have to be very careful to use unique constraint names across all mixins. Applying two different mixins that use the same constraint name would result in only the outer mixin’s constraints being applied, because it would override the constraint defined in the inner mixin. It’s very easy to run into this issue when using copy/paste to define a new mixin and forgetting to change the name of the constraint. Frustration will follow, as the code looks right, but leads to unexpected results. Moreover, the more mixins are used in the code base, the easier it is for constraint name collisions to happen.

Chaining of mixins is not particularly readable. It is bearable for one or two levels, but the more levels there are, the worse it’s going to get.

Finally, using mixins will cause the number of types in our code to explode. Each mixin on top of a class will create a new type. From a coding standpoint this isn’t such a big deal, as we won’t be referencing those types directly. The more types we have, though, the longer our compile times are going to get. Also, note that for the compiler mixin1 #(mixin2 #(some_class)) is a distinct type from mixin2 #(mixin1 #(some_class)), regardless if it results in the “same” class. It’s very easy to use mixin1 #(mixin2 #(some_class)) in one test, but use mixin3 #(mixin2 #(mixin1 #(some_class))) in another, which would make the compiler “see” an extra type.

The mixin pattern uses inheritance, which doesn’t match the call to action in the post title, so obviously we’re not going to stop here.

Using aspect oriented programming

It’s much easier to write our test family using aspect oriented programming (AOP). AOP allows us to alter the definition of a class from a different file. Even though SystemSystemverilog doesn’t support AOP, I’d still like to show an example in e, as it can provide us with some hints into how we could improve the mixin-base solution.

(Please note that the following code may not be idiomatic, so don’t take it as a reference on how to handle constraints in e.)

Our sequence item definition would look similar:

<'
struct sequence_item like any_sequence_item {

  direction: direction_e;
  address: uint(bits: 32);
  sec_mode: sec_mode_e;

};
'>

In our test that only does mapped accesses, we would tell the compiler to add the constraint to the sequence item:

<'
import test_all_random;

extend sequence_item {
  keep address in [CODE_START_ADDR..CODE_END_ADDR] or
      address in [SRAM_START_ADDR..SRAM_END_ADDR] or
      address in [PERIPHERAL_START_ADDR..PERIPHERAL_END_ADDR];
};
'>

This does not result in a new type. It tweaks the existing sequence_item type for the duration of that test.

If we would like to reuse the constraint in the test that only writes to mapped addresses, we could put the extension into its own file. We could do the same for the other extensions that handle the other features. This would allow each test to load the relevant extension files. For example, for legal writes to mapped addresses we would have:

<'
import test_all_random;
import constraints/only_legal_writes;
import constraints/only_mapped_addresses;
'>

The file structure is similar to what we had when we used mixins, but the code is much cleaner.

Pay special attention to the natural language description of what we are doing: in test_mapped_addresses we are adding the constraint to the sequence_item type.

Using constraint objects

Regular object oriented programming doesn’t allow us to change type definitions. What we can do, however, is build our code in such a way as to allow it to be extended when it is being used.

Back in 2015, there was an exciting DVCon paper that presented how to add constraints using composition. It showed how to add additional constraints to an instance of an object without changing the type of that object. This is done by encapsulating the constraints into their own objects which extend the behavior of the original object’s randomize() function. Have a quick look at the paper before proceeding, to understand the exact way this is done.

While the paper shows how to add constraints to object instances, we can extend the approach to add constraints globally, to all instances of a type. If we look back at the AOP case from before, this would be conceptually similar to what we were doing there. We would be emulating the addition of constraints to the sequence_item type.

The paper makes an attempt at global constraints in its final section, by using the UVM configuration DB. While that approach works, I feel that it is not expressive enough. A better API, consisting of a static function to add constraints globally, would make the code much more readable than a very verbose config DB set(...) call.

To get the extensibility we want, we have to set up the necessary infrastructure for it. If the sequence item class is under our control, we can modify it directly. Alternatively, if the sequence item is part of an external UVC package, we can define a sub-class which contains the necessary code.

We’ll assume that sequence_item can’t be changed and we’ll create a new constrained_sequence_item class. We would either use this sub-class in our sequences directly or use a factory override.

To execute code that affects all instances, the sequence item class needs a static function through which constraints are added:

class constrained_sequence_item extends sequence_item;

  static function void add_global_constraint(abstract_constraint c);
    // ...
  endfunction

  // ...
endclass

The abstract_constraint class would be the base class for our constraints and would provide us with a reference to the object that is being randomized:

virtual class abstract_constraint;

  protected sequence_item object;

  function void set_object(sequence_item object);
    this.object = object;
  endfunction

endclass

The code to handle global constraints is similar to the one presented in the paper. We store all global constraints in a static array:

class constrained_sequence_item extends sequence_item;

  local static rand abstract_constraint global_constraints[$];

  static function void add_global_constraint(abstract_constraint c);
     global_constraints.push_back(c);
  endfunction

  // ...
endclass

Before randomizing a sequence item instance, we have to set up the constraint objects to point to it:

class constrained_sequence_item extends sequence_item;

  function void pre_randomize();
    foreach (global_constraints[i])
      global_constraints[i].set_object(this);
  endfunction

  // ...
endclass

With the infrastructure set up, we can move on. We encapsulate the constraints for our features into their own constraint classes:

class only_mapped_addresses_constraint extends abstract_constraint #(sequence_item);

  constraint c {
    object.address inside {
        [CODE_START_ADDR:CODE_END_ADDR],
        [SRAM_START_ADDR:SRAM_END_ADDR],
        [PERIPHERAL_START_ADDR:PERIPHERAL_END_ADDR] };
  }

endclass

class only_legal_writes_constraint extends abstract_constraint #(sequence_item);

  constraint c {
    object.direction == sequence_item::WRITE;
    object.address[1:0] == 0;
  }

endclass

class only_legal_secure_accesses_constraint extends abstract_constraint #(sequence_item);

  constraint c {
    object.sec_mode == sequence_item::SECURE;
    object.address[27] == 0;
  }

endclass

In the test that only accesses mapped addresses we would make sure to add the required constraints:

class test_mapped_addresses extends test_all_random;

  protected virtual function void add_constraints();
    only_mapped_addresses_constraint c = new();
    constrained_sequence_item::add_global_constraint(c);
  endfunction

  // ...
endclass

The add_constraints() function should be called before any sequence items are started. A good place to call it from is the end_of_elaboration_phase(…) function.

In the other feature oriented tests we would simply add their respective constraints.

For the test that does writes to mapped addresses we just need to make sure that both constraints are added. We could do this by extending the random test and making two add_global_constraint(…) calls, one for each constraint object:

class test_legal_writes_to_mapped_addresses extends test_random;

  protected virtual function void add_constraints();
    only_legal_writes_constraint c0 = new();
    only_mapped_addresses_constraint c1 = new();
    constrained_sequence_item::add_global_constraint(c0);
    constrained_sequence_item::add_global_constraint(c1);
  endfunction

  // ...
endclass

We could also extend the test that only does legal writes and add the constraints for mapped addresses:

class test_legal_writes_to_mapped_addresses extends test_legal_writes;

  protected virtual function void add_constraints();
    only_mapped_addresses_constraint c = new();
    super.add_constraints();
    constrained_sequence_item::add_global_constraint(c);
  endfunction

  // ...
endclass

Of course, this approach can be used to handle all combinations of constraints.

Adding constraints dynamically has the same advantages as the mixin approach we looked at earlier.

It doesn’t suffer from the same readability issue, because we don’t rely on long parameterization chains. It suffers from a bit too much verboseness due to the multiple add_global_constraint(…) calls, though this could be improved by adding a variant of the function that accepts a list of constraint objects.

This approach also avoids the type explosion issue that mixins have and is potentially faster to compile.

There is a bit of boilerplate code required for the infrastructure. This can be extracted into a reusable library.

The first thing we need to do is to make the abstract constraint class parameterizable:

virtual class abstract_constraint #(type T = int);

  protected T object;

  function void set_object(T object);
    this.object = object;
  endfunction

endclass

The package should expose a macro to handle the constraint infrastructure:

`define constraints_utils(TYPE) \
  static function void add_global_constraint(constraints::abstract_constraint #(TYPE) c); \
  // ...

There was a subtle issue with the simplistic infrastructure code we looked at before. It wasn’t able to handle randomization of multiple instances at the same time (for example, when randomizing an array of sequence items). As this is a more exotic use case, the problem won’t show up immediately. It’s a simple fix to make, but it would be very annoying to have to make it in mutiple projects. Even when the code might look deceptively simple and have us think it’s not worth the hassle to put into an own library, doing so makes it easier to implement and propagate fixes for such issues.

The macro makes the definition of constrained_sequence_item much cleaner:

class constrained_sequence_item extends sequence_item;

  `constraints_utils(sequence_item)

  // ...
endclass

You can find the constraints library on GitHub.

It already supports instance and global constraints. What I would like to add is the possibility to add constraints to all items under a UVM scope, similar to what the paper presents at the end, but using a nicer API that doesn’t require the user to do any UVM config DB calls.

I also want to look at the possibility of magically generating all test combinations, given a list of constraint objects. Currently we had to enumerate all combinations of constraints by writing a test class for each, which is very repetitive. It would be great if we could get this automatically and save ourselves the typing. This is something I’ll definitely look at in a future post.

In the meantime you can have a look at the full example code on GitHub and try it out yourselves. I hope it inspires you to write flexible test suites that help you reach you verification goals faster.

There’s one thing, though, that crept up on me: compile times get much bigger. While this doesn’t sound like a big deal, I’ve found that long build times are an absolute drain on productivity. I use SVUnit a lot, so I’m used to having a very short path between making a change and seeing the effects of that change. Ideally, there should be no delay between starting the test script and getting the result. A delay of a couple of seconds is tolerable. More than 10 seconds becomes noticeable. After exceeding the one minute mark, the temptation to switch to something else (like the Internet browser) becomes very high. This slowdown happens gradually, with each new class that is added, decreasing development speed.

In this post I’d like to talk about compilation. This topic has a tendency to be trivialized and underestimated, even more so in the hardware industry, where it’s common to have design flows already set up to deal with this process.

Full vs. incremental builds

A build is the process of taking the source code and producing an executable object. When talking about builds, there are two terms we need to be familiar with: full builds and incremental builds. A full build is performed when there isn’t any build output, which requires the entire source code to be built. This is either the case when starting in a new workspace (for example, after cloning the source repository) or after deleting the previous build output. An incremental build only builds the parts of the source code that have changed since the previous build. Because only parts of the project are rebuilt in this case, this means that, generally, the process is faster.

We’ll limit our discussion about builds to SystemVerilog packages, though the same concepts also apply to modules and interfaces.

Let’s say we have two packages, package0 and package1, which we use in our verification environment:

// File: package0.sv

package package0;

  class some_base_class;
  endclass

endpackage

// File: package1.sv

package package1;

  import package0::*;

  class some_derived_class extends some_base_class;
  endclass

endpackage

Compiling these two packages using an EDA tool is pretty straightforward:

compiler package0.sv package1.sv

The very first time we run this command, the tool will parse the two source files and generate the data structures it uses to represent the compiler output. Since we didn’t have any build output when we ran the command, we were performing a full build.

If we add a new class to package1 and run the compiler again, we will be performing an incremental build:

package package1;

  import package0::*;

  class some_derived_class extends some_base_class;
  endclass

  class some_other_class;
  endclass

endpackage

The tool will only recompile package1. It won’t touch package0, since it didn’t change. If compilation for package0 takes a lot of time, this will saves us that time.

A deeper dive into SystemVerilog compilation

Before we continue with our main discussion, it makes sense to look a bit deeper into how SystemVerilog compilation works. Before I investigated this topic I had some misplaced ideas, which I would like to dispel.

I have only ever really looked at the behavior of one particular EDA tool, but I assume that other simulators behave similarly, as they all have a common heritage. Some SystemVerilog tools differentiate between compilation and elaboration. These defintions depend on the tool you’re using. I’ve seen compilation used to mean parsing the code and generating syntax trees. Elaboration takes these syntax trees and generates executable code that is run in the simulator. I’ll use the term compile to mean both of these steps.

Let’s start small, with a single package that contains only one class:

package package0;

  class some_base_class;
  endclass

endpackage

After we compile the package, we will have performed a full build. Now, let’s add another class to the package:

package package0;

  class some_base_class;
  endclass

  class some_base_class2;
  endclass

endpackage

In this case, you’ll notice that the tool compiles both classes. I’m a bit cautious about posting the log files and how I can tell that it’s compiling both classes. Some tools make this easier to see than others. One clear sign is that compile takes longer. You can try it out by adding more and more classes and recompiling. I’ve created some scripts that can help out with such experiments: https://github.com/verification-gentleman-blog/smaller-packages/.

In this case, an incremental compile takes about as much time as a full build, which suggests that nothing is being reused from previous build attempts. Even if we only add classes, the build output for previously built classes is discarded.

What did we learn from this? That tools only organize build output using packages as their most granular unit. Changes within packages are “lost”, from an incremental build point of view.

You could argue that from the previous experiment we could infer that tools organize build output based on files. If we were to put each file in its own class and include them in the package, then the tool would be able to somehow behave differently. This isn’t, the case, though. `include directives are handled by the pre-processor. It interleaves all of the files together and gives the compiler a big file with all the class definitions inline (the situation we had previously).

We can do another experiment to convince ourselves that builds aren’t organized by files. Let’s put two packages inside the same file:

package package0;
endpackage

package package1;
endpackage

Let’s modify package1 by adding a new variable:

package package0;
endpackage

package package1;
  bit some_var;
endpackage

When rebuilding, we’ll notice that only package1 gets rebuilt, but package0 is left alone. (This is also the behavior we would have liked to have for classes inside a package.)

Now let’s also modify package0 by adding a variable to it:

package package0;
  bit some_var;
endpackage

package package1;
  bit some_var;
endpackage

When rebuilding, we’ll see that package0 is being rebuilt, as we expected, but, surprisingly, so is package1. This is very confusing initially, but obvious once you know the explanation. Because we shifted the lines where package1 and its items are defined in the file, the tool has to update debug information regarding line numbers. This is important for debuggers and for messages that contain line numbers (like assertion erros, $info(…) calls, etc.). This, by the way, is a very good reason to only define one element (package, interface, module) per file.

Let’s look at one more thing. Let’s take two packages that have a dependency relationship:

package package0;

  class some_base_class;
  endclass

endpackage

package package1;

  import package0::*;

  class some_derived_class extends some_base_class;
  endclass

endpackage

It’s clear that changes to package1 shouldn’t (and indeed won’t) cause rebuilds of package0. It’s also clear that changing some_base_class will have to trigger a rebuild of package1. Now, let’s add a new class to package0:

package package0;

  class some_base_class;
  endclass

  class some_base_class2;
  endclass

endpackage

At this point, we shouldn’t be surprised anymore that both packages are rebuilt in this case. This is because the tool only understands changes at the package level. package1 depends on package0, so any change to package0 will lead to a rebuild of package1, regardless if this is really needed. Unfortunately, this isn’t the behavior we would like to have.

Contrast the way SystemVerilog builds work to C++, where files are compiled individually and are linked together in a separate step (a gross over-simplifaction). Changes to one class don’t cause recompiles of other classes in the same namespace, if the two classes are unrelated. This is because C++ classes are split between the header (which declares which functions a class provides) and the implementation (which contain the function bodies). A class that depends on another class includes its header, to let the compiler know that it relies on the other class. Only changes in a class’s header cause recompiles of dependent classes, while changes to its implementation don’t. Because of this setup, C++ builds are much more powerful when it comes to build avoidance, by only rebuilding the parts that they absolutely have to build. This allows for guidelines that incremental builds should take between 5-10 seconds and that full builds (including tests) should take between 1-2 minutes, according to http://www.bitsnbites.eu/faster-c-builds/, numbers which are incredibly low by SystemVerilog standards, where merely starting the simulator takes double digit numbers of seconds.

Case study

The classic testbench structure for an IP block consists of one or more interface verification components (IVCs), that contain code related to the signal protocols used by the design, and one module verification component (MVC), that contains code for aspects related to the design functionality.

IVCs typically consist of a package and one or more interfaces. We don’t usually make changes to the IVCs, so once we’ve built them via a full build, they won’t have any impact on subsequent incremental builds.

Most of our work is focused on the MVC. As we’ve seen above, if we place our MVC code into one package, then any change we make to it will trigger a new build, because of the way SystemVerilog tools handle incremental builds. This isn’t going to be very efficient, as an incremental build of the package after each change will take about as long as a full build.

What would happen if we could split our big MVC package into multiple smaller packages?

It’s experiment time again! We’ll assume that we can split the code such that building each package takes the same amount of time. We’ll also ignore any extra costs from building multiple packages instead of one single package. This means that if an incremental build of the entire mvc package would have taken N seconds, then by splitting it into P packages each of the smaller packages would take N/P seconds to build. We’ll also assume that we are just as likely to make changes to any of the smaller packages. This means that the probablity to change any package is 1/P.

Let’s assume that we can create two independent packages, p0 and p1. We can misuse UML to visualize the package topology:

Any change we make to p0 won’t cause rebuilds of p1 and vice-versa. We can compute the average incremental build time in this case. Building any of the packages takes N/2 seconds, but we do it only half of the time (since in the other half we change the other package). The average incremental build time is the mean: N/2 * 1/2 + N/2 * 1/2 = N/2. By splitting the code into two independent packages, we’ve managed to half our incremental build time. It’s not very realistic, though, that we could manage to do such a split on a real project.

Let’s have a look at something closer to reality. Let’s assume that we can split our MVC into two packages, p0 and p1, but p1 depends on p0:

An incremental build of p1 would still take only N/2 seconds, because changing anything in p1 doesn’t have any effect on p0. A change in p0 would mean that we also have to rebuild p1, which means that it would take N/2 + N/2 = N seconds. On average, we would need N/2 * 1/2 + N * 1/2 = 3/4 * N seconds.

We should try to structure our code in such a way as to increase the number of packages without any dependencies to each other. Let’s say we can split p1 from the previous example into two independent packages, p1_0 and p1_1:

In this case, changing anything in either p1_0 or p1_1 would take N/3 seconds. A change in p0 would require all three packages to be rebuilt and would take the full N seconds. On average, a change would take N/3 * 1/3 + N/3 * 1/3 + N * 1/3 = 7/9 * N seconds.

We could go on further with deeper package hierarchies, but I think you get the idea.

MVC code lends itself nicely to such a structure. We typically have some “common” code that models the basics of our DUT, from which we can model different higher level aspects, relating to the features of the DUT. We would use our models inside checks or coverage, which could be built independently from each other:

Conclusions

Splitting code across multiple packages will generally be better for compilation speed. There are also other advantages. It could make the code base easier to understand, by grouping code by theme (code for X goes in package p_x, code for Y goes in package p_y). It could also make development easier, by allowing developers to specialize in only a handful of the packages, instead of having to deal with the entire code base.

Having to manage multiple packages brings its own set of challenges, though. It could make the code base more difficult to understand if the boundaries between packages are arbitrary (where does code for X go, in p0 or p1?). More packages, especially when they have intricate dependency relationships, also make compilation more difficult to set up.

I’m not going to recommend making one package per class, just to improve build times. Ideally, SystemVerilog compilers should evolve to better handle incremental compilation, by working at levels lower than just packages. At the same time, you should care about turnaround time, so dumping all code into one package shouldn’t be your default mode of operation.

Aside from monitoring and driving signals, an interface UVC is also responsible for checking that the DUT conforms to the protocol specification. This is typically done with SystemVerilog assertions, which provide a compact and powerful syntax for describing temporal behavior at the signal level. I already wrote a bit about unit testing SVAs using SVAUnit, a library from our friends at AMIQ Consulting.

I’ve since then had a bit of an epiphany while working on an interface UVC for a new proprietary on-chip interface. Now on a previous module, I needed to write some bigger SVA properties of the type “when register X is written via AHB, then Y happens”. The AHB UVC I was using (also written by me a while back) only had assertions embedded in a checker, but it didn’t export any SVA sequences for users to combine into their own properties. I ended up doing a bit of clipboard based inheritance and defining the needed sequences in my module SVA checker. I had a similar problem when I was trying to write some simple formal properties for a different module, where I also just copied (gasp!) and patched the needed code. Now AHB isn’t such a complicated and/or dynamic protocol, but my actions were in direct violation of the DRY princple. For the new UVC I was developing, I decided to not make the same mistake and build a nice hierarchy of SVA sequences, properties and assertions. These would form part of the UVC API, sort of an SVA API which users could “call” in their own code. As any important parts of the exported API, such members have to be unit tested.

Let’s look at some simple AHB SVA constructs. Since this protocol is so popular, I assume that most of you are already aquainted with it and for those of you who aren’t I’ll try to keep things simple, but I won’t explain any protocol details. Since the spec isn’t open, I can’t link it here, but a quick search should net you some useful resources. Nevertheless, I’m pretty sure you’ll be able to follow the post without becoming an expert in the protocol.

One of the first non-trivial protocol rules for AHB is that “[when] the slave is requesting wait states, the master must not change the transfer type […]”. Let’s write a property for this with the following signature:

property trans_held_until_ready(HTRANS, HREADY);
  // ...
endproperty

In the previous post we saw how we can use the expect statement to check that signal toggles happen as desired. The unit test supplied the property, while the code being tested handled the signals. To check a property, we can reverse the two roles and have the test supply the signal toggles, while the code under test is exactly our property of interest. The same `FAIL_UNLESS_PROP(…) macro can help us check if the property passes for a legal trace:

    `SVTEST(trans_held_until_ready__trans_stable__passes)
      cb.HTRANS <= NONSEQ;
      cb.HREADY <= 0;
      cb.HREADY <= ##3 1;

      `FAIL_UNLESS_PROP(trans_held_until_ready(HTRANS, HREADY))
    `SVTEST_END

I’ve ommited the definitions of the signals, which are bundled in a clocking block called cb. Declaring this clocking block as default also allows use to use the cycled delay operator, ##n, which makes the code a bit more readable.

Just checking that properties pass is rather boring though. Not only that, but a property that doesn’t pass when it should results in a false negative, which is instantly visible in the simulation log. It’s much more valuable that a property fail when it should, because false positives are much more insidious and less likely to be caught. We can do this also with an expect statement, but we’ll need to trigger a fail if the corresponding pass block is triggered. As with `FAIL_UNLESS_PROP(…), we can wrap this check inside a macro:

`define FAIL_IF_PROP_PASS(prop) \
  expect (prop) \
    `FAIL_IF(1)

Having HTRANS change before an occurence of HREADY should cause our property to fail:

    `SVTEST(trans_held_until_ready__trans_changes__fails)
      cb.HTRANS <= NONSEQ;
      cb.HREADY <= 0;
      cb.HTRANS <= ##3 SEQ;

      `FAIL_IF_PROP(trans_held_until_ready(HTRANS, HREADY))
    `SVTEST_END

Here’s how a property that satisfies both tests could look:

property trans_held_until_ready(HTRANS, HREADY);
  HTRANS inside { NONSEQ, SEQ } |=>
    $stable(HTRANS) throughout HREADY [->1];
endproperty

Those of you who’ve worked with AHB before might raise an eyebrow looking at that code. What if, for example, HTRANS comes together with HREADY and changes in the following cycle? The property shouldn’t fail, as the first transfer was accepted and a new one can begin. We can add a test for this exact situation:

    `SVTEST(trans_held_until_ready__trans_stable__passes)
      cb.HTRANS <= NONSEQ;
      cb.HREADY <= 0;
      cb.HREADY <= ##3 1;

      `FAIL_UNLESS_PROP(trans_held_until_ready(HTRANS, HREADY))
    `SVTEST_END

With this test, we can fix the property:

  property trans_held_until_ready(HTRANS, HREADY);
    HTRANS inside { NONSEQ, SEQ } |->
      HREADY or ##1 ($stable(HTRANS) throughout HREADY [->1]);
  endproperty

Some of you might argue that when HTRANS comes at the same time as HREADY, we’re not really “holding” anything. It could be argued that this is a special case and what we’re really interested in for this property are the cases where we actually see some wait states. We could exclude the instant grant case by tweaking the antecedent in such a way that it doesn’t match. This would lead to a vacuous pass of the property. A vacuous pass means that we have’t really checked anything, because we didn’t particularly care what happened in that situation. Vacuous passes aren’t usually shown in the assertion statistics, so we could “misuse” the number of times an assertion of this property passes as coverage for how many times we’ve seen (correctly) stalled transfers.

A vacuous pass is still a pass though and as per the LRM it should also trigger the execution of an assert/expect statement’s pass block. Some tools don’t work like this, though, choosing instead to not execute pass blocks on vacuous successes (unless the user explictly enables this, maybe via some command line switch or simulator setting). We can use this to our advantage to distinguish between a “real” pass and a vacuous pass. What we have then, is a sort of ternary logic, where a property can result in one of the following:

• (nonvacuous) pass, where the pass block is executed
• fail, where the fail block is executed
• vacuous pass, where neither block is executed

Note that there’s no concept of vacuous fails. Something either works, it doesn’t or it isn’t “important”.

Even if a simulator does execute pass block for vacuous successes, this behavior can either be turned off via a switch or, in a more portable fashion, via the $assertcontrol(…) system task (if it’s supported by the tool). This means that we can rather safely rely on the behavior described in the outcome list to determine vacuity.

As before, we can wrap such a check inside a macro. It’s definition is a bit trickier, since we need to check that neither block was executed. We can do this using variables:

`define FAIL_UNLESS_PROP_VAC(prop) \
  begin \
    bit pass_called; \
    bit fail_called; \
    \
    expect (prop) \
      pass_called = 1; \
    else \
      fail_called = 1; \
    \
    if (pass_called || fail_called) \
      `FAIL_IF(1) \
  end

If any of the two blocks gets executed, one of the variables will be set and we can issue an error. This code, while deceptively simple, fails to compile in some simulators, with them complaining that they can’t find the definition of pass_called inside the pass block (and, of course, the same for fail_called). This is the part where I got bogged down trying to find a suitable workaround. The only way I could get this to work was to define the *_called variables inside a package and use the scope operator to reference them in the pass/fail blocks:

package vgm_svunit_utils_sva;

  bit pass_called;
  bit fail_called;

endpackage

This seems rather crazy, because not only does it require a user to include the file with the macro definition, but to also compile the extra support package. It’s a bit much for just a couple of measly variables, but it’s either this or nothing…

Since we’re going to rely on global variables with a persistent lifetime, we’ll need to make sure to set them to 0 before executing the expect:

`define FAIL_UNLESS_PROP_VAC(prop) \
  begin \
    vgm_svunit_utils_sva::pass_called = 0; \
    vgm_svunit_utils_sva::fail_called = 0; \
    \
    expect (prop) \
      vgm_svunit_utils_sva::pass_called = 1; \
    else \
      vgm_svunit_utils_sva::fail_called = 1; \
    \
    if (vgm_svunit_utils_sva::pass_called || \
        vgm_svunit_utils_sva::fail_called) \
      `FAIL_IF(1) \
  end

Using this macro, we can tweak our test for instantly granted transfers to require a vacuous pass for the property:

    `SVTEST(trans_held_until_ready__trans_stable__vacuous)
      cb.HTRANS <= NONSEQ;
      cb.HREADY <= 0;
      cb.HREADY <= ##3 1;

      `FAIL_UNLESS_PROP_VAC(trans_held_until_ready(HTRANS, HREADY))
    `SVTEST_END

This will also mean that we have to fix the property:

property trans_held_until_ready(HTRANS, HREADY);
  HTRANS inside { NONSEQ, SEQ } && !HREADY |=>
    $stable(HTRANS) throughout HREADY [->1];
endproperty

Let’s take a step back now. Remember, that for the `FAIL_IF_PROP(…) macro we were checking whether the pass block is executed and if it was we issued an error. This doesn’t fit into the whole “ternary logic” scheme we discussed above when talking about vacuity. If we only did this, we wouldn’t be able to distinguish a fail from a vacuous pass. The macro name is also kind of misleading. What do we want here? Do we want the property to fail? Do we want it to fail or be vacuous, but under no circumstances result in a nonvacuous pass? What I intended was the former, but others could just as well interpret it as the latter.

More explicit macros would better clarify our intent. In this case, what we want is a `FAIL_UNLESS_PROP_FAIL(…) macro, because we are explicitly checking that the property can catch errors. What we should check is that the fail block gets executed:

`define FAIL_UNLESS_PROP_FAIL(prop) \
  begin \
    vgm_svunit_utils_sva::fail_called = 0; \
    \
    expect (prop) \
    else \
      vgm_svunit_utils_sva::fail_called = 1; \
    \
    if (!vgm_svunit_utils_sva::fail_called) \
      `FAIL_IF(1) \
  end

In some cases, we would want to forbid a property to fail, but it wouldn’t be important if the pass is vacuous or not. Here we would have a `FAIL_IF_PROP_FAIL(…) macro, that check that the fail block wasn’t executed. There are six such macros that we can define, a pair for each of the three possible outcomes. We won’t look at their definitions here, but their construction is pretty simple now that we know the behavior of the pass/fail blocks.

It’s time for another realization about our property: the trigger condition is slightly off. Once we assert it what’s going to happen is that a new evaluation thread is going to be started on each clock cycle where a transfer is stalled. All of these threads are going to run in parallel, perform the same check and end at the very same time – when HREADY finally comes. This isn’t good for perfomance, especially if we have many AHB interfaces and very long stalls.

The start of an AHB transaction is a pretty interesting event, not only for this property, but potentially for others. A UVC user might be interesed in writing an own property that triggers once a transfer has started. We can fix our property and at the same time provide a reusable building block by defining a sequence:

sequence trans_started(HTRANS);
  // ...
endsequence

Just as for properties we wanted to check whether they fail or pass when we want them, for sequence we want to make sure that they match when they should and don’t match when they shouldn’t. We can check for a sequence match (or lack thereof) by treating it as a property and checking its pass/fail state. Doing the following would look a bit weird, though:

`FAIL_UNLESS_PROP_PASS(trans_started(HTRANS))

The intent of the code becomes a bit muddied: “Are we testing a property? But I thought trans_started(…) was a sequence…”. It would be better to have separate macros for sequence testing:

`define FAIL_IF_SEQ(seq) \
  `FAIL_UNLESS_PROP_FAIL(seq ##0 1)

`define FAIL_UNLESS_SEQ(seq) \
  `FAIL_UNLESS_PROP_PASS(seq ##0 1)

Using these will make the code a bit clearer. Also, notice the extra ##0 1 fused after the sequence. This is to ensure that we can’t accidentally pass a property as an argument, because the fusion operator will cause a compile error unless what comes before it is a sequence.

Coming back to our trans_started(…) sequence, the first thing we would like it to do is to not match when HTRANS is IDLE:

    `SVTEST(trans_started__idle__doesnt_match)
      HTRANS <= IDLE;
      `FAIL_IF_SEQ(trans_started(HTRANS))
    `SVTEST_END

We would also like it to match then HTRANS becomes active after an IDLE:

    `SVTEST(trans_started__coming_from_idle__matches)
      cb.HTRANS <= IDLE;
      ##1;

      cb.HTRANS <= NONSEQ;

      `FAIL_UNLESS_SEQ(trans_started(HTRANS))
    `SVTEST_END

With our tests in place, we can write the sequence implementation that fulfils them:

sequence trans_started(HTRANS);
  HTRANS inside { NONSEQ, SEQ } &&
    $past(HTRANS inside { IDLE, BUSY });
endsequence

Something still doesn’t feel right, though. What about back to back transfers? It’s perfectly legal to start a new transfer immediately after the previous one was granted. In this case, there isn’t any IDLE cycle to use as an anchor. What we can, however, use is the occurrence of HREADY in the previous cycle, which we’ll have to feed to the property. Here’s how this could be tested:

    `SVTEST(trans_started__after_done_trans__matches)
      cb.HTRANS <= NONSEQ;
      cb.HREADY <= 1;
      ##1;

      `FAIL_UNLESS_SEQ(trans_started(HTRANS, HREADY))
    `SVTEST_END

The fixed sequence would then be:

sequence trans_started(HTRANS, HREADY);
  HTRANS inside { NONSEQ, SEQ } &&
    $past(HTRANS inside { IDLE, BUSY } || HREADY);
endsequence

If we try to run this in the simulator, though, the test is still going to fail, even though there isn’t anything obviously wrong with our fix. This is because the test contains a very subtle mistake. When the underlying expect statement from the `FAIL_*(…) macro kicks in, in its very first cycle the value returned by $past(HREADY) is 0, because we haven’t actually let it run long enough for there to have been an actual previous cycle. The LRM states that in this case $past(…) returns the default value of the expression passed to it. What we need to do is move the delay operator into the `FAIL_*(…) macro, to allow the expect to sample HREADY first and look for a match of trans_started(…) afterwards:

    `SVTEST(trans_started__after_done_trans__matches)
      cb.HTRANS <= NONSEQ;
      cb.HREADY <= 1;

      `FAIL_UNLESS_SEQ(##1 trans_started(HTRANS, HREADY))
    `SVTEST_END

This way the test does what we intend it to do. We can now instantiate the sequence inside our trans_held_until_ready(…) property to have it trigger at the appropriate times. Since trans_started(…) has already been tested, we don’t have to write too many tests for the property, focusing just on what’s important. Also, by breaking the problem into smaller parts its easier to notice what the corner cases might be. As we’ve seen, writing even such a small property can be tricky, so we should make sure that our code works before trusting it to find design bugs.

Regarding the testing of assertions, I’m not saying that this isn’t important as well. A lot of the more complicated assertions we need to write will have to rely on support code (for example when pipelining comes into the mix) and we’re going to want to check that all parts of an assertion – the property, the support code and the connections between them – fit properly together. For protocol assertions and other simple assertions, I favor breaking down into smaller properties and sequences and testing those, not only to make testing easier, but to also provide a set of reusable elements that UVC users can integrate into their own code.

You can find the full code for the examples here and you can also download the SVUnit utils package if you want to start using these techiques for your own code.

There’s still some work to be done regarding unit tests and SVA constructs. For one, we strongly relied on the assumption that vacuous passes don’t trigger action blocks. We could add some code that tests this assumption by doing a trial run of a known vacuous property (e.g. 0 -> 1). If this isn’t the case, we could try calling the $assertcontrol(…) system task to disable vacuous success execution of pass blocks, if the task is available. Finally, if all else fails, we could inform the user to change the tool invocation to match our required behavior. This plan makes me feel less bad about the extra *_utils_sva package, which we had to use for the workaround with the status variables, because this is where we’d put all of this extra code. I’d also like to see this code merged into SVUnit at some point, but I’m not sure if now is the right time, due to the differences in tool capabilities across simulator vendors.

Now I’d like to conclude this series on unit testing UVCs. The tips in the past few posts should help you develop your UVCs faster and with higher quality, thereby increasing your confidence that they are ready for life in the harsh and unforgiving world of verification.

interface vgm_axi_interface(input bit ACLK, input bit ARESETn);
  logic [3:0] AWID;
  logic [31:0] AWADDR;
  logic [3:0] AWLEN;
  logic AWVALID;
  logic AWREADY;

  logic [3:0] WID;
  logic [31:0] WDATA;
  logic WLAST;
  logic WVALID;
  logic WREADY;

  logic [3:0] BID;
  logic [1:0] BRESP;
  logic BVALID;
  logic BREADY;
endinterface

Our sequence item will model the properties of a write transaction:

typedef enum bit [3:0] { LENGTH_[1:16] } length_e;


class sequence_item extends uvm_sequence_item;
  rand bit [3:0] id;
  rand bit [31:0] address;
  rand length_e length;
  rand transfer transfers[];
  rand int unsigned delay;

  // ...
endclass


class transfer extends uvm_sequence_item;
  rand bit[31:0] data;
  rand int unsigned delay;

  // ...
endclass

The driver will consist of the familiar get and drive loop:

class master_driver extends uvm_driver #(sequence_item);
  virtual vgm_axi_interface intf;

  virtual protected task get_and_drive();
    forever begin
      seq_item_port.get_next_item(req);
      drive();
      seq_item_port.item_done();
    end
  endtask

  // ...
endclass

We’ll implement the driver based on the following unit tests. Have a quick look at them before going further:

    `SVTEST(drive_awvalid__with_delay)
      sequence_item item = new("item");
      `FAIL_UNLESS(item.randomize() with {
        delay == 3;
      })
      sequencer.add_item(item);

      repeat (3)
        @(posedge clk) `FAIL_UNLESS(intf.AWVALID === 0)
      @(posedge clk) `FAIL_UNLESS(intf.AWVALID === 1)
    `SVTEST_END


    `SVTEST(drive_awvalid__held_until_hready)
      sequence_item item = new("item");
      `FAIL_UNLESS(item.randomize() with {
        delay == 0;
      })
      sequencer.add_item(item);
      intf.AWREADY <= 0;

      repeat (4)
        @(posedge clk) `FAIL_UNLESS(intf.AWVALID === 1)

      intf.AWREADY <= 1;
      @(posedge clk) `FAIL_UNLESS(intf.AWVALID === 1)
      @(posedge clk) `FAIL_UNLESS(intf.AWVALID === 0)
    `SVTEST_END


    `SVTEST(drive_write_addr_channel)
      sequence_item item = new("item");
      `FAIL_UNLESS(item.randomize() with {
        id == 5;
        address == 'h1122_3344;
        length == LENGTH_14;
        delay == 0;
      })
      sequencer.add_item(item);

      @(posedge clk);
      `FAIL_UNLESS(intf.AWID == 5)
      `FAIL_UNLESS(intf.AWADDR == 'h1122_3344)
      `FAIL_UNLESS(intf.AWLEN == 'b1101)
    `SVTEST_END


    `SVTEST(drive_wvalid__with_delay)
      sequence_item item = new("item");
      `FAIL_UNLESS(item.randomize() with {
        delay == 0;
        length == LENGTH_4;
        transfers[0].delay == 1;
        transfers[1].delay == 3;
        transfers[2].delay == 2;
        transfers[3].delay == 0;
      })
      sequencer.add_item(item);

      // Skip over address phase
      @(posedge clk);

      @(posedge clk) `FAIL_UNLESS(intf.WVALID === 0)
      @(posedge clk) `FAIL_UNLESS(intf.WVALID === 1)

      repeat (3)
        @(posedge clk) `FAIL_UNLESS(intf.WVALID === 0)
      @(posedge clk) `FAIL_UNLESS(intf.WVALID === 1)

      repeat (2)
        @(posedge clk) `FAIL_UNLESS(intf.WVALID === 0)
      @(posedge clk) `FAIL_UNLESS(intf.WVALID === 1)

      @(posedge clk) `FAIL_UNLESS(intf.WVALID === 1)
    `SVTEST_END


    `SVTEST(drive_write_data_channel)
      sequence_item item = new("item");
      `FAIL_UNLESS(item.randomize() with {
        delay == 0;
        length == LENGTH_4;
        transfers[0].data == 'hffff_ffff;
        transfers[1].data == 'h0000_0000;
        transfers[2].data == 'haaaa_aaaa;
        transfers[3].data == 'h5555_5555;
        transfers[0].delay == 0;
        transfers[1].delay == 0;
        transfers[2].delay == 0;
        transfers[3].delay == 0;
      })
      sequencer.add_item(item);

      // Skip over address phase
      @(posedge clk);

      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'hffff_ffff)
      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'h0000_0000)
      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'haaaa_aaaa)
      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'h5555_5555)
    `SVTEST_END


    `SVTEST(drive_write_data_channel__data_held_until_wready)
      sequence_item item = new("item");
      `FAIL_UNLESS(item.randomize() with {
        delay == 0;
        length == LENGTH_4;
        transfers[0].data == 'hffff_ffff;
        transfers[1].data == 'h0000_0000;
        transfers[2].data == 'haaaa_aaaa;
        transfers[3].data == 'h5555_5555;
        transfers[0].delay == 0;
        transfers[1].delay == 0;
        transfers[2].delay == 0;
        transfers[3].delay == 0;
      })
      sequencer.add_item(item);

      // Skip over address phase
      @(posedge clk);

      intf.WREADY <= 0;
      repeat (3)
        @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'hffff_ffff)
      intf.WREADY <= 1;
      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'hffff_ffff)

      intf.WREADY <= 0;
      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'h0000_0000)
      intf.WREADY <= 1;
      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'h0000_0000)

      intf.WREADY <= 0;
      repeat (2)
        @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'haaaa_aaaa)
      intf.WREADY <= 1;
      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'haaaa_aaaa)

      intf.WREADY <= 0;
      repeat (4)
        @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'h5555_5555)
      intf.WREADY <= 1;
      @(posedge clk) `FAIL_UNLESS(intf.WDATA === 'h5555_5555)
    `SVTEST_END


    `SVTEST(drive_write_data_channel__wlast_driven_for_last_transfer)
      sequence_item item = new("item");
      `FAIL_UNLESS(item.randomize() with {
        delay == 0;
        length == LENGTH_8;
        foreach (transfers[i])
          transfers[i].delay == 0;
      })
      sequencer.add_item(item);

      // Skip over address phase
      @(posedge clk);

      repeat (7)
        @(posedge clk) `FAIL_IF(intf.WLAST)
      @(posedge clk) `FAIL_UNLESS(intf.WLAST)
    `SVTEST_END

The tests above cover the desired functionality that we want to implement in our driver. We won’t go through each and every one of them and see what production code we need to write, since the actual implementation of the driver isn’t really important for this post. We want to focus more on the tests themselves.

When first confronted with these tests, a new developer won’t have an easy time understanding what’s going on. The tests are pretty verbose and it’s not immediately clear what the focus of each one is. Let’s see how we could improve this.

First, we’ll notice that the one thing we do in each test is to create an item and queue it for the driver. We use randomization to make sure that the item is “consistent”, meaning that the constraints defined in it hold. We could set item variables procedurally, but we would need to ensure that the length and the number of transfers match, which would mean even more code. Instead of repeating these steps in each unit test, we could centralize them into one place. Since we use randomization, we can’t extract a function. We’re forced to use a macro:

  `define add_item_with(CONSTRAINTS) \
    sequence_item item = new("item"); \
    `FAIL_UNLESS(item.randomize() with CONSTRAINTS) \
    sequencer.add_item(item);

This is going to save us some lines of code and it’s going to make the intent of the code more obvious. What will differ between unit tests are the constraints they use when adding an item:

    `SVTEST(drive_awvalid__with_delay)
      `add_item_with({
        delay == 3;
      })

      // ...
    `SVTEST_END


    `SVTEST(drive_awvalid__held_until_hready)
      `add_item_with({
        delay == 0;
      })

      // ...
    `SVTEST_END


    `SVTEST(drive_write_addr_channel)
      `add_item_with({
        id == 5;
        address == 'h1122_3344;
        length == LENGTH_14;
        delay == 0;
      })

      // ...
    `SVTEST_END

We can even go one step further. If we look at the tests again, we’ll notice that we use the same constraint over and over again to get an item without any delay. Also, whenever we want to check some write data channel aspects, we want to constrain the delay of each transfer to be zero. We do have tests where we want non-zero delays, but they are the exceptional cases. What we could do is to add some default values to the delay variables via soft constraints. This way, whenever we use the `add_item_with(...) macro we know that we’ll get an item without any delay:

  `define add_item_with(CONSTRAINTS) \
    sequence_item item = new("item"); \
    `FAIL_UNLESS(item.randomize() with { \
      soft delay == 0; \
      foreach (transfers[i]) \
        soft transfers[i].delay == 0; \
      \
      if (1) \
        CONSTRAINTS \
    }) \
    sequencer.add_item(item);

This way, we can write even more compact code to add items. Here are the two data tests I mentioned:

    `SVTEST(drive_write_data_channel)
      `add_item_with({
        length == LENGTH_4;
        transfers[0].data == 'hffff_ffff;
        transfers[1].data == 'h0000_0000;
        transfers[2].data == 'haaaa_aaaa;
        transfers[3].data == 'h5555_5555;
      })

      // ...
    `SVTEST_END


    `SVTEST(drive_write_data_channel__data_held_until_wready)
      `add_item_with({
        length == LENGTH_4;
        transfers[0].data == 'hffff_ffff;
        transfers[1].data == 'h0000_0000;
        transfers[2].data == 'haaaa_aaaa;
        transfers[3].data == 'h5555_5555;
      })

      // ...
    `SVTEST_END

If we compare them with the initial version from the beginning of the post, we’ll see that they are much more compact. It’s also clearer that the handling of the data variables are what we’re testing and not anything related to delays.

Since we want to check the behavior of signals at certain points in time, we need to do a lot of waits. The statement @(posedge clk) comes up a lot in our unit tests. We could shorten this by using a default clocking block:

module master_driver_unit_test;
  // ...

  default clocking @(posedge clk);
  endclocking
endmodule

Now, instead of using the verbose @(posedge clk) statement, we can use the cycle delay operator:

    `SVTEST(drive_wvalid__with_delay)
      // ...

      // Skip over address phase
      ##1;

      ##1 `FAIL_UNLESS(intf.WVALID === 0)
      ##1 `FAIL_UNLESS(intf.WVALID === 1)

      repeat (3)
        ##1 `FAIL_UNLESS(intf.WVALID === 0)
      ##1 `FAIL_UNLESS(intf.WVALID === 1)

      repeat (2)
        ##1 `FAIL_UNLESS(intf.WVALID === 0)
      ##1 `FAIL_UNLESS(intf.WVALID === 1)

      ##1 `FAIL_UNLESS(intf.WVALID === 1)
    `SVTEST_END

Having less words to parse makes the test’s intent clearer. Using a default clocking block is an option most of the time, but if you have a more exotic protocol that uses both edges of the clock or multiple clocks altogether, it’s not going to work.

One thing you may have noticed is that I’ve marked some wait statements with comments. If you’ve read Clean Code (and if you haven’t you should), you’ll call me out on this. Uncle Bob says that comments are a crutch for poorly written code that doesn’t express its intent properly. Instead of relying on comments, we could create a named task:

  task wait_addr_phase_ended();
    ##1;
  endtask

Now, when a test calls this task, it’ll be immediately apparent what the intention is:

    `SVTEST(drive_write_data_channel)
      `add_item_with({
        // ...
      })

      wait_addr_phase_ended();

      // ...
    `SVTEST_END

There is a mismatch between what the task does and its name. The task actually just waits for one cycle. To reflect this, it should have been named wait_cycle(). A task call like this will take us back to square one in terms of test readability. We may as well just use the ##1 statement as that tells us the same thing. If we want to solve this mismatch between the task name and its implementation, we should change the latter. In the context of our tests, we knew that the address phase was going to end after one clock cycle. Generally, though, What we want is to wait for AWVALID and AWREADY to be high at the same time:

  task wait_addr_phase_ended();
    @(posedge clk iff intf.AWVALID && intf.AWREADY);
  endtask

Some unit-testing purists might bash this method because it adds complexity to the testing logic. This is something we should try to avoid, since we don’t want to have to start testing our tests. The task is lean enough that I’d say this point doesn’t apply here.

While we may have streamlined our test preparation code, checking that our expectations are fulfilled is ridiculously long. Procedural code isn’t really well suited to check behavior over time. You know what is though? Assertions… Instead of writing a big mess of procedural code that does repeats and cycle delays, we could write a nice property and check that it holds. When people hear the word property, they normally think of concurrent assertions, but this isn’t really what we want here. What we want to do is to check that a certain property holds after a certain point in time, not during the whole simulation.

Luckily, SystemVerilog provides the expect construct, which does exactly what we want. Given a property, it will begin evaluating it starting with the first subsequent clock. For example, to check that the driver can drive data transfers with delays, we could write the following:

    `SVTEST(drive_wvalid__with_delay)
      // ...

      expect (
        intf.WVALID === 0
          ##1 intf.WVALID === 1
          ##1 intf.WVALID === 0 [*3]
          ##1 intf.WVALID === 1
          ##1 intf.WVALID === 0 [*2]
          ##1 intf.WVALID === 1
          ##1 intf.WVALID === 1)
      else
        `FAIL_IF(1)
    `SVTEST_END

This is much cleaner than the procedural code we had before. It also allows us to structure our unit tests according to the Arrange, Act, Assert pattern (even though most of the time for drivers Arrange and Act get a bit mixed, but at least Assert is separated clearly).

Since expecting that properties hold is something we’ll want to do over and over again, let’s wrap it in a utility macro and make it part of the vgm_svunit_utils package:

`define FAIL_UNLESS_PROP(prop) \
  expect (prop) \
  else \
    `FAIL_IF(1)

Using this macro will give the unit tests a more consistent SVUnit look and feel:

    `SVTEST(drive_wvalid__with_delay)
      // ...

      `FAIL_UNLESS_PROP(
        intf.WVALID === 0
          ##1 intf.WVALID === 1
          ##1 intf.WVALID === 0 [*3]
          // ...
      )
    `SVTEST_END

As we saw in the previous post, it’s very important to use the === (4-state equality) operator instead of ==, otherwise we’re writing tests that always pass. I intentionally wrote the drive_write_addr_channel buggy to show this (kudos to anyone who noticed). Also, we need to watch out for hidden comparisons. In the last test we didn’t even use the equality operator:

    `SVTEST(drive_write_data_channel__wlast_driven_for_last_transfer)
      // ...

      repeat (7)
        @(posedge clk) `FAIL_IF(intf.WLAST)
      @(posedge clk) `FAIL_UNLESS(intf.WLAST)
    `SVTEST_END

Because of the way the `FAIL_* macros are written, they will both always pass, so the test isn’t really doing anything. If we were to re-write them using properties, we would notice if WLAST isn’t being driven:

    `SVTEST(drive_write_data_channel__wlast_driven_for_last_transfer)
      // ...

      `FAIL_UNLESS_PROP(
        !intf.WLAST [*7]
          ##1 intf.WLAST)
    `SVTEST_END

If WLAST were to be X, then the negation would also return X, which would be interpreted as a 0, leading to a fail of the property. For single bit signals, using properties is much safer than comparing for equality. There’s also the added bonus that the code is more compact. For vectors, though, we still need to make sure that we’re using the === operator.

Another cool thing that properties allow us to do is to focus more on the aspects that are important for a test. For example, in the data_held_until_ready test we want to check that the driver doesn’t modify the value of WDATA until it sees a corresponding WREADY. We did this by choosing known values for the data transfers and checking that these values stay on the bus for the appropriate number of clock cycles. Actually, we don’t (or shouldn’t) care what data is being driven, as long as it stays constant. We could simplify the code to the following:

    `SVTEST(drive_write_data_channel__data_held_until_wready)
      `add_item_with({
        length == LENGTH_4;
      })

      // ...

      `FAIL_UNLESS_PROP(
        stable_for(intf.WDATA, 3)
          ##1 stable_for(intf.WDATA, 1)
          ##1 stable_for(intf.WDATA, 2)
          ##1 stable_for(intf.WDATA, 4))
    `SVTEST_END

The stable_for(…) sequence only exists because my simulator complained about using $past(...) inside an expect statement. It’s content could have been inlined to the property:

  sequence stable_for(signal, int unsigned num_cycles);
    ##1 ($stable(signal) [*num_cycles]);
  endsequence

We don’t really need to use a property to check that the signal stays stable. As per the LRM we could use the $stable(...) system function inside procedural code as well, but some tools don’t allow this, limiting its use to assertions.

While it’s usually frowned upon to have randomness in unit tests, I would argue that this isn’t necessarily a problem here. Randomness should be avoided because it causes us to write complicated code for our expectations. As long as we don’t need to do this (i.e. the checking code stays the same regardless of what we plug into it), everything should be fine. There is one caveat, though. On the off chance that two consecutive transfers contain the same data, it won’t be possible to figure out whether the driver moved to the second transfer too early. In the extreme case, all transfers could have the same data value, making it impossible to check that the driver really holds transfers constant for their entire durations. This could be solved by writing a constraint that all data values should be unique.

Last, but not least, I hinted in the previous post that a driver not only drives items from the sequencer. It’s also supposed to request items from the sequencer at well defined points in time. For example, a driver should call get_next_item(...) once it’s able to process a new item, but not before, to allow the running sequence to randomize items at the latest possible time (so called late randomization). This is helpful when sequences use the current state of the system to decide what to do next. For simple protocols this is easy: a new item can start exactly after the previous one has finished. For pipelined protocols, though, it’s a not as easy. The AXI protocol is massively pipelined and can have a lot of ongoing transactions at any time. I don’t want to have to think what a sensible definition for an available slot for a new item would be, because the scheme would probably be too complicated. I do however want to show how we could verify that a driver calls sequencer methods at defined times.

We’ll take a contrived example of how to handle responses, since I couldn’t think of anything better. Whether we’re checking that put_response(...) or get_next_item(...) was called when expected doesn’t really matter, so this example should be enough to prove a point. Let’s say that when a response comes on the write response channel, the driver is supposed to let the sequencer know.

We’ll have another sequence item for the response:

typedef enum { OKAY, EXOKAY, SLVERR, DECERR } response_kind_e;

class response extends uvm_sequence_item;
  bit [3:0] id;
  response_kind_e kind;

  // ...
endclass

First of all, we’ll want to check that the response contains the proper values:

    `SVTEST(put_response_when_ready)
      response rsp;

      intf.BID <= 5;
      intf.BVALID <= 1;
      ##1;

      intf.BREADY <= 1;
      ##1;

      uvm_wait_for_nba_region();
      `FAIL_UNLESS(sequencer.try_get_rsp(rsp))
      `FAIL_UNLESS(rsp.id == 5)
    `SVTEST_END

The driver waits for a response to be seen on the bus and calls put_response(...) when this is the case:

class master_driver extends uvm_driver #(sequence_item, response);
  // ..

  virtual protected task collect_and_put();
    forever begin
      collect();
      seq_item_port.put_response(rsp);
    end
  endtask

  virtual protected task collect();
    @(intf.ACLK iff intf.BVALID);
    rsp = response::type_id::create("rsp");
    rsp.id = intf.BID;
  endtask
endclass

The test is going to pass with this implementation. The problem is, though, that the response is considered to be done only once it has also been accepted, i.e. BREADY goes high. Unfortunately, the previous code sends responses too early. We’ll need to update our unit test to check that put_response(...) was called after BREADY was also high and that it was called only once. This is where the test diagnostic information that sequencer_stub provides is going to be useful:

    `SVTEST(put_response_when_ready)
      // ...

      intf.BREADY <= 1;
      ##1;

      `FAIL_UNLESS_TRIGGERED(sequencer.put_response_called)
      `FAIL_UNLESS(sequencer.num_put_response_calls == 1)

      // ...
    `SVTEST_END

The sequencer_stub class contains a named event put_response_called that, as the name suggests, is triggered when put_reponse(...) is called by the driver. The `FAIL_UNLESS_TRIGGERED(...) macro is part of the vgm_svunit_utils package. It wraps the code required to check that an event was triggered in the current time step:

`define FAIL_UNLESS_TRIGGERED(ev) \
  fork \
    wait (ev.triggered); \
    \
    begin \
      #1; \
      `FAIL_IF_LOG(1, `"'ev' not triggered`") \
    end \
  join_any \
  disable fork;

The wait statement checks if the event was already triggered (because the driver code could have executed first) and if it wasn’t, it blocks. If time moves forward and the event didn’t get triggered, an error message is triggered. Since the test will now fail, we’ll need to update the driver code (not shown).

We’ve covered a lot of ground in this post on how to write more comprehensive, readable and maintainable unit tests for UVM drivers. You can find the example code here. I hope this helps you be more productive when developing your own drivers.

I first started with unit testing about two years ago, while developing some other interface UVCs. I’ve learned a few things throughout this time and I’d like to share some of the techniques I’ve used. In this post we’ll look at how to test UVM drivers.

A driver is supposed to take a transaction (called a sequence item in UVM lingo) and convert it into signal toggles. Testing a driver is conceptually pretty straightforward: we supply it with an item and we check that the toggles it produces are correct. As an example, we’ll take the Wishbone protocol, revision B.3. Our sequence item models the properties of an access:

typedef enum { READ, WRITE } direction_e;


class sequence_item extends uvm_sequence_item;
  rand direction_e direction;
  rand bit[31:0] address;
  rand bit[31:0] data;

  rand int unsigned delay;

  // ...
endclass

Aside from the direction, address and data, we can also randomize how many clock cycles the driver should wait before starting the transfer.

All the drivers I’ve seen up to now consisted primarily of a loop in which an item is fetched and then driven:

class master_driver extends uvm_driver #(sequence_item);
  virtual task run_phase(uvm_phase phase);
    forever begin
      seq_item_port.get_next_item(req);
      drive();
      seq_item_port.item_done();
    end
  endtask

  // ...
endclass

Our goal is to write the drive() task.

Let’s look at how to supply a driver with an item. A driver is an active component, that asks for items at its own pace. Inside an agent, it’s connected to a sequencer, that feeds it with items when they become available. Inside our unit test, we need to emulate the same relationship by having a test double which the driver can interrogate. There’s nothing stopping us from using uvm_sequencer itself:

module master_driver_unit_test;
  master_driver driver;
  uvm_sequencer #(sequence_item) sequencer;


  function void build();
    svunit_ut = new(name);

    driver = new("driver", null);
    sequencer = new("sequencer", null);
    driver.seq_item_port.connect(sequencer.seq_item_export);
  endfunction

  // ...
endmodule

The first test we want to write is that when the driver gets an item with no delay, it drives CYC_O and STB_O immediately. We first create an item and we start it on the sequencer using execute_item(…). This models a `uvm_send(...) action inside a sequence:

module master_driver_unit_test;

  `SVTEST(cyc_and_stb_driven)
    sequence_item item = new("item");

    fork
      sequencer.execute_item(item);
    join_none

    @(posedge clk);
    `FAIL_UNLESS(intf.CYC_O === 1)
    `FAIL_UNLESS(intf.STB_O === 1)
  `SVTEST_END

  // ...
endmodule

Since execute_item(…) blocks until the driver finishes processing the item, we’ll need to fork it out to be able to check what the driver does with the it.

After supplying the driver with the item, we need to check that it drives the appropriate signal values. Once an item is gotten, we expect the driver to start driving CYC_O and STB_O and their values to be valid on the next posedge. We have to check one clock cycle at a time. For example, if we would drive an item with a delay of three cycles, the unit test would look like this:

module master_driver_unit_test;

  `SVTEST(cyc_and_stb_driven_with_delay)
    sequence_item item = new("item");
    item.delay = 3;

    fork
      sequencer.execute_item(item);
    join_none

    repeat (3) begin
      @(posedge clk);
      `FAIL_UNLESS(intf.CYC_O === 0)
      `FAIL_UNLESS(intf.STB_O === 0)
    end

    @(posedge clk);
    `FAIL_UNLESS(intf.CYC_O === 1)
    `FAIL_UNLESS(intf.STB_O === 1)
  `SVTEST_END

  // ...
endmodule

It’s not enough to just skip the first three clock cycles. We need to ensure that the driver signals idle cycles during that time. Also, notice the use of the === operator (4-state equality). If we were to use the == operator instead, we would get false positives if the driver doesn’t drive any of the signals. This is because X (unknown value due to not being driven) matches anything.

We could write a few more unit tests for our driver. For example, a test could check that a read transfer is properly driven:

module master_driver_unit_test;

  `SVTEST(read_transfer_driven)
    sequence_item item = new("item");
    item.direction = READ;
    item.address = 'haabb_ccdd;

    fork
      sequencer.execute_item(item);
    join_none

    @(posedge clk);
    `FAIL_UNLESS(intf.WE_O === 0)
    `FAIL_UNLESS(intf.ADR_O === 'haabb_ccdd)
  `SVTEST_END

  // ...
endmodule

Another test would check that a write transfer is properly driven:

module master_driver_unit_test;

  `SVTEST(write_transfer_driven)
    sequence_item item = new("item");
    item.direction = WRITE;
    item.address = 'h1122_3344;

    fork
      sequencer.execute_item(item);
    join_none

    @(posedge clk);
    `FAIL_UNLESS(intf.WE_O === 1)
    `FAIL_UNLESS(intf.ADR_O === 'h1122_3344)
  `SVTEST_END

  // ...
endmodule

Notice that in the last two tests we didn’t check CYC_O and STB_O anymore. This is because we already checked that they get driven when sending an item. When we write the unit tests, we don’t write them in isolation from the production code. They evolve together. To save effort and make the tests more readable, we can focus on certain aspects of the class we want to test.

The implementation of the drive() task would look something like this:

class master_driver extends uvm_driver #(sequence_item);
  virtual protected task drive();
    repeat (req.delay)
      @(posedge intf.CLK_I);

    intf.CYC_O <= 1;
    intf.STB_O <= 1;
    intf.WE_O <= req.direction;
    intf.ADR_O <= req.address;

    // ...
  endtask

  // ...
endclass

We can see that we drive WE_O and ADR_O at the same time we write CYC_O and STB_O. It wouldn’t bring us much if we, for example, exhaustively checked that the address can be driven with different delays.

Up to now we only tested that the driver properly reacts to requests from the sequencer. Most of the times, the driver also has to react to other events triggered by its partner on the bus. In our case, since we’re developing a master driver, it needs to be sensitive to toggles on signals driven by the slave. One such requirement is that a master is supposed to keep the control signals stable until the slave acknowledges the transfer. This is signaled by raising the ACK_I signal.

We need to write a test where, aside from executing an item on the sequencer, we also model the behavior of the slave:

module master_driver_unit_test;

  `SVTEST(transfer_held_until_ack)
    sequence_item item = new("item");
    intf.ACK_I <= 0;

    fork
      sequencer.execute_item(item);
    join_none

    repeat (3) begin
      @(posedge clk);
      `FAIL_UNLESS(intf.CYC_O === 1)
      `FAIL_UNLESS(intf.STB_O === 1)
    end

    intf.ACK_I <= 1;
    @(posedge clk);
    `FAIL_UNLESS(intf.CYC_O === 1)
    `FAIL_UNLESS(intf.STB_O === 1)
  `SVTEST_END

  // ...
endmodule

We basically model all collaborators of the driver, where some might communicate with it via method calls (like the sequencer) and some might communicate with it via signal toggles on the interface (like a connected slave).

This last test would suggest that we should update the drive() task with the following code:

class master_driver extends uvm_driver #(sequence_item);
  virtual protected task drive();
    // ...

    @(posedge intf.CLK_I iff intf.ACK_I);
  endtask

  // ...
endclass

While this is what we would need to do, the test still passes without this line. This is because, once the driver starts driving an item, it won’t touch the signals anymore until it gets another item. The extra wait statement would cause the driver to mark an item as finished at a later time. This is hints that it isn’t enough to just check signal toggles. It’s also important that the driver makes calls to item_done() at the right time. This isn’t something that we can check easily check with uvm_sequencer. We’d need to capture information about method calls from the driver to the sequencer.

We could choose to implement such extra testing functionality in a sub-class of uvm_sequencer. We could capture the number of times item_done() (or any other method) got called during a test. This wouldn’t be a problem to implement, but have you ever taken a look at uvm_sequencer? That class is massive. The functionality is shared with two of its subclasses, uvm_sequencer_base and uvm_sequencer_param_base. Most of the stuff a sequencer does (prioritization, locking, etc.) we don’t even need. Debugging anything would be a nightmare. Interrupting an item in the middle of it being driven (due to a unit test finishing early) is also going to cause fatal errors to be issued (e.g. “get_next_item() called twice without a call to item_done() in between”).

A better alternative would be to start from scratch with a lightweight class that mimics the uvm_sequencer functionality we need and provides us with test diagnostic information. When talking about test doubles, I like to use the same terminology as outlined in this article. I can’t really decide whether what we want to create should be called a fake (since we’ll implement working functionality, but only a limited part of what uvm_sequencer can do) or a stub (since we want to collect information about method calls). I chose ‘stub’, for now, based on gut feeling.

Our stub has to be parameterizable, just like uvm_sequencer, to be able to interact with any driver. Just like a sequencer, it’s going to have a seq_item_export for the driver to connect to:

class sequencer_stub #(type REQ = uvm_sequence_item, type RSP = REQ)
    extends uvm_component;

  uvm_seq_item_pull_imp #(REQ, RSP, this_type) seq_item_export;

  // ...
endclass

Since in every test we always forked out execute_item(…), we’ll provide a function that just schedules an item to be picked up by the driver at its convenience:

class sequencer_stub #(type REQ = uvm_sequence_item, type RSP = REQ)
    extends uvm_component;

  extern virtual function void add_item(REQ item);

  // ...
endclass

Requests (items from the sequencer to the driver) and responses (items from the driver to the sequencer) will be stored in FIFOs:

class sequencer_stub #(type REQ = uvm_sequence_item, type RSP = REQ)
    extends uvm_component;

  protected uvm_tlm_fifo #(REQ) reqs;
  protected uvm_tlm_fifo #(RSP) rsps;

  // ...
endclass

Last, but not least, the sequencer methods (get_next_item(), item_done(…), etc.) operate on these FIFOs to emulate the behavior of a real sequencer. For example, get_next_item() peeks inside the request FIFO:

task sequencer_stub::get_next_item(output REQ t);
  reqs.peek(t);
endtask

The item_done(…) function pops a request from the FIFO, because it’s been handled:

function void sequencer_stub::item_done(RSP item = null);
  REQ t;
  void'(reqs.try_get(t));

  // ...
endfunction

At the same time, we can also count the number of times a certain method was called. This information could be useful to check that the driver requests items at defined intervals:

function bit sequencer_stub::has_do_available();
  num_has_do_available_calls++;
  return !reqs.is_empty();
endfunction

Last, but not least, we’ll need to ensure that all unit tests start from the same state. This means that there aren’t any items queued from previous unit tests and that the diagnostic information has been cleared. A flush() method (similar to uvm_tlm_fifo::flush()) should be called in teardown() to enforce this rule:

function void sequencer_stub::flush();
  reqs.flush();
  rsps.flush();
  num_get_next_item_calls = 0;
  num_try_next_item_calls = 0;
  // ...
endfunction