Fix and document --gdb option, bug454.

Changes

@@ -6,6 +6,8 @@ indicates the contributor was also the author of the fix; Thanks!
 
 * Verilator 3.833 devel
 
+****  Fix and document --gdb option, bug454. [Jeremy Bennett]
+
 
 * Verilator 3.832 2012/03/07
 

bin/verilator

@@ -69,7 +69,7 @@ if (! GetOptions (
 		  "debug:s"	=> \&debug,
 		  # "version!"	=> \&version,	# Also passthru'ed
 		  # Switches
-		  "gdb=s"	=> \$opt_gdb,	# Undocumented debugging
+		  "gdb!"	=> \$opt_gdb,
 		  "gdbbt!"	=> \$opt_gdbbt,
 		  # Additional parameters
 		  "<>"		=> sub {},	# Ignored
@@ -82,17 +82,24 @@ if ($opt_gdbbt && !gdb_works()) {
     warn "-Info: --gdbbt ignored: gdb doesn't seem to be working\n" if $Debug;
     $opt_gdbbt = 0;
 }
-if ($opt_gdbbt && !$opt_gdb && $Debug) {
+if ($opt_gdb) {
+    # Generic GDB interactive
+    run (("gdb"||$ENV{VERILATOR_GDB})
+	 ." ".verilator_bin()
+	 ." -ex 'run ".join(' ',@Opt_Verilator_Sw)."'"
+	 ." -ex 'set width 0'"
+	 ." -ex 'bt'");
+} elsif ($opt_gdbbt && $Debug) {
     # Run under GDB to get gdbbt
-    run ("gdb ".verilator_bin()
+    run ("gdb"
+	 ." ".verilator_bin()
 	 ." --batch --quiet --return-child-result"
 	 ." -ex 'run ".join(' ',@Opt_Verilator_Sw)."'"
 	 ." -ex 'set width 0'"
 	 ." -ex 'bt'");
 } else {
     # Normal, non gdb
-    run (($opt_gdb?"$opt_gdb ":"")
-	 .verilator_bin()
+    run (verilator_bin()
 	 ." ".join(' ',@Opt_Verilator_Sw));
 }
 
@@ -260,6 +267,7 @@ descriptions in the next sections for more information.
     --exe                       Link to create executable
      -F <file>                  Parse options from a file, relatively
      -f <file>                  Parse options from a file
+    --gdb                       Run Verilator under GDB interactively
     --gdbbt                     Run Verilator under GDB for backtrace
     --help                      Display this help
      -I<dir>                    Directory to search for includes
@@ -558,11 +566,17 @@ The file may contain // comments which are ignored to the end of the line.
 Any $VAR, $(VAR), or ${VAR} will be replaced with the specified environment
 variable.
 
+=item --gdb
+
+Run Verilator underneath an interactive GDB (or VERILATOR_GDB environment
+variable value) session.  See also --gdbbt.
+
 =item --gdbbt
 
-If --debug is specified, run Verilator underneath a GDB process and print
-a backtrace on exit.  Without --debug or if GDB doesn't seem to work, this
-flag is ignored.
+If --debug is specified, run Verilator underneath a GDB process and print a
+backtrace on exit, then exit GDB immediately.  Without --debug or if GDB
+doesn't seem to work, this flag is ignored.  Intended for easy creation of
+backtraces by users; otherwise see the --gdb flag.
 
 =item --help
 
@@ -1299,6 +1313,11 @@ baseline regression tests.
 If set, specifies an alternative name of the Verilator binary.  May be used
 for debugging and selecting between multiple operating system builds.
 
+=item VERILATOR_GDB
+
+If set, the command to run when using the --gdb option, such as "ddd".  If
+not specified, it will use "gdb".
+
 =item VERILATOR_ROOT
 
 Specifies the directory containing the distribution kit.  This is used to

internals.pod

@@ -240,7 +240,7 @@ variable is an output.
 
 The test_regress/driver.pl script accepts --debug --gdb to start Verilator
 under gdb.  You can also use --debug --gdbbt to just backtrace and then
-exit gdb.
+exit gd. To debug the Verilated executable, use --gdbsim.
 
 To break at a specific edit number which changed a node (presumably to find
 what made a <e####> line in the tree dumps):
@@ -249,8 +249,8 @@ what made a <e####> line in the tree dumps):
 
 To print a node:
 
-   call nodep->dumpGdb()      # aliased to "pn" in .gdbinit
-   call nodep->dumpTreeGdb()  # aliased to "pnt" in .gdbinit
+   call nodep->dumpGdb()      # aliased to "pn" in src/.gdbinit
+   call nodep->dumpTreeGdb()  # aliased to "pnt" in src/.gdbinit
 
 =head1 DISTRIBUTION
 

src/V3Options.cpp

@@ -957,8 +957,8 @@ void V3Options::parseOptsList(FileLine* fl, const string& optdir, int argc, char
 		shift;
 		parseOptsFile(fl, parseFileArg(optdir,argv[i]), false);
 	    }
-	    else if ( !strcmp (sw, "-gdb") && (i+1)<argc ) {
-		shift; // Used only in perl shell
+	    else if ( !strcmp (sw, "-gdb") ) {
+		// Used only in perl shell
 	    }
 	    else if ( !strcmp (sw, "-gdbbt")) {
 		// Used only in perl shell

test_regress/driver.pl

@@ -464,9 +464,8 @@ sub compile_vlt_flags {
     $self->{trace} = 1 if ($opt_trace || $checkflags =~ /-trace\b/);
     $self->{coverage} = 1 if ($checkflags =~ /-coverage\b/);
 
-    $opt_gdb="gdbrun" if defined $opt_gdb;
     my @verilator_flags = @{$param{verilator_flags}};
-    unshift @verilator_flags, "--gdb $opt_gdb" if $opt_gdb;
+    unshift @verilator_flags, "--gdb" if $opt_gdb;
     unshift @verilator_flags, "--gdbbt" if $opt_gdbbt;
     unshift @verilator_flags, @Opt_Driver_Verilator_Flags;
     unshift @verilator_flags, "--x-assign unique";  # More likely to be buggy
@@ -716,10 +715,12 @@ sub execute {
 	$param{executable} ||= "$self->{obj_dir}/$param{VM_PREFIX}";
 	$self->_run(logfile=>"$self->{obj_dir}/vlt_sim.log",
 		    cmd=>[($run_env
-			   .($opt_gdbsim ? "gdbrun ":"")
-			   .$param{executable}),
+			   .($opt_gdbsim ? ("gdb"||$ENV{VERILATOR_GDB})." " : "")
+			   .$param{executable}
+			   .($opt_gdbsim ? " -ex 'run " : "")),
 			  @{$param{all_run_flags}},
-			  ],
+			  ($opt_gdbsim ? "'" : ""),
+		    ],
 		    %param,
 		    expect=>$param{expect},		# backward compatible name
 		    );

test_regress/t/t_debug_fatalsrc_bt_bad.pl

@@ -7,6 +7,8 @@ if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); di
 # Lesser General Public License Version 3 or the Perl Artistic License
 # Version 2.0.
 
+$ENV{VERILATOR_TEST_NO_GDB} and $Self->skip("Skipping due to VERILATOR_TEST_NO_GDB");
+
 compile (
 	 v_flags2 => ["--lint-only --debug --gdbbt --debug-fatalsrc"],
 	 fails=>$Self->{v3},

test_regress/t/t_debug_sigsegv_bad.pl

@@ -8,6 +8,7 @@ if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); di
 # Version 2.0.
 
 $Self->{vlt} or $Self->skip("Verilator only test");
+$ENV{VERILATOR_TEST_NO_GDB} and $Self->skip("Skipping due to VERILATOR_TEST_NO_GDB");
 
 compile (
 	 verilator_flags2 => ["--debug-sigsegv"],

test_regress/t/t_debug_sigsegv_bt_bad.pl

@@ -7,6 +7,8 @@ if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); di
 # Lesser General Public License Version 3 or the Perl Artistic License
 # Version 2.0.
 
+$ENV{VERILATOR_TEST_NO_GDB} and $Self->skip("Skipping due to VERILATOR_TEST_NO_GDB");
+
 compile (
 	 v_flags2 => ["--lint-only --debug --gdbbt --debug-sigsegv"],
 	 fails=>$Self->{v3},