From 24b1a6aa43615be22c7ee66bd68ec5675f6a6a9a Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Tue, 10 Aug 2021 18:04:36 +0200 Subject: [PATCH] docs: Document how to use gdb with unix sockets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit With gdb 9.0 and better it is possible to connect to a gdbstub over unix sockets, which is better than a TCP socket connection in some situations. The QEMU command line to set this up is non-obvious; document it. Signed-off-by: Sebastian Meyer Message-id: 162867284829.27377.4784930719350564918-0@git.sr.ht [PMM: Tweaked commit message; adjusted wording in a couple of places; fixed rST formatting issue; moved section up out of the 'advanced debugging options' subsection] Reviewed-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Peter Maydell --- docs/system/gdb.rst | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst index 144d083df3..bdb42dae2f 100644 --- a/docs/system/gdb.rst +++ b/docs/system/gdb.rst @@ -15,7 +15,8 @@ The ``-s`` option will make QEMU listen for an incoming connection from gdb on TCP port 1234, and ``-S`` will make QEMU not start the guest until you tell it to from gdb. (If you want to specify which TCP port to use or to use something other than TCP for the gdbstub -connection, use the ``-gdb dev`` option instead of ``-s``.) +connection, use the ``-gdb dev`` option instead of ``-s``. See +`Using unix sockets`_ for an example.) .. parsed-literal:: @@ -100,6 +101,29 @@ not just those in the cluster you are currently working on:: (gdb) set schedule-multiple on +Using unix sockets +================== + +An alternate method for connecting gdb to the QEMU gdbstub is to use +a unix socket (if supported by your operating system). This is useful when +running several tests in parallel, or if you do not have a known free TCP +port (e.g. when running automated tests). + +First create a chardev with the appropriate options, then +instruct the gdbserver to use that device: + +.. parsed-literal:: + + |qemu_system| -chardev socket,path=/tmp/gdb-socket,server=on,wait=off,id=gdb0 -gdb chardev:gdb0 -S ... + +Start gdb as before, but this time connect using the path to +the socket:: + + (gdb) target remote /tmp/gdb-socket + +Note that to use a unix socket for the connection you will need +gdb version 9.0 or newer. + Advanced debugging options ==========================