Covergroup Arguments, Arrays and Reuse

Write one covergroup and reuse it: arguments, arrays of instances, classes, subclasses, class parameters and packages.

You Will Be Able To

  • Pass value and ref arguments to a covergroup and say when each is read.
  • Build an array of covergroup instances, one per port, each with its own arguments.
  • Put several covergroups in a class, reach them by hierarchical name, and override one in a subclass.
  • Share a covergroup through a package or shape it with class parameters.
Lesson
C19
Time
40 min
Runs on
Coverage build
Check
4 questions

A switch had four ports, and the testbench had four copies of the same covergroup, one per port, each edited by hand. A bin range was fixed in three copies and forgotten in the fourth. The port with the stale copy read 100% while it never sent its longest packets. One covergroup with arguments, built four times, would have had one range to fix.

One Covergroup Type, One Instance per PortThe example below. Arrows show construction: each new call gives an instance its own ref variable and its own value arguments.
  • Model
  • Result
  • Control
  • Data
One covergroup type, one instance per portThe example below. Arrows show construction: each `new` call gives an instance its own `ref` variable and its own value arguments. model covergroup port_cg (ref len, max_len, w) model cov[0] len[0], max 2, weight 1 model cov[1] len[1], max 4, weight 3 result port_cg::get_coverage() weighted over instances new(len[0], 2, 1)new(len[1], 4, 3)
  1. model covergroup port_cg(ref len, max_len, w)
    • new(len[0], 2, 1) → cov[0]
    • new(len[1], 4, 3) → cov[1]
  2. model cov[0]len[0], max 2, weight 1
    • port_cg::get_coverage()
  3. model cov[1]len[1], max 4, weight 3
    • port_cg::get_coverage()
  4. result port_cg::get_coverage()weighted over instances
  1. Build per port

    Each instance gets its own bins: 2 for port 0, 4 for port 1.

  2. Read per port or per type

    Each instance reports its own number. The type number weights them by their option.weight.

Read the diagram as text
  • covergroup port_cg: (ref len, max_len, w)
  • cov[0]: len[0], max 2, weight 1
  • cov[1]: len[1], max 4, weight 3
  • port_cg::get_coverage(): weighted over instances
  • covergroup port_cg → cov[0]: new(len[0], 2, 1)
  • covergroup port_cg → cov[1]: new(len[1], 4, 3)
  • cov[0] → port_cg::get_coverage()
  • cov[1] → port_cg::get_coverage()

One definition to review and fix; as many instances as there are ports.

Value Arguments

A covergroup can take arguments, like a task: covergroup cg (int max_len);. Value arguments are evaluated once, when new runs, so each instance keeps the values it was built with (IEEE 1800-2023 19.3). They can shape bins, guards and options.

ref Arguments

A ref argument names a variable, and the covergroup reads that variable's current value at each sample. It is how one covergroup type samples different signals: each instance gets its own variable (19.3).

Value argument

covergroup cg (bit [1:0] v);
  coverpoint v;
endgroup

Frozen at new: every sample sees the value passed in.

ref argument

covergroup cg (ref bit [1:0] v);
  coverpoint v;
endgroup

Read at each sample: the coverpoint follows the variable.

A ref argument is read-only inside the covergroup. Do not pass an automatic variable: its lifetime can end before the covergroup is done (SVA-FC 26.11).

An Argument in an Option

Options can use value arguments: option.weight = w; gives each instance its own weight (19.4, 19.7). In type coverage, instances are weighted by their option.weight.

Option set from an argumentStandardCoverage build (measured)
option.weight = w; with instances of weight 1 and 3used: the type number weights themused: 87.50% in the check below
option.at_least = n; in a coverpoint, n = 2each bin needs 2 hitsignored: one hit covers a bin
option.at_least = 2; with a constanteach bin needs 2 hitsused

The second row is a departure (scenario cov-053 in docs/sva-standard-traces/CF.md). With a constant, at_least works.

An Argument in a Bin Range

The standard lets a value argument bound a bin range: bins b[] = {[0:mx]}; builds one bin per value up to the instance's mx (19.5.1, 19.3).

covergroup cg(int mx); coverpoint v { bins b[] = {[0:mx]}; }, new(3), samples 0, 2, 5StandardCoverage build (measured)
binsb[0] to b[3]: 4 bins, 2 hit: 50.00%compile error: "Non-constant expression in array bins range"

Standard behaviour, not run on this build. Scenario cov-054 in docs/sva-standard-traces/CF.md.

Arrays of Covergroup Instances

Covergroup handles can form an array, port_cg cov[4];, each element built with its own new. A loop builds and samples them. Each instance keeps its own bins and counts.

Several Covergroups in a Class

A class can hold several embedded covergroups, each with its own sampling (19.4). Each is constructed in the class constructor; an embedded covergroup that is never constructed samples nothing.

