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 49Debugging multicore machines 50============================ 51 52GDB's abstraction for debugging targets with multiple possible 53parallel flows of execution is a two layer one: it supports multiple 54"inferiors", each of which can have multiple "threads". When the QEMU 55machine has more than one CPU, QEMU exposes each CPU cluster as a 56separate "inferior", where each CPU within the cluster is a separate 57"thread". Most QEMU machine types have identical CPUs, so there is a 58single cluster which has all the CPUs in it. A few machine types are 59heterogenous and have multiple clusters: for example the ``sifive_u`` 60machine has a cluster with one E51 core and a second cluster with four 61U54 cores. Here the E51 is the only thread in the first inferior, and 62the U54 cores are all threads in the second inferior. 63 64When you connect gdb to the gdbstub, it will automatically 65connect to the first inferior; you can display the CPUs in this 66cluster using the gdb ``info thread`` command, and switch between 67them using gdb's usual thread-management commands. 68 69For multi-cluster machines, unfortunately gdb does not by default 70handle multiple inferiors, and so you have to explicitly connect 71to them. First, you must connect with the ``extended-remote`` 72protocol, not ``remote``:: 73 74 (gdb) target extended-remote localhost:1234 75 76Once connected, gdb will have a single inferior, for the 77first cluster. You need to create inferiors for the other 78clusters 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 90Once you've done this, ``info threads`` will show CPUs in 91all 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 98You probably also want to set gdb to ``schedule-multiple`` mode, 99so that when you tell gdb to ``continue`` it resumes all CPUs, 100not just those in the cluster you are currently working on:: 101 102 (gdb) set schedule-multiple on 103 104Using unix sockets 105================== 106 107An alternate method for connecting gdb to the QEMU gdbstub is to use 108a unix socket (if supported by your operating system). This is useful when 109running several tests in parallel, or if you do not have a known free TCP 110port (e.g. when running automated tests). 111 112First create a chardev with the appropriate options, then 113instruct 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 119Start gdb as before, but this time connect using the path to 120the socket:: 121 122 (gdb) target remote /tmp/gdb-socket 123 124Note that to use a unix socket for the connection you will need 125gdb version 9.0 or newer. 126 127Advanced debugging options 128========================== 129 130Changing single-stepping behaviour 131^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 132 133The default single stepping behavior is step with the IRQs and timer 134service routines off. It is set this way because when gdb executes a 135single step it expects to advance beyond the current instruction. With 136the IRQs and timer service routines on, a single step might jump into 137the one of the interrupt or exception vectors instead of executing the 138current instruction. This means you may hit the same breakpoint a number 139of times before executing the instruction gdb wants to have executed. 140Because there are rare circumstances where you want to single step into 141an interrupt vector the behavior can be controlled from GDB. There are 142three 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 174Examining physical memory 175^^^^^^^^^^^^^^^^^^^^^^^^^ 176 177Another feature that QEMU gdbstub provides is to toggle the memory GDB 178works with, by default GDB will show the current process memory respecting 179the virtual address translation. 180 181If you want to examine/change the physical memory you can set the gdbstub 182to work with the physical memory rather with the virtual one. 183 184The 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. 195