[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

This revision was automatically updated to reflect the committed changes.
yaxunl marked 2 inline comments as done.
Closed by commit rG795e934e15b7: [HIP] Start document HIP support by clang 
(authored by yaxunl).
Herald added a project: clang.

Changed prior to commit:
  https://reviews.llvm.org/D154123?vs=543652=543947#toc

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

Files:
  clang/docs/HIPSupport.rst

Index: clang/docs/HIPSupport.rst
===
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,175 @@
+.. raw:: html
+
+  
+.none { background-color: #FF }
+.part { background-color: #99 }
+.good { background-color: #CCFF99 }
+  
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+   :local:
+
+=
+HIP Support
+=
+
+HIP (Heterogeneous-Compute Interface for Portability) ``_ is
+a C++ Runtime API and Kernel Language. It enables developers to create portable applications for
+offloading computation to different hardware platforms from a single source code.
+
+AMD GPU Support
+===
+
+Clang provides HIP support on AMD GPUs via the ROCm platform ``_.
+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 ``_.
+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 ``_, 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 ``_. 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 `_.
+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. 

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl marked 3 inline comments as done.
yaxunl added inline comments.



Comment at: clang/docs/HIPSupport.rst:30
+
+Clang provides partial HIP support on Intel GPUs using the CHIP-Star project 
``_. 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 SPIRV via the SPIRV backend or the out-of-tree LLVM-SPIRV 
translator. The SPIRV is then bundled and embedded into the host executables.
+

keryell wrote:
> Fix the spelling when we talk about the Khronos SPIR-V standard, by 
> opposition to tool names.
> Perhaps you can split the line in shorter ones so the diff are more obvious.
> Fix the spelling when we talk about the Khronos SPIR-V standard, by 
> opposition to tool names.
> Perhaps you can split the line in shorter ones so the diff are more obvious.

will do



Comment at: clang/docs/HIPSupport.rst:65
+
+   clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
+

keryell wrote:
> yaxunl wrote:
> > arsenm wrote:
> > > scchan wrote:
> > > > missing --hip-link
> > > What does hip-link do? Why is it needed? I never use it and it works
> > It indicates HIP offloading at the linking stage and creates the HIP 
> > toolchain.
> > 
> > For -fno-gpu-rdc mode, it locates the HIP runtime library and links it.
> > 
> > For -fgpu-rdc mode, it unbundles object files and does device linking and 
> > embedding.
> I am a little lost here.
> I have the feeling that the newbie syntax (compile+link in one invocation) 
> should be
> ```
> clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
> ```
> since it should be obvious to the Driver that we want to produce a working 
> program for a GPU.
> Or does this work producing a working program with another meaning?
Currently, the linker will only link HIP runtime library when --hip-link is 
specified.

The linker does not see `-xhip sample.cpp`. It only sees the intermediate obj 
files passed to it, therefore it does not know it is for HIP.

This could be improved by letting the clang driver add an implicit `--hip-link` 
option to the linker when the driver sees the linking of HIP input files. 
However, this needs a separate patch.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Ronan Keryell via Phabricator via cfe-commits]

keryell added inline comments.



Comment at: clang/docs/HIPSupport.rst:30
+
+Clang provides partial HIP support on Intel GPUs using the CHIP-Star project 
``_. 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 SPIRV via the SPIRV backend or the out-of-tree LLVM-SPIRV 
translator. The SPIRV is then bundled and embedded into the host executables.
+

Fix the spelling when we talk about the Khronos SPIR-V standard, by opposition 
to tool names.
Perhaps you can split the line in shorter ones so the diff are more obvious.



Comment at: clang/docs/HIPSupport.rst:65
+
+   clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
+

yaxunl wrote:
> arsenm wrote:
> > scchan wrote:
> > > missing --hip-link
> > What does hip-link do? Why is it needed? I never use it and it works
> It indicates HIP offloading at the linking stage and creates the HIP 
> toolchain.
> 
> For -fno-gpu-rdc mode, it locates the HIP runtime library and links it.
> 
> For -fgpu-rdc mode, it unbundles object files and does device linking and 
> embedding.
I am a little lost here.
I have the feeling that the newbie syntax (compile+link in one invocation) 
should be
```
clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
```
since it should be obvious to the Driver that we want to produce a working 
program for a GPU.
Or does this work producing a working program with another meaning?


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Siu Chi Chan via Phabricator via cfe-commits]

scchan accepted this revision.
scchan added a comment.
This revision is now accepted and ready to land.

LGTM thanks


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl updated this revision to Diff 543652.
yaxunl marked an inline comment as done.
yaxunl added a comment.

revised by comments


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

Files:
  clang/docs/HIPSupport.rst

Index: clang/docs/HIPSupport.rst
===
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,162 @@
+.. raw:: html
+
+  
+.none { background-color: #FF }
+.part { background-color: #99 }
+.good { background-color: #CCFF99 }
+  
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+   :local:
+
+=
+HIP Support
+=
+
+HIP (Heterogeneous-Compute Interface for Portability) ``_ is a C++ Runtime API and Kernel Language. It enables developers to create portable applications for offloading computation to different hardware platforms from a single source code.
+
+AMD GPU Support
+===
+
+Clang provides HIP support on AMD GPUs via the ROCm platform ``_. 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 ``_. 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 SPIRV via the SPIRV backend or the out-of-tree LLVM-SPIRV translator. The SPIRV 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 ``_, 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 ``_. 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 `_. 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 

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl marked 2 inline comments as done.
yaxunl added inline comments.



Comment at: clang/docs/HIPSupport.rst:65
+
+   clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
+

arsenm wrote:
> scchan wrote:
> > missing --hip-link
> What does hip-link do? Why is it needed? I never use it and it works
It indicates HIP offloading at the linking stage and creates the HIP toolchain.

For -fno-gpu-rdc mode, it locates the HIP runtime library and links it.

For -fgpu-rdc mode, it unbundles object files and does device linking and 
embedding.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Matt Arsenault via Phabricator via cfe-commits]

arsenm added inline comments.



Comment at: clang/docs/HIPSupport.rst:65
+
+   clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
+

scchan wrote:
> missing --hip-link
What does hip-link do? Why is it needed? I never use it and it works


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Siu Chi Chan via Phabricator via cfe-commits]

scchan added inline comments.



Comment at: clang/docs/HIPSupport.rst:65
+
+   clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
+

missing --hip-link



Comment at: clang/docs/HIPSupport.rst:77
+
+   clang++ --offload-arch=native -xhip sample.cpp -o sample
+

missing --hip-link


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl added a comment.

ping


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl updated this revision to Diff 541028.
yaxunl marked 4 inline comments as done.
yaxunl added a comment.

revised by comments


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

Files:
  clang/docs/HIPSupport.rst

Index: clang/docs/HIPSupport.rst
===
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,162 @@
+.. raw:: html
+
+  
+.none { background-color: #FF }
+.part { background-color: #99 }
+.good { background-color: #CCFF99 }
+  
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+   :local:
+
+=
+HIP Support
+=
+
+HIP (Heterogeneous-Compute Interface for Portability) ``_ is a C++ Runtime API and Kernel Language. It enables developers to create portable applications for offloading computation to different hardware platforms from a single source code.
+
+AMD GPU Support
+===
+
+Clang provides HIP support on AMD GPUs via the ROCm platform ``_. 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 ``_. 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 SPIRV via the SPIRV backend or the out-of-tree LLVM-SPIRV translator. The SPIRV 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 ``_, 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 ``_. 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++ --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 `_. 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++ --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 

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl marked 5 inline comments as done.
yaxunl added inline comments.



Comment at: clang/docs/HIPSupport.rst:24
+
+Clang supports HIP on `ROCm platform `_.
+

keryell wrote:
> keryell wrote:
> > I thought the idea of HIP was to also target Nvidia GPU? Otherwise I do not 
> > understand "portable applications for GPUs" above.
> Thinking to the fact this is used by other projects like 
> https://github.com/CHIP-SPV/chipStar this is even wider but at the same time 
> that project is not up-streamed.
will add a brief description of HIP support on other devices.



Comment at: clang/docs/HIPSupport.rst:33
+
+   clang++ -c --offload-arch=gfx906 -xhip test.cpp -o test.o
+

keryell wrote:
> I suggest giving also a simpler example without `-c` to generate directly an 
> executable without split compile and link.
> Also avoid using `test` as an example as it is confusing as it is also a 
> shell builtin on Unix and it might take sometime to understand why the `test` 
> does not use the GPU. :-)
will do



Comment at: clang/docs/HIPSupport.rst:35-37
+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

keryell wrote:
> 
will fix



Comment at: clang/docs/HIPSupport.rst:141
+ - 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.

keryell wrote:
> Should this one be with underscores too?
> 
This is due to design inconsistency. The same with `__HIP_NO_IMAGE_SUPPORT`.

Since these two macros are new and not widely used, renaming them won't cause 
significant interruptions. I will let clang emit `__HIP_NO_IMAGE_SUPPORT__` and 
`__HIP_API_PER_THREAD_DEFAULT_STREAM__` and make the current ones alias and 
document them as deprecated.

The macros for HIP memory scope were designed by following the naming 
convention of clang atomic macros e.g. `__ATOMIC_RELAXED`, 
`__OPENCL_MEMORY_SCOPE_WORK_ITEM`, therefore they will not be changed.



CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Ronan Keryell via Phabricator via cfe-commits]

keryell added inline comments.



Comment at: clang/docs/HIPSupport.rst:24
+
+Clang supports HIP on `ROCm platform `_.
+

keryell wrote:
> I thought the idea of HIP was to also target Nvidia GPU? Otherwise I do not 
> understand "portable applications for GPUs" above.
Thinking to the fact this is used by other projects like 
https://github.com/CHIP-SPV/chipStar this is even wider but at the same time 
that project is not up-streamed.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Ronan Keryell via Phabricator via cfe-commits]

keryell added inline comments.



Comment at: clang/docs/HIPSupport.rst:24
+
+Clang supports HIP on `ROCm platform `_.
+

I thought the idea of HIP was to also target Nvidia GPU? Otherwise I do not 
understand "portable applications for GPUs" above.



Comment at: clang/docs/HIPSupport.rst:33
+
+   clang++ -c --offload-arch=gfx906 -xhip test.cpp -o test.o
+

I suggest giving also a simpler example without `-c` to generate directly an 
executable without split compile and link.
Also avoid using `test` as an example as it is confusing as it is also a shell 
builtin on Unix and it might take sometime to understand why the `test` does 
not use the GPU. :-)



Comment at: clang/docs/HIPSupport.rst:35-37
+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





Comment at: clang/docs/HIPSupport.rst:141
+ - 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.

Should this one be with underscores too?



CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl updated this revision to Diff 540485.
yaxunl marked an inline comment as done.
yaxunl edited the summary of this revision.
yaxunl added a comment.

revised by comments


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

Files:
  clang/docs/HIPSupport.rst

Index: clang/docs/HIPSupport.rst
===
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,143 @@
+.. raw:: html
+
+  
+.none { background-color: #FF }
+.part { background-color: #99 }
+.good { background-color: #CCFF99 }
+  
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+   :local:
+
+===
+HIP Support
+===
+
+`HIP (Heterogeneous-Compute Interface for Portability) `_
+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 `_.
+
+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 `_.
+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=``
+ - ``ROCM_PATH``
+ - Specifies the ROCm installation path.
+ - Automatic detection
+   * - ``--hip-path=``
+ - ``HIP_PATH``
+ - Specifies the HIP runtime installation path.
+ - Determined by ROCm directory structure
+   * - ``--hip-device-lib-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 

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl marked 3 inline comments as done.
yaxunl added inline comments.



Comment at: clang/docs/HIPSupport.rst:33
+
+   clang -c --offload-arch=gfx906 -xhip test.cpp -o test.o
+

arsenm wrote:
> Aren't you supposed to use clang++? Also, could show that .hip is recognized?
good point. will fix


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Matt Arsenault via Phabricator via cfe-commits]

arsenm added inline comments.



Comment at: clang/docs/HIPSupport.rst:33
+
+   clang -c --offload-arch=gfx906 -xhip test.cpp -o test.o
+

Aren't you supposed to use clang++? Also, could show that .hip is recognized?


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl marked 2 inline comments as done.
yaxunl added inline comments.



Comment at: clang/docs/HIPSupport.rst:49
+
+You can also use ``--offload-arch=native`` to let ``amdgpu-arch`` 
automatically detect the GPU architecture on your system:
+

arsenm wrote:
> s/architecture/architectures
done



Comment at: clang/docs/HIPSupport.rst:99
+
+Note: The compiler options override environment variables. Specifying HIP 
runtime and device library paths individually will override the ROCm path.
+

arsenm wrote:
> We should really not have the environment variables I wouldn't go out of the 
> way to advertise them, just mark as deprecated
added warnings to discourage use of env vars


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl updated this revision to Diff 540430.
yaxunl added a comment.

revised by comments


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

Files:
  clang/docs/HIPSupport.rst

Index: clang/docs/HIPSupport.rst
===
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,134 @@
+.. raw:: html
+
+  
+.none { background-color: #FF }
+.part { background-color: #99 }
+.good { background-color: #CCFF99 }
+  
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+   :local:
+
+===
+HIP Support
+===
+
+`HIP (Heterogeneous-Compute Interface for Portability) `_
+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 `_.
+
+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
+
+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 `_.
+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=``
+ - ``ROCM_PATH``
+ - Specifies the ROCm installation path.
+ - Automatic detection
+   * - ``--hip-path=``
+ - ``HIP_PATH``
+ - Specifies the HIP runtime installation path.
+ - Determined by ROCm directory structure
+   * - ``--hip-device-lib-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``
+ 

[PATCH] D154123: [HIP] Start document HIP support by clang

[Matt Arsenault via Phabricator via cfe-commits]

arsenm added inline comments.



Comment at: clang/docs/HIPSupport.rst:49
+
+You can also use ``--offload-arch=native`` to let ``amdgpu-arch`` 
automatically detect the GPU architecture on your system:
+

s/architecture/architectures



Comment at: clang/docs/HIPSupport.rst:99
+
+Note: The compiler options override environment variables. Specifying HIP 
runtime and device library paths individually will override the ROCm path.
+

We should really not have the environment variables I wouldn't go out of the 
way to advertise them, just mark as deprecated


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl updated this revision to Diff 538201.
yaxunl marked an inline comment as done.
yaxunl added a comment.

revised by comments


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

Files:
  clang/docs/HIPSupport.rst

Index: clang/docs/HIPSupport.rst
===
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,132 @@
+.. raw:: html
+
+  
+.none { background-color: #FF }
+.part { background-color: #99 }
+.good { background-color: #CCFF99 }
+  
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+   :local:
+
+===
+HIP Support
+===
+
+`HIP (Heterogeneous-Compute Interface for Portability) `_
+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 `_.
+
+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
+
+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 `_.
+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 architecture 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
+3. ``--rocm-path`` compiler option
+4. ``ROCM_PATH`` environment variable
+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
+3. ``--rocm-path`` compiler option
+4. ``ROCM_PATH`` environment variable
+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=``
+ - ``ROCM_PATH``
+ - Specifies the ROCm installation path.
+ - Automatic detection
+   * - ``--hip-path=``
+ - ``HIP_PATH``
+ - Specifies the HIP runtime installation path.
+ - Determined by ROCm directory structure
+   * - ``--hip-device-lib-path=``
+ - ``HIP_DEVICE_LIB_PATH``
+ - Specifies the HIP device library installation path.
+ - Determined by ROCm directory structure
+
+Note: The compiler options override environment variables. Specifying HIP runtime and device library paths individually will override the ROCm path.
+
+
+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 

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl marked an inline comment as done.
yaxunl added inline comments.



Comment at: clang/docs/HIPSupport.rst:82
+===
+
+1. **Compiler Options**: If you specify paths using the compiler options, 
these will override the correponding paths set via environment variables. 

scchan wrote:
> I think it would be easier to understand by explicitly calling out the order 
> of precedence:
> 
> - For HIP path:
>   - --hip-path option
>   - HIP_PATH env var
>   - --rocm-path option
>  - ROCM_PATH env var
>  - default automatic detection
> 
> 
> -- For device lib:
>   - --hip-device-lib-path option
>   - HIP_DEVICE_LIB_PATH env var
>   - --rocm-path option
>   -  ROCM_PATH env var
>   - default automatic detection
> 
wil do


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Siu Chi Chan via Phabricator via cfe-commits]

scchan added inline comments.



Comment at: clang/docs/HIPSupport.rst:82
+===
+
+1. **Compiler Options**: If you specify paths using the compiler options, 
these will override the correponding paths set via environment variables. 

I think it would be easier to understand by explicitly calling out the order of 
precedence:

- For HIP path:
  - --hip-path option
  - HIP_PATH env var
  - --rocm-path option
 - ROCM_PATH env var
 - default automatic detection


-- For device lib:
  - --hip-device-lib-path option
  - HIP_DEVICE_LIB_PATH env var
  - --rocm-path option
  -  ROCM_PATH env var
  - default automatic detection



CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl updated this revision to Diff 536231.
yaxunl marked 4 inline comments as done.
yaxunl added a comment.

revised by comments


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

Files:
  clang/docs/HIPSupport.rst

Index: clang/docs/HIPSupport.rst
===
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,124 @@
+.. raw:: html
+
+  
+.none { background-color: #FF }
+.part { background-color: #99 }
+.good { background-color: #CCFF99 }
+  
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+   :local:
+
+===
+HIP Support
+===
+
+`HIP (Heterogeneous-Compute Interface for Portability) `_
+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 `_.
+
+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
+
+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 `_.
+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 architecture on your system:
+
+.. code-block:: shell
+
+   clang -c --offload-arch=native -xhip test.cpp -o test.o
+
+Path Settings for HIP Dependencies
+==
+
+Compiling a HIP program relies on the HIP runtime and device libraries. You can configure the paths to these dependencies using either compiler options or environment variables.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Compiler Option
+ - Environment Variable
+ - Description
+ - Default Value
+   * - ``--rocm-path=``
+ - ``ROCM_PATH``
+ - Path to the ROCm installation. This should be specified if the HIP runtime and device libraries follow the ROCm installation directory structure.
+ - Compiler tries detecting ROCm path by relative path to clang assuming default ROCm directory structure, then tries detecting ROCm path by its default installation location.
+   * - ``--hip-path=``
+ - ``HIP_PATH``
+ - Path to the HIP runtime installation.
+ - Determined by assuming the ROCm directory structure.
+   * - ``--hip-device-lib-path=``
+ - ``HIP_DEVICE_LIB_PATH``
+ - Path to the HIP device library installation.
+ - Determined by assuming the ROCm directory structure.
+
+Precedence of Path Settings
+===
+
+1. **Compiler Options**: If you specify paths using the compiler options, these will override the correponding paths set via environment variables. 
+
+2. **HIP Runtime and Device Library Paths**: If you specify individual paths for the HIP runtime or device libraries using either the compiler options or environment variables, these paths will take precedence over the ROCm path.
+
+3. **ROCm Path**: If you don't specify individual paths for the HIP runtime and device libraries, you can specify the ROCm path. This is used as a base path to find the HIP runtime and device libraries assuming they are located in the default directory structure relative to the ROCm installation.
+
+4. **Automatic Detection**: If the ROCm path is not specified, the compiler attempts to detect the ROCm installation. Initially, it tries to find it by looking at the relative path to clang assuming the default ROCm directory structure. If this fails, it tries to find the ROCm installation at its default installation location.
+
+This hierarchy allows you flexibility in how you configure the paths depending on your installation and directory structure.
+
+
+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.
+   * - 

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl marked 5 inline comments as done.
yaxunl added inline comments.



Comment at: clang/docs/HIPSupport.rst:33
+
+   clang -c --offload-arch=gfx906 test.hip -o test.o
+

scchan wrote:
> can we add -xhip to enable HIP for files without the .hip file ext?
will do



Comment at: clang/docs/HIPSupport.rst:56
+Environment Variables
+=
+

scchan wrote:
> I'd suggest adding a section to cover compiler options to pass various 
> hip/rocm related paths and that using the compiler options would be a much 
> more preferable alternative.
It may be clearer to put the options and environment vars for setting 
dependency paths side by side since they are connected



Comment at: clang/docs/HIPSupport.rst:87
+   * - ``__HIPCC__``
+ - This macro indicates that the code is being compiled using the HIP 
compiler.
+   * - ``__HIP_MEMORY_SCOPE_SINGLETHREAD``

scchan wrote:
> I think this macro is essentially an alias to __HIP__?
Yes. will change the description 



Comment at: clang/docs/HIPSupport.rst:99
+   * - ``__HIP_DEVICE_COMPILE__``
+ - This macro is defined when the code is being compiled for a HIP device.
+   * - ``__HIP_NO_IMAGE_SUPPORT``

scchan wrote:
> It might be helpful to provide more context here as to how a HIP source file 
> gets compiled (once for the host and then once for each device arch).  Also 
> I'd suggest moving this up closer to __HIP__ given they are related.
will do


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Siu Chi Chan via Phabricator via cfe-commits]

scchan added inline comments.



Comment at: clang/docs/HIPSupport.rst:33
+
+   clang -c --offload-arch=gfx906 test.hip -o test.o
+

can we add -xhip to enable HIP for files without the .hip file ext?



Comment at: clang/docs/HIPSupport.rst:56
+Environment Variables
+=
+

I'd suggest adding a section to cover compiler options to pass various hip/rocm 
related paths and that using the compiler options would be a much more 
preferable alternative.



Comment at: clang/docs/HIPSupport.rst:87
+   * - ``__HIPCC__``
+ - This macro indicates that the code is being compiled using the HIP 
compiler.
+   * - ``__HIP_MEMORY_SCOPE_SINGLETHREAD``

I think this macro is essentially an alias to __HIP__?



Comment at: clang/docs/HIPSupport.rst:99
+   * - ``__HIP_DEVICE_COMPILE__``
+ - This macro is defined when the code is being compiled for a HIP device.
+   * - ``__HIP_NO_IMAGE_SUPPORT``

It might be helpful to provide more context here as to how a HIP source file 
gets compiled (once for the host and then once for each device arch).  Also I'd 
suggest moving this up closer to __HIP__ given they are related.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl added inline comments.



Comment at: clang/docs/HIPSupport.rst:104
+ - This macro is defined when the GPU default stream kind is set to 
per-thread.
+

b-sumner wrote:
> Should we include the __gfxNNN__ or __GFXN__ macros here?  What about wave 
> size, and CU mode?  And what about unsafe FP atomics macro?
Those are not only for HIP but for all languages targeting amdgpu. I am 
thinking we probably need a separate page for amdgpu support by clang.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Brian Sumner via Phabricator via cfe-commits]

b-sumner added inline comments.



Comment at: clang/docs/HIPSupport.rst:104
+ - This macro is defined when the GPU default stream kind is set to 
per-thread.
+

Should we include the __gfxNNN__ or __GFXN__ macros here?  What about wave 
size, and CU mode?  And what about unsafe FP atomics macro?


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154123/new/

https://reviews.llvm.org/D154123

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154123: [HIP] Start document HIP support by clang

[Yaxun Liu via Phabricator via cfe-commits]

yaxunl created this revision.
yaxunl added reviewers: tra, scchan, b-sumner, arsenm.
Herald added a project: All.
yaxunl requested review of this revision.
Herald added a subscriber: wdng.

start with example usage, predefined macros and env vars.


https://reviews.llvm.org/D154123

Files:
  clang/docs/HIPSupport.rst

Index: clang/docs/HIPSupport.rst
===
--- /dev/null
+++ clang/docs/HIPSupport.rst
@@ -0,0 +1,104 @@
+.. raw:: html
+
+  
+.none { background-color: #FF }
+.part { background-color: #99 }
+.good { background-color: #CCFF99 }
+  
+
+.. role:: none
+.. role:: part
+.. role:: good
+
+.. contents::
+   :local:
+
+===
+HIP Support
+===
+
+`HIP (Heterogeneous-Compute Interface for Portability) `_
+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 `_.
+
+Example Usage
+=
+
+To compile a HIP program, you can use the following command:
+
+.. 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 `_.
+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 architecture on your system:
+
+.. code-block:: shell
+
+   clang -c --offload-arch=native test.hip -o test.o
+
+Environment Variables
+=
+
+.. list-table::
+   :header-rows: 1
+
+   * - Variable
+ - Description
+ - Default Value
+   * - ``ROCM_PATH``
+ - ROCm installation path.
+ - Empty
+   * - ``HIP_PATH``
+ - HIP runtime installation path.
+ - Empty
+   * - ``HIP_DEVICE_LIB_PATH``
+ - HIP device library installation path.
+ - Empty
+
+Predefined Macros
+=
+
+.. list-table::
+   :header-rows: 1
+
+   * - Macro
+ - Description
+   * - ``__CLANG_RDC__``
+ - This macro indicates that Clang is used for relocatable device code compilation (RDC).
+   * - ``__HIP__``
+ - This macro is defined when the HIP language option is enabled. It is used to indicate that the code is being compiled for the HIP environment.
+   * - ``__HIPCC__``
+ - This macro indicates that the code is being compiled using the HIP compiler.
+   * - ``__HIP_MEMORY_SCOPE_SINGLETHREAD``
+ - This macro is set to 1 and represents the memory scope that is limited to a single thread in HIP.
+   * - ``__HIP_MEMORY_SCOPE_WAVEFRONT``
+ - This macro is set to 2 and represents the memory scope that is limited to a wavefront in HIP.
+   * - ``__HIP_MEMORY_SCOPE_WORKGROUP``
+ - This macro is set to 3 and represents the memory scope that is limited to a workgroup in HIP.
+   * - ``__HIP_MEMORY_SCOPE_AGENT``
+ - This macro is set to 4 and represents the memory scope that is limited to an agent in HIP.
+   * - ``__HIP_MEMORY_SCOPE_SYSTEM``
+ - This macro is set to 5 and represents the memory scope that is limited to the system in HIP.
+   * - ``__HIP_DEVICE_COMPILE__``
+ - This macro is defined when the code is being compiled for a HIP device.
+   * - ``__HIP_NO_IMAGE_SUPPORT``
+ - This macro is set to 1 when the target device does not support HIP image functions.
+   * - ``HIP_API_PER_THREAD_DEFAULT_STREAM``
+ - This macro is defined when the GPU default stream kind is set to per-thread.
+
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits