Options for Reporting and Checking

Name and annotate instances, ask for overlap warnings and missing-cross lists, and keep per-instance numbers under merging.

You Will Be Able To

  • Name an instance with option.name and describe it with option.comment, in a form every tool reads back.
  • Say what option.detect_overlap and option.cross_num_print_missing do, and that neither changes the number.
  • Use option.get_inst_coverage to keep per-instance numbers under type_option.merge_instances.
Lesson
C24
Time
25 min
Runs on
Coverage build
Check
5 questions

A regression report listed eight covergroup instances, all called port_cg with a tool-made suffix. One was at 40%, and the team had to guess which port it was. Two lines, a name and a comment set when each instance was built, would have said "port 5, the slow port".

InstanceWithout a nameWith option.name and option.comment
p0port_cg_1port0: the slow port
p1port_cg_2port1
.........

Names and comments change only what a report shows; every number stays the same.

Report Options and the Number

Most options in this lesson change what the coverage report shows. Only one of them can change a number a method returns.

Where Each Option ActsArrows show where each option has its effect: on the coverage report, or on the value get_inst_coverage() returns.
  • Neutral
  • Report
  • Result
  • Data
Where each option actsArrows show where each option has its effect: on the coverage report, or on the value `get_inst_coverage()` returns. neutral option.name instance name neutral option.comment free text neutral detect_overlap a warning neutral cross_num_print_missing a list neutral option.get_inst_coverage with merging report Coverage report names, notes, warnings, lists result get_inst_coverage() the value returned
  1. neutral option.nameinstance name
    • Coverage report
  2. neutral option.commentfree text
    • Coverage report
  3. neutral detect_overlapa warning
    • Coverage report
  4. neutral cross_num_print_missinga list
    • Coverage report
  5. report Coverage reportnames, notes, warnings, lists
  6. neutral option.get_inst_coveragewith merging
    • get_inst_coverage()
  7. result get_inst_coverage()the value returned
  1. Report only

    Name, comment, overlap warnings and the missing-product list appear in the report.

  2. A returned number

    Under merge_instances, option.get_inst_coverage decides whether the method returns the instance or the type number.

Read the diagram as text
  • option.name: instance name
  • option.comment: free text
  • detect_overlap: a warning
  • cross_num_print_missing: a list
  • option.get_inst_coverage: with merging
  • Coverage report: names, notes, warnings, lists
  • get_inst_coverage(): the value returned
  • option.name → Coverage report
  • option.comment → Coverage report
  • detect_overlap → Coverage report
  • cross_num_print_missing → Coverage report
  • option.get_inst_coverage → get_inst_coverage()

The sections below take the options one at a time.

option.name

option.name is the instance's name in the coverage database and report. Unset, the tool makes a unique name for each instance (IEEE 1800-2023 19.7). It can be set in the definition, from an argument, or after construction; set_inst_name() (lesson C22) also sets it.

How the name is setStandard (19.7)Coverage build (measured)
not seta unique name per instanceempty for every instance
option.name = nm; in the definition, new("port0")port0empty
c.option.name = "port0"; after newport0port0

The first two rows are standard behaviour, not run correctly on this build. Scenario cov-076 in docs/sva-standard-traces/CG.md.

option.comment

option.comment is a string saved with the instance, coverpoint or cross and printed in the report (19.7). Use it for the "why" a reader needs: which plan row, which port, what a weight of 0 means.

How the comment is setStandardCoverage build (measured)
option.comment = "..."; in the covergroup definitionsaved and read backreads back empty
option.comment in a coverpointsaved for that coverpointignored: "Ignoring unsupported coverage option"
c.option.comment = "..."; after newsaved and read backsaved and read back

The first two rows are standard behaviour, not run correctly on this build. Scenario cov-077 in docs/sva-standard-traces/CG.md.

option.detect_overlap

Bins of a coverpoint may overlap: a value then counts for each bin that holds it. option.detect_overlap = 1; asks the tool to warn when two bins of a coverpoint overlap (19.7), so accidental overlaps are caught. It can be set in the covergroup, as a default, or in a coverpoint.

bins lo = {[0:5]}; bins mid = {[4:9]}; with detect_overlap = 1, sample 4StandardCoverage build (measured)
warningoverlap of lo and mid reportednone: "Ignoring unsupported coverage option: detect_overlap"
number100.00%: 4 covers both bins100.00%

The warning is standard behaviour; the number is the same either way. Scenario cov-078 in docs/sva-standard-traces/CG.md.

option.cross_num_print_missing

option.cross_num_print_missing = N; asks the report to list up to N cross products that were never hit (19.7). The default is 0. It is set on a cross, or in the covergroup as the default for its crosses, and it never changes the number.

option.get_inst_coverage

With type_option.merge_instances = 1, the type number is the union of every instance's bins. A tool need not then keep each instance's own number, so get_inst_coverage() returns the type number unless option.get_inst_coverage = 1 (19.7). The option can only be set in the definition.

merge_instancesoption.get_inst_coveragex.get_inst_coverage() (x hit 1 of 2)type number (x and y together)
11x's own: 50.00%union: 100.00%
10the type number: 100.00%100.00%
0eitherx's own: 50.00%average

Measured on the coverage build; it agrees with the standard.

Try It

Each port hit one bin, so each instance is at 50%. The merged type number is the union of both: 100%.

Names and comments set after construction read back here. Predict the first line with option.get_inst_coverage = 1 removed.

RUNVerilator (coverage build) · simulator service
Edit the code, then run it
Expected: port0 (the slow port): 50.00% port1: 50.00% type: 100.00%

Check Yourself

Predict the outputMerged instances without option.get_inst_coverage. Predict the exact output.
module tb;
  covergroup cg with function sample(bit [1:0] a);
    type_option.merge_instances = 1;
    coverpoint a { bins one = {1}; bins two = {2}; }
  endgroup
  cg x = new, y = new;
  initial begin
    x.sample(1);
    y.sample(2);
    $display("%0.2f%%", x.get_inst_coverage());
  end
endmodule
ConceptWhich of these options can change a value that get_inst_coverage() returns?
ConceptWhat does option.detect_overlap = 1; do in the standard?
ConceptOn the coverage build, where should option.name be set so that it reads back?
ConceptA cross has option.cross_num_print_missing = 5;. What changes?

Common Mistakes

Wrong Leave instances unnamed in a bench with many ports.

The report shows tool-made names, so nobody can tell which port has the hole.

Fix Set option.name for each instance, after construction on the coverage build.

Before
foreach (pc[k]) pc[k] = new;
After
foreach (pc[k]) begin
  pc[k] = new;
  pc[k].option.name = $sformatf("port%0d", k);
end

Wrong Expect detect_overlap to remove an overlap.

It only warns; the overlapping value still counts for both bins.

Fix Fix the ranges once the warning names them.

Wrong Merge instances and read per-port numbers without option.get_inst_coverage = 1.

Every port then returns the merged type number.

Fix Set option.get_inst_coverage = 1 in the definition when you merge.

Remember

  • option.name names an instance (unique by default in the standard); on the coverage build set it after construction.
  • option.comment annotates the report; on the coverage build assign it to the instance after construction.
  • option.detect_overlap warns about overlapping bins; the build ignores it, and overlaps still count twice.
  • option.cross_num_print_missing lists unhit cross products in the report and never changes the number.
  • With merge_instances, option.get_inst_coverage = 1 keeps each instance's own number.

Practice

Report a problem with this page