It seems some users will try and use the gdbstub to debug userspace
inside a system emulation. While possible clarify the limitations of
this approach and direct the users to a less head scratching way of
debugging user-space.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Clarifies: https://gitlab.com/qemu-project/qemu/-/issues/1274
---
 docs/system/gdb.rst | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst
index 9906991b84..c0cc0c9c7e 100644
--- a/docs/system/gdb.rst
+++ b/docs/system/gdb.rst
@@ -60,7 +60,7 @@ As TCG cannot track all memory accesses in user-mode there is no
 support for watchpoints.
 
 Relocating code
----------------
+===============
 
 On modern kernels confusion can be caused by code being relocated by
 features such as address space layout randomisation. To avoid
@@ -68,6 +68,17 @@ confusion when debugging such things you either need to update gdb's
 view of where things are in memory or perhaps more trivially disable
 ASLR when booting the system.
 
+Debugging user-space in system emulation
+========================================
+
+While technically possible to debug a user-space program running
+inside a system image it does present challenges. Kernel preemption
+and execution mode changes between kernel and user mode can make it
+hard to follow whats going on. Unless you are specifically trying to
+debug some interaction between kernel and user-space you are better
+off running your guest program with gdb either in the guest or using
+a gdbserver exposed via a port to the outside world.
+
 Debugging multicore machines
 ============================
 
-- 
2.39.2

On Mon, 20 Nov 2023 at 15:08, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> It seems some users will try and use the gdbstub to debug userspace
> inside a system emulation. While possible clarify the limitations of
> this approach and direct the users to a less head scratching way of
> debugging user-space.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Clarifies: https://gitlab.com/qemu-project/qemu/-/issues/1274
> ---
>  docs/system/gdb.rst | 13 ++++++++++++-
>  1 file changed, 12 insertions(+), 1 deletion(-)
>
> diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst
> index 9906991b84..c0cc0c9c7e 100644
> --- a/docs/system/gdb.rst
> +++ b/docs/system/gdb.rst
> @@ -60,7 +60,7 @@ As TCG cannot track all memory accesses in user-mode there is no
>  support for watchpoints.
>
>  Relocating code
> ----------------
> +===============
>
>  On modern kernels confusion can be caused by code being relocated by
>  features such as address space layout randomisation. To avoid
> @@ -68,6 +68,17 @@ confusion when debugging such things you either need to update gdb's
>  view of where things are in memory or perhaps more trivially disable
>  ASLR when booting the system.
>
> +Debugging user-space in system emulation
> +========================================
> +
> +While technically possible to debug a user-space program running

"While it is"

> +inside a system image it does present challenges. Kernel preemption

"image, "

> +and execution mode changes between kernel and user mode can make it
> +hard to follow whats going on. Unless you are specifically trying to

"what's"

> +debug some interaction between kernel and user-space you are better
> +off running your guest program with gdb either in the guest or using
> +a gdbserver exposed via a port to the outside world.
> +
>  Debugging multicore machines
>  ============================

thanks
-- PMM

On 20/11/23 16:08, Alex Bennée wrote:
> It seems some users will try and use the gdbstub to debug userspace
> inside a system emulation. While possible clarify the limitations of
> this approach and direct the users to a less head scratching way of
> debugging user-space.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Clarifies: https://gitlab.com/qemu-project/qemu/-/issues/1274
> ---
>   docs/system/gdb.rst | 13 ++++++++++++-
>   1 file changed, 12 insertions(+), 1 deletion(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

On 11/20/23 07:08, Alex Bennée wrote:
> It seems some users will try and use the gdbstub to debug userspace
> inside a system emulation. While possible clarify the limitations of
> this approach and direct the users to a less head scratching way of
> debugging user-space.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Clarifies: https://gitlab.com/qemu-project/qemu/-/issues/1274
> ---
>   docs/system/gdb.rst | 13 ++++++++++++-
>   1 file changed, 12 insertions(+), 1 deletion(-)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~