Add `--coverage-per-instance`

bin/verilator

@@ -377,6 +377,7 @@ detailed descriptions of these arguments.
     --coverage-fsm              Enable FSM state/arc coverage
     --coverage-line             Enable line coverage
     --coverage-max-width <width>   Maximum array depth for coverage
+    --coverage-per-instance     Enable per-instance coverage counters
     --coverage-toggle           Enable toggle coverage
     --coverage-underscore       Enable coverage of _signals
     --coverage-user             Enable SVL user coverage

docs/guide/exe_verilator.rst

@@ -317,6 +317,20 @@ Summary:
    toggle coverage. Defaults to 256, as covering large vectors may greatly
    slow coverage simulations.
 
+.. option:: --coverage-per-instance
+
+   For Verilator-inserted coverage, preserve generated coverage counters and
+   ``.dat`` records per hierarchy instance. This option must be specified when
+   Verilating the model, together with one or more coverage instrumentation
+   options, for example :vlopt:`--coverage`, :vlopt:`--coverage-line`,
+   :vlopt:`--coverage-toggle`, :vlopt:`--coverage-expr`,
+   :vlopt:`--coverage-fsm`, or :vlopt:`--coverage-user`. It may increase
+   generated model size, counter memory, coverage write time, and ``.dat`` file
+   size.
+
+   This does not affect SystemVerilog ``cover``, which uses the IEEE-specified
+   coverage option ``per_instance``.
+
 .. option:: --coverage-toggle
 
    Enables adding signal toggle coverage. See :ref:`Toggle Coverage`.

src/V3EmitCMain.cpp

@@ -157,6 +157,9 @@ private:
 
         if (v3Global.opt.coverage()) {
             puts("// Write coverage data (since Verilated with --coverage)\n");
+            if (v3Global.opt.coveragePerInstance()) {
+                puts("contextp->coveragep()->forcePerInstance(true);\n");
+            }
             puts("contextp->coveragep()->write();\n");
             puts("\n");
         }

src/V3Options.cpp

