xref: /openbmc/qemu/docs/system/gdb.rst (revision d2dfe0b5)
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