[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 07/12] docs: Improve our gdbstub documentation
From: |
Peter Maydell |
Subject: |
[PULL 07/12] docs: Improve our gdbstub documentation |
Date: |
Tue, 14 Apr 2020 17:26:08 +0100 |
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 <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Message-id: address@hidden
---
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
- [PULL 00/12] target-arm queue, Peter Maydell, 2020/04/14
- [PULL 01/12] osdep.h: Drop no-longer-needed Coverity workarounds, Peter Maydell, 2020/04/14
- [PULL 02/12] thread.h: Fix Coverity version of qemu_cond_timedwait(), Peter Maydell, 2020/04/14
- [PULL 03/12] thread.h: Remove trailing semicolons from Coverity qemu_mutex_lock() etc, Peter Maydell, 2020/04/14
- [PULL 04/12] linux-user/flatload.c: Use "" for include of QEMU header target_flat.h, Peter Maydell, 2020/04/14
- [PULL 10/12] kernel-doc: Use c:struct for Sphinx 3.0 and later, Peter Maydell, 2020/04/14
- [PULL 06/12] scripts/coverity-scan: Add Docker support, Peter Maydell, 2020/04/14
- [PULL 07/12] docs: Improve our gdbstub documentation,
Peter Maydell <=
- [PULL 05/12] scripts/run-coverity-scan: Script to run Coverity Scan build, Peter Maydell, 2020/04/14
- [PULL 11/12] docs: Require Sphinx 1.6 or better, Peter Maydell, 2020/04/14
- [PULL 12/12] Deprecate KVM support for AArch32, Peter Maydell, 2020/04/14
- [PULL 08/12] configure: Honour --disable-werror for Sphinx, Peter Maydell, 2020/04/14
- [PULL 09/12] scripts/kernel-doc: Add missing close-paren in c:function directives, Peter Maydell, 2020/04/14
- Re: [PULL 00/12] target-arm queue, Peter Maydell, 2020/04/14