From 52860ccff165d396ee045ebb08ebdf8d9c594e8c Mon Sep 17 00:00:00 2001 From: Istvan Kiss Date: Mon, 16 Sep 2024 12:25:47 +0200 Subject: [PATCH] HIP runtime API reference reorganize --- .wordlist.txt | 1 + docs/doxygen/Doxyfile | 6 +- docs/doxygen/mainpage.md | 33 --- docs/index.md | 11 +- docs/reference/deprecated_api_list.rst | 232 ++++++++++++------ .../hip_runtime_api/data_structures.rst | 13 + .../hip_runtime_api/data_structures_list.rst | 4 + docs/reference/hip_runtime_api/files.rst | 14 ++ docs/reference/hip_runtime_api/files_list.rst | 2 + .../global_enum_and_defines.rst | 12 + docs/reference/hip_runtime_api/modules.rst | 13 + .../modules/callback_activity_apis.rst | 12 + .../modules/context_management.rst | 12 + .../modules}/cooperative_groups_reference.rst | 6 +- .../modules/device_management.rst | 12 + .../modules/error_handling.rst | 12 + .../modules/event_management.rst | 12 + .../modules/execution_control.rst | 12 + .../modules/graph_management.rst | 12 + .../modules/initialization_and_version.rst | 12 + .../hip_runtime_api/modules/launch_api.rst | 12 + .../modules/memory_management.rst | 12 + .../external_resource_interoperability.rst | 12 + .../stream_ordered_memory_allocator.rst | 12 + .../memory_management/surface_object.rst | 12 + .../memory_management/texture_management.rst | 12 + .../texture_management_deprecated.rst | 12 + .../unified_memory_reference.rst | 5 +- .../virtual_memory_reference.rst | 5 +- .../modules/module_management.rst | 12 + .../hip_runtime_api/modules/occupancy.rst | 12 + .../modules/opengl_interoperability.rst | 12 + .../peer_to_peer_device_memory_access.rst | 12 + .../modules/profiler_control.rst | 12 + .../modules/runtime_compilation.rst | 12 + .../modules/stream_management.rst | 12 + .../modules/stream_memory_operations.rst | 12 + .../hip_runtime_api/modules_list.rst | 28 +++ docs/reference/hip_runtime_api_reference.rst | 33 +++ docs/sphinx/_toc.yml.in | 56 ++++- 40 files changed, 620 insertions(+), 130 deletions(-) delete mode 100644 docs/doxygen/mainpage.md create mode 100644 docs/reference/hip_runtime_api/data_structures.rst create mode 100644 docs/reference/hip_runtime_api/data_structures_list.rst create mode 100644 docs/reference/hip_runtime_api/files.rst create mode 100644 docs/reference/hip_runtime_api/files_list.rst create mode 100644 docs/reference/hip_runtime_api/global_enum_and_defines.rst create mode 100644 docs/reference/hip_runtime_api/modules.rst create mode 100644 docs/reference/hip_runtime_api/modules/callback_activity_apis.rst create mode 100644 docs/reference/hip_runtime_api/modules/context_management.rst rename docs/reference/{ => hip_runtime_api/modules}/cooperative_groups_reference.rst (94%) create mode 100644 docs/reference/hip_runtime_api/modules/device_management.rst create mode 100644 docs/reference/hip_runtime_api/modules/error_handling.rst create mode 100644 docs/reference/hip_runtime_api/modules/event_management.rst create mode 100644 docs/reference/hip_runtime_api/modules/execution_control.rst create mode 100644 docs/reference/hip_runtime_api/modules/graph_management.rst create mode 100644 docs/reference/hip_runtime_api/modules/initialization_and_version.rst create mode 100644 docs/reference/hip_runtime_api/modules/launch_api.rst create mode 100644 docs/reference/hip_runtime_api/modules/memory_management.rst create mode 100644 docs/reference/hip_runtime_api/modules/memory_management/external_resource_interoperability.rst create mode 100644 docs/reference/hip_runtime_api/modules/memory_management/stream_ordered_memory_allocator.rst create mode 100644 docs/reference/hip_runtime_api/modules/memory_management/surface_object.rst create mode 100644 docs/reference/hip_runtime_api/modules/memory_management/texture_management.rst create mode 100644 docs/reference/hip_runtime_api/modules/memory_management/texture_management_deprecated.rst rename docs/reference/{ => hip_runtime_api/modules/memory_management}/unified_memory_reference.rst (67%) rename docs/reference/{ => hip_runtime_api/modules/memory_management}/virtual_memory_reference.rst (67%) create mode 100644 docs/reference/hip_runtime_api/modules/module_management.rst create mode 100644 docs/reference/hip_runtime_api/modules/occupancy.rst create mode 100644 docs/reference/hip_runtime_api/modules/opengl_interoperability.rst create mode 100644 docs/reference/hip_runtime_api/modules/peer_to_peer_device_memory_access.rst create mode 100644 docs/reference/hip_runtime_api/modules/profiler_control.rst create mode 100644 docs/reference/hip_runtime_api/modules/runtime_compilation.rst create mode 100644 docs/reference/hip_runtime_api/modules/stream_management.rst create mode 100644 docs/reference/hip_runtime_api/modules/stream_memory_operations.rst create mode 100644 docs/reference/hip_runtime_api/modules_list.rst create mode 100644 docs/reference/hip_runtime_api_reference.rst diff --git a/.wordlist.txt b/.wordlist.txt index 87d1579669..eebf604b52 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -32,6 +32,7 @@ enqueues entrypoint entrypoints enum +enums embeded extern fatbinary diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index b0e7231aa6..636d850bc8 100644 --- a/docs/doxygen/Doxyfile +++ b/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 diff --git a/docs/doxygen/mainpage.md b/docs/doxygen/mainpage.md deleted file mode 100644 index adda06c877..0000000000 --- a/docs/doxygen/mainpage.md +++ /dev/null @@ -1,33 +0,0 @@ -# HIP Runtime API Reference {#mainpage} - -This is the full HIP Runtime API reference. The API is organized into -[modules](modules.html) based on functionality. - -## List of Modules - -- @ref GlobalDefs -- @ref Driver -- @ref Device -- @ref Execution -- @ref Error -- @ref Stream -- @ref StreamM -- @ref Event -- @ref Memory - - @ref External - - @ref MemoryM - - @ref StreamO -- @ref PeerToPeer -- @ref Context -- @ref Module -- @ref Occupancy -- @ref Profiler -- @ref Clang -- @ref Texture - - @ref TextureD -- @ref Runtime -- @ref Callback -- @ref Graph -- @ref Virtual -- @ref GL -- @ref Surface diff --git a/docs/index.md b/docs/index.md index 2558b73e68..f1849e4df0 100644 --- a/docs/index.md +++ b/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) ::: diff --git a/docs/reference/deprecated_api_list.rst b/docs/reference/deprecated_api_list.rst index bc7e8d7c05..4cee58f9c8 100644 --- a/docs/reference/deprecated_api_list.rst +++ b/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` diff --git a/docs/reference/hip_runtime_api/data_structures.rst b/docs/reference/hip_runtime_api/data_structures.rst new file mode 100644 index 0000000000..55dc15eaea --- /dev/null +++ b/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 diff --git a/docs/reference/hip_runtime_api/data_structures_list.rst b/docs/reference/hip_runtime_api/data_structures_list.rst new file mode 100644 index 0000000000..47110eab2d --- /dev/null +++ b/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` \ No newline at end of file diff --git a/docs/reference/hip_runtime_api/files.rst b/docs/reference/hip_runtime_api/files.rst new file mode 100644 index 0000000000..bbef9330c6 --- /dev/null +++ b/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 diff --git a/docs/reference/hip_runtime_api/files_list.rst b/docs/reference/hip_runtime_api/files_list.rst new file mode 100644 index 0000000000..a4fe1274b6 --- /dev/null +++ b/docs/reference/hip_runtime_api/files_list.rst @@ -0,0 +1,2 @@ +* :doc:`hip:doxygen/html/files` +* :doc:`hip:doxygen/html/globals_globals` \ No newline at end of file diff --git a/docs/reference/hip_runtime_api/global_enum_and_defines.rst b/docs/reference/hip_runtime_api/global_enum_and_defines.rst new file mode 100644 index 0000000000..0660b13007 --- /dev/null +++ b/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: diff --git a/docs/reference/hip_runtime_api/modules.rst b/docs/reference/hip_runtime_api/modules.rst new file mode 100644 index 0000000000..a9d9a8f44b --- /dev/null +++ b/docs/reference/hip_runtime_api/modules.rst @@ -0,0 +1,13 @@ +.. meta:: + :description: HIP runtime API modules reference page + :keywords: AMD, ROCm, HIP, CUDA, HIP runtime API modules + +.. _modules_reference: + +******************************************************************************* +Modules +******************************************************************************* + +The API is organized into modules based on functionality: + +.. include:: modules_list.rst diff --git a/docs/reference/hip_runtime_api/modules/callback_activity_apis.rst b/docs/reference/hip_runtime_api/modules/callback_activity_apis.rst new file mode 100644 index 0000000000..d27c59ebbf --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/callback_activity_apis.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The callback activity APIs reference page. + :keywords: AMD, ROCm, HIP, CUDA, callback activity APIs, callback activity + +.. _callback_activity_apis_reference: + +******************************************************************************* +Callback activity APIs +******************************************************************************* + +.. doxygengroup:: Callback + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/context_management.rst b/docs/reference/hip_runtime_api/modules/context_management.rst new file mode 100644 index 0000000000..83fce7e593 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/context_management.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The context management reference page. + :keywords: AMD, ROCm, HIP, CUDA, context management, context + +.. _context_management_reference: + +******************************************************************************* +Context management [deprecated] +******************************************************************************* + +.. doxygengroup:: Context + :content-only: diff --git a/docs/reference/cooperative_groups_reference.rst b/docs/reference/hip_runtime_api/modules/cooperative_groups_reference.rst similarity index 94% rename from docs/reference/cooperative_groups_reference.rst rename to docs/reference/hip_runtime_api/modules/cooperative_groups_reference.rst index 1191edcbb4..6edc01fc95 100644 --- a/docs/reference/cooperative_groups_reference.rst +++ b/docs/reference/hip_runtime_api/modules/cooperative_groups_reference.rst @@ -1,11 +1,13 @@ .. meta:: - :description: This chapter lists types and device API wrappers related to the Cooperative Group feature. Programmers can directly use these API features in their kernels. + :description: This chapter lists types and device API wrappers related to the + Cooperative Group feature. Programmers can directly use these + API features in their kernels. :keywords: AMD, ROCm, HIP, cooperative groups .. _cooperative_groups_reference: ******************************************************************************* -HIP Cooperative groups API +Cooperative groups ******************************************************************************* Cooperative kernel launches diff --git a/docs/reference/hip_runtime_api/modules/device_management.rst b/docs/reference/hip_runtime_api/modules/device_management.rst new file mode 100644 index 0000000000..17b600f5c5 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/device_management.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The device management reference page. + :keywords: AMD, ROCm, HIP, CUDA, device management, device + +.. _device_management_reference: + +******************************************************************************* +Device management +******************************************************************************* + +.. doxygengroup:: Device + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/error_handling.rst b/docs/reference/hip_runtime_api/modules/error_handling.rst new file mode 100644 index 0000000000..1e2ec4a1f7 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/error_handling.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The error handling reference page. + :keywords: AMD, ROCm, HIP, CUDA, error handling, error + +.. _error_handling_reference: + +******************************************************************************* +Error handling +******************************************************************************* + +.. doxygengroup:: Error + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/event_management.rst b/docs/reference/hip_runtime_api/modules/event_management.rst new file mode 100644 index 0000000000..b4df0d0164 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/event_management.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The event management reference page. + :keywords: AMD, ROCm, HIP, CUDA, event management, event + +.. _event_management_reference: + +******************************************************************************* +Event management +******************************************************************************* + +.. doxygengroup:: Event + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/execution_control.rst b/docs/reference/hip_runtime_api/modules/execution_control.rst new file mode 100644 index 0000000000..dfc5b8d5d6 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/execution_control.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The execution control reference page. + :keywords: AMD, ROCm, HIP, CUDA, execution control, execution + +.. _execution_control_reference: + +******************************************************************************* +Execution control +******************************************************************************* + +.. doxygengroup:: Execution + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/graph_management.rst b/docs/reference/hip_runtime_api/modules/graph_management.rst new file mode 100644 index 0000000000..6bfca89c2f --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/graph_management.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The graph management reference page. + :keywords: AMD, ROCm, HIP, CUDA, graph management, graph + +.. _graph_management_reference: + +******************************************************************************* +Graph management +******************************************************************************* + +.. doxygengroup:: Graph + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/initialization_and_version.rst b/docs/reference/hip_runtime_api/modules/initialization_and_version.rst new file mode 100644 index 0000000000..77317b5647 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/initialization_and_version.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The initialization and version reference page. + :keywords: AMD, ROCm, HIP, CUDA, initialization, version + +.. _driver_reference: + +******************************************************************************* +Initialization and version +******************************************************************************* + +.. doxygengroup:: Driver + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/launch_api.rst b/docs/reference/hip_runtime_api/modules/launch_api.rst new file mode 100644 index 0000000000..ddd3c32c94 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/launch_api.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The launch API reference page. + :keywords: AMD, ROCm, HIP, CUDA, launch API, triple-chevron + +.. _launch_api_reference: + +******************************************************************************* +Launch API +******************************************************************************* + +.. doxygengroup:: Clang + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/memory_management.rst b/docs/reference/hip_runtime_api/modules/memory_management.rst new file mode 100644 index 0000000000..f78805b8f2 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/memory_management.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The memory management reference page. + :keywords: AMD, ROCm, HIP, CUDA, memory management, memory + +.. _memory_management_reference: + +******************************************************************************* +Memory management +******************************************************************************* + +.. doxygengroup:: Memory + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/memory_management/external_resource_interoperability.rst b/docs/reference/hip_runtime_api/modules/memory_management/external_resource_interoperability.rst new file mode 100644 index 0000000000..c002d5136c --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/memory_management/external_resource_interoperability.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The external resource interoperability reference page. + :keywords: AMD, ROCm, HIP, CUDA, external resource interoperability + +.. _external_resource_interoperability_reference: + +******************************************************************************* +External resource interoperability +******************************************************************************* + +.. doxygengroup:: External + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/memory_management/stream_ordered_memory_allocator.rst b/docs/reference/hip_runtime_api/modules/memory_management/stream_ordered_memory_allocator.rst new file mode 100644 index 0000000000..39caaba5e3 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/memory_management/stream_ordered_memory_allocator.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The stream ordered memory allocator reference page. + :keywords: AMD, ROCm, HIP, CUDA, stream ordered memory allocator + +.. _stream_ordered_memory_allocator_reference: + +******************************************************************************* +Stream ordered memory allocator +******************************************************************************* + +.. doxygengroup:: StreamO + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/memory_management/surface_object.rst b/docs/reference/hip_runtime_api/modules/memory_management/surface_object.rst new file mode 100644 index 0000000000..8ccce297c6 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/memory_management/surface_object.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The surface object reference page. + :keywords: AMD, ROCm, HIP, CUDA, surface object, surface + +.. _surface_object_reference: + +******************************************************************************* +Surface object +******************************************************************************* + +.. doxygengroup:: Surface + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/memory_management/texture_management.rst b/docs/reference/hip_runtime_api/modules/memory_management/texture_management.rst new file mode 100644 index 0000000000..4688d5df72 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/memory_management/texture_management.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The texture management reference page. + :keywords: AMD, ROCm, HIP, CUDA, texture management, texture + +.. _texture_management_reference: + +******************************************************************************* +Texture management +******************************************************************************* + +.. doxygengroup:: Texture + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/memory_management/texture_management_deprecated.rst b/docs/reference/hip_runtime_api/modules/memory_management/texture_management_deprecated.rst new file mode 100644 index 0000000000..886a446dbc --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/memory_management/texture_management_deprecated.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The deprecated texture management reference page. + :keywords: AMD, ROCm, HIP, CUDA, deprecated texture management + +.. _texture_management_deprecated_reference: + +******************************************************************************* +Texture management (deprecated) +******************************************************************************* + +.. doxygengroup:: TextureD + :content-only: diff --git a/docs/reference/unified_memory_reference.rst b/docs/reference/hip_runtime_api/modules/memory_management/unified_memory_reference.rst similarity index 67% rename from docs/reference/unified_memory_reference.rst rename to docs/reference/hip_runtime_api/modules/memory_management/unified_memory_reference.rst index 12922d7664..828d4fdcd4 100644 --- a/docs/reference/unified_memory_reference.rst +++ b/docs/reference/hip_runtime_api/modules/memory_management/unified_memory_reference.rst @@ -1,12 +1,11 @@ .. meta:: - :description: This chapter describes introduces Unified Memory (UM) and shows - how to use it in AMD HIP. + :description: The managed memory reference page. :keywords: AMD, ROCm, HIP, CUDA, unified memory, unified, memory, UM, APU .. _unified_memory_reference: ******************************************************************************* -HIP managed memory allocation API +Managed memory ******************************************************************************* .. doxygengroup:: MemoryM diff --git a/docs/reference/virtual_memory_reference.rst b/docs/reference/hip_runtime_api/modules/memory_management/virtual_memory_reference.rst similarity index 67% rename from docs/reference/virtual_memory_reference.rst rename to docs/reference/hip_runtime_api/modules/memory_management/virtual_memory_reference.rst index d8ef7ebd5c..e46b6d91e4 100644 --- a/docs/reference/virtual_memory_reference.rst +++ b/docs/reference/hip_runtime_api/modules/memory_management/virtual_memory_reference.rst @@ -1,12 +1,11 @@ .. meta:: - :description: This topic describes introduces Virtual Memory (VM) and shows - how to use it in AMD HIP. + :description: The virtual memory (VM) management reference page. :keywords: AMD, ROCm, HIP, CUDA, virtual memory, virtual, memory, VM .. _virtual_memory_reference: ******************************************************************************* -HIP virtual memory management API +Virtual memory management ******************************************************************************* .. doxygengroup:: Virtual diff --git a/docs/reference/hip_runtime_api/modules/module_management.rst b/docs/reference/hip_runtime_api/modules/module_management.rst new file mode 100644 index 0000000000..6a5b645b9b --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/module_management.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The module management reference page. + :keywords: AMD, ROCm, HIP, CUDA, module management, module + +.. _module_management_reference: + +******************************************************************************* +Module management +******************************************************************************* + +.. doxygengroup:: Module + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/occupancy.rst b/docs/reference/hip_runtime_api/modules/occupancy.rst new file mode 100644 index 0000000000..492c3f2310 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/occupancy.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The occupancy reference page. + :keywords: AMD, ROCm, HIP, CUDA, occupancy + +.. _occupancy_reference: + +******************************************************************************* +Occupancy +******************************************************************************* + +.. doxygengroup:: Occupancy + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/opengl_interoperability.rst b/docs/reference/hip_runtime_api/modules/opengl_interoperability.rst new file mode 100644 index 0000000000..d90a790fbf --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/opengl_interoperability.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The OpenGL interoperability reference page. + :keywords: AMD, ROCm, HIP, CUDA, OpenGL interoperability, OpenGL interop + +.. _opengl_interoperability_reference: + +******************************************************************************* +OpenGL interoperability +******************************************************************************* + +.. doxygengroup:: GL + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/peer_to_peer_device_memory_access.rst b/docs/reference/hip_runtime_api/modules/peer_to_peer_device_memory_access.rst new file mode 100644 index 0000000000..2797776ae4 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/peer_to_peer_device_memory_access.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The peer to peer device memory access reference page. + :keywords: AMD, ROCm, HIP, CUDA, peer to peer device memory access, peer to peer + +.. _peer_to_peer_device_memory_access_reference: + +******************************************************************************* +Peer to peer device memory access +******************************************************************************* + +.. doxygengroup:: PeerToPeer + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/profiler_control.rst b/docs/reference/hip_runtime_api/modules/profiler_control.rst new file mode 100644 index 0000000000..dd56e485ba --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/profiler_control.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The profiler control reference page. + :keywords: AMD, ROCm, HIP, CUDA, profiler control, profiler + +.. _profiler_control_reference: + +******************************************************************************* +Profiler control +******************************************************************************* + +.. doxygengroup:: Profiler + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/runtime_compilation.rst b/docs/reference/hip_runtime_api/modules/runtime_compilation.rst new file mode 100644 index 0000000000..7c76c2047e --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/runtime_compilation.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The runtime compilation reference page. + :keywords: AMD, ROCm, HIP, CUDA, runtime compilation + +.. _runtime_compilation_reference: + +******************************************************************************* +Runtime compilation +******************************************************************************* + +.. doxygengroup:: Runtime + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/stream_management.rst b/docs/reference/hip_runtime_api/modules/stream_management.rst new file mode 100644 index 0000000000..6e5de67d7c --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/stream_management.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The stream management reference page. + :keywords: AMD, ROCm, HIP, CUDA, stream management, stream + +.. _stream_management_reference: + +******************************************************************************* +Stream management +******************************************************************************* + +.. doxygengroup:: Stream + :content-only: diff --git a/docs/reference/hip_runtime_api/modules/stream_memory_operations.rst b/docs/reference/hip_runtime_api/modules/stream_memory_operations.rst new file mode 100644 index 0000000000..beed1cd314 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules/stream_memory_operations.rst @@ -0,0 +1,12 @@ +.. meta:: + :description: The stream memory operations reference page. + :keywords: AMD, ROCm, HIP, CUDA, stream memory operations + +.. _stream_memory_operations_reference: + +******************************************************************************* +Stream memory operations +******************************************************************************* + +.. doxygengroup:: StreamM + :content-only: diff --git a/docs/reference/hip_runtime_api/modules_list.rst b/docs/reference/hip_runtime_api/modules_list.rst new file mode 100644 index 0000000000..5c18435187 --- /dev/null +++ b/docs/reference/hip_runtime_api/modules_list.rst @@ -0,0 +1,28 @@ +* :ref:`driver_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:`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:`cooperative_groups_reference` \ No newline at end of file diff --git a/docs/reference/hip_runtime_api_reference.rst b/docs/reference/hip_runtime_api_reference.rst new file mode 100644 index 0000000000..e928a93875 --- /dev/null +++ b/docs/reference/hip_runtime_api_reference.rst @@ -0,0 +1,33 @@ +.. meta:: + :description: HIP runtime API reference page + :keywords: AMD, ROCm, HIP, CUDA, HIP runtime API, HIP runtime + +.. _runtime_api_reference: + +******************************************************************************* +HIP runtime API +******************************************************************************* + +This is the full HIP Runtime API reference. + +:doc:`Modules ` +============================================================ + +The API is organized into modules based on functionality. + +.. include:: hip_runtime_api/modules_list.rst + +:doc:`Global defines and enums ` +========================================================================= + +The structs, define macros, typedefs and enums in the HIP runtime API. + +:doc:`Data structures ` +============================================================ + +.. include:: hip_runtime_api/data_structures_list.rst + +:doc:`Files ` +============================================================ + +.. include:: hip_runtime_api/files_list.rst \ No newline at end of file diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 850fde34e1..22779c9f8f 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -37,7 +37,54 @@ subtrees: - caption: Reference entries: - - file: doxygen/html/index + - file: reference/hip_runtime_api_reference + subtrees: + - entries: + - file: reference/hip_runtime_api/modules + subtrees: + - entries: + - file: reference/hip_runtime_api/modules/initialization_and_version + - file: reference/hip_runtime_api/modules/device_management + - file: reference/hip_runtime_api/modules/execution_control + - file: reference/hip_runtime_api/modules/error_handling + - file: reference/hip_runtime_api/modules/stream_management + - file: reference/hip_runtime_api/modules/stream_memory_operations + - file: reference/hip_runtime_api/modules/event_management + - file: reference/hip_runtime_api/modules/memory_management + subtrees: + - entries: + - file: reference/hip_runtime_api/modules/memory_management/external_resource_interoperability + - file: reference/hip_runtime_api/modules/memory_management/stream_ordered_memory_allocator + - file: reference/hip_runtime_api/modules/memory_management/unified_memory_reference + - file: reference/hip_runtime_api/modules/memory_management/virtual_memory_reference + - file: reference/hip_runtime_api/modules/memory_management/texture_management + - file: reference/hip_runtime_api/modules/memory_management/texture_management_deprecated + - file: reference/hip_runtime_api/modules/memory_management/surface_object + - file: reference/hip_runtime_api/modules/peer_to_peer_device_memory_access + - file: reference/hip_runtime_api/modules/context_management + - file: reference/hip_runtime_api/modules/module_management + - file: reference/hip_runtime_api/modules/occupancy + - file: reference/hip_runtime_api/modules/profiler_control + - file: reference/hip_runtime_api/modules/launch_api + - file: reference/hip_runtime_api/modules/runtime_compilation + - file: reference/hip_runtime_api/modules/callback_activity_apis + - file: reference/hip_runtime_api/modules/graph_management + - file: reference/hip_runtime_api/modules/opengl_interoperability + - file: reference/hip_runtime_api/modules/cooperative_groups_reference + - file: reference/hip_runtime_api/global_enum_and_defines + - file: reference/hip_runtime_api/data_structures + subtrees: + - entries: + - file: doxygen/html/annotated + - file: doxygen/html/classes + - file: doxygen/html/inherits + - file: doxygen/html/functions_data_fields + - file: reference/hip_runtime_api/files + subtrees: + - entries: + - file: doxygen/html/files + - file: doxygen/html/globals_globals + - file: reference/virtual_rocr - file: reference/cpp_language_extensions title: C++ language extensions - file: reference/cpp_language_support @@ -45,13 +92,6 @@ subtrees: - file: reference/math_api - file: reference/terms title: Comparing syntax for different APIs - - file: reference/cooperative_groups_reference - title: HIP Cooperative groups API - - file: reference/virtual_rocr - - file: reference/unified_memory_reference - title: HIP managed memory allocation API - - file: reference/virtual_memory_reference - title: HIP virtual memory management API - file: reference/deprecated_api_list title: List of deprecated APIs