docs/system/gdb.rst

   1 .. _gdb_005fusage:
   2
   3 GDB usage
   4 ---------
   5
   6 QEMU has a primitive support to work with gdb, so that you can do
   7 'Ctrl-C' while the virtual machine is running and inspect its state.
   8
   9 In order to use gdb, launch QEMU with the '-s' option. It will wait for
  10 a gdb connection:
  11
  12 .. parsed-literal::
  13
  14    |qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
  15    Connected to host network interface: tun0
  16    Waiting gdb connection on port 1234
  17
  18 Then launch gdb on the 'vmlinux' executable::
  19
  20    > gdb vmlinux
  21
  22 In gdb, connect to QEMU::
  23
  24    (gdb) target remote localhost:1234
  25
  26 Then you can use gdb normally. For example, type 'c' to launch the
  27 kernel::
  28
  29    (gdb) c
  30
  31 Here are some useful tips in order to use gdb on system code:
  32
  33 1. Use ``info reg`` to display all the CPU registers.
  34
  35 2. Use ``x/10i $eip`` to display the code at the PC position.
  36
  37 3. Use ``set architecture i8086`` to dump 16 bit code. Then use
  38    ``x/10i $cs*16+$eip`` to dump the code at the PC position.
  39
  40 Advanced debugging options:
  41
  42 The default single stepping behavior is step with the IRQs and timer
  43 service routines off. It is set this way because when gdb executes a
  44 single step it expects to advance beyond the current instruction. With
  45 the IRQs and timer service routines on, a single step might jump into
  46 the one of the interrupt or exception vectors instead of executing the
  47 current instruction. This means you may hit the same breakpoint a number
  48 of times before executing the instruction gdb wants to have executed.
  49 Because there are rare circumstances where you want to single step into
  50 an interrupt vector the behavior can be controlled from GDB. There are
  51 three commands you can query and set the single step behavior:
  52
  53 ``maintenance packet qqemu.sstepbits``
  54    This will display the MASK bits used to control the single stepping
  55    IE:
  56
  57    ::
  58
  59       (gdb) maintenance packet qqemu.sstepbits
  60       sending: "qqemu.sstepbits"
  61       received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
  62
  63 ``maintenance packet qqemu.sstep``
  64    This will display the current value of the mask used when single
  65    stepping IE:
  66
  67    ::
  68
  69       (gdb) maintenance packet qqemu.sstep
  70       sending: "qqemu.sstep"
  71       received: "0x7"
  72
  73 ``maintenance packet Qqemu.sstep=HEX_VALUE``
  74    This will change the single step mask, so if wanted to enable IRQs on
  75    the single step, but not timers, you would use:
  76
  77    ::
  78
  79       (gdb) maintenance packet Qqemu.sstep=0x5
  80       sending: "qemu.sstep=0x5"
  81       received: "OK"