From 973ca35f934622e640ce42aeca3a27bcff8831c2 Mon Sep 17 00:00:00 2001 From: Istvan Kiss Date: Thu, 24 Oct 2024 14:55:01 +0200 Subject: [PATCH] Add what is HIP --- .wordlist.txt | 6 ++ docs/data/what_is_hip/hip.drawio | 157 +++++++++++++++++++++++++++++++ docs/data/what_is_hip/hip.svg | 2 + docs/index.md | 29 ++---- docs/sphinx/_toc.yml.in | 8 ++ docs/what_is_hip.rst | 97 +++++++++++++++++++ 6 files changed, 280 insertions(+), 19 deletions(-) create mode 100644 docs/data/what_is_hip/hip.drawio create mode 100644 docs/data/what_is_hip/hip.svg create mode 100644 docs/what_is_hip.rst diff --git a/.wordlist.txt b/.wordlist.txt index 2033214571..8d3c4d5129 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -58,6 +58,7 @@ hipcc hipCtx hipexamine hipified +HIPify hipModule hipModuleLaunchKernel hipother @@ -65,6 +66,7 @@ HIPRTC icc IILE iGPU +inlined inplace Interoperation interoperate @@ -87,6 +89,7 @@ ltrace makefile Malloc malloc +MALU memset multicore multigrid @@ -101,6 +104,7 @@ NOP Numa Nsight ocp +omnitrace overindex overindexing oversubscription @@ -111,6 +115,7 @@ preconditioners predefining prefetched preprocessor +profilers PTX PyHIP queryable @@ -118,6 +123,7 @@ prefetching quad representable RMW +rocgdb ROCm's rocTX roundtrip diff --git a/docs/data/what_is_hip/hip.drawio b/docs/data/what_is_hip/hip.drawio new file mode 100644 index 0000000000..1a47e4b097 --- /dev/null +++ b/docs/data/what_is_hip/hip.drawio @@ -0,0 +1,157 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/data/what_is_hip/hip.svg b/docs/data/what_is_hip/hip.svg new file mode 100644 index 0000000000..c151dc8717 --- /dev/null +++ b/docs/data/what_is_hip/hip.svg @@ -0,0 +1,2 @@ +
NVIDIA runtime
NVIDIA runtime
NVIDIA Platform
NVIDIA Platform
HIP
HIP
AMD runtime
AMD runtime
AMD Platform
AMD Platform +
hipLibrary
hipLibrary
rocLibrary
rocLibrary
cuLibrary
cuLibrary
Application Implementation
Application Implementation
Application
Application
runtime API
runtime API
kernel language
kernel languageText is not SVG - cannot display \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 54fa9cc411..28d7d4f287 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,32 +1,23 @@ # HIP documentation -The Heterogeneous-computing Interface for Portability (HIP) API is a C++ runtime -API and kernel language that lets developers create portable applications for AMD -and NVIDIA GPUs from single source code. +The Heterogeneous-computing Interface for Portability (HIP) is a C++ runtime API and kernel language that lets you create portable applications for AMD and NVIDIA GPUs from a single source code. For more information, see [What is HIP?](./what_is_hip) -For HIP supported AMD GPUs on multiple operating systems, see: +Installation instructions are available from: -* [Linux system requirements](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-gpus) -* [Microsoft Windows system requirements](https://rocm.docs.amd.com/projects/install-on-windows/en/latest/reference/system-requirements.html#windows-supported-gpus) - -The CUDA enabled NVIDIA GPUs are supported by HIP. For more information, see [GPU Compute Capability](https://developer.nvidia.com/cuda-gpus). +* [Installing HIP](./install/install) +* [Building HIP from source](./install/build) -On the AMD ROCm platform, HIP provides header files and runtime library built on top of HIP-Clang compiler in the repository [Common Language Runtimes (CLR)](./understand/amd_clr), which contains source codes for AMD's compute languages runtimes as follows, +HIP enabled GPUs: -On non-AMD platforms, like NVIDIA, HIP provides header files required to support non-AMD specific back-end implementation in the repository ['hipother'](https://github.com/ROCm/hipother), which translates from the HIP runtime APIs to CUDA runtime APIs. +* [Supported AMD GPUs on Linux](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-gpus) +* [Supported AMD GPUs on Windows](https://rocm.docs.amd.com/projects/install-on-windows/en/latest/reference/system-requirements.html#windows-supported-gpus) +* [Supported NVIDIA GPUs](https://developer.nvidia.com/cuda-gpus) -## Overview +The HIP documentation is organized into the following categories: -::::{grid} 1 1 2 2 +::::{grid} 1 2 2 2 :gutter: 3 -:::{grid-item-card} Install - -* [Installing HIP](./install/install) -* [Building HIP from source](./install/build) - -::: - :::{grid-item-card} Conceptual * {doc}`./understand/programming_model` diff --git a/docs/sphinx/_toc.yml.in b/docs/sphinx/_toc.yml.in index 56abaee03f..251faba0fa 100644 --- a/docs/sphinx/_toc.yml.in +++ b/docs/sphinx/_toc.yml.in @@ -5,6 +5,8 @@ defaults: maxdepth: 6 root: index subtrees: +- entries: + - file: what_is_hip - caption: Install entries: @@ -12,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 new file mode 100644 index 0000000000..98f7e767f0 --- /dev/null +++ b/docs/what_is_hip.rst @@ -0,0 +1,97 @@ +.. meta:: + :description: This chapter provides an introduction to the HIP API. + :keywords: AMD, ROCm, HIP, CUDA, C++ language extensions + +.. _intro-to-hip: + +******************************************************************************* +What is HIP? +******************************************************************************* + +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 ROCm) to tune for + performance or handle tricky cases. + +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 for AMD GPUs to port existing projects as +described :doc:`HIP porting guide `. + +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 `. + +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 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 :ref:`HIP Runtime API Reference `. + +Kernel language +----------------------------------------------- + +HIP provides a C++ syntax that is suitable for compiling most code that commonly appears in +compute kernels (classes, namespaces, operator overloading, and templates). HIP also defines other +language features that are designed to target accelerators, such as: + +* Short-vector headers that can serve on a host or device +* 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 `.