The man page does not contain all the chapters from the System Emulation Users Guide, so some of the links that we've put into the qemu options descriptions can not be resolved and thus the link names are used in the man pages instead. These link names currently contain weird "_005f" letters in the middle and just do not make any sense for the users. To avoid this situation, replace the link names with more descriptive, natural text. Message-Id: <20201116145341.91606-1-thuth@redhat.com> Resolves: https://gitlab.com/qemu-project/qemu/-/issues/3 Buglink: https://bugs.launchpad.net/qemu/+bug/1453608 Signed-off-by: Thomas Huth <thuth@redhat.com>
110 lines
3.6 KiB
ReStructuredText
110 lines
3.6 KiB
ReStructuredText
.. _GDB usage:
|
|
|
|
GDB usage
|
|
---------
|
|
|
|
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`` 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 -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::
|
|
|
|
> gdb vmlinux
|
|
|
|
In gdb, connect to QEMU::
|
|
|
|
(gdb) target remote localhost:1234
|
|
|
|
Then you can use gdb normally. For example, type 'c' to launch the
|
|
kernel::
|
|
|
|
(gdb) c
|
|
|
|
Here are some useful tips in order to use gdb on system code:
|
|
|
|
1. Use ``info reg`` to display all the CPU registers.
|
|
|
|
2. Use ``x/10i $eip`` to display the code at the PC position.
|
|
|
|
3. Use ``set architecture i8086`` to dump 16 bit code. Then use
|
|
``x/10i $cs*16+$eip`` to dump the code at the PC position.
|
|
|
|
Advanced debugging options:
|
|
|
|
The default single stepping behavior is step with the IRQs and timer
|
|
service routines off. It is set this way because when gdb executes a
|
|
single step it expects to advance beyond the current instruction. With
|
|
the IRQs and timer service routines on, a single step might jump into
|
|
the one of the interrupt or exception vectors instead of executing the
|
|
current instruction. This means you may hit the same breakpoint a number
|
|
of times before executing the instruction gdb wants to have executed.
|
|
Because there are rare circumstances where you want to single step into
|
|
an interrupt vector the behavior can be controlled from GDB. There are
|
|
three commands you can query and set the single step behavior:
|
|
|
|
``maintenance packet qqemu.sstepbits``
|
|
This will display the MASK bits used to control the single stepping
|
|
IE:
|
|
|
|
::
|
|
|
|
(gdb) maintenance packet qqemu.sstepbits
|
|
sending: "qqemu.sstepbits"
|
|
received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
|
|
|
|
``maintenance packet qqemu.sstep``
|
|
This will display the current value of the mask used when single
|
|
stepping IE:
|
|
|
|
::
|
|
|
|
(gdb) maintenance packet qqemu.sstep
|
|
sending: "qqemu.sstep"
|
|
received: "0x7"
|
|
|
|
``maintenance packet Qqemu.sstep=HEX_VALUE``
|
|
This will change the single step mask, so if wanted to enable IRQs on
|
|
the single step, but not timers, you would use:
|
|
|
|
::
|
|
|
|
(gdb) maintenance packet Qqemu.sstep=0x5
|
|
sending: "qemu.sstep=0x5"
|
|
received: "OK"
|
|
|
|
|
|
Another feature that QEMU gdbstub provides is to toggle the memory GDB
|
|
works with, by default GDB will show the current process memory respecting
|
|
the virtual address translation.
|
|
|
|
If you want to examine/change the physical memory you can set the gdbstub
|
|
to work with the physical memory rather with the virtual one.
|
|
|
|
The memory mode can be checked by sending the following command:
|
|
|
|
``maintenance packet qqemu.PhyMemMode``
|
|
This will return either 0 or 1, 1 indicates you are currently in the
|
|
physical memory mode.
|
|
|
|
``maintenance packet Qqemu.PhyMemMode:1``
|
|
This will change the memory mode to physical memory.
|
|
|
|
``maintenance packet Qqemu.PhyMemMode:0``
|
|
This will change it back to normal memory mode.
|