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

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.