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