Two covergroups, one class
class mon;
  bit [1:0] k;  bit [3:0] len;
  covergroup cg_kind; coverpoint k { bins b[] = {[0:3]}; } endgroup
  covergroup cg_len;  coverpoint len { bins one = {1}; bins many = {[2:8]}; } endgroup
  function new(); cg_kind = new; cg_len = new; endfunction
endclass

Reaching an Embedded Covergroup by Name

Outside the class, an embedded covergroup is reached through the object: m.cg_len.get_inst_coverage(), m.cg_len.sample(), m.cg_len.option.comment (19.4, SVA-FC 26.14). The covergroup variable itself must not be assigned outside the class constructor.

Overriding a Covergroup in a Subclass

A subclass can declare a covergroup with the same name. Like any same-named class member, it hides the base one. Code in the subclass, or reached through a subclass handle, uses the new covergroup. Code in the base class still uses the base covergroup.

Who samples pcovCovergroup that counts
a subclass method, or c.pcov with a subclass handle cthe subclass covergroup
a base-class method such as observe()the base covergroup

Hiding is a property of names, not of objects. Both covergroups exist in a subclass object.

IEEE 1800-2023 adds real covergroup inheritance: covergroup extends pcov; ... endgroup in the subclass. It replaces the base instance everywhere, keeps its coverpoints and options, and overrides those it redefines (19.4.1).

Base observe() samples pcov; read through the subclass objectStandardCoverage build (measured)
subclass declares covergroup pcov (hiding)base 25.00%, subclass 0.00%the same
subclass declares covergroup extends pcov (1800-2023)the derived covergroup counts: 100.00%compile error: "Unsupported: covergroup inheritance (extends)"

The second row is standard behaviour, not run on this build. Scenario cov-058-extends in docs/sva-standard-traces/CF.md.

Class Parameters Shape the Bins

In a parameterised class, the covergroup can use the class parameters in its bins. Each specialisation gets its own bins, fixed at compile time (SVA-FC 26.17).

Covergroups in a Package

A covergroup declared in a package can be instanced in any module or class that imports it. With with function sample(...) and arguments, it depends on nothing in the place it is used, so one definition serves every agent.

Try It

Port 0 allows lengths 1 and 2 and saw 1: 50%. Port 1 allows 1 to 4 and saw 3 and 4: 50%. The type number weights them 1 and 3, and both are 50%.

Each instance reads its own element of len through its ref argument. Predict the type number if port 0 also sent a length of 2.

RUNVerilator (coverage build) · simulator service
Edit the code, then run it
Expected: port 0: 50.00% port 1: 50.00% type: 50.00%

Check Yourself

Predict the outputPredict the exact output.
module tb;
  bit [3:0] v;
  covergroup cg (int mx);
    coverpoint v { bins b[] = {[0:15]} with (item <= mx); }
  endgroup
  cg lo = new(1), hi = new(3);
  initial begin
    v = 1; lo.sample(); hi.sample();
    $display("%0.2f %0.2f", lo.get_inst_coverage(), hi.get_inst_coverage());
  end
endmodule
ConceptWhen is a covergroup's value argument read?
ConceptA subclass declares covergroup pcov with the same name as the base class's, and the base class method observe() calls pcov.sample(). Which covergroup does observe() sample?
ConceptWhy give each port its own instance of one covergroup type instead of one instance for all ports?

Common Mistakes

Wrong Copy a covergroup once per port and edit each copy.

The copies drift apart, and a fix lands in some of them only.

Fix Write one covergroup with arguments and build one instance per port.

Before
covergroup port0_cg; ... endgroup
covergroup port1_cg; ... endgroup
After
covergroup port_cg (ref bit [3:0] len, input int mx);
  ...
endgroup
port_cg cov[2];

Wrong Expect a subclass covergroup of the same name to be sampled by base-class methods.

Base-class code still names the base covergroup; the subclass one stays empty.

Fix Override the sampling method as well, or use covergroup extends where the tool supports it.

Wrong Bound a bin range by an argument on the coverage build.

The build rejects a non-constant bin range, although the standard allows it.

Fix Write the constant range and filter it: {[0:15]} with (item <= mx).

Wrong Cover a byte with bins b[] = {[0:255]}; and expect 256 bins.

A byte is signed, -128 to 127, so values 128 to 255 take no part (19.5.7): 128 bins. A well-known book makes this slip.

Fix Use bit [7:0] for a value from 0 to 255, or bin the signed range.

Remember

  • Value arguments are read once, at new; ref arguments are read at every sample.
  • Arguments can shape bins, guards and options; the coverage build rejects them in a bin range and ignores them in at_least.
  • Arrays of instances give one covergroup per port, each with its own arguments and numbers.
  • A class can hold several covergroups, reached as obj.cg; a same-named covergroup in a subclass only hides the base one.
  • Class parameters and packages let one covergroup definition serve many agents.

Practice

Report a problem with this page