Commentary: Clarify some warning messages.

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]

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

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'

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

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)

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}};

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

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;

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

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

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;

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