@@ -1360,6 +1360,7 @@ void V3Options::parseOptsList(FileLine* fl, const string& optdir, int argc,
     DECL_OPTION("-coverage-fsm", OnOff, &m_coverageFsm);
     DECL_OPTION("-coverage-line", OnOff, &m_coverageLine);
     DECL_OPTION("-coverage-max-width", Set, &m_coverageMaxWidth);
+    DECL_OPTION("-coverage-per-instance", OnOff, &m_coveragePerInstance);
     DECL_OPTION("-coverage-toggle", OnOff, &m_coverageToggle);
     DECL_OPTION("-coverage-underscore", OnOff, &m_coverageUnderscore);
     DECL_OPTION("-coverage-user", OnOff, &m_coverageUser);

src/V3Options.h

@@ -228,6 +228,7 @@ private:
     bool m_coverageExpr = false;    // main switch: --coverage-expr
     bool m_coverageFsm = false;     // main switch: --coverage-fsm
     bool m_coverageLine = false;    // main switch: --coverage-block
+    bool m_coveragePerInstance = false;  // main switch: --coverage-per-instance
     bool m_coverageToggle = false;  // main switch: --coverage-toggle
     bool m_coverageUnderscore = false;  // main switch: --coverage-underscore
     bool m_coverageUser = false;    // main switch: --coverage-func
@@ -524,6 +525,7 @@ public:
     bool coverageExpr() const { return m_coverageExpr; }
     bool coverageFsm() const { return m_coverageFsm; }
     bool coverageLine() const { return m_coverageLine; }
+    bool coveragePerInstance() const { return m_coveragePerInstance; }
     bool coverageToggle() const { return m_coverageToggle; }
     bool coverageUnderscore() const { return m_coverageUnderscore; }
     bool coverageUser() const { return m_coverageUser; }

test_regress/t/t_cover_per_instance.out

@@ -0,0 +1,90 @@
+//      // verilator_coverage annotation
+        // DESCRIPTION: Verilator: Coverage per-instance hierarchy for duplicate module instances
+        //
+        // This file ONLY is placed under the Creative Commons Public Domain.
+        // SPDX-FileCopyrightText: 2026 Wilson Snyder
+        // SPDX-License-Identifier: CC0-1.0
+        
+        module child (
+            input clk,
+            input en
+        );
+        `ifdef INLINE_CHILD  //verilator inline_module
+        `else  //verilator no_inline_module
+        `endif
+%000001   reg [3:0] count = 0;
+-000001  point: type=line comment=block hier=tb.dut.u_a
+-000001  point: type=line comment=block hier=tb.dut.u_b
+        
+%000009   always @(posedge clk) begin
+-000009  point: type=line comment=block hier=tb.dut.u_a
+-000009  point: type=line comment=block hier=tb.dut.u_b
+%000008     if (en) begin
+-000004  point: type=branch comment=if hier=tb.dut.u_a
+-000001  point: type=branch comment=if hier=tb.dut.u_b
+-000005  point: type=branch comment=else hier=tb.dut.u_a
+-000008  point: type=branch comment=else hier=tb.dut.u_b
+%000004       count <= count + 1'b1;
+-000004  point: type=branch comment=if hier=tb.dut.u_a
+-000001  point: type=branch comment=if hier=tb.dut.u_b
+%000008     end else begin
+-000005  point: type=branch comment=else hier=tb.dut.u_a
+-000008  point: type=branch comment=else hier=tb.dut.u_b
+%000008       count <= count;
+-000005  point: type=branch comment=else hier=tb.dut.u_a
+-000008  point: type=branch comment=else hier=tb.dut.u_b
+            end
+          end
+        endmodule
+        
+        module t (
+            input clk
+        );
+%000001   reg [3:0] cyc = 0;
+-000001  point: type=line comment=block hier=tb.dut
+        
+          // Over 9 clock edges, u_a.en is true for cyc 0..3, so u_a should report
+          // if coverage of 4, else coverage of 5, and line coverage of 9.
+          child u_a (
+              .clk(clk),
+              .en(cyc < 4)
+          );
+        
+          // u_b.en is true only for cyc 0, so u_b should report if coverage of 1,
+          // else coverage of 8, and line coverage of 9.
+          child u_b (
+              .clk(clk),
+              .en(cyc == 0)
+          );
+        
+%000009   always @(posedge clk) begin
+-000009  point: type=line comment=block hier=tb.dut
+%000009     cyc <= cyc + 1'b1;
+-000009  point: type=line comment=block hier=tb.dut
+          end
+        endmodule
+        
+        module tb;
+%000001   reg clk = 0;
+-000001  point: type=line comment=block hier=tb
+        
+          t dut (
+              .clk(clk)
+          );
+        
+ 000017   always #1 clk = !clk;
++000017  point: type=line comment=block hier=tb
+        
+%000009   always @(posedge clk) begin
+-000009  point: type=line comment=block hier=tb
+%000008     if (dut.cyc == 8) begin
+-000001  point: type=branch comment=if hier=tb
+-000008  point: type=branch comment=else hier=tb
+%000001       $write("*-* All Finished *-*\n");
+-000001  point: type=branch comment=if hier=tb
+%000001       $finish;
+-000001  point: type=branch comment=if hier=tb
+            end
+          end
+        endmodule
+        

test_regress/t/t_cover_per_instance.v

@@ -0,0 +1,64 @@
+// DESCRIPTION: Verilator: Coverage per-instance hierarchy for duplicate module instances
+//
+// This file ONLY is placed under the Creative Commons Public Domain.
+// SPDX-FileCopyrightText: 2026 Wilson Snyder
+// SPDX-License-Identifier: CC0-1.0
+
+module child (
+    input clk,
+    input en
+);
+`ifdef INLINE_CHILD  //verilator inline_module
+`else  //verilator no_inline_module
+`endif
+  reg [3:0] count = 0;
+
+  always @(posedge clk) begin
+    if (en) begin
+      count <= count + 1'b1;
+    end else begin
+      count <= count;
+    end
+  end
+endmodule
+
+module t (
+    input clk
+);
+  reg [3:0] cyc = 0;
+
+  // Over 9 clock edges, u_a.en is true for cyc 0..3, so u_a should report
+  // if coverage of 4, else coverage of 5, and line coverage of 9.
+  child u_a (
+      .clk(clk),
+      .en(cyc < 4)
+  );
+
+  // u_b.en is true only for cyc 0, so u_b should report if coverage of 1,
+  // else coverage of 8, and line coverage of 9.
+  child u_b (
+      .clk(clk),
+      .en(cyc == 0)
+  );
+
+  always @(posedge clk) begin
+    cyc <= cyc + 1'b1;
+  end
+endmodule
+
+module tb;
+  reg clk = 0;
+
+  t dut (
+      .clk(clk)
+  );
+
+  always #1 clk = !clk;
+
+  always @(posedge clk) begin
+    if (dut.cyc == 8) begin
+      $write("*-* All Finished *-*\n");
+      $finish;
+    end
+  end
+endmodule

test_regress/t/t_cover_per_instance_inline.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+# DESCRIPTION: Verilator: Verilog Test driver/expect definition
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of either the GNU Lesser General Public License Version 3,
+# or the Perl Artistic License Version 2.0.
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+import os
+
+import vltest_bootstrap
+
+test.scenarios('simulator')
+
+test.compile(top_filename="t/t_cover_per_instance.v",
+             v_flags2=["+define+INLINE_CHILD"],
+             verilator_flags2=[
+                 '--binary',
+                 '--coverage-line',
+                 '--coverage-per-instance',
+                 '--top-module',
+                 'tb',
+                 '--timing',
+             ])
+
+test.execute(all_run_flags=[" +verilator+coverage+file+" + test.obj_dir + "/coverage.dat"])
+
+cov = test.obj_dir + "/coverage.dat"
+
+test.run(cmd=[
+    os.environ["VERILATOR_ROOT"] + "/bin/verilator_coverage",
+    "--annotate-points",
+    "--annotate",
+    test.obj_dir + "/annotated-points",
+    cov,
+],
+         verilator_run=True)
+
+test.files_identical(test.obj_dir + "/annotated-points/t_cover_per_instance.v",
+                     "t/t_cover_per_instance.out")
+
+test.passes()

test_regress/t/t_cover_per_instance_noinline.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# DESCRIPTION: Verilator: Verilog Test driver/expect definition
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of either the GNU Lesser General Public License Version 3,
+# or the Perl Artistic License Version 2.0.
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+import os
+
+import vltest_bootstrap
+
+test.scenarios('simulator')
+
+test.compile(top_filename="t/t_cover_per_instance.v",
+             verilator_flags2=[
+                 '--binary',
+                 '--coverage-line',
+                 '--coverage-per-instance',
+                 '--top-module',
+                 'tb',
+                 '--timing',
+             ])
+
+test.execute(all_run_flags=[" +verilator+coverage+file+" + test.obj_dir + "/coverage.dat"])
+
+cov = test.obj_dir + "/coverage.dat"
+
+test.run(cmd=[
+    os.environ["VERILATOR_ROOT"] + "/bin/verilator_coverage",
+    "--annotate-points",
+    "--annotate",
+    test.obj_dir + "/annotated-points",
+    cov,
+],
+         verilator_run=True)
+
+test.files_identical(test.obj_dir + "/annotated-points/t_cover_per_instance.v",
+                     "t/t_cover_per_instance.out")
+
+test.passes()

test_regress/t/t_cover_per_instance_user.out

@@ -0,0 +1,62 @@
+# SystemC::Coverage-3
+C '
ft/t_cover_per_instance_user.v
l11
n18
tline
pagev_line/child
oblock
S11
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l11
n18
tline
pagev_line/child
oblock
S11
htb.wrap_b.dut_b' 1
+C '
ft/t_cover_per_instance_user.v
l11
n7
ttoggle
pagev_toggle/child
oobserved:0->1
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l11
n7
ttoggle
pagev_toggle/child
oobserved:0->1
htb.wrap_b.dut_b' 1
+C '
ft/t_cover_per_instance_user.v
l11
n7
ttoggle
pagev_toggle/child
oobserved:1->0
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l11
n7
ttoggle
pagev_toggle/child
oobserved:1->0
htb.wrap_b.dut_b' 1
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[0]:0->1
htb.dut_a' 2
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[0]:0->1
htb.wrap_b.dut_b' 1
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[0]:1->0
htb.dut_a' 2
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[0]:1->0
htb.wrap_b.dut_b' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[1]:0->1
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[1]:0->1
htb.wrap_b.dut_b' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[1]:1->0
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[1]:1->0
htb.wrap_b.dut_b' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[2]:0->1
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[2]:0->1
htb.wrap_b.dut_b' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[2]:1->0
htb.dut_a' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[2]:1->0
htb.wrap_b.dut_b' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[3]:0->1
htb.dut_a' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[3]:0->1
htb.wrap_b.dut_b' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[3]:1->0
htb.dut_a' 0
+C '
ft/t_cover_per_instance_user.v
l12
n13
ttoggle
pagev_toggle/child
ocount[3]:1->0
htb.wrap_b.dut_b' 0
+C '
ft/t_cover_per_instance_user.v
l12
n21
tline
pagev_line/child
oblock
S12
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l12
n21
tline
pagev_line/child
oblock
S12
htb.wrap_b.dut_b' 1
+C '
ft/t_cover_per_instance_user.v
l15
n5
tuser
pagev_user/child
osame_stmt
S15
htb.dut_a.same_stmt' 4
+C '
ft/t_cover_per_instance_user.v
l15
n5
tuser
pagev_user/child
osame_stmt
S15
htb.wrap_b.dut_b.same_stmt' 1
+C '
ft/t_cover_per_instance_user.v
l17
n3
tline
pagev_line/child
oblock
S17-18
htb.dut_a' 9
+C '
ft/t_cover_per_instance_user.v
l17
n3
tline
pagev_line/child
oblock
S17-18
htb.wrap_b.dut_b' 9
+C '
ft/t_cover_per_instance_user.v
l19
n5
tbranch
pagev_branch/child
oif
S19-20
htb.dut_a' 4
+C '
ft/t_cover_per_instance_user.v
l19
n5
tbranch
pagev_branch/child
oif
S19-20
htb.wrap_b.dut_b' 1
+C '
ft/t_cover_per_instance_user.v
l19
n6
tbranch
pagev_branch/child
oelse
S21-22
htb.dut_a' 5
+C '
ft/t_cover_per_instance_user.v
l19
n6
tbranch
pagev_branch/child
oelse
S21-22
htb.wrap_b.dut_b' 8
+C '
ft/t_cover_per_instance_user.v
l28
n11
ttoggle
pagev_toggle/wrap
oclk:0->1
htb.wrap_b' 9
+C '
ft/t_cover_per_instance_user.v
l28
n11
ttoggle
pagev_toggle/wrap
oclk:1->0
htb.wrap_b' 8
+C '
ft/t_cover_per_instance_user.v
l29
n11
ttoggle
pagev_toggle/wrap
oen:0->1
htb.wrap_b' 1
+C '
ft/t_cover_per_instance_user.v
l29
n11
ttoggle
pagev_toggle/wrap
oen:1->0
htb.wrap_b' 1
+C '
ft/t_cover_per_instance_user.v
l38
n13
tline
pagev_line/tb
oblock
S38
htb' 1
+C '
ft/t_cover_per_instance_user.v
l38
n7
ttoggle
pagev_toggle/tb
oclk:0->1
htb' 9
+C '
ft/t_cover_per_instance_user.v
l38
n7
ttoggle
pagev_toggle/tb
oclk:1->0
htb' 8
+C '
ft/t_cover_per_instance_user.v
l39
n13
ttoggle
pagev_toggle/tb
ocyc[0]:0->1
htb' 5
+C '
ft/t_cover_per_instance_user.v
l39
n13
ttoggle
pagev_toggle/tb
ocyc[0]:1->0
htb' 4
+C '
ft/t_cover_per_instance_user.v
l39
n13
ttoggle
pagev_toggle/tb
ocyc[1]:0->1
htb' 2
+C '
ft/t_cover_per_instance_user.v
l39
n13
ttoggle
pagev_toggle/tb
ocyc[1]:1->0
htb' 2
+C '
ft/t_cover_per_instance_user.v
l39
n13
ttoggle
pagev_toggle/tb
ocyc[2]:0->1
htb' 1
+C '
ft/t_cover_per_instance_user.v
l39
n13
ttoggle
pagev_toggle/tb
ocyc[2]:1->0
htb' 1
+C '
ft/t_cover_per_instance_user.v
l39
n13
ttoggle
pagev_toggle/tb
ocyc[3]:0->1
htb' 1
+C '
ft/t_cover_per_instance_user.v
l39
n13
ttoggle
pagev_toggle/tb
ocyc[3]:1->0
htb' 0
+C '
ft/t_cover_per_instance_user.v
l39
n19
tline
pagev_line/tb
oblock
S39
htb' 1
+C '
ft/t_cover_per_instance_user.v
l53
n3
tline
pagev_line/tb
oblock
S53-54
htb' 9
+C '
ft/t_cover_per_instance_user.v
l57
n3
tline
pagev_line/tb
oblock
S57
htb' 17
+C '
ft/t_cover_per_instance_user.v
l59
n3
tline
pagev_line/tb
oblock
S59
htb' 9
+C '
ft/t_cover_per_instance_user.v
l60
n5
tbranch
pagev_branch/tb
oif
S60-62
htb' 1
+C '
ft/t_cover_per_instance_user.v
l60
n6
tbranch
pagev_branch/tb
oelse
htb' 8
+C '
ft/t_cover_per_instance_user.v
l8
n11
ttoggle
pagev_toggle/child
oclk:0->1
htb.dut_a' 9
+C '
ft/t_cover_per_instance_user.v
l8
n11
ttoggle
pagev_toggle/child
oclk:0->1
htb.wrap_b.dut_b' 9
+C '
ft/t_cover_per_instance_user.v
l8
n11
ttoggle
pagev_toggle/child
oclk:1->0
htb.dut_a' 8
+C '
ft/t_cover_per_instance_user.v
l8
n11
ttoggle
pagev_toggle/child
oclk:1->0
htb.wrap_b.dut_b' 8
+C '
ft/t_cover_per_instance_user.v
l9
n11
ttoggle
pagev_toggle/child
oen:0->1
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l9
n11
ttoggle
pagev_toggle/child
oen:0->1
htb.wrap_b.dut_b' 1
+C '
ft/t_cover_per_instance_user.v
l9
n11
ttoggle
pagev_toggle/child
oen:1->0
htb.dut_a' 1
+C '
ft/t_cover_per_instance_user.v
l9
n11
ttoggle
pagev_toggle/child
oen:1->0
htb.wrap_b.dut_b' 1

test_regress/t/t_cover_per_instance_user.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# DESCRIPTION: Verilator: Verilog Test driver/expect definition
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of either the GNU Lesser General Public License Version 3,
+# or the Perl Artistic License Version 2.0.
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+import vltest_bootstrap
+
+test.scenarios('simulator')
+
+test.compile(verilator_flags2=[
+    '--binary',
+    '--assert',
+    '--coverage-line',
+    '--coverage-toggle',
+    '--coverage-user',
+    '--coverage-per-instance',
+    '--top-module',
+    'tb',
+    '--timing',
+])
+
+test.execute(all_run_flags=[" +verilator+coverage+file+" + test.obj_dir + "/coverage.dat"])
+
+test.files_identical(test.obj_dir + "/coverage.dat", "t/" + test.name + ".out")
+
+test.passes()

test_regress/t/t_cover_per_instance_user.v

@@ -0,0 +1,65 @@
+// DESCRIPTION: Verilator: User coverage per-instance records for the same statement
+//
+// This file ONLY is placed under the Creative Commons Public Domain.
+// SPDX-FileCopyrightText: 2026 Wilson Snyder
+// SPDX-License-Identifier: CC0-1.0
+
+module child (
+    input clk,
+    input en
+);
+  reg observed = 1'b0;
+  reg [3:0] count = 0;
+
+  same_stmt:
+    cover property (@(posedge clk) en);
+
+  always @(posedge clk) begin
+    observed <= en;
+    if (en) begin
+      count <= count + 1'b1;
+    end else begin
+      count <= count;
+    end
+  end
+endmodule
+
+module wrap (
+    input clk,
+    input en
+);
+  child dut_b (
+      .clk(clk),
+      .en(en)
+  );
+endmodule
+
+module tb;
+  reg clk = 0;
+  reg [3:0] cyc = 0;
+
+  // Same user cover statement at two different hierarchy points.
+  // Expected with per_instance: dut_a count=4, wrap_b.dut_b count=1.
+  child dut_a (
+      .clk(clk),
+      .en(cyc < 4)
+  );
+
+  wrap wrap_b (
+      .clk(clk),
+      .en(cyc == 0)
+  );
+
+  always @(posedge clk) begin
+    cyc <= cyc + 1'b1;
+  end
+
+  always #1 clk = !clk;
+
+  always @(posedge clk) begin
+    if (cyc == 8) begin
+      $write("*-* All Finished *-*\n");
+      $finish;
+    end
+  end
+endmodule