]>
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 | |
18 | connection, use the ``-gdb dev`` option instead of ``-s``.) | |
324b2298 PB |
19 | |
20 | .. parsed-literal:: | |
21 | ||
e5910d42 PM |
22 | |qemu_system| -s -S -kernel bzImage -hda rootdisk.img -append "root=/dev/hda" |
23 | ||
24 | QEMU will launch but will silently wait for gdb to connect. | |
324b2298 PB |
25 | |
26 | Then launch gdb on the 'vmlinux' executable:: | |
27 | ||
28 | > gdb vmlinux | |
29 | ||
30 | In gdb, connect to QEMU:: | |
31 | ||
32 | (gdb) target remote localhost:1234 | |
33 | ||
34 | Then you can use gdb normally. For example, type 'c' to launch the | |
35 | kernel:: | |
36 | ||
37 | (gdb) c | |
38 | ||
39 | Here are some useful tips in order to use gdb on system code: | |
40 | ||
41 | 1. Use ``info reg`` to display all the CPU registers. | |
42 | ||
43 | 2. Use ``x/10i $eip`` to display the code at the PC position. | |
44 | ||
45 | 3. Use ``set architecture i8086`` to dump 16 bit code. Then use | |
46 | ``x/10i $cs*16+$eip`` to dump the code at the PC position. | |
47 | ||
d211556f PM |
48 | Debugging multicore machines |
49 | ============================ | |
50 | ||
51 | GDB's abstraction for debugging targets with multiple possible | |
52 | parallel flows of execution is a two layer one: it supports multiple | |
53 | "inferiors", each of which can have multiple "threads". When the QEMU | |
54 | machine has more than one CPU, QEMU exposes each CPU cluster as a | |
55 | separate "inferior", where each CPU within the cluster is a separate | |
56 | "thread". Most QEMU machine types have identical CPUs, so there is a | |
57 | single cluster which has all the CPUs in it. A few machine types are | |
58 | heterogenous and have multiple clusters: for example the ``sifive_u`` | |
59 | machine has a cluster with one E51 core and a second cluster with four | |
60 | U54 cores. Here the E51 is the only thread in the first inferior, and | |
61 | the U54 cores are all threads in the second inferior. | |
62 | ||
63 | When you connect gdb to the gdbstub, it will automatically | |
64 | connect to the first inferior; you can display the CPUs in this | |
65 | cluster using the gdb ``info thread`` command, and switch between | |
66 | them using gdb's usual thread-management commands. | |
67 | ||
68 | For multi-cluster machines, unfortunately gdb does not by default | |
69 | handle multiple inferiors, and so you have to explicitly connect | |
70 | to them. First, you must connect with the ``extended-remote`` | |
71 | protocol, not ``remote``:: | |
72 | ||
73 | (gdb) target extended-remote localhost:1234 | |
74 | ||
75 | Once connected, gdb will have a single inferior, for the | |
76 | first cluster. You need to create inferiors for the other | |
77 | clusters and attach to them, like this:: | |
78 | ||
79 | (gdb) add-inferior | |
80 | Added inferior 2 | |
81 | (gdb) inferior 2 | |
82 | [Switching to inferior 2 [<null>] (<noexec>)] | |
83 | (gdb) attach 2 | |
84 | Attaching to process 2 | |
85 | warning: No executable has been specified and target does not support | |
86 | determining executable automatically. Try using the "file" command. | |
87 | 0x00000000 in ?? () | |
88 | ||
89 | Once you've done this, ``info threads`` will show CPUs in | |
90 | all the clusters you have attached to:: | |
91 | ||
92 | (gdb) info threads | |
93 | Id Target Id Frame | |
94 | 1.1 Thread 1.1 (cortex-m33-arm-cpu cpu [running]) 0x00000000 in ?? () | |
95 | * 2.1 Thread 2.2 (cortex-m33-arm-cpu cpu [halted ]) 0x00000000 in ?? () | |
96 | ||
97 | You probably also want to set gdb to ``schedule-multiple`` mode, | |
98 | so that when you tell gdb to ``continue`` it resumes all CPUs, | |
99 | not just those in the cluster you are currently working on:: | |
100 | ||
101 | (gdb) set schedule-multiple on | |
102 | ||
acb0a27e PM |
103 | Advanced debugging options |
104 | ========================== | |
105 | ||
106 | Changing single-stepping behaviour | |
107 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
324b2298 PB |
108 | |
109 | The default single stepping behavior is step with the IRQs and timer | |
110 | service routines off. It is set this way because when gdb executes a | |
111 | single step it expects to advance beyond the current instruction. With | |
112 | the IRQs and timer service routines on, a single step might jump into | |
113 | the one of the interrupt or exception vectors instead of executing the | |
114 | current instruction. This means you may hit the same breakpoint a number | |
115 | of times before executing the instruction gdb wants to have executed. | |
116 | Because there are rare circumstances where you want to single step into | |
117 | an interrupt vector the behavior can be controlled from GDB. There are | |
118 | three commands you can query and set the single step behavior: | |
119 | ||
120 | ``maintenance packet qqemu.sstepbits`` | |
121 | This will display the MASK bits used to control the single stepping | |
122 | IE: | |
123 | ||
124 | :: | |
125 | ||
126 | (gdb) maintenance packet qqemu.sstepbits | |
127 | sending: "qqemu.sstepbits" | |
128 | received: "ENABLE=1,NOIRQ=2,NOTIMER=4" | |
129 | ||
130 | ``maintenance packet qqemu.sstep`` | |
131 | This will display the current value of the mask used when single | |
132 | stepping IE: | |
133 | ||
134 | :: | |
135 | ||
136 | (gdb) maintenance packet qqemu.sstep | |
137 | sending: "qqemu.sstep" | |
138 | received: "0x7" | |
139 | ||
140 | ``maintenance packet Qqemu.sstep=HEX_VALUE`` | |
141 | This will change the single step mask, so if wanted to enable IRQs on | |
142 | the single step, but not timers, you would use: | |
143 | ||
144 | :: | |
145 | ||
146 | (gdb) maintenance packet Qqemu.sstep=0x5 | |
147 | sending: "qemu.sstep=0x5" | |
148 | received: "OK" | |
50679467 | 149 | |
acb0a27e PM |
150 | Examining physical memory |
151 | ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
50679467 JD |
152 | |
153 | Another feature that QEMU gdbstub provides is to toggle the memory GDB | |
154 | works with, by default GDB will show the current process memory respecting | |
155 | the virtual address translation. | |
156 | ||
157 | If you want to examine/change the physical memory you can set the gdbstub | |
158 | to work with the physical memory rather with the virtual one. | |
159 | ||
160 | The memory mode can be checked by sending the following command: | |
161 | ||
162 | ``maintenance packet qqemu.PhyMemMode`` | |
163 | This will return either 0 or 1, 1 indicates you are currently in the | |
164 | physical memory mode. | |
165 | ||
166 | ``maintenance packet Qqemu.PhyMemMode:1`` | |
167 | This will change the memory mode to physical memory. | |
168 | ||
169 | ``maintenance packet Qqemu.PhyMemMode:0`` | |
170 | This will change it back to normal memory mode. |