Instruction Set Reference

This section documents all 93 XQVM instructions, organised into the 14 categories below. Each page covers the semantics, error conditions, and worked examples for one category. For the opcode byte, mnemonic, operand layout, and stack effect of every instruction, see the generated Opcode Reference – that table is the single source of truth for wire-level facts, so the pages in this section carry prose and teaching content instead of repeating it.

Notation

• Stack effect – described in prose on this page (“Pop b, then a”) and summarised on the generated Opcode Reference as a Stack column of the form 2 → 1, meaning two values popped and one pushed. The value stack is last-in-first-out: whichever value was pushed most recently is popped first, so PUSH a; PUSH b; SUB computes a - b, not b - a. Every “pop x, then y” operand order on this section’s pages, including the ones on constraints.md and index-math.md, depends on this rule.
• reg – the u8 operand encoded in the instruction byte stream, identifying a register slot (r0–r255).
• label – a sequential id assigned to each TARGET instruction, in program order, during the load-time pre-scan described in Bytecode Format. It is not a byte offset, and not the .N token used in .xqasm source – that token is assembler-only and is resolved to the sequential id before encoding. JUMP1/JUMPI1 encode the id as a single u8 operand; JUMP2/JUMPI2 encode it as a u16 operand (big-endian). See Control Flow for how the assembler picks between the two.
• Assignments use \(\leftarrow\) (register write) and \(\to\) (stack push).
• Iverson brackets – \([P]\) equals \(1\) if \(P\) is true, \(0\) otherwise.
• Checked arithmetic – every integer operation is checked against the i64 range. A result that would leave it raises ArithmeticOverflow rather than wrapping or panicking; see Arithmetic.

Register Effect Vocabulary

A handful of pages, constraints.md and energy.md, annotate individual opcodes with a **Register effect:** line using three terms:

• read – register contents are inspected but not changed.
• write – register is replaced wholesale with a new value.
• mutate – register’s existing value is modified in-place (e.g. appending to a vec, incrementing a coefficient).

Most category pages group opcodes by topic or mechanism rather than walking through them one at a time, so they carry no such line.

RegVal – The Register Value Type

Each of the 256 registers holds one variant of RegVal – Unset, Int, VecInt, VecXqmx, Model, or Sample. See VM Architecture for the full table.

Type mismatches at runtime produce a RegisterType error with the expected and actual variant names; reading an Unset register via LOAD or OUTPUT produces UnsetRegister instead, since there is no variant to compare against.

Categories

Reserved Opcodes

Every byte value not listed in Opcode Reference is illegal; the decoder rejects it. The 93 assigned bytes are not contiguous – there are gaps both between and within the ranges above, plus one large unassigned block above the normal instruction space. The full gap set, derived by diffing the 93 assigned byte values against the complete 0x00-0xFF space:

NOP (0xF0) and HALT (0xFF) are the only two assigned bytes outside 0x00-0x7F; every other byte in 0x80-0xFF is illegal. See spec/xqvm/ISA.md for the normative list, organised the same way.