cut DXILResources.rst down to just the buffer parts

bogner · bogner · commit c6332c05ad03 · 2024-07-15T13:24:50.000-07:00
A lot of this document is in flux, but it would be helpful to get the
parts we're already working on in tree. To facilitate that, cut out
everything that isn't about handles or buffers.
diff --git a/llvm/docs/DirectX/DXILResources.rst b/llvm/docs/DirectX/DXILResources.rst
@@ -91,28 +91,6 @@ 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
 -------
 
@@ -156,55 +134,6 @@ There are a few fields to describe variants of all of these types:
 .. _rawBufferLoad: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#rawbufferload
 .. _rawBufferStore: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#rawbufferstore
 
-Textures
---------
-
-.. code-block:: llvm
-
-   target("dx.Texture1D", ElementType, IsWriteable, IsROV)
-   target("dx.Texture1DArray", ...)
-   target("dx.Texture2D", ...)
-   target("dx.Texture2DArray", ...)
-   target("dx.Texture3D", ...)
-   target("dx.TextureCUBE", ...)
-   target("dx.TextureCUBEArray", ...)
-
-   target("dx.Texture2DMS", ElementType, IsWriteable, IsROV, SampleCount)
-   target("dx.Texture2DMSArray", ...)
-
-   target("dx.FeedbackTexture2D", ElementType, IsWriteable, IsROV, FeedbackType)
-   target("dx.FeedbackTexture2DArray", ...)
-
-There are a number of texture types, but they are mostly interestingly
-different in their dimensions. These are distinct so that we can overload the
-various sample and texture load/store operations such that their parameters are
-appropriate to the type.
-
-.. list-table:: Texture Fields
-   :header-rows: 1
-
-   * - Field
-     - Description
-   * - ElementType
-     - Type for a single element, such as ``i8``, ``v4f32``, or a structure
-       type.
-   * - IsWriteable
-     - Whether or not the field is writeable. This distinguishes SRVs (not
-       writeable) and UAVs (writeable).
-   * - SampleCount
-     - Sample count for a multisampled texture.
-   * - FeedbackType
-     - Feedback type for a feedback texture.
-
-Raytracing Resources
---------------------
-
-.. code-block:: llvm
-
-   target("dx.RTAccelerationStructure")
-
-.. note:: TODO: Describe RTAccelerationStructure
-
 Resource Operations
 ===================
 
@@ -293,30 +222,6 @@ Examples:
                @llvm.dx.handle.fromBinding.tdx.Buffer_i8_0_0t(
                    i32 1, i32 8, i32 1, i32 0, i1 false)
 
-   ; cbuffer cb0 {
-   ;   float4 g_MaxThreadIter : packoffset(c0);
-   ;   float4 g_Window : packoffset(c1);
-   ; }
-   %cb0 = call target("dx.CBuffer", 32)
-               @llvm.dx.handle.fromBinding.tdx.CBuffer_32t(
-                   i32 0, i32 0, i32 1, i32 0, i1 false)
-
-   ; Texture2D<float4> ColorMapTexture : register(t3);
-   %tex = call target("dx.Texture2D", <4 x f32>, 0, 0)
-               @llvm.dx.handle.fromBinding.tdx.Texture2D_v4f32_0_0t(
-                   i32 0, i32 3, i32 1, i32 0, i1 false)
-
-   ; Texture1D<float4> Buf[5] : register(t3);
-   ; Texture1D<float4> B = Buf[NonUniformResourceIndex(i)];
-   %tex = call target("dx.Texture1D", <4 x f32>, 0, 0)
-               @llvm.dx.handle.fromBinding.tdx.Texture1D_v4f32_0_0t(
-                   i32 0, i32 3, i32 5, i32 %i, i1 true)
-
-   ; SamplerState ColorMapSampler : register(s0);
-   %smp = call target("dx.Sampler", 0)
-               @llvm.dx.handle.fromBinding.tdx.Sampler_0t(
-                   i32 0, i32 0, i32 1, i32 0, i1 false)
-
 .. list-table:: ``@llvm.dx.handle.fromHeap``
    :header-rows: 1
 
@@ -351,28 +256,6 @@ Examples:
                @llvm.dx.handle.fromHeap.tdx.Buffer_v4f32_1_0(
                    i32 2, i1 false)
 
