[llvm] [DXIL][Doc] Update specification of to use TableGen list instead of dag (PR #99055)
Justin Bogner via llvm-commits
llvm-commits at lists.llvm.org
Mon Jul 22 11:37:48 PDT 2024
================
@@ -172,112 +177,272 @@ 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 DXILShaderStage;
-A constraint class to represent overload types and shader stages predicated on shader
-model version is defined as
+ def compute : DXILShaderStage;
+ def pixel : DXILShaderStage;
+ def vertex : DXILShaderStage;
+ ...
+
+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;
-The ``dag overload_types`` and ``dag shader_kinds`` use a special markers ``overloads``
-and ``stages``, respectively.
+ def ReadOnly : DXILOpAttributes;
+ def ReadNone : DXILOpAttributes;
+ def IsWave : DXILOpAttributes;
+ ...
-Examples of Constraints
------------------------
+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
+---------------------------
-Consider a DXIL Operation that is valid in Shader Model 6.2 and later,
+``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::
-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
+ class VersionedOverloads<Version minver, list<LLVMType> ols> {
+ Version dxil_version = minver;
+ list<LLVMType> overload_types = ols;
+ }
-This is represented as
+Following is an example specification of valid overload types for ``DXIL1_0`` and
+``DXIL1_2``.
.. 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)>];
+ 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 version 6.2 and later,
-1. with no overload types, i.e., all argument typess and result type are fixed.
-2. is valid for all stages.
+Stages Specification
+--------------------
-This is represented as
+``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::
- [SMVersionConstraints<SMVersion<SM6_2>, (overloads), (stages allKinds)>];
+ class VersionedStages<Version minver, list<DXILShaderStage> sts> {
+ Version dxil_version = minver;
+ list<DXILShaderStage> shader_stages = sts;
+ }
+Following is an example specification of valid stages for ``DXIL1_0``,
+``DXIL1_2``, ``DXIL1_4`` and ``DXIL1_6``.
+
+.. code-block::
+
+ stages = [
+ VersionedStages<DXIL1_0, [compute, pixel]>,
+ VersionedStages<DXIL1_2, [compute, pixel, mesh]>,
+ VersionedStages<DXIL1_4, [all_stages]>,
+ VersionedStages<DXIL1_6, [removed]>
+ ];
+
+The following two pseudo stage records in addition to standard shader stages
+are defined.
+
+1. ``all_stages`` signifies that the operation is valid for all stages in the
+ specified DXIL version and later.
+2. ``removed`` signifies removal of support for the operation in the specified
+ DXIL version and later.
+
+A non-empty list of supported stages is required to be specified. If an operation
+is supported in all DXIL versions and all stages it is required to be specified as
+
+.. code-block::
+
+ stages = [VersionedStages<DXIL1_0, [all_stages]>];
-Specifying attributes predicated on Shader Model version using the single field
-``sm_constraints`` not only allows for all of them to be specified together but
-also allows for a single place to specify minimum shader model version that supports
-the operation. Thus, a separate fiels is not needed to specify minimum shader model
-version.
Attribute Specification
-=======================
+-----------------------
-DXIL Operation attributes that are not predicated on any constraint, are represented as
-a ``dag`` of Attribute records of the following abstract ``DXILAttributes`` class.
+``attributes`` field of ``class DXILOp`` is used to represent valid operation
+attributes predicated on DXIL version as list of records of the following class
.. code-block::
- class DXILAttributes;
+ class VersionedAttributes<MinVersion minver, list<DXILAttribute> attrs> {
+ MinVersion dxil_version = ver;
+ list<DXILAttribute> attributes = attrs;
+ }
-Following example records represent memory attributes
+Following is an example specification of valid attributes for ``DXIL1_0``.
.. code-block::
- def ReadOnly : DXILOpAttributes;
- def ReadNone : DXILOpAttributes;
+ attributes = [VersionedAttributes<DXIL1_0, [ReadNone]];
+
+A null list of ``attributes`` signifies no operation attributes.
-DXIL Operation Specification Example
-====================================
-Following illustrates the specification of the DXIL Op ``Sin``
+Interpretation of Multiple Constraint Specification
+---------------------------------------------------
+
+Each of the constraints states that the specified overload type, stage or
+attribute records are valid for the predicated DXIL version. Only
+the constraints corresponding to latest minimal DXIL version is applicable.
+Note as in the above example, any overload types, stages or attributes,
+that remain valid in a later DXIL version need to be specified in full.
+For example, consider the following specification of valid overload types:
.. code-block::
- def Sin : DXILOp {
- let Doc ="Returns sine(theta) for theta in radians.";
- let OpCode = 13;
- let OpClass = unary;
+ overloads = [
+ VersionedOverloads<DXIL1_0, [halfTy, floatTy]>,
+ VersionedOverloads<DXIL1_2, [halfTy, floatTy, doubleTy]>
+ ];
+
+It specifies that the overload types ``halfTy`` and ``floatTy`` are valid for DXIL
+version 1.0 and later. It also specifies that ``doubleTy`` is additionally supported
+in DXIL version 1.2 and later.
+
+This provides the flexibility to specify constraints independent
+of others in the list.
+
+
+DXIL Operation Specification Examples
+=====================================
+
+Following examples illustrate the specification of some of the DXIL Ops.
+
+``Sin`` operation - an operation valid in all DXIL versions and all stages
+and has valid overload types predicated on DXIL version.
+
+.. code-block::
+
+ def Sin : DXILOp<13, unary> {
+ let Doc = "Returns sine(theta) for theta in radians.";
let LLVMIntrinsic = int_sin;
- let arguments = (ins LLVMMatchType<0>);
- let result = (out dxil_overload_ty);
- let sm_constraints = [SMVersionConstraints<SMVersion<SM6_0>,
- (overloads llvm_half_ty, llvm_float_ty),
- (stages allKinds)>];
- let attributes = (attrs ReadNone);
- let DXILVersion = DX1_0;
+ let result = overloadTy;
+ let arguments = [overloadTy];
+ let overloads = [VersionedOverloads<DXIL1_0, [halfTy, floatTy]>];
+ let stages = [VersionedStages<DXIL1_0, [all_stages]>];
+ let attributes = [VersionedAttributes<DXIL1_0, [ReadNone]>];
}
+``FlattenedThreadIdInGroup`` - an operation with no arguments, no
+overload types, and valid stages and attributes predicated by DXIL Version.
+
+.. code-block::
+
+ def FlattenedThreadIdInGroup : DXILOp<96, flattenedThreadIdInGroup> {
+ let Doc = "Provides a flattened index for a given thread within a given "
+ "group (SV_GroupIndex)";
+ let LLVMIntrinsic = int_dx_flattened_thread_id_in_group;
+ let result = i32Ty;
+ let stages = [VersionedStages<DXIL1_0, [compute, mesh, amplification, node]>];
+ let attributes = [VersionedAttributes<DXIL1_0, [ReadNone]>];
+ }
+
+``RawBufferStore`` - an operation with ``void`` return type, valid overload types
+predicated by DXIL Version and valid in all DXIL versions and stages.
+
+.. code-block::
+
+ def RawBufferStore : DXILOp<140, rawBufferStore> {
+ let Doc = "Writes to a RWByteAddressBuffer or RWStructuredBuffer.";
+ let result = voidTy;
+ let arguments = [dxil_resource_ty, i32Ty, i32Ty, overloadTy,
+ overloadTy, overloadTy, overloadTy, i8Ty, i32Ty];
+ let overloads = [
+ VersionedOverloads<DXIL1_2, [halfTy, floatTy, i16Ty, i32Ty]>,
+ VersionedOverloads<DXIL1_3>,[halfTy, floatTy, doubleTy,
+ i16Ty, i32Ty, i64Ty]>
+ ];
+ let stages = [VersionedStages<DXIL1_2, all_stages>];
+ let attributes = [VersionedAttributes<DXIL1_0, [ReadOnly]>];
+ }
+
+``DerivCoarseX`` - an operation with no overload types and stages predicated
+by DXIL Version.
+
+.. code-block::
+
+ def DerivCoarseX : DXILOp<83, unary> {
+ let doc = "Computes the rate of change per stamp in x direction.";
+ let LLVMIntrinsic = int_dx_ddx;
+ let result = overloadTy;
+ let arguments = [overloadTy];
+ let stages = [
+ Versioned<DXIL1_0, [library, pixel]>,
+ Versioned<DXIL1_6, [library, pixel, amplification, compute, mesh]>
----------------
bogner wrote:
Please make sure the examples are all consistent with the naming described above. These ones have the "Versioned<...>" from an earlier iteration.
https://github.com/llvm/llvm-project/pull/99055
More information about the llvm-commits
mailing list