[amdgpu] start documenting amdgpu support by clang

[yaxunl]

Summary

start with predefined macros

[yaxunl]

remove redundant text

[jdoerfert]

clang/docs/AMDGPUSupport.rst

34

FWIW, this arguably confusing use of AMD, and duplication of AMDGPU, should be deprecated and removed. Or at least not advocated...

63

Any reason this one does not end in __?

[arsenm]

clang/docs/AMDGPUSupport.rst

55

The fma macro was actually from the opencl spec but never handled in the correct place

[yaxunl]

clang/docs/AMDGPUSupport.rst

63

It is my mistake. Did not consider consistency when designing this macro.

[yaxunl]

clang/docs/AMDGPUSupport.rst

34

will remove from the documentation.

55

will remove

[yaxunl]

revised by comments

[jdoerfert]

I would recommend to introduce __AMDGCN_WAVEFRONT_SIZE__ as an alias for '__AMDGCN_WAVEFRONT_SIZE and at some point to deprecate the latter.
Otherwise, LGTM

[yaxunl]

In D154133#4462387, @jdoerfert wrote:

I would recommend to introduce __AMDGCN_WAVEFRONT_SIZE__ as an alias for '__AMDGCN_WAVEFRONT_SIZE and at some point to deprecate the latter.
Otherwise, LGTM

Added __AMDGCN_WAVEFRONT_SIZE__ in https://reviews.llvm.org/D154207. will update the documentation

[yaxunl]

added __AMDGCN_WAVEFRONT_SIZE__ and reordered

[arsenm]

clang/docs/AMDGPUSupport.rst

21

"on amdgpu target" doesn't sound grammatical

[lamb-j]

clang/docs/AMDGPUSupport.rst

21

"for the amdgpu target"? or
"on AMD GPU targets?"

50

Defined?

[yaxunl]

clang/docs/AMDGPUSupport.rst

21

will use "on AMD GPU targets".

50

will fix

[yaxunl]

revised by comments

[arsenm]

Need to start somewhere

[scchan]

clang/docs/AMDGPUSupport.rst

47

This set of feature macros is tricky. A feature macro is defined only when the corresponding target feature has been explicitly specified during compilation; otherwise it's undefined. Users will have to refer to the target feature table to get the semantic of each state. For example, for xnack, undefined=="any", 1 for xnack+, 0 for xnack-.

Is there a reason we don't support features other than sramecc and xnack?

[yaxunl]

clang/docs/AMDGPUSupport.rst

47

This macro is designed to support Target ID only, therefore it is only emitted when target ID containing the feature is used.

The target ID features are stable since they are used to select code objects from fat binaries.

My understanding is that other features used by amdgpu backend do not have stable feature names, therefore are not suitable to be used as predefined macros for users to condition their code.

[scchan]

clang/docs/AMDGPUSupport.rst

47

The current wording seems to imply that a feature macro is always defined if that target feature is supported but that's not the case. For example, the macro amdgcn_feature_xnack is undefined if a user compiles for xnack="any".

clang/docs/AMDGPUSupport.rst

+.. 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:
+
+==============
+AMDGPU Support
+==============
+
+Clang supports OpenCL, HIP and OpenMP on AMD GPU targets.
+
+
+Predefined Macros
+=================
+
+
+.. list-table::
+   :header-rows: 1
+
+   * - Macro
+     - Description
+   * - ``__AMDGPU__``
+     - Indicates that the code is being compiled for an AMD GPU.
+   * - ``__AMDGCN__``
+     - Defined if the GPU target is AMDGCN.
+   * - ``__R600__``
+     - Defined if the GPU target is R600.
+   * - ``__<ArchName>__``
+     - Defined with the name of the architecture (e.g., ``__gfx906__`` for the gfx906 architecture).
+   * - ``__<GFXN>__``
+     - Defines the GFX family (e.g., for gfx906, this macro would be ``__GFX9__``).
+   * - ``__amdgcn_processor__``
+     - Defined with the processor name as a string (e.g., ``"gfx906"``).
+   * - ``__amdgcn_target_id__``
+     - Defined with the target ID as a string.
+   * - ``__amdgcn_feature_<feature-name>__``
+     - Defined for each supported target feature. The value is 1 if the feature is enabled and 0 if it is disabled. Allowed feature names are sramecc and xnack.
+   * - ``__AMDGCN_CUMODE__``
+     - Defined as 1 if the CU mode is enabled and 0 if the WGP mode is enabled.
+   * - ``__AMDGCN_UNSAFE_FP_ATOMICS__``
+     - Defined if unsafe floating-point atomics are allowed.
+   * - ``__AMDGCN_WAVEFRONT_SIZE__``
+     - Defines the wavefront size. Allowed values are 32 and 64.
+   * - ``__AMDGCN_WAVEFRONT_SIZE``
+     - Alias to ``__AMDGCN_WAVEFRONT_SIZE__``. To be deprecated.
+   * - ``__HAS_FMAF__``
+     - Defined if FMAF instruction is available (deprecated).
+   * - ``__HAS_LDEXPF__``
+     - Defined if LDEXPF instruction is available (deprecated).
+   * - ``__HAS_FP64__``
+     - Defined if FP64 instruction is available (deprecated).
+
+Please note that the specific architecture and feature names will vary depending on the GPU. Also, some macros are deprecated and may be removed in future releases.