Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Opcode Reference

Concise reference table for every opcode in the XQVM bytecode format. Derived directly from conformance/opcodes.yaml, which is kept in sync with the Rust opcodes! x-macro and the Python Opcode enum.

For the normative bytecode specification, see spec/xqvm/SPEC.md.

Columns:

  • Code – wire-encoding byte.
  • Mnemonic – uppercase assembly name.
  • Operands – post-opcode operand layout; empty for no-operand instructions.
  • Stack – stack effect as pop → push; 0 → 1 means one value produced. any → 0 marks an instruction that empties the stack outright rather than applying a fixed net effect.
  • Description – single-sentence semantic summary.

Reserved wire bytes (rejected by the decoder as illegal): 0x0D, 0x19, 0x1D-0x1F, 0x2D-0x2F, 0x35, 0x46-0x49, 0x4D-0x4F, 0x55-0x59, 0x5C-0x5F, 0x6B-0x6F, 0x78-0x7E, 0x80-0xEF, 0xF1-0xFE.

Total: 93 opcodes.

Control Flow

CodeMnemonicOperandsStackDescription
0x00TARGET–0 → 0Mark a valid jump destination.
0x01JUMP1label: u80 → 0Unconditionally jump to a basic block by u8 label index (narrow form).
0x02JUMPI1label: u81 → 0Jump to a basic block by u8 label index if the top of the stack is non-zero (narrow form).
0x03JUMP2label: u160 → 0Unconditionally jump to a basic block by u16 label index (wide form).
0x04JUMPI2label: u161 → 0Jump to a basic block by u16 label index if the top of the stack is non-zero (wide form).
0x05LIDXreg: Register0 → 0Copy the current loop index (offset-adjusted) into a register.
0x06LVALreg: Register0 → 0Copy the current loop value into a register.
0x07NEXT–0 → 0Advance the loop index; jump back or exit the current loop.
0x08RANGE–2 → 0Start a range loop over [start, start + count).
0x09ITERreg: Register2 → 0Start a vec iteration over a slice of a register’s vec.

Register I/O

CodeMnemonicOperandsStackDescription
0x0ALOADreg: Register0 → 1Push the value of an int register onto the stack.
0x0BSTOWreg: Register1 → 0Pop the top of the stack into an int register.
0x0CDROPreg: Register0 → 0Reset a register to Unset, releasing any value it held.
0x0EINPUTreg: Register1 → 0Pop a calldata slot index and load that slot into a register.
0x0FOUTPUTreg: Register1 → 0Pop an output slot index and write the register to it.

Stack Manipulation

CodeMnemonicOperandsStackDescription
0x10POP–1 → 0Discard the top of the stack.
0x11PUSH1val: [u8; 1]0 → 1Push a 1-byte big-endian signed constant, sign-extended to i64.
0x12PUSH2val: [u8; 2]0 → 1Push a 2-byte big-endian signed constant, sign-extended to i64.
0x13PUSH3val: [u8; 3]0 → 1Push a 3-byte big-endian signed constant, sign-extended to i64.
0x14PUSH4val: [u8; 4]0 → 1Push a 4-byte big-endian signed constant, sign-extended to i64.
0x15PUSH5val: [u8; 5]0 → 1Push a 5-byte big-endian signed constant, sign-extended to i64.
0x16PUSH6val: [u8; 6]0 → 1Push a 6-byte big-endian signed constant, sign-extended to i64.
0x17PUSH7val: [u8; 7]0 → 1Push a 7-byte big-endian signed constant, sign-extended to i64.
0x18PUSH8val: [u8; 8]0 → 1Push a full 8-byte big-endian signed constant (i64).
0x1ASCLR–any → 0Clear the entire value stack.
0x1BSWAP–2 → 2Swap the top two stack elements.
0x1CCOPY–1 → 2Duplicate the top of the stack.

Arithmetic

CodeMnemonicOperandsStackDescription
0x20ADD–2 → 1Pop b and a; push a + b.
0x21SUB–2 → 1Pop b and a; push a - b.
0x22MUL–2 → 1Pop b and a; push a * b.
0x23DIV–2 → 1Pop b and a; push a / b (floor division, rounds toward negative infinity).
0x24MOD–2 → 1Pop b and a; push a % b.
0x25SQR–1 → 1Pop a; push a * a.
0x26ABS–1 → 1Pop a; push |a|.
0x27NEG–1 → 1Pop a; push -a.
0x28MIN–2 → 1Pop b and a; push min(a, b).
0x29MAX–2 → 1Pop b and a; push max(a, b).
0x2AINC–1 → 1Pop a; push a + 1.
0x2BDEC–1 → 1Pop a; push a - 1.
0x2CBITLEN–1 → 1Pop a; push floor(log2(a))+1. If a <= 0, push 0.

Comparison

CodeMnemonicOperandsStackDescription
0x30EQ–2 → 1Pop b and a; push 1 if a == b, else 0.
0x31LT–2 → 1Pop b and a; push 1 if a < b, else 0.
0x32GT–2 → 1Pop b and a; push 1 if a > b, else 0.
0x33LTE–2 → 1Pop b and a; push 1 if a <= b, else 0.
0x34GTE–2 → 1Pop b and a; push 1 if a >= b, else 0.

Logical Boolean

CodeMnemonicOperandsStackDescription
0x36NOT–1 → 1Pop a; push 1 if a == 0, else 0.
0x37AND–2 → 1Pop b and a; push 1 if both are non-zero, else 0.
0x38OR–2 → 1Pop b and a; push 1 if either is non-zero, else 0.
0x39XOR–2 → 1Pop b and a; push 1 if exactly one is non-zero, else 0.

Bitwise

