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, + for example during early kernel boot before the MMU is enabled or + before the kernel has relocated itself. In such cases, prefer + 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. + +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. + Relocating code =============== -- 2.47.3
