SWDEV-490062 - Update documentation

Change-Id: Ib5297fdda2e05795b3b20436cc1de962e310b08b
2024-10-21 16:50:09 +02:00
@@ -0,0 +1,171 @@
+.. meta::
+  :description: This chapter describes the C++ support of the HIP ecosystem
+                ROCm software.
+  :keywords: AMD, ROCm, HIP, C++
+
+*******************************************************************************
+C++ language support
+*******************************************************************************
+
+The ROCm platform enables the power of combined C++ and HIP (Heterogeneous-computing
+Interface for Portability) code. This code is compiled with a ``clang`` or ``clang++``
+compiler. The official compilers support the HIP platform, or you can use the
+``amdclang`` or ``amdclang++`` included in the ROCm installation, which are a wrapper for
+the official versions.
+
+The source code is compiled according to the ``C++03``, ``C++11``, ``C++14``, ``C++17``,
+and ``C++20`` standards, along with HIP-specific extensions, but is subject to
+restrictions. The key restriction is the reduced support of standard library in device
+code. This is due to the fact that by default a function is considered to run on host,
+except for ``constexpr`` functions, which can run on host and device as well.
+
+.. _language_modern_cpp_support:
+
+Modern C++ support
+===============================================================================
+
+C++ is considered a modern programming language as of C++11. This section describes how
+HIP supports these new C++ features.
+
+C++11 support
+-------------------------------------------------------------------------------
+
+The C++11 standard introduced many new features. These features are supported in HIP host
+code, with some notable omissions on the device side. The rule of thumb here is that
+``constexpr`` functions work on device, the rest doesn't. This means that some important
+functionality like ``std::function`` is missing on the device, but unfortunately the
+standard library wasn't designed with HIP in mind, which means that the support is in a
+state of "works as-is".
+
+Certain features have restrictions and clarifications. For example, any functions using
+the ``constexpr`` qualifier or the new ``initializer lists``, ``std::move`` or
+``std::forward`` features are implicitly considered to have the ``__host__`` and
+``__device__`` execution space specifier. Also, ``constexpr`` variables that are static
+members or namespace scoped can be used from both host and device, but only for read
+access. Dereferencing a static ``constexpr`` outside its specified execution space causes
+an error.
+
+Lambdas are supported, but there are some extensions and restrictions on their usage. For
+more information, see the `Extended lambdas`_ section below.
+
+C++14 support
+-------------------------------------------------------------------------------
+
+The C++14 language features are supported.
+
+C++17 support
+-------------------------------------------------------------------------------
+
+All C++17 language features are supported.
+
+C++20 support
+-------------------------------------------------------------------------------
+
+All C++20 language features are supported, but extensions and restrictions apply. C++20
+introduced coroutines and modules, which fundamentally changed how programs are written.
+HIP doesn't support these features. However, ``consteval`` functions can be called from
+host and device, even if specified for host use only.
+
+The three-way comparison operator (spaceship operator ``<=>``) works with host and device
+code.
+
+.. _language_restrictions:
+
+Extensions and restrictions
+===============================================================================
+
+In addition to the deviations from the standard, there are some general extensions and
+restrictions to consider.
+
+Global functions
+-------------------------------------------------------------------------------
+
+Functions that serve as an entry point for device execution are called kernels and are
+specified with the ``__global__`` qualifier. To call a kernel function, use the triple
+chevron operator: ``<<< >>>``. Kernel functions must have a ``void`` return type. These
+functions can't:
+
+* have a ``constexpr`` specifier
+* have a parameter of type ``std::initializer_list`` or ``va_list``
+* use an rvalue reference as a parameter.
+* use parameters having different sizes in host and device code, e.g. long double arguments, or structs containing long double members.
+* use struct-type arguments which have different layout in host and device code.
+
+Kernels can have variadic template parameters, but only one parameter pack, which must be
+the last item in the template parameter list.
+
+Device space memory specifiers
+-------------------------------------------------------------------------------
+
+HIP includes device space memory specifiers to indicate whether a variable is allocated
+in host or device memory and how its memory should be allocated. HIP supports the
+``__device__``, ``__shared__``, ``__managed__``, and ``__constant__`` specifiers.
+
+The ``__device__`` and ``__constant__`` specifiers define global variables, which are
+allocated within global memory on the HIP devices. The only difference is that
+``__constant__`` variables can't be changed after allocation. The ``__shared__``
+specifier allocates the variable within shared memory, which is available for all threads
+in a block.
+
+The ``__managed__`` variable specifier creates global variables that are initially
+undefined and unaddressed within the global symbol table. The HIP runtime allocates
+managed memory and defines the symbol when it loads the device binary. A managed variable
+can be accessed in both device and host code.
+
+It's important to know where a variable is stored because it is only available from
+certain locations. Generally, variables allocated in the host memory are not accessible
+from the device code, while variables allocated in the device memory are not directly
+accessible from the host code. Dereferencing a pointer to device memory on the host
+results in a segmentation fault. Accessing device variables in host code should be done
+through kernel execution or HIP functions like ``hipMemCpyToSymbol``.
+
+Exception handling
+-------------------------------------------------------------------------------
+
+An important difference between the host and device code is exception handling. In device
+code, this control flow isn't available due to the hardware architecture. The device
+code must use return codes to handle errors.
+
+Kernel parameters
+-------------------------------------------------------------------------------
+
+There are some restrictions on kernel function parameters. They cannot be passed by
+reference, because these functions are called from the host but run on the device. Also,
+a variable number of arguments is not allowed.
+
+Classes
+-------------------------------------------------------------------------------
+
+Classes work on both the host and device side, but there are some constraints. The
+``static`` member functions can't be ``__global__``. ``Virtual`` member functions work,
+but a ``virtual`` function must not be called from the host if the parent object was
+created on the device, or the other way around, because this behavior is undefined.
+Another minor restriction is that ``__device__`` variables, that are global scoped must
+have trivial constructors.
+
+Polymorphic function wrappers
+-------------------------------------------------------------------------------
+
+HIP doesn't support the polymorphic function wrapper ``std::function``, which was
+introduced in C++11.
+
+Extended lambdas
+-------------------------------------------------------------------------------
+
+HIP supports Lambdas, which by default work as expected.
+
+Lambdas have implicit host device attributes. This means that they can be executed by
+both host and device code, and works the way you would expect. To make a lambda callable
+only by host or device code, users can add ``__host__`` or ``__device__`` attribute. The
+only restriction is that host variables can only be accessed through copy on the device.
+Accessing through reference will cause undefined behavior.
+
+Inline namespaces
+-------------------------------------------------------------------------------
+
+Inline namespaces are supported, but with a few exceptions. The following entities can't
+be declared in namespace scope within an inline unnamed namespace:
+
+* ``__managed__``, ``__device__``, ``__shared__`` and ``__constant__`` variables
+* ``__global__`` function and function templates
+* variables with surface or texture type
@@ -28,7 +28,7 @@ There are two formats of FP8 numbers, E4M3 and E5M2.
 HIP Header
 ==========

