OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

docs: Improve our gdbstub documentation

Browse Source 
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>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Message-id: 20200403094014.9589-1-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell 2020-04-03 10:40:14 +01:00
parent 9edfa3580f
commit e5910d42dd
2 changed files with 33 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/system/gdb.rst
View File

@ -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::

24
qemu-options.hx
View File

@ -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::