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 and warning sections.

Resolves: https://gitlab.com/qemu-project/qemu/-/work_items/3596
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v2
  - made the soft breakpoint section a warning
  - moved discussion about TCG's unlimited break and watchpoints to a
  new note
---
 docs/system/gdb.rst | 37 ++++++++++++++++++++++++++++---------
 1 file changed, 28 insertions(+), 9 deletions(-)

diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst
index d50470b135e..15233372c01 100644
--- a/docs/system/gdb.rst
+++ b/docs/system/gdb.rst
@@ -49,15 +49,34 @@ 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.
+
+.. warning::
+
+  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 Linux kernel boot before the MMU is enabled or before the
+  kernel has relocated itself. In such cases, you should use
+  hardware-assisted breakpoints (e.g., ``hbreak`` in GDB) which do not
+  require memory access.
+
+Watchpoints allow the debugger to watch for reads and writes to
+various memory locations. The number of watchpoints available will be
+a depend on the architecture and support of the accelerator.
+
+.. note::
+
+  If you are using the TCG accelerator, there is no limit on the
+  number of hardware breakpoints or watchpoints, and QEMU handles
+  requests for both software and hardware breakpoints identically,
+  as if they were hardware breakpoints.
+
 
 Relocating code
 ===============
-- 
2.47.3

On 29/6/26 12:58, Alex Bennée 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 and warning sections.
> 
> Resolves: https://gitlab.com/qemu-project/qemu/-/work_items/3596
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> 
> ---
> v2
>    - made the soft breakpoint section a warning
>    - moved discussion about TCG's unlimited break and watchpoints to a
>    new note
> ---
>   docs/system/gdb.rst | 37 ++++++++++++++++++++++++++++---------
>   1 file changed, 28 insertions(+), 9 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com>

Alex Bennée <alex.bennee@linaro.org> writes:

> 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 and warning sections.
>
> Resolves: https://gitlab.com/qemu-project/qemu/-/work_items/3596
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

Queued to gdbstub/next, thanks.

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

On 6/29/2026 3:58 AM, Alex Bennée 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 and warning sections.
> 
> Resolves: https://gitlab.com/qemu-project/qemu/-/work_items/3596
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> 
> ---
> v2
>   - made the soft breakpoint section a warning
>   - moved discussion about TCG's unlimited break and watchpoints to a
>   new note
> ---
>  docs/system/gdb.rst | 37 ++++++++++++++++++++++++++++---------
>  1 file changed, 28 insertions(+), 9 deletions(-)
> 

I'll let you pull this as part of gdbstub system.

Reviewed-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>

On Mon, 29 Jun 2026 at 11:59, Alex Bennée <alex.bennee@linaro.org> 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 and warning sections.
>
> Resolves: https://gitlab.com/qemu-project/qemu/-/work_items/3596
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
>   - made the soft breakpoint section a warning
>   - moved discussion about TCG's unlimited break and watchpoints to a
>   new note
> ---

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM