[llvm] [NFC][AMDGPU][Doc] Add developer guideline (PR #194425)

[Matt Arsenault via llvm-commits]

================
@@ -0,0 +1,297 @@
+===============================
+Developer Guideline for AMDGPU
+===============================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document collects coding conventions, test policies, and other development
+guidelines that apply to all AMDGPU-related code across the LLVM project (the
+backend in ``llvm/lib/Target/AMDGPU``, Clang AMDGPU support, LLD, associated
+tests, etc.).  It supplements the
+`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_ and the
+`LLVM Testing Guide <https://llvm.org/docs/TestingGuide.html>`_; everything in
+those documents still applies unless explicitly overridden here.
+
+Some of the guidelines below overlap with rules in the upstream LLVM
+documentation.  They are included here for convenience so that all expectations
+for AMDGPU contributions are collected in one place.
+
+Coding Standards
+================
+
+AMDGPU-related code follows the
+`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_ with the
+refinements listed below.
+
+Use of ``auto``
+---------------
+
+Do **not** use ``auto`` except in the following cases:
+
+* Lambda expressions:
+
+  .. code-block:: c++
+
+     auto Pred = [](unsigned Val) { return Val > 0; };
+
+* Casts where the target type is already spelled out on the right-hand side
+  (``cast``, ``dyn_cast``, ``static_cast``, etc.):
+
+  .. code-block:: c++
+
+     auto *Inst = cast<CallInst>(V);
+
+* Iterators:
+
+  .. code-block:: c++
+
+     auto It = Container.begin();
+
+* Structured bindings:
+
+  .. code-block:: c++
+
+     auto [Key, Value] = Pair;
+
+In all other cases, write the type explicitly.
+
+Use of Braces
+-------------
+
+LLVM's coding standard allows omitting braces around a single-statement block.
+In AMDGPU code, braces may be omitted **only when the single statement
+fits on one line**.  If the statement spans more than one line (e.g. because of
+a long argument list that wraps), keep the braces.
+
+For ``if``/``else`` chains, if **either** branch requires braces, add braces to
+**all** branches to keep them symmetric.
+
+.. code-block:: c++
+
+   // OK — single statement on one line, braces omitted.
+   for (unsigned I = 0; I < N; ++I)
+     doSomething(I);
+
+   // Required — single statement, but spans multiple lines.
+   if (Cond) {
+     doSomethingElse(LongArgument1,
+                     LongArgument2);
+   }
+
+   // Required — the else branch needs braces, so the if branch gets them too.
+   if (Cond) {
+     doSomething();
+   } else {
+     doSomethingElse(LongArgument1,
+                     LongArgument2);
+   }
+
+   // Avoid — asymmetric braces.
+   if (Cond)
+     doSomething();
+   else {
+     doSomethingElse(LongArgument1,
+                     LongArgument2);
+   }
+
+Design Practices
+=================
+
+Prefer Feature Checks over Generation Checks
+---------------------------------------------
+
+Avoid conditioning logic on a specific GPU generation (e.g. ``isGFX11()``).
+Generation checks are fragile: when a new generation ships, every such check
+must be audited to decide whether it should include the new generation too.
+
+Instead, query the specific capability that the code actually depends on via a
+feature predicate (e.g. ``hasFeatureX()``).  Feature predicates are
+self-documenting, compose better across generations, and do not require updates
+when a new generation is added.
+
+.. code-block:: c++
+
+   // Avoid — ties the logic to a specific generation.
+   if (ST.isGFX11())
+     handleNewBehaviour();
+
+   // Preferred — checks the actual capability.
+   if (ST.hasPackedFP32Ops())
+     handleNewBehaviour();
+
----------------
arsenm wrote:

Naming should try to match the terminology of the ISA documentation. Instruction enum names should be all caps, matching the documentation's name for at least 1 target. Compiler invented variants of that instruction should use a lowercase suffix (e.g., if you need a variant that has additional property flags or register uses)

When instructions have different properties on different subtargets, prefer using different opcodes rather than littering if target checks in the code 

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