[clang][docs] Add preliminary documentation for SPIR-V support in the HIPAMD ToolChain

[AlexVlx]

This is mostly stealing from #75357, and updating it to reflect the pivot towards AMDGCN flavoured SPIR-V and the slightly different set of limitations. As we bring up more functionality it will be updated accordingly. With thanks to @yxsamliu.

[llvmbot]

@llvm/pr-subscribers-clang

Author: Alex Voicu (AlexVlx)

Changes

This is mostly stealing from #75357, and updating it to reflect the pivot towards AMDGCN flavoured SPIR-V and the slightly different set of limitations. As we bring up more functionality it will be updated accordingly. With thanks to @yxsamliu.

---

Full diff: https://github.com/llvm/llvm-project/pull/96657.diff

1 Files Affected:

• (modified) clang/docs/HIPSupport.rst (+45)

diff --git a/clang/docs/HIPSupport.rst b/clang/docs/HIPSupport.rst
index 5ba84c2f67055..72a6871903340 100644
--- a/clang/docs/HIPSupport.rst
+++ b/clang/docs/HIPSupport.rst
@@ -284,3 +284,48 @@ Example Usage
       Base* basePtr = &obj;
       basePtr->virtualFunction(); // Allowed since obj is constructed in device code
    }
+
+SPIR-V Support on HIPAMD ToolChain
+==================================
+
+The HIPAMD ToolChain supports targetting
+`AMDGCN Flavoured SPIR-V <https://llvm.org/docs/SPIRVUsage.html#target-triples>`_.
+The support for SPIR-V in the ROCm and HIPAMD ToolChain is under active
+development.
+
+Compilation Process
+-------------------
+
+When compiling HIP programs with the intent of utilizing SPIR-V, the process
+diverges from the traditional compilation flow:
+
+Using ``--offload-arch=amdgcnspirv``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- **Target Triple**: The ``--offload-arch=amdgcnspirv`` flag instructs the
+  compiler to use the target triple ``spirv64-amd-amdhsa``. This approach does
+  generates generic AMDGCN SPIR-V which retains architecture specific elements
+  without hardcoding them, thus allowing for optimal target specific code to be
+  generated at run time, when the concrete target is known.
+
+- **LLVM IR Translation**: The program is compiled to LLVM Intermediate
+  Representation (IR), which is subsequently translated into SPIR-V. In the
+  future, this translation step will be replaced by direct SPIR-V emission via
+  the SPIR-V Back-end.
+
+- **Clang Offload Bundler**: The resulting SPIR-V is embedded in the Clang
+  offload bundler with the bundle ID ``hipv4-hip-spirv64-amd-amdhsa-generic``.
+
+Mixed with Normal ``--offload-arch``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Mixing ``amdgcnspirv`` and concrete ``gfx###`` targets via ``--offload-arch``
+is not currently supported; this limitation is temporary and will be removed in
+a future release**
+
+Architecture Specific Macros
+----------------------------
+
+None of the architecture specific :doc:`AMDGPU macros <AMDGPUSupport>` are
+defined when targeting SPIR-V. An alternative, more flexible mechanism to enable
+doing per target / per feature code selection will be added in the future.

[jhuber6]

LGTM

[jhuber6]

I'll need to play with this with my driver code. I'm guessing it's because it needs to generate an entirely separate toolchain? The OpenMP path basically does that by inferring the toolchain from the string value, so we can support --offload-arch=sm_89,gfx90a for example.

[yxsamliu]

I think we need HIPAMD toolchain instead of HIPSPIRV toolchain because we want to locate the tools and device libraries on ROCm platform and do argument translation using amdgpu information like we are compiling for any amdgpu processors.

[AlexVlx]

@yxsamliu is correct, the HIPSPIRV toolchain is matched to a different downstream ecosystem.

[AlexVlx]

I'll need to play with this with my driver code. I'm guessing it's because it needs to generate an entirely separate toolchain? The OpenMP path basically does that by inferring the toolchain from the string value, so we can support --offload-arch=sm_89,gfx90a for example.

Not quite, it's more because we'd have to nest two triples (spirv64-amd-amdhsa && amdgcn-amd-amdhsa) within the same toolchain, since we're using the same HIPAMD ToolChain. It's fixable, just slightly faffy to do without spamming toolchains / within the same toolchain.

[jhuber6]

I'll need to play with this with my driver code. I'm guessing it's because it needs to generate an entirely separate toolchain? The OpenMP path basically does that by inferring the toolchain from the string value, so we can support --offload-arch=sm_89,gfx90a for example.

Not quite, it's more because we'd have to nest two triples (spirv64-amd-amdhsa && amdgcn-amd-amdhsa) within the same toolchain, since we're using the same HIPAMD ToolChain. It's fixable, just slightly faffy to do without spamming toolchains / within the same toolchain.

Honestly I'm wondering if it would be cleaner to just make a HIPSPIRVToolChain since we may want special handling in the future.

[AlexVlx]

I'll need to play with this with my driver code. I'm guessing it's because it needs to generate an entirely separate toolchain? The OpenMP path basically does that by inferring the toolchain from the string value, so we can support --offload-arch=sm_89,gfx90a for example.

Not quite, it's more because we'd have to nest two triples (spirv64-amd-amdhsa && amdgcn-amd-amdhsa) within the same toolchain, since we're using the same HIPAMD ToolChain. It's fixable, just slightly faffy to do without spamming toolchains / within the same toolchain.

Honestly I'm wondering if it would be cleaner to just make a HIPSPIRVToolChain since we may want special handling in the future.

I looked at this and it doesn't look super appealing (turned into something of a rabbit hole), it'd duplicate a lot of the existing toolchain, and would also try to squat in an already overcrowded space (there's already HIPSPV).

[jhuber6]

I looked at this and it doesn't look super appealing (turned into something of a rabbit hole), it'd duplicate a lot of the existing toolchain, and would also try to squat in an already overcrowded space (there's already HIPSPV).

We already have a SPIR-V toolchain for HIP? Seems like it was added over two years ago. What does the other handling do that this toolchain doesn't?