Commentary

docs/gen/ex_DIDNOTCONVERGE_faulty.rst

@@ -0,0 +1,6 @@
+.. comment: generated by t_lint_didnotconverge_bad
+.. code-block:: sv
+   :linenos:
+
+      always_comb b = ~a;
+      always_comb a = b;

docs/gen/ex_DIDNOTCONVERGE_msg.rst

@@ -0,0 +1,7 @@
+.. comment: generated by t_lint_didnotconverge_bad
+.. code-block::
+
+   -V{t#,#}+    Vt_lint_didnotconverge_bad___024root___change_request
+   -V{t#,#}+    Vt_lint_didnotconverge_bad___024root___change_request_1
+   -V{t#,#}        CHANGE: t/t_lint_didnotconverge_bad.v:14: a
+   %Error: t/t_lint_didnotconverge_bad.v:7: Verilated model didn't converge

docs/gen/ex_DIDNOTCONVERGE_nodbg_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_lint_didnotconverge_nodbg_bad
+.. code-block::
+
+   %Error: t/t_lint_didnotconverge_bad.v:7: Verilated model didn't converge

docs/gen/ex_STMTDLY_faulty.rst

@@ -0,0 +1,5 @@
+.. comment: generated by t_lint_stmtdly_bad
+.. code-block:: sv
+   :emphasize-lines: 1
+
+         #100 $finish;  //<--- Warning

docs/gen/ex_STMTDLY_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_lint_stmtdly_bad
+.. code-block::
+
+   %Warning-STMTDLY: example.v:1:8 Unsupported: Ignoring delay on this delayed statement.

docs/guide/warnings.rst

@@ -481,39 +481,44 @@ List Of Warnings
 
    Faulty example:
 
-   .. code-block:: sv
+   .. include:: ../../docs/gen/ex_DIDNOTCONVERGE_faulty.rst
 
-         always_comb b = ~a;
-         always_comb a = b
+   Results in at runtime (not when Verilated):
 
-   This code will toggle forever, and thus to prevent an infinite loop, the
-   executable will give the didn't converge error.
+   .. include:: ../../docs/gen/ex_DIDNOTCONVERGE_nodbg_msg.rst
 
-   To debug this, first review any UNOPTFLAT warnings that were ignored.
-   Though typically it is safe to ignore UNOPTFLAT (at a performance cost),
-   at the time of issuing a UNOPTFLAT Verilator did not know if the logic
-   would eventually converge and assumed it would.
+   This is because the signals keep toggling even with out time
+   passing. Thus to prevent an infinite loop, the Verilated executable
+   gives the DIDNOTCONVERGE error.
+
+   To debug this, first review any UNOPT or UNOPTFLAT warnings that were
+   ignored.  Though typically it is safe to ignore UNOPTFLAT (at a
+   performance cost), at the time of issuing a UNOPTFLAT Verilator did not
+   know if the logic would eventually converge and assumed it would.
 
    Next, run Verilator with :vlopt:`--prof-cfuncs -CFLAGS -DVL_DEBUG
    <--prof-cfuncs>`.  Rerun the test.  Now just before the convergence
    error you should see additional output similar to this:
 
-   .. code-block::
+   .. include:: ../../docs/gen/ex_DIDNOTCONVERGE_msg.rst
 
-         CHANGE: filename.v:1: b
-         CHANGE: filename.v:2: a
-
-   This means that signal b and signal a keep changing, inspect the code
-   that modifies these signals.  Note if many signals are getting printed
-   then most likely all of them are oscillating.  It may also be that
-   e.g. "a" may be oscillating, then "a" feeds signal "c" which then is
-   also reported as oscillating.
+   The CHANGE line means that on the given filename and line number that
+   drove a signal, the signal 'a' kept changing. Inspect the code that
+   modifies these signals.  Note if many signals are getting printed then
+   most likely all of them are oscillating.  It may also be that e.g. "a"
+   may be oscillating, then "a" feeds signal "c" which then is also
+   reported as oscillating.
 
    One way DIDNOTCONVERGE may occur is flops are built out of gate
-   primitives.  error. Verilator does not support building flops or latches
-   out of gate primitives, and any such code must change to use behavioral
+   primitives. Verilator does not support building flops or latches out of
+   gate primitives, and any such code must change to use behavioral
    constructs (e.g. always_ff and always_latch).
 
+   Another way DIDNOTCONVERGE may occur is if # delays are used to generate
+   clocks.  Verilator ignores the delays and gives an :option:`ASSIGNDLY`
+   or :option:`STMTDLY` warning.  If these were suppressed, due to the
+   absense of the delay, the code may now oscillate.
+
    Finally, rare, more difficult cases can be debugged like a C++ program;
    either enter :command:`gdb` and use its tracing facilities, or edit the
    generated C++ code to add appropriate prints to see what is going on.
@@ -1183,9 +1188,25 @@ List Of Warnings
 
    Faulty example:
 
-   .. code-block:: sv
+   .. include:: ../../docs/gen/ex_STMTDLY_faulty.rst
 
-         #100 $finish;  //<--- Warning
+   Results in:
+
+   .. include:: ../../docs/gen/ex_STMTDLY_msg.rst
+
+   This is a warning because Verilator does not support delayed statements.
+   It will simply ignore all such delays.  In many cases ignoring a delay
+   might be harmless, but if the delayed statement is, as in this example,
+   used to cause some important action at a later time, it might be an
+   important difference.
+
+   Some possible work arounds:
+
+   * Move the delayed statement into the C++ wrapper file, where the
+     stimulus and clock generation can be done in C++.
+
+   * Convert the statement into a FSM, or other statement that tests
+     against $time.
 
 
 .. option:: SYMRSVDWORD
@@ -1353,7 +1374,9 @@ List Of Warnings
 
    Often UNOPTFLAT is caused by logic that isn't truly circular as viewed by
    synthesis which analyzes interconnection per-bit, but is circular to
-   simulation which analyzes per-bus:
+   simulation which analyzes per-bus.
+
+   Faulty example:
 
    .. code-block:: sv
 
@@ -1466,9 +1489,16 @@ List Of Warnings
    Error that a construct might be legal according to IEEE but is not
    currently supported by Verilator.
 
+   A typical workaround is to recode the construct into a simpler and more
+   common alternative language construct.
+
+   Alternatively, check if the construct is supported by other tools, and
+   if so please consider submitting a github pull request against the
+   Verilator sources to implement the missing unsupported feature.
+
    This error may be ignored with :vlopt:`--bbox-unsup`, however this will
-   make the design simulate incorrectly; see the details under
-   :vlopt:`--bbox-unsup`.
+   make the design simulate incorrectly and is only intended for lint
+   usage; see the details under :vlopt:`--bbox-unsup`.
 
 
 .. option:: UNUSED

test_regress/t/t_lint_didnotconverge_bad.out

@@ -0,0 +1,6 @@
+-V{t#,#}- Verilated::debug is on. Message prefix indicates {<thread>,<sequence_number>}.
+-V{t#,#}+    Vt_lint_didnotconverge_bad___024root___change_request
+-V{t#,#}+    Vt_lint_didnotconverge_bad___024root___change_request_1
+-V{t#,#}        CHANGE: t/t_lint_didnotconverge_bad.v:14: a
+%Error: t/t_lint_didnotconverge_bad.v:7: Verilated model didn't converge
+Aborting...

test_regress/t/t_lint_didnotconverge_bad.pl

@@ -0,0 +1,33 @@
+#!/usr/bin/env perl
+if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); die; }
+# DESCRIPTION: Verilator: Verilog Test driver/expect definition
+#
+# Copyright 2008 by Wilson Snyder. 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-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+scenarios(vlt => 1);
+
+compile(
+    verilator_flags2 => ["--prof-cfuncs"],
+    );
+
+execute(
+    fails => 1,
+    expect_filename => $Self->{golden_filename},
+    );
+
+extract(
+    in => $Self->{top_filename},
+    out => "../docs/gen/ex_DIDNOTCONVERGE_faulty.rst",
+    lines => "16-17");
+
+extract(
+    in => $Self->{golden_filename},
+    out => "../docs/gen/ex_DIDNOTCONVERGE_msg.rst",
+    lines => "2-5");
+
+ok(1);
+1;

test_regress/t/t_lint_didnotconverge_bad.v

@@ -0,0 +1,19 @@
+// DESCRIPTION: Verilator: Verilog Test module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2012 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+
+module t (/*AUTOARG*/
+   // Outputs
+   a, b
+   );
+
+   // verilator lint_off UNOPT
+
+   output logic a, b;
+
+   always_comb b = ~a;
+   always_comb a = b;
+
+endmodule

test_regress/t/t_lint_didnotconverge_nodbg_bad.out

@@ -0,0 +1,2 @@
+%Error: t/t_lint_didnotconverge_bad.v:7: Verilated model didn't converge
+Aborting...

test_regress/t/t_lint_didnotconverge_nodbg_bad.pl

@@ -0,0 +1,30 @@
+#!/usr/bin/env perl
+if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); die; }
+# DESCRIPTION: Verilator: Verilog Test driver/expect definition
+#
+# Copyright 2008 by Wilson Snyder. 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-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+scenarios(vlt => 1);
+
+top_filename("t/t_lint_didnotconverge_bad.v");
+
+compile(
+    make_flags => 'CPPFLAGS_ADD=-UVL_DEBUG',
+    );
+
+execute(
+    fails => 1,
+    expect_filename => $Self->{golden_filename},
+    );
+
+extract(
+    in => $Self->{golden_filename},
+    out => "../docs/gen/ex_DIDNOTCONVERGE_nodbg_msg.rst",
+    lines => "1");
+
+ok(1);
+1;

test_regress/t/t_lint_stmtdly_bad.out

@@ -0,0 +1,7 @@
+%Warning-STMTDLY: t/t_lint_stmtdly_bad.v:10:8: Unsupported: Ignoring delay on this delayed statement.
+                                             : ... In instance t
+   10 |       #100 $finish;   
+      |        ^~~
+                  ... For warning description see https://verilator.org/warn/STMTDLY?v=latest
+                  ... Use "/* verilator lint_off STMTDLY */" and lint_on around source to disable this message.
+%Error: Exiting due to

test_regress/t/t_lint_stmtdly_bad.pl

@@ -0,0 +1,29 @@
+#!/usr/bin/env perl
+if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); die; }
+# DESCRIPTION: Verilator: Verilog Test driver/expect definition
+#
+# Copyright 2008 by Wilson Snyder. 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-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+scenarios(vlt => 1);
+
+compile(
+    fails => 1,
+    expect_filename => $Self->{golden_filename},
+    );
+
+extract(
+    in => $Self->{top_filename},
+    out => "../docs/gen/ex_STMTDLY_faulty.rst",
+    lines => "10");
+
+extract(
+    in => $Self->{golden_filename},
+    out => "../docs/gen/ex_STMTDLY_msg.rst",
+    lines => "1");
+
+ok(1);
+1;

test_regress/t/t_lint_stmtdly_bad.v

@@ -0,0 +1,13 @@
+// DESCRIPTION: Verilator: Verilog Test module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2012 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+
+module t (/*AUTOARG*/);
+
+   initial begin
+      #100 $finish;  //<--- Warning
+   end
+
+endmodule