From 324b2298feab35533d44301cfdae332c086463cf Mon Sep 17 00:00:00 2001 From: Paolo Bonzini Date: Fri, 28 Feb 2020 15:36:05 +0000 Subject: docs/system: convert Texinfo documentation to rST MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apart from targets.rst, which was written by hand, this is an automated conversion obtained with the following command: makeinfo --force -o - --docbook \ -D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \ -D 'qemu_system QEMU_SYSTEM_MACRO' \ $texi | pandoc -f docbook -t rst+smart | perl -e ' $/=undef; $_ = <>; s/^- − /- /gm; s/QEMU_SYSTEM_MACRO/|qemu_system|/g; s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g; s/(?=::\n\n +\|qemu)/.. parsed-literal/g; s/:\n\n::$/::/gm; print' > $rst In addition, the following changes were made manually: - target-i386.rst and target-mips.rst: replace CPU model documentation with an include directive - monitor.rst: replace the command section with a comment - images.rst: add toctree - target-arm.rst: Replace use of :math: (which Sphinx complains about) with :sup:, and hide it behind |I2C| and |I2C| substitutions. Content that is not @included remains exclusive to qemu-doc.texi. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell Reviewed-by: Alex Bennée Tested-by: Alex Bennée Signed-off-by: Peter Maydell Message-id: 20200228153619.9906-20-peter.maydell@linaro.org Message-id: 20200226113034.6741-19-pbonzini@redhat.com [PMM: Fixed target-arm.rst use of :math:; remove out of date note about images.rst from commit message; fixed expansion of |qemu_system_x86|; use parsed-literal in invocation.rst when we want to use |qemu_system_x86|; fix incorrect subsection level for "OS requirements" in target-i386.rst; fix incorrect syntax for making links to other sections of the manual] Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- docs/system/gdb.rst | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/system/gdb.rst (limited to 'docs/system/gdb.rst') diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst new file mode 100644 index 0000000..639f814 --- /dev/null +++ b/docs/system/gdb.rst @@ -0,0 +1,81 @@ +.. _gdb_005fusage: + +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. + +In order to use gdb, launch QEMU with the '-s' option. It will wait for +a gdb connection: + +.. 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 + +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" -- cgit v1.1