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

[via cfe-commits]

Author: Alex Voicu
Date: 2024-06-28T14:57:27+01:00
New Revision: f425db8732770c8abe1f18f7b3606a4aba45b7d8

URL: https://github.com/llvm/llvm-project/commit/f425db8732770c8abe1f18f7b3606a4aba45b7d8
DIFF: https://github.com/llvm/llvm-project/commit/f425db8732770c8abe1f18f7b3606a4aba45b7d8.diff

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

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.

Added: 
    

Modified: 
    clang/docs/HIPSupport.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/HIPSupport.rst b/clang/docs/HIPSupport.rst
index 5ba84c2f67055..e26297c7af97a 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 ``hip-spirv64-amd-amdhsa--amdgcnspirv``.
+
+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.