SWDEV-541514 - Docs update 2025-09-15 (#993)

Co-authored-by: Julia Jiang <56359287+jujiang-del@users.noreply.github.com>

projects/hip/docs/how-to/debugging.rst

@@ -259,42 +259,50 @@ HSA provides environment variables that help analyze issues in drivers or hardwa
 
 * To isolate issues with hardware copy engines, you can use ``HSA_ENABLE_SDMA``.
 
-    ``HSA_ENABLE_SDMA=0`` causes host-to-device and device-to-host copies to use compute shader
-    blit kernels, rather than the dedicated DMA copy engines. Compute shader copies have low latency
-    (typically < 5 us) and can achieve approximately 80% of the bandwidth of the DMA copy engine.
+  ``HSA_ENABLE_SDMA=0`` causes host-to-device and device-to-host copies to use compute shader
+  blit kernels, rather than the dedicated DMA copy engines. Compute shader copies have low latency
+  (typically < 5 us) and can achieve approximately 80% of the bandwidth of the DMA copy engine.
 
 * To diagnose interrupt storm issues in the driver, you can use ``HSA_ENABLE_INTERRUPT``.
 
-    ``HSA_ENABLE_INTERRUPT=0`` causes completion signals to be detected with memory-based
-    polling, rather than interrupts.
+  ``HSA_ENABLE_INTERRUPT=0`` causes completion signals to be detected with memory-based
+  polling, rather than interrupts.
 
 HIP environment variable summary
 --------------------------------
 
 Here are some of the more commonly used environment variables:
 
-.. include-table:: data/env_variables_hip.rst
+.. include-table:: ./reference/env_variables/debug_hip_env.rst
     :table: hip-env-debug
 
 General debugging tips
 ======================================================
 
 * ``gdb --args`` can be used to pass the executable and arguments to ``gdb``.
+
 * You can set environment variables (``set env``) from within GDB on Linux:
 
-    .. code-block:: bash
+  .. code-block:: bash
 
-        (gdb) set env AMD_SERIALIZE_KERNEL 3
+      (gdb) set env AMD_SERIALIZE_KERNEL 3
 
-    .. note::
-        This ``gdb`` command does not use an equal (=) sign.
+  .. note::
+
+      This ``gdb`` command does not use an equal (=) sign.
 
 * The GDB backtrace shows a path in the runtime. This is because a fault is caught by the runtime, but it is generated by an asynchronous command running on the GPU.
+
 * To determine the true location of a fault, you can force the kernels to run synchronously by setting the environment variables ``AMD_SERIALIZE_KERNEL=3`` and ``AMD_SERIALIZE_COPY=3``. This forces HIP runtime to wait for the kernel to finish running before returning. If the fault occurs when a kernel is running, you can see the code that launched the kernel inside the backtrace. The thread that's causing the issue is typically the one inside ``libhsa-runtime64.so``.
+
 * VM faults inside kernels can be caused by:
 
-    * Incorrect code (e.g., a for loop that extends past array boundaries)
-    * Memory issues, such as invalid kernel arguments (null pointers, unregistered host pointers, bad pointers)
-    * Synchronization issues
-    * Compiler issues (incorrect code generation from the compiler)
-    * Runtime issues
+  * Incorrect code (e.g., a for loop that extends past array boundaries)
+
+  * Memory issues, such as invalid kernel arguments (null pointers, unregistered host pointers, bad pointers)
+
+  * Synchronization issues
+
+  * Compiler issues (incorrect code generation from the compiler)
+
+  * Runtime issues