[0031] Semantics - Move processing to Sema at entry function decl

[tex3d]

In the Semantics proposal, under Sema:
https://github.com/llvm/wg-hlsl/blob/main/proposals/0031-semantics.md#sema

Sema check is only stateless, and done during parsing. The parser first emits an HLSLUnparsedSemantic attribute, which is passed down to Sema.

• convert this class into a valid semantic class like HLSLUserSemantic or HLSLSV_*.
• check shader stage compatibility with the system semantic.
• check type compability with the system semantic.

At this stage, we have either HLSLUserSemanticAttr attributes, or known compatible HLSLSV_*Attr attributes. All non-converted HLSLUnparsedSemantic would have raised a diagnostic to say unknown HLSL system semantic X.

No further checking is done as we must wait for codegen to move forward.

These are some of my thoughts.

No semantic differentiation or diagnostics until entry-level processing

During parsing, we do not necessarily know the usage of the decl with the semantic attribute. There is almost nothing we can assume about the semantic during attribute parsing. At this stage, without usage context, the semantic is merely an identifier. In my opinion all that should be captured into the AST semantic attribute in this location is this unparsed/uninterpreted/unmodified identifier.

Determining whether a semantic represents a specific system value, and performing any index or type checking, when you haven't determined the exact usage context, is an HLSL language change.

We could propose a change to the HLSL language that restricts the basic spellings allowed at the semantic parsing level even if it's not used for anything, but I'm not sure how much this buys us. It creates a potential compatibility issue, so that we may diagnose a tiny subset of potentially malformed-looking system value semantic assignments that are unused and ignored.

At the time when we have a full entry decl in Sema, we can then do all the checking we need to verify correct usage for shader signatures.

Perform signature diagnostics and construction in Sema, not CodeGen

Full diagnostics need to be performed in Sema rather than CodeGen, otherwise tools like clangd will lack these diagnostics.

This will involve recursive type traversal and signature element shape construction, application of semantic overrides, semantic index expansions based on type layouts, system value interpretations based on context, special object handling (like streams/patches), diagnosing of system value indexing/type/shape constraints, and so on.

I would propose that the full shader signatures should be diagnosed and constructed in Sema when checking each entry function decl. This would include some target-specific (DirectX vs. Vulkan) interpretations and checks, like signature packing and corresponding diagnostics for DirectX, for example. I anticipate some minor complications for the patch constant function handling for Hull Shaders.

Capture signature elements to entry function decl attribute(s)

I also think the details of the signatures should be captured into to the AST somehow for codegen to follow, so the logic is not duplicated. This capturing cannot (generally) be at the same location as the semantic attribute, since the semantic attribute may be on a struct field (type), and a signature element expresses the interpretation on a particular parameter of the instance of that field.

There are multiple options for capturing this information, perhaps the simplest being an attribute on the entry function that contains the full expansion of signature elements and their mapping to parameters and return type elements.

Use information captured in AST to drive CodeGen

I think the signature information captured in the AST should be sufficient for CodeGen without needing special-case code for handling each specific system value semantic. This would mean the different ways CodeGen would read/write argument/return value contents would be enumerated and encoded into the AST element.

Structured description of shader signature and semantic constraints

I would also prefer to define all the properties and constraints used for different semantic types relative to shader context in easily comprehensible tables, extending the way it's defined in DXC for DXIL to include additional type constraints, as well as account for Vulkan/SPIR-V targets. I prefer this to a bunch of special-case code spread about in different locations, since it's already defined in this structured way for DXC. This may map to a TableGen approach, or a def file approach may be sufficient.

Additional metadata capture for signatures

At CodeGen, there will be information in the signature elements that needs to be captured somewhere to preserve it for shader signature metadata. We need to design the intermediate metadata used for capturing signature information, at least for DirectX. There may also be information desirable to capture for SPIR-V, like semantic names to determine names to use in SPIR-V.

Additional Complications

• in and out are not the only possibilities for entry parameters, you could also have inout, which is both an in and an out parameter folded into one.
• Some shader stages have special object types that define inputs or outputs using a template argument. Some of these have indexing on the object or special operations to write to elements (Stream.Append).
• Some shader stages use arrays to represent a separate vertex array dimension, not a packed indexable interpolant, such as GS input vertex array (ex. in triangleadj MyVertex array[6]).
• We'll need to optimize entry functions such that signature loads/stores are fully sunk into control flow, may be moved across other memory operations, and untouched output parameter elements don't result in store output calls (boiler plate calls are cleaned up).
• Dynamic indexing of input/output array elements previously loaded element-by-element need to translate to dynamic indexes in load/store output operations.
• Layouts for signature elements do not necessarily match parameter memory layouts (signature element flattening).

