[PATCH for-5.0?] docs: Improve our gdbstub documentation

[PATCH for-5.0?] docs: Improve our gdbstub documentation

[Peter Maydell]

The documentation of our -s and -gdb options is quite old; in
particular it still claims that it will cause QEMU to stop and wait
for the gdb connection, when this has not been true for some time:
you also need to pass -S if you want to make QEMU not launch the
guest on startup.

Improve the documentation to mention this requirement in the
executable's --help output, the documentation of the -gdb option in
the manual, and in the "GDB usage" chapter.

Includes some minor tweaks to these paragraphs of documentation
since I was editing them anyway (such as dropping the description
of our gdb support as "primitive").

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
Maybe 5.0 material since it's just a docs improvement?

 docs/system/gdb.rst | 22 +++++++++++++++-------
 qemu-options.hx     | 24 ++++++++++++++++++------
 2 files changed, 33 insertions(+), 13 deletions(-)

diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst
index 639f814b32d..a40145fcf84 100644
--- a/docs/system/gdb.rst
+++ b/docs/system/gdb.rst
@@ -3,17 +3,25 @@
 GDB usage
 ---------
 
-QEMU has a primitive support to work with gdb, so that you can do
-'Ctrl-C' while the virtual machine is running and inspect its state.
+QEMU supports working with gdb via gdb's remote-connection facility
+(the "gdbstub"). This allows you to debug guest code in the same
+way that you might with a low-level debug facility like JTAG
+on real hardware. You can stop and start the virtual machine,
+examine state like registers and memory, and set breakpoints and
+watchpoints.
 
-In order to use gdb, launch QEMU with the '-s' option. It will wait for
-a gdb connection:
+In order to use gdb, launch QEMU with the ``-s`` and ``-S`` options.
+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``.)
 
 .. parsed-literal::
 
-   |qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
-   Connected to host network interface: tun0
-   Waiting gdb connection on port 1234
+   |qemu_system| -s -S -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
+
+QEMU will launch but will silently wait for gdb to connect.
 
 Then launch gdb on the 'vmlinux' executable::
 
diff --git a/qemu-options.hx b/qemu-options.hx
index 16debd03cb6..292d4e7c0ce 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -3680,14 +3680,26 @@ SRST
 ERST
 
 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
-    "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
+    "-gdb dev        accept gdb connection on 'dev'. (QEMU defaults to starting\n"
+    "                the guest without waiting for gdb to connect; use -S too\n"
+    "                if you want it to not start execution.)\n",
+    QEMU_ARCH_ALL)
 SRST
 ``-gdb dev``
-    Wait for gdb connection on device dev (see
-    :ref:`gdb_005fusage`). Typical connections will likely be
-    TCP-based, but also UDP, pseudo TTY, or even stdio are reasonable
-    use case. The latter is allowing to start QEMU from within gdb and
-    establish the connection via a pipe:
+    Accept a gdb connection on device dev (see
+    :ref:`gdb_005fusage`). Note that this option does not pause QEMU
+    execution -- if you want QEMU to not start the guest until you
+    connect with gdb and issue a ``continue`` command, you will need to
+    also pass the ``-S`` option to QEMU.
+
+    The most usual configuration is to listen on a local TCP socket::
+
+        -gdb tcp::3117
+
+    but you can specify other backends; UDP, pseudo TTY, or even stdio
+    are all reasonable use cases. For example, a stdio connection
+    allows you to start QEMU from within gdb and establish the
+    connection via a pipe:
 
     .. parsed-literal::
 
-- 
2.20.1

Re: [PATCH for-5.0?] docs: Improve our gdbstub documentation

[Philippe Mathieu-Daudé]

On 4/3/20 11:40 AM, Peter Maydell wrote:
> The documentation of our -s and -gdb options is quite old; in
> particular it still claims that it will cause QEMU to stop and wait
> for the gdb connection, when this has not been true for some time:
> you also need to pass -S if you want to make QEMU not launch the
> guest on startup.
> 
> Improve the documentation to mention this requirement in the
> executable's --help output, the documentation of the -gdb option in
> the manual, and in the "GDB usage" chapter.
> 
> Includes some minor tweaks to these paragraphs of documentation
> since I was editing them anyway (such as dropping the description
> of our gdb support as "primitive").
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> Maybe 5.0 material since it's just a docs improvement?
> 
>   docs/system/gdb.rst | 22 +++++++++++++++-------
>   qemu-options.hx     | 24 ++++++++++++++++++------
>   2 files changed, 33 insertions(+), 13 deletions(-)
> 
> diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst
> index 639f814b32d..a40145fcf84 100644
> --- a/docs/system/gdb.rst
> +++ b/docs/system/gdb.rst
> @@ -3,17 +3,25 @@
>   GDB usage
>   ---------
>   
> -QEMU has a primitive support to work with gdb, so that you can do
> -'Ctrl-C' while the virtual machine is running and inspect its state.
> +QEMU supports working with gdb via gdb's remote-connection facility
> +(the "gdbstub"). This allows you to debug guest code in the same
> +way that you might with a low-level debug facility like JTAG

