docs/system/gdb.rst

   1 .. _GDB usage:
   2
   3 GDB usage
   4 ---------
   5
   6 QEMU supports working with gdb via gdb's remote-connection facility
   7 (the "gdbstub"). This allows you to debug guest code in the same
   8 way that you might with a low-level debug facility like JTAG
   9 on real hardware. You can stop and start the virtual machine,
  10 examine state like registers and memory, and set breakpoints and
  11 watchpoints.
  12
  13 In order to use gdb, launch QEMU with the ``-s`` and ``-S`` options.
  14 The ``-s`` option will make QEMU listen for an incoming connection
  15 from gdb on TCP port 1234, and ``-S`` will make QEMU not start the
  16 guest until you tell it to from gdb. (If you want to specify which
  17 TCP port to use or to use something other than TCP for the gdbstub
  18 connection, use the ``-gdb dev`` option instead of ``-s``. See
  19 `Using unix sockets`_ for an example.)
  20
  21 .. parsed-literal::
  22
  23    |qemu_system| -s -S -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
  24
  25 QEMU will launch but will silently wait for gdb to connect.
  26
  27 Then launch gdb on the 'vmlinux' executable::
  28
  29    > gdb vmlinux
  30
  31 In gdb, connect to QEMU::
  32
  33    (gdb) target remote localhost:1234
  34
  35 Then you can use gdb normally. For example, type 'c' to launch the
  36 kernel::
  37
  38    (gdb) c
  39
  40 Here are some useful tips in order to use gdb on system code:
  41
  42 1. Use ``info reg`` to display all the CPU registers.
  43
  44 2. Use ``x/10i $eip`` to display the code at the PC position.
  45
  46 3. Use ``set architecture i8086`` to dump 16 bit code. Then use
  47    ``x/10i $cs*16+$eip`` to dump the code at the PC position.
  48
  49 Debugging multicore machines
  50 ============================
  51
  52 GDB's abstraction for debugging targets with multiple possible
  53 parallel flows of execution is a two layer one: it supports multiple
  54 "inferiors", each of which can have multiple "threads". When the QEMU
  55 machine has more than one CPU, QEMU exposes each CPU cluster as a
  56 separate "inferior", where each CPU within the cluster is a separate
  57 "thread". Most QEMU machine types have identical CPUs, so there is a
  58 single cluster which has all the CPUs in it.  A few machine types are
  59 heterogenous and have multiple clusters: for example the ``sifive_u``
  60 machine has a cluster with one E51 core and a second cluster with four
  61 U54 cores. Here the E51 is the only thread in the first inferior, and
  62 the U54 cores are all threads in the second inferior.
  63
  64 When you connect gdb to the gdbstub, it will automatically
  65 connect to the first inferior; you can display the CPUs in this
  66 cluster using the gdb ``info thread`` command, and switch between
  67 them using gdb's usual thread-management commands.
  68
  69 For multi-cluster machines, unfortunately gdb does not by default
  70 handle multiple inferiors, and so you have to explicitly connect
  71 to them. First, you must connect with the ``extended-remote``
  72 protocol, not ``remote``::
  73
  74     (gdb) target extended-remote localhost:1234
  75
  76 Once connected, gdb will have a single inferior, for the
  77 first cluster. You need to create inferiors for the other
  78 clusters and attach to them, like this::
  79
  80   (gdb) add-inferior
  81   Added inferior 2
  82   (gdb) inferior 2
  83   [Switching to inferior 2 [<null>] (<noexec>)]
  84   (gdb) attach 2
  85   Attaching to process 2
  86   warning: No executable has been specified and target does not support
  87   determining executable automatically.  Try using the "file" command.
  88   0x00000000 in ?? ()
  89
  90 Once you've done this, ``info threads`` will show CPUs in
  91 all the clusters you have attached to::
  92
  93   (gdb) info threads
  94     Id   Target Id         Frame
  95     1.1  Thread 1.1 (cortex-m33-arm-cpu cpu [running]) 0x00000000 in ?? ()
  96   * 2.1  Thread 2.2 (cortex-m33-arm-cpu cpu [halted ]) 0x00000000 in ?? ()
  97
  98 You probably also want to set gdb to ``schedule-multiple`` mode,
  99 so that when you tell gdb to ``continue`` it resumes all CPUs,
 100 not just those in the cluster you are currently working on::
 101
 102   (gdb) set schedule-multiple on
 103
 104 Using unix sockets
 105 ==================
 106
 107 An alternate method for connecting gdb to the QEMU gdbstub is to use
 108 a unix socket (if supported by your operating system). This is useful when
 109 running several tests in parallel, or if you do not have a known free TCP
 110 port (e.g. when running automated tests).
 111
 112 First create a chardev with the appropriate options, then
 113 instruct the gdbserver to use that device:
 114
 115 .. parsed-literal::
 116
 117    |qemu_system| -chardev socket,path=/tmp/gdb-socket,server=on,wait=off,id=gdb0 -gdb chardev:gdb0 -S ...
 118
 119 Start gdb as before, but this time connect using the path to
 120 the socket::
 121
 122    (gdb) target remote /tmp/gdb-socket
 123
 124 Note that to use a unix socket for the connection you will need
 125 gdb version 9.0 or newer.
 126
 127 Advanced debugging options
 128 ==========================
 129
 130 Changing single-stepping behaviour
 131 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 132
 133 The default single stepping behavior is step with the IRQs and timer
 134 service routines off. It is set this way because when gdb executes a
 135 single step it expects to advance beyond the current instruction. With
 136 the IRQs and timer service routines on, a single step might jump into
 137 the one of the interrupt or exception vectors instead of executing the
 138 current instruction. This means you may hit the same breakpoint a number
 139 of times before executing the instruction gdb wants to have executed.
 140 Because there are rare circumstances where you want to single step into
 141 an interrupt vector the behavior can be controlled from GDB. There are
 142 three commands you can query and set the single step behavior:
 143
 144 ``maintenance packet qqemu.sstepbits``
 145    This will display the MASK bits used to control the single stepping
 146    IE:
 147
 148    ::
 149
 150       (gdb) maintenance packet qqemu.sstepbits
 151       sending: "qqemu.sstepbits"
 152       received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
 153
 154 ``maintenance packet qqemu.sstep``
 155    This will display the current value of the mask used when single
 156    stepping IE:
 157
 158    ::
 159
 160       (gdb) maintenance packet qqemu.sstep
 161       sending: "qqemu.sstep"
 162       received: "0x7"
 163
 164 ``maintenance packet Qqemu.sstep=HEX_VALUE``
 165    This will change the single step mask, so if wanted to enable IRQs on
 166    the single step, but not timers, you would use:
 167
 168    ::
 169
 170       (gdb) maintenance packet Qqemu.sstep=0x5
 171       sending: "qemu.sstep=0x5"
 172       received: "OK"
 173
 174 Examining physical memory
 175 ^^^^^^^^^^^^^^^^^^^^^^^^^
 176
 177 Another feature that QEMU gdbstub provides is to toggle the memory GDB
 178 works with, by default GDB will show the current process memory respecting
 179 the virtual address translation.
 180
 181 If you want to examine/change the physical memory you can set the gdbstub
 182 to work with the physical memory rather with the virtual one.
 183
 184 The memory mode can be checked by sending the following command:
 185
 186 ``maintenance packet qqemu.PhyMemMode``
 187     This will return either 0 or 1, 1 indicates you are currently in the
 188     physical memory mode.
 189
 190 ``maintenance packet Qqemu.PhyMemMode:1``
 191     This will change the memory mode to physical memory.
 192
 193 ``maintenance packet Qqemu.PhyMemMode:0``
 194     This will change it back to normal memory mode.