ziskemu
ziskemu is the ZisK emulator and profiler. It converts a RISC-V ELF into a ZisK ROM (or loads a prebuilt ROM), executes it against an input, and — beyond just running the program — reports detailed cost and performance statistics so you can find hotspots and validate optimizations. It never generates a proof.
What it is
ziskemu is the low-level emulator that cargo-zisk run and cargo-zisk execute build on, and it is the tool ZisK exposes for profiling.
Its job is twofold:
- Run a compiled guest outside of a Cargo project — convert an ELF to a ZisK ROM (or load a prebuilt ROM), feed it an input, and capture the output.
- Profile that run — break the execution cost down by category and by opcode, rank the most expensive functions, and surface the instruction-level hotspots that drive proving cost.
It does not prove anything. Use it to check that a guest produces the
right output and to understand where its cost goes, then move to
cargo-zisk prove or the
SDK to generate a proof.
A key advantage: profiling works on any ELF that carries symbols,
including optimized release builds. No special instrumentation, debug
build, or recompilation is required — ziskemu reads the symbol
information already present in the binary.
Profiling cost vs. final cost
When reading a ziskemu report it helps to distinguish two notions of cost:
- Profiling cost — the individual operational cost accrued directly within a function's own instructions, using the best-case cost model for each operation. It has a direct cause-and-effect relationship with code changes: replace a loop with a precompile and the profiling cost drops proportionally. This is the metric to optimize against.
- Final cost — the real cost of an execution in the ZisK proving system, measured at instance granularity. Operations are grouped into instances (state-machine execution units), so cost can stay flat until you cross an instance boundary and then jump. It reflects true proving cost but is less predictable for incremental optimization.
Optimize using profiling cost (consistent, proportional), then read final cost to understand the real savings in production.
Basic usage
Run a guest ELF against an input and print its output:
ziskemu -e program.elf -i input.bin -c
Load a prebuilt ZisK ROM instead of converting an ELF each time:
ziskemu -r program.rom -i input.bin -c
Profile the run — overall cost distribution and opcode breakdown:
ziskemu -e program.elf -i input.bin -X
Add symbols to attribute cost to functions (Regions of Interest):
ziskemu -e program.elf -i input.bin -X -S
From here, see CLI for the run-time flags, Statistics & reports for the cost reports, and Function analysis for symbol-based profiling.