A proven methodology to hierarchically reuse interface connections from the block to the chip level

UVM Harness Whitepaper

The missing link in interface connectivity.

By David Larson, Director of Corporate Verification verification@synapse-da.com

Revision 1.2 December 7, 2011

Table of Contents
Introduction .................................................................................................................................................. 2 What is a Harness?........................................................................................................................................ 3 Interface Binding ....................................................................................................................................... 3 The Other End ........................................................................................................................................... 4 A Complete Harness.................................................................................................................................. 4 Connecting the Harness ............................................................................................................................ 6 Connecting Harnesses in System Simulations .............................................................................................. 6 Virtual Harnesses ...................................................................................................................................... 7 Advanced Interfaces ..................................................................................................................................... 7 Arrays of Interfaces ................................................................................................................................... 7 Scalable Harnesses .................................................................................................................................... 8 Connecting Harnesses for Arrays of Sub-Modules ................................................................................... 9 Summary ..................................................................................................................................................... 10 Thanks ......................................................................................................................................................... 11

UVM Harness, David Larson

Page 1

Introduction
In every UVM test bench, System Verilog interfaces must be used to connect signals from the RTL to the test environment. For a single block-level test bench, the interface connections are typically made by connecting each signal in an interface to the ports of the DUT, like this:
module top; wire clk, reset_n; my_signals ifc(clk, reset_n); // instantiate the interface switch DUT ( .clk(clk), .reset(reset_n), .data(ifc.data), // connect each signal of the interface to ports on the DUT .status(ifc.status), .port0(ifc.port[0]), .port1(ifc.port[1]), ... ); initial begin uvm_config_db#(virtual my_signals)::set(null, "tb.switch_env0.*", "vif", ifc); end endmodule

This approach is fine for simple, single-use block level test benches... but it falls apart for multi-block test benches for several reasons: 1. The connections are not reusable. You must reconnect each signal on every block to your interfaces in a system test bench. This task becomes more ominous when there are many modules that need to be reconnected and each of those modules has several interfaces and each of those interfaces has many signals. Connecting the interfaces can be a major task. 2. The ports may not be available. In synthesizable netlists, interfaces often arent used to connect the modules together because of tool (or corporate) limitations. Instead, wires are typically used to stitch the modules together. You could try to assign your interface signals to the wires, but it is very difficult to get the directions right and very easy to make a mistake (believe me, Ive tried). You could easily get lost floating on an ocean of tedious signal connections. A better approach is to use a reusable harness. With a harness, the connections made in a block-level test bench can be reused in multi-block test benches. Also, a collection of harnesses can be grouped together into virtual (or system) harnesses that connect system-level environments to yet larger system environments.

UVM Harness, David Larson

Page 2

What is a Harness?
Like a car stereo harness, a UVM harness is a collection of wires (grouped together in interfaces) with at least two ends or connectors to it. One end connects to the module(s) and the other end connects to the UVM environment. The connectors in the harness are written for your module and environment. Once the harness is created, you can then use it in all of your block-level and system-level test benches. All you have to do is snap in the connectors.
Figure 1 - A car stereo harness. A connector on one end snaps into your specific stereo; the other connectors snap into the wiring for your specific car.

Fundamentally, a connector is an interface that is bound to your module. Once the interfaces are bound, you never have to connect that end of the harness again.

Interface Binding
System Verilog allows you to bind (or add) some of your own items to modules from a separate file allowing you to amend the definition of the module. This mechanism is sort of like aspect-oriented programming. It is intended to be used in the test bench to add things like coverage, assertions, monitors, and... interfaces1. When you bind an interface to a module, the compiler acts as if that the interface is instantiated inside the module. This also means that you can access signals and ports as if the context of your code is inside the module as well. So, referring to internal signals and ports from an external file like this is perfectly valid:
bind math_coprocessor_module reg_ifc regIfc(.clk(clk), .reset_n(reset_n), .address(addr), .data(data), .wr(write), .req(request), .ack(ack));

Where the signals clk, reset_n, addr, data, write, request and ack are ports of a module (as seen from the inside of the module) called the math_coprocessor_module2. Notice that all of the interface signals are declared as ports of the interface, which allows you to connect all of the signals in the interface instantiation and bidirectionally when necessary. Also notice that since we are connecting the interface to the port names of the module, the connections are always valid for every instance of this module. Binding the signal interfaces creates one end of the UVM harness. Now we need to create the other end of the harness that connects to the environment...