"JTAG" is a standard, maybe replace by "JTAG adapter"?

> +on real hardware. You can stop and start the virtual machine,
> +examine state like registers and memory, and set breakpoints and
> +watchpoints.
>   
> -In order to use gdb, launch QEMU with the '-s' option. It will wait for
> -a gdb connection:
> +In order to use gdb, launch QEMU with the ``-s`` and ``-S`` options.
> +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``.)
>   
>   .. parsed-literal::
>   
> -   |qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
> -   Connected to host network interface: tun0
> -   Waiting gdb connection on port 1234
> +   |qemu_system| -s -S -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
> +
> +QEMU will launch but will silently wait for gdb to connect.
>   
>   Then launch gdb on the 'vmlinux' executable::
>   
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 16debd03cb6..292d4e7c0ce 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -3680,14 +3680,26 @@ SRST
>   ERST
>   
>   DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
> -    "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
> +    "-gdb dev        accept gdb connection on 'dev'. (QEMU defaults to starting\n"
> +    "                the guest without waiting for gdb to connect; use -S too\n"
> +    "                if you want it to not start execution.)\n",
> +    QEMU_ARCH_ALL)
>   SRST
>   ``-gdb dev``
> -    Wait for gdb connection on device dev (see
> -    :ref:`gdb_005fusage`). Typical connections will likely be
> -    TCP-based, but also UDP, pseudo TTY, or even stdio are reasonable
> -    use case. The latter is allowing to start QEMU from within gdb and
> -    establish the connection via a pipe:
> +    Accept a gdb connection on device dev (see
> +    :ref:`gdb_005fusage`). Note that this option does not pause QEMU
> +    execution -- if you want QEMU to not start the guest until you
> +    connect with gdb and issue a ``continue`` command, you will need to
> +    also pass the ``-S`` option to QEMU.
> +
> +    The most usual configuration is to listen on a local TCP socket::
> +
> +        -gdb tcp::3117

FYI OpenOCD uses 3333.

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

> +
> +    but you can specify other backends; UDP, pseudo TTY, or even stdio
> +    are all reasonable use cases. For example, a stdio connection
> +    allows you to start QEMU from within gdb and establish the
> +    connection via a pipe:
>   
>       .. parsed-literal::
>   
> 

Re: [PATCH for-5.0?] docs: Improve our gdbstub documentation

[Richard Henderson]

On 4/3/20 2:40 AM, Peter Maydell wrote:
> The documentation of our -s and -gdb options is quite old; in
> particular it still claims that it will cause QEMU to stop and wait
> for the gdb connection, when this has not been true for some time:
> you also need to pass -S if you want to make QEMU not launch the
> guest on startup.
> 
> Improve the documentation to mention this requirement in the
> executable's --help output, the documentation of the -gdb option in
> the manual, and in the "GDB usage" chapter.
> 
> Includes some minor tweaks to these paragraphs of documentation
> since I was editing them anyway (such as dropping the description
> of our gdb support as "primitive").
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> Maybe 5.0 material since it's just a docs improvement?

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

Re: [PATCH for-5.0?] docs: Improve our gdbstub documentation

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> The documentation of our -s and -gdb options is quite old; in
> particular it still claims that it will cause QEMU to stop and wait
> for the gdb connection, when this has not been true for some time:
> you also need to pass -S if you want to make QEMU not launch the
> guest on startup.
>
> Improve the documentation to mention this requirement in the
> executable's --help output, the documentation of the -gdb option in
> the manual, and in the "GDB usage" chapter.
>
> Includes some minor tweaks to these paragraphs of documentation
> since I was editing them anyway (such as dropping the description
> of our gdb support as "primitive").
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> Maybe 5.0 material since it's just a docs improvement?

Sure why not.

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée