Skip to content

[NFC] Update Shader Flags section of DXIL.rst #7295

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

[NFC] Update Shader Flags section of DXIL.rst #7295

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
03d8c6a
Update Shader Flags documentation
Icohedron Apr 1, 2025
42ca0a3
Match feature info names in dxcdisassembler.cpp where it makes sense
Icohedron Apr 2, 2025
3421eb2
Correct Raster Ordered UAVs criteria. Correct Disable shader optimiza…
Icohedron Apr 2, 2025
aeca9eb
Fix wording for ROV flag criteria
Icohedron Apr 2, 2025
6fb8317
Update criteria for setting the m_bResMayNotAlias flag
Icohedron Apr 22, 2025
8030ce8
Correct the criteria used to set shader flag 16 (UAVs at every shader…
Icohedron Apr 22, 2025
cfe435b
Correct criteria used to set shader flag 15 (64 UAV slots)
Icohedron Apr 22, 2025
17ecebc
Update flag descriptions to match DXContainerConstants.def in LLVM
Icohedron Jun 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 46 additions & 27 deletions docs/DXIL.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,33 +515,52 @@ Additional shader properties are specified via tag-value pair list, which is the
Shader Flags
------------

Shaders have additional flags that covey their capabilities via tag-value pair with tag kDxilShaderFlagsTag (0), followed by an i64 bitmask integer. The bits have the following meaning:

=== =====================================================================
Bit Description
=== =====================================================================
0 Disable shader optimizations
1 Disable math refactoring
2 Shader uses doubles
3 Force early depth stencil
4 Enable raw and structured buffers
5 Shader uses min-precision, expressed as half and i16
6 Shader uses double extension intrinsics
7 Shader uses MSAD
8 All resources must be bound for the duration of shader execution
9 Enable view port and RT array index from any stage feeding rasterizer
10 Shader uses inner coverage
11 Shader uses stencil
12 Shader uses intrinsics that access tiled resources
13 Shader uses relaxed typed UAV load formats
14 Shader uses Level9 comparison filtering
15 Shader uses up to 64 UAVs
16 Shader uses UAVs
17 Shader uses CS4 raw and structured buffers
18 Shader uses Rasterizer Ordered Views
19 Shader uses wave intrinsics
20 Shader uses int64 instructions
=== =====================================================================
Shaders have additional flags that convey their capabilities via a tag-value pair with tag kDxilShaderFlagsTag (0), followed by an i64 bitmask integer. The bits have the following meaning, Shader Model requirements, and criteria for being set:

=== ==== ======================================================================================== ==========================================================================================================================================================================================================================================================================================================================================================
Bit SM Description Criteria to set shader flag
=== ==== ======================================================================================== ==========================================================================================================================================================================================================================================================================================================================================================
0 Disable shader optimizations Command-line flag ``-disable-llvm-optzns`` provided to DXC's internal frontend
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-dixable-llvm-optzns isn't really supported by DXC, I believe the flag is -Od.

Copy link
Collaborator Author

@Icohedron Icohedron Apr 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was able to confirm that -disable-llvm-optzns is tied to the setting of this flag, but I wasn't sure about -Od.

The DisableOptimizations flag is set to a value returned from a getter in DxilModule: DxilShaderFlags.cpp
The corresponding setter is used in DxilGenerationPass.cpp to using a field bDisableOptimizations from HLOptions.
bDisableOptimizations is set in CGHLSLMS.cpp using a field from CodeGenOptions which itself is set in CompilerInvocation.cpp from OPT_disable_llvm_optzns

1 Disable math refactoring Not set
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not immediately clear what 'Not set' means in this context? Same for the others with the same criteria.

Is it that there is no set criteria, or, just if the flag is not set?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It just means the flag is not set

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this is an older shader model flag. Maybe something more like: "Removed in Shader Model 6.0" is appropriate. @tex3d any thoughts?

Copy link
Collaborator Author

@Icohedron Icohedron Apr 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Though I suppose the wording is a bit awkward because I think the intention for some of these flags is that you can set it if you wish to have its effects? Like if you want to disable math refactoring, you can set the bit for it?

The criteria is more like describing the conditions under which the flag is required to be set and the validator will complain if you use a capability without setting its corresponding bit, or set a capability bit without actually utilizing it in the shader. Though, again, this isn't entirely the case because the shader flags enabled by a command-line flag don't fall into this category.

2 Double-precision floating point Use of the double data type
3 Force early depth-stencil test Shader is a pixel shader, and the ``[earlydepthstencil]`` attribute is present in the HLSL source
4 Raw and structured buffers Use of RawBuffer or StructuredBuffer resource types
5 Low-precision data types Use of half or i16 data types
6 Double-precision extensions Use of FDiv, UIToFP, SIToFP, FPToUI, FPToSI, or Fma instructions with a double type
7 Masked sum of absolute differences Use of the Msad instruction
8 All resources bound for the duration of shader execution Command-line flag ``/all_resources_bound`` provided to DXC
9 View port or render target array index from any shader feeding rasterizer ViewPortArrayIndex or RenderTargetArrayIndex semantics are present in the input signature of a geometry shader, or the output signature of a vertex, domain, or hull shader. If DXIL validator version < 1.4, this flag is also required if the ViewPortArrayIndex or RenderTargetArrayIndex semantics are present in the input signature of domain and hull shaders
10 Inner coverage Use of the InnerCoverage instruction, or the InnerCoverage semantic is present in the output signature of a pixel shader
11 Stencil reference value The StencilRef semantic is present in the output signature of a pixel shader
12 Tiled resources Use of the CheckAccessFullyMapped instruction or, if DXIL validator version >= 1.8, the use of LodClamp in intrinsics SampleGrad, SampleCmpGrad, Sample, SampleBias, SampleCmp, or SampleCmpBias
13 Typed UAV load additional formats Use of TextureLoad or BufferLoad on a UAV with a multi-component data type. If DXIL validator version == 1.0 then this flag is set when a TextureLoad or BufferLoad is used on any UAV, regardless of its data type
14 Comparison filtering for feature level 9 Not set
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be good to know the context in which this was valid, but I suspect this was also removed in SM 6.0.

15 64 UAV slots The presence of more than 8 UAVs. If Shader Model >= 6.6, then UAV ranges count as multiple UAVs
16 UAVs at every shader stage The shader has UAVs and: if Shader Model >= 6.8, the shader is a vertex, hull, domain, or geometry shader; else (Shader Model < 6.8) the shader is not a compute or pixel shader
17 CS4 raw and structured buffers Use of RawBuffer or StructuedBuffer in a Shader Model 4.x compute shader
18 Rasterizer order views Not set
19 Wave-level operations Use of any wave or quad intrinsic: WaveIsFirstLane, WaveGetLaneIndex, WaveGetLaneCount, WaveAnyTrue, WaveAllTrue, WaveActiveAllEqual, WaveActiveBallot, WaveReadLaneAt, WaveReadLaneFirst, WaveActiveOp, WaveActiveBit, WavePrefixOp, QuadReadLaneAt, QuadOp, WaveAllBitCount, WavePrefixBitCount, WaveMatch, WaveMultiPrefixOp, WaveMultiPrefixBitCount, QuadVote
20 64-bit integers Use of i64 data types
21 6.1+ View instancing Use of the ViewID instruction
22 6.1+ Barycentrics Use of the AttributeAtVertex instruction, or the Barcentrics semantic is present in the shader input signature. If DXIL validator version < 1.6 then this flag must not be set at all
23 6.2+ Use native low-precision data types Command-line flag ``-enable-16bit-types`` is provided to DXC
24 6.4+ Variable-rate shading The ShadingRate semantic is present in the shader input or output signature
25 6.5+ Raytracing tier 1.1 features Use of the AllocateRayQuery, AllocateRayQuery2, or GeometryIndex instruction

26 6.5+ Sampler feedback Not set
27 6.6+ 64-bit integer atomics on typed resources Use of i64 AtomicBinOp or AtomicCompareExchange instructions on a typed resource
28 6.6+ 64-bit integer atomics on group shared Use of i64 AtomicBinOp or AtomicCompareExchange instructions on group shared memory
29 6.6+ Derivatives in mesh and amp shaders Use of instructions DerivFineX, DerivFineY, DerivCoarseX, DerivCoarseY, CalculateLOD, Sample, SampleBias, SampleCmp, or SampleCmpBias in a mesh or amplification shader
30 6.6+ Resource descriptor heap indexing Use of the CreateHandleFromHeap instruction on a resource descriptor heap
31 6.6+ Sampler descriptor heap indexing Use of the CreateHandleFromHeap instruction on a sampler descriptor heap
32 6.6+ 64-bit integer atomics on descriptor heap resources Use of i64 AtomicBinOp or AtomicCompareExchange instructions on a descriptor heap resource
33 6.7+ Any UAV may not alias any other UAV If DXIL validator version >= 1.8: use of a UAV in any function. If DXIL validator version < 1.8: global presence of a UAV. This flag is not set if the ``-res-may-alias`` command-line flag is provided to DXC
34 6.7+ Advanced texture operations Use of SampleCmpLevel or TextureGatherRaw instructions, or the use of TextureLoad, SampleLevel, SampleCmpLevelZero, Sample Grad, SampleCmpGrad, Sample, SampleBias, SampleCamp, or SampleCmpBias with non-constant offsets
35 6.7+ Writeable MSAA textures Use of the TextureStoreSample instruction. Or if DXIL validator version < 1.8: the presence of Texture2DMS or Texture2DMSArray resources. Or if DXIL validator version >= 1.8: use of Texture2DMS or Texture2DMSArray resources in CreateHandle, CreateHandleForLib, or AnnotateHandle instructions
36 6.9+ Reserved Unused
37 6.8+ Expanded comparison sampling Use of the instructions SampleCmpGrad or SampleCmpBias
38 6.8+ Extended command information Use of the instructions StartVertexLocation or StartInstanceLocation
=== ==== ======================================================================================== ==========================================================================================================================================================================================================================================================================================================================================================

Geometry Shader
---------------
Expand Down