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