1 2

See the Verilog LRM IEEE 1800-2009, section 23.11 Binding auxiliary code to scopes or instances System Verilog also allows you to bind to a particular instance of a module, though it is generally best to bind to the module itself, so that the interface instantiations are automatically added to every instance of the module in the hierarchy.

UVM Harness, David Larson

Page 3

The Other End

The other end of the harness is a function that will connect the interfaces to the UVM environment. We do this by adding a set_vifs() function to the module. Unfortunately System Verilog does not allow you to directly bind functions to a module. You can, however, put that function in a dummy interface and then bind that interface to the module (well go over other uses of this dummy interface later):
interface math_coprocesser_harness(); // the dummy interface function void set_vifs(string path); uvm_config_db#(virtual reg_ifc)::set(null, {path,".reg_agent.*"}3, "vif", math_coprocessor_module.regIfc);4 uvm_config_db#(virtual cmd_ifc)::set(null, {path,".cmd_agent.*"}, "vif", math_coprocessor_module.cmdIfc); uvm_config_db#(virtual usb_ifc)::set(null, {path,".usb_agent.*"}, "vif", math_coprocessor_module.usbIfc); ... endfunction endinterface bind math_coprocessor_module math_coprocessor_harness harness(); // bind the interface to the module

Notice that each of the calls to the uvm_config_db pass in one of the bound interfaces, and each of the interfaces refer to the module (this is called upwards name referencing5). Upwards name referencing is necessary because the compiler knows nothing about the other interfaces within the context of the math_coprocesor_harness interface. Adding the math_coprocessor_module prefix tells the compiler where to look for these interfaces.

A Complete Harness
A complete harness file defines the dummy interface and binds all of the interfaces. The following is what a complete harness file could look like:
interface math_coprocessor_harness(); function void set_vifs (string path); uvm_config_db#(virtual reg_ifc)::set(null, {path,".reg_agent.*"}, "vif", math_coprocessor_module.regIfc); uvm_config_db#(virtual cmd_ifc)::set(null, {path,".cmd_agent.*"}, "vif", math_coprocessor_module.cmdIfc); uvm_config_db#(virtual usb_ifc)::set(null, {path,".usb_agent.*"}, "vif", math_coprocessor_module.usbIfc); uvm_config_db#(virtual mem_ifc)::set(null, {path,".mem_agent[0].*"}, "vif", math_coprocessor_module.cache.mem_ifc0); uvm_config_db#(virtual mem_ifc)::set(null, {path,".mem_agent[1].*"}, "vif", math_coprocessor_module.txx.cmd.memory.mem_ifc0);

It is easier to pass in the reference to the environment as the first argument and let UVM figure out the full path: uvm_config_db#(virtual reg_ifc)::set(env, "reg_agent.*", "vif", math_coprocessor_module.regIfc); But because set_vifs() has to be called in the build phase, the sub-envs will not be instantiated by this point preventing hierarchical assignments. 4 This document follows Accelleras recommendation of assigning the interfaces using the configuration DB. An alternative approach is to use the convention used in OVM, where interfaces are assigned directly using assign_vi(). It is worth comparing the two approaches see the OVM Harness Whitepaper. 5 See the Verilog LRM IEEE 1800-2009, section 23.8 Upwards Name Referencing

UVM Harness, David Larson

Page 4

uvm_config_db#(virtual mem_ifc)::set(null, {path,".mem_agent[2].*"}, "vif", math_coprocessor_module.rxx.cmd.memory.mem_ifc0); endfunction endinterface bind math_coprocessor_module reg_ifc reg_ifc0(.clk(clk), .reset_n(reset_n), .address(addr), .data(data), .wr(wr), .req(request), .ack(ack)); bind math_coprocessor_module cmd_ifc cmd_ifc0(.clk(clk), .reset_n(reset_n), .cmd(command), .valid(valid)); bind math_coprocessor_module usb_ifc usb_ifc0(.clk(clk), .reset_n(reset_n), .tx(tx), .rx(rx) ); bind memory_module mem_ifc mem_ifc0(.clk(clk), .reset_n(reset_n), .wr(write), .data(data), .addr(address), .req(request) ); bind math_coprocessor_module math_coprocessor_harness harness(); // adds the set_vifs function

