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

Co-authored-by: Julia Jiang <56359287+jujiang-del@users.noreply.github.com>
2025-09-24 18:57:00 +02:00
parent 0575606e49
commit 83fb0c8c47
@@ -43,6 +43,13 @@ in both single and double precision formats.
 Complex Number Functions
 ========================

+.. note::
+
+  Changes have been made to small vector constructors for ``hipComplex`` and ``hipFloatComplex``
+  initialization, such as ``float2`` and ``int4``. If your code previously relied
+  on a single value to initialize all components within a vector or complex type, you might need
+  to update your code.
+
 A comprehensive collection of functions for creating and manipulating complex numbers, organized by
 functional categories for easy reference.

@@ -12,44 +12,24 @@ on AMD platform, which are grouped by functionality.
 GPU isolation variables
 ================================================================================

-The GPU isolation environment variables in HIP are collected in the following table.
-For more information, check :doc:`GPU isolation page <rocm:conceptual/gpu-isolation>`.
-
-.. include-table:: data/env_variables_hip.rst
-    :table: hip-env-isolation
+.. include:: ./env_variables/gpu_isolation_hip_env.rst

 Profiling variables
 ================================================================================

-The profiling environment variables in HIP are collected in the following table. For
-more information, check :doc:`setting the number of CUs page <rocm:how-to/setting-cus>`.
-
-.. include-table:: data/env_variables_hip.rst
-    :table: hip-env-prof
+.. include:: ./env_variables/profiling_hip_env.rst

 Debug variables
 ================================================================================

-The debugging environment variables in HIP are collected in the following table. For
-more information, check :ref:`debugging_with_hip`.
-
-.. include-table:: data/env_variables_hip.rst
-    :table: hip-env-debug
+.. include:: ./env_variables/debug_hip_env.rst

 Memory management related variables
 ================================================================================

-The memory management related environment variables in HIP are collected in the
-following table.
-
-.. include-table:: data/env_variables_hip.rst
-    :table: hip-env-memory
+.. include:: ./env_variables/memory_management_hip_env.rst

 Other useful variables
 ================================================================================

