[clang] [llvm] [clang][docs] Add preliminary documentation for SPIR-V support in the HIPAMD ToolChain (PR #96657)

[via llvm-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Alex Voicu (AlexVlx)

<details>
<summary>Changes</summary>

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
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.

``````````

</details>


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