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 <alex.bennee@linaro.org>
---
 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

On Fri, 26 Jun 2026 at 10:43, 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! section.
>
> Resolves: https://gitlab.com/qemu-project/qemu/-/work_items/3596
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  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

On 26/6/26 15:47, Peter Maydell wrote:
> On Fri, 26 Jun 2026 at 10:43, 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! section.
>>
>> Resolves: https://gitlab.com/qemu-project/qemu/-/work_items/3596
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> ---
>>   docs/system/gdb.rst | 35 ++++++++++++++++++++++++++---------
>>   1 file changed, 26 insertions(+), 9 deletions(-)


>   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.

I noticed and reviewed v2, but wanted to clarify here, if we ever get
SoftMMU in user-mode then we won't have this restriction.