-The following table lists environment variables that are useful but relate to
-different features.
-
-.. include-table:: data/env_variables_hip.rst
-    :table: hip-env-other
+.. include:: ./env_variables/miscellaneous_hip_env.rst
@@ -0,0 +1,100 @@
+The debugging environment variables in HIP are collected in the following table. For
+more information, check :doc:`hip:how-to/logging`, :doc:`hip:how-to/debugging`
+and :doc:`GPU isolation <rocm:conceptual/gpu-isolation>`.
+
+.. _hip-env-debug:
+.. list-table::
+    :header-rows: 1
+    :widths: 35,14,51
+
+    * - **Environment variable**
+      - **Default value**
+      - **Value**
+
+    * - | ``AMD_LOG_LEVEL``
+        | Enables HIP log on various level.
+      - ``0``
+      - | 0: Disable log.
+        | 1: Enables error logs.
+        | 2: Enables warning logs next to lower-level logs.
+        | 3: Enables information logs next to lower-level logs.
+        | 4: Enables debug logs next to lower-level logs.
+        | 5: Enables debug extra logs next to lower-level logs.
+
+    * - | ``AMD_LOG_LEVEL_FILE``
+        | Sets output file for ``AMD_LOG_LEVEL``.
+      - stderr output
+      -
+
+    * - | ``AMD_LOG_MASK``
+        | Specifies HIP log filters. Here is the ` complete list of log masks <https://github.com/ROCm/clr/blob/develop/rocclr/utils/debug.hpp#L40>`_.
+      - ``0x7FFFFFFF``
+      - | 0x1: Log API calls.
+        | 0x2: Kernel and copy commands and barriers.
+        | 0x4: Synchronization and waiting for commands to finish.
+        | 0x8: Decode and display AQL packets.
+        | 0x10: Queue commands and queue contents.
+        | 0x20: Signal creation, allocation, pool.
+        | 0x40: Locks and thread-safety code.
+        | 0x80: Kernel creations and arguments, etc.
+        | 0x100: Copy debug.
+        | 0x200: Detailed copy debug.
+        | 0x400: Resource allocation, performance-impacting events.
+        | 0x800: Initialization and shutdown.
+        | 0x1000: Misc debug, not yet classified.
+        | 0x2000: Show raw bytes of AQL packet.
+        | 0x4000: Show code creation debug.
+        | 0x8000: More detailed command info, including barrier commands.
+        | 0x10000: Log message location.
+        | 0x20000: Memory allocation.
+        | 0x40000: Memory pool allocation, including memory in graphs.
+        | 0x80000: Timestamp details.
+        | 0xFFFFFFFF: Log always even mask flag is zero.
+
+    * - | ``HIP_LAUNCH_BLOCKING``
+        | Used for serialization on kernel execution.
+      - ``0``
+      - | 0: Disable. Kernel executes normally.
+        | 1: Enable. Serializes kernel enqueue, behaves the same as ``AMD_SERIALIZE_KERNEL``.
+
+    * - | ``HIP_VISIBLE_DEVICES`` (or ``CUDA_VISIBLE_DEVICES``)
+        | Only devices whose index is present in the sequence are visible to HIP
+      - Unset by default.
+      - 0,1,2: Depending on the number of devices on the system.
+
+    * - | ``GPU_DUMP_CODE_OBJECT``
+        | Dump code object.
+      - ``0``
+      - | 0: Disable
+        | 1: Enable
+
+    * - | ``AMD_SERIALIZE_KERNEL``
+        | Serialize kernel enqueue.
+      - ``0``
+      - | 0: Disable
+        | 1: Wait for completion before enqueue.
+        | 2: Wait for completion after enqueue.
+        | 3: Both
+
+    * - | ``AMD_SERIALIZE_COPY``
+        | Serialize copies
+      - ``0``
+      - | 0: Disable
+        | 1: Wait for completion before enqueue.
+        | 2: Wait for completion after enqueue.
+        | 3: Both
+
+    * - | ``AMD_DIRECT_DISPATCH``
+        | Enable direct kernel dispatch (Currently for Linux; under development for Windows).
+      - ``1``
+      - | 0: Disable
+        | 1: Enable
+
+    * - | ``GPU_MAX_HW_QUEUES``
+        | The maximum number of hardware queues allocated per device.
+      - ``4``
+      - The variable controls how many independent hardware queues HIP runtime can create per process,
+        per device. If an application allocates more HIP streams than this number, then HIP runtime reuses
+        the same hardware queues for the new streams in a round-robin manner. Note that this maximum
+        number does not apply to hardware queues that are created for CU-masked HIP streams, or
+        cooperative queues for HIP Cooperative Groups (single queue per device).
@@ -0,0 +1,27 @@
+Restricting the access of applications to a subset of GPUs, also known as GPU
+isolation, allows users to hide GPU resources from programs. The GPU isolation
+environment variables in HIP are collected in the following table.
+
+.. _hip-env-isolation:
+.. list-table::
+    :header-rows: 1
+    :widths: 50,30,20
+
+    * - **Environment variable**
+      - **Links**
+      - **Value**
+
+    * - | ``ROCR_VISIBLE_DEVICES``
+        | A list of device indices or UUIDs that will be exposed to applications.
+      - :doc:`GPU isolation <rocm:conceptual/gpu-isolation>`, :doc:`Setting the number of compute units <rocm:how-to/setting-cus>`
+      - Example: ``0,GPU-DEADBEEFDEADBEEF``
+
+    * - | ``GPU_DEVICE_ORDINAL``
+        | Devices indices exposed to OpenCL and HIP applications.
+      - :doc:`GPU isolation <rocm:conceptual/gpu-isolation>`
+      - Example: ``0,2``
+
+    * - | ``HIP_VISIBLE_DEVICES`` or ``CUDA_VISIBLE_DEVICES``
+        | Device indices exposed to HIP applications.
+      - :doc:`GPU isolation <rocm:conceptual/gpu-isolation>`, :doc:`HIP debugging <hip:how-to/debugging>`
+      - Example: ``0,2``
@@ -0,0 +1,100 @@
+The memory management related environment variables in HIP are collected in the
+following table. The ``HIP_HOST_COHERENT`` variable linked at the following
+pages:
+
+- :ref:`Coherence control <hip:coherence_control>`
+
+- :ref:`Memory allocation flags <hip:memory_allocation_flags>`
+
+.. _hip-env-memory:
+.. list-table::
+    :header-rows: 1
+    :widths: 35,14,51
+
+    * - **Environment variable**
+      - **Default value**
+      - **Value**
+
+    * - | ``HIP_HIDDEN_FREE_MEM``
+        | Amount of memory to hide from the free memory reported by hipMemGetInfo.
+      - ``0``
+      - | 0: Disable
+        | Unit: megabyte (MB)
+
+    * - | ``HIP_HOST_COHERENT``
+        | Specifies if the memory is coherent between the host and GPU in ``hipHostMalloc``.
+      - ``0``
+      - | 0: Memory is not coherent.
+        | 1: Memory is coherent.
+        | Environment variable has effect, if the following conditions are statisfied:
+        | - One of the ``hipHostMallocDefault``, ``hipHostMallocPortable``,  ``hipHostMallocWriteCombined`` or ``hipHostMallocNumaUser`` flag set to 1.
+        | - ``hipHostMallocCoherent``, ``hipHostMallocNonCoherent`` and ``hipHostMallocMapped`` flags set to 0.
+
+    * - | ``HIP_INITIAL_DM_SIZE``
+        | Set initial heap size for device malloc.
+      - ``8388608``
+      - | Unit: Byte
+        | The default value corresponds to 8 MB.
+
+    * - | ``HIP_MEM_POOL_SUPPORT``
+        | Enables memory pool support in HIP.
+      - ``0``
+      - | 0: Disable
+        | 1: Enable
+
+    * - | ``HIP_MEM_POOL_USE_VM``
+        | Enables memory pool support in HIP.
+      - | ``0``: other OS
+        | ``1``: Windows
+      - | 0: Disable
+        | 1: Enable
+
+    * - | ``HIP_VMEM_MANAGE_SUPPORT``
+        | Virtual Memory Management Support.
+      - ``1``
+      - | 0: Disable
+        | 1: Enable
+
+    * - | ``GPU_MAX_HEAP_SIZE``
+        | Set maximum size of the GPU heap to % of board memory.
+      - ``100``
+      - | Unit: Percentage
+
+    * - | ``GPU_MAX_REMOTE_MEM_SIZE``
+        | Maximum size that allows device memory substitution with system.
+      - ``2``
+      - | Unit: kilobyte (KB)
+
+    * - | ``GPU_NUM_MEM_DEPENDENCY``
+        | Number of memory objects for dependency tracking.
+      - ``256``
+      -
+
+    * - | ``GPU_STREAMOPS_CP_WAIT``
+        | Force the stream memory operation to wait on CP.
+      - ``0``
+      - | 0: Disable
+        | 1: Enable
+
+    * - | ``HSA_LOCAL_MEMORY_ENABLE``
+        | Enable HSA device local memory usage.
+      - ``1``
+      - | 0: Disable
+        | 1: Enable
+
+    * - | ``PAL_ALWAYS_RESIDENT``
+        | Force memory resources to become resident at allocation time.
+      - ``0``
+      - | 0: Disable
+        | 1: Enable
+
+    * - | ``PAL_PREPINNED_MEMORY_SIZE``
+        | Size of prepinned memory.
+      - ``64``
+      - | Unit: kilobyte (KB)
+
+    * - | ``REMOTE_ALLOC``
+        | Use remote memory for the global heap allocation.
+      - ``0``
+      - | 0: Disable
+        | 1: Enable
@@ -0,0 +1,34 @@
+The following table lists environment variables that are useful but relate to
+different features in HIP.
+
+.. _hip-env-other:
+.. list-table::
+    :header-rows: 1
+    :widths: 35,14,51
+
+    * - **Environment variable**
+      - **Default value**
+      - **Value**
+
+    * - | ``HIPRTC_COMPILE_OPTIONS_APPEND``
+        | Sets compile options needed for ``hiprtc`` compilation.
+      - Unset by default.
+      - ``--gpu-architecture=gfx906:sramecc+:xnack``, ``-fgpu-rdc``
+
+    * - | ``AMD_COMGR_SAVE_TEMPS``
+        | Controls the deletion of temporary files generated during the compilation of COMGR. These files do not appear in the current working directory, but are instead left in a platform-specific temporary directory.
+      - Unset by default.
+      - | 0: Temporary files are deleted automatically.
+        | Non zero integer: Turn off the temporary files deletion.
+
+    * - | ``AMD_COMGR_EMIT_VERBOSE_LOGS``
+        | Sets logging of COMGR to include additional Comgr-specific informational messages.
+      - Unset by default.
+      - | 0: Verbose log disabled.
+        | Non zero integer: Verbose log enabled.
+
+    * - | ``AMD_COMGR_REDIRECT_LOGS``
+        | Controls redirect logs of COMGR.
+      - Unset by default.
+      - | `stdout` / `-`: Redirected to the standard output.
+        | `stderr`: Redirected to the error stream.
@@ -0,0 +1,23 @@
+The profiling environment variables in HIP are collected in the following table. For
+more information, check :doc:`setting the number of CUs page <rocm:how-to/setting-cus>`.
+
+.. _hip-env-prof:
+.. list-table::
+    :header-rows: 1
+    :widths: 70,30
+
+    * - **Environment variable**
+      - **Value**
+
+    * - | ``HSA_CU_MASK``
+        | Sets the mask on a lower level of queue creation in the driver, this mask will also be set for queues being profiled.
+      - Example: ``1:0-8``
+
+    * - | ``ROC_GLOBAL_CU_MASK``
+        | Sets the mask on queues created by the HIP or the OpenCL runtimes, this mask will also be set for queues being profiled.
+      - Example: ``0xf``, enables only 4 CUs
+
+    * - | ``HIP_FORCE_QUEUE_PROFILING``
+        | Used to run the app as if it were run in rocprof. Forces command queue profiling on by default.
+      - | 0: Disable
+        | 1: Enable
@@ -13,6 +13,8 @@ returned by HIP API functions to indicate various runtime conditions and errors.

 For more details, see :ref:`Error handling functions <error_handling_reference>`.

