[clang] 795e934 - [HIP] Start document HIP support by clang
Yaxun Liu via cfe-commits
cfe-commits at lists.llvm.org
Tue Jul 25 06:41:24 PDT 2023
Author: Yaxun (Sam) Liu
Date: 2023-07-25T09:36:58-04:00
New Revision: 795e934e15b7f74fc5f5dd88e3aac36c8cac4765
URL: https://github.com/llvm/llvm-project/commit/795e934e15b7f74fc5f5dd88e3aac36c8cac4765
DIFF: https://github.com/llvm/llvm-project/commit/795e934e15b7f74fc5f5dd88e3aac36c8cac4765.diff
LOG: [HIP] Start document HIP support by clang
start with example usage, predefined macros, and path setting.
Reviewed by: Brian Sumner, Siu Chi Chan, Matt Arsenault, Ronan Keryell
Differential Revision: https://reviews.llvm.org/D154123
Added:
clang/docs/HIPSupport.rst
Modified:
Removed:
################################################################################
diff --git a/clang/docs/HIPSupport.rst b/clang/docs/HIPSupport.rst
new file mode 100644
index 00000000000000..4057e1f691593b
--- /dev/null
+++ b/clang/docs/HIPSupport.rst
@@ -0,0 +1,175 @@
+.. raw:: html
+
+ <style type="text/css">
+ .none { background-color: #FFCCCC }
+ .part { background-color: #FFFF99 }
+ .good { background-color: #CCFF99 }
+ </style>
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+ :local:
+
+=============
+HIP Support
+=============
+
+HIP (Heterogeneous-Compute Interface for Portability) `<https://github.com/ROCm-Developer-Tools/HIP>`_ is
+a C++ Runtime API and Kernel Language. It enables developers to create portable applications for
+offloading computation to
diff erent hardware platforms from a single source code.
+
+AMD GPU Support
+===============
+
+Clang provides HIP support on AMD GPUs via the ROCm platform `<https://rocm.docs.amd.com/en/latest/#>`_.
+The ROCm runtime forms the base for HIP host APIs, while HIP device APIs are realized through HIP header
+files and the ROCm device library. The Clang driver uses the HIPAMD toolchain to compile HIP device code
+to AMDGPU ISA via the AMDGPU backend. The compiled code is then bundled and embedded in the host executables.
+
+Intel GPU Support
+=================
+
+Clang provides partial HIP support on Intel GPUs using the CHIP-Star project `<https://github.com/CHIP-SPV/chipStar>`_.
+CHIP-Star implements the HIP runtime over oneAPI Level Zero or OpenCL runtime. The Clang driver uses the HIPSPV
+toolchain to compile HIP device code into LLVM IR, which is subsequently translated to SPIR-V via the SPIR-V
+backend or the out-of-tree LLVM-SPIRV translator. The SPIR-V is then bundled and embedded into the host executables.
+
+.. note::
+ While Clang does not directly provide HIP support for NVIDIA GPUs and CPUs, these platforms are supported via other means:
+
+ - NVIDIA GPUs: HIP support is offered through the HIP project `<https://github.com/ROCm-Developer-Tools/HIP>`_, which provides a header-only library for translating HIP runtime APIs into CUDA runtime APIs. The code is subsequently compiled using NVIDIA's `nvcc`.
+
+ - CPUs: HIP support is available through the HIP-CPU runtime library `<https://github.com/ROCm-Developer-Tools/HIP-CPU>`_. This header-only library enables CPUs to execute unmodified HIP code.
+
+
+Example Usage
+=============
+
+To compile a HIP program, use the following command:
+
+.. code-block:: shell
+
+ clang++ -c --offload-arch=gfx906 -xhip sample.cpp -o sample.o
+
+The ``-xhip`` option indicates that the source is a HIP program. If the file has a ``.hip`` extension,
+Clang will automatically recognize it as a HIP program:
+
+.. code-block:: shell
+
+ clang++ -c --offload-arch=gfx906 sample.hip -o sample.o
+
+To link a HIP program, use this command:
+
+.. code-block:: shell
+
+ clang++ --hip-link --offload-arch=gfx906 sample.o -o sample
+
+For convenience, Clang also supports compiling and linking in a single step:
+
+.. code-block:: shell
+
+ clang++ --hip-link --offload-arch=gfx906 -xhip sample.cpp -o sample
+
+In the above commands, ``gfx906`` is the GPU architecture that the code is being compiled for. The supported GPU
+architectures can be found in the `AMDGPU Processor Table <https://llvm.org/docs/AMDGPUUsage.html#processors>`_.
+Alternatively, you can use the ``amdgpu-arch`` tool that comes with Clang to list the GPU architecture on your system:
+
+.. code-block:: shell
+
+ amdgpu-arch
+
+You can use ``--offload-arch=native`` to automatically detect the GPU architectures on your system:
+
+.. code-block:: shell
+
+ clang++ --hip-link --offload-arch=native -xhip sample.cpp -o sample
+
+
+Path Setting for Dependencies
+=============================
+
+Compiling a HIP program depends on the HIP runtime and device library. The paths to the HIP runtime and device libraries
+can be specified either using compiler options or environment variables. The paths can also be set through the ROCm path
+if they follow the ROCm installation directory structure.
+
+Order of Precedence for HIP Path
+--------------------------------
+
+1. ``--hip-path`` compiler option
+2. ``HIP_PATH`` environment variable *(use with caution)*
+3. ``--rocm-path`` compiler option
+4. ``ROCM_PATH`` environment variable *(use with caution)*
+5. Default automatic detection (relative to Clang or at the default ROCm installation location)
+
+Order of Precedence for Device Library Path
+-------------------------------------------
+
+1. ``--hip-device-lib-path`` compiler option
+2. ``HIP_DEVICE_LIB_PATH`` environment variable *(use with caution)*
+3. ``--rocm-path`` compiler option
+4. ``ROCM_PATH`` environment variable *(use with caution)*
+5. Default automatic detection (relative to Clang or at the default ROCm installation location)
+
+.. list-table::
+ :header-rows: 1
+
+ * - Compiler Option
+ - Environment Variable
+ - Description
+ - Default Value
+ * - ``--rocm-path=<path>``
+ - ``ROCM_PATH``
+ - Specifies the ROCm installation path.
+ - Automatic detection
+ * - ``--hip-path=<path>``
+ - ``HIP_PATH``
+ - Specifies the HIP runtime installation path.
+ - Determined by ROCm directory structure
+ * - ``--hip-device-lib-path=<path>``
+ - ``HIP_DEVICE_LIB_PATH``
+ - Specifies the HIP device library installation path.
+ - Determined by ROCm directory structure
+
+.. note::
+
+ We recommend using the compiler options as the primary method for specifying these paths. While the environment variables ``ROCM_PATH``, ``HIP_PATH``, and ``HIP_DEVICE_LIB_PATH`` are supported, their use can lead to implicit dependencies that might cause issues in the long run. Use them with caution.
+
+
+Predefined Macros
+=================
+
+.. list-table::
+ :header-rows: 1
+
+ * - Macro
+ - Description
+ * - ``__CLANG_RDC__``
+ - Defined when Clang is compiling code in Relocatable Device Code (RDC) mode. RDC, enabled with the ``-fgpu-rdc`` compiler option, is necessary for linking device codes across translation units.
+ * - ``__HIP__``
+ - Defined when compiling with HIP language support, indicating that the code targets the HIP environment.
+ * - ``__HIPCC__``
+ - Alias to ``__HIP__``.
+ * - ``__HIP_DEVICE_COMPILE__``
+ - Defined during device code compilation in Clang's separate compilation process for the host and each offloading GPU architecture.
+ * - ``__HIP_MEMORY_SCOPE_SINGLETHREAD``
+ - Represents single-thread memory scope in HIP (value is 1).
+ * - ``__HIP_MEMORY_SCOPE_WAVEFRONT``
+ - Represents wavefront memory scope in HIP (value is 2).
+ * - ``__HIP_MEMORY_SCOPE_WORKGROUP``
+ - Represents workgroup memory scope in HIP (value is 3).
+ * - ``__HIP_MEMORY_SCOPE_AGENT``
+ - Represents agent memory scope in HIP (value is 4).
+ * - ``__HIP_MEMORY_SCOPE_SYSTEM``
+ - Represents system-wide memory scope in HIP (value is 5).
+ * - ``__HIP_NO_IMAGE_SUPPORT__``
+ - Defined with a value of 1 when the target device lacks support for HIP image functions.
+ * - ``__HIP_NO_IMAGE_SUPPORT``
+ - Alias to ``__HIP_NO_IMAGE_SUPPORT__``. Deprecated.
+ * - ``__HIP_API_PER_THREAD_DEFAULT_STREAM__``
+ - Defined when the GPU default stream is set to per-thread mode.
+ * - ``HIP_API_PER_THREAD_DEFAULT_STREAM``
+ - Alias to ``__HIP_API_PER_THREAD_DEFAULT_STREAM__``. Deprecated.
+
More information about the cfe-commits
mailing list