Index: clang/docs/HIPSupport.rst
===================================================================
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,143 @@
+.. 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 that allows developers to create portable applications for
+GPUs from single source code.
+
+Clang supports HIP on `ROCm platform <https://rocm.docs.amd.com/en/latest/#>`_.
+
+Example Usage
+=============
+
+To compile a HIP program, you can use the following command:
+
+.. code-block:: shell
+
+   clang++ -c --offload-arch=gfx906 -xhip test.cpp -o test.o
+
+This command will compile a .cpp file with the -xhip option to indicate that
+the source is a HIP program. However, if the file has a .hip extension, you
+don't need the -xhip option. Clang will automatically recognize it as a HIP
+program. Here's an example:
+
+.. code-block:: shell
+
+   clang++ -c --offload-arch=gfx906 test.hip -o test.o
+
+To link a HIP program, you can use this command:
+
+.. code-block:: shell
+
+   clang++ --hip-link --offload-arch=gfx906 test.o -o test
+
+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 run the ``amdgpu-arch`` tool that comes with Clang to list the GPU architecture on your sytem:
+
+.. code-block:: shell
+
+   amdgpu-arch
+
+You can also use ``--offload-arch=native`` to let ``amdgpu-arch`` automatically detect the GPU architectures on your system:
+
+.. code-block:: shell
+
+   clang -c --offload-arch=native -xhip test.cpp -o test.o
+
+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_API_PER_THREAD_DEFAULT_STREAM``
+     - Defined when the GPU default stream is set to per-thread mode.
+