docs/system/gdb.rst

4 ---------
6 QEMU supports working with gdb via gdb's remote-connection facility
8 way that you might with a low-level debug facility like JTAG
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
18 connection, use the ``-gdb dev`` option instead of ``-s``. See
21 .. parsed-literal::
23    |qemu_system| -s -S -kernel bzImage -drive file=rootdisk.img,format=raw -append "root=/dev/sda"
59 As TCG cannot track all memory accesses in user-mode there is no
71 Debugging user-space in system emulation
74 While it is technically possible to debug a user-space program running
78 debug some interaction between kernel and user-space you are better
100 them using gdb's usual thread-management commands.
102 For multi-cluster machines, unfortunately gdb does not by default
104 to them. First, you must connect with the ``extended-remote``
107     (gdb) target extended-remote localhost:1234
113   (gdb) add-inferior
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 ?? ()
131 You probably also want to set gdb to ``schedule-multiple`` mode,
135   (gdb) set schedule-multiple on
141 a unix socket (if supported by your operating system). This is useful when
148 .. parsed-literal::
150 …|qemu_system| -chardev socket,path=/tmp/gdb-socket,server=on,wait=off,id=gdb0 -gdb chardev:gdb0 -S…
153 the socket::
155    (gdb) target remote /tmp/gdb-socket
157 Note that to use a unix socket for the connection you will need
163 Changing single-stepping behaviour
232 Connecting to the GDB socket allows running arbitrary code inside the guest;
235 qemu-user, it allows directly downloading any file readable by QEMU from the
238 The GDB socket is not protected by authentication, authorization or encryption.
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