-   ; struct S { float f; };
-   ; ConstantBuffer<S> CB = ResourceDescriptorHeap[0];
-   %cb0 = call target("dx.CBuffer", 4)
-               @llvm.dx.handle.fromBinding.tdx.CBuffer_4t(
-                   i32 0, i1 false)
-
-   ; Texture2D<float4> ColorMapTexture : register(t3);
-   %tex = call target("dx.Texture2D", <4 x f32>, 0, 0)
-               @llvm.dx.handle.fromBinding.tdx.Texture2D_v4f32_0_0t(
-                   i32 0, i1 false)
-
-   ; Texture1D<float4> Buf[5] : register(t3);
-   ; Texture1D<float4> B = Buf[NonUniformResourceIndex(i)];
-   %tex = call target("dx.Texture1D", <4 x f32>, 0, 0)
-               @llvm.dx.handle.fromHeap.tdx.Texture1D_v4f32_0_0t(
-                   i32 %i, i1 true)
-
-   ; SamplerState ColorMapSampler =  ResourceDescriptorHeap[3];
-   %smp = call target("dx.Sampler", 0)
-               @llvm.dx.handle.fromBinding.tdx.Sampler_0t(
-                   i32 3, i1 false)
-
 Buffer Loads and Stores
 -----------------------
 
@@ -583,220 +466,3 @@ Examples:
    call void @llvm.dx.bufferLoad.tdx.Buffer_sl_i32f32f64s_0_0t.f32(
        target("dx.Buffer", {i32, f32}, 0, 0) %buf, i32 %index, i32 1, f32 %data)
 
