xquad vm run

Execute XQVM bytecode or assembly source, printing the residual outputs and stack, with optional step-by-step tracing.

Usage

xquad vm run [OPTIONS] <FILE>

Arguments

Options

xquad vm run does not call the verifier. A program that fails verification can still be handed to run; some defects (an unset register read, for example) are also caught by the VM’s own runtime checks and abort with a runtime error, but others are not. See xquad vm check and Verification for what static verification does and does not guarantee.

Examples

Run bytecode

xquad vm run add.xqb

stack (bottom to top):
  42

Run assembly directly

xquad vm run --text add.xqasm

Skips the separate xquad vm asm step; the source is assembled in memory and run immediately.

Pass calldata and read outputs

INPUT and OUTPUT each take one register operand in assembly, but both pop the slot index off the value stack at runtime – the index is not implicit in the instruction. A program that reads calldata[0] into r0, adds one, and writes the result to output slot 0 needs the index pushed explicitly before each call: PUSH 0; INPUT r0; ...; PUSH 0; OUTPUT r1; HALT.

xquad vm run io.xqb --calldata 41

outputs:
  [0] = Int(42)

--calldata accepts a comma-separated list; each value is consumed in order by successive INPUT instructions. OUTPUT faults UnsetRegister if the register it reads was never written, the same as LOAD. Both INPUT and OUTPUT fault with CallDataIndex/OutputIndex respectively if the popped index is out of range for the calldata or output-slot array – the index itself is not guaranteed to be valid just because it came off the stack. See Register I/O for the full set of INPUT/OUTPUT error modes.

Enable tracing

xquad vm run regs.xqb --trace

Trace lines go to stderr:

step    offset    instruction            stack                      read-regs        written-regs   
     1  0x0000    PUSH1 7                [7]                                                        
     2  0x0002    STOW r0                []                                          r0=7           
     3  0x0004    LOAD r0                [7]                        r0=7                            
     4  0x0006    HALT                   [7]                                                        

and the residual stack goes to stdout, separately from the trace:

stack (bottom to top):
  7

Trace lines go to stderr by default so the stdout result is not interleaved with them in a terminal. Redirect stderr separately to capture the trace on its own:

xquad vm run regs.xqb --trace 2>trace.txt

JSON trace

xquad vm run regs.xqb --trace --trace-format json --trace-file trace.jsonl

trace.jsonl then holds one JSON object per step:

{"step":1,"pos":0,"instruction":"PUSH1 7","stack":[7],"read_regs":{},"written_regs":{}}
{"step":2,"pos":2,"instruction":"STOW r0","stack":[],"read_regs":{},"written_regs":{"0":{"type":"int","value":7}}}
{"step":3,"pos":4,"instruction":"LOAD r0","stack":[7],"read_regs":{"0":{"type":"int","value":7}},"written_regs":{}}
{"step":4,"pos":6,"instruction":"HALT","stack":[7],"read_regs":{},"written_regs":{}}

Custom step limits

countloop.xqb assembles a five-iteration RANGE loop around a NOP: six encoded instructions, 14 executed steps, because the body and its NEXT run once per iteration. A limit that is reached before HALT aborts the run:

xquad vm run countloop.xqb --step-limit 3

Error: run failed: StepLimitExceeded { pos: None, requested: 1, used: 3, limit: 3 }

The limit is exact, and 0 is not a sentinel for “unlimited”. A zero budget permits no instructions at all, so the first fetch fails:

xquad vm run countloop.xqb --step-limit 0

Error: run failed: StepLimitExceeded { pos: None, requested: 1, used: 0, limit: 0 }

Passing --unlimited-steps alongside --step-limit is a usage error (exit 2) rather than resolved by precedence, so opting out of the bound cannot be said two ways at once:

xquad vm run countloop.xqb --step-limit 0 --unlimited-steps

Usage: xquad vm run [OPTIONS] FILE
Try 'xquad vm run --help' for help.

Error: --step-limit cannot be used with --unlimited-steps

The conflict fires on an explicit --step-limit, not on the default, so --unlimited-steps on its own is accepted. It removes the bound entirely, which is only safe where you control the program or can abandon the thread – a program that never halts will not return:

xquad vm run countloop.xqb --unlimited-steps

prints nothing, since the program leaves no outputs and no residual stack. To raise the limit rather than remove it, pass a larger number, up to u64::MAX:

xquad vm run countloop.xqb --step-limit 18446744073709551615

also runs to completion, but for a different reason: the limit is higher, not absent. A budget that exactly covers the program succeeds – --step-limit 14 runs countloop.xqb to completion, and --step-limit 13 does not.

Output

After execution, xquad vm run prints, in order:

1. Outputs – every output slot that was written, with its index and value.
2. Stack – any values remaining on the value stack, bottom to top.

A run that both writes outputs and leaves values on the stack prints both sections:

outputs:
  [0] = Int(42)
  [1] = VecInt([1, 2, 3])
stack (bottom to top):
  7

Error reporting

A runtime fault is one line on stderr naming the VM error and the byte offset it happened at, and the command exits 1. underflow.xqb is PUSH 1 / ADD / HALT: ADD needs two stack values and only one was pushed.

xquad vm run underflow.xqb

Error: run failed: StackUnderflow { pos: 2 }

xquad vm dis underflow.xqb shows the ADD at 0x0002. The trace options above write the steps that led there.