Commentary on MULTIDRIVEN (#2972).

docs/gen/ex_MULTIDRIVEN_faulty.rst

@@ -0,0 +1,11 @@
+.. comment: generated by t_lint_multidriven_bad
+.. code-block:: sv
+   :linenos:
+   :emphasize-lines: 2,5
+
+      always @(posedge clk) begin
+         out2[7:0] <= d0;  // <--- Warning
+      end
+      always @(negedge clk) begin
+         out2[15:8] <= d0;  // <--- Warning
+      end

docs/gen/ex_MULTIDRIVEN_msg.rst

@@ -0,0 +1,6 @@
+.. comment: generated by t_lint_multidriven_bad
+.. code-block::
+
+   %Warning-MULTIDRIVEN: example.v:1:22 Signal has multiple driving blocks with different clocking: 'out2'
+                         example.v:1:7 ... Location of first driving block
+                         example.v:1:7 ... Location of other driving block

docs/guide/warnings.rst

@@ -803,15 +803,25 @@ List Of Warnings
 
 .. option:: MULTIDRIVEN
 
-   .. TODO better example
+   Warns that the specified signal comes from multiple always blocks each
+   with different clocking. This warning does not look at individual bits
+   (see example below).
 
-   Warns that the specified signal comes from multiple always blocks.  This
-   is often unsupported by synthesis tools, and is considered bad style.
-   It will also cause longer simulation runtimes due to reduced
-   optimizations.
+   This is considered bad style, as the consumer of a given signal may be
+   unaware of the inconsistent clocking, causing clock domain crossing
+   bugs.
+
+   Faulty example:
+
+   .. include:: ../../docs/gen/ex_MULTIDRIVEN_faulty.rst
+
+   Results in:
+
+   .. include:: ../../docs/gen/ex_MULTIDRIVEN_msg.rst
 
    Ignoring this warning will only slow simulations, it will simulate
-   correctly.
+   correctly.  It may however cause longer simulation runtimes due to
+   reduced optimizations.
 
 
 .. option:: MULTITOP

test_regress/driver.pl

@@ -2449,10 +2449,12 @@ sub _lineno_match {
     my $lineno = shift;
     my $lines = shift;
     return 1 if !defined $lines;
-    if ($lines =~ /^(\d+)$/) {
-        return $1 == $lineno;
-    } elsif ($lines =~ /^(\d+)-(\d+)$/) {
-        return $1 <= $lineno && $2 >= $lineno;
+    foreach my $lc (split /,/, $lines) {
+        if ($lc =~ /^(\d+)$/) {
+            return 1 if $1 == $lineno;
+        } elsif ($lc =~ /^(\d+)-(\d+)$/) {
+            return 1 if $1 <= $lineno && $2 >= $lineno;
+        }
     }
     return 0;
 }

test_regress/t/t_lint_multidriven_bad.out

@@ -1,17 +1,17 @@
 %Warning-MULTIDRIVEN: t/t_lint_multidriven_bad.v:21:22: Signal has multiple driving blocks with different clocking: 't.mem'
                       t/t_lint_multidriven_bad.v:27:7: ... Location of first driving block
-   27 |       mem[a0] <= d1;
+   27 |       mem[a0] <= d1;   
       |       ^~~
                       t/t_lint_multidriven_bad.v:24:7: ... Location of other driving block
-   24 |       mem[a0] <= d0;
+   24 |       mem[a0] <= d0;   
       |       ^~~
                       ... For warning description see https://verilator.org/warn/MULTIDRIVEN?v=latest
                       ... Use "/* verilator lint_off MULTIDRIVEN */" and lint_on around source to disable this message.
 %Warning-MULTIDRIVEN: t/t_lint_multidriven_bad.v:19:22: Signal has multiple driving blocks with different clocking: 'out2'
                       t/t_lint_multidriven_bad.v:35:7: ... Location of first driving block
-   35 |       out2[15:8] <= d0;
+   35 |       out2[15:8] <= d0;   
       |       ^~~~
                       t/t_lint_multidriven_bad.v:32:7: ... Location of other driving block
-   32 |       out2[7:0] <= d0;
+   32 |       out2[7:0] <= d0;   
       |       ^~~~
 %Error: Exiting due to

test_regress/t/t_lint_multidriven_bad.pl

@@ -15,5 +15,15 @@ lint(
     expect_filename => $Self->{golden_filename},
     );
 
+extract(
+    in => $Self->{top_filename},
+    out => "../docs/gen/ex_MULTIDRIVEN_faulty.rst",
+    lines => "31-36");
+
+extract(
+    in => $Self->{golden_filename},
+    out => "../docs/gen/ex_MULTIDRIVEN_msg.rst",
+    lines => "10,11,14");
+
 ok(1);
 1;

test_regress/t/t_lint_multidriven_bad.v

@@ -21,18 +21,18 @@ module t (/*AUTOARG*/
    reg [7:0]         mem [4];
 
    always @(posedge clk) begin
-      mem[a0] <= d0;
+      mem[a0] <= d0;  // <--- Warning
    end
    always @(negedge clk) begin
-      mem[a0] <= d1;
+      mem[a0] <= d1;  // <--- Warning
    end
    assign out = {mem[3],mem[2],mem[1],mem[0]};
 
    always @(posedge clk) begin
-      out2[7:0] <= d0;
+      out2[7:0] <= d0;  // <--- Warning
    end
    always @(negedge clk) begin
-      out2[15:8] <= d0;
+      out2[15:8] <= d0;  // <--- Warning
    end
 
 endmodule