| 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 -drive file=rootdisk.img,format=raw -append "root=/dev/sda" |
| 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 | the AccelGdbConfig structure). |
| 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. |