This harness binds to two different modules, the math_coprocessor_module and the memory_module. There are three instantiations of the memory_module in the DUT so we grab each of the interfaces that were automatically instantiated for us and assign them to our mem_agents in the environment. Note that you could optionally place the interfaces inside the dummy interface and only bind the harness. The advantage of placing them inside the harness interface is that the interfaces can automatically scale to module parameters. See the Scalable Harnesses section below for more information.
interface math_coprocessor_harness(); // have to use upwards name referencing for every signal reg_ifc regIfc(.clk(math_coprocessor_module.clk), .reset_n(math_coprocessor_module.reset_n), .address(math_coprocessor_module.addr), .data(math_coprocessor_module.data), .wr(math_coprocessor_module.wr), .req(math_coprocessor_module.request), .ack(math_coprocessor_module.ack)); cmd_ifc cmdIfc(.clk(math_coprocessor_module.clk), .reset_n(math_coprocessor_module.reset_n), .cmd(math_coprocessor_module.command), .valid(math_coprocessor_module.valid)); usb_ifc usbIfc(.clk(math_coprocessor_module.clk), .reset_n(math_coprocessor_module.reset_n), .tx(math_coprocessor_module.tx), .rx(math_coprocessor_module.rx) ); function void set_vifs (string path); uvm_config_db#(virtual reg_ifc)::set(null, {path,".reg_agent.*"}, "vif", regIfc); // no need for upwards name referencing here uvm_config_db#(virtual cmd_ifc)::set(null, {path,".cmd_agent.*"}, "vif", cmdIfc); uvm_config_db#(virtual usb_ifc)::set(null, {path,".usb_agent.*"}, "vif", usbIfc); uvm_config_db#(virtual mem_ifc)::set(null, {path,".mem_agent[0].*"}, "vif", math_coprocessor_module.cache.mem_ifc0); uvm_config_db#(virtual mem_ifc)::set(null, {path,".mem_agent[1].*"}, "vif", math_coprocessor_module.txx.cmd.memory.mem_ifc0); uvm_config_db#(virtual mem_ifc)::set(null, {path,".mem_agent[2].*"}, "vif", math_coprocessor_module.rxx.cmd.memory.mem_ifc0); endfunction endinterface

UVM Harness, David Larson

Page 5

bind memory_module mem_ifc mem_ifc0(.clk(clk), .reset_n(reset_n), .wr(write), .data(data), .addr(address), .req(request) ); bind math_coprocessor_module math_coprocessor_harness harness(); // only one bind

There are two minor disadvantages to this alternate approach though: 1. Upwards name referencing has to be used for the signals connections to internal interfaces. 2. Only interfaces that are to be bound to the DUT can be placed in the dummy interface. All of the other ones (if any) have to remain outside (like the memory_module in our example).

Connecting the Harness

Okay, great... now we have a harness. Now all you have to do is one wonderful little step to connect the entire block to the environment. In your test case (or preferably in your intermediate-base test class or test bench class), connect the harness to the environment like this:
function void build_phase(uvm_phase phase); super.build_phase(phase); ... env = math_coprocessor_env::type_id::create("env", this); top_module.dut_inst.harness.set_vifs(env.get_full_name()); // this connects the whole environment! ... endfunction

Do NOT connect the harness in your block env! If you do, then your env will not be reusable as a sub-env in larger system simulations because the path to the harness will be invalid.

Connecting Harnesses in System Simulations

