ovs-sandbox: Add an option to allow running ovs-vswitchd under gdb

It is some times useful to leverage the sandbox facility to experiment
and explore the internals of ovs-vswitchd.  Since GDB requires console
access for user inputs, this patch launch an xterm for GDB, The main
terminal continue to run the sub-shell as before. Exiting the sub-shell
will also kill the ovs-vswitchd under GDB (but not GDB itself currently)

Signed-off-by: Andy Zhou <azhou@nicira.com>
Acked-by: Ben Pfaff <blp@nicira.com>

3 files changed, 49 insertions, 4 deletions

diff --git a/tutorial/Tutorial.md b/tutorial/Tutorial.md
index d6a963b0f..d9e800475 100644
--- a/tutorial/Tutorial.md
+++ b/tutorial/Tutorial.md
@@ -104,6 +104,27 @@ The sandbox directory contains log files for the Open vSwitch dameons.
 You can examine them while you're running in the sandboxed environment
 or after you exit.
 
+Using GDB
+---------
+
+GDB support is not required to go through the tutorial. It is added in case
+user wants to explore the internals of OVS programs.
+
+GDB can already be used to debug any running process, with the usual
+'gdb <program> <process-id>' command.
+
+'ovs-sandbox' also has a '-g' option for launching ovs-vswitchd under GDB.
+This option can be handy for setting break points before ovs-vswitchd runs,
+or for catching early segfaults.
+
+To avoid GDB mangling with the sandbox sub shell terminal, 'ovs-sandbox'
+starts a new xterm to run each GDB session.  For systems that do not support
+X windows, GDB support is effectively disabled.
+
+When launching sandbox through the build tree's make file, the '-g' option
+can be passed via the 'SANDBOXFLAGS' environment variable.
+'make sandbox SANDBOXFLAGS=-g' will start the sandbox with ovs-vswitchd
+running under GDB in its own xterm if X is available.
 
 Motivation
 ----------
diff --git a/tutorial/automake.mk b/tutorial/automake.mk
index 3d22d7aa4..5af0aac47 100644
--- a/tutorial/automake.mk
+++ b/tutorial/automake.mk
@@ -9,4 +9,4 @@ EXTRA_DIST += \
 	tutorial/t-stage4
 
 sandbox: all
-	cd $(srcdir)/tutorial && MAKE=$(MAKE) ./ovs-sandbox -b $(abs_builddir)
+	cd $(srcdir)/tutorial && MAKE=$(MAKE) ./ovs-sandbox -b $(abs_builddir) $(SANDBOXFLAGS)
diff --git a/tutorial/ovs-sandbox b/tutorial/ovs-sandbox
index 45bb2346c..5663acd58 100755
--- a/tutorial/ovs-sandbox
+++ b/tutorial/ovs-sandbox
@@ -16,16 +16,36 @@
 
 set -e
 
-run () {
-    echo "$@"
+run() {
     (cd "$sandbox" && "$@") || exit 1
 }
 
+run_xterm() {
+    run xterm -e "$@" &
+}
+
+rungdb() {
+    under_gdb=$1
+    shift
+    # Remove the --detach and to put the process under gdb control.
+    # Also remove --vconsole:off to allow error message to show up
+    # on the console.
+    # Use "DISPLAY" variable to determine out if X is supported
+    if $under_gdb && [ "$DISPLAY" ]; then
+        args=`echo $@ |sed s/--detach//g | sed s/--vconsole:off//g`
+        run_xterm gdb --args $args
+    else
+        run $@
+    fi
+}
+
+gdb_vswitchd=false;
 builddir=
 srcdir=
 schema=
 installed=false
 built=false
+
 for option; do
     # This option-parsing mechanism borrowed from a Autoconf-generated
     # configure script under the following license:
@@ -63,6 +83,7 @@ These options force ovs-sandbox to use a particular OVS build:
   -s, --srcdir=DIR     specify Open vSwitch source directory
 These options force ovs-sandbox to use an installed Open vSwitch:
   -i, --installed      use installed Open vSwitch
+  -g, --gdb-vswitchd   run ovs-vswitchd under gdb
   -S, --schema=FILE    use FILE as vswitch.ovsschema
 
 Other options:
@@ -98,6 +119,9 @@ EOF
             prev=schema
             installed=:
             ;;
+        -g|--gdb-v*)
+            gdb_vswitchd=true
+            ;;
         -*)
             echo "unrecognized option $option (use --help for help)" >&2
             exit 1
@@ -204,7 +228,7 @@ run ovsdb-server --detach --no-chdir --pidfile -vconsole:off --log-file \
     --remote=punix:"$sandbox"/db.sock
 
 # Start ovs-vswitchd.
-run ovs-vswitchd --detach --no-chdir --pidfile -vconsole:off --log-file \
+rungdb $gdb_vswitchd ovs-vswitchd --detach --no-chdir --pidfile -vconsole:off --log-file \
     --enable-dummy=override -vvconn -vnetdev_dummy
 
 cat <<EOF