[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an + index into a dynamic resource heap. + + In LLVM we represent binding information in the arguments of the python3kgae wrote: So clang codeGen will not create metadata which saves resource binding? Because the binding information is in createHandleFromBinding? https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an damyanp wrote: what is a "binding space"? https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
damyanp wrote:
> The sample type is an enum value from the DXIL ABI
Do we want to tie this so closely to the DXIL ABI? Would an extra level of
indirection here allow LLVM and DXIL to evolve independently?
https://github.com/llvm/llvm-project/pull/90553
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+"dx.CBufferLoad" and "dx.CBufferLoadLegacy" operations.
damyanp wrote:
> "dx.CBufferLoad"
Didn't we just remove support for this from DXC? (I may be misunderstanding
things)
https://github.com/llvm/llvm-project/pull/90553
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+"dx.CBufferLoad" and "dx.CBufferLoadLegacy" operations.
+
+Buffers
+---
+
+.. code-block:: llvm
+
+ target("dx.Buffer", ElementType, IsWriteable, IsROV)
+
+There is only one buffer type. This can represent both UAVs and SRVs via the
+``IsWriteable`` field. Since the type that's encoded is an llvm type, it
+handles both ``Buffer`` and ``StructuredBuffer`` uniformly. For ``RawBuffer``,
+the type is ``i8``, which is unambiguous since ``char
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+"dx.CBufferLoad" and "dx.CBufferLoadLegacy" operations.
+
+Buffers
+---
+
+.. code-block:: llvm
+
+ target("dx.Buffer", ElementType, IsWriteable, IsROV)
+
+There is only one buffer type. This can represent both UAVs and SRVs via the
+``IsWriteable`` field. Since the type that's encoded is an llvm type, it
+handles both ``Buffer`` and ``StructuredBuffer`` uniformly. For ``RawBuffer``,
+the type is ``i8``, which is unambiguous since ``char
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+"dx.CBufferLoad" and "dx.CBufferLoadLegacy" operations.
+
+Buffers
+---
+
+.. code-block:: llvm
+
+ target("dx.Buffer", ElementType, IsWriteable, IsROV)
+
+There is only one buffer type. This can represent both UAVs and SRVs via the
+``IsWriteable`` field. Since the type that's encoded is an llvm type, it
+handles both ``Buffer`` and ``StructuredBuffer`` uniformly. For ``RawBuffer``,
+the type is ``i8``, which is unambiguous since ``char
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an + index into a dynamic resource heap. + + In LLVM we represent binding information in the arguments of the bogner wrote: Yes. The information in the metadata in DXIL is represented in the create handle calls and target types. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an bogner wrote: It's the "space" in `register(t3, space0)`. From https://learn.microsoft.com/en-us/windows/win32/direct3d12/resource-binding-in-hlsl: > The space keyword specifies to which logical register space the declared > variable is bound. If the space keyword is omitted, then the default space > index of 0 is implicitly assigned to the range (so the tex2 range above > resides in space0). register(t3, space0) will never conflict with > register(t3, space1), nor with any array in another space that might include > t3. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+"dx.CBufferLoad" and "dx.CBufferLoadLegacy" operations.
bogner wrote:
Not exactly, but this isn't the right place to discuss the legacy operation. I
touch on it briefly in the "Constant Buffer Loads" section and I've updated
this part to just mention `llvm.dx.cbufferLoad`
https://github.com/llvm/llvm-project/pull/90553
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+"dx.CBufferLoad" and "dx.CBufferLoadLegacy" operations.
+
+Buffers
+---
+
+.. code-block:: llvm
+
+ target("dx.Buffer", ElementType, IsWriteable, IsROV)
+
+There is only one buffer type. This can represent both UAVs and SRVs via the
+``IsWriteable`` field. Since the type that's encoded is an llvm type, it
+handles both ``Buffer`` and ``StructuredBuffer`` uniformly. For ``RawBuffer``,
+the type is ``i8``, which is unambiguous since ``char
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an damyanp wrote: I've always called those "register spaces" (and it seems that's what the linked doc calls them as well). https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+"dx.CBufferLoad" and "dx.CBufferLoadLegacy" operations.
+
+Buffers
+---
+
+.. code-block:: llvm
+
+ target("dx.Buffer", ElementType, IsWriteable, IsROV)
+
+There is only one buffer type. This can represent both UAVs and SRVs via the
+``IsWriteable`` field. Since the type that's encoded is an llvm type, it
+handles both ``Buffer`` and ``StructuredBuffer`` uniformly. For ``RawBuffer``,
+the type is ``i8``, which is unambiguous since ``char
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an damyanp wrote: If we want to use some different nomenclature for this here then I think it's probably worth explaining that. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an bogner wrote: It's called "bind space" in https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#metadata-resource-records for whatever reason. I can update to use register space instead, as I do think that's more common. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ binding space, lower bound in that space, and size of the binding, or (b) an
+ index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
bogner wrote:
Other than a different but very similar enum I'm not sure how we would abstract
this. FWIW, the set of sampler types is pretty small:
```c++
enum class SamplerKind : unsigned {
Default = 0,
Comparison,
Mono,
Invalid,
};
```
https://github.com/llvm/llvm-project/pull/90553
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,794 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ register space, lower bound in that space, and size of the binding, or (b)
+ an index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
python3kgae wrote:
Why not save the type like the dx.Buffer but a BufferSize?
For cbuffer we'll create a dummy struct to cache the layout, for
ConstantBuffer<> case, the element type is already there.
https://github.com/llvm/llvm-project/pull/90553
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an + index into a dynamic resource heap. + + In LLVM we represent binding information in the arguments of the python3kgae wrote: How does an array of resources work? Always initialize the first element with createHandleFromBinding in clang codeGen to make sure the binding is saved? https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
https://github.com/bogner edited https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,794 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ register space, lower bound in that space, and size of the binding, or (b)
+ an index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
bogner wrote:
Removed the cbuffer stuff from this doc for now. There are a couple of trade
offs on how to represent the type in a cbuffer, but just using an LLVM type
doesn't seem optimal since the mapping between types and cbuffer layout is a
bit complicated.
https://github.com/llvm/llvm-project/pull/90553
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,794 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ register space, lower bound in that space, and size of the binding, or (b)
+ an index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+``llvm.dx.cbufferLoad`` operation.
+
+Buffers
+---
+
+.. code-block:: llvm
+
+ target("dx.Buffer", ElementType, IsWriteable, IsROV)
+
+There is only one buffer type. This can represent both UAVs and SRVs via the
+``IsWriteable`` field. Since the type that's encoded is an llvm type, it
+handles both ``Buffer`` and ``StructuredBuffer`` uniformly. For ``RawBuffer``,
+the type is ``i8``, which is unambiguous since ``char`` isn't a legal typ
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,794 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ register space, lower bound in that space, and size of the binding, or (b)
+ an index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Samplers
+
+
+.. code-block:: llvm
+
+ target("dx.Sampler", SamplerType)
+
+The "dx.Sampler" type is used to represent sampler state. The sampler type is
+an enum value from the DXIL ABI, and these appear in sampling operations as
+well as LOD calculations and texture gather.
+
+Constant Buffers
+
+
+.. code-block:: llvm
+
+ target("dx.CBuffer", BufferSize)
+
+The "dx.CBuffer" type is a constant buffer of the given size. Note that despite
+the name this is distinct from the buffer types, and can only be read using the
+``llvm.dx.cbufferLoad`` operation.
+
+Buffers
+---
+
+.. code-block:: llvm
+
+ target("dx.Buffer", ElementType, IsWriteable, IsROV)
+
+There is only one buffer type. This can represent both UAVs and SRVs via the
+``IsWriteable`` field. Since the type that's encoded is an llvm type, it
+handles both ``Buffer`` and ``StructuredBuffer`` uniformly. For ``RawBuffer``,
+the type is ``i8``, which is unambiguous since ``char`` isn't a legal typ
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,799 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + binding space, lower bound in that space, and size of the binding, or (b) an + index into a dynamic resource heap. + + In LLVM we represent binding information in the arguments of the bogner wrote: Yeah, arrays of resources will be handled similarly to how they're handled in dxc where the binding's size tells us the information we need. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
https://github.com/bogner ready_for_review https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
llvmbot wrote: @llvm/pr-subscribers-backend-directx Author: Justin Bogner (bogner) Changes This adds a new document about DXIL Resource Handling. I've attempted to describe here how we intend to use TargetExtTypes to represent resources in LLVM IR and the various intrinsics we'll need to lower these through LLVM to DXIL. For now this document is limited to the high level concepts and a few details on buffer types, and there are a number of TODOs in the document that we'll iterate on as we progress in the implementation. --- Full diff: https://github.com/llvm/llvm-project/pull/90553.diff 4 Files Affected: - (modified) clang/docs/HLSL/HLSLIRReference.rst (-9) - (modified) clang/docs/HLSL/ResourceTypes.rst (+4-3) - (added) llvm/docs/DirectX/DXILResources.rst (+468) - (modified) llvm/docs/DirectXUsage.rst (+2-1) ``diff diff --git a/clang/docs/HLSL/HLSLIRReference.rst b/clang/docs/HLSL/HLSLIRReference.rst index c0d8d33f33bff..c0033946a6ec8 100644 --- a/clang/docs/HLSL/HLSLIRReference.rst +++ b/clang/docs/HLSL/HLSLIRReference.rst @@ -11,15 +11,6 @@ Introduction The goal of this document is to provide a reference for all the special purpose IR metadata and attributes used by the HLSL code generation path. -IR Metadata -=== - -``hlsl.uavs`` -- - -The ``hlsl.uavs`` metadata is a list of all the external global variables that -represent UAV resources. - Function Attributes === diff --git a/clang/docs/HLSL/ResourceTypes.rst b/clang/docs/HLSL/ResourceTypes.rst index aad7b3314f084..0d461ba3ee707 100644 --- a/clang/docs/HLSL/ResourceTypes.rst +++ b/clang/docs/HLSL/ResourceTypes.rst @@ -29,6 +29,7 @@ pointer of the template parameter type. The pointer is populated from a call to data through until lowering in the backend. Resource types are annotated with the ``HLSLResource`` attribute, which drives -code generation for resource binding metadata. The ``hlsl`` metadata nodes are -transformed in the backend to the binding information expected by the target -runtime. +code generation into target extension types in IR. These types are target +specific and differ between DXIL and SPIR-V generation, providing the necessary +information for the targets to generate binding metadata for their respective +target runtimes. diff --git a/llvm/docs/DirectX/DXILResources.rst b/llvm/docs/DirectX/DXILResources.rst new file mode 100644 index 0..b7ea478373f50 --- /dev/null +++ b/llvm/docs/DirectX/DXILResources.rst @@ -0,0 +1,468 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + register space, lower bound in that space, and size of the binding, or (b) + an index into a dynamic resource heap. + + In LLVM we represent binding information in the arguments of the + :ref:`handle creation intrinsics `. When generating + DXIL we transform these calls to metadata, ``dx.op.createHandle``, + ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and + ``dx.op.createHandleForLib`` as needed. + +`Type information` + The type of data that's accessible via the resource. For buffers and + textures this can be a simple type like ``float`` or ``float4``, a struct, + or raw bytes. For constant buffers this is just a size. For samplers this is + the kind of sampler. + + In LLVM we embed this information as a parameter on the ``target()`` type of + the resource. See :ref:`dxil-resources-types-of-resource`. + +`Resource kind information` + The kind of resource. In HLSL we have things like ``ByteAddressBuffer``, + ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
llvmbot wrote: @llvm/pr-subscribers-clang @llvm/pr-subscribers-hlsl Author: Justin Bogner (bogner) Changes This adds a new document about DXIL Resource Handling. I've attempted to describe here how we intend to use TargetExtTypes to represent resources in LLVM IR and the various intrinsics we'll need to lower these through LLVM to DXIL. For now this document is limited to the high level concepts and a few details on buffer types, and there are a number of TODOs in the document that we'll iterate on as we progress in the implementation. --- Full diff: https://github.com/llvm/llvm-project/pull/90553.diff 4 Files Affected: - (modified) clang/docs/HLSL/HLSLIRReference.rst (-9) - (modified) clang/docs/HLSL/ResourceTypes.rst (+4-3) - (added) llvm/docs/DirectX/DXILResources.rst (+468) - (modified) llvm/docs/DirectXUsage.rst (+2-1) ``diff diff --git a/clang/docs/HLSL/HLSLIRReference.rst b/clang/docs/HLSL/HLSLIRReference.rst index c0d8d33f33bff..c0033946a6ec8 100644 --- a/clang/docs/HLSL/HLSLIRReference.rst +++ b/clang/docs/HLSL/HLSLIRReference.rst @@ -11,15 +11,6 @@ Introduction The goal of this document is to provide a reference for all the special purpose IR metadata and attributes used by the HLSL code generation path. -IR Metadata -=== - -``hlsl.uavs`` -- - -The ``hlsl.uavs`` metadata is a list of all the external global variables that -represent UAV resources. - Function Attributes === diff --git a/clang/docs/HLSL/ResourceTypes.rst b/clang/docs/HLSL/ResourceTypes.rst index aad7b3314f084..0d461ba3ee707 100644 --- a/clang/docs/HLSL/ResourceTypes.rst +++ b/clang/docs/HLSL/ResourceTypes.rst @@ -29,6 +29,7 @@ pointer of the template parameter type. The pointer is populated from a call to data through until lowering in the backend. Resource types are annotated with the ``HLSLResource`` attribute, which drives -code generation for resource binding metadata. The ``hlsl`` metadata nodes are -transformed in the backend to the binding information expected by the target -runtime. +code generation into target extension types in IR. These types are target +specific and differ between DXIL and SPIR-V generation, providing the necessary +information for the targets to generate binding metadata for their respective +target runtimes. diff --git a/llvm/docs/DirectX/DXILResources.rst b/llvm/docs/DirectX/DXILResources.rst new file mode 100644 index 0..b7ea478373f50 --- /dev/null +++ b/llvm/docs/DirectX/DXILResources.rst @@ -0,0 +1,468 @@ +== +DXIL Resource Handling +== + +.. contents:: + :local: + +.. toctree:: + :hidden: + +Introduction + + +Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and +eventually lowered by the DirectX backend into metadata in DXIL. + +In DXC and DXIL, static resources are represented as lists of SRVs (Shader +Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and +Samplers. This metadata consists of a "resource record ID" which uniquely +identifies a resource and type information. As of shader model 6.6, there are +also dynamic resources, which forgo the metadata and are described via +``annotateHandle`` operations in the instruction stream instead. + +In LLVM we attempt to unify some of the alternative representations that are +present in DXC, with the aim of making handling of resources in the middle end +of the compiler simpler and more consistent. + +Resource Type Information and Properties + + +There are a number of properties associated with a resource in DXIL. + +`Resource ID` + An arbitrary ID that must be unique per resource type (SRV, UAV, etc). + + In LLVM we don't bother representing this, instead opting to generate it at + DXIL lowering time. + +`Binding information` + Information about where the resource comes from. This is either (a) a + register space, lower bound in that space, and size of the binding, or (b) + an index into a dynamic resource heap. + + In LLVM we represent binding information in the arguments of the + :ref:`handle creation intrinsics `. When generating + DXIL we transform these calls to metadata, ``dx.op.createHandle``, + ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and + ``dx.op.createHandleForLib`` as needed. + +`Type information` + The type of data that's accessible via the resource. For buffers and + textures this can be a simple type like ``float`` or ``float4``, a struct, + or raw bytes. For constant buffers this is just a size. For samplers this is + the kind of sampler. + + In LLVM we embed this information as a parameter on the ``target()`` type of + the resource. See :ref:`dxil-resources-types-of-resource`. + +`Resource kind information` + The kind of resource. In HLSL we have things like ``ByteAddressBuffer``, + ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
https://github.com/damyanp edited https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
https://github.com/damyanp approved this pull request. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -29,6 +29,7 @@ pointer of the template parameter type. The pointer is populated from a call to data through until lowering in the backend. Resource types are annotated with the ``HLSLResource`` attribute, which drives -code generation for resource binding metadata. The ``hlsl`` metadata nodes are -transformed in the backend to the binding information expected by the target -runtime. +code generation into target extension types in IR. These types are target +specific and differ between DXIL and SPIR-V generation, providing the necessary +information for the targets to generate binding metadata for their respective +target runtimes. damyanp wrote: I think that this needs to be reconciled with #98419? https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -29,6 +29,7 @@ pointer of the template parameter type. The pointer is populated from a call to data through until lowering in the backend. Resource types are annotated with the ``HLSLResource`` attribute, which drives -code generation for resource binding metadata. The ``hlsl`` metadata nodes are -transformed in the backend to the binding information expected by the target -runtime. +code generation into target extension types in IR. These types are target +specific and differ between DXIL and SPIR-V generation, providing the necessary +information for the targets to generate binding metadata for their respective +target runtimes. bogner wrote: Good point. I've updated this doc to talk about `__hlsl_resource_t` and to talk about the set of resource attributes more generically. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
bogner wrote: Just noticed that this was missing the change I had locally for updating the load and store operations to reflect the two different buffer types. I've pushed that in the latest update. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
@@ -0,0 +1,425 @@
+==
+DXIL Resource Handling
+==
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+Introduction
+
+
+Resources in DXIL are represented via ``TargetExtType`` in LLVM IR and
+eventually lowered by the DirectX backend into metadata in DXIL.
+
+In DXC and DXIL, static resources are represented as lists of SRVs (Shader
+Resource Views), UAVs (Uniform Access Views), CBVs (Constant Bffer Views), and
+Samplers. This metadata consists of a "resource record ID" which uniquely
+identifies a resource and type information. As of shader model 6.6, there are
+also dynamic resources, which forgo the metadata and are described via
+``annotateHandle`` operations in the instruction stream instead.
+
+In LLVM we attempt to unify some of the alternative representations that are
+present in DXC, with the aim of making handling of resources in the middle end
+of the compiler simpler and more consistent.
+
+Resource Type Information and Properties
+
+
+There are a number of properties associated with a resource in DXIL.
+
+`Resource ID`
+ An arbitrary ID that must be unique per resource type (SRV, UAV, etc).
+
+ In LLVM we don't bother representing this, instead opting to generate it at
+ DXIL lowering time.
+
+`Binding information`
+ Information about where the resource comes from. This is either (a) a
+ register space, lower bound in that space, and size of the binding, or (b)
+ an index into a dynamic resource heap.
+
+ In LLVM we represent binding information in the arguments of the
+ :ref:`handle creation intrinsics `. When generating
+ DXIL we transform these calls to metadata, ``dx.op.createHandle``,
+ ``dx.op.createHandleFromBinding``, ``dx.op.createHandleFromHeap``, and
+ ``dx.op.createHandleForLib`` as needed.
+
+`Type information`
+ The type of data that's accessible via the resource. For buffers and
+ textures this can be a simple type like ``float`` or ``float4``, a struct,
+ or raw bytes. For constant buffers this is just a size. For samplers this is
+ the kind of sampler.
+
+ In LLVM we embed this information as a parameter on the ``target()`` type of
+ the resource. See :ref:`dxil-resources-types-of-resource`.
+
+`Resource kind information`
+ The kind of resource. In HLSL we have things like ``ByteAddressBuffer``,
+ ``RWTexture2D``, and ``RasterizerOrderedStructuredBuffer``. These map to a
+ set of DXIL kinds like ``RawBuffer`` and ``Texture2D`` with fields for
+ certain properties such as ``IsUAV`` and ``IsROV``.
+
+ In LLVM we represent this in the ``target()`` type. We omit information
+ that's deriveable from the type information, but we do have fields to encode
+ ``IsWriteable``, ``IsROV``, and ``SampleCount`` when needed.
+
+.. note:: TODO: There are two fields in the DXIL metadata that are not
+ represented as part of the target type: ``IsGloballyCoherent`` and
+ ``HasCounter``.
+
+ Since these are derived from analysis, storing them on the type would mean
+ we need to change the type during the compiler pipeline. That just isn't
+ practical. It isn't entirely clear to me that we need to serialize this info
+ into the IR during the compiler pipeline anyway - we can probably get away
+ with an analysis pass that can calculate the information when we need it.
+
+ If analysis is insufficient we'll need something akin to ``annotateHandle``
+ (but limited to these two properties) or to encode these in the handle
+ creation.
+
+.. _dxil-resources-types-of-resource:
+
+Types of Resource
+=
+
+We define a set of ``TargetExtTypes`` that is similar to the HLSL
+representations for the various resources, albeit with a few things
+parameterized. This is different than DXIL, as simplifying the types to
+something like "dx.srv" and "dx.uav" types would mean the operations on these
+types would have to be overly generic.
+
+Buffers
+---
+
+.. code-block:: llvm
+
+ target("dx.TypedBuffer", ElementType, IsWriteable, IsROV)
+ target("dx.RawBuffer", ElementType, IsWriteable, IsROV)
+
+We need two separate buffer types to account for the differences between the
+16-byte `bufferLoad`_ / `bufferStore`_ operations that work on DXIL's
+TypedBuffers and the `rawBufferLoad`_ / `rawBufferStore`_ operations that are
+used for DXIL's RawBuffers and StructuredBuffers. We call the latter
+"RawBuffer" to match the naming of the operations, but it can represent both
+the Raw and Structured variants.
+
+For TypedBuffer, the element type must be an integer or floating point type.
+For RawBuffer the type can be an integer, floating point, or struct type.
+HLSL's ByteAddressBuffer is represented by an `i8` element type.
+
+These types are generally used by BufferLoad and BufferStore operations, as
+well as atomics.
+
+There are a few fields to describe variants of all of these types:
+
+.. list-table:: Buffer Fields
+
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
https://github.com/llvm-beanz approved this pull request. https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] [llvm] [DirectX] Start documenting DXIL Resource handling (PR #90553)
https://github.com/bogner closed https://github.com/llvm/llvm-project/pull/90553 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
