mirror of
https://github.com/KhronosGroup/SPIRV-Tools
synced 2024-10-18 19:20:05 +00:00
Clarify the syntax. Some named enumerants are unusable
You can't use a named enumerant if it's only meaningful in an operand supplied as an ID to a target instruction. The place where you'd use the name is something like an OpConstant, but there's not enough context to bring those names into scope, unless you're willing to tolerate potential collisions. Occurs for the names in: - 3.25 Memory Semantics - 3.27 Scope ID - 3.29 Kernel Enqueue Flags - 3.30 Kernel Profiling Info
This commit is contained in:
parent
41bf0733c6
commit
d7aa15ff16
69
syntax.md
69
syntax.md
@ -1,7 +1,11 @@
|
|||||||
# SPIR-V Assembly language syntax
|
# SPIR-V Assembly language syntax
|
||||||
|
|
||||||
The assembly attempts to adhere to the binary form as closely as possible using
|
## Overview
|
||||||
text names from that specification. Here is an example.
|
|
||||||
|
The assembly attempts to adhere the binary form as closely as possible
|
||||||
|
using text names from section 3 of the SPIR-V spec.
|
||||||
|
|
||||||
|
Here is an example:
|
||||||
|
|
||||||
```
|
```
|
||||||
OpCapability Shader
|
OpCapability Shader
|
||||||
@ -16,11 +20,35 @@ OpReturn
|
|||||||
OpFunctionEnd
|
OpFunctionEnd
|
||||||
```
|
```
|
||||||
|
|
||||||
<a name="assignment-format"></a>
|
A module is a sequence of instructions, separated by whitespace.
|
||||||
In order to improve the text's readability, the `<result-id>` generated by an
|
An instruction is an opcode name followed by operands, separated by
|
||||||
instruction can be moved to the beginning of that instruction and followed by
|
whitespace. Typically each instruction is presented on its own line,
|
||||||
an `=` sign. This allows us to distinguish between variable defs and uses and
|
but the assembler does not enforce this rule.
|
||||||
locate variable defs more easily. So, the above example can also be written as:
|
|
||||||
|
The opcode names and expected operands are described in section 3 of
|
||||||
|
the SPIR-V specification. An operand is one of:
|
||||||
|
* a literal integer: A decimal integer or a hexadecimal integer (preceded by `0x`).
|
||||||
|
* a literal floating point number.
|
||||||
|
* a literal string, surrounded by double-quotes ("). TODO: describe quoting and
|
||||||
|
escaping rules.
|
||||||
|
* a named enumerated value, specific to that operand position. For example,
|
||||||
|
the `OpMemoryModel` takes a named Addressing Model operand (e.g. `Logical` or
|
||||||
|
`Physical32`), and a named Memory Model operand (e.g. `Simple` or `OpenCL`).
|
||||||
|
Named enumerated values are only meaningful in specific positions, and will
|
||||||
|
otherwise generate an error.
|
||||||
|
* an injected immediate integer: `!<integer>`. See [below](#immediate).
|
||||||
|
|
||||||
|
## Assignment-oriented Assembly Form
|
||||||
|
<a name="assignment-form"></a>
|
||||||
|
The description and examples from above describe the Canonical Assembly
|
||||||
|
Form for SPIR-V assembly language.
|
||||||
|
|
||||||
|
We also define the Assignment-oriented Assembly Form, aimed at improving
|
||||||
|
the text's readability. In AAF, the `<result-id>` generated by an
|
||||||
|
instruction is moved to the beginning of that instruction and followed by
|
||||||
|
an `=` sign. This allows us to distinguish between variable definitions
|
||||||
|
and uses and locate value definitions more easily. So, the above example
|
||||||
|
can also be written as:
|
||||||
|
|
||||||
```
|
```
|
||||||
OpCapability Shader
|
OpCapability Shader
|
||||||
@ -35,13 +63,6 @@ locate variable defs more easily. So, the above example can also be written as:
|
|||||||
OpFunctionEnd
|
OpFunctionEnd
|
||||||
```
|
```
|
||||||
|
|
||||||
Each line encapsulates one and only one instruction, or an OpCode and all of its
|
|
||||||
operands. OpCodes use the names provided in section 3.28 Instructions of the
|
|
||||||
SPIR-V specification, immediate values such as Addressing Model, Memory Model,
|
|
||||||
etc. use the names provided in sections 3.2 Source Language through 3.27
|
|
||||||
Capability of the SPIR-V specification. Literals strings are enclosed in quotes
|
|
||||||
`"<string>"` while literal numbers have no special formatting.
|
|
||||||
|
|
||||||
## ID Definitions & Usage
|
## ID Definitions & Usage
|
||||||
|
|
||||||
An ID definition pertains to the `<result-id>` of an OpCode, and ID usage is any
|
An ID definition pertains to the `<result-id>` of an OpCode, and ID usage is any
|
||||||
@ -69,6 +90,7 @@ following example will result in identical SPIR-V binary as the example above.
|
|||||||
```
|
```
|
||||||
|
|
||||||
## Arbitrary Integers
|
## Arbitrary Integers
|
||||||
|
<a name="immediate"></a>
|
||||||
|
|
||||||
*Warning: Not all of the following has been implemented*
|
*Warning: Not all of the following has been implemented*
|
||||||
|
|
||||||
@ -115,7 +137,7 @@ output without any checking; when a recognizable OpCode is eventually
|
|||||||
encountered, it begins a new instruction and parsing returns to normal. (If a
|
encountered, it begins a new instruction and parsing returns to normal. (If a
|
||||||
subsequent OpCode is never found, then this alternate parsing mode handles all
|
subsequent OpCode is never found, then this alternate parsing mode handles all
|
||||||
the remaining words in the program. If a subsequent OpCode is in an
|
the remaining words in the program. If a subsequent OpCode is in an
|
||||||
[assignment format](#assignment-format), the ID preceding it begins a new
|
[assignment form](#assignment-form), the ID preceding it begins a new
|
||||||
instruction, even if that ID is itself a `!<integer>`.)
|
instruction, even if that ID is itself a `!<integer>`.)
|
||||||
|
|
||||||
The assembler processes the words encountered in alternate parsing mode as
|
The assembler processes the words encountered in alternate parsing mode as
|
||||||
@ -155,3 +177,20 @@ Note that this has some interesting consequences, including:
|
|||||||
number generated for an existing named ID, it will result in a reference to
|
number generated for an existing named ID, it will result in a reference to
|
||||||
that named ID being output. This may be valid SPIR-V, contrary to the
|
that named ID being output. This may be valid SPIR-V, contrary to the
|
||||||
presumed intention of the writer.
|
presumed intention of the writer.
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
* Some enumerants cannot be used by name, because the target instruction
|
||||||
|
in which they are meaningful take an ID reference instead of a literal value.
|
||||||
|
For example:
|
||||||
|
* Named enumerated value `CmdExecTime` from section 3.30 Kernel
|
||||||
|
Profiling Info is used in constructing a mask value supplied as
|
||||||
|
an ID for `OpCaptureEventProfilingInfo`. But no other instruction
|
||||||
|
has enough context to bring the enumerant names from section 3.30
|
||||||
|
into scope.
|
||||||
|
* Similarly, the names in section 3.29 Kernel Enqueue Flags are used to
|
||||||
|
construct a value supplied as an ID to the Flags argument of
|
||||||
|
OpEnqueueKernel.
|
||||||
|
* Similarly for the names in section 3.25 Memory Semantics.
|
||||||
|
* Similarly for the names in section 3.27 Scope.
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user