From e5910d42dd7a12c66c3a0b050d5f1d2b00b99ea8 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Fri, 3 Apr 2020 10:40:14 +0100 Subject: [PATCH] docs: Improve our gdbstub documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Richard Henderson Reviewed-by: Alex Bennée Message-id: 20200403094014.9589-1-peter.maydell@linaro.org --- 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 639f814b32..a40145fcf8 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 16debd03cb..292d4e7c0c 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::