Now we are ready to look at how to connect system-level environments that use the sub-environments created earlier. This is where it gets exciting. If you have created a harness for each of the sub-envs, then connecting them all up is trivial. Each of the sub-envs are connected with one line:
function void build_phase(uvm_phase phase); ... env = math_coprocessor_env::type_id::create("env", this); top_module.chip_inst.math_coprocessor.harness.set_vifs({env.get_full_name(), ".math_env0); // connect the entire math environment! top_module.chip_inst.memory_cache.harness.set_vifs({env.get_full_name(), ".cache_env0); // connect the entire cache environment! top_module.chip_inst.arbiter.harness.set_vifs({env.get_full_name(), ".arb_env0); // connect the entire arbiter environment! ... endfunction

Or, better yet, create a virtual harness so these harness connections can be reused as well...

UVM Harness, David Larson

Page 6

Virtual Harnesses
A virtual harness is a collection of harnesses or other virtual harnesses and may contain additional interface connections. It is used to connect sub-environments in a system-level environment to submodules. Furthermore, virtual harness can be reused hierarchically in still larger system test benches.
interface chip_virtual_harness (); function void set_vifs(string path); // connect the sub-harnesses using upwards name referencing chip_module.math.harness.set_vifs({path, ".math_env"}); chip_module.regs.harness.set_vifs({path, ".regs_env"}); chip_module.sys.harness.set_vifs({path, ".sys_env"}); // ... others ... // connect agents used in this environment (if any) uvm_config_db#(virtual jtag_ifc)::set(null, {path,".jtag_agent.*"}, "vif", chip_module.jtagIfc); // ... others ... endfunction endinterface bind chip_module jtag_ifc jtagIfc(.clk(tck), .reset(trst), .data_in(tdi), .data_out(tdo), .test_mode_select(tms)); bind chip_module chip_virtual_harness harness();

Notice that we use upwards name referencing when connecting the sub-harnesses to the subenvironments. That allows the virtual harness to be reused in larger test benches since the path to the sub-harnesses are still correct with respect to the definition of the module. Now in the test, you only have to connect the virtual harness to connect all the signals for this block and all sub-blocks:
top.dxx.chip.harness.set_vifs(env.get_full_name()); // BAM! Hierarchically connect everything!

Advanced Interfaces
The following sections handle special cases that you will likely run into.

Arrays of Interfaces
Some modules need to have an array of interfaces (like a switch or top-level register programming modules). These pose an interesting challenge, since System Verilog does not allow you to loop over static constructs:
reg_ifc regIfc[`RegDevs-1:0]6 ( .clk(RegTopModule.SysClk), .reset_n(RegTopModule.SysReset_n), .rdAddr(RegTopModule.RegRdAddr), .rdData(RegTopModule.RegRdData),
6

See the Verilog LRM IEEE 1800-2009, section 23.3.3.5 Unpacked array ports and arrays of instances for the port connections rules used here. Special care is needed to make sure that signals are spread across the ports correctly, using the rules spelled out in the LRM. In your environment, you may need to change the order to LSB:MSB.

UVM Harness, David Larson

Page 7

.rd(RegTopModule.RegRd), .rdDataValid(RegTopModule.RegRdDataValid), .wrAddr(RegTopModule.RegWrAddr), .wrData(RegTopModule.RegWrData), .wr(RegTopModule.RegWr) ); function void set_vifs(string path); foreach (regIfc[i]) // NO! This is illegal! uvm_config_db#(virtual reg_ifc)::set(null, {path,".reg_a[",i,"]"}}, "vif", regIfc[i]); endfunction

The good news is that SV does allow you to loop over virtual interfaces. So, if want to go that route then we have to take an extra step and assign the interfaces to virtual interfaces before looping over them. Fortunately, this extra step is fairly painless:
reg_ifc regIfc[`RegDevs-1:0] ( .clk(RegTopModule.SysClk), .reset_n(RegTopModule.SysReset_n), .rdAddr(RegTopModule.RegRdAddr), .rdData(RegTopModule.RegRdData), .rd(RegTopModule.RegRd), .rdDataValid(RegTopModule.RegRdDataValid), .wrAddr(RegTopModule.RegWrAddr), .wrData(RegTopModule.RegWrData), .wr(RegTopModule.RegWr) ); virtual interface reg_ifc vifc[`RegDevs]; // extra vif for looping initial begin vifc = regIfc[0:NUM_CLIENTS-1]; // assign the entire array in one step!7 end function void set_vifs(reg_top_env env); foreach (vifc[i]) // loop over the virtual interface uvm_config_db#(virtual reg_ifc)::set(null, {path,".reg_a[",i,"]"}}, "vif", vifc[i]); endfunction

Scalable Harnesses
It is not uncommon for modules to be parameterized... but what if one or more of those parameters affect your interfaces? A parameter can affect how many interfaces to instantiate, signal bus widths or other behavior. So, how can a harness scale to parameter settings? The trick is to parameterize your harness and then when you instantiate and bind your harness you pass in the module parameters to your harness. This is what the above register top harness looks like parameterized (notice that the instantiation of the reg_ifc is inside the reg_harness):
interface reg_harness #(NUM_CLIENTS = 5); reg_ifc regIfc[NUM_CLIENTS-1:0] ( .clk(RegTopModule.SysClk),
7

For your environment, you may need to assign the interfaces in MSB:LSB order experiment with it. Also see footnote Error! Bookmark not defined..

UVM Harness, David Larson

Page 8

.reset_n(RegTopModule.SysReset_n), .rdAddr(RegTopModule.RegRdAddr), .rdData(RegTopModule.RegRdData), .rd(RegTopModule.RegRd), .rdDataValid(RegTopModule.RegRdDataValid), .wrAddr(RegTopModule.RegWrAddr), .wrData(RegTopModule.RegWrData), .wr(RegTopModule.RegWr) ); virtual interface reg_ifc vifc[NUM_CLIENTS]; initial begin vifc = regIfc[0:NUM_CLIENTS-1]; end function void set_vifs(string path); foreach (vifc[i]) uvm_config_db#(virtual reg_ifc)::set(null, {path,".reg_a[",i,"]"}, "vif", vifc[i]); endfunction endinterface bind RegTopModule reg_top_harness #(.NUM_CLIENTS(NUM_CLIENTS)) harness();

Now, when a RegTopModule is instantiated, a harness is also automatically instantiated with the correct settings. The harness self-adjusts to conform to each instantiation of the module.

Connecting Harnesses for Arrays of Sub-Modules

Often there are a variable number of sub-modules instantiated within a design. Each one of those submodules has a harness (created earlier) that needs to be connected within a larger virtual harness. You may be tempted to assign each of the harness interfaces to an array of local virtual interfaces, similar to the approach we used earlier:
interface chip_harness; virtual interface memory_harness memory_harnesses[NUM_MEMORIES]; // the compiler could have a problem with this, see below for (genvar i = 0; i < NUM_MEMORIES; i++) begin initial begin memory_harnesses[i] = chip_module.mem[i].harness; end end function void set_vifs(string path); chip_module.regTop.harness.set_vifs(path, ".regTopEnv"}); chip_module.ALU.harness.set_vifs(path, ".aluEnv"}); .... foreach (chip_harnesses[i]) begin chip_harnesses[i].set_vifs({path,".memEnv[",i,"]"}); end endfunction endinterface bind chip_module chip_harness harness();

This may not work for you because some simulators have a problem with dealing with more than one harness of the same type that uses upwards name referencing. (And the compiler will give you a very

UVM Harness, David Larson

Page 9

confusing error message to boot.) So we cant assign an array of harnesses to virtual interfaces, we have to do something different. The solution is to use genvar to create a series of initial blocks that will connect the arrays of submodules directly. The trick is to block those connections until the connect function is called and the env reference is ready:
interface chip_harness; mailbox mb = new(); // see below for why we use a mailbox vs. an event here genvar i; for (i = 0; i < NUM_MEMORIES; i++) begin initial begin chip_env env; mb.peek(env); // block until env is available. See below for why we use peek chip_module.mem[i].harness.set_vifs({path,".memEnv[",i,"]"}); end end function void set_vifs(string path); chip_module.regTop.harness.set_vifs(path, ".regTopEnv"}); chip_module.ALU.harness.set_vifs(path, ".aluEnv"}); .... mb.try_put(env); // see below for why we use try_put() instead of put() endfunction endinterface bind chip_module chip_harness harness();

You might be wondering why we use a mailbox instead of an event to block the connections. The reason is because events are triggered on the next delta cycle, while mailboxes are triggered on the current delta cycle. You cannot connect the interfaces in the next delta cycle; the connect phase will already be done and OVM will be chugging away in the run phase with null interface connections! The initial blocks use peek instead of get because get removes the reference from the mailbox, while peek leaves it there so that all the initial blocks get the reference, not just one. peek blocks until the reference is available. In the connect function, we have to use try_put instead of put because SV does not allow you to call a task from within a function (try_put is a function and put is a task). We dont have to worry about the try_put function failing there is no risk of that here.

Summary
With harnesses, the connections made in block test benches can be leveraged in larger test benches. Furthermore, harnesses can be used hierarchically, where harnesses created for system test benches can be reused in larger test benches. In every case, all of the interfaces are connected to the RTL in just one statement. Without harnesses, stitching all of the signals to interfaces in large system simulations can be very tedious and error prone (and almost impossible in some cases). The connections made in small, block level test benches have to be thrown out and cannot be reused. UVM Harness, David Larson Page 10

The harness methodology has been tested and proven to be highly beneficial in large-scale projects, resulting in large productivity gains and virtually eliminates all test bench connectivity problems.

Thanks
I am very thankful to everyone who helped me review and test the harness concept: Andy Iverson at Tektronix Terry Beale at Tektronix Jyotsna Balleda at Synapse Design Anami Justesen at Qlogic

UVM Harness, David Larson

Page 11