diff --git a/Changes b/Changes index 483438765..60d1ec432 100644 --- a/Changes +++ b/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] diff --git a/bin/verilator b/bin/verilator index 1ed15a16e..0c2cbe780 100755 --- a/bin/verilator +++ b/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 diff --git a/docs/guide/exe_sim.rst b/docs/guide/exe_sim.rst index 0040e242f..d396c96d2 100644 --- a/docs/guide/exe_sim.rst +++ b/docs/guide/exe_sim.rst @@ -29,6 +29,10 @@ Summary: Enable simulation runtime debugging. Equivalent to :vlopt:`+verilator+debugi+4 <+verilator+debugi+\>`. + 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+ Enable simulation runtime debugging at the provided level. diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index 7d1c8b984..049a297e3 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -1211,6 +1211,40 @@ Summary: Run Verilator and record with the :command:`rr` command. See `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 diff --git a/docs/guide/simulating.rst b/docs/guide/simulating.rst index 023bf4aef..47a35df1a 100644 --- a/docs/guide/simulating.rst +++ b/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. diff --git a/src/V3Options.cpp b/src/V3Options.cpp index bcd9de6fc..5993a7b84 100644 --- a/src/V3Options.cpp +++ b/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]() { diff --git a/test_regress/t/t_flag_runtime_debug.pl b/test_regress/t/t_flag_runtime_debug.pl new file mode 100755 index 000000000..56b905656 --- /dev/null +++ b/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;