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).
--rom(-r) is not implemented: it panics for any file (ZiskRom::get_instruction() pc=0x1000 … is out of range). Use--elf.- The positional
CHUNK_SIZEargument 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-Xor--sdk -X.
Program input
| Flag | Short | Default | Description |
|---|---|---|---|
--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
| Flag | Short | Default | Description |
|---|---|---|---|
--max-steps <MAX_STEPS> | -n | 68719476735 | Maximum number of steps to execute before stopping. |
--print-step <PRINT_STEP> | -p | 0 | Print progress every N steps (0 disables). |
--max-input-mem <BYTES> | 134217728 | Maximum 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
| Flag | Env | Default | Description |
|---|---|---|---|
--random-seed <HEX> | ZISK_RANDOM_SEED | random | Seed 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
| Flag | Short | Default | Description |
|---|---|---|---|
--log-output | -c | false | Print 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 | -f | false | Print the guest output in RISCOF format. Panics on normal guests. |
--verbose | -v | false | Verbose logging. |
--log-step | -l | false | Log step progress. |
--log-metrics | -m | false | Log performance metrics for the run. |
Quick checks
Lightweight flags for fast runs and machine-readable output:
| Flag | Default | Description |
|---|---|---|
--steps | false | Print only the step count, skipping full statistics. |
--with-progress | false | Print a progress update every 16M steps for long runs. |
--no-thousands-sep | false | Drop the thousands separator in the ROI / function tables. Other report sections keep it. |
Traces and coverage
| Flag | Short | Default | Description |
|---|---|---|---|
--coverage | false | Show coverage of opcodes and precompiles (requires -X). | |
--generate-minimal-traces | -g | false | Generate 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.
| Flag | Default | Description |
|---|---|---|
--trace-steps | false | Print 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
| Flag | Short | Default | Description |
|---|---|---|---|
--with-memory-data | true | Load 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 | -a | false | Enable the RISC-V tracer. |
--legacy-stats | -x | false | Generate the legacy step/usage statistics report (superseded by -X / --sdk). Reports zeros in 1.4.0-alpha. |
--reg-step-check | false | One-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:
| Feature | Effect |
|---|---|
compressed | Decode the RISC-V C (compressed) extension in the transpiler. |
float | Support 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:
| Failure | Message on stderr | Exit status |
|---|---|---|
Guest exits with a nonzero code N | Error during emulation: guest exited with code N | The 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 error | Error during emulation: … | 1 |
| Bad command-line arguments (rejected by the argument parser) | error: … and the usage line | 2 |
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.
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.