-HIP header defined the FP8 ocp/fnuz numbers `here <https://github.com/ROCm/clr/blob/develop/hipamd/include/hip/amd_detail/amd_hip_fp8.h>`_.
+The `HIP header <https://github.com/ROCm/clr/blob/develop/hipamd/include/hip/amd_detail/amd_hip_fp8.h>`_ defines the FP8 ocp/fnuz numbers.

 Supported Devices
 =================
@@ -0,0 +1,15 @@
+.. meta::
+  :description: The global defines, enum, structs and files reference page.
+
+.. _global_defines_enums_structs_files_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:`hip:doxygen/html/annotated`
+* :doc:`hip:doxygen/html/files`
@@ -0,0 +1,12 @@
+.. meta::
+  :description: The driver types reference page.
+  :keywords: AMD, ROCm, HIP, CUDA, driver types
+
+.. _driver_types_reference:
+
+*******************************************************************************
+Driver types
+*******************************************************************************
+
+.. doxygengroup:: DriverTypes
+   :content-only:
@@ -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:
@@ -0,0 +1,41 @@
+.. meta::
+  :description: The HIP runtime API modules reference page.
+  :keywords: AMD, ROCm, HIP, CUDA, HIP runtime API modules, modules
+
+.. _modules_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:`cooperative_groups_reference`
@@ -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:
@@ -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:
@@ -0,0 +1,70 @@
+.. 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.
+  :keywords: AMD, ROCm, HIP, cooperative groups
+
+.. _cooperative_groups_reference:
+
+*******************************************************************************
+Cooperative groups
+*******************************************************************************
+
+Cooperative kernel launches
+===========================
+
+The following host-side functions are used for cooperative kernel launches.
+
+.. doxygengroup:: ModuleCooperativeG
+   :content-only:
+
+Cooperative groups classes
+==========================
+
+The following cooperative groups classes can be used on the device side.
+
+.. _thread_group_ref:
+
+.. doxygenclass:: cooperative_groups::thread_group
+   :members:
+
+.. _thread_block_ref:
+
+.. doxygenclass:: cooperative_groups::thread_block
+   :members:
+
+.. _grid_group_ref:
+
+.. doxygenclass:: cooperative_groups::grid_group
+   :members:
+
+.. _multi_grid_group_ref:
+
+.. doxygenclass:: cooperative_groups::multi_grid_group
+   :members:
+ 
+.. _thread_block_tile_ref:
+
+.. doxygenclass:: cooperative_groups::thread_block_tile
+   :members:
+
+.. _coalesced_group_ref:
+
+.. doxygenclass:: cooperative_groups::coalesced_group
+   :members:
+
+Cooperative groups construct functions
+======================================
+
+The following functions are used to construct different group-type instances on the device side.
+
+.. doxygengroup:: CooperativeGConstruct
+   :content-only:
+
+Cooperative groups exposed API functions
+========================================
+
+The following functions are the exposed API for different group-type instances on the device side.
+
+.. doxygengroup:: CooperativeGAPI
+   :content-only:
@@ -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:
@@ -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:
@@ -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:
@@ -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:
@@ -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:
@@ -0,0 +1,12 @@
+.. meta::
+  :description: The initialization and version reference page.
+  :keywords: AMD, ROCm, HIP, CUDA, initialization, version
+
+.. _initialization_version_reference:
+
+*******************************************************************************
+Initialization and version
+*******************************************************************************
+
+.. doxygengroup:: Driver
+   :content-only:
@@ -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:
@@ -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:
@@ -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:
@@ -0,0 +1,11 @@
+.. meta::
+  :description: The deprecated memory management reference page.
+
+.. _memory_management_deprecated_reference:
+
+*******************************************************************************
+Memory management (deprecated)
+*******************************************************************************
+
+.. doxygengroup:: MemoryD
+   :content-only:
@@ -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:
@@ -0,0 +1,15 @@
+.. meta::
+  :description: The surface object reference page.
+  :keywords: AMD, ROCm, HIP, CUDA, surface object, surface
+
+.. _surface_object_reference:
+
+*******************************************************************************
+Surface object
+*******************************************************************************
+
+.. doxygengroup:: Surface
+   :content-only:
+
+.. doxygengroup:: SurfaceAPI
+   :content-only:
@@ -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:
@@ -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:
@@ -0,0 +1,12 @@
+.. meta::
+  :description: The managed memory reference page.
+  :keywords: AMD, ROCm, HIP, CUDA, unified memory, unified, memory, UM, APU
+
+.. _unified_memory_reference:
+
+*******************************************************************************
+Managed memory
+*******************************************************************************
+
+.. doxygengroup:: MemoryM
+   :content-only:
@@ -0,0 +1,12 @@
+.. meta::
+  :description: The virtual memory (VM) management reference page.
+  :keywords: AMD, ROCm, HIP, CUDA, virtual memory, virtual, memory, VM
+
+.. _virtual_memory_reference:
+
+*******************************************************************************
+Virtual memory management
+*******************************************************************************
+
+.. doxygengroup:: Virtual
+   :content-only:
@@ -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:
@@ -0,0 +1,12 @@
+.. meta::
+  :description: The occupancy reference page.
+  :keywords: AMD, ROCm, HIP, CUDA, occupancy
+
+.. _occupancy_reference:
+
+*******************************************************************************
+Occupancy
+*******************************************************************************
+
+.. doxygengroup:: Occupancy
+   :content-only:
@@ -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:
@@ -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:
@@ -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:
@@ -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:
@@ -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:
@@ -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:
@@ -0,0 +1,14 @@
+.. meta::
+  :description: HIP runtime API reference page
+  :keywords: AMD, ROCm, HIP, CUDA, HIP runtime API, HIP runtime
+
+.. _runtime_api_reference:
+
+********************************************************************************
+HIP runtime API
+********************************************************************************
+
+The HIP Runtime API reference:
+
+* :ref:`modules_reference`
+* :ref:`global_defines_enums_structs_files_reference`
@@ -1,4 +1,4 @@
-# Table Comparing Syntax for Different Compute APIs
+# Table comparing syntax for different compute APIs

 |Term|CUDA|HIP|OpenCL|
 |---|---|---|---|
@@ -5,7 +5,7 @@
  :keywords: AMD, ROCm, HIP, HSA, ROCR runtime, virtual memory management

 *******************************************************************************
-HSA Runtime API for ROCm
+HSA runtime API for ROCm
 *******************************************************************************

 The following functions are located in the https://github.com/ROCm/ROCR-Runtime repository.