From d25b6d16bc2f4445e9be2db59ff3fbaa7516b951 Mon Sep 17 00:00:00 2001 From: Matthias Knorr Date: Fri, 16 Aug 2024 11:43:19 +0200 Subject: [PATCH] Update what_is_hip and table of contents --- docs/sphinx/_toc.yml.in | 6 +++ docs/what_is_hip.rst | 83 +++++++++++++++++++++++++++++------------ 2 files changed, 66 insertions(+), 23 deletions(-) diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index c5c2127acf..a1edafe763 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -14,6 +14,12 @@ subtrees: title: Installing HIP - file: install/build title: Building HIP from source + - url: https://rocm.docs.amd.com/projects/install-on-linux/en/${branch}/reference/system-requirements.html#supported-gpus + title: Linux supported AMD GPUs + - url: https://rocm.docs.amd.com/projects/install-on-windows/en/${branch}/reference/system-requirements.html#windows-supported-gpus + title: Windows supported AMD GPUs + - url: https://developer.nvidia.com/cuda-gpus + title: NVIDIA supported GPUs - caption: Conceptual entries: diff --git a/docs/what_is_hip.rst b/docs/what_is_hip.rst index 37a94e6af3..841689d4eb 100644 --- a/docs/what_is_hip.rst +++ b/docs/what_is_hip.rst @@ -8,41 +8,78 @@ What is HIP? ******************************************************************************* -The Heterogeneous-computing Interface for Portability (HIP) API is a C++ runtime -API and kernel language (C++ language extension) that lets developers create -portable applications running in heterogeneous systems, using CPUs and AMD GPUs -or NVIDIA GPUs from a single source code. HIP provides a simple marshalling -language to access either the AMD ROCM back-end, or NVIDIA CUDA back-end, to -build and run application kernels. +The Heterogeneous-computing Interface for Portability (HIP) API is a C++ runtime API +and kernel language that lets developers create portable applications running in heterogeneous systems, +using CPUs and AMD GPUs or NVIDIA GPUs from a single source code. HIP provides a simple +marshalling language to access either the AMD ROCM back-end, or NVIDIA CUDA back-end, +to build and run application kernels. .. figure:: data/what_is_hip/hip.svg :alt: HIP in an application. :align: center -* HIP is a thin API with little or no performance impact over coding directly in NVIDIA CUDA or AMD :doc:`ROCm `. -* HIP enables coding in a single-source C++ programming language including features such as templates, C++11 lambdas, classes, namespaces, and more. -* Developers can specialize for the platform (CUDA or AMD) to tune for performance or handle tricky cases. - -:doc:`ROCm ` offers compilers (``clang``, ``hipcc``), code profilers (``rocprof``, ``omnitrace``), debugging tools (``rocgdb``), libraries and HIP with the runtime API and kernel language extension, to create heterogeneous applications running on both CPUs and GPUs. ROCm provides marshalling libraries like :doc:`hipFFT ` or :doc:`hipBLAS ` that act as a thin programming layer over either NVIDIA CUDA or AMD ROCm to enable support for either back-end. These libraries offer pointer-based memory interfaces and are easily integrated into your applications. - -HIP supports the ability to build and run on either AMD GPUs or NVIDIA GPUs. GPU Programmers familiar with NVIDIA CUDA or OpenCL will find the HIP API familiar and easy to use. Developers no longer need to choose between AMD or NVIDIA GPUs. You can quickly port your application to run on the available hardware while maintaining a single codebase. The :doc:`HIPify ` tools, based on the clang front-end and Perl language, can convert CUDA API calls into the corresponding HIP API calls. However, HIP is not intended to be a drop-in replacement for CUDA, and developers should expect to do some manual coding and performance tuning work to port existing projects as described in :doc:`HIP porting guide `. - -HIP is designed to work seamlessly with the ROCm Runtime (:doc:`ROCr `). HIP provides two components: those that run on the CPU, also known as host system, and those that run on GPUs, or accelerators. The host-based code is used to create device buffers, move data between the host application and a device, launch the device code (also known as kernel), manage streams and events, and perform synchronization. The device or kernel code, running on GPUs, provides significantly increased performance over CPUs for certain types of functions as described in :doc:`Programming model `. - -In summary, HIP simplifies cross-platform development, maintains performance, and provides a familiar C++ experience for GPU programming that runs seamlessly on both AMD and NVIDIA GPUs. +* HIP is a thin API with little or no performance impact over coding directly + in NVIDIA CUDA or AMD :doc:`ROCm `. +* HIP enables coding in a single-source C++ programming language including + features such as templates, C++11 lambdas, classes, namespaces, and more. +* Developers can specialize for the platform (CUDA or ROCm) to tune for + performance or handle tricky cases. + +:doc:`ROCm ` offers compilers (``clang``, ``hipcc``), code +profilers (``rocprof``, ``omnitrace``), debugging tools (``rocgdb``), libraries +and HIP with the runtime API and kernel language, to create heterogeneous applications +running on both CPUs and GPUs. ROCm provides marshalling libraries like +:doc:`hipFFT ` or :doc:`hipBLAS ` that act as a +thin programming layer over either NVIDIA CUDA or AMD ROCm to enable support for +either back-end. These libraries offer pointer-based memory interfaces and are +easily integrated into your applications. + +HIP supports the ability to build and run on either AMD GPUs or NVIDIA GPUs. +GPU Programmers familiar with NVIDIA CUDA or OpenCL will find the HIP API +familiar and easy to use. Developers no longer need to choose between AMD or NVIDIA GPUs. +You can quickly port your application to run on the available hardware while +maintaining a single codebase. The :doc:`HIPify ` tools, based +on the clang front-end and Perl language, can convert CUDA API calls into the +corresponding HIP API calls. However, HIP is not intended to be a drop-in replacement +for CUDA, and developers should expect to do some manual coding and +performance tuning work to port existing projects as described +:doc:`HIP porting guide `. + +HIP is designed to work seamlessly with the ROCm Runtime +(:doc:`ROCr `). HIP provides two components: those that run +on the CPU, also known as host system, and those that run on GPUs, also referred +to as device. The host-based code is used to create device buffers, move data +between the host application and a device, launch the device code (also known +as kernel), manage streams and events, and perform synchronization. +The kernel language provides a way to develop massively parallel programs that +run on GPUs, and provides access to GPU specific hardware capabilities. + +In summary, HIP simplifies cross-platform development, maintains performance, +and provides a familiar C++ experience for GPU programming that runs seamlessly +on both AMD and NVIDIA GPUs. HIP components =============================================== -HIP consists of the following components. For information on the license associated with each component, -see :doc:`HIP licensing `. +HIP consists of the following components. For information on the license +associated with each component, see :doc:`HIP licensing `. C++ runtime API ----------------------------------------------- -For the AMD ROCm platform, HIP provides headers and a runtime library built on top of HIP-Clang compiler in the repository :doc:`Common Language Runtime (CLR) `. The HIP runtime implements HIP streams, events, and memory APIs, and is an object library that is linked with the application. The source code for all headers and the library implementation is available on GitHub. +For the AMD ROCm platform, HIP provides headers and a runtime library built on +top of HIP-Clang compiler in the repository +:doc:`Common Language Runtime (CLR) `. The HIP runtime +implements HIP streams, events, and memory APIs, and is an object library that +is linked with the application. The source code for all headers and the library +implementation is available on GitHub. -For the NVIDIA CUDA platform, HIP provides header files in the repository `hipother `_ which translate from the HIP runtime APIs to CUDA runtime APIs. The header files contain mostly inlined functions and thus have very low overhead. Developers coding in HIP should expect the same performance as coding in native CUDA. The code is then compiled with ``nvcc``, the standard C++ compiler provided with the CUDA SDK. +For the NVIDIA CUDA platform, HIP provides headers that translate from the +HIP runtime API to the CUDA runtime API. The host-side contains mostly inlined +wrappers or even just preprocessor defines, with no additional overhead. +The device-side code is compiled with ``nvcc``, just like normal CUDA kernels, +and therefore one can expect the same performance as if directly coding in CUDA. +The CUDA specific headers can be found in the `hipother repository `_. For further details, check `HIP Runtime API Reference `_. @@ -57,5 +94,5 @@ language features that are designed to target accelerators, such as: * Math functions that resemble those in ``math.h``, which is included with standard C++ compilers * Built-in functions for accessing specific GPU hardware capabilities -For further details, check :doc:`C++ language extensions ` and :doc:`C++ language support `. - +For further details, check :doc:`C++ language extensions ` +and :doc:`C++ language support `.