Add --runtime-debug for Verilated executable runtime debugging.

Changes

@@ -15,10 +15,11 @@ Verilator 5.021 devel
 
 * Add predicted stack overflow warning (#4799).
 * Add +verilator+coverage+file runtime option.
-* Add --main support for dumping coverage.
+* Add --runtime-debug for Verilated executable runtime debugging.
 * Add '--decorations node' for inserting debug comments into emitted code.
 * Remove deprecated 32-bit pointer mode (`gcc -m32`).
 * Change zero replication width error to ZEROREPL warning (#4753) (#4762). [Pengcheng Xu]
+* Support dumping coverage with --main.
 * Support `vpiConstType` in `vpi_get_str()` (#4797). [Marlon James]
 * Support SystemC 3.0.0 public review version (#4805) (#4807). [Anthony Donlon]
 * Support parsing anonymous primitive instantiations (#4809). [Anthony Donlon]

bin/verilator

@@ -416,6 +416,7 @@ detailed descriptions of these arguments.
     --reloop-limit              Minimum iterations for forming loops
     --report-unoptflat          Extra diagnostics for UNOPTFLAT
     --rr                        Run Verilator and record with rr
+    --runtime-debug             Enable model runtime debugging
     --savable                   Enable model save-restore
     --sc                        Create SystemC output
     --no-skip-identical         Disable skipping identical output

docs/guide/exe_sim.rst

@@ -29,6 +29,10 @@ Summary:
    Enable simulation runtime debugging.  Equivalent to
    :vlopt:`+verilator+debugi+4 <+verilator+debugi+\<value\>>`.
 
+   To be useful, the model typically must first be compiled with debug
+   capabilities by Verilating with :vlopt:`--runtime-debug` or `-CFLAGS
+   -DVL_DEBUG=1`.
+
 .. option:: +verilator+debugi+<value>
 
    Enable simulation runtime debugging at the provided level.

docs/guide/exe_verilator.rst

@@ -1211,6 +1211,40 @@ Summary:
    Run Verilator and record with the :command:`rr` command.  See
    `https://rr-project.org <https://rr-project.org>`_.
 
+.. option:: --runtime-debug
+
+   Enable including debug assertions in the generated model. This may
+   significantly decrease model performance. This option will only work
+   with gcc/clang.
+
+   This option has the same effect as the following flags:
+
+   :vlopt:`--decorations node`
+     Instructs Verilator to add comments to the Verilated C++ code to
+     assist determining what Verilog code was responsible for each C++
+     statement.
+
+   ``-CFLAGS -ggdb  -LDFLAGS -ggdb``
+     Instructs the compiler and linker to enable debugger symbols.
+
+   ``-CFLAGS -fsanitize=address,undefined  -LDFLAGS -fsanitize=address,undefined``
+     Instructs the compiler and linker to enable the address sanitizer, and
+     undefined behavior sanitizer.
+
+   ``-CFLAGS -D_GLIBCXX_DEBUG``
+     Instructs the compiler to enable C++ library (glibc) internal
+     assertions to find library-misuse issues.
+
+   ``-CFLAGS -DVL_DEBUG=1``
+     Instructs the compiler to enable Verilator's runtime assertions and
+     debug capabilities.  To enable debug print messages at runtime, see
+     :vlopt:`+verilator+debug`.
+
+   The :vlopt:`-CFLAGS` and/or :vlopt:`-LDFLAGS` options used here pass the
+   following argument into the generated Makefile for use as compiler or
+   linker options respectively.  If you are using your own Makefiles, adapt
+   appropriately to pass the suggested flags to the compiler and linker.
+
 .. option:: --savable
 
    Enable including save and restore functions in the generated model.  See

docs/guide/simulating.rst

@@ -515,36 +515,30 @@ documentation.
 Runtime Debugging
 =================
 
-To debug a Verilated executable, typically you will want to have debugger
-symbols inserted by the compiler, assertions enabled in the C library,
-assertions enabled in the Verilated library, and the sanitizer enabled to
-look for bad memory or undefined operations. (These options slow down the
-executable, so do this only when debugging.) To enable these, Verilate
-with:
+To debug a Verilated executable, Verilate with :vlopt:`--runtime-debug`.
+This will instruct the compiler to insert debugger, and enable various
+library assertions. These options slow down the executable, so do this
+only when debugging.
 
-   .. code-block:: bash
-
-      --decorations node
-      -CFLAGS -ggdb  -LDFLAGS -ggdb
-      -CFLAGS -DVL_DEBUG=1
-      -CFLAGS -D_GLIBCXX_DEBUG
-      -CFLAGS -fsanitize=address,undefined  -LDFLAGS -fsanitize=address,undefined
-
-The :vlopt:`--decorations node` option used here will add comments to the
-Verilated C++ code to indicate what Verilog code was responsible, which may
-assist debug readability.
-
-The :vlopt:`-CFLAGS` and/or :vlopt:`-LDFLAGS` options used here pass the
-following argument into the generated Makefile for use as compiler or
-linker options respectively.  If you are using your own Makefiles, adapt
-appropriately to pass the suggested flags to the compiler and linker.
+If you are using your own Makefiles, adapt appropriately to pass the
+options documented under :vlopt:`--runtime-debug` to the compiler and
+linker.
 
 Once you have a debugging-enabled executable, run it using the the standard
 GNU debugger ``gdb`` or a similar tool, and create a backtrace; e.g.:
 
    .. code-block:: bash
 
-      gdb obj_dir/Vmodel
-        run {Vmodel_command_arguments}
-        {segmentation faults}
+      gdb obj_dir/Vtop
+        run {Vtop_command_arguments}
+        {Vtop prints output, perhaps a segmentation faults}
         bt
+
+Rarely the bug may disappear with :vlopt:`--runtime-debug`; if so, try
+instead using the sub-options that :vlopt:`--runtime-debug` documents, to
+find the maximum subset that still shows the issue.  E.g. it is likely that
+using `-CFLAGS -D_GLIBCXX_DEBUG` will not hide any bug, so may be used.
+
+Using :vlopt:`--runtime-debug` or `-CFLAGS -DVL_DEBUG=1` will only print a
+message if something goes wrong.  To enable debug print messages at
+runtime, additionally use the :vlopt:`+verilator+debug` runtime option.

src/V3Options.cpp

@@ -1406,6 +1406,15 @@ void V3Options::parseOptsList(FileLine* fl, const string& optdir, int argc,
     });
     DECL_OPTION("-report-unoptflat", OnOff, &m_reportUnoptflat);
     DECL_OPTION("-rr", CbCall, []() {});  // Processed only in bin/verilator shell
+    DECL_OPTION("-runtime-debug", CbCall, [this, fl]() {
+        decorations(fl, "node");
+        addCFlags("-ggdb");
+        addLdLibs("-ggdb");
+        addCFlags("-fsanitize=address,undefined");
+        addLdLibs("-fsanitize=address,undefined");
+        addCFlags("-D_GLIBCXX_DEBUG");
+        addCFlags("-DVL_DEBUG=1");
+    });
 
     DECL_OPTION("-savable", OnOff, &m_savable);
     DECL_OPTION("-sc", CbCall, [this]() {

test_regress/t/t_flag_runtime_debug.pl

@@ -0,0 +1,26 @@
+#!/usr/bin/env perl
+if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); die; }
+# DESCRIPTION: Verilator: Verilog Test driver/expect definition
+#
+# Copyright 2019 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(simulator => 1);
+
+top_filename("t/t_flag_main.v");
+
+compile(
+    verilator_flags2 => ['--binary --runtime-debug'],
+    );
+
+execute(
+    check_finished => 1,
+    );
+
+file_grep("$Self->{obj_dir}/$Self->{vm_prefix}.mk", qr/VL_DEBUG=1/);
+
+ok(1);
+1;