HIP runtime API reference reorganize

.wordlist.txt

@@ -32,6 +32,7 @@ enqueues
 entrypoint
 entrypoints
 enum
+enums
 embeded
 extern
 fatbinary

docs/doxygen/Doxyfile

@@ -829,12 +829,11 @@ WARN_LOGFILE =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT = mainpage.md \
- ../../include/hip \
+INPUT = ../../include/hip \
  ../../../clr/hipamd/include/hip/amd_detail/amd_hip_gl_interop.h \
  ../../../clr/hipamd/include/hip/amd_detail/amd_surface_functions.h \
  ../../../clr/hipamd/include/hip/amd_detail/amd_hip_cooperative_groups.h \
- ../../../ROCR-Runtime/src/inc/hsa_ext_amd.h
+ ../../../ROCR-Runtime/runtime/hsa-runtime/inc/hsa_ext_amd.h
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2207,6 +2206,7 @@ PREDEFINED = "__HIP_PLATFORM_AMD__" \
  "__CG_QUALIFIER__=" \
  "__CG_STATIC_QUALIFIER__=static" \
  "_CG_STATIC_CONST_DECL_=static constexpr" \
+ "HIP_PUBLIC_API" \
  "HIP_ENABLE_WARP_SYNC_BUILTINS"
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this

docs/index.md

@@ -53,15 +53,16 @@ On non-AMD platforms, like NVIDIA, HIP provides header files required to support
 
 :::{grid-item-card} Reference
 
-* {doc}`/doxygen/html/index`
+* [HIP runtime API](./reference/hip_runtime_api_reference)
+ * {ref}`modules_reference`
+ * {doc}`reference/hip_runtime_api/global_enum_and_defines`
+ * {doc}`reference/hip_runtime_api/data_structures`
+ * {doc}`reference/hip_runtime_api/files`
+* [HSA runtime API for ROCm](./reference/virtual_rocr)
 * [C++ language extensions](./reference/cpp_language_extensions)
 * [C++ language support](./reference/cpp_language_support)
 * [HIP math API](./reference/math_api)
 * [Comparing syntax for different APIs](./reference/terms)
-* [HSA runtime API for ROCm](./reference/virtual_rocr)
-* [HIP managed memory allocation API](./reference/unified_memory_reference)
-* [HIP virtual memory management API](./reference/virtual_memory_reference)
-* [HIP Cooperative groups API](./reference/cooperative_groups_reference)
 * [List of deprecated APIs](./reference/deprecated_api_list)
 
 :::

docs/reference/deprecated_api_list.rst

@@ -6,88 +6,174 @@
 HIP deprecated runtime API functions
 **********************************************************************************************
 
-Several of our API functions have been flagged for deprecation. Using the following functions results in
-errors and unexpected results, so we encourage you to update your code accordingly.
+Several of our API functions have been flagged for deprecation. Using the
+following functions results in errors and unexpected results, so we encourage
+you to update your code accordingly.
 
-Context management
+Deprecated since ROCm 1.6.0
 ============================================================
 
-CUDA supports cuCtx API, which is the driver API that defines "Context" and "Devices" as separate
-entities. Context contains a single device, and a device can theoretically have multiple contexts. HIP
-initially added limited support for these APIs in order to facilitate porting from existing driver codes.
-These APIs are now marked as deprecated because there are better alternate interfaces (such as
-``hipSetDevice`` or the stream API) to achieve these functions.
-
-* ``hipCtxCreate``
-* ``hipCtxDestroy``
-* ``hipCtxPopCurrent``
-* ``hipCtxPushCurrent``
-* ``hipCtxSetCurrent``
-* ``hipCtxGetCurrent``
-* ``hipCtxGetDevice``
-* ``hipCtxGetApiVersion``
-* ``hipCtxGetCacheConfig``
-* ``hipCtxSetCacheConfig``
-* ``hipCtxSetSharedMemConfig``
-* ``hipCtxGetSharedMemConfig``
-* ``hipCtxSynchronize``
-* ``hipCtxGetFlags``
-* ``hipCtxEnablePeerAccess``
-* ``hipCtxDisablePeerAccess``
-* ``hipDevicePrimaryCtxGetState``
-* ``hipDevicePrimaryCtxRelease``
-* ``hipDevicePrimaryCtxRetain``
-* ``hipDevicePrimaryCtxReset``
-* ``hipDevicePrimaryCtxSetFlags``
-
-Memory management
+Deprecated memory management functions.
+
+.. list-table::
+ :widths: 40, 60
+ :header-rows: 1
+ :align: left
+
+ * - function
+ -
+ * - :cpp:func:`hipMallocHost`
+ - replaced with :cpp:func:`hipHostMalloc`
+ * - :cpp:func:`hipMemAllocHost`
+ - replaced with :cpp:func:`hipHostMalloc`
+ * - :cpp:func:`hipFreeHost`
+ - replaced with :cpp:func:`hipHostFree`
+
+Deprecated since ROCm 1.9.0
 ============================================================
 
