Rewrite the builder generator to cover every opcode -- each operand maps to a
typed param by kind + quantifier, emitted with a running operand index so all
shapes compose:
optional '?' -> Maybe(T)
variadic '*' -> []T
composite Pair* -> []Pair_Id_Id / []Pair_Lit_Id / []Pair_Id_Lit
LiteralString -> string (packed into word operands)
Id/Lit/enum -> Id / i64 / the typed enum (ValueEnum) or bit_set (BitEnum)
A verb that would clash with an Odin keyword, builtin, builtin type name, or a
re-exported ir.type_* constructor gets a trailing '_' (return_, switch_, string_,
size_of_, type_void_, ...). builder.odin gains the Pair_* types + a string packer.
873 inst_<OpName> + 873 Builder methods. Package compiles; suite 10 passed.
Add a count-only mode to the Writer (advance pos without storing) and factor the
section walk into emit_module, so encode and the new encoded_size(m) share one
path. encoded_size returns the exact byte count encode will produce -- the SPIR-V
analog of an ISA's encode_max_code_size, here exact rather than an upper bound.
The printer now sizes its scratch buffer with it instead of retry-on-overflow.
Verified: encoded_size == encode byte_count; suite 10 passed.
Extend tablegen to emit builders_gen.odin -- 723 opcodes get a low-level
inst_<OpName>(buf, ...) constructor and a high-level Builder method, mapping each
grammar operand to a typed param (IdResultType->Type_Ref, IdResult->auto-allocated
Id, IdRef->Id, LiteralInteger->i64, ValueEnum/BitEnum->the typed enum, trailing
IdRef* -> []Id). builder.odin keeps just the hand-written Builder infrastructure.
Skipped (stay hand-writable, like an ISA's can_generate_builder): operands that
aren't simple typed params yet (optional, Pair* composites, LiteralString),
type-declaration opcodes (those are ir.Type), and verbs colliding with Odin
keywords/builtins (return_, switch_, size_of, ...).
Validated: a function body built via i_add / return_ encodes + round-trips
byte-exact (builder_made test) -> 10 passed.
Two layers, the SPIR-V analog of an ISA's mnemonic builders:
- low level: inst_<OpName>(buf, ...) -> Operation, stateless + alloc-free, the
caller owns the operand backing (SPIR-V operands are a slice, so unlike an
ISA's inline [4]Operand they can't be owned by the return value).
- high level: a Builder owning operand storage + a result-<id> allocator;
iadd/load/store/call/variable/ret/ret_value append to the current block and
return the new <id>.
Hand-written here for a representative slice (Id / no-result / variadic / enum
operands) to fix the pattern; tablegen will generate the full per-opcode set.
Validated: a builder-made function body round-trips byte-exact.
Type-defining instructions the codec doesn't model structurally -- OpTypeImage,
OpTypeSampler, OpTypeSampledImage, OpTypeMatrix, OpTypeOpaque, OpTypeEvent,
OpTypeDeviceEvent, OpTypeReserveId, OpTypeQueue, OpTypePipe -- decode to
Type{.OPAQUE} plus an Opaque_Info{opcode, words} side entry (the operand words
after the result <id>) and re-emit verbatim. One generic fallback covers every
opaque SPIR-V type byte-exact, with no per-type fields.
Test: image_type (OpTypeImage, 7 operands) round-trips -> 9 passed.
- fmt_bitenum prints the common BitEnum operands as their set bits' names joined
with '|' (or None when empty): FunctionControl, MemoryAccess, SelectionControl,
LoopControl, ImageOperands -- so OpFunction ... None, OpLoad ... Aligned.
- fmt_inst now also prints words trailing the fixed operand layout (the params an
enum value/bit pulls in, e.g. MemoryAccess Aligned's alignment), previously
dropped: OpLoad %2 %7 Aligned 16.
- Definition order: Module.defs records the exact type/constant/global
interleaving (SPIR-V's single 'types, constants, global variables' section must
be dependency-ordered -- a length constant before the array type that uses it,
etc.). decode records it; encode replays it for byte-exact, spec-valid output
(empty defs falls back to all-types, then -constants, then -globals).
emit_one_type/constant/global factored out for the replay; no encoder alloc.
- OpTypeRuntimeArray: ARRAY with len_ref == ID_NONE (vs OpTypeArray's <id> length).
Tests: bool_and_array sets defs so OpConstant precedes OpTypeArray (verified in
disasm); runtime_array added -> 7 passed.
Extend the shared type model so SPIR-V's OpTypeBool and OpTypeArray (whose length
is a constant <id>, not a literal) lower cleanly:
- ir.Type_Kind gains BOOL (a distinct boolean; LLVM i1 will use it too).
- ir.Type gains len_ref: Id -- an ARRAY length carried as a constant <id>
(alongside the existing literal count for dialects with literal lengths).
- type_bool / type_array constructors.
SPIR-V codec: OpTypeBool <-> Type{.BOOL}; OpTypeArray <-> Type{.ARRAY, elem,
len_ref}. Test bool_and_array round-trips byte-exact -> 6 passed.
NOTE: a spec-valid module orders an array's length constant before the array
type; the codec round-trips the shape byte-exact regardless, but emitting the
types/constants section in dependency order is a follow-up.
The decoder already detects endianness from the magic word and byte-swaps each
word; strings are read from word values, so both endiannesses decode. Lock it in:
the round-trip helper now also byte-swaps every word to big-endian, decodes, and
asserts the re-encoding reproduces the original little-endian bytes -- across all
5 cases.
fmt_enum prints the common ValueEnum operands by name (Capability Shader,
Addressing/Memory model Logical GLSL450, ExecutionModel GLCompute, StorageClass,
Decoration, ...); BitEnums stay numeric (their bit_set %v form is too verbose to
read inline). The header comment now reads version/generator/bound from the
encoded words, so Bound reflects the computed value, not the pre-encode 0.
- OpFunctionParameter: the entry block's Block.params round-trip as
OpFunctionParameter (emitted between OpFunction and the entry OpLabel, decoded
back onto the entry block).
- encode computes bound (max <id> + 1) when the caller leaves it 0; a non-zero
bound (e.g. from decode) is preserved, so re-encode is stable.
- Trailing operands an enum value/bit pulls in (MemoryAccess Aligned's alignment,
...) are captured on decode as literals, so enum-parameter instructions
re-encode byte-exact.
Tests: param_function + load_aligned added -> 5 passed.
print(m, sb, options): disassemble a Module into a spirv-dis-style listing.
Encodes to a scratch buffer (doubling on overflow) and walks the word stream
generically through the operand-layout table, so every opcode disassembles with
no per-op code -- Id operands as %id, LiteralString quoted, the result-id column
right-aligned before OpName:
; SPIR-V
; Version: 1.5
; Bound: 9
%2 = OpTypeInt 32 1
%4 = OpConstant %2 10
%6 = OpIAdd %2 %4 %5
OpReturn
Enums print numerically for now (symbolic names a refinement). Completes the
encode / decode / print verb triad.
A tests/ package (the ISA test convention) that, per module shape, does
encode -> decode -> re-encode and asserts byte-identical output -- exercising the
encoder, decoder, <id> side tables, and the generic operation codec together:
void_main header + preamble + a void function (116 B)
int_constants i32 type + two scalar OpConstants incl. 0xDEADBEEF (88 B)
iadd_function %r = OpIAdd %i32 %a %b ; OpReturn -- generic operand codec
with a result + value operands (164 B)
3 passed. Run: odin run core/rexcode/ir/spirv/tests. (build.lua is ISA-centric;
wiring the ir/ packages into the gen/check/test pipeline is a follow-up.)
The inverse of the encoder: read the header (detecting endianness from the
magic word), walk the instruction stream, and lower each instruction by opcode
back into the structured Module -- the ir core (types/constants/globals/
functions, the generic table-driven operation decode), the SPIR-V sections
(preamble / debug / annotations), and the flat <id> space into the side id
tables (with an id->Type_Ref map so type-naming operands recover TYPE operands).
Single allocator pass (context.allocator), one reused per-instruction word
scratch buffer. Validated: encode -> decode -> re-encode is byte-exact on the
void compute main module (116 bytes; caps/types/functions/blocks/ops/ids/bound
all recovered). Same gaps as the encoder (OpFunctionParameter, ARRAY/bool,
enum-parameter operands); big-endian sources a later refinement.
The second half of encode(): the <id> side tables (Module.type_ids /
global_ids / function_ids -- SPIR-V's flat id space, which ir.Type/Global/
Function don't carry) plus the lowering:
emit_types ir.Type -> OpTypeXxx (void/int/float/vector/pointer/struct/
function; INT signedness + POINTER storage class ride in aux)
emit_constants OpConstant / OpConstantComposite / true/false/null
emit_globals OpVariable (storage class from the pointer type)
emit_operation generic table-driven op emit: INSTRUCTION_INDEX gives the
result-type/result-id prefix, the rest stream from op.operands
emit_functions OpFunction / OpLabel / body / OpFunctionEnd
Validated: a complete void compute main module encodes to byte-exact-correct
SPIR-V (29 words, all checked). Known gaps: OpFunctionParameter, ARRAY/bool
types, explicit enum-parameter operands, computed bound. Decoder next.
The Module -> word-stream encoder's first half: a fast single-pass word writer
(one host-endian store per word; instruction headers written as a placeholder
and backpatched, so variable-length instructions need no measure pass) plus the
header and the preamble / debug / annotation sections in spec layout order
(capabilities, extensions, ext-inst imports, memory model, entry points,
execution modes, OpString/OpSource/OpName, decorations).
Validated: a minimal module encodes to byte-exact-correct SPIR-V (magic, v1.5,
OpCapability Shader, OpMemoryModel Logical GLSL450, OpEntryPoint GLCompute %main,
NUL-terminated 'main' string, correct backpatched word counts).
Types/constants/globals/function bodies (the <id> + type lowering) are next.
Extend the tablegen to emit encoding_table.odin from the grammar -- the
per-opcode operand layout that drives the codec:
INSTRUCTION_SPECS flat []Operand_Spec {Spec_Kind, Quantifier}
INSTRUCTION_INDEX [max_opcode+1]Spec_Run -- O(1) opcode -> its operand run
ENUM_PARAMS enumerant -> trailing-parameter operands, so the codec
PARAM_SPECS reads MemoryAccess.Aligned / OpExecutionMode LocalSize /
Decoration.SpecId etc. correctly
873 opcodes, 3693 operand specs. Package compiles.
Start the SPIR-V intermediate representation under core/rexcode/ir/spirv,
following the ir API (docs/ir_design.md) and the ISA package conventions. SPIR-V
is table-driven on encoding and SSA on dataflow, so it re-exports the shared ir
vocabulary and is laid out like an arch package.
spirv.odin package + ir re-exports + physical format (MAGIC, version,
Header, wordCount<<16|opcode framing)
module.odin Module :: struct { using base: ir.Module, ...sections... } --
capabilities, ext-imports, entry points, exec modes, constant
pool, decorations, debug; SPIR-V's module metadata has no
ir.Module slot, so it is carried alongside the core
reloc.odin Relocation (linkage import/export)
opcodes.odin GENERATED: the Opcode enum (873 opcodes)
operand_kinds.odin GENERATED: ValueEnum/BitEnum operand kinds + Spec_Kind
tablegen/gen.odin the generator (core:encoding/json)
tablegen/spirv.core.grammar.json vendored authoritative grammar (Khronos
SPIRV-Headers unified1) -- single source of truth
Generating from the authoritative grammar avoids hand-transcription errors
(hand-authoring had Quads/Aliased/... wrong). Package compiles. Codec
(encode/decode + flat<->structured lowering), printer, and tests are next.
A sibling to core:rexcode/isa for the intermediate representations (WASM,
SPIR-V, LLVM bitcode + the LLVM dialects AIR/DXIL). Holds the shared
vocabulary every IR package builds on, implements no specific IR.
Design stance (see docs/ir_design.md): keep the ISA layer's spirit, but
where IRs are structurally MORE uniform than ISAs (SSA + a type system
regularize the operand/module shape), the shared core is richer. ir/ owns:
status.odin Error/Error_Code (shape-identical to isa.Error)
refs.odin Id/Ref/Ref_Space/Symbol_Table (the label analog: structural
id references, not PC-relative byte offsets)
types.odin Type/Type_Ref/Type_Kind (the type table -- no ISA analog)
module.odin Module/Function/Block/Operation/Operand/Result/Dataflow
(the structured model; Operation = isa.Instruction + an
optional typed Result, opcode a u16 like Mnemonic)
print.odin token kinds + options + num-fmt (parallels isa.print)
Three honest concessions vs the ISA API, made explicit not inert: a
structured Module replaces the flat []Instruction; a first-class type
system; id-based entity refs replace labels. The encode/decode verbs take
a Module and drop label_defs/resolve/base_address. Dataflow hosts both the
WASM value stack and SSA; the codec is pluggable (table for WASM/SPIR-V,
bitstream for the LLVM family -- AIR/DXIL are LLVM dialects, not peers).
Package compiles; a hand-built SSA module round-trips through the types.
