1324b2298SPaolo Bonzini.. _gdb_005fusage: 2324b2298SPaolo Bonzini 3324b2298SPaolo BonziniGDB usage 4324b2298SPaolo Bonzini--------- 5324b2298SPaolo Bonzini 6*e5910d42SPeter MaydellQEMU supports working with gdb via gdb's remote-connection facility 7*e5910d42SPeter Maydell(the "gdbstub"). This allows you to debug guest code in the same 8*e5910d42SPeter Maydellway that you might with a low-level debug facility like JTAG 9*e5910d42SPeter Maydellon real hardware. You can stop and start the virtual machine, 10*e5910d42SPeter Maydellexamine state like registers and memory, and set breakpoints and 11*e5910d42SPeter Maydellwatchpoints. 12324b2298SPaolo Bonzini 13*e5910d42SPeter MaydellIn order to use gdb, launch QEMU with the ``-s`` and ``-S`` options. 14*e5910d42SPeter MaydellThe ``-s`` option will make QEMU listen for an incoming connection 15*e5910d42SPeter Maydellfrom gdb on TCP port 1234, and ``-S`` will make QEMU not start the 16*e5910d42SPeter Maydellguest until you tell it to from gdb. (If you want to specify which 17*e5910d42SPeter MaydellTCP port to use or to use something other than TCP for the gdbstub 18*e5910d42SPeter Maydellconnection, use the ``-gdb dev`` option instead of ``-s``.) 19324b2298SPaolo Bonzini 20324b2298SPaolo Bonzini.. parsed-literal:: 21324b2298SPaolo Bonzini 22*e5910d42SPeter Maydell |qemu_system| -s -S -kernel bzImage -hda rootdisk.img -append "root=/dev/hda" 23*e5910d42SPeter Maydell 24*e5910d42SPeter MaydellQEMU will launch but will silently wait for gdb to connect. 25324b2298SPaolo Bonzini 26324b2298SPaolo BonziniThen launch gdb on the 'vmlinux' executable:: 27324b2298SPaolo Bonzini 28324b2298SPaolo Bonzini > gdb vmlinux 29324b2298SPaolo Bonzini 30324b2298SPaolo BonziniIn gdb, connect to QEMU:: 31324b2298SPaolo Bonzini 32324b2298SPaolo Bonzini (gdb) target remote localhost:1234 33324b2298SPaolo Bonzini 34324b2298SPaolo BonziniThen you can use gdb normally. For example, type 'c' to launch the 35324b2298SPaolo Bonzinikernel:: 36324b2298SPaolo Bonzini 37324b2298SPaolo Bonzini (gdb) c 38324b2298SPaolo Bonzini 39324b2298SPaolo BonziniHere are some useful tips in order to use gdb on system code: 40324b2298SPaolo Bonzini 41324b2298SPaolo Bonzini1. Use ``info reg`` to display all the CPU registers. 42324b2298SPaolo Bonzini 43324b2298SPaolo Bonzini2. Use ``x/10i $eip`` to display the code at the PC position. 44324b2298SPaolo Bonzini 45324b2298SPaolo Bonzini3. Use ``set architecture i8086`` to dump 16 bit code. Then use 46324b2298SPaolo Bonzini ``x/10i $cs*16+$eip`` to dump the code at the PC position. 47324b2298SPaolo Bonzini 48324b2298SPaolo BonziniAdvanced debugging options: 49324b2298SPaolo Bonzini 50324b2298SPaolo BonziniThe default single stepping behavior is step with the IRQs and timer 51324b2298SPaolo Bonziniservice routines off. It is set this way because when gdb executes a 52324b2298SPaolo Bonzinisingle step it expects to advance beyond the current instruction. With 53324b2298SPaolo Bonzinithe IRQs and timer service routines on, a single step might jump into 54324b2298SPaolo Bonzinithe one of the interrupt or exception vectors instead of executing the 55324b2298SPaolo Bonzinicurrent instruction. This means you may hit the same breakpoint a number 56324b2298SPaolo Bonziniof times before executing the instruction gdb wants to have executed. 57324b2298SPaolo BonziniBecause there are rare circumstances where you want to single step into 58324b2298SPaolo Bonzinian interrupt vector the behavior can be controlled from GDB. There are 59324b2298SPaolo Bonzinithree commands you can query and set the single step behavior: 60324b2298SPaolo Bonzini 61324b2298SPaolo Bonzini``maintenance packet qqemu.sstepbits`` 62324b2298SPaolo Bonzini This will display the MASK bits used to control the single stepping 63324b2298SPaolo Bonzini IE: 64324b2298SPaolo Bonzini 65324b2298SPaolo Bonzini :: 66324b2298SPaolo Bonzini 67324b2298SPaolo Bonzini (gdb) maintenance packet qqemu.sstepbits 68324b2298SPaolo Bonzini sending: "qqemu.sstepbits" 69324b2298SPaolo Bonzini received: "ENABLE=1,NOIRQ=2,NOTIMER=4" 70324b2298SPaolo Bonzini 71324b2298SPaolo Bonzini``maintenance packet qqemu.sstep`` 72324b2298SPaolo Bonzini This will display the current value of the mask used when single 73324b2298SPaolo Bonzini stepping IE: 74324b2298SPaolo Bonzini 75324b2298SPaolo Bonzini :: 76324b2298SPaolo Bonzini 77324b2298SPaolo Bonzini (gdb) maintenance packet qqemu.sstep 78324b2298SPaolo Bonzini sending: "qqemu.sstep" 79324b2298SPaolo Bonzini received: "0x7" 80324b2298SPaolo Bonzini 81324b2298SPaolo Bonzini``maintenance packet Qqemu.sstep=HEX_VALUE`` 82324b2298SPaolo Bonzini This will change the single step mask, so if wanted to enable IRQs on 83324b2298SPaolo Bonzini the single step, but not timers, you would use: 84324b2298SPaolo Bonzini 85324b2298SPaolo Bonzini :: 86324b2298SPaolo Bonzini 87324b2298SPaolo Bonzini (gdb) maintenance packet Qqemu.sstep=0x5 88324b2298SPaolo Bonzini sending: "qemu.sstep=0x5" 89324b2298SPaolo Bonzini received: "OK" 90