+.. _basic_runtime_errors:
+
 Basic Runtime Errors
 ====================

@@ -100,6 +102,8 @@ Basic Runtime Errors
    If this error is encountered, it generally means the API or feature is not fully supported in the
    current version.

+.. _memory_management_errors:
+
 Memory Management Errors
 ========================

@@ -139,6 +143,14 @@ Memory Management Errors
      - ``1052``
      - Runtime memory call returned error

+    * - :term:`hipErrorInvalidChannelDescriptor`
+      - ``911``
+      - Input for texture object, resource descriptor, or texture descriptor is a NULL pointer or invalid
+
+    * - :term:`hipErrorInvalidTexture`
+      - ``912``
+      - Texture reference pointer is NULL or invalid
+
 .. glossary::

  hipErrorOutOfMemory
@@ -233,6 +245,21 @@ Memory Management Errors
    This error differs from ``hipErrorOutOfMemory`` in that it relates to memory operations internal to the HIP
    runtime rather than explicit application requests for memory allocation.

+  hipErrorInvalidChannelDescriptor
+
+    This error indicates that an invalid channel descriptor is used to define the format and layout of data
+    in memory, particularly when working with textures or arrays. This could happen if the descriptor is
+    incorrectly set up or if it does not match the expected format for the operation being performed.
+
+  hipErrorInvalidTexture
+
+    The error code is returned when an invalid texture object is used in a function call. This typically
+    occurs when a texture object is not properly initialized or configured before being used in operations
+    that require valid texture data. If you encounter this error, it suggests that the texture object
+    might be missing necessary configuration details or has been corrupted.
+
+.. _device_context_errors:
+
 Device and Context Errors
 =========================

