On Fri, 26 Jun 2026 at 10:43, Alex Bennée <[email protected]> wrote: > > There are a couple of gotchas we should point out: > > - software breakpoints can fail on early boot > - TCG treats all breakpoints as "hardware" breakpoints > > Rewrite the text to explain this more clearly and call out the gotchas > in a Note! section. > > Resolves: https://gitlab.com/qemu-project/qemu/-/work_items/3596 > Signed-off-by: Alex Bennée <[email protected]> > --- > docs/system/gdb.rst | 35 ++++++++++++++++++++++++++--------- > 1 file changed, 26 insertions(+), 9 deletions(-) > > diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst > index d50470b135e..f7878ca8606 100644 > --- a/docs/system/gdb.rst > +++ b/docs/system/gdb.rst > @@ -49,15 +49,32 @@ Here are some useful tips in order to use gdb on system > code: > Breakpoint and Watchpoint support > ================================= > > -While GDB can always fall back to inserting breakpoints into memory > -(if writable) other features are very much dependent on support of the > -accelerator. For TCG system emulation we advertise an infinite number > -of hardware assisted breakpoints and watchpoints. For other > -accelerators it will depend on if support has been added (see > -supports_guest_debug and related hooks in AccelOpsClass). > - > -As TCG cannot track all memory accesses in user-mode there is no > -support for watchpoints. > +GDB supports two types of breakpoint - software and hardware. Software > +breakpoints are simply implemented by writing the architecture's > +breakpoint instruction into memory. Hardware breakpoints are less > +invasive but rely on the support from the architecture which will > +usually only be able to track a limited number of breakpoints at once. > +Each accelerator will also need to specifically support enabling these > +hardware features. > + > +.. note:: > + > + Software breakpoints may fail if the memory is not yet accessible,
"or the guest code is not yet at that address, " > + for example during early kernel boot before the MMU is enabled or We should say "Linux kernel" here. > + before the kernel has relocated itself. In such cases, prefer s/prefer/you should use/ > + hardware-assisted breakpoints (e.g., ``hbreak`` in GDB) which do not > + require memory access. Due to the TCG accelerators complete control > + of the system all breakpoints are treated as hardware breakpoints > + and the number of them available is for all intents and purposes > + infinite. I think this bit about TCG should be a separate "note::". Maybe rephrase it something like: If you are using the TCG accelerator, there is no limit on the number of hardware breakpoints, and QEMU handles requests for both software and hardware breakpoints identically, as if they were hardware breakpoints. ? > + > +Watchpoints allow the debugger to watch for reads and writes to > +various memory locations. The number of watchpoints available will be > +a factor of the architecture and support of the accelerator. For the > +TCG accelerator running system emulation we can support as many > +watchpoints as memory allows. As TCG cannot track all memory accesses > +in user-mode there is no support for watchpoints in that mode. > + -- PMM