Some of these details may prove a bit tricky for the current wrapped entry function approach.

[Keenuts]

During parsing, we do not necessarily know the usage of the decl with the semantic attribute. There is almost nothing we can assume about the semantic during attribute parsing. At this stage, without usage context, the semantic is merely an identifier. In my opinion all that should be captured into the AST semantic attribute in this location is this unparsed/uninterpreted/unmodified identifier.

This is what's implemented: initial parsing does not differentiate between system/user semantics, everything is a HLSLUnparsedSemantic attribute which only captures a name, and if there is an index at the end. Differentiation is done at a later stage. (See below for SV_ prefix)

Determining whether a semantic represents a specific system value, and performing any index or type checking, when you haven't determined the exact usage context, is an HLSL language change.
We could propose a change to the HLSL language that restricts the basic spellings allowed at the semantic parsing level even if it's not used for anything, but I'm not sure how much this buys us. It creates a potential compatibility issue, so that we may diagnose a tiny subset of potentially malformed-looking system value semantic assignments that are unused and ignored.

For this rule, I tried to see what DXC and the existing documentation says.
MSDN says All system-values begin with an SV_ prefix. Which doesn't mean every semantic starting with SV_ is a system semantic tho.
But looking at DXC, putting SV_ as prefix to any semantic seems to yield a invalid semantic 'SV_<name>' for <shader-stage>

Full diagnostics need to be performed in Sema rather than CodeGen, otherwise tools like clangd will lack these diagnostics.

Agree. Moved all diagnostics to sema for llvm/llvm-project#159047
I'll send a change to this proposal to capture this.

I would propose that the full shader signatures should be diagnosed and constructed in Sema when checking each entry function decl.

Yes, now plan is to have sema emit the correct attribute for each scalar so codegen can blindly generate the proper input/output/code for each without having to do the recursive construction.
Plan is to attach an attribute with index per non-aggregate/non-array type with all indexing computed.

I also think the details of the signatures should be captured into to the AST somehow for codegen to follow

Assuming each non-aggregate/non-array value as input/output has a clean attribute with semantic-name + index attached after sema, what additional information would you need?

I would also prefer to define all the properties and constraints used for different semantic types relative to shader context in easily comprehensible tables

This was my initial plan: I wanted to have each system semantic defined in the TD file with the constraints expressed in the TD file. (In the last PR, the only implemented constraint was is indexable or not for semantics like SV_GroupID).
Would that be a way to implement this centralized table you mention?

At CodeGen, there will be information in the signature elements that needs to be captured somewhere to preserve it for shader signature metadata. We need to design the intermediate metadata used for capturing signature information, at least for DirectX. There may also be information desirable to capture for SPIR-V, like semantic names to determine names to use in SPIR-V.

On the SPIR-V side, name is fetched from the attribute, and passed to the backend to generate an OpName.

• in and out are not the only possibilities for entry parameters, you could also have inout, which is both an in and an out parameter folded into one.
• Some shader stages have special object types that define inputs or outputs using a template argument. Some of these have indexing on the object or special operations to write to elements (Stream.Append).
• Some shader stages use arrays to represent a separate vertex array dimension, not a packed indexable interpolant, such as GS input vertex array (ex. in triangleadj MyVertex array[6]).

I feel those 3 items are things we'll be able to implement in codegen once the basic cases are handled. It will probably as all work present challenges, but don't see something we suggest today that would make this any harder.

• We'll need to optimize entry functions such that signature loads/stores are fully sunk into control flow, may be moved across other memory operations, and untouched output parameter elements don't result in store output calls (boiler plate calls are cleaned up).

This is what we do for SPIR-V: semantics are actually handled like we handle vk::ext_input_builtin/vk::ext_output_builtin, meaning if the shader is not storing to a semantic output, no store is generated, keeping the correct behavior.

[llvm-beanz]

We could propose a change to the HLSL language that restricts the basic spellings allowed at the semantic parsing level even if it's not used for anything, but I'm not sure how much this buys us.

I'm not convinced this is actually a language change. Semantics aren't actually a core part of the language, and have no meaning inside a program (they describe external bindings for some APIs). From the language perspective, they're merely annotations that the runtime interprets in an implementation-defined way.

