Add HIP 7.0 changes to documentation

Author: randyh62

docs/hip-7-changes.rst

@@ -8,7 +8,7 @@
 HIP API 7.0 changes
 *******************************************************************************
 
-To improve code portability between AMD and NVIDIA GPU programming models specific changes were made to the HIP API in the 7.0 release to simplify cross-platform programming. These changes align HIP C++ even more closely with NVIDIA CUDA. These changes are incompatible with prior releases, and might require recompiling existing HIP applications for use in the 7.0 release, or editing and recompiling code in some cases. In the best case, the change requires no modification of existing applications. These changes were made available in a preview release based on the 6.4.1 release, and as such, hopefully, you have had advanced notice and prepared for the following changes.
+To improve code portability between AMD and NVIDIA GPU programming models, changes were made to the HIP API in ROCm 7.0 to simplify cross-platform programming. These changes align HIP C++ even more closely with NVIDIA CUDA. These changes are incompatible with prior releases, and might require recompiling existing HIP applications for use with ROCm 7.0, or editing and recompiling code in some cases. In the best case, the change requires no modification of existing applications. These changes were made available in a preview release based on ROCm 6.4.1 to help you prepare.
 
 Behavior changes in HIP Runtime API
 ===================================
@@ -163,23 +163,13 @@ Stream capture updates
 Restrict stream capture modes
 -----------------------------
 
-Stream capture mode has been restricted in HIP APIs through the addition of the macro ``CHECK_STREAM_CAPTURE_SUPPORTED``.
-
-In the HIP enumeration ``hipStreamCaptureMode``, three capture modes were previously supported: 
-
-* Global
-* ThreadLocal
-* Relaxed 
-
-As of the 7.0 release, when checking with the ``CHECK_STREAM_CAPTURE_SUPPORTED`` macro the only supported stream capture mode is ``hipStreamCaptureModeRelaxed``. The rest are not supported, and the macro will return ``hipErrorStreamCaptureUnsupported``.
-
-This change matches the behavior of CUDA. There is no impact on any application if stream capture works correctly on the CUDA platform. However, in the HIP runtime the API will return ``hipErrorStreamCaptureUnsupported`` on unsupported stream capture modes.
-
-This update involves the following APIs. They are allowed only in relaxed stream capture mode. Not all three capture modes.
+Stream capture mode has been restricted in the following APIs to relaxed (``hipStreamCaptureModeRelaxed``) mode:
 
 * :cpp:func:`hipMallocManaged`
 * :cpp:func:`hipMemAdvise`
 
+These APIs are allowed only in relaxed stream capture mode. If the functions are used with stream capture, the HIP runtime the will return ``hipErrorStreamCaptureUnsupported`` on unsupported stream capture modes.
+
 Check stream capture mode
 -------------------------
 
@@ -230,7 +220,7 @@ More conditional checks are added in the API implementation, and the return erro
 * If the input stream handle is invalid, the returned error is changed to ``hipErrorContextIsDestroyed`` from ``hipErrorInvalidValue``
 * Adds a grid dimension check, if any input global work size dimension is zero, returns ``hipErrorInvalidValue``
 * Adds extra shared memory size check, if exceeds the size limit, returns ``hipErrorInvalidValue``
-* If the total number of threads per block exceeds the maximum work group limit during a kernel launch, the return value is changed to``hipErrorInvalidConfiguration`` from ``hipErrorInvalidValue``
+* If the total number of threads per block exceeds the maximum work group limit during a kernel launch, the return value is changed to ``hipErrorInvalidConfiguration`` from ``hipErrorInvalidValue``
 
 ``hipModuleLaunchCooperativeKernel``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/how-to/hip_porting_guide.rst

@@ -29,6 +29,8 @@ error code spaces:
 General Tips
 --------------------------------------------------------------------------------
 
+* ``hipDeviceptr_t`` is a ``void*`` and treated like a raw pointer, while ``CUdevicptr``
+  is an ``unsigned int`` and treated as a device memory handle. 
 * Starting to port on an NVIDIA machine is often the easiest approach, as the
   code can be tested for functionality and performance even if not fully ported
   to HIP.

