llvm/docs/DirectX/DXILOpTableGenDesign.rst - llvm-project.git - Git at Google

 ==============================================================
 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.

 Following is the complete list of properties of DXIL Ops with the corresponding field name
 as used in ``hctdb.py``. A DXIL Op is represented by a set of associated properties. These
 are categorized into two groups - viz., those that are (1) consumed in DXIL backend passes
 and (2) consumed in other usage scenarios such as validation, DXIL reader, etc.

 A. Properties consumed in DXIL backend passes

    1. Name of operation (``dxil_op``)
    2. The generic or HLSL-specific intrinsic that maps to the operation (``llvm_name``).
    3. Unique Integer ID (``dxil_opid``)
    4. Operation Class signifying the name and function signature of the operation (``dxil_class``).
       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.
    5. List of valid overload types for the operation (``oload_types``).
    6. Required DXIL Version with support for the operation.
    7. A string that documents the operation (``doc``) - This is not strictly necessary but is included
       for readability and documentation of the operation.

 B. Properties consumed in other usage scenarios

    1. Required minimum Shader Model (``shader_model``).
    2. Minimum shader model required with translation by linker (``shader_model_translated``)
    3.  List of shader stages applicable to (``shader_stages``), empty for all.
    4.  Memory access attributes of the operation (``fn_attr``).
    5.  Boolean attributes of operation to indicate if it

        * is some kind of a derivative (``is_derivative``)
        * requires gradient calculation (``is_gradient``)
        * is a sampler feedback (``is_feedback``)
        * requires in-wave, cross-lane functionality (``is_wave``)
        * requires that all of its inputs are uniform across the wave (``requires_uniform_inputs``).
        * is a barrier operation (``is_barrier``).

 Motivation
 ==========

 DXIL backend passes depend on various properties of DXIL Operations. For example, ``DXILLowering``
 pass will need information such as the DXIL operation an LLVM intrinsic is to be lowered to,
 along with valid overload and parameter types etc. The TableGen file -
 ``llvm/lib/Target/DirectX/DXIL.td`` - is used to represent DXIL Operations
 by specifying their properties listed above. ``DXIL.td`` is designed to be the single source
 of reference of DXIL Operations for DXIL backend implementation in ``llvm-project`` repo -
 analogous to ``hctdb.py`` for ``DirectXShadeCompiler`` repo. It needs to have a rich
 representation capabilities that TableGen backends (such as ``DXILEmitter``) can rely on.
 Additionally, the DXIL Op specification should be easy to read and comprehend.

 This note focuses on specification of the set of properties consumed by DXIL backend
 passes identified above in category A. Any of the properties from category B are expected to be
 included as deemed necessary during implementation.

 Design
 ======

 1. Each DXIL Operation is represented as a TableGen record. The name of each of the records
    signifies operation name.
 2. The LLVM Intrinsic that maps to the operation is represented using ``Intrinsic::*``.
 3. The unique operation id is represented by an integer.
 4. DXIL Operation Class is represented as follows

    .. code-block::

         // Abstraction of DXIL Operation class.
         // It encapsulates an associated function signature viz.,
         // returnTy(param1Ty, param2Ty, ...) represented as a list of LLVMTypes.
         // DXIL Ops that belong to a DXILOpClass record the signature of that DXILOpClass

         class DXILOpClass<list<LLVMType> OpSig> {
           list<LLVMType> OpSignature = OpSig;
         }

    Concrete operation classes, such as ``unary`` are defined inheriting from ``DXILOpClass``.
 5. Valid overload types are represented as a list of ``LLVMType``.
 6. Concrete records of DXIL versions and are defined by inheriting from the class

    .. code-block::

         // Abstract class to represent major and minor version values
         class Version<int major, int minor> {
           int Major = major;
           int Minor = minor;
         }

 7. A documentation string for the operation.


 A DXIL Operation is represented by the following TableGen class by encapsulating the various
 TableGen representations of its properties described above.

 .. code-block::

   // Abstraction DXIL Operation
   class DXILOpPropertiesBase {
     int OpCode = 0;                           // Opcode of DXIL Operation
     DXILOpClass OpClass = UnknownOpClass;     // Class of DXIL Operation.
     Intrinsic LLVMIntrinsic = ?;              // LLVM Intrinsic DXIL Operation maps to
     list<LLVMType> OpOverloadTypes = ?; // Valid overload type
                                               // of DXIL Operation
     Version DXILVer = ?;                      // Min DXIL version
     string Doc = "";                          // A short description of the operation
   }


 The following convenience class, definitions of ``unary`` and ``DXVer1_0`` are used to
 illustrate the definitions of ``Sin`` and ``Cos`` operations:

   .. code-block::

       class DXILOpProperties<int opCode,
                     Intrinsic intrinsic,
                     list<LLVMType> overloadTypes,
                     string doc> : DXILOpPropertiesBase {
         int OpCode = opCode;
         Intrinsic LLVMIntrinsic = intrinsic;
         list<LLVMType> OpOverloadTypes = overloadTypes;
         string Doc = doc;
       }

       def unary : DXILOpClass<[llvm_any_ty, LLVMMatchType<0>]>;
       def DXVer1_0 : Version<1, 0>;

       let OpClass = unary, DXILVer = DXVer1_0 in {
         def Cos  : DXILOpProperties<12, int_cos, [llvm_half_ty, llvm_float_ty],
                                    "Returns cosine(theta) for theta in radians.">;
         def Sin  : DXILOpProperties<13, int_sin, [llvm_half_ty, llvm_float_ty],
                                    "Returns sine(theta) for theta in radians.">;
       }

 Summary
 =======

 This note sketches the design of a readable and maintainable TableGen specification of
 DXIL Ops in ``DXIL.td`` intended to serve as a single source of reference for TableGen
 backends (such as ``DXILEmitter``) that generates C++ representations used in DXIL
 backend passes.
	==============================================================
	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.

	Following is the complete list of properties of DXIL Ops with the corresponding field name
	as used in ``hctdb.py``. A DXIL Op is represented by a set of associated properties. These
	are categorized into two groups - viz., those that are (1) consumed in DXIL backend passes
	and (2) consumed in other usage scenarios such as validation, DXIL reader, etc.

	A. Properties consumed in DXIL backend passes

	1. Name of operation (``dxil_op``)
	2. The generic or HLSL-specific intrinsic that maps to the operation (``llvm_name``).
	3. Unique Integer ID (``dxil_opid``)
	4. Operation Class signifying the name and function signature of the operation (``dxil_class``).
	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.
	5. List of valid overload types for the operation (``oload_types``).
	6. Required DXIL Version with support for the operation.
	7. A string that documents the operation (``doc``) - This is not strictly necessary but is included
	for readability and documentation of the operation.

	B. Properties consumed in other usage scenarios

	1. Required minimum Shader Model (``shader_model``).
	2. Minimum shader model required with translation by linker (``shader_model_translated``)
	3. List of shader stages applicable to (``shader_stages``), empty for all.
	4. Memory access attributes of the operation (``fn_attr``).
	5. Boolean attributes of operation to indicate if it

	* is some kind of a derivative (``is_derivative``)
	* requires gradient calculation (``is_gradient``)
	* is a sampler feedback (``is_feedback``)
	* requires in-wave, cross-lane functionality (``is_wave``)
	* requires that all of its inputs are uniform across the wave (``requires_uniform_inputs``).
	* is a barrier operation (``is_barrier``).

	Motivation
	==========

	DXIL backend passes depend on various properties of DXIL Operations. For example, ``DXILLowering``
	pass will need information such as the DXIL operation an LLVM intrinsic is to be lowered to,
	along with valid overload and parameter types etc. The TableGen file -
	``llvm/lib/Target/DirectX/DXIL.td`` - is used to represent DXIL Operations
	by specifying their properties listed above. ``DXIL.td`` is designed to be the single source
	of reference of DXIL Operations for DXIL backend implementation in ``llvm-project`` repo -
	analogous to ``hctdb.py`` for ``DirectXShadeCompiler`` repo. It needs to have a rich
	representation capabilities that TableGen backends (such as ``DXILEmitter``) can rely on.
	Additionally, the DXIL Op specification should be easy to read and comprehend.

	This note focuses on specification of the set of properties consumed by DXIL backend
	passes identified above in category A. Any of the properties from category B are expected to be
	included as deemed necessary during implementation.

	Design
	======

	1. Each DXIL Operation is represented as a TableGen record. The name of each of the records
	signifies operation name.
	2. The LLVM Intrinsic that maps to the operation is represented using ``Intrinsic::*``.
	3. The unique operation id is represented by an integer.
	4. DXIL Operation Class is represented as follows

	.. code-block::

	// Abstraction of DXIL Operation class.
	// It encapsulates an associated function signature viz.,
	// returnTy(param1Ty, param2Ty, ...) represented as a list of LLVMTypes.
	// DXIL Ops that belong to a DXILOpClass record the signature of that DXILOpClass

	class DXILOpClass<list<LLVMType> OpSig> {
	list<LLVMType> OpSignature = OpSig;
	}

	Concrete operation classes, such as ``unary`` are defined inheriting from ``DXILOpClass``.
	5. Valid overload types are represented as a list of ``LLVMType``.
	6. Concrete records of DXIL versions and are defined by inheriting from the class

	.. code-block::

	// Abstract class to represent major and minor version values
	class Version<int major, int minor> {
	int Major = major;
	int Minor = minor;
	}

	7. A documentation string for the operation.


	A DXIL Operation is represented by the following TableGen class by encapsulating the various
	TableGen representations of its properties described above.

	.. code-block::

	// Abstraction DXIL Operation
	class DXILOpPropertiesBase {
	int OpCode = 0; // Opcode of DXIL Operation
	DXILOpClass OpClass = UnknownOpClass; // Class of DXIL Operation.
	Intrinsic LLVMIntrinsic = ?; // LLVM Intrinsic DXIL Operation maps to
	list<LLVMType> OpOverloadTypes = ?; // Valid overload type
	// of DXIL Operation
	Version DXILVer = ?; // Min DXIL version
	string Doc = ""; // A short description of the operation
	}


	The following convenience class, definitions of ``unary`` and ``DXVer1_0`` are used to
	illustrate the definitions of ``Sin`` and ``Cos`` operations:

	.. code-block::

	class DXILOpProperties<int opCode,
	Intrinsic intrinsic,
	list<LLVMType> overloadTypes,
	string doc> : DXILOpPropertiesBase {
	int OpCode = opCode;
	Intrinsic LLVMIntrinsic = intrinsic;
	list<LLVMType> OpOverloadTypes = overloadTypes;
	string Doc = doc;
	}

	def unary : DXILOpClass<[llvm_any_ty, LLVMMatchType<0>]>;
	def DXVer1_0 : Version<1, 0>;

	let OpClass = unary, DXILVer = DXVer1_0 in {
	def Cos : DXILOpProperties<12, int_cos, [llvm_half_ty, llvm_float_ty],
	"Returns cosine(theta) for theta in radians.">;
	def Sin : DXILOpProperties<13, int_sin, [llvm_half_ty, llvm_float_ty],
	"Returns sine(theta) for theta in radians.">;
	}

	Summary
	=======

	This note sketches the design of a readable and maintainable TableGen specification of
	DXIL Ops in ``DXIL.td`` intended to serve as a single source of reference for TableGen
	backends (such as ``DXILEmitter``) that generates C++ representations used in DXIL
	backend passes.