From: Sebastian Meyer <meyer@absint.com>

This includes the changes suggested by Philippe.
I kept the `-S` in the command line. The user shall
use that instead of `wait=on`.

Signed-off-by: Sebastian Meyer <meyer@absint.com>
---
 docs/system/gdb.rst | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst
index 144d083df3..f7411cb8ed 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::
 
@@ -168,3 +169,24 @@ The memory mode can be checked by sending the following command:
 
 ``maintenance packet Qqemu.PhyMemMode:0``
     This will change it back to normal memory mode.
+
+Using unix sockets
+^^^^^^^^^^^^^^^^^^
+
+An alternate method for connecting gdb to the QEMU gdbstub are unix
+sockets (if supported by your operating system). This is useful when
+running several tests in parallel and/or you do not have a free TCP
+port a priori (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 gdb version 9.0 or newer is required.
-- 
2.32.0

On Wed, 11 Aug 2021 at 10:10, ~archi42 <archi42@git.sr.ht> wrote:
>
> From: Sebastian Meyer <meyer@absint.com>
>
> This includes the changes suggested by Philippe.
> I kept the `-S` in the command line. The user shall
> use that instead of `wait=on`.
>
> Signed-off-by: Sebastian Meyer <meyer@absint.com>

Thanks; I've applied this to target-arm.next for 6.2.

I made a few minor tweaks to the commit message and the wording
of the docs, and fixed a rST format error (a stray double-colon
meant that the text ".. parsed-literal::" was put in the output
verbatim). You can look at the fixed-up version of the commit
here if you like:

https://git.linaro.org/people/peter.maydell/qemu-arm.git/commit/?h=target-arm.next&id=80acb580a7c98300248794d59bd98a31fb1b1bd9

-- PMM

On 8/23/21 12:39 PM, Peter Maydell wrote:
> On Wed, 11 Aug 2021 at 10:10, ~archi42 <archi42@git.sr.ht> wrote:
>>
>> From: Sebastian Meyer <meyer@absint.com>
>>
>> This includes the changes suggested by Philippe.
>> I kept the `-S` in the command line. The user shall
>> use that instead of `wait=on`.
>>
>> Signed-off-by: Sebastian Meyer <meyer@absint.com>
> 
> Thanks; I've applied this to target-arm.next for 6.2.
> 
> I made a few minor tweaks to the commit message and the wording
> of the docs, and fixed a rST format error (a stray double-colon
> meant that the text ".. parsed-literal::" was put in the output
> verbatim). You can look at the fixed-up version of the commit
> here if you like:
> 
> https://git.linaro.org/people/peter.maydell/qemu-arm.git/commit/?h=target-arm.next&id=80acb580a7c98300248794d59bd98a31fb1b1bd9

Sorry I missed the patch because I was not Cc'ed.

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>