The binary parser has a C API, described in binary.h.
Eventually we will make it public in libspirv.h.
The API is event-driven in the sense that a callback is called
when a valid header is parsed, and for each parsed instruction.
Classify some operand types as "concrete". The binary parser uses
only concrete operand types to describe parsed instructions.
The old disassembler APIs are moved into disassemble.cpp
TODO: Add unit tests for spvBinaryParse.
This begins the refactoring of the disassembler into
two parts: A binary decoder in binary.cpp, and an
event-driven converter to text in disassemble.cpp
Note that we are more strict than Google style for one aspect:
pointer/reference indicators are adjacent to their types, not
their variables.
find . -name "*.h" -exec clang-format -i {} \;
find . -name "*.cpp" -exec clang-format -i {} \;
This is required to support extended instructions that
have literal numbers as operands. An example is OpenCL's
vloadn.
The previous code in the assembler assumed that *any* literal
number argument in any part of an OpExtInst must be the name
of the extended instruction. That's true only for the first
literal number argument.
Versions 1.2, 2.0, and 2.1 all use the same
extended instruction list.
Updated the source code patch for the SPIR-V doc generator,
so it can both generate the core syntax table, and also the
OpenCL extended instructions table.
Tested the Math and Common functions.
TODO: test the remaining entries.
Removed spvBinaryDecodeOpcode and spvBinaryDecodeOperand from the public
interface since they were only ever used in binary.cpp.
Replaced the usage of spv_operand_table_t and it's ilk with the
AssemblyGrammar to reduce the number of passed parameters.
Fixed typo in comment.
Except for OpConstant and OpSpecConstant, all other literal number
operands are indeed unsigned integers. So,
* Rename all *LITERAL_NUMBER* operand types to *LITERAL_INTEGER*.
* Expect unsigned integers for *LITERAL_INTEGER* operands.
* Keep MULITPLE_WORD_LITERAL untouched since it is only used by
OpConstant and OpSpecConstant.
And we want to provide the capability to specify floating-point
numbers after !<integer> in the alternate parsing mode. So,
OPTIONAL_LITERAL_NUMBER is reserved for OPTIONAL_CIV.
The DiagnosticStream will not emit the accumulated message
text if the error is SPV_FAILED_MATCH.
Change various interfaces to accept the intended error
code instead of a boolean "is_optional". This allows
us to avoid repeating the following type of logic deep
inside helper methods:
if (is_optional) return SPV_FAILED_MATCH;
return diagnostic() << " message text ";
Affects OpConstant, and OpSwitch.
Adds constant libspirv::kUnknownType for readability.
Adds tests for hexadecimal number parsing.
Updates syntax.md to describe hex parsing, including
sign extension.
Use this to shorten error return code in the assembler.
For example, change this:
if (error = something()) {
diagnostic() << " Bad integer literal " << value;
return SPV_ERROR_INVALID_VALUE;
}
to this:
if (error = something())
return diagnostic() << " Bad integer literal " << value;
Also shorten code due to the fact that binaryEncodeU32 and
binaryCodeU64 can't fail (short of failure to expand a std::vector).
We need to know how to generate correct SPIRV for cases like
OpConstant %int64 42 since the current parser will encode the 42 as a
32-bit value incorrectly.
This change is the first of a pair. This one tracks types, and makes
sure that OpConstant and OpSpecConstant are only ever called with
Integer or Float types, and OpSwitch is only called with integer
generating values.
Move the definition of spv_instruction_t to an internal
header file, since it now depends on C++ and is not
used by the external interface.
Use a std::vector<uint32_t> in spv_instruction_t
instead of a fixed size array.
Fixes dependencies among capabilities. (The table should store
the mask of capabilites, not the capability enum.)
Remove the old spot check test for capabilities of enums.
Implement some outstanding feedback from
Ic29c5a4a8178a62a5a1acad13d02f19cc1307097:
- use "token" instead of "word" when referring to assembly text
- specify how the numbers are parsed
Add a test for negative numbers.
Operand class enum values not used in the syntax table:
- Image channel order: only used to describe a return value
- Image channel type: only used to describe a return value
- "Image operands": used to make a section in the spec
to describe values used to construct an optional image id,
but does not itself appear in the syntax table.
Removes some TODOs from opcode.cpp.
All uses of OptionalLiteral by the SPIR-V spec are used
for literal numbers.
Also rename:
- SPV_OPERAND_TYPE_OPTIONAL_LITERAL to
SPV_OPERAND_TYPE_OPTIONAL_LITERAL_NUMBER.
- SPV_OPERAND_TYPE_VARIABLE_LITERAL to
SPV_OPERAND_TYPE_VARIABLE_LITERAL_NUMBER.
- SPV_OPERAND_TYPE_VARIABLE_LITERAL_ID to
SPV_OPERAND_TYPE_VARIABLE_LITERAL_NUMBER_ID.
- SPV_OPERAND_TYPE_VARIABLE_ID_LITERAL to
SPV_OPERAND_TYPE_VARIABLE_ID_LITERAL_NUMBER.
- SPV_OPERAND_TYPE_LITERAL_IN_OPTIONAL_TUPLE to
SPV_OPERAND_TYPE_LITERAL_NUMBER_IN_OPTIONAL_TUPLE.
Many instructions added and a few changed structure.
Workarounds:
- Some operands can be enabled by either one of two
capabilities. The spv_operand_desc_t does not handle that
now. For now just select the first one.
Fixes to tests:
- OpLoopMerge now takes a mandatory continue target.
- OpTypePipe drops the type argument. Pipes are opaque.
- OpLine no longer takes a target ID argument.
The ID validator was fixed the OpLine and OpTypePipe
changes. Those were the only ID validator tests affected.
The patch to the spec doc generator was updated so it handles
the two-capability case, even if in an hacky way.
Also removed un-necessary heap-allocation of spv_named_id_table.
This removed the necessity to expose a function to create/destroy it
and simplified the interface.
If a memory mask operand is present, it is a mask. The mask appears
only once, so just use SPV_OPERAND_TYPE_OPTIONAL_MEMORY_MASK.
The "variable literals" aspect comes into play as follows: if the
Aligned bit is set in the mask, then the parser will be made to
expect the alignment value as a literal number operand that follows
the mask. That is done through mask operand expansion.
Properly support a memory access mask with a combination
of bits, including the Aligned bit. When the Aligned bit is
set, the parser should expect an alignment value literal operand.
For example, support combining mask enums with "|",
such as "NotNaN|AllowRecip" for the fast math mode.
This is supported for mask values that don't modify the
expected operand pattern:
- fast math mode
- function control
- loop control
- selection control
TODO: disassembler support to print them as mask expressions.
Add a new operand type SPV_OPERAND_TYPE_MULTIWORD_LITERAL_NUMBER
to represent those operands that can expand into multiple words.
Now only OpConstant and OpSpecConstant have such kind of operand.
Added a new enum for supported assembly syntax formats:
Canonical Assembly Format (CAF) and Assignment Assembly Format (AAF).
Updated assembler interface functions to support choice of assembly
syntax format.
Added diagnostic messages for what should be an internal failure
that never happens. I figure if we return "failed" for something the
user cannot control we should print a message for it.
Previous the api used spv_text_t and spv_binary_t for both input
and output, but depending on the usage, you either MUST
call spvBinaryDestroy or you MUST NOT call spvBinaryDestroy on the
pointer.
The assembler and disassembler now use a dynamically adjusted
sequence of expected operand types. (Internally, it is a deque,
for readability.) Both parsers repeatedly pull an expected operand
type from the left of this pattern list, and try to match the next
input token against it.
The expected pattern is adjusted during the parse to accommodate:
- an extended instruction's expected operands, depending on the
extended instruction's index.
- when an operand itself has operands
- to handle sequences of zero or more operands, or pairs of
operands. These are expanded lazily during the parse.
Adds spv::OperandClass from the SPIR-V specification generator.
Modifies spv_operand_desc_t:
- adds hasResult, hasType, and operandClass array to the opcode
description type.
- "wordCount" is replaced with "numTypes", which counts the number
of entries in operandTypes. And each of those describes a
*logical* operand, including the type id for the instruction,
and the result id for the instruction. A logical operand could be
variable-width, such as a literal string.
Adds opcode.inc, an automatically-generated table of operation
descriptions, with one line to describe each core instruction.
Externally, we have modified the SPIR-V spec doc generator to
emit this file.
(We have hacked this copy to use the old semantics for OpLine.)
Inside the assembler, parsing an operand may fail with new
error code SPV_FAIL_MATCH. For an optional operand, this is not
fatal, but should trigger backtracking at a higher level.
The spvTextIsStartOfNewInst checks the case of the third letter
of what might be an opcode. So now, "OpenCL" does not look like
an opcode name.
In assembly, the EntryPoint name field is mandatory, but can be
an empty string.
Adjust tests for changes to:
- OpSampedImage
- OpTypeSampler
Use double quotes ("). They can be interspersed with
other whitespace characters, just like shell quoting.
A backslash (\) always escapes the next character.
The end of the stream always terminates the word.
Add AutoText struct to unit test utilities, to easily
make spv_text_t values and reference them as spv_text values.
- a single hyphen is a string, not a number.
- a string with more than one period is a string, not a number
- check for string overflow
Add some unit tests
Since now we can distinguish between def and use according to
the variable's location, there is no need to keep two variable
prefixes.
Also reformat tests to use the value generating instruction
format ("<result-id> = <opcode> <operand>..").
Fix the bug that TextAdvance() forgot to skip whitespace at the
beginning of the next line after a comment line.
Fix the bug that TextAdvanceLine() increase line number after going
over a character.
For enum Capability and enum Op, not all newly added enumerants are
registered into capabilityInfoEntries and opcodeTableEntries yet.
That will come in following commits.
