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 Breakpoint and Watchpoint support
  50 =================================
  51
  52 While GDB can always fall back to inserting breakpoints into memory
  53 (if writable) other features are very much dependent on support of the
  54 accelerator. For TCG system emulation we advertise an infinite number
  55 of hardware assisted breakpoints and watchpoints. For other
  56 accelerators it will depend on if support has been added (see
  57 supports_guest_debug and related hooks in AccelOpsClass).
  58
  59 As TCG cannot track all memory accesses in user-mode there is no
  60 support for watchpoints.
  61
  62 Relocating code
  63 ===============
  64
  65 On modern kernels confusion can be caused by code being relocated by
  66 features such as address space layout randomisation. To avoid
  67 confusion when debugging such things you either need to update gdb's
  68 view of where things are in memory or perhaps more trivially disable
  69 ASLR when booting the system.
  70
  71 Debugging user-space in system emulation
  72 ========================================
  73
  74 While it is technically possible to debug a user-space program running
  75 inside a system image, it does present challenges. Kernel preemption
  76 and execution mode changes between kernel and user mode can make it
  77 hard to follow what's going on. Unless you are specifically trying to
  78 debug some interaction between kernel and user-space you are better
  79 off running your guest program with gdb either in the guest or using
  80 a gdbserver exposed via a port to the outside world.
  81
  82 Debugging multicore machines
  83 ============================
  84
  85 GDB's abstraction for debugging targets with multiple possible
  86 parallel flows of execution is a two layer one: it supports multiple
  87 "inferiors", each of which can have multiple "threads". When the QEMU
  88 machine has more than one CPU, QEMU exposes each CPU cluster as a
  89 separate "inferior", where each CPU within the cluster is a separate
  90 "thread". Most QEMU machine types have identical CPUs, so there is a
  91 single cluster which has all the CPUs in it.  A few machine types are
  92 heterogeneous and have multiple clusters: for example the ``sifive_u``
  93 machine has a cluster with one E51 core and a second cluster with four
  94 U54 cores. Here the E51 is the only thread in the first inferior, and
  95 the U54 cores are all threads in the second inferior.
  96
  97 When you connect gdb to the gdbstub, it will automatically
  98 connect to the first inferior; you can display the CPUs in this
  99 cluster using the gdb ``info thread`` command, and switch between
 100 them using gdb's usual thread-management commands.
 101
 102 For multi-cluster machines, unfortunately gdb does not by default
 103 handle multiple inferiors, and so you have to explicitly connect
 104 to them. First, you must connect with the ``extended-remote``
 105 protocol, not ``remote``::
 106
 107     (gdb) target extended-remote localhost:1234
 108
 109 Once connected, gdb will have a single inferior, for the
 110 first cluster. You need to create inferiors for the other
 111 clusters and attach to them, like this::
 112
 113   (gdb) add-inferior
 114   Added inferior 2
 115   (gdb) inferior 2
 116   [Switching to inferior 2 [<null>] (<noexec>)]
 117   (gdb) attach 2
 118   Attaching to process 2
 119   warning: No executable has been specified and target does not support
 120   determining executable automatically.  Try using the "file" command.
 121   0x00000000 in ?? ()
 122
 123 Once you've done this, ``info threads`` will show CPUs in
 124 all the clusters you have attached to::
 125
 126   (gdb) info threads
 127     Id   Target Id         Frame
 128     1.1  Thread 1.1 (cortex-m33-arm-cpu cpu [running]) 0x00000000 in ?? ()
 129   * 2.1  Thread 2.2 (cortex-m33-arm-cpu cpu [halted ]) 0x00000000 in ?? ()
 130
 131 You probably also want to set gdb to ``schedule-multiple`` mode,
 132 so that when you tell gdb to ``continue`` it resumes all CPUs,
 133 not just those in the cluster you are currently working on::
 134
 135   (gdb) set schedule-multiple on
 136
 137 Using unix sockets
 138 ==================
 139
 140 An alternate method for connecting gdb to the QEMU gdbstub is to use
 141 a unix socket (if supported by your operating system). This is useful when
 142 running several tests in parallel, or if you do not have a known free TCP
 143 port (e.g. when running automated tests).
 144
 145 First create a chardev with the appropriate options, then
 146 instruct the gdbserver to use that device:
 147
 148 .. parsed-literal::
 149
 150    |qemu_system| -chardev socket,path=/tmp/gdb-socket,server=on,wait=off,id=gdb0 -gdb chardev:gdb0 -S ...
 151
 152 Start gdb as before, but this time connect using the path to
 153 the socket::
 154
 155    (gdb) target remote /tmp/gdb-socket
 156
 157 Note that to use a unix socket for the connection you will need
 158 gdb version 9.0 or newer.
 159
 160 Advanced debugging options
 161 ==========================
 162
 163 Changing single-stepping behaviour
 164 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 165
 166 The default single stepping behavior is step with the IRQs and timer
 167 service routines off. It is set this way because when gdb executes a
 168 single step it expects to advance beyond the current instruction. With
 169 the IRQs and timer service routines on, a single step might jump into
 170 the one of the interrupt or exception vectors instead of executing the
 171 current instruction. This means you may hit the same breakpoint a number
 172 of times before executing the instruction gdb wants to have executed.
 173 Because there are rare circumstances where you want to single step into
 174 an interrupt vector the behavior can be controlled from GDB. There are
 175 three commands you can query and set the single step behavior:
 176
 177 ``maintenance packet qqemu.sstepbits``
 178    This will display the MASK bits used to control the single stepping
 179    IE:
 180
 181    ::
 182
 183       (gdb) maintenance packet qqemu.sstepbits
 184       sending: "qqemu.sstepbits"
 185       received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
 186
 187 ``maintenance packet qqemu.sstep``
 188    This will display the current value of the mask used when single
 189    stepping IE:
 190
 191    ::
 192
 193       (gdb) maintenance packet qqemu.sstep
 194       sending: "qqemu.sstep"
 195       received: "0x7"
 196
 197 ``maintenance packet Qqemu.sstep=HEX_VALUE``
 198    This will change the single step mask, so if wanted to enable IRQs on
 199    the single step, but not timers, you would use:
 200
 201    ::
 202
 203       (gdb) maintenance packet Qqemu.sstep=0x5
 204       sending: "qemu.sstep=0x5"
 205       received: "OK"
 206
 207 Examining physical memory
 208 ^^^^^^^^^^^^^^^^^^^^^^^^^
 209
 210 Another feature that QEMU gdbstub provides is to toggle the memory GDB
 211 works with, by default GDB will show the current process memory respecting
 212 the virtual address translation.
 213
 214 If you want to examine/change the physical memory you can set the gdbstub
 215 to work with the physical memory rather with the virtual one.
 216
 217 The memory mode can be checked by sending the following command:
 218
 219 ``maintenance packet qqemu.PhyMemMode``
 220     This will return either 0 or 1, 1 indicates you are currently in the
 221     physical memory mode.
 222
 223 ``maintenance packet Qqemu.PhyMemMode:1``
 224     This will change the memory mode to physical memory.
 225
 226 ``maintenance packet Qqemu.PhyMemMode:0``
 227     This will change it back to normal memory mode.
 228
 229 Security considerations
 230 =======================
 231
 232 Connecting to the GDB socket allows running arbitrary code inside the guest;
 233 in case of the TCG emulation, which is not considered a security boundary, this
 234 also means running arbitrary code on the host. Additionally, when debugging
 235 qemu-user, it allows directly downloading any file readable by QEMU from the
 236 host.
 237
 238 The GDB socket is not protected by authentication, authorization or encryption.
 239 It is therefore a responsibility of the user to make sure that only authorized
 240 clients can connect to it, e.g., by using a unix socket with proper
 241 permissions, or by opening a TCP socket only on interfaces that are not
 242 reachable by potential attackers.