1.. _gdb_005fusage: 2 3GDB usage 4--------- 5 6QEMU supports working with gdb via gdb's remote-connection facility 7(the "gdbstub"). This allows you to debug guest code in the same 8way that you might with a low-level debug facility like JTAG 9on real hardware. You can stop and start the virtual machine, 10examine state like registers and memory, and set breakpoints and 11watchpoints. 12 13In order to use gdb, launch QEMU with the ``-s`` and ``-S`` options. 14The ``-s`` option will make QEMU listen for an incoming connection 15from gdb on TCP port 1234, and ``-S`` will make QEMU not start the 16guest until you tell it to from gdb. (If you want to specify which 17TCP port to use or to use something other than TCP for the gdbstub 18connection, use the ``-gdb dev`` option instead of ``-s``.) 19 20.. parsed-literal:: 21 22 |qemu_system| -s -S -kernel bzImage -hda rootdisk.img -append "root=/dev/hda" 23 24QEMU will launch but will silently wait for gdb to connect. 25 26Then launch gdb on the 'vmlinux' executable:: 27 28 > gdb vmlinux 29 30In gdb, connect to QEMU:: 31 32 (gdb) target remote localhost:1234 33 34Then you can use gdb normally. For example, type 'c' to launch the 35kernel:: 36 37 (gdb) c 38 39Here are some useful tips in order to use gdb on system code: 40 411. Use ``info reg`` to display all the CPU registers. 42 432. Use ``x/10i $eip`` to display the code at the PC position. 44 453. Use ``set architecture i8086`` to dump 16 bit code. Then use 46 ``x/10i $cs*16+$eip`` to dump the code at the PC position. 47 48Advanced debugging options: 49 50The default single stepping behavior is step with the IRQs and timer 51service routines off. It is set this way because when gdb executes a 52single step it expects to advance beyond the current instruction. With 53the IRQs and timer service routines on, a single step might jump into 54the one of the interrupt or exception vectors instead of executing the 55current instruction. This means you may hit the same breakpoint a number 56of times before executing the instruction gdb wants to have executed. 57Because there are rare circumstances where you want to single step into 58an interrupt vector the behavior can be controlled from GDB. There are 59three commands you can query and set the single step behavior: 60 61``maintenance packet qqemu.sstepbits`` 62 This will display the MASK bits used to control the single stepping 63 IE: 64 65 :: 66 67 (gdb) maintenance packet qqemu.sstepbits 68 sending: "qqemu.sstepbits" 69 received: "ENABLE=1,NOIRQ=2,NOTIMER=4" 70 71``maintenance packet qqemu.sstep`` 72 This will display the current value of the mask used when single 73 stepping IE: 74 75 :: 76 77 (gdb) maintenance packet qqemu.sstep 78 sending: "qqemu.sstep" 79 received: "0x7" 80 81``maintenance packet Qqemu.sstep=HEX_VALUE`` 82 This will change the single step mask, so if wanted to enable IRQs on 83 the single step, but not timers, you would use: 84 85 :: 86 87 (gdb) maintenance packet Qqemu.sstep=0x5 88 sending: "qemu.sstep=0x5" 89 received: "OK" 90 91 92Another feature that QEMU gdbstub provides is to toggle the memory GDB 93works with, by default GDB will show the current process memory respecting 94the virtual address translation. 95 96If you want to examine/change the physical memory you can set the gdbstub 97to work with the physical memory rather with the virtual one. 98 99The memory mode can be checked by sending the following command: 100 101``maintenance packet qqemu.PhyMemMode`` 102 This will return either 0 or 1, 1 indicates you are currently in the 103 physical memory mode. 104 105``maintenance packet Qqemu.PhyMemMode:1`` 106 This will change the memory mode to physical memory. 107 108``maintenance packet Qqemu.PhyMemMode:0`` 109 This will change it back to normal memory mode. 110