CLI
Invocation and run-time flags for the ziskemu binary, which emulates a RISC-V ELF (or prebuilt ROM) against an input and writes the output, with no proof generated. Documents the program-input, execution, output, quick-check, trace, and diagnostic flags.
ziskemu converts a RISC-V ELF into a ZisK ROM (or loads a prebuilt
ROM), 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 either as an ELF (--elf) or as a prebuilt
ROM (--rom). The optional positional CHUNK_SIZE traces every that-many
steps (used by the chunk player).
Program input
| Flag | Short | Default | Description |
|---|---|---|---|
--elf <ELF_FILE> | -e | — | RISC-V ELF to convert to a ZisK ROM and emulate. |
--rom <ROM_FILE> | -r | — | Prebuilt ZisK ROM to emulate, instead of converting an ELF. |
--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). |
Output and logging
| Flag | Short | Default | Description |
|---|---|---|---|
--log-output | -c | true | Print the guest output to the console (on by default). |
--log-output-riscof | -f | false | Print the guest output in RISCOF format. |
--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 for machine-readable output. |
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. |
--store-op-output <FILE> | -s | — | Store operation data to a file for analysis. |
--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). | |
--tracerv | -a | false | Enable the RISC-V tracer. |
--legacy-stats | -x | false | Generate the legacy step/usage statistics report (superseded by -X / --sdk). |
--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. |
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
Load a prebuilt ROM instead of converting an ELF each time:
ziskemu -r program.rom -i input.bin -c
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.