[llvm] [DirectX][DXIL] Design document for TableGen Spec of DXIL Operations (PR #85170)

[Justin Bogner via llvm-commits]

================
@@ -0,0 +1,224 @@
+==============================================================
+Specification of DXIL Operations using TableGen Representation
+==============================================================
+.. contents::
+   :local:
+
+.. toctree
+   :hidden
+
+Introduction
+============
+
+`DirectXShaderCompiler <https://github.com/microsoft/DirectXShaderCompiler>`_
+encapsulates, among other information, various DXIL Operations in
+`hctdb.py <https://github.com/microsoft/DirectXShaderCompiler/blob/main/utils/hct/hctdb.py>`_.
+DXIL Operations are represented in one of the following `two ways
+<https://github.com/microsoft/DirectXShaderCompiler/blob/130877392c263888ef06bab768856d3dab1f1c9a/docs/DXIL.rst#L1978>`_:
+
+#. Using LLVM instructions
+#. Using LLVM External functions. These are represented in LLVM IR as follows:
+
+   * "Standard" LLVM intrinsics (e.g., ``llvm.sin.*``) and
+   * HLSL intrinsics (defined as LLVM intrinsics in ``llvm/include/llvm/IR/IntrinsicsDirectX.td``, e.g., ``llvm.dx.*``)
+
+These are  collectively referred to as `LLVM Intrinsics` in this note.
+
+DXIL Ops, as currently represented in ``hctdb.py`` have the following attributes
+
+#. ``name`` - A short, unique name
+#. ``llvm_id`` - ID of LLVM instruction. This is just an arbitrary, yet fixed, number that indicates LLVM's ``CallInst`` for all LLVM intrinsics
+#. ``llvm_name`` - String name of LLVM instruction type
+#. ``is_dxil_op`` - A bool indicating whether this is a call into a built-in DXIL function
+#. ``dxil_op`` - String name of DXIL operation
+#. ``dxil_opid`` - ID of DXIL operation
+#. ``dxil_class`` - String name of the opcode class
+#. ``category`` - String classification for this instruction
+#. ``doc`` - String documentation description of this instruction
+#. ``remarks`` - String long-form remarks on this instruction
+#. ``ops`` - List of operands that this instruction takes
+#. ``is_allowed`` - Bool indicating whether this instruction is allowed in a DXIL program
+#. ``oload_types`` - String denoting overload types if applicable (e.g., "hf", "iwl")
+#. ``fn_attr`` - Attribute shorthand strings: rn=does not access memory,ro=only reads from memory,
+#. ``is_deriv`` - Bool indicating whether this is some kind of derivative
+#. ``is_gradient`` - Bool indicating whether this requires a gradient calculation
+#. ``is_feedback`` - Bool indicating whether this is a sampler feedback op
+#. ``is_wave``  - Bool indicating whether this requires in-wave, cross-lane functionality
+#. ``requires_uniform_inputs``  - Bool indicating whether this operation requires that all of its inputs are uniform across the wave
+#. ``is_barrier``  - Bool indicating whether this is a barrier operation
+#. ``shader_stages`` - shader stages to which this applies, empty for all.
+#. ``shader_model`` - minimum shader model required (e.g., 6, 0)
+#. ``inst_helper_prefix`` - None
+#. ``fully_qualified_name_prefix`` - Constant string ``"hlsl::OP::OpCode"``
+#. ``is_dxil_op`` - Bool that evaluates (dxil_op != "") indicating whether this is a DXIL operation
+#. ``is_reserved`` - Bool that evaluates (dxil_class == "Reserved")
+#. ``shader_model_translated`` - minimum shader model required with translation by linker
+#. ``props`` - extra properties
+
+Core DXIL Operation information is encapsulated in ``utils/hct/hctdb.py``. Additional
+refinements of this information, such as supported overload types specific to
+Shader Model version, is embedded in various other source locations in
+`DirectXShaderCompiler <https://github.com/microsoft/DirectXShaderCompiler>`_
+repo. Additional conditions that refine the DXIL Op properties are also encoded
+in the DXIL Validator component.
+
+Motivation
+==========
+
+``DXILLowering`` pass needs to lower the LLVM intrinsics. TableGen file -
+``llvm/lib/Target/DirectX/DXIL.td`` - is used to specify the properties of DXIL
+Ops including the mapping of each of them to LLVM intrinsics they correspond to,
+if any. This purpose is served by ``utils/hct/hctdb.py`` in ``DirectXShaderCompiler``
+repo. Analogously, ``DXIL.td`` is planned to be the single source of reference
+for the properties and LLVM intrinsic mapping of DXIL Ops for DXIL backend
+implementation in ``llvm-project`` repo. Additionally, the refinements of DXIL Op
+properties based on aspects such as target Shader Model version, Shader kind (viz.,
+Compute, Pixel, Vertex etc) should also be represented in TableGen specification
+of DXIL Ops - as much as possible. This will allow generation of valid DXIL code
+in all passes and potentially not require (or reduce the complexity of) a post-compile
+validation step that ensures valid DXIL binary.
+
+As a result, specification in ``DXIL.td`` needs to have a rich representation
+abilities that TableGen backends (such as ``DXILEmitter``) can rely on. The DXIL
+Op specification should be declarative - as much as possible - making it
+easy to comprehend and amenable to specification of constraints that refine
+DXIL Op properties.
+
+.. _DXIL Operation Attributes:
+
+DXIL Operation Attributes
+=========================
+
+Distilling the essential attributes of DXIL Op from the above, following
+attributes form the core of its specification.
+
+#. ``dxil_opid`` or ``OpCode``
+#. ``dxil_class`` or ``OpClass`` - this string is an integral part of the DXIL Op
+   function name and is constructed in the format ``dx.op.<class-name>.<overload-type>``.
+   The DXIL validator checks for any deviation from this for each of the DXIL Op call.
+#. ``ops`` - list of operands encapsulating the index and valid (fixed or overload) types
+#. ``oload_types`` - Valid overload types of the DXIL op
+#. Rest of the attributes represented using ``is_*`` booleans along with
+   ``shader_model_translated`` and ``shader_stages``
+
+Each of the LLVM intrinsics maps to an function represented by a call to an
+external function of the form ``dx.op.<class-name>.<overload-type>`` as noted above.
+
+TableGen Specification
+======================
+
+Shader Model
+^^^^^^^^^^^^
+
+DirectX Shader Models are distinguished by their ``major.minor`` number.
+This is represented by the following TableGen class.
+
+.. code-block::
+
+  class DXILShaderModel<int major, int minor> {
+    int MajorAndMinor = !add(!mul(major, 10), minor);
+  }
----------------
bogner wrote:

Combining MajorAndMinor here is confusing (and in fact I see that you've started splitting this into separate fields in #87803 already). Please update to use two fields.

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