diff --git a/.wordlist.txt b/.wordlist.txt index 5e266ba469..a8d49b2012 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -17,6 +17,7 @@ clr coroutines cuBLASLt cuCtx +CUDA's cuDNN dataflow deallocate @@ -52,7 +53,9 @@ hcBLAS icc IILE iGPU +inlined inplace +interop Interoperation interoperate Intrinsics @@ -107,6 +110,7 @@ scalarizing sceneries shaders SIMT +SOMA SPMV structs SYCL diff --git a/docs/.gitignore b/docs/.gitignore index 53b7787fbd..f43f04af9f 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -5,4 +5,4 @@ /_templates /doxygen/html /doxygen/xml -/sphinx/_toc.yml +/sphinx/_toc.yml \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 82bcefee89..2db96905c9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,7 +47,6 @@ numfig = False - exclude_patterns = [ "doxygen/mainpage.md", "understand/glossary.md" diff --git a/docs/data/how-to/cooperative_groups/thread_hierarchy_coop_bottom.drawio b/docs/data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_bottom.drawio similarity index 100% rename from docs/data/how-to/cooperative_groups/thread_hierarchy_coop_bottom.drawio rename to docs/data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_bottom.drawio diff --git a/docs/data/how-to/cooperative_groups/thread_hierarchy_coop_bottom.svg b/docs/data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_bottom.svg similarity index 100% rename from docs/data/how-to/cooperative_groups/thread_hierarchy_coop_bottom.svg rename to docs/data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_bottom.svg diff --git a/docs/data/how-to/cooperative_groups/thread_hierarchy_coop_top.drawio b/docs/data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_top.drawio similarity index 100% rename from docs/data/how-to/cooperative_groups/thread_hierarchy_coop_top.drawio rename to docs/data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_top.drawio diff --git a/docs/data/how-to/cooperative_groups/thread_hierarchy_coop_top.svg b/docs/data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_top.svg similarity index 100% rename from docs/data/how-to/cooperative_groups/thread_hierarchy_coop_top.svg rename to docs/data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_top.svg diff --git a/docs/data/unified_memory/um.drawio b/docs/data/how-to/hip_runtime_api/memory_management/unified_memory/um.drawio similarity index 100% rename from docs/data/unified_memory/um.drawio rename to docs/data/how-to/hip_runtime_api/memory_management/unified_memory/um.drawio diff --git a/docs/data/unified_memory/um.svg b/docs/data/how-to/hip_runtime_api/memory_management/unified_memory/um.svg similarity index 100% rename from docs/data/unified_memory/um.svg rename to docs/data/how-to/hip_runtime_api/memory_management/unified_memory/um.svg diff --git a/docs/data/how-to/hip_runtime_api/runtimes.drawio b/docs/data/how-to/hip_runtime_api/runtimes.drawio new file mode 100644 index 0000000000..ee1425b2ae --- /dev/null +++ b/docs/data/how-to/hip_runtime_api/runtimes.drawio @@ -0,0 +1,130 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/data/how-to/hip_runtime_api/runtimes.svg b/docs/data/how-to/hip_runtime_api/runtimes.svg new file mode 100644 index 0000000000..12edbdf831 --- /dev/null +++ b/docs/data/how-to/hip_runtime_api/runtimes.svg @@ -0,0 +1,2 @@ +Runtimes
HIP Runtime API
HIP Runtime API
CUDA Driver API
CUDA Driver API
CUDA runtime
CUDA runtime
ROCr runtime
ROCr runtime
PAL
PAL
CLR
CLR
AMD Platform
AMD Platform +
NVIDIA Platform
NVIDIA PlatformText is not SVG - cannot display \ No newline at end of file diff --git a/docs/data/how-to/hip_runtime_api/stream_management.drawio b/docs/data/how-to/hip_runtime_api/stream_management.drawio new file mode 100644 index 0000000000..2b443fe3f0 --- /dev/null +++ b/docs/data/how-to/hip_runtime_api/stream_management.drawio @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/data/how-to/hip_runtime_api/stream_management.svg b/docs/data/how-to/hip_runtime_api/stream_management.svg new file mode 100644 index 0000000000..c7a05657f1 --- /dev/null +++ b/docs/data/how-to/hip_runtime_api/stream_management.svg @@ -0,0 +1 @@ +Stream 1
Kernel A
Kernel AStream 2
Memory Copy
Memory Copy
hipDeviceSynchronize
hipDeviceSynchronize
Kernel B
Kernel B
Kernel C
Kernel C
Memory Copy
Memory Copy
Memory Copy
Memory Copy
Memory Copy
Memory CopyText is not SVG - cannot display \ No newline at end of file diff --git a/docs/how-to/hip_runtime_api.rst b/docs/how-to/hip_runtime_api.rst new file mode 100644 index 0000000000..cad6c38bdc --- /dev/null +++ b/docs/how-to/hip_runtime_api.rst @@ -0,0 +1,37 @@ +.. meta:: + :description: This chapter describes the HIP runtime API and shows + how to use it in AMD HIP. + :keywords: AMD, ROCm, HIP, CUDA, HIP runtime API How to, + +.. _hip_runtime_api_how-to: + +******************************************************************************** +HIP Runtime API +******************************************************************************** + +The HIP runtime API provides C and C++ functionality to manage GPUs, like event, +stream and memory management. On AMD platforms the HIP runtime uses the +:doc:`Common Language Runtime (CLR) `, while on NVIDIA +platforms it is only a thin layer over the CUDA runtime or Driver API. + +- **CLR** contains source code for AMD's compute language runtimes: ``HIP`` and + ``OpenCL™``. CLR includes the implementation of the ``HIP`` language on the + AMD platform `hipamd `_ and + the Radeon Open Compute Common Language Runtime (rocclr). rocclr is a virtual + device interface, that enables the HIP runtime to interact with different + backends such as ROCr on Linux or PAL on Windows. CLR also include the + implementation of `OpenCL runtime `_. +- The **CUDA runtime** is built on top of the CUDA driver API, which is a C API + with lower-level access to NVIDIA GPUs. For further information about the CUDA + driver and runtime API and its relation to HIP check the :doc:`CUDA driver API porting guide`. + On non-AMD platform, HIP runtime determines, if CUDA is available and can be + used. + +The relation between the different runtimes and their backends is presented in +the following figure. + +.. figure:: ../data/how-to/hip_runtime_api/runtimes.svg + +.. note:: + + The CUDA specific headers can be found in the `hipother repository `_. diff --git a/docs/how-to/cooperative_groups.rst b/docs/how-to/hip_runtime_api/cooperative_groups.rst similarity index 95% rename from docs/how-to/cooperative_groups.rst rename to docs/how-to/hip_runtime_api/cooperative_groups.rst index 370d6dc729..9acc5da149 100644 --- a/docs/how-to/cooperative_groups.rst +++ b/docs/how-to/hip_runtime_api/cooperative_groups.rst @@ -8,9 +8,16 @@ Cooperative groups ******************************************************************************* -Cooperative groups API is an extension to the HIP programming model, which provides developers with a flexible, dynamic grouping mechanism for the communicating threads. Cooperative groups let you define your own set of thread groups which may fit your user-cases better than those defined by the hardware. This lets you specify the level of granularity for thread communication which can lead to more efficient parallel decompositions. +Cooperative groups API is an extension to the HIP programming model, which +provides developers with a flexible, dynamic grouping mechanism for the +communicating threads. Cooperative groups let you define your own set of thread +groups which may fit your user-cases better than those defined by the hardware. +This lets you specify the level of granularity for thread communication which +can lead to more efficient parallel decompositions. -The API is accessible in the ``cooperative_groups`` namespace after the ``hip_cooperative_groups.h`` is included. The header contains the following elements: +The API is accessible in the ``cooperative_groups`` namespace after the +``hip_cooperative_groups.h`` is included. The header contains the following +elements: * Static functions to create groups and subgroups. * Hardware-accelerated operations over the whole group, like shuffles. @@ -19,13 +26,13 @@ The API is accessible in the ``cooperative_groups`` namespace after the ``hip_c * Get group properties member functions. Cooperative groups thread model -=============================== +================================================================================ The thread hierarchy abstraction of cooperative groups are in :ref:`grid hierarchy ` and :ref:`block hierarchy `. .. _coop_thread_top_hierarchy: -.. figure:: ../data/how-to/cooperative_groups/thread_hierarchy_coop_top.svg +.. figure:: ../../data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_top.svg :alt: Diagram depicting nested rectangles of varying color. The outermost one titled "Grid", inside sets of different sized rectangles layered on one another titled "Block". Each "Block" containing sets of uniform @@ -48,7 +55,7 @@ The **block** is the same as the :ref:`inherent_thread_model` block entity. .. _coop_thread_bottom_hierarchy: -.. figure:: ../data/how-to/cooperative_groups/thread_hierarchy_coop_bottom.svg +.. figure:: ../../data/how-to/hip_runtime_api/cooperative_groups/thread_hierarchy_coop_bottom.svg :alt: The new level between block thread and threads. Cooperative group thread hierarchy in blocks. diff --git a/docs/how-to/hip_runtime_api/memory_management.rst b/docs/how-to/hip_runtime_api/memory_management.rst new file mode 100644 index 0000000000..9c68c89895 --- /dev/null +++ b/docs/how-to/hip_runtime_api/memory_management.rst @@ -0,0 +1,335 @@ +.. meta:: + :description: This chapter introduces memory management and shows how to use + it in AMD HIP. + :keywords: AMD, ROCm, HIP, CUDA, memory management + +******************************************************************************** +Memory management +******************************************************************************** + +Memory management is an important part of the HIP runtime API, when creating +high-performance applications. Both allocating and copying +memory can result in bottlenecks, which can significantly impact performance. + +For traditional device memory management, HIP uses the C-style functions +:cpp:func:`hipMalloc` for allocating and :cpp:func:`hipFree` for freeing memory. +There are advanced features like managed memory, virtual memory or stream +ordered memory allocator which are described in subsections. + +Host Memory +================================================================================ + +Introduction +-------------------------------------------------------------------------------- + +``hipHostMalloc`` allocates pinned host memory which is mapped into the address +space of all GPUs in the system, the memory can be accessed directly by the GPU +device, and can be read or written with much higher bandwidth than pageable +memory obtained with functions such as ``malloc()``. +There are two use cases for this host memory: + +* Faster ``HostToDevice`` and ``DeviceToHost`` Data Transfers: The runtime + tracks the ``hipHostMalloc`` allocations and can avoid some of the setup + required for regular unpinned memory. For exact measurements on a specific + system, experiment with ``--unpinned`` and ``--pinned`` switches for the + ``hipBusBandwidth`` tool. +* Zero-Copy GPU Access: GPU can directly access the host memory over the CPU/GPU + interconnect, without need to copy the data. This avoids the need for the + copy, but during the kernel access each memory access must traverse the + interconnect, which can be tens of times slower than accessing the GPU's local + device memory. Zero-copy memory can be a good choice when the memory accesses + are infrequent (perhaps only once). Zero-copy memory is typically "Coherent" + and thus not cached by the GPU but this can be overridden if desired. + +Memory allocation flags +-------------------------------------------------------------------------------- + +There are flags parameter which can specify options how to allocate the memory, +for example, +``hipHostMallocPortable``, the memory is considered allocated by all contexts, not just the one on which the allocation is made. +``hipHostMallocMapped``, will map the allocation into the address space for the current device, and the device pointer can be obtained with the API ``hipHostGetDevicePointer()``. +``hipHostMallocNumaUser`` is the flag to allow host memory allocation to follow Numa policy by user. Please note this flag is currently only applicable on Linux, under development on Windows. + +All allocation flags are independent, and can be used in any combination without restriction, for instance, ``hipHostMalloc`` can be called with both ``hipHostMallocPortable`` and ``hipHostMallocMapped`` flags set. Both usage models described above use the same allocation flags, and the difference is in how the surrounding code uses the host memory. + +Numa-aware host memory allocation +-------------------------------------------------------------------------------- + +Numa policy determines how memory is allocated. +Target of Numa policy is to select a CPU that is closest to each GPU. +Numa distance is the measurement of how far between GPU and CPU devices. + +By default, each GPU selects a Numa CPU node that has the least Numa distance +between them, that is, host memory will be automatically allocated closest on +the memory pool of Numa node of the current GPU device. Using +:cpp:func:`hipSetDevice` API to a different GPU will still be able to access the +host allocation, but can have longer Numa distance. Note, Numa policy is so far +implemented on Linux, and under development on Windows. + +Coherency Controls +-------------------------------------------------------------------------------- + +ROCm defines two coherency options for host memory: + +* Coherent memory : Supports fine-grain synchronization while the kernel is + running. For example, a kernel can perform atomic operations that are + visible to the host CPU or to other (peer) GPUs. Synchronization instructions + include ``threadfence_system`` and C++11-style atomic operations. + +In order to achieve this fine-grained coherence, many AMD GPUs use a limited +cache policy, such as leaving these allocations uncached by the GPU, or making +them read-only. + +* Non-coherent memory : Can be cached by GPU, but cannot support synchronization + while the kernel is running. Non-coherent memory can be optionally + synchronized only at command (end-of-kernel or copy command) boundaries. This + memory is appropriate for high-performance access when fine-grain + synchronization is not required. + +HIP provides the developer with controls to select which type of memory is used +via allocation flags passed to :cpp:func:`hipHostMalloc` and the +``HIP_HOST_COHERENT`` environment variable. By default, the environment variable +``HIP_HOST_COHERENT`` is set to 0 in HIP. + +The control logic in the current version of HIP is as follows: + +* No flags are passed in: the host memory allocation is coherent, the + ``HIP_HOST_COHERENT`` environment variable is ignored. +* ``hipHostMallocCoherent=1``: The host memory allocation will be coherent, the + ``HIP_HOST_COHERENT`` environment variable is ignored. +* ``hipHostMallocMapped=1``: The host memory allocation will be coherent, the + ``HIP_HOST_COHERENT`` environment variable is ignored. +* ``hipHostMallocNonCoherent=1``, ``hipHostMallocCoherent=0``, and + ``hipHostMallocMapped=0``: The host memory will be non-coherent, the + ``HIP_HOST_COHERENT`` environment variable is ignored. +* ``hipHostMallocCoherent=0``, ``hipHostMallocNonCoherent=0``, + ``hipHostMallocMapped=0``, but one of the other ``HostMalloc`` flags is set: + + * If ``HIP_HOST_COHERENT`` is defined as 1, the host memory allocation is + coherent. + * If ``HIP_HOST_COHERENT`` is not defined, or defined as 0, the host memory + allocation is non-coherent. + +* ``hipHostMallocCoherent=1``, ``hipHostMallocNonCoherent=1``: Illegal. + +Visibility of Zero-Copy Host Memory +-------------------------------------------------------------------------------- + +Coherent host memory is automatically visible at synchronization points. +Non-coherent + +.. list-table:: HIP API + + * - HIP API + - ``hipStreamSynchronize`` + - ``hipDeviceSynchronize`` + - ``hipEventSynchronize`` + - ``hipStreamWaitEvent`` + * - Synchronization Effect + - host waits for all commands in the specified stream to complete + - host waits for all commands in all streams on the specified device to complete + - host waits for the specified event to complete + - stream waits for the specified event to complete + * - Fence + - system-scope release + - system-scope release + - system-scope release + - none + * - Coherent Host Memory Visibility + - yes + - yes + - yes + - yes + * - Non-Coherent Host Memory Visibility + - yes + - yes + - depends - see below + - no + +``hipEventSynchronize`` +-------------------------------------------------------------------------------- + +Developers can control the release scope for :cpp:func:`hipEvents`: + +* By default, the GPU performs a device-scope acquire and release operation + with each recorded event. This will make host and device memory visible to + other commands executing on the same device. + +A stronger system-level fence can be specified when the event is created with +:cpp:func:`hipEventCreateWithFlags`: + +* :cpp:func:`hipEventReleaseToSystem`: Perform a system-scope release operation when the + event is recorded. This will make both Coherent and Non-Coherent host memory + visible to other agents in the system, but may involve heavyweight operations + such as cache flushing. Coherent memory will typically use lighter-weight + in-kernel synchronization mechanisms such as an atomic operation and thus + does not need to use :cpp:func:`hipEventReleaseToSystem`. +* :cpp:func:`hipEventDisableTiming`: Events created with this flag will not record + profiling data and provide the best performance if used for synchronization. + +Summary and Recommendations +-------------------------------------------------------------------------------- + +* Coherent host memory is the default and is the easiest to use since the memory + is visible to the CPU at typical synchronization points. This memory allows + in-kernel synchronization commands such as :cpp:func:`threadfence_system` to work + transparently. +* HIP/ROCm also supports the ability to cache host memory in the GPU using the + "Non-Coherent" host memory allocations. This can provide performance benefit, + but care must be taken to use the correct synchronization. + +Managed memory allocation +-------------------------------------------------------------------------------- + +Managed memory, including the ``__managed__`` keyword, is supported in HIP +combined host/device compilation, on Linux, not on Windows (under development). + +Managed memory, via unified memory allocation, allows data be shared and +accessible to both the CPU and GPU using a single pointer. The allocation will +be managed by AMD GPU driver using the Linux HMM (Heterogeneous Memory +Management) mechanism, the user can call managed memory API ``hipMallocManaged`` +to allocate a large chunk of HMM memory, execute kernels on device and fetch +data between the host and device as needed. + +In HIP application, it is recommended to do the capability check before calling +the managed memory APIs. For example: + +.. code-block:: cpp + + int managed_memory = 0; + HIPCHECK(hipDeviceGetAttribute(&managed_memory, + hipDeviceAttributeManagedMemory,p_gpuDevice)); + + if (!managed_memory ) { + printf ("info: managed memory access not supported on the device %d\n Skipped\n", p_gpuDevice); + } + else { + HIPCHECK(hipSetDevice(p_gpuDevice)); + HIPCHECK(hipMallocManaged(&Hmm, N * sizeof(T))); + . . . + } + + +Please note, the managed memory capability check may not be necessary, but if +HMM is not supported, then managed malloc will fall back to using system memory +and other managed memory API calls will have undefined behavior. + +Note, managed memory management is implemented on Linux, not supported on +Windows yet. + +HIP Stream Memory Operations +-------------------------------------------------------------------------------- + +HIP supports Stream Memory Operations to enable direct synchronization between +Network Nodes and GPU. Following new APIs are added, + +* ``hipStreamWaitValue32`` +* ``hipStreamWaitValue64`` +* ``hipStreamWriteValue32`` +* ``hipStreamWriteValue64`` + +Note, CPU access to the semaphore's memory requires volatile keyword to disable +CPU compiler's optimizations on memory access. + +Please note, HIP stream does not guarantee concurrency on AMD hardware for the +case of multiple (at least 6) long-running streams executing concurrently, using +``hipStreamSynchronize(nullptr)`` for synchronization. + +Direct Dispatch +================================================================================ + +HIP runtime has Direct Dispatch enabled by default in ROCM 4.4 on Linux. With +this feature we move away from our conventional producer-consumer model where +the runtime creates a worker thread(consumer) for each HIP Stream, and the host +thread(producer) enqueues commands to a command queue(per stream). + +For Direct Dispatch, HIP runtime would directly enqueue a packet to the AQL +queue (user mode queue on GPU) on the Dispatch API call from the application. +That has shown to reduce the latency to launch the first wave on the idle GPU +and total time of tiny dispatches synchronized with the host. + +In addition, eliminating the threads in runtime has reduced the variance in the +dispatch numbers as the thread scheduling delays and atomics/locks +synchronization latencies are reduced. + +This feature can be disabled via setting the following environment variable, +AMD_DIRECT_DISPATCH=0 + +Note, Direct Dispatch is implemented on Linux. It is currently not supported on +Windows. + +HIP Runtime Compilation +================================================================================ + +HIP now supports runtime compilation (HIP RTC), the usage of which will provide +the possibility of optimizations and performance improvement compared with other +APIs via regular offline static compilation. + +HIP RTC APIs accept HIP source files in character string format as input +parameters and create handles of programs by compiling the HIP source files +without spawning separate processes. + +For more details on HIP RTC APIs, refer to [HIP Runtime API Reference](../doxygen/html/index). + +For Linux developers, the link [here](https://github.com/ROCm/hip-tests/blob/develop/samples/2_Cookbook/23_cmake_hiprtc/saxpy.cpp) +shows an example how to program HIP application using runtime compilation +mechanism, and a detailed [HIP RTC programming guide](./hip_rtc) is +also available. + +Device-Side Malloc +================================================================================ + +HIP-Clang now supports device-side malloc and free. +This implementation does not require the use of +``hipDeviceSetLimit(hipLimitMallocHeapSize,value)`` nor respects any setting. +The heap is fully dynamic and can grow until the available free memory on the +device is consumed. + +Use of Per-thread default stream +================================================================================ + +The per-thread default stream is supported in HIP. It is an implicit stream +local to both the thread and the current device. This means that the command +issued to the per-thread default stream by the thread does not implicitly +synchronize with other streams (like explicitly created streams), or default +per-thread stream on other threads. +The per-thread default stream is a blocking stream and will synchronize with the +default null stream if both are used in a program. +The per-thread default stream can be enabled via adding a compilation option, +``-fgpu-default-stream=per-thread``. + +And users can explicitly use ``hipStreamPerThread`` as per-thread default stream +handle as input in API commands. There are test codes as examples in the +[link](https://github.com/ROCm/hip-tests/tree/develop/catch/unit/streamperthread). + +Use of Long Double Type +================================================================================ + +In HIP-Clang, long double type is 80-bit extended precision format for x86_64, +which is not supported by AMDGPU. HIP-Clang treats long double type as IEEE +double type for AMDGPU. Using long double type in HIP source code will not cause +issue as long as data of long double type is not transferred between host and +device. However, long double type should not be used as kernel argument type. + +Use of ``_Float16`` Type +================================================================================ + +If a host function is to be used between clang (or hipcc) and gcc for x86_64, +i.e. its definition is compiled by one compiler but the caller is compiled by a +different compiler, ``_Float16`` or aggregates containing ``_Float16`` should +not be used as function argument or return type. This is due to lack of stable +ABI for ``_Float16`` on x86_64. Passing ``_Float16`` or aggregates containing +``_Float16`` between clang and gcc could cause undefined behavior. + +FMA and contractions +================================================================================ + +By default HIP-Clang assumes ``-ffp-contract=fast-honor-pragmas``. +Users can use ``#pragma clang fp contract(on|off|fast)`` to control ``fp`` +contraction of a block of code. For x86_64, FMA is off by default since the +generic x86_64 target does not support FMA by default. To turn on FMA on x86_64, +either use ``-mfma`` or ``-march=native`` on CPU's supporting FMA. + +When contractions are enabled and the CPU has not enabled FMA instructions, the +GPU can produce different numerical results than the CPU for expressions that +can be contracted. Tolerance should be used for floating point comparisons. diff --git a/docs/how-to/unified_memory.rst b/docs/how-to/hip_runtime_api/memory_management/unified_memory.rst similarity index 99% rename from docs/how-to/unified_memory.rst rename to docs/how-to/hip_runtime_api/memory_management/unified_memory.rst index f64189454c..cd0d0f7be5 100644 --- a/docs/how-to/unified_memory.rst +++ b/docs/how-to/hip_runtime_api/memory_management/unified_memory.rst @@ -17,12 +17,13 @@ and promise increased efficiency and innovation. Unified memory ============== + Unified Memory is a single memory address space accessible from any processor within a system. This setup simplifies memory management processes and enables applications to allocate data that can be read or written by code running on either CPUs or GPUs. The Unified memory model is shown in the following figure. -.. figure:: ../data/unified_memory/um.svg +.. figure:: ../../../data/how-to/hip_runtime_api/memory_management/unified_memory/um.svg AMD Accelerated Processing Unit (APU) is a typical example of a Unified Memory Architecture. On a single die, a central processing unit (CPU) is combined @@ -35,6 +36,7 @@ throughput (data processed by unit time). System requirements =================== + Unified memory is supported on Linux by all modern AMD GPUs from the Vega series onward. Unified memory management can be achieved with managed memory allocation and, for the latest GPUs, with a system allocator. @@ -108,6 +110,7 @@ system requirements` and :ref:`checking unified memory management support`. Checking unified memory management support ------------------------------------------ + Some device attributes can offer information about which :ref:`unified memory programming models` are supported. The attribute value is 1 if the functionality is supported, and 0 if it is not supported. diff --git a/docs/how-to/virtual_memory.rst b/docs/how-to/hip_runtime_api/memory_management/virtual_memory.rst similarity index 100% rename from docs/how-to/virtual_memory.rst rename to docs/how-to/hip_runtime_api/memory_management/virtual_memory.rst diff --git a/docs/how-to/programming_manual.md b/docs/how-to/programming_manual.md deleted file mode 100644 index 33ab58de93..0000000000 --- a/docs/how-to/programming_manual.md +++ /dev/null @@ -1,212 +0,0 @@ -# HIP programming manual - -## Host Memory - -### Introduction - -`hipHostMalloc` allocates pinned host memory which is mapped into the address space of all GPUs in the system, the memory can be accessed directly by the GPU device, and can be read or written with much higher bandwidth than pageable memory obtained with functions such as `malloc()`. -There are two use cases for this host memory: - -* Faster `HostToDevice` and `DeviceToHost` Data Transfers: -The runtime tracks the `hipHostMalloc` allocations and can avoid some of the setup required for regular unpinned memory. For exact measurements on a specific system, experiment with `--unpinned` and `--pinned` switches for the `hipBusBandwidth` tool. -* Zero-Copy GPU Access: -GPU can directly access the host memory over the CPU/GPU interconnect, without need to copy the data. This avoids the need for the copy, but during the kernel access each memory access must traverse the interconnect, which can be tens of times slower than accessing the GPU's local device memory. Zero-copy memory can be a good choice when the memory accesses are infrequent (perhaps only once). Zero-copy memory is typically "Coherent" and thus not cached by the GPU but this can be overridden if desired. - -### Memory allocation flags - -There are flags parameter which can specify options how to allocate the memory, for example, -`hipHostMallocPortable`, the memory is considered allocated by all contexts, not just the one on which the allocation is made. -`hipHostMallocMapped`, will map the allocation into the address space for the current device, and the device pointer can be obtained with the API `hipHostGetDevicePointer()`. -`hipHostMallocNumaUser` is the flag to allow host memory allocation to follow Numa policy by user. Please note this flag is currently only applicable on Linux, under development on Windows. - -All allocation flags are independent, and can be used in any combination without restriction, for instance, `hipHostMalloc` can be called with both `hipHostMallocPortable` and `hipHostMallocMapped` flags set. Both usage models described above use the same allocation flags, and the difference is in how the surrounding code uses the host memory. - -### Numa-aware host memory allocation - -Numa policy determines how memory is allocated. -Target of Numa policy is to select a CPU that is closest to each GPU. -Numa distance is the measurement of how far between GPU and CPU devices. - -By default, each GPU selects a Numa CPU node that has the least Numa distance between them, that is, host memory will be automatically allocated closest on the memory pool of Numa node of the current GPU device. Using `hipSetDevice` API to a different GPU will still be able to access the host allocation, but can have longer Numa distance. -Note, Numa policy is so far implemented on Linux, and under development on Windows. - -### Coherency Controls - -ROCm defines two coherency options for host memory: - -* Coherent memory : Supports fine-grain synchronization while the kernel is running. For example, a kernel can perform atomic operations that are visible to the host CPU or to other (peer) GPUs. Synchronization instructions include `threadfence_system` and C++11-style atomic operations. -In order to achieve this fine-grained coherence, many AMD GPUs use a limited cache policy, such as leaving these allocations uncached by the GPU, or making them read-only. - -* Non-coherent memory : Can be cached by GPU, but cannot support synchronization while the kernel is running. Non-coherent memory can be optionally synchronized only at command (end-of-kernel or copy command) boundaries. This memory is appropriate for high-performance access when fine-grain synchronization is not required. - -HIP provides the developer with controls to select which type of memory is used via allocation flags passed to `hipHostMalloc` and the `HIP_HOST_COHERENT` environment variable. By default, the environment variable HIP_HOST_COHERENT is set to 0 in HIP. -The control logic in the current version of HIP is as follows: - -* No flags are passed in: the host memory allocation is coherent, the HIP_HOST_COHERENT environment variable is ignored. -* `hipHostMallocCoherent=1`: The host memory allocation will be coherent, the HIP_HOST_COHERENT environment variable is ignored. -* `hipHostMallocMapped=1`: The host memory allocation will be coherent, the HIP_HOST_COHERENT environment variable is ignored. -* `hipHostMallocNonCoherent=1`, `hipHostMallocCoherent=0`, and `hipHostMallocMapped=0`: The host memory will be non-coherent, the HIP_HOST_COHERENT environment variable is ignored. -* `hipHostMallocCoherent=0`, `hipHostMallocNonCoherent=0`, `hipHostMallocMapped=0`, but one of the other `HostMalloc` flags is set: - * If `HIP_HOST_COHERENT` is defined as 1, the host memory allocation is coherent. - * If `HIP_HOST_COHERENT` is not defined, or defined as 0, the host memory allocation is non-coherent. -* `hipHostMallocCoherent=1`, `hipHostMallocNonCoherent=1`: Illegal. - -### Visibility of Zero-Copy Host Memory - -Coherent host memory is automatically visible at synchronization points. -Non-coherent - -| HIP API | Synchronization Effect | Fence | Coherent Host Memory Visibility | Non-Coherent Host Memory Visibility| -| --- | --- | --- | --- | --- | -| `hipStreamSynchronize` | host waits for all commands in the specified stream to complete | system-scope release | yes | yes | -| `hipDeviceSynchronize` | host waits for all commands in all streams on the specified device to complete | system-scope release | yes | yes | -| `hipEventSynchronize` | host waits for the specified event to complete | device-scope release | yes | depends - see below| -| `hipStreamWaitEvent` | stream waits for the specified event to complete | none | yes | no | - -### `hipEventSynchronize` - -Developers can control the release scope for `hipEvents`: - -* By default, the GPU performs a device-scope acquire and release operation with each recorded event. This will make host and device memory visible to other commands executing on the same device. - -A stronger system-level fence can be specified when the event is created with `hipEventCreateWithFlags`: - -* `hipEventReleaseToSystem`: Perform a system-scope release operation when the event is recorded. This will make both Coherent and Non-Coherent host memory visible to other agents in the system, but may involve heavyweight operations such as cache flushing. Coherent memory will typically use lighter-weight in-kernel synchronization mechanisms such as an atomic operation and thus does not need to use `hipEventReleaseToSystem`. -* `hipEventDisableTiming`: Events created with this flag will not record profiling data and provide the best performance if used for synchronization. - -### Summary and Recommendations - -* Coherent host memory is the default and is the easiest to use since the memory is visible to the CPU at typical synchronization points. This memory allows in-kernel synchronization commands such as `threadfence_system` to work transparently. -* HIP/ROCm also supports the ability to cache host memory in the GPU using the "Non-Coherent" host memory allocations. This can provide performance benefit, but care must be taken to use the correct synchronization. - -### Managed memory allocation - -Managed memory, including the `__managed__` keyword, is supported in HIP combined host/device compilation, on Linux, not on Windows (under development). - -Managed memory, via unified memory allocation, allows data be shared and accessible to both the CPU and GPU using a single pointer. -The allocation will be managed by AMD GPU driver using the Linux HMM (Heterogeneous Memory Management) mechanism, the user can call managed memory API `hipMallocManaged` to allocate a large chunk of HMM memory, execute kernels on device and fetch data between the host and device as needed. - -In HIP application, it is recommended to do the capability check before calling the managed memory APIs. For example: - -```cpp -int managed_memory = 0; -HIPCHECK(hipDeviceGetAttribute(&managed_memory, - hipDeviceAttributeManagedMemory,p_gpuDevice)); - -if (!managed_memory ) { - printf ("info: managed memory access not supported on the device %d\n Skipped\n", p_gpuDevice); -} -else { - HIPCHECK(hipSetDevice(p_gpuDevice)); - HIPCHECK(hipMallocManaged(&Hmm, N * sizeof(T))); -. . . -} -``` - -Please note, the managed memory capability check may not be necessary, but if HMM is not supported, then managed malloc will fall back to using system memory and other managed memory API calls will have undefined behavior. - -Note, managed memory management is implemented on Linux, not supported on Windows yet. - -### HIP Stream Memory Operations - -HIP supports Stream Memory Operations to enable direct synchronization between Network Nodes and GPU. Following new APIs are added, - `hipStreamWaitValue32` - `hipStreamWaitValue64` - `hipStreamWriteValue32` - `hipStreamWriteValue64` - -Note, CPU access to the semaphore's memory requires volatile keyword to disable CPU compiler's optimizations on memory access. -For more details, please check the documentation `HIP-API.pdf`. - -Please note, HIP stream does not guarantee concurrency on AMD hardware for the case of multiple (at least 6) long-running streams executing concurrently, using `hipStreamSynchronize(nullptr)` for synchronization. - -## Direct Dispatch - -HIP runtime has Direct Dispatch enabled by default in ROCM 4.4 on Linux. -With this feature we move away from our conventional producer-consumer model where the runtime creates a worker thread(consumer) for each HIP Stream, and the host thread(producer) enqueues commands to a command queue(per stream). - -For Direct Dispatch, HIP runtime would directly enqueue a packet to the AQL queue (user mode queue on GPU) on the Dispatch API call from the application. That has shown to reduce the latency to launch the first wave on the idle GPU and total time of tiny dispatches synchronized with the host. - -In addition, eliminating the threads in runtime has reduced the variance in the dispatch numbers as the thread scheduling delays and atomics/locks synchronization latencies are reduced. - -This feature can be disabled via setting the following environment variable, -AMD_DIRECT_DISPATCH=0 - -Note, Direct Dispatch is implemented on Linux. It is currently not supported on Windows. - -## HIP Runtime Compilation - -HIP now supports runtime compilation (HIP RTC), the usage of which will provide the possibility of optimizations and performance improvement compared with other APIs via regular offline static compilation. - -HIP RTC APIs accept HIP source files in character string format as input parameters and create handles of programs by compiling the HIP source files without spawning separate processes. - -For more details on HIP RTC APIs, refer to [HIP Runtime API Reference](../doxygen/html/index). - -For Linux developers, the link [here](https://github.com/ROCm/hip-tests/blob/develop/samples/2_Cookbook/23_cmake_hiprtc/saxpy.cpp) shows an example how to program HIP application using runtime compilation mechanism, and a detailed [HIP RTC programming guide](./hip_rtc) is also available. - -## HIP Graph - -HIP graph is supported. For more details, refer to the HIP API Guide. - -## Device-Side Malloc - -HIP-Clang now supports device-side malloc and free. -This implementation does not require the use of `hipDeviceSetLimit(hipLimitMallocHeapSize,value)` nor respects any setting. The heap is fully dynamic and can grow until the available free memory on the device is consumed. - -## Use of Per-thread default stream - -The per-thread default stream is supported in HIP. It is an implicit stream local to both the thread and the current device. This means that the command issued to the per-thread default stream by the thread does not implicitly synchronize with other streams (like explicitly created streams), or default per-thread stream on other threads. -The per-thread default stream is a blocking stream and will synchronize with the default null stream if both are used in a program. -The per-thread default stream can be enabled via adding a compilation option, -`-fgpu-default-stream=per-thread`. - -And users can explicitly use `hipStreamPerThread` as per-thread default stream handle as input in API commands. There are test codes as examples in the [link](https://github.com/ROCm/hip-tests/tree/develop/catch/unit/streamperthread). - -## Use of Long Double Type - -In HIP-Clang, long double type is 80-bit extended precision format for x86_64, which is not supported by AMDGPU. HIP-Clang treats long double type as IEEE double type for AMDGPU. Using long double type in HIP source code will not cause issue as long as data of long double type is not transferred between host and device. However, long double type should not be used as kernel argument type. - -## Use of `_Float16` Type - -If a host function is to be used between clang (or hipcc) and gcc for x86_64, i.e. its definition is compiled by one compiler but the caller is compiled by a different compiler, `_Float16` or aggregates containing `_Float16` should not be used as function argument or return type. This is due to lack of stable ABI for `_Float16` on x86_64. Passing `_Float16` or aggregates containing `_Float16` between clang and gcc could cause undefined behavior. - -## FMA and contractions - -By default HIP-Clang assumes `-ffp-contract=fast-honor-pragmas`. -Users can use `#pragma clang fp contract(on|off|fast)` to control `fp` contraction of a block of code. -For x86_64, FMA is off by default since the generic x86_64 target does not -support FMA by default. To turn on FMA on x86_64, either use `-mfma` or `-march=native` -on CPU's supporting FMA. - -When contractions are enabled and the CPU has not enabled FMA instructions, the -GPU can produce different numerical results than the CPU for expressions that -can be contracted. Tolerance should be used for floating point comparisons. - -## Math functions with special rounding modes - -Note: Currently, HIP only supports basic math functions with rounding modern (round to nearest). HIP does not support basic math functions with rounding modes `ru` (round up), `rd` (round down), and `rz` (round towards zero). - -## Creating Static Libraries - -HIP-Clang supports generating two types of static libraries. The first type of static library does not export device functions, and only exports and launches host functions within the same library. The advantage of this type is the ability to link with a non-hipcc compiler such as gcc. The second type exports device functions to be linked by other code objects. However, this requires using hipcc as the linker. - -In addition, the first type of library contains host objects with device code embedded as fat binaries. It is generated using the flag --emit-static-lib. The second type of library contains relocatable device objects and is generated using `ar`. - -Here is an example to create and use static libraries: - -* Type 1 using `--emit-static-lib`: - - ```cpp - hipcc hipOptLibrary.cpp --emit-static-lib -fPIC -o libHipOptLibrary.a - gcc test.cpp -L. -lhipOptLibrary -L/path/to/hip/lib -lamdhip64 -o test.out - ``` - -* Type 2 using system `ar`: - - ```cpp - hipcc hipDevice.cpp -c -fgpu-rdc -o hipDevice.o - ar rcsD libHipDevice.a hipDevice.o - hipcc libHipDevice.a test.cpp -fgpu-rdc -o test.out - ``` - -For more information, please see [HIP samples host functions](https://github.com/ROCm/hip-tests/tree/develop/samples/2_Cookbook/15_static_library/host_functions) and [device_functions](https://github.com/ROCm/hip-tests/tree/rocm-5.5.x/samples/2_Cookbook/15_static_library/device_functions). diff --git a/docs/index.md b/docs/index.md index c0348d39d9..16208a7d84 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,22 +32,22 @@ On non-AMD platforms, like NVIDIA, HIP provides header files required to support * {doc}`./understand/programming_model` * {doc}`./understand/hardware_implementation` * {doc}`./understand/amd_clr` +* {doc}`./understand/compilers` * {doc}`./understand/texture_fetching` ::: :::{grid-item-card} How to -* [Programming manual](./how-to/programming_manual) +* {doc}`./how-to/hip_runtime_api` + * {doc}`./how-to/hip_runtime_api/memory_management` + * {doc}`./how-to/hip_runtime_api/cooperative_groups` * [HIP porting guide](./how-to/hip_porting_guide) * [HIP porting: driver API guide](./how-to/hip_porting_driver_api) * {doc}`./how-to/hip_rtc` * {doc}`./how-to/performance_guidelines` * [Debugging with HIP](./how-to/debugging) * {doc}`./how-to/logging` -* [Unified memory](./how-to/unified_memory) -* [Virtual memory](./how-to/virtual_memory) -* [Cooperative groups](./how-to/cooperative_groups) * {doc}`./how-to/faq` ::: diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 813a89cdfa..4ed3e3ba29 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -18,23 +18,27 @@ subtrees: - file: understand/programming_model - file: understand/hardware_implementation - file: understand/amd_clr + - file: understand/compilers - file: understand/texture_fetching title: Texture fetching - caption: How to entries: - - file: how-to/programming_manual + - file: how-to/hip_runtime_api + subtrees: + - entries: + - file: how-to/hip_runtime_api/memory_management + subtrees: + - entries: + - file: how-to/hip_runtime_api/memory_management/unified_memory + - file: how-to/hip_runtime_api/memory_management/virtual_memory + - file: how-to/hip_runtime_api/cooperative_groups - file: how-to/hip_porting_guide - file: how-to/hip_porting_driver_api - file: how-to/hip_rtc - file: how-to/performance_guidelines - file: how-to/debugging - file: how-to/logging - - file: how-to/cooperative_groups - - file: how-to/unified_memory - title: Unified memory - - file: how-to/virtual_memory - title: Virtual memory - file: how-to/faq - caption: Reference diff --git a/docs/tutorial/saxpy.rst b/docs/tutorial/saxpy.rst index 91ecc10be7..c3dc766102 100644 --- a/docs/tutorial/saxpy.rst +++ b/docs/tutorial/saxpy.rst @@ -143,10 +143,12 @@ Retrieval of the result from the device is done much like input data copy. In th HIP_CHECK(hipMemcpy(y.data(), d_y, size_bytes, hipMemcpyDeviceToHost)); +.. _compiling_on_the_command_line: + Compiling on the command line ============================= -.. _setting_up_the_command-line: +.. _setting_up_the_command_line: Setting up the command line --------------------------- diff --git a/docs/understand/compilers.rst b/docs/understand/compilers.rst new file mode 100644 index 0000000000..34fd2a4bfa --- /dev/null +++ b/docs/understand/compilers.rst @@ -0,0 +1,95 @@ +.. meta:: + :description: This chapter describes the compilation workflow of the HIP + compilers. + :keywords: AMD, ROCm, HIP, CUDA, HIP runtime API + +.. _hip_compilers: + +******************************************************************************** +HIP compilers +******************************************************************************** + +The HIP programming interface refers to the HIP compilers and HIP runtime API, +that enable developers to write programs that execute on AMD or NVIDIA GPUs. + +This document introduces and describes the advantages of the different +compilation workflows and different HIP runtime API modules. + +HIP compilers +================================================================================ + +ROCm provides the compiler driver ``hipcc``, that can be used on AMD and NVIDIA +platforms. ``hipcc`` takes care of setting the default library and include paths +for HIP, as well as some environment variables, and takes care of invoking the +appropriate compiler - ``amdclang++`` on AMD platforms and ``nvcc`` on NVIDIA +platforms. ``amdclang++`` is based on the ``clang++`` compiler. For further +details, check :doc:`the llvm project`. + +HIP compilation workflow +================================================================================ + +Offline compilation +-------------------------------------------------------------------------------- + +The compilation of HIP code is separated into a host- and a device-code +compilation stage. + +The compiled device code is embedded into the host object file. Depending on the +platform, the device code can be compiled into assembly or binary. ``nvcc`` and +``amdclang++`` target different architectures and use different code object +formats: ``nvcc`` uses the binary ``cubin`` or the assembly ``PTX`` files, while +the ``amdclang++`` path is the binary ``hsaco`` format. On NVIDIA platforms the +driver takes care of compiling the PTX files to executable code during runtime. + +On the host side ``nvcc`` only replaces the ``<<<...>>>`` kernel launch syntax +with the appropriate CUDA runtime function call and the modified host code is +passed to the default host compiler. ``hipcc`` or ``amdclang++`` can compile the +host code in one step without other C++ compilers. + +An example for how to compile HIP from the command line can be found in the +:ref:`SAXPY tutorial` . + +Runtime compilation +-------------------------------------------------------------------------------- + +HIP lets you compile kernels at runtime with the ``hiprtc*`` API. Kernels are +stored as a text string that are then passed to HIPRTC alongside options to +guide the compilation. + +For further details, check the +:doc:`how-to section for the HIP runtime compilation<../how-to/hip_rtc>`. + +Static Libraries +================================================================================ + +``hipcc`` supports generating two types of static libraries. The first type of +static library does not export device functions, and only exports and launches +host functions within the same library. The advantage of this type is the +ability to link with a non-hipcc compiler such as gcc. The second type exports +device functions to be linked by other code objects. However, this requires +using ``hipcc`` as the linker. + +In addition, the first type of library contains host objects with device code +embedded as fat binaries. It is generated using the flag ``--emit-static-lib``. +The second type of library contains relocatable device objects and is generated +using ``ar``. + +Here is an example to create and use static libraries: + +* Type 1 using `--emit-static-lib`: + + .. code-block:: cpp + + hipcc hipOptLibrary.cpp --emit-static-lib -fPIC -o libHipOptLibrary.a + gcc test.cpp -L. -lhipOptLibrary -L/path/to/hip/lib -lamdhip64 -o test.out + +* Type 2 using system `ar`: + + .. code-block:: cpp + + hipcc hipDevice.cpp -c -fgpu-rdc -o hipDevice.o + ar rcsD libHipDevice.a hipDevice.o + hipcc libHipDevice.a test.cpp -fgpu-rdc -o test.out + +For more information, please see `HIP samples host functions `_ +and `device_functions `_. diff --git a/docs/understand/programming_model.rst b/docs/understand/programming_model.rst index 410448434d..fd3c920378 100644 --- a/docs/understand/programming_model.rst +++ b/docs/understand/programming_model.rst @@ -225,7 +225,7 @@ better than the defaults defined by the hardware. The implicit groups defined by kernel launch parameters are still available when working with cooperative groups. -For further information, see :doc:`Cooperative groups `. +For further information, see :doc:`Cooperative groups <./how-to/hip_runtime_api/cooperative_groups>`. Memory model ============