gdbremote: Initial (and minimal) support for remote debugging

_drgn.pyi

@@ -669,6 +669,14 @@ class Program:
         """
         ...
 
+    def set_gdbremote(self, conn: str) -> None:
+        """
+        Set the program to the specificed elffile and connect to a gdbserver.
+
+        :param conn: gdb connection string (e.g. localhost:2345)
+        """
+        ...
+
     def set_kernel(self) -> None:
         """
         Set the program to the running operating system kernel.
@@ -1067,6 +1075,11 @@ class ProgramFlags(enum.Flag):
     The program is running on the local machine.
     """
 
+    IS_GDBREMOTE = ...
+    """
+    The program is connected via the gdbremote protocol.
+    """
+
 class FindObjectFlags(enum.Flag):
     """
     ``FindObjectFlags`` are flags for :meth:`Program.object()`. These can be

docs/advanced_usage.rst

@@ -217,3 +217,52 @@ core dumps. These special objects include:
     distinguish it from the kernel variable ``vmcoreinfo_data``.
 
     This is available without debugging information.
+
+Debugging via the gdbremote protocol
+------------------------------------
+
+The
+`gdbremote protocol <https://sourceware.org/gdb/current/onlinedocs/gdb.html/Remote-Protocol.html>`_
+makes it possible to run drgn on one machine and use it to debug code running
+on another system. drgn implements the client side of the protocol and can
+connect via gdbremote to a variety of different gdbremote "server"
+implementations including
+`gdbserver <https://sourceware.org/gdb/current/onlinedocs/gdb.html/Server.html>`_,
+`kgdb <https://www.kernel.org/doc/html/latest/dev-tools/kgdb.html>`_,
+`OpenOCD <https://openocd.org/>`_
+and the
+`QEMU gdbstub <https://qemu-project.gitlab.io/qemu/system/gdb.html>`_.
+
+Currently the gdbremote support in drgn is absolutely minimal:
+
+* drgn can only connect to network sockets (use socat to bridge to stubs
+  that are not networked)
+* only a single thread is supported
+* there is no support for automatically handle address space layout
+  randomization (ASLR)
+* register packet decoding is implemented only for AArch64
+
+However, even this minimal support is sufficient to connect to the gdbserver,
+read memory and generate a stack trace using AArch64 frame pointers::
+
+    sh$ drgn --gdbremote localhost:2345 --symbols ./hello
+    drgn 0.0.27+67.ge8a745c3 (using Python 3.11.2, elfutils 0.188, without libkdumpfile)
+    For help, type help(drgn).
+    >>> import drgn
+    >>> from drgn import FaultError, NULL, Object, cast, container_of, execscript, offsetof, reinterpret, sizeof, stack_trace
+    >>> from drgn.helpers.common import *
+    >>> prog['main']
+    (int (int argc, const char **argv))0x754
+    >>> prog.threads()
+    <_drgn._ThreadIterator object at 0x7f81b570d0>
+    >>> prog.main_thread().stack_trace()
+    #0  0x5555550764     <--- Symbol lookup currently fails due to ASLR offsets
+    #1  0x7ff7e17740
+    #2  0x7ff7e17818
+    >>> prog.main_thread().stack_trace()[0].registers()['x0']
+    1
+    >>> argv = prog.main_thread().stack_trace()[0].registers()['x1']
+    >>> argv0 = prog.read_u64(argv)
+    >>> prog.read(argv0, 8)
+    b'./hello\x00'
+    >>>

drgn/cli.py

@@ -178,6 +178,12 @@ def _main() -> None:
     program_group.add_argument(
         "-c", "--core", metavar="PATH", type=str, help="debug the given core dump"
     )
+    program_group.add_argument(
+        "--gdbremote",
+        metavar="CONN",
+        type=str,
+        help="connect to the specified gdbserver",
+    )
     program_group.add_argument(
         "-p",
         "--pid",
@@ -295,6 +301,12 @@ def _main() -> None:
                 sys.exit(
                     f"{e}\nerror: attaching to live process requires ptrace attach permissions"
                 )
+        elif args.gdbremote is not None:
+            prog.set_gdbremote(args.gdbremote)
+
+            # Suppress default symbol loading (at present, gdbremote always
+            # needs to get symbols from --symbols)
+            args.default_symbols = {}
         else:
             try:
                 prog.set_kernel()

libdrgn/Makefile.am

@@ -71,6 +71,8 @@ libdrgnimpl_la_SOURCES = $(ARCH_DEFS_PYS:_defs.py=.c) \
 			 hash_table.c \
 			 hash_table.h \
 			 helpers.h \
+			 gdbremote.c \
+			 gdbremote.h \
 			 io.c \
 			 io.h \
 			 kallsyms.c \

libdrgn/arch_aarch64.c

@@ -229,6 +229,17 @@ linux_kernel_get_initial_registers_aarch64(const struct drgn_object *task_obj,
 	return NULL;
 }
 
+static struct drgn_error *
+gdbremote_get_initial_registers_aarch64(struct drgn_program *prog,
+					const void *regs, size_t reglen,
+					struct drgn_register_state **ret)
+{
+	// gdbremote uses the same binary format as struct user_pt_reg
+	// so we can just reuse that code.
+	return get_initial_registers_from_struct_aarch64(prog, regs, reglen,
+							 ret);
+}
+
 static struct drgn_error *
 apply_elf_reloc_aarch64(const struct drgn_relocating_section *relocating,
 			uint64_t r_offset, uint32_t r_type, const int64_t *r_addend,
@@ -495,6 +506,7 @@ const struct drgn_architecture_info arch_info_aarch64 = {
 	.prstatus_get_initial_registers = prstatus_get_initial_registers_aarch64,
 	.linux_kernel_get_initial_registers =
 		linux_kernel_get_initial_registers_aarch64,
+	.gdbremote_get_initial_registers = gdbremote_get_initial_registers_aarch64,
 	.apply_elf_reloc = apply_elf_reloc_aarch64,
 	.linux_kernel_pgtable_iterator_create =
 		linux_kernel_pgtable_iterator_create_aarch64,

libdrgn/drgn.h

@@ -522,6 +522,8 @@ enum drgn_program_flags {
 	DRGN_PROGRAM_IS_LIVE = (1 << 1),
 	/** The program is running on the local machine. */
 	DRGN_PROGRAM_IS_LOCAL = (1 << 2),
+	/** The program is connected via the gdbremote protocol. */
+	DRGN_PROGRAM_IS_GDBREMOTE = (1 << 3),
 };
 
 /**
@@ -802,6 +804,15 @@ struct drgn_error *drgn_program_set_core_dump(struct drgn_program *prog,
  */
 struct drgn_error *drgn_program_set_core_dump_fd(struct drgn_program *prog, int fd);
 
+/**
+ * Set a @ref drgn_program to a gdbremote server.
+ *
+ * @param[in] conn gdb connection string (e.g. localhost:2345)
+ * @return @c NULL on success, non-@c NULL on error.
+ */
+struct drgn_error *drgn_program_set_gdbremote(struct drgn_program *prog,
+					      const char *conn);
+
 /**
  * Set a @ref drgn_program to the running operating system kernel.
  *