| Message ID | 20200403094014.9589-1-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [for-5.0?] docs: Improve our gdbstub documentation | expand |
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:: > >
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~
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
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::
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(-) -- 2.20.1