-Constant Buffer Loads
----------------------
-
-*relevant types: CBuffer*
-
-Loading from constant buffers is relatively straightforward, and we model it
-with a single intrinsic, `llvm.dx.cbufferLoad`. Similarly to how we handle
-``bufferLoad``, we allow the intrinsic to load a scalar or a vector of
-consecutive values as needed.
-
-In DXIL there are two operations that load from a constant buffer -
-`cBufferLoad`_ and ` and `cbufferLoadLegacy`_. These names can be confusing
-because only ``cbufferLoadLegacy`` is widely supported by drivers. The "legacy"
-op loads 16 bytes of data from the buffer, which is generally 4 32-bit values
-or 2 64-bit values, whereas the largely unsupported replacement loads a scalar
-directly. These differences are minor and we can easily lower to either from
-our own generic intrinsic.
-
-.. _cbufferLoadLegacy: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#cbufferloadlegacy
-.. _cbufferLoad: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#cbufferload
-
-.. list-table:: ``@llvm.dx.cbufferLoad``
-   :header-rows: 1
-
-   * - Argument
-     -
-     - Type
-     - Description
-   * - Return value
-     -
-     - The scalar or vector type to load.
-     - Data loaded from the cbuffer.
-   * - ``%cbuffer``
-     - 0
-     - ``target(dx.CBuffer, ...)``
-     - The constant buffer to load from
-   * - ``%offset``
-     - 1
-     - ``i32``
-     - Byte offset to load from
-
-Examples:
-
-.. code-block:: llvm
-
-   %ret = call float @llvm.dx.cbufferLoad.f32.tdx.CBuffer_16t(
-       target("dx.CBuffer", 16) %cbuffer, i32 2)
-   %ret = call <4 x float> @llvm.dx.cbufferLoad.v4f32.tdx.CBuffer_64t(
-       target("dx.CBuffer", 16) %cbuffer, i32 0)
-
-.. note:: TODO: Again, do we need alignment or can we rely on types here?
-
-Texture Load and Store
-----------------------
-
-*relevant types: Textures*
-
-.. note:: TODO: The texture load and store operations in DXIL have *a lot* of
-          parameters, and they use an awkward trick where which ones are valid
-          and which *must* be ``undef`` depends on the texture type. I'd rather
-          not copy that approach.
-
-          We have a few options:
-
-          1. Encode the dimensions into the operation in a way similar to the
-             approach described below in the ``GetDimensions`` section. I
-             showed that approach there because here is a bit less tractable.
-          2. Encode the dimensions as types on the ``dx.Texture`` target type.
-             This gives us uniform structure of the operations at the expense
-             of them being more awkward to work with.
-
-GetDimensions
--------------
-
-*relevant types: All Texture and Buffer types*
-
-.. note:: TODO: This approach needs discussion. See the commentary in texture
-          loads and stores above.
-
-Looking up a resource's dimensions is done via a family of ``GetDimensions``
-intrinsics. The equivalent `DXIL operation <GetDimensions_>`_ returns ``{ i32,
-i32, i32, 32 }`` regardless of which dimensions are relevant for the resource,
-which can be confusing. Instead, we define variants of the form
-``GetDimensions.xyzsm`` where the returned elements are represented by an
-initial:
-
-- ``x`` is width
-- ``y`` is height
-- ``z`` is array size for 1D or 2D arrays, or depth for 3D textures
-- ``s`` is number of samples in a multisampled texture
-- ``m`` is the number of MIP levels in a mipmapped texture
-
-The set of variants is not dynamic - these initials are always specified in
-this order and there are exactly 10 valid configurations.
-
-.. _GetDimensions: https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst#getdimensions
-
-.. list-table:: ``GetDimensions`` variants
-   :header-rows: 1
-
-   * - Variant
-     - Returns
-     - Args
-     - Resource types
-   * - ``GetDimensions.x``
-     - ``i32``
-     - n/a
-     - ``Buffer``, read-only ``Texture1D``
-   * - ``GetDimensions.xm``
-     - ``{i32, i32}``
-     - ``%miplevel``
-     - writeable ``Texture1D``
-   * - ``GetDimensions.xy``
-     - ``{i32, i32}``
-     - n/a
-     - read-only ``Texture2D`` and ``TextureCube``
-   * - ``GetDimensions.xym``
-     - ``{i32, i32, i32}``
-     - ``%miplevel``
-     - writeable ``Texture2D`` and ``TextureCube``
-   * - ``GetDimensions.xyz``
-     - ``{i32, i32, i32}``
-     - n/a
-     - readonly ``Texture2DArray``, ``Texture3D``, ``TextureCubeArray``
-   * - ``GetDimensions.xyzm``
-     - ``{i32, i32, i32, i32}``
-     - ``%miplevel``
-     - writeable ``Texture2DArray``, ``Texture3D``, ``TextureCubeArray``
-   * - ``GetDimensions.xys``
-     - ``{i32, i32, i32}``
-     - n/a
-     - ``Texture2DMS``
-   * - ``GetDimensions.xyzs``
-     - ``{i32, i32, i32, i32}``
-     - n/a
-     - ``Texture2DMSArray``
-
-Examples:
-
-.. code-block:: llvm
-
-   declare i32
-       @llvm.dx.GetDimensions.x.tdx.Buffer_f32_0_0t()
-   declare i32
-       @llvm.dx.GetDimensions.x.tdx.Texture1D_f32_0_0t()
-   declare {i32, i32}
-       @llvm.dx.GetDimensions.xm.tdx.Texture1D_f32_1_0t(i32 %miplevel)
-   declare {i32, i32}
-       @llvm.dx.GetDimensions.xy.tdx.Texture2D_f32_0_0t()
-   declare {i32, i32}
-       @llvm.dx.GetDimensions.xz.tdx.Texture1DArray_f32_0_0t()
-   declare {i32, i32, i32, i32}
-       @llvm.dx.GetDimensions.xyzm.tdx.Texture3D_f32_1_0t(i32 %miplevel)
-   declare {i32, i32, i32, i32}
-       @llvm.dx.GetDimensions.xyzs.tdx.Texture2DMSArray_f32_1_0_1t()
-
-Samples
--------
-
-*relevant types: Textures and Samples*
-
-.. note:: TODO: Describe sampling.
-
-   The following DXIL operations are relevant:
-   - ``Sample``
-   - ``SampleBias``
-   - ``SampleLevel``
-   - ``SampleGrad``
-   - ``SampleCmp``
-   - ``SampleCmpLevelZero``
-
-CalculateLOD
-------------
-
-*relevant types: Textures and Samples*
-
-.. note:: TODO: Describe ``CalculateLOD``.
-
-TextureGather
--------------
-
-*relevant types: Textures and Samples*
-
-.. note:: TODO: Describe ``TextureGather`` and ``TextureGatherCmp``.
-
-Texture2DMSGetSamplePosition
-----------------------------
-
-*relevant types: Texture2DMS and maybe Texture2DMSArray*
-
-.. note:: TODO: Describe ``Texture2DMSGetSamplePosition``
-
-Buffer Update Counter
----------------------
-
-*relevant types: RWStructuredBuffer?*
-
-.. note:: TODO: Describe ``BufferUpdateCounter``
-
-   Note that we need to account for calculating HasCounter, as was mentioned in
-   an earlier TODO.
-
-Atomics
--------
-
-*relevant types: Textures and Buffers*
-
-.. note:: TODO: Describe ``AtomicBinOp`` and ``AtomicCompareExchange``
-
-Reflection Information
-======================
-
-.. note:: TODO: Add some notes on the HLSL variable name and its relationship
-          to reflection.
-
-          Ideally this would boil down to a link to a separate "reflection"
-          document.