docs/how-to/hip_rtc.rst

@@ -14,6 +14,8 @@ alongside options to guide the compilation.
 
 .. note::
 
+  * Device code compilation via HIPRTC uses the ``__hip_internal`` namespace instead
+    of the ``std`` namespace to avoid namespace collision. 
   * This library can be used for compilation on systems without AMD GPU drivers
     installed (offline compilation). However, running the compiled code still
     requires both the HIP runtime library and GPU drivers on the target system.
@@ -35,6 +37,11 @@ To use HIPRTC functionality the header needs to be included:
 
   #include <hip/hiprtc.h>
 
+.. note::
+
+  Prior to the 7.0 release, the HIP runtime included the hipRTC library. With the 7.0
+  release, the library is separate and must be specifically included as shown above. 
+  
 Kernels can be stored in a string:
 
 .. code-block:: cpp
@@ -255,6 +262,13 @@ The full example is below:
     HIP_CHECK(hipFree(doutput));
   }
 
+.. note::
+
+  Some applications define datatypes such as ``int64_t``, ``uint64_t``, ``int32_t``, and ``uint32_t``
+  that could lead to conflicts when integrating with ``hipRTC``. To resolve these conflicts, these
+  datatypes are replaced with HIP-specific internal datatypes prefixed with ``__hip``. For example,
+  ``int64_t`` is replaced by ``__hip_int64_t``.
+
 HIPRTC specific options
 ===============================================================================
 

docs/how-to/hip_runtime_api/error_handling.rst

@@ -21,11 +21,9 @@ without changing it. To get a human readable version of the errors,
 
 .. note::
 
-    :cpp:func:`hipGetLastError` returns the returned error code of the last HIP
-    runtime API call even if it's ``hipSuccess``, while ``cudaGetLastError``
-    returns the error returned by any of the preceding CUDA APIs in the same
-    host thread. :cpp:func:`hipGetLastError` behavior will be matched with
-    ``cudaGetLastError`` in ROCm release 7.0.
+    :cpp:func:`hipGetLastError` returns the last actual HIP API error caught in the current thread
+    during the application execution. Prior to ROCm 7.0, ``hipGetLastError`` might also return
+    ``hipSuccess`` or ``hipErrorNotReady`` from the last HIP runtime API call, which are not errors.
 
 
 Best practices of HIP error handling:

docs/how-to/hip_runtime_api/memory_management/host_memory.rst

@@ -108,6 +108,8 @@ C++ application.
   :cpp:func:`hipMalloc` and :cpp:func:`hipFree` are blocking calls. However, HIP
   also provides non-blocking versions :cpp:func:`hipMallocAsync` and
   :cpp:func:`hipFreeAsync`, which require a stream as an additional argument.
+  For asynchronous memory allocations made with ``hipMallocAsync`` and ``hipMallocFromPoolAsync``
+  ``hipFree`` does not implicitly wait for synchronization, to match the behavior of ``cudaFree``.
 
 .. _pinned_host_memory:
 

docs/index.md

@@ -11,10 +11,10 @@ and kernel language that lets you create portable applications for AMD and
 NVIDIA GPUs from a single source code. For more information, see [What is HIP?](./what_is_hip)
 
 ```{note}
-The 7.0 release of the HIP API includes backward incompatible changes to make it
-align more closely with NVIDIA CUDA. These change are incompatible with prior releases,
-and may require recompiling existing HIP applications for use in the 7.0 release.
-For more information, see [HIP API 7.0 changes](./hip-7-changes).
+HIP API 7.0 introduces changes to make it align more closely with NVIDIA CUDA.
+These changes are incompatible with prior releases, and might require recompiling
+existing HIP applications for use with the ROCm 7.0 release. For more information,
+see [HIP API 7.0 changes](./hip-7-changes).
 ```
 
 Installation instructions are available from:

docs/reference/complex_math_api.rst

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

docs/reference/error_codes.rst

@@ -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,13 +483,22 @@ 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
     function or is not available for the current device. Common scenarios include:
 
     * 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
 ===============