Update user manual with AMD GPU issues

- Describe the issues with setting breakpoints using source line
  position when the corresponding code object is not loaded due to
  deferred code object loading.
- Describe an issue with instruction single stepping the S_ENDPGM
  instruction.

Change-Id: I5067571498e77bb845c0a6e1454e6b649788a32e

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 64bc239727ec362feb91b8945bd213fae3ef89fd..4db89dcbc60551ba12a4528ad4e022418e5210b5 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -26716,12 +26716,22 @@ objects that have the same breakpoint set.  The work around is to use
 The HIP runtime currently performs deferred code object loading by
 default.  AMD GPU code objects are not loaded until the first kernel
 is launched.  Before then, all breakpoints have to be set as pending
-breakpoints using source line positions.
+breakpoints.
+
+If source line positions are used that only correspond to source lines
+in unloaded code objects, then @value{GDBN} may not set pending
+breakpoints, and instead set breakpoints in unpredictable places of
+the loaded code objects if they contain code from the same file.  This
+can result in unexpected breakpoint hits being reported.  When the
+code object containing the source lines is loaded, the incorrect
+breakpoints will be remomoved and replaced by the correct ones.  This
+problem can be avoided by only setting breakpoints in unloaded code
+objects using symbol or function names.
 
 The @code{HIP_ENABLE_DEFERRED_LOADING} environment variable can be
 used to disable deferred code object loading by the HIP runtime.  This
-allows breakpoints to be set in AMD GPU code as soon as the inferior
-reaches the @code{main} function.
+ensures all code objects will be loaded when the inferior reaches the
+beginning of the @code{main} function.
 
 For example,
 
@@ -26739,6 +26749,9 @@ and using the non-stop mode (@pxref{Non-Stop Mode}).  This will
 prevent the ROCm runtime from terminating the inferior, while allowing
 @value{GDBN} to report the memory violation.
 
+@item
+AMD GPU does not currently support calling inferior functions.
+
 @item
 @value{GDBN} does not support following a forked process.
 
@@ -26757,13 +26770,15 @@ runtime available as part of releases before ROCm 3.5.
 AMD GPU does not currently support the compiler address, memory, or
 thread sanitizers.
 
-@item
-AMD GPU does not currently support calling inferior functions.
-
 @item
 @value{GDBN} support for AMD GPU is not currently available under
 virtualization.
 
+@item
+Performing an instruction single step when an AMD GPU wavefront is
+positioned on an @code{S_ENDPGM} instruction may cause the AMD GPU
+hardware to hang.
+
 @end enumerate
 
 @node Controlling GDB