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 -hda rootdisk.img -append "root=/dev/hda"
42 1. Use ``info reg`` to display all the CPU registers.
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
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
91 single cluster which has all the CPUs in it.  A few machine types are
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
109 Once connected, gdb will have a single inferior, for the
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
148 .. parsed-literal::
150 …|qemu_system| -chardev socket,path=/tmp/gdb-socket,server=on,wait=off,id=gdb0 -gdb chardev:gdb0 -S…
155    (gdb) target remote /tmp/gdb-socket
163 Changing single-stepping behaviour
166 The default single stepping behavior is step with the IRQs and timer
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
173 Because there are rare circumstances where you want to single step into
175 three commands you can query and set the single step behavior:
178    This will display the MASK bits used to control the single stepping
188    This will display the current value of the mask used when single
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:
235 qemu-user, it allows directly downloading any file readable by QEMU from the