]>
Commit | Line | Data |
---|---|---|
923e9311 | 1 | .. _GDB usage: |
324b2298 PB |
2 | |
3 | GDB usage | |
4 | --------- | |
5 | ||
e5910d42 PM |
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 | |
24b1a6aa SM |
18 | connection, use the ``-gdb dev`` option instead of ``-s``. See |
19 | `Using unix sockets`_ for an example.) | |
324b2298 PB |
20 | |
21 | .. parsed-literal:: | |
22 | ||
e5910d42 PM |
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. | |
324b2298 PB |
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 | ||
ab9d29b0 AB |
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 | |
84dd7d88 | 63 | =============== |
ab9d29b0 AB |
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 | ||
84dd7d88 AB |
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 | ||
d211556f PM |
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 | |
b980c1ae | 92 | heterogeneous and have multiple clusters: for example the ``sifive_u`` |
d211556f PM |
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 | ||
24b1a6aa SM |
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 | ||
acb0a27e PM |
160 | Advanced debugging options |
161 | ========================== | |
162 | ||
163 | Changing single-stepping behaviour | |
164 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
324b2298 PB |
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" | |
50679467 | 206 | |
acb0a27e PM |
207 | Examining physical memory |
208 | ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
50679467 JD |
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. | |
abf7ba31 IL |
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. |