diff --git a/docs/gen/ex_DIDNOTCONVERGE_faulty.rst b/docs/gen/ex_DIDNOTCONVERGE_faulty.rst new file mode 100644 index 000000000..e37f06208 --- /dev/null +++ b/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; diff --git a/docs/gen/ex_DIDNOTCONVERGE_msg.rst b/docs/gen/ex_DIDNOTCONVERGE_msg.rst new file mode 100644 index 000000000..c15d71bb4 --- /dev/null +++ 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 diff --git a/docs/gen/ex_DIDNOTCONVERGE_nodbg_msg.rst b/docs/gen/ex_DIDNOTCONVERGE_nodbg_msg.rst new file mode 100644 index 000000000..b6de737df --- /dev/null +++ b/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 diff --git a/docs/gen/ex_STMTDLY_faulty.rst b/docs/gen/ex_STMTDLY_faulty.rst new file mode 100644 index 000000000..97fcc43e9 --- /dev/null +++ b/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 diff --git a/docs/gen/ex_STMTDLY_msg.rst b/docs/gen/ex_STMTDLY_msg.rst new file mode 100644 index 000000000..fe19fb943 --- /dev/null +++ b/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. diff --git a/docs/guide/warnings.rst b/docs/guide/warnings.rst index 0b9828383..c464e8b3b 100644 --- a/docs/guide/warnings.rst +++ b/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 diff --git a/test_regress/t/t_lint_didnotconverge_bad.out b/test_regress/t/t_lint_didnotconverge_bad.out new file mode 100644 index 000000000..1a0bb785a --- /dev/null +++ b/test_regress/t/t_lint_didnotconverge_bad.out @@ -0,0 +1,6 @@ +-V{t#,#}- Verilated::debug is on. Message prefix indicates {,}. +-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... diff --git a/test_regress/t/t_lint_didnotconverge_bad.pl b/test_regress/t/t_lint_didnotconverge_bad.pl new file mode 100755 index 000000000..5281eac77 --- /dev/null +++ b/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; diff --git a/test_regress/t/t_lint_didnotconverge_bad.v b/test_regress/t/t_lint_didnotconverge_bad.v new file mode 100644 index 000000000..315e91aa5 --- /dev/null +++ b/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 diff --git a/test_regress/t/t_lint_didnotconverge_nodbg_bad.out b/test_regress/t/t_lint_didnotconverge_nodbg_bad.out new file mode 100644 index 000000000..1b59dad18 --- /dev/null +++ b/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... diff --git a/test_regress/t/t_lint_didnotconverge_nodbg_bad.pl b/test_regress/t/t_lint_didnotconverge_nodbg_bad.pl new file mode 100755 index 000000000..3b851338e --- /dev/null +++ b/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; diff --git a/test_regress/t/t_lint_stmtdly_bad.out b/test_regress/t/t_lint_stmtdly_bad.out new file mode 100644 index 000000000..f23238765 --- /dev/null +++ b/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 diff --git a/test_regress/t/t_lint_stmtdly_bad.pl b/test_regress/t/t_lint_stmtdly_bad.pl new file mode 100755 index 000000000..548dab0af --- /dev/null +++ b/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; diff --git a/test_regress/t/t_lint_stmtdly_bad.v b/test_regress/t/t_lint_stmtdly_bad.v new file mode 100644 index 000000000..3684bbb30 --- /dev/null +++ b/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