gdbserver: get back to life

run-gdbserver is dead, converted to ./run --gdbserver --userland

I'm so happy, this refactor was so easy due to previous good code structure.

Fix https://github.com/cirosantilli/linux-kernel-module-cheat/issues/63

README.adoc

@@ -2588,10 +2588,10 @@ First build `gdbserver` into the root filesystem:
 ./build-buildroot --config 'BR2_PACKAGE_GDB=y'
 ....
 
-Then on guest, to debug link:userland/linux/myinsmod.c[]:
+Then on guest, to debug link:userland/linux/rand_check.c[]:
 
 ....
-./gdbserver.sh ./linux/myinsmod.out hello.ko
+./gdbserver.sh ./c/print_argv.out asdf qwer
 ....
 
 Source: link:rootfs_overlay/lkmc/gdbserver.sh[].
@@ -2599,13 +2599,13 @@ Source: link:rootfs_overlay/lkmc/gdbserver.sh[].
 And on host:
 
 ....
-./run-gdbserver userland/linux/myinsmod.c
+./run-gdb --gdbserver --userland userland/c/print_argv.c main
 ....
 
 or alternatively with the path to the executable itself:
 
 ....
-./run-gdbserver "$(./getvar userland_build_dir)/linux/myinsmod.out"
+./run --gdbserver --userland "$(./getvar userland_build_dir)/c/print_argv.out"
 ....
 
 Bibliography: https://reverseengineering.stackexchange.com/questions/8829/cross-debugging-for-arm-mips-elf-with-qemu-toolchain/16214#16214
@@ -2621,7 +2621,7 @@ Analogous to <<gdb-step-debug-userland-processes>>:
 on host you need:
 
 ....
-./run-gdbserver "$(./getvar buildroot_build_build_dir)"/busybox-*/busybox ls_main
+./run-gdb --gdbserver --userland "$(./getvar buildroot_build_build_dir)"/busybox-*/busybox ls_main
 ....
 
 === gdbserver libc
@@ -2631,13 +2631,13 @@ Our setup gives you the rare opportunity to step debug libc and other system lib
 For example in the guest:
 
 ....
-./gdbserver.sh ./count.out
+./gdbserver.sh ./posix/count.out
 ....
 
 Then on host:
 
 ....
-./run-gdbserver count
+./run-gdb --gdbserver --userland userland/posix/count.c main
 ....
 
 and inside GDB:
@@ -3599,7 +3599,7 @@ Or alternatively, if you are using <<tmux>>, do everything in one go with:
 ;
 ....
 
-To stop at the very first instruction of a freestanding program, just use `--no-continue` TODO example.
+To stop at the very first instruction of a freestanding program, just use `--no-continue`. A good example of this is shown at: <<freestanding-programs>>.
 
 === User mode tests
 

run-gdb

@@ -85,31 +85,49 @@ Connect with GDB to an emulator to debug Linux itself
         self.add_argument(
             '--after',
             default='',
-            help='Pass extra arguments to GDB, to be appended after all other arguments'
+            help='''Pass extra arguments to GDB, to be appended after all other arguments.'''
         )
         self.add_argument(
             '--before',
             default='',
-            help='Pass extra arguments to GDB to be prepended before any of the arguments passed by this script'
+            help='''Pass extra arguments to GDB to be prepended before any of the arguments passed by this script.'''
         )
         self.add_argument(
             '--continue',
             default=True,
-            help="Don't run continue after connecting"
+            help='''\
+Run `continue` in GDB after connecting.
+* https://github.com/cirosantilli/linux-kernel-module-cheat#gdb-step-debug-early-boot
+* https://github.com/cirosantilli/linux-kernel-module-cheat#freestanding-programs
+* https://github.com/cirosantilli/linux-kernel-module-cheat#baremetal-gdb-step-debug
+'''
+        )
+        self.add_argument(
+            '--gdbserver',
+            default=False,
+            help='''https://github.com/cirosantilli/linux-kernel-module-cheat#gdbserver'''
         )
         self.add_argument(
             '--kgdb',
             default=False,
+            help='''https://github.com/cirosantilli/linux-kernel-module-cheat#kgdb'''
         )
         self.add_argument(
             '--lxsymbols',
             default=True,
+            help='''\
+Use the Linux kernel lxsymbols GDB script.
+Only enabled by default when debugging the Linux kernel, not on userland or baremetal.
+* https://github.com/cirosantilli/linux-kernel-module-cheat#gdb-step-debug-kernel-module
+* https://github.com/cirosantilli/linux-kernel-module-cheat#bypass-lx-symbols
+'''
         )
         self.add_argument(
             '--sim',
             default=False,
-            help='''Use the built-in GDB CPU simulator
+            help='''\
-See: https://github.com/cirosantilli/linux-kernel-module-cheat#gdb-builtin-cpu-simulator
+Use the built-in GDB CPU simulator.
+https://github.com/cirosantilli/linux-kernel-module-cheat#gdb-builtin-cpu-simulator
 '''
         )
         self.add_argument(
@@ -123,7 +141,10 @@ the script is a .py file next to the source code.
         self.add_argument(
             'break_at',
             nargs='?',
-            help='Extra options to append at the end of the emulator command line'
+            help='''\
+If given, break at the given expression, e.g. `main`. You will be left there automatically
+by default due to --continue if this breakpoint is reached.
+'''
         )
 
     def timed_main(self):
@@ -152,6 +173,10 @@ the script is a .py file next to the source code.
         if self.env['userland']:
             image = self.env['image']
             linux_full_system = False
+            if self.env['gdbserver']:
+                before.extend([
+                    '-ex', 'set sysroot {}'.format(self.env['buildroot_staging_dir']),
+                ])
         elif self.env['baremetal']:
             image = self.env['image']
             linux_full_system = False
@@ -167,7 +192,9 @@ the script is a .py file next to the source code.
         if self.env['sim']:
             target = 'sim'
         else:
-            if self.env['kgdb']:
+            if self.env['gdbserver']:
+                port = self.env['qemu_hostfwd_generic_port']
+            elif self.env['kgdb']:
                 port = self.env['extra_serial_port']
             else:
                 port = self.env['gdb_port']

run-gdbserver

@@ -1,29 +0,0 @@
-#!/usr/bin/env python3
-
-import os
-import subprocess
-import sys
-
-import common
-from shell_helpers import LF
-
-parser = self.get_argparse(argparse_args={
-    'description':'Connect to gdbserver running on the guest.'
-})
-parser.add_argument(
-    'executable',
-    help='Path to the executable to be debugged relative to the Buildroot build directory.'
-)
-parser.add_argument(
-    'break_at', default='main', nargs='?'
-)
-args = self.setup(parser)
-sys.exit(subprocess.Popen([
-  self.env['gdb_path'],
-  '-q',
-  '-ex', 'set sysroot {}'.format(kwargs['buildroot_staging_dir']),
-  '-ex', 'target remote localhost:{}'.format(kwargs['qemu_hostfwd_generic_port']),
-  '-ex', 'tbreak {}'.format(kwargs['break_at']),
-  '-ex', 'continue',
-  os.path.join(kwargs['buildroot_build_build_dir'], self.resolve_userland_executable(kwargs['executable'])),
-]).wait())