@@ -385,6 +412,8 @@ Device and Context Errors
    * Custom build environments with mismatched components
    * Partial upgrades of the ROCm stack

+.. _kernel_launch_errors:
+
 Kernel and Launch Errors
 ========================

@@ -396,10 +425,18 @@ Kernel and Launch Errors
     - Value
     - Description

+   * - :term:`hipErrorInvalidValue``
+     - ``1``
+     - Invalid input value
+
   * - :term:`hipErrorInvalidDeviceFunction`
     - ``98``
     - Invalid device function

+   * - :term:`hipErrorContextIsDestroyed`
+     - ``709``
+     - Invalid stream handle
+
   * - :term:`hipErrorInvalidConfiguration`
     - ``9``
     - Invalid configuration argument
@@ -446,6 +483,11 @@ Kernel and Launch Errors

 .. glossary::

+  hipErrorInvalidValue
+
+    Error returned when a grid dimension check finds any input global work size
+    dimension is zero, or a shared memory size check finds the size exceeds the size limit. 
+
  hipErrorInvalidDeviceFunction

    Invalid device function. This error occurs when attempting to use a function that is not a valid device
@@ -453,6 +495,10 @@ Kernel and Launch Errors

    * Code compiled for a specific GPU architecture (using ``--offload-arch``) but executed on an different/incompatible GPU

+  hipErrorContextIsDestroyed
+
+    This error is returned when the input stream or input stream handle is invalid. 
+
  hipErrorInvalidConfiguration

    Invalid configuration argument. This error occurs when the configuration specified for a kernel launch
@@ -507,7 +553,7 @@ Kernel and Launch Errors
  hipErrorInvalidKernelFile

    Invalid kernel file. This error occurs when the kernel file or module being loaded is corrupted or in
-    an invalid format.
+    an invalid format, for example the file name exists but the file size is 0.

  hipErrorInvalidImage

@@ -556,6 +602,7 @@ Kernel and Launch Errors

    * Launching a cooperative kernel with grid dimensions that exceed hardware limits
    * Requesting more resources than available for synchronization across thread blocks
+    * The shared memory size in bytes exceeds the device local memory size per CU
    * Using cooperative groups on hardware with limited support
    * Not accounting for cooperative launch limitations in kernel configuration

@@ -577,6 +624,8 @@ Kernel and Launch Errors
    normal operation. Additional debugging of the previous failed launch may be required to identify
    the root cause.

+.. _stream_capture_errors:
+
 Stream Capture Errors
 =====================

@@ -624,6 +673,10 @@ Stream Capture Errors
     - ``907``
     - Operation not permitted on an event last recorded in a capturing stream

+   * - :term:`hipErrorInvalidResourceHandle`
+     - ``400``
+     - Input launch stream is ``NULL`` or is ``hipStreamLegacy``
+
 .. glossary::

  hipErrorStreamCaptureUnsupported
@@ -754,6 +807,14 @@ Stream Capture Errors
    and cannot be used for host-side synchronization until the capture is complete and the graph
    is executed.

+  hipErrorInvalidResourceHandle
+
+    This error is returned when the input launch stream is a NULL pointer, is invalid, or is ``hipStreamLegacy``.
+    If you encounter this error, you should check the validity of the resource handle being used in your HIP
+    API calls. Ensure that the handle was correctly obtained and has not been freed or invalidated before use.
+
+.. _profiler_errors:
+
 Profiler Errors
 ===============

@@ -845,6 +906,8 @@ Profiler Errors
    The HIP profiler must be in an active state before it can be stopped. This error is informational
    and indicates that the profiler is already in the desired inactive state.

+.. _resource_mapping_errors:
+
 Resource Mapping Errors
 =======================

@@ -992,6 +1055,8 @@ Resource Mapping Errors
    operation was attempted on a resource that was not mapped as a pointer. Resources must be mapped
    with the appropriate mapping type for the operations that will be performed on them.

+.. _peer_access_errors:
+
 Peer Access Errors
 ==================

@@ -1058,6 +1123,8 @@ Peer Access Errors
    access between peer devices. Not all device combinations support peer access. Compatibility can be
    determined with :cpp:func:`hipDeviceCanAccessPeer()`.

+.. _system_file_errors:
+
 System and File Errors
 ======================

@@ -1183,6 +1250,8 @@ System and File Errors
    This is a catch-all error that may require looking at system logs or using additional
    debugging tools to identify the root cause.

+.. _graphics_content_errors:
+
 Graphics Context Errors
 =======================

@@ -1216,6 +1285,8 @@ Graphics Context Errors
    instantiated graph update. This error occurs when attempting to update an already instantiated
    graph with changes that are not allowed.

+.. _hardware_errors:
+
 Hardware Errors
 ===============

@@ -240,10 +240,12 @@ page.
        - 106
        - 104

-.. [1] RDNA architectures have a configurable wavefront size. The native
-   wavefront size is 32, but they can run in "CU mode", which has an effective
-   wavefront size of 64. This affects the number of resident wavefronts and
-   blocks per compute Unit.
+.. [1] The RDNA architectures feature an experimental compiler option called 
+   ``mwavefrontsize64``, which determines the wavefront size for kernel code
+   generation. When this option is disabled, the native wavefront size of 32 is
+   used, when enabled wavefront size 64 is used. This option is not supported by
+   the HIP runtime.
+
 .. [2] RDNA architectures expand the concept of the traditional compute unit
   with the so-called work group processor, which effectively includes two
   compute units, within which all threads can cooperate.
@@ -8,7 +8,50 @@
 HIP runtime API
 ********************************************************************************

-The HIP Runtime API reference:
+The HIP Runtime API reference includes descriptions of HIP functions, as well as global datatypes, enums, and structs. 

-* :ref:`modules_reference`
-* :ref:`global_defines_enums_structs_files_reference`
+Modules
+=======
+
+The API is organized into modules based on functionality.
+
+* :ref:`initialization_version_reference`
+* :ref:`device_management_reference`
+* :ref:`execution_control_reference`
+* :ref:`error_handling_reference`
+* :ref:`stream_management_reference`
+* :ref:`stream_memory_operations_reference`
+* :ref:`event_management_reference`
+* :ref:`memory_management_reference`
+
+  * :ref:`memory_management_deprecated_reference`
+  * :ref:`external_resource_interoperability_reference`
+  * :ref:`stream_ordered_memory_allocator_reference`
+  * :ref:`unified_memory_reference`
+  * :ref:`virtual_memory_reference`
+  * :ref:`texture_management_reference`
+  * :ref:`texture_management_deprecated_reference`
+  * :ref:`surface_object_reference`
+
+* :ref:`peer_to_peer_device_memory_access_reference`
+* :ref:`context_management_reference`
+* :ref:`module_management_reference`
+* :ref:`occupancy_reference`
+* :ref:`profiler_control_reference`
+* :ref:`launch_api_reference`
+* :ref:`runtime_compilation_reference`
+* :ref:`callback_activity_apis_reference`
+* :ref:`graph_management_reference`
+* :ref:`opengl_interoperability_reference`
+* :ref:`graphics_interoperability_reference`
+* :ref:`cooperative_groups_reference`
+
+Global defines, enums, structs and files
+========================================
+
+The structs, define macros, enums and files in the HIP runtime API.
+
+* :ref:`global_enum_defines_reference`
+* :ref:`driver_types_reference`
+* :doc:`../../doxygen/html/annotated`
+* :doc:`../../doxygen/html/files`