-* ``hipMallocHost`` (replaced with ``hipHostMalloc``)
-* ``hipMemAllocHost`` (replaced with ``hipHostMalloc``)
-* ``hipFreeHost`` (replaced with ``hipHostFree``)
-* ``hipMemcpyToArray``
-* ``hipMemcpyFromArray``
+CUDA supports cuCtx API, which is the driver API that defines "Context" and
+"Devices" as separate entities. Context contains a single device, and a device
+can theoretically have multiple contexts. HIP initially added limited support
+for context APIs in order to facilitate porting from existing driver codes. These
+APIs are now marked as deprecated because there are better alternate interfaces
+(such as ``hipSetDevice`` or the stream API) to achieve these functions.
+
+.. list-table::
+ :widths: 40
+ :header-rows: 1
+ :align: left
 
-Profiler control
+ * - function
+ * - :cpp:func:`hipCtxCreate`
+ * - :cpp:func:`hipCtxDestroy`
+ * - :cpp:func:`hipCtxPopCurrent`
+ * - :cpp:func:`hipCtxPushCurrent`
+ * - :cpp:func:`hipCtxSetCurrent`
+ * - :cpp:func:`hipCtxGetCurrent`
+ * - :cpp:func:`hipCtxGetDevice`
+ * - :cpp:func:`hipCtxGetApiVersion`
+ * - :cpp:func:`hipCtxGetCacheConfig`
+ * - :cpp:func:`hipCtxSetCacheConfig`
+ * - :cpp:func:`hipCtxSetSharedMemConfig`
+ * - :cpp:func:`hipCtxGetSharedMemConfig`
+ * - :cpp:func:`hipCtxSynchronize`
+ * - :cpp:func:`hipCtxGetFlags`
+ * - :cpp:func:`hipCtxEnablePeerAccess`
+ * - :cpp:func:`hipCtxDisablePeerAccess`
+ * - :cpp:func:`hipDevicePrimaryCtxGetState`
+ * - :cpp:func:`hipDevicePrimaryCtxRelease`
+ * - :cpp:func:`hipDevicePrimaryCtxRetain`
+ * - :cpp:func:`hipDevicePrimaryCtxReset`
+ * - :cpp:func:`hipDevicePrimaryCtxSetFlags`
+
+
+Deprecated since ROCm 3.0.0
 ============================================================
 
-* ``hipProfilerStart`` (use roctracer/rocTX)
-* ``hipProfilerStop`` (use roctracer/rocTX)
+The ``hipProfilerStart`` and ``hipProfilerStop`` functions are deprecated. 
+Instead, you can use ``roctracer`` or ``rocTX`` for profiling which provide more 
+flexibility and detailed profiling capabilities. 
 
+.. list-table::
+ :widths: 40
+ :header-rows: 1
+ :align: left
 
-Texture management
+ * - function
+ * - :cpp:func:`hipProfilerStart`
+ * - :cpp:func:`hipProfilerStop`
+
+Deprecated since ROCm 3.8.0
 ============================================================
 
