[llvm] [DXIL][Doc] Update specification of to use TableGen list instead of dag (PR #99055)

[David Peixotto via llvm-commits]

================
@@ -172,112 +177,257 @@ Shader Model version is represented as follows:
      int Minor = minor;
    }
 
-   // Valid Shader model version records
 
-   // Definition of Shader Model 6.0 - 6.8 and DXIL Version 1.0 - 1.8
+Concrete representations of valid DXIL versions are defined as follows:
+
+.. code-block::
+
+   // Definition of DXIL Version 1.0 - 1.8
    foreach i = 0...8 in {
-     def SM6_#i : Version<6, i>;
-     def DX1_#i : Version<1, i>;
+     def DXIL1_#i : Version<1, i>;
    }
 
-A shader model version predicate class is defined as
+Shader Stage Specification
+==========================
+
+Various shader stages such as ``compute``, ``pixel``, ``vertex``, etc., are represented
+as follows
 
 .. code-block::
 
-   class SMVersion<Version ver> : Pred {
-     Version SMVersion = ver;
-   }
+   // Shader stages
+   class ShaderStage;
+
+   def compute : ShaderStage;
+   def pixel : ShaderStage;
+   def vertex : ShaderStage;
+   ...
 
-A constraint class to represent overload types and shader stages predicated on shader
-model version is defined as
+Shader Attribute Specification
+==============================
+
+Various operation memory access and boolean attributes such as ``ReadNone``,
+``IsWave`` etc., are represented as follows
 
 .. code-block::
 
-   class SMVersionConstraints<SMVersion smver, dag oloads, dag stages> : Constraint<smver> {
-     dag overload_types = oloads;
-     dag stage_kinds = stages;
+  class DXILAttribute;
+
+  def ReadOnly : DXILOpAttributes;
+  def ReadNone : DXILOpAttributes;
+  def IsWave : DXILOpAttributes;
+  ...
+
+Constrained Specification
+=========================
+
+DXIL Operation properties such as valid overload types, shader stages and
+attributes are predicated on DXIL version. These are represented as list of
+versioned constraints.
+
+Overload Type Specification
+---------------------------
+
+``overloads`` field of ``class DXILOp`` is used to represent valid operation
+overloads predicated on DXIL version as list of records of the following class
+
+.. code-block::
+
+   class VersionedOverloads<Version minver, list<LLVMType> ols> {
+     Version dxil_version = minver;
+     list<LLVMType> overload_types = ols;
    }
 
-The ``dag overload_types`` and ``dag shader_kinds`` use a special markers ``overloads``
-and ``stages``, respectively.
+Following is an example specification of valid overload types for ``DXIL1_0`` and
+``DXIL1_2``.
 
-Examples of Constraints
------------------------
+.. code-block::
+
+   overloads = [
+                 VersionedOverloads<DXIL1_0, [halfTy, floatTy]>,
+                 VersionedOverloads<DXIL1_2, [halfTy, floatTy, doubleTy]>
+               ];
+
+An empty list signifies that the operation supports no overload types.
 
-Consider a DXIL Operation that is valid in Shader Model 6.2 and later,
 
-1. with valid overload types ``half``, ``float``, ``i16`` and ``i32``
-2. is valid for stages ``pixel`` and ``compute``
-3. with valid overload types ``double`` and ``i614`` if Shader Model version 6.3 and later
-4. is valid for all stages if Shader Model version 6.3 and later
+Stages Specification
+--------------------
+
+``stages`` field of ``class DXILOp`` is used to represent valid operation
+stages predicated on DXIL version as list of records of the following class
+
+.. code-block::
+
+   class VersionedStages<Version minver, list<ShaderStage> sts> {
+     Version dxil_version = minver;
+     list<ShaderStage> shader_stages = sts;
+   }
 
-This is represented as
+Following is an example specification of valid stages for ``DXIL1_0``,
+``DXIL1_2``, ``DXIL1_4`` and ``DXIL1_6``.
 
 .. code-block::
 
-   [SMVersionConstraints<SMVersion<SM6_2>,
-                          (overloads llvm_half_ty, llvm_float_ty, llvm_i16_ty, llvm_i32_ty),
-                          (stages pixel, compute)>,
-    SMVersionConstraints<SMVersion<SM6_3>,
-                          (overloads llvm_half_ty, llvm_float_ty, llvm_double_ty,
-                                 llvm_i16_ty, llvm_i32_ty, llvm_i64_ty),
-                          (stages allKinds)>];
+   stages = [
+             VersionedStages<DXIL1_0, [compute, pixel]>,
+             VersionedStages<DXIL1_2, [compute, pixel, mesh]>,
+             VersionedStages<DXIL1_4, [all_stages]>,
----------------
dmpots wrote:

There is no `DXIL1_1` or `DXIL1_5` in this list. It would be good to say explicitly in the docs what that means.

Edit,

I saw it when reading more, but it looked like it applied to the attributes section. Might be worth putting it into its own section that describes how to interpret the constraints.

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