CodeMnemonicOperandsStackDescription
0x3ABAND–2 → 1Pop b and a; push a & b.
0x3BBOR–2 → 1Pop b and a; push a | b.
0x3CBXOR–2 → 1Pop b and a; push a ^ b.
0x3DBNOT–1 → 1Pop a; push ~a.
0x3ESHL–2 → 1Pop b and a; push a << b.
0x3FSHR–2 → 1Pop b and a; push a >> b (arithmetic right shift, sign-preserving).

Allocators

CodeMnemonicOperandsStackDescription
0x40BQMXreg: Register1 → 0Pop size; allocate a binary QUBO model ({0, 1} domain) into a register.
0x41SQMXreg: Register1 → 0Pop size; allocate a spin Ising model ({-1, +1} domain) into a register.
0x42XQMXreg: Register2 → 0Pop k then size; allocate an integer model with domain {0, …, k-1} into a register. Errors when k < 2.
0x43BSMXreg: Register1 → 0Pop size; allocate a binary sample ({0, 1} domain) into a register.
0x44SSMXreg: Register1 → 0Pop size; allocate a spin sample ({-1, +1} domain) into a register.
0x45XSMXreg: Register2 → 0Pop k then size; allocate an integer sample with domain {0, …, k-1} into a register. Errors when k < 2.
0x4AVECreg: Register0 → 0Create an empty vec<int> in a register, identical to VECI.
0x4BVECIreg: Register0 → 0Create an empty vec<int> in a register.
0x4CVECXreg: Register0 → 0Create an empty vec<xqmx> in a register.

Vector Operations

CodeMnemonicOperandsStackDescription
0x50VECPUSHreg: Register1 → 0Pop a value; append it to the register’s vec.
0x51VECGETreg: Register1 → 1Pop index; push vec[index] from the register’s vec.
0x52VECSETreg: Register2 → 0Pop value and index; set vec[index] in the register’s vec.
0x53VECLENreg: Register0 → 1Push the length of the register’s vec onto the stack.
0x54SLACKindices: Register, coeffs: Register2 → 0Pop capacity and start_index; append slack variable indices and power-of-two coefficients to two register vecs.

Index Math

CodeMnemonicOperandsStackDescription
0x5AIDXGRID–3 → 1Pop cols, col, row; push the flat grid index row * cols + col.
0x5BIDXTRIU–2 → 1Pop j and i; push the upper-triangular index for the unordered pair (i, j).

XQMX Coefficient Access

CodeMnemonicOperandsStackDescription
0x60GETLINEreg: Register1 → 1Pop i; push linear[i] from the register’s model, or a sample’s assignment at i; raises IndexOutOfBounds outside [0, size).
0x61SETLINEreg: Register2 → 0Pop value and i; set linear[i] in the register’s model, or a sample’s assignment at i; a sample value outside its domain raises SampleOutOfDomain.
0x62ADDLINEreg: Register2 → 0Pop delta and i; add delta to linear[i] in the register’s model, or a sample’s assignment at i; a sample result outside its domain raises SampleOutOfDomain.
0x63GETQUADreg: Register2 → 1Pop j and i; push quadratic[i, j] from the register’s model; requires MODEL mode – a sample register raises TypeMismatch; raises IndexOutOfBounds outside [0, size).
0x64SETQUADreg: Register3 → 0Pop value, j, and i; set quadratic[i, j] in the register’s model; requires MODEL mode – a sample register raises TypeMismatch; raises IndexOutOfBounds outside [0, size).
0x65ADDQUADreg: Register3 → 0Pop delta, j, and i; add delta to quadratic[i, j] in the register’s model; requires MODEL mode – a sample register raises TypeMismatch; raises IndexOutOfBounds outside [0, size).

XQMX Grid

CodeMnemonicOperandsStackDescription
0x66RESIZEreg: Register2 → 0Pop cols and rows; set the grid dimensions of the register’s model or sample.
0x67ROWFINDreg: Register2 → 1Pop value and row; push the first column where the value matches, or -1.
0x68COLFINDreg: Register2 → 1Pop value and col; push the first row where the value matches, or -1.
0x69ROWSUMreg: Register1 → 1Pop row; push the sum of all linear values in that grid row.
0x6ACOLSUMreg: Register1 → 1Pop col; push the sum of all linear values in that grid column.

XQMX High-Level Constraints

CodeMnemonicOperandsStackDescription
0x70ONEHOTRreg: Register2 → 0Pop penalty and row; add a one-hot constraint over the grid row.
0x71ONEHOTCreg: Register2 → 0Pop penalty and col; add a one-hot constraint over the grid column.
0x72EXCLUDEreg: Register3 → 0Pop penalty, j, and i; add a mutual-exclusion constraint between variables i and j; raises IndexOutOfBounds outside [0, size).
0x73IMPLIESreg: Register3 → 0Pop penalty, j, and i; add an implication constraint from variable i to variable j; raises IndexOutOfBounds outside [0, size).
0x74EQUALITYmodel: Register, indices: Register, coeffs: Register2 → 0Pop penalty and target; expand weighted equality constraint into QUBO terms on a model.
0x75ATLEASTmodel: Register, indices: Register2 → 0Pop penalty and k; allocate slack variables and apply at-least-k constraint.
0x76ATLEASTWmodel: Register, indices: Register, coeffs: Register2 → 0Pop penalty and k; allocate slack variables and apply weighted at-least-k constraint.
0x77REDUCEmodel: Register3 → 1Pop P_aux, var_b, var_a; allocate auxiliary variable and add Rosenberg enforcement terms; push aux index.
0x7FENERGYmodel: Register, sample: Register0 → 1Compute the Hamiltonian energy of a sample against a model; push the result.

Special

CodeMnemonicOperandsStackDescription
0xF0NOP–0 → 0No operation.
0xFFHALT–0 → 0Stop execution.