-* ``hipGetTextureReference``
-* ``hipTexRefSetAddressMode``
-* ``hipTexRefSetArray``
-* ``hipTexRefSetFilterMode``
-* ``hipTexRefSetFlags``
-* ``hipTexRefSetFormat``
-* ``hipTexRefGetAddress``
-* ``hipTexRefGetAddressMode``
-* ``hipTexRefGetFilterMode``
-* ``hipTexRefGetFlags``
-* ``hipTexRefGetFormat``
-* ``hipTexRefGetMaxAnisotropy``
-* ``hipTexRefGetMipmapFilterMode``
-* ``hipTexRefGetMipmapLevelBias``
-* ``hipTexRefGetMipmapLevelClamp``
-* ``hipTexRefGetMipMappedArray``
-* ``hipTexRefSetAddress``
-* ``hipTexRefSetAddress2D``
-* ``hipTexRefSetMaxAnisotropy``
-* ``hipTexRefSetBorderColor``
-* ``hipTexRefSetMipmapFilterMode``
-* ``hipTexRefSetMipmapLevelBias``
-* ``hipTexRefSetMipmapLevelClamp``
-* ``hipTexRefSetMipmappedArray``
-* ``hipTexRefGetBorderColor``
-* ``hipTexRefGetArray``
-* ``hipBindTexture``
-* ``hipBindTexture2D``
-* ``hipBindTextureToArray``
-* ``hipGetTextureAlignmentOffset``
-* ``hipUnbindTexture``
-* ``hipBindTextureToMipmappedArray``
+Deprecated memory management and texture management functions.
+
+.. list-table::
+ :widths: 40
+ :header-rows: 1
+ :align: left
+
+ * - function
+ * - :cpp:func:`hipBindTexture`
+ * - :cpp:func:`hipBindTexture2D`
+ * - :cpp:func:`hipBindTextureToArray`
+ * - :cpp:func:`hipGetTextureAlignmentOffset`
+ * - :cpp:func:`hipUnbindTexture`
+ * - :cpp:func:`hipMemcpyToArray`
+ * - :cpp:func:`hipMemcpyFromArray`
+
+Deprecated since ROCm 4.3.0
+============================================================
+
+Deprecated texture management functions.
+
+.. list-table::
+ :widths: 40
+ :header-rows: 1
+ :align: left
+
+ * - function
+ * - :cpp:func:`hipTexRefSetFlags`
+ * - :cpp:func:`hipTexRefSetFormat`
+ * - :cpp:func:`hipTexRefGetAddress`
+ * - :cpp:func:`hipTexRefGetAddressMode`
+ * - :cpp:func:`hipTexRefGetFilterMode`
+ * - :cpp:func:`hipTexRefGetFlags`
+ * - :cpp:func:`hipTexRefGetFormat`
+ * - :cpp:func:`hipTexRefGetMaxAnisotropy`
+ * - :cpp:func:`hipTexRefGetMipmapFilterMode`
+ * - :cpp:func:`hipTexRefGetMipmapLevelBias`
+ * - :cpp:func:`hipTexRefGetMipmapLevelClamp`
+ * - :cpp:func:`hipTexRefGetMipMappedArray`
+ * - :cpp:func:`hipTexRefSetAddress`
+ * - :cpp:func:`hipTexRefSetAddress2D`
+ * - :cpp:func:`hipTexRefSetMaxAnisotropy`
+
+Deprecated since ROCm 5.3.0
+============================================================
+
+Deprecated texture management functions.
+
+.. list-table::
+ :widths: 40
+ :header-rows: 1
+ :align: left
+
+ * - function
+ * - :cpp:func:`hipGetTextureReference`
+ * - :cpp:func:`hipTexRefSetAddressMode`
+ * - :cpp:func:`hipTexRefSetArray`
+ * - :cpp:func:`hipTexRefSetFilterMode`
+ * - :cpp:func:`hipTexRefSetBorderColor`
+ * - :cpp:func:`hipTexRefSetMipmapFilterMode`
+ * - :cpp:func:`hipTexRefSetMipmapLevelBias`
+ * - :cpp:func:`hipTexRefSetMipmapLevelClamp`
+ * - :cpp:func:`hipTexRefSetMipmappedArray`
+
+Deprecated since ROCm 5.7.0
+============================================================
+
+Deprecated texture management functions.
+
+.. list-table::
+ :widths: 40
+ :header-rows: 1
+ :align: left
+
+ * - function
+ * - :cpp:func:`hipBindTextureToMipmappedArray`
+
+Deprecated since ROCm 6.1.0
+============================================================
+
+Deprecated texture management functions.
+
+.. list-table::
+ :widths: 40
+ :header-rows: 1
+ :align: left
+
+ * - function
+ * - :cpp:func:`hipTexRefGetBorderColor`
+ * - :cpp:func:`hipTexRefGetArray`

docs/reference/hip_runtime_api/data_structures.rst

@@ -0,0 +1,13 @@
+.. meta::
+ :description: HIP runtime data structures reference page.
+ :keywords: AMD, ROCm, HIP, CUDA, HIP runtime data structures
+
+.. _data_structures_reference:
+
+*******************************************************************************
+Data structures
+*******************************************************************************
+
+The API is organized into modules based on functionality:
+
+.. include:: data_structures_list.rst

docs/reference/hip_runtime_api/data_structures_list.rst

@@ -0,0 +1,4 @@
+* :doc:`hip:doxygen/html/annotated`
+* :doc:`hip:doxygen/html/classes`
+* :doc:`hip:doxygen/html/inherits`
+* :doc:`hip:doxygen/html/functions_data_fields`

docs/reference/hip_runtime_api/files.rst

@@ -0,0 +1,14 @@
+.. meta::
+ :description: HIP runtime files reference page.
+ :keywords: AMD, ROCm, HIP, CUDA, HIP runtime files
+
+.. _files_reference:
+
+*******************************************************************************
+Files
+*******************************************************************************
+
+The list of all files with brief descriptions and a list of all functions,
+variables, defines, enums, and typedefs with links to the files they belong to.
+
+.. include:: files_list.rst

docs/reference/hip_runtime_api/files_list.rst

@@ -0,0 +1,2 @@
+* :doc:`hip:doxygen/html/files`
+* :doc:`hip:doxygen/html/globals_globals`

docs/reference/hip_runtime_api/global_enum_and_defines.rst

@@ -0,0 +1,12 @@
+.. meta::
+ :description: The global enum and defines reference page.
+ :keywords: AMD, ROCm, HIP, CUDA, global enum, defines
+
+.. _global_enum_defines_reference:
+
+*******************************************************************************
+Global enum and defines
+*******************************************************************************
+
+.. doxygengroup:: GlobalDefs
+ :content-only: