Skip to main content

CLI

Invocation and run-time flags for the ziskemu binary, which emulates a guest ELF, a WebAssembly binary, or ZisK assembly against an input and writes the output, with no proof generated. Documents the program-input, execution, randomness, output, quick-check, trace, and diagnostic flags, and the exit status.

ziskemu converts a guest ELF (or a WebAssembly binary) into a ZisK ROM, or assembles ZisK assembly, emulates it against the provided input, and writes the output to the console or a file. No proof is generated. For the profiling reports see Statistics & reports and Function analysis.

ziskemu [OPTIONS] [CHUNK_SIZE]

You must provide the program in exactly one form: an ELF or WebAssembly binary (--elf) or ZisK assembly (--zisk). The flags are mutually exclusive. --rom is also accepted but not implemented in 1.4.0-alpha (see below).

When --elf names a directory, ziskemu runs in RISCOF directory mode: it emulates every *dut*.elf file found under it, silently (no output for the directory as a whole).

Not working in 1.4.0-alpha
  • --rom (-r) is not implemented: it panics for any file (ZiskRom::get_instruction() pc=0x1000 … is out of range). Use --elf.
  • The positional CHUNK_SIZE argument panics. Omit it.
  • --trace (-t) writes nothing.
  • --log-output-riscof (-f) panics on normal guests (it is meant for the RISCOF test suite).
  • --legacy-stats (-x) reports zeros. Use -X or --sdk -X.

Program input​

FlagShortDefaultDescription
--elf <ELF_FILE>-e—Guest program to convert to a ZisK ROM and emulate: a RISC-V ELF or a WebAssembly binary (detected from its magic bytes; see WASM guests).
--rom <ROM_FILE>-r—Prebuilt ZisK ROM to emulate. Not implemented in 1.4.0-alpha: panics for any file.
--zisk <FILE_OR_DIR>-z—ZisK assembly to assemble and emulate: one .zisk file, or a directory of .zisk files. See ZisK assembly.
--inputs <INPUT_FILE>-i—Input data file fed to the guest. Omit for no input.
--legacy-inputs <FILE>—Input data file in the legacy format.
--output <OUTPUT_FILE>-o—Write the guest output to this file instead of (or alongside) the console.

Execution​

FlagShortDefaultDescription
--max-steps <MAX_STEPS>-n68719476735Maximum number of steps to execute before stopping.
--print-step <PRINT_STEP>-p0Print progress every N steps (0 disables).
--max-input-mem <BYTES>134217728Maximum input memory (default 128 MiB).

The --max-input-mem default is still 128 MiB, below the 2 GB the platform accepts. To emulate a larger input, raise it, for example --max-input-mem 2147483648. See Limits.

Host randomness​

FlagEnvDefaultDescription
--random-seed <HEX>ZISK_RANDOM_SEEDrandomSeed of the host randomness generator (zkvm_random_u64): up to 64 hex characters, zero-padded on the left. Without it, each run draws a fresh seed.

Unlike cargo-zisk, ziskemu prints the seed it used (Random seed: <HEX>) only with -v, so by default stdout carries only the guest output. To replay a run, pass the same seed. See Host randomness.

Output and logging​

FlagShortDefaultDescription
--log-output-cfalsePrint the guest's committed public outputs to the console, one 32-bit word per line in hex. The guest's stdout is printed with or without it.
--log-output-riscof-ffalsePrint the guest output in RISCOF format. Panics on normal guests.
--verbose-vfalseVerbose logging.
--log-step-lfalseLog step progress.
--log-metrics-mfalseLog performance metrics for the run.

Quick checks​

Lightweight flags for fast runs and machine-readable output:

FlagDefaultDescription
--stepsfalsePrint only the step count, skipping full statistics.
--with-progressfalsePrint a progress update every 16M steps for long runs.
--no-thousands-sepfalseDrop the thousands separator in the ROI / function tables. Other report sections keep it.

Traces and coverage​

FlagShortDefaultDescription
--coveragefalseShow coverage of opcodes and precompiles (requires -X).
--generate-minimal-traces-gfalseGenerate minimal execution traces.
--trace <TRACE_FILE>-t—Write an execution trace to a file. Writes nothing in 1.4.0-alpha.
--store-op-output <FILE>-s—Store the operands of every arithmetic and binary operation to a file, as 17-byte records: the opcode (1 byte), then a and b (8 bytes each, little-endian). Requires -X.
--disasm <DISASM_FILE>—Write a disassembly annotated with execution counts (requires -S -X).

Instruction traces​

These print to stdout as the program runs. All of them force full, non-fast emulation, so expect a slower run and — on real programs — a very large amount of output. Redirect stdout to a file.

FlagDefaultDescription
--trace-stepsfalsePrint every executed instruction: step, pc, opcode, a/b/c, flag, and the decoded instruction. Unlike --log-step this works in release builds.
--trace-from <STEP>—First step of the change-trace window. Defaults to 0 when only --trace-to is given.
--trace-to <STEP>—Last step (inclusive) of the change-trace window. Defaults to unbounded when only --trace-from is given.

--trace-from / --trace-to open a window in which each executed instruction is followed by every register and stack write it caused, formatted as prev (0xhex) => post (0xhex). Register writes are shown by register name; stack writes are RAM writes in [RAM_ADDR, SYS_ADDR) and additionally show the absolute address and its offset relative to sp (x2).

# Dump the instructions and the state they changed around a suspect step
ziskemu -e program.elf -i input.bin --trace-from 1200000 --trace-to 1200500 > window.log

Advanced & diagnostic​

FlagShortDefaultDescription
--with-memory-datatrueLoad data sections into memory so they can be read during full emulation (off in chunk-player mode). Always on: there is no way to disable it.
--tracerv-afalseEnable the RISC-V tracer.
--legacy-stats-xfalseGenerate the legacy step/usage statistics report (superseded by -X / --sdk). Reports zeros in 1.4.0-alpha.
--reg-step-checkfalseOne-line verdict on register step distances. Runs on the fast emulation path and does not need -X — see Register step distance.

Build features​

Two features of the ziskemu crate change what the emulator accepts. They are off by default, so they apply only when you build ziskemu from source with --features:

FeatureEffect
compressedDecode the RISC-V C (compressed) extension in the transpiler.
floatSupport floating-point instructions in the RISC-V and WebAssembly transpilers through the ZisK float library.

Exit status​

ziskemu exits with 0 only when the guest runs to completion and exits with code 0. A failed execution is never a success:

FailureMessage on stderrExit status
Guest exits with a nonzero code NError during emulation: guest exited with code NThe low 8 bits of N, or 1 if they are 0
Trap (unimp, ebreak, a write to a read-only CSR)Error during emulation: ExecutionFailed { reason: Trap, step: …, pc: … }1
Any other emulation errorError during emulation: …1
Bad command-line arguments (rejected by the argument parser)error: … and the usage line2
Panic (for example --rom, CHUNK_SIZE, -f)thread 'main' … panicked at …101

A failed execution can't be proven, so check the exit status in scripts before you move on to proving.

note

ziskemu exposes further advanced and diagnostic flags. Run ziskemu --help for the complete, version-exact list.

Examples​

Run an ELF and print its output:

ziskemu -e program.elf -i input.bin -c

Run a ZisK assembly file:

ziskemu -z program.zisk

Cap the step count and print progress while running:

ziskemu -e program.elf -i input.bin -n 5000000 -p 1000000 -c

To profile a run, add -X (and -S for function-level detail) — see Statistics & reports and Function analysis.