XQVM Reference

XQVM is the virtual machine at the core of XQuad: a stack-based interpreter with a 256-slot register file that executes compiled quadratic-optimisation programs. This section is the reference for that machine – its execution model, assembly language, instruction set, binary format, and verifier. For what a QUBO/Ising model is and why you would want one, start at Concepts instead; this section assumes you already have a program, or want to write one directly in .xqasm, and want to know exactly what the machine does with it.

A minimal program

Save this as add.xqasm, then assemble and run it:

; push two integers and add them
PUSH 10
PUSH 32
ADD
HALT

$ xquad asm add.xqasm -o add.xqb
assembled 4 instructions (21 bytes) -> add.xqb
$ xquad run add.xqb
stack (bottom to top):
  42

The program pushes 10 and 32 onto the value stack, adds them, and halts. The result remains on the stack and is printed by xquad run. xquad run --text add.xqasm skips the separate assembly step and runs the source directly.

What this section covers

• VM Architecture – the value stack, the 256-slot register file, and the loop stack.
• Loop Stack – RANGE/ITER/NEXT iteration.
• Calldata and Outputs – getting values into a program with INPUT and out with OUTPUT.
• Execution – the fetch-decode-execute cycle and execution tracing.
• Assembly – the .xqasm text syntax.
• Assembly Examples – worked .xqasm programs.
• Instructions – all 93 instructions, by category.
• Opcode Reference – the generated opcode table.
• Bytecode Format – the .xqb wire format.
• Verifier – what the pre-execution verifier checks.
• CLI – the xquad command-line tool.
• Limits and Errors – fixed and configurable limits, and every runtime and verifier error.