From 8f4490628f5c6b4233bc058734b84184b300d98a Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Sat, 20 Jul 2024 17:50:14 -0400 Subject: [PATCH] Commentary: Clarify some warning messages. --- Changes | 2 +- docs/gen/ex_PINMISSING_faulty.rst | 11 ++++ docs/gen/ex_PINMISSING_msg.rst | 4 ++ docs/gen/ex_PKGNODECL_faulty.rst | 11 ++++ docs/gen/ex_PKGNODECL_msg.rst | 4 ++ docs/guide/warnings.rst | 81 +++++++++++++++++------- test_regress/t/t_lint_pinmissing_bad.out | 9 +++ test_regress/t/t_lint_pinmissing_bad.pl | 35 ++++++++++ test_regress/t/t_lint_pinmissing_bad.v | 12 ++++ test_regress/t/t_lint_pkgnodecl_bad.out | 5 ++ test_regress/t/t_lint_pkgnodecl_bad.pl | 35 ++++++++++ test_regress/t/t_lint_pkgnodecl_bad.v | 12 ++++ 12 files changed, 197 insertions(+), 24 deletions(-) create mode 100644 docs/gen/ex_PINMISSING_faulty.rst create mode 100644 docs/gen/ex_PINMISSING_msg.rst create mode 100644 docs/gen/ex_PKGNODECL_faulty.rst create mode 100644 docs/gen/ex_PKGNODECL_msg.rst create mode 100644 test_regress/t/t_lint_pinmissing_bad.out create mode 100755 test_regress/t/t_lint_pinmissing_bad.pl create mode 100644 test_regress/t/t_lint_pinmissing_bad.v create mode 100644 test_regress/t/t_lint_pkgnodecl_bad.out create mode 100755 test_regress/t/t_lint_pkgnodecl_bad.pl create mode 100644 test_regress/t/t_lint_pkgnodecl_bad.v diff --git a/Changes b/Changes index d75b43b38..68199acd2 100644 --- a/Changes +++ b/Changes @@ -652,7 +652,7 @@ Verilator 5.006 2023-01-22 **Minor:** * Support clocking blocks (#3674). [Krzysztof Bieganski, Antmicro Ltd] -* Support packed structs (#3802). [Aleksander Kiryk, Antmicro Ltd] +* Support unpacked structs (#3802). [Aleksander Kiryk, Antmicro Ltd] * Support Windows-native builds using cmake (#3814). [Kritik Bhimani] * Support p format for UnpackArray (#3877). [Aleksander Kiryk, Antmicro Ltd] * Support property calls without parenthesis (#3879) (#3893). [Ryszard Rozak, Antmicro Ltd] diff --git a/docs/gen/ex_PINMISSING_faulty.rst b/docs/gen/ex_PINMISSING_faulty.rst new file mode 100644 index 000000000..a8172dea9 --- /dev/null +++ b/docs/gen/ex_PINMISSING_faulty.rst @@ -0,0 +1,11 @@ +.. comment: generated by t_lint_pinmissing_bad +.. code-block:: sv + :linenos: + :emphasize-lines: 2 + + module t; + sub sub(); // <--- Warning + endmodule + module sub + (output port); + endmodule diff --git a/docs/gen/ex_PINMISSING_msg.rst b/docs/gen/ex_PINMISSING_msg.rst new file mode 100644 index 000000000..c1a06525e --- /dev/null +++ b/docs/gen/ex_PINMISSING_msg.rst @@ -0,0 +1,4 @@ +.. comment: generated by t_lint_pinmissing_bad +.. code-block:: + + %Warning-PINMISSING: example.v:1:8 Cell has missing pin: 'port' diff --git a/docs/gen/ex_PKGNODECL_faulty.rst b/docs/gen/ex_PKGNODECL_faulty.rst new file mode 100644 index 000000000..1f0b81529 --- /dev/null +++ b/docs/gen/ex_PKGNODECL_faulty.rst @@ -0,0 +1,11 @@ +.. comment: generated by t_lint_pkgnodecl_bad +.. code-block:: sv + :linenos: + :emphasize-lines: 2 + + module t; + initial Pkg::hello(); //<--- Warning + endmodule + package Pkg; + function void hello(); endfunction + endpackage diff --git a/docs/gen/ex_PKGNODECL_msg.rst b/docs/gen/ex_PKGNODECL_msg.rst new file mode 100644 index 000000000..7c772b7c4 --- /dev/null +++ b/docs/gen/ex_PKGNODECL_msg.rst @@ -0,0 +1,4 @@ +.. comment: generated by t_lint_pkgnodecl_bad +.. code-block:: + + %Error-PKGNODECL: example.v:1:12 Package/class 'Pkg' not found, and needs to be predeclared (IEEE 1800-2023 26.3) diff --git a/docs/guide/warnings.rst b/docs/guide/warnings.rst index b15619b52..d86bbc0f8 100644 --- a/docs/guide/warnings.rst +++ b/docs/guide/warnings.rst @@ -419,9 +419,9 @@ List Of Warnings .. option:: CONSTRAINTIGN - Warns that Verilator does not support :code:`constraint`, - :code:`constraint_mode`, or :code:`rand_mode`, and the construct was are - ignored. + Warns that Verilator does not support certain forms of + :code:`constraint`, :code:`constraint_mode`, or :code:`rand_mode`, and + the construct was are ignored. Ignoring this warning may make Verilator randomize() simulations differ from other simulators. @@ -1264,7 +1264,7 @@ List Of Warnings .. option:: PINMISSING - .. TODO better example + .. TODO better example (frequent) Warns that a module has a pin that is not mentioned in an instance. If a pin is not missing it should still be specified on the instance @@ -1273,6 +1273,22 @@ List Of Warnings Ignoring this warning will only suppress the lint check; it will simulate correctly. + Faulty example: + + .. include:: ../../docs/gen/ex_PKGNODECL_faulty.rst + + Results in: + + .. include:: ../../docs/gen/ex_PKGNODECL_msg.rst + + Repaired example: + + .. code-block:: sv + :emphasize-lines: 2 + + sub sub ( + .port()); + Other tools with similar warnings: Icarus Verilog's portbind, "warning: Instantiating module ... with dangling input port (...)". Slang's unconnected-port, "port '...' has no connection". @@ -1304,7 +1320,7 @@ List Of Warnings generate if (A==0) begin b b_inst1 (.x(1'b0)); //<--- error nonexistent port - b #(.PX(1'b0)) b_inst2 (); //<--- error nonexistent parameter + b #(.PX(1'b0)) b_inst2 (); //<--- error nonexistent parameter end endgenerate endmodule @@ -1346,11 +1362,22 @@ List Of Warnings .. option:: PKGNODECL - .. TODO better example + An error that a package/class appears to have been referenced that has + not yet been declared. According to IEEE 1800-2023 26.3, all packages + must be declared before being used. - An error that a package/class appears to have been referenced that has not - yet been declared. According to IEEE 1800-2023 26.3, all packages must - be declared before being used. + Faulty example: + + .. include:: ../../docs/gen/ex_PKGNODECL_faulty.rst + + Results in: + + .. include:: ../../docs/gen/ex_PKGNODECL_msg.rst + + Often the package is declared in its own header file. In this case add + an include of that package header file to the referencing file. (And + make sure you have header guards in the package's header file to prevent + multiple declarations of the package.) .. option:: PREPROCZERO @@ -1375,7 +1402,7 @@ List Of Warnings `endif The portable way to suppress this warning is to use a define value other - than zero to when used in a preprocessor expression. + than zero, when it is to be used in a preprocessor expression. .. option:: PROCASSWIRE @@ -1897,7 +1924,8 @@ List Of Warnings .. option:: UNPACKED - Warns that unpacked structs and unions are not supported. + Warns that unpacked structs and unions are not supported because + :vlopt:`--structs-packed` was used, or by up through version 5.004. Ignoring this warning will make Verilator treat the structure as packed, which may make Verilator simulations differ from other simulators. This @@ -1948,14 +1976,16 @@ List Of Warnings .. TODO better example - Warns that the specified genvar is never used/consumed. + Warns that the specified genvar is never used/consumed. See similar + :option:`UNUSEDSIGNAL`. .. option:: UNUSEDPARAM .. TODO better example - Warns that the specified parameter is never used/consumed. + Warns that the specified parameter is never used/consumed. See similar + :option:`UNUSEDSIGNAL`. .. option:: UNUSEDSIGNAL @@ -2078,10 +2108,6 @@ List Of Warnings .. option:: WAITCONST - .. code-block:: sv - - wait(1); // Blocks forever - Warns that a `wait` statement awaits a constant condition, which means it either blocks forever or never blocks. @@ -2089,6 +2115,12 @@ List Of Warnings something that elaborates to zero), does not warn, as it is presumed the code is making the intent clear. + Faulty example: + + .. code-block:: sv + + wait(1); // Blocks forever + .. option:: WIDTH @@ -2125,7 +2157,7 @@ List Of Warnings .. include:: ../../docs/gen/ex_WIDTHEXPAND_1_faulty.rst - Results in a WIDTHEXPAND warning: + Results in a :option:`WIDTHEXPAND` warning: .. include:: ../../docs/gen/ex_WIDTHEXPAND_1_msg.rst @@ -2136,15 +2168,18 @@ List Of Warnings .. option:: WIDTHTRUNC - A more granular WIDTH warning, for when a value is truncated. + A more granular :option:`WIDTH` warning, for when a value is + truncated. See :option:`WIDTH`. .. option:: WIDTHEXPAND - A more granular WIDTH warning, for when a value is zero expanded. + A more granular :option:`WIDTH` warning, for when a value is zero + expanded. See :option:`WIDTH`. .. option:: WIDTHXZEXPAND - A more granular WIDTH warning, for when a value is X/Z expanded. + A more granular :option:`WIDTH` warning, for when a value is X/Z + expanded. See :option:`WIDTH`. .. option:: WIDTHCONCAT @@ -2193,7 +2228,7 @@ List Of Warnings #(parameter int MY_PARAM = 0); reg [7:0] data; always @* begin - data = {MY_PARAM{1'b1}}; //<--- WARNING + data = {MY_PARAM{1'b1}}; //<--- Warning end endmodule @@ -2214,7 +2249,7 @@ List Of Warnings :emphasize-lines: 2 module dut - #(parameter int MY_PARAM = 1); //<--- REPAIRED + #(parameter int MY_PARAM = 1); //<--- REPAIRED reg [7:0] data; always @* begin data = {MY_PARAM{1'b1}}; diff --git a/test_regress/t/t_lint_pinmissing_bad.out b/test_regress/t/t_lint_pinmissing_bad.out new file mode 100644 index 000000000..c86daaab5 --- /dev/null +++ b/test_regress/t/t_lint_pinmissing_bad.out @@ -0,0 +1,9 @@ +%Warning-PINMISSING: t/t_lint_pinmissing_bad.v:8:8: Cell has missing pin: 'port' + 8 | sub sub(); + | ^~~ + t/t_lint_pinmissing_bad.v:11:11: ... Location of port declaration + 11 | (output port); + | ^~~~ + ... For warning description see https://verilator.org/warn/PINMISSING?v=latest + ... Use "/* verilator lint_off PINMISSING */" and lint_on around source to disable this message. +%Error: Exiting due to diff --git a/test_regress/t/t_lint_pinmissing_bad.pl b/test_regress/t/t_lint_pinmissing_bad.pl new file mode 100755 index 000000000..b48fa0bc9 --- /dev/null +++ b/test_regress/t/t_lint_pinmissing_bad.pl @@ -0,0 +1,35 @@ +#!/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(linter => 1); + +my $root = ".."; + +if (!-r "$root/.git") { + skip("Not in a git repository"); +} else { + lint( + fails => 1, + expect_filename => $Self->{golden_filename}, + ); + + extract( + in => $Self->{top_filename}, + out => "../docs/gen/ex_PINMISSING_faulty.rst", + lines => "7-12"); + + extract( + in => $Self->{golden_filename}, + out => "../docs/gen/ex_PINMISSING_msg.rst", + lines => "1-1"); +} + +ok(1); +1; diff --git a/test_regress/t/t_lint_pinmissing_bad.v b/test_regress/t/t_lint_pinmissing_bad.v new file mode 100644 index 000000000..ef1de6b05 --- /dev/null +++ b/test_regress/t/t_lint_pinmissing_bad.v @@ -0,0 +1,12 @@ +// 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; + sub sub(); // <--- Warning +endmodule +module sub + (output port); +endmodule diff --git a/test_regress/t/t_lint_pkgnodecl_bad.out b/test_regress/t/t_lint_pkgnodecl_bad.out new file mode 100644 index 000000000..56072a8d4 --- /dev/null +++ b/test_regress/t/t_lint_pkgnodecl_bad.out @@ -0,0 +1,5 @@ +%Error-PKGNODECL: t/t_lint_pkgnodecl_bad.v:8:12: Package/class 'Pkg' not found, and needs to be predeclared (IEEE 1800-2023 26.3) + 8 | initial Pkg::hello(); + | ^~~ + ... For error description see https://verilator.org/warn/PKGNODECL?v=latest +%Error: Exiting due to diff --git a/test_regress/t/t_lint_pkgnodecl_bad.pl b/test_regress/t/t_lint_pkgnodecl_bad.pl new file mode 100755 index 000000000..7a81df912 --- /dev/null +++ b/test_regress/t/t_lint_pkgnodecl_bad.pl @@ -0,0 +1,35 @@ +#!/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(linter => 1); + +my $root = ".."; + +if (!-r "$root/.git") { + skip("Not in a git repository"); +} else { + lint( + fails => 1, + expect_filename => $Self->{golden_filename}, + ); + + extract( + in => $Self->{top_filename}, + out => "../docs/gen/ex_PKGNODECL_faulty.rst", + lines => "7-12"); + + extract( + in => $Self->{golden_filename}, + out => "../docs/gen/ex_PKGNODECL_msg.rst", + lines => "1"); +} + +ok(1); +1; diff --git a/test_regress/t/t_lint_pkgnodecl_bad.v b/test_regress/t/t_lint_pkgnodecl_bad.v new file mode 100644 index 000000000..ee8248f78 --- /dev/null +++ b/test_regress/t/t_lint_pkgnodecl_bad.v @@ -0,0 +1,12 @@ +// 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; + initial Pkg::hello(); //<--- Warning +endmodule +package Pkg; + function void hello(); endfunction +endpackage