I think it's also pretty clear that DXC doesn't always follow consistent behaviors. If you make up a SV_* named semantic it errors pretty aggressively, but if you use a valid SV_* semantic in some situations it can be instead treated as a user semantic.

From a grammar perspective I don't actually think that changes what we need to capture in the AST though. We can always capture SV_* semantics as "system values" and error for unrecognized system values (which DXC does!). We can decide after validating semantics against an active entry point whether or not to treat the semantic as a system or user semantic if it is valid to do so.

[Keenuts]

Also, regarding this other comment:

I think we'll need to restrict semantics to ASCII English alphanumeric characters [a-zA-Z_][a-zA-Z_0-9]* due to limitations in the way the runtime interprets these.

So shall we consider the following:

• _ : invalid
• _0 : invalid
• A_0 : valid, A_ + index 0
• 😏0 : invalid
• déçu0 : invalid

[llvm-beanz]

My gut feeling is that we should just be requiring that semantics are "identifier" tokens. The C++11 definition seems to fit our needs from both a grammar perspective and the runtime's requirements: https://timsong-cpp.github.io/cppwp/n3337/lex.name

[Keenuts]

Thanks, fine for me as we could rely on clang's parsing for identifiers. Looked into it and seems like we need N3337 and P1949 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1949r7.html )
Added testing to the user-semantic branch to cover those

[tex3d]

My gut feeling is that we should just be requiring that semantics are "identifier" tokens. The C++11 definition seems to fit our needs from both a grammar perspective and the runtime's requirements: https://timsong-cpp.github.io/cppwp/n3337/lex.name

That defines identifiers as:

identifier:
    identifier-nondigit
    identifier identifier-nondigit
    identifier digit
identifier-nondigit:
    nondigit
    universal-character-name
    other implementation-defined characters
nondigit: one of
    a b c d e f g h i j k l m
    n o p q r s t u v w x y z
    A B C D E F G H I J K L M
    N O P Q R S T U V W X Y Z _
digit: one of
    0 1 2 3 4 5 6 7 8 9

The problem is universal-character-name and other implementation-defined characters. They need to just be the ASCII characters.

Thanks, fine for me as we could rely on clang's parsing for identifiers. Looked into it and seems like we need N3337 and P1949 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1949r7.html ) Added testing to the user-semantic branch to cover those

That changes the identifier definition to:

identifier:
    identifier-start
    identifier identifier-continue
identifier-start:
    nondigit
    universal-character-name of class XID_Start
identifier-continue:
    digit
    nondigit
    universal-character-name of class XID_Continue
nondigit: one of
    a b c d e f g h i j k l m
    n o p q r s t u v w x y z
    A B C D E F G H I J K L M
    N O P Q R S T U V W X Y Z _
digit: one of
    0 1 2 3 4 5 6 7 8 9

Again, the problem is universal-character-name of class XID_Start and universal-character-name of class XID_Continue.

The definition for semantics needs to be:

identifier:
    identifier-start
    identifier identifier-continue
identifier-start:
    nondigit
identifier-continue:
    digit
    nondigit
nondigit: one of
    a b c d e f g h i j k l m
    n o p q r s t u v w x y z
    A B C D E F G H I J K L M
    N O P Q R S T U V W X Y Z _
digit: one of
    0 1 2 3 4 5 6 7 8 9

Otherwise, this will cause all manner of problems for D3D runtime's use of semantics.

The check could be at the interpretation of the semantic, when used in an entry point and would be preserved and passed through to a target runtime, instead of the language element itself, though I'm not sure what advantage that would have, other than perhaps supporting unicode semantics in some future target, so not restricting the syntax to what's supported for a particular runtime target.

[llvm-beanz]

Otherwise, this will cause all manner of problems for D3D runtime's use of semantics.

I don't believe this is an accurate statement. The D3D runtime performs the comparison with _stricmp, which does a case-insensitive compare of any character in the ASCII alphabetic range, which works for UTF-8 just fine as long as the input string doesn't contain alphabetic characters outside that range. If the string does happen to contain alphabetic characters outside the ASCII range the comparison acts as case-sensitive.

I don't believe this causes "all manner of problems", I think it could just cause a semantic to not match when it may have been intended to due to some additional characters being sensitively matched unexpectedly.

We've spent a lot more time discussing the need for this than I think this warranted so I'll just leave it at this: my opinion is that we do not need additional validation beyond what the Lexer is currently providing, and frankly since DXC lets you use universal-character-name tokens in Semantics and the world hasn't ended I think we've blown this pretty far out of proportions.