Profiling in depth
ziskemu is ZisK's advanced emulator and profiler. This tutorial drives it directly to
find exactly what makes a guest expensive to prove, the costly functions, the
hot instructions, and the operations that dominate.
It is the deep companion to Profiling your program,
which uses the friendly cargo-zisk run --profiling wrapper on a merkle-tree
example. The concepts introduced there — the profiling-vs-proving-cost
trade-off, the cost-report categories, basic cost markers, and the Firefox
call-stack view — aren't repeated here; this guide adds the full ziskemu
toolset on top.
You only need a compiled guest ELF and an input. Build one with
cargo-zisk build --release (the ELF lands at
target/elf/riscv64ima-zisk-zkvm-elf/release/<name>), then point -e at
it and -i at your input. Every command below has the same shape, shortened to
ziskemu -e <elf> -i <input> …:
ziskemu -e target/elf/riscv64ima-zisk-zkvm-elf/release/<name> -i input.bin -X
The reports shown below come from a larger program — a stateless block
validator built on reth and revm, run on one OP Mainnet block — so every
section has rich data to read. All figures are at cost version 1; see
Cost model. Your own guest prints the
same shapes, just smaller. ziskemu runs the guest and analyzes it; it never
generates a proof, which is what makes it fast to iterate with.
Profiling cost vs. final cost
You optimize against profiling cost: the per-operation cost that moves proportionally with your code, so every change shows up immediately. The final cost — what you actually pay to prove — is measured per instance (operations are batched into fixed-capacity state-machine instances), so it stays flat and then jumps when you cross a boundary. The companion tutorial summarizes this in Understanding profiling importance; two consequences are worth internalizing:
- Instance boundaries. 1 or 31,068 Keccak operations both cost one Keccak instance; the 31,069th needs a second — doubling that cost for a single extra operation. Profiling cost, in contrast, rises smoothly with each operation.
- Specialized instances. ZisK has a cheap
BinaryAddinstance for 64-bit additions versus the generalBinaryinstance (ADD, SUB, AND, OR, XOR, …). So 1MADDs profile cheaper than 1MORs — and profiling cost shows that consistently, while final cost only reveals it once the program is large enough to split instances. The planner also picks strategies from your operation mix, and a function's final cost aggregates everything it calls.
Optimize with profiling cost; confirm the savings with final cost.
What profiling can tell you
Profiling reads the symbols already in your ELF, so it works on optimized release builds with no instrumentation, no special build flags, and no runtime overhead. For the questions it helps you answer — which crate is cheapest to prove, whether a change helped, whether precompiles are applied, and where to patch — and the optimize-then-re-profile workflow, see Understanding profiling importance.
The statistics report (-X)
-X (or --stats) is the first command to run — overall cost plus a
per-operation breakdown:
ziskemu -e <elf> -i <input> -X
REPORT (cost version 1)
----------------------------------------
STEPS 196,958,502
COST DISTRIBUTION COST %
------------------------------------------------
MAIN 12,211,427,124 59.52%
OPCODES 2,324,733,913 11.33%
PRECOMPILES 3,309,455,321 16.13%
MEMORY 2,384,861,950 11.62%
------------------------
VARIABLE 20,230,478,308 98.61%
BASE 285,212,672 1.39%
------------------------
TOTAL 20,515,690,980 100.00%
FROPS 1,881,599,426 9.30%
RAM USAGE 36,149,769 6.79%
ROM USAGE 430,947 10.27%
ROM REGIONS STEPS %
------------------------------------------------
LOW (< ROM) 189 0.00%
PROGRAM ROM 196,958,313 100.00%
ZISKLIB ROM 0 0.00%
FLOAT ROM 0 0.00%
STEPS is the instruction count — how long the run is. COST DISTRIBUTION
is the profiling cost. Four categories depend on your program: MAIN (the
processor itself, proportional to STEPS), OPCODES (simple 64-bit arithmetic and
logic), PRECOMPILES (operations too big for 64 bits — 256-bit math, elliptic
curves, Keccak, DMA), and MEMORY (reads, writes, and the extra cost of
non-aligned or sub-8-byte access). Their sum is VARIABLE. BASE is the fixed
overhead of the ROM and tables, the same for every program, and TOTAL adds it. Whichever
dominates tells you what kind of work is expensive; the companion tutorial
explains each on a real program in
Cost distribution summary.
A few extra lines round it out: FROPS — frequent operations like adding 1
(loop counters), adding 8 (pointers), or values < 256, which ZisK pre-computes
into BASE; the figure is what you'd pay without that optimization, as a share
of VARIABLE — RAM USAGE, reported only with the default bump allocator,
ROM USAGE, and ROM REGIONS, the steps spent in the program, in the ZisK
library, and in the float library.
Below the summary comes the per-opcode breakdown (excerpt):
COST BY BASE OPCODE COUNT % COST %
------------------------------------------------------------------------
OP and 8,976,502 4.56% 493,707,610 2.44%
OP ltu 5,218,673 2.65% 287,027,015 1.42%
OP add 21,454,761 10.89% 265,133,088 1.31%
…
COST BY PRECOMPILED OPCODE COUNT % COST %
--------------------------------------------------------------------------
OP keccak 66,401 0.03% 2,756,504,713 13.63%
OP dma_xmemcpy 1,811,880 0.92% 334,189,307 1.65%
…
FROPS BY OPCODE COUNT HIT COST %
-----------------------------------------------------------------------
FROP eq 9,670,796 87.41% 531,893,780 2.63%
FROP ltu 7,172,892 57.89% 394,509,060 1.95%
FROP and 3,953,249 30.57% 217,428,695 1.07%
…
Base opcodes and precompiles get separate tables. Each row shows the COUNT, its
share of steps, its total COST, and its share of VARIABLE cost. Rows are
sorted by cost, highest first, so the costly ones are at the top; add
--sort-by-units to sort by COUNT instead. The habit that matters most:
compare COUNT against the cost %. Here keccak ran only 66,401 times (0.03%
of steps) yet is 13.63% of the variable cost — rare but expensive, the
textbook optimization target. The FROPS table adds a HIT column: how often
the pre-computed pattern matched.
Find the expensive functions (-S)
Add -S (or --read-symbols) to attribute cost to functions. ZisK simulates the
call stack and charges each function cumulatively — its own code plus
everything it calls (the _start / main frames are filtered out, since they
would always be 100%):
ziskemu -e <elf> -i <input> -X -S
You get two rankings. By cost — usually the one you act on:
TOP COST FUNCTIONS (COST, % VARIABLE COST, CALLS, COST/CALL, FUNCTION)
----------------------------------------------------------------------
15,761,295,098 77.91% 1 15,761,295,098 <reth_evm::execute::BasicBlockExecutor<…> as reth_evm::exec
15,364,142,388 75.95% 59 260,409,193 <op_revm::handler::OpHandler<…> as revm_handler::handler::H
3,382,429,366 16.72% 26,700 126,682 ziskos::zisklib::lib::keccak256::keccak256
3,023,880,011 14.95% 1 3,023,880,011 <tries::zeth::SparseState as tries::StatelessTrie>::new
2,859,161,019 14.13% 11,263 253,854 revm_interpreter::instructions::host::sload::<revm_interpre
…
…and a parallel TOP STEP FUNCTIONS ranked by cycles instead of cost.
Comparing the two is revealing: keccak256 is 3.12% of steps but 16.72% of
the variable cost. A function whose cost share dwarfs its cycle share is doing expensive
per-cycle work (a precompile) and is worth a close look.
Tune the view as you go: -T / --top-roi N shows more or fewer functions;
-M / --main-name names a non-standard entry point; and --roi-filter "<regex>" marks functions of interest (add --top-roi-filter to show only
matches — ideal for comparing implementations of one subsystem). Rust names get
long, so they're compacted to 160 characters by default (collapsing nested
generics and eliding path segments); adjust with --compact-names=N or
--no-compact-names.
Why a function is expensive (-D)
Once you know which function, -D (or --top-roi-detail) shows why: for each
top function, a cost-by-opcode breakdown scoped to that function, plus its top
callers.
ziskemu -e <elf> -i <input> -X -S -D
DETAIL FUNCTION ziskos::zisklib::lib::keccak256::keccak256
----------------------------------------------------------
| STEPS 6,141,874 3.12%
| MAIN COST 380,796,188 11.26%
| OPCODES COST 56,186,602 1.66%
| PRECOMPILES COST 2,778,032,067 82.13%
| MEMORY COST 167,414,509 4.95%
| -----------------------
| TOTAL COST 3,382,429,366 100.00%
| COST BY OPCODE COUNT % COST %
| ------------------------------------------------------------------------
| OP keccak 66,401 1.08% 2,756,504,713 81.49%
| OP xor 933,742 15.20% 51,355,810 1.52%
| OP dma_xmemset 53,400 0.87% 9,905,700 0.29%
| OP dma_memcpy 26,700 0.43% 7,186,883 0.21%
| OP dma_xmemcpy 26,700 0.43% 4,434,771 0.13%
| OP add 169,311 2.76% 2,031,732 0.06%
| OP and 26,700 0.43% 1,468,500 0.04%
| OP ltu 16,315 0.27% 897,325 0.03%
| OP sub 7,877 0.13% 433,235 0.01%
| TOP STEP CALLERS (calls, steps)
| -------------------------------
| 10,479 3,660,778 59.60% <tries::zeth::SparseState as tries::StatelessTrie>::new
| 5,407 650,394 10.59% revm_interpreter::instructions::system::keccak256::<revm_interpre
| 4,659 559,080 9.10% <revm_database::states::state::State<op_stateless::witness_db::Wi
| …
The cost lines and the opcode table are scoped to this one function: precompiles
are 82.13% of its cost and keccak alone 81.49%, so the hashing itself is the
target, not the surrounding code. TOP STEP CALLERS reverses the view — who
calls it and how much each is responsible for. SparseState::new makes 10,479 of
the 26,700 calls and accounts for 59.60% of the function's steps, so that's the
path to investigate first.
-C / --roi-callers N controls how many callers are listed (default 10).
Instruction-level hotspots (-H)
To go below functions — to the exact instructions that run most often — use the
PC histogram, -H (or --top-histogram). It groups consecutive hot instructions and
attributes each group to its function (with -S):
ziskemu -e <elf> -i <input> -X -S -H 50
TOP PC HISTOGRAM (EXECUTIONS, % EXECUTIONS, PC)
-----------------------------------------------
2,591,985 1.32% 0x9007aae0: ld r10, 0xc0(r19)
2,591,985 1.32% 0x9007aae4: lbu r11, 0x0(r10)
…
2,591,985 1.32% 0x9007ab20: beq r11, r0, 0xffffffc0
44,063,745 22.37% ----------- <op_revm::handler::OpHandler<…> as revm_handler::handler::Handler>::execution
1,248,595 0.63% 0x900e4f1c: addi r17, r12, 0x0 => copyb
1,248,595 0.63% 0x900e4f20: lbu r12, 0x0(r15)
1,248,595 0.63% 0x900e4f24: beq r12, r14, 0xffffffd0
3,745,785 1.90% ----------- revm_bytecode::legacy::analysis::analyze_legacy
Each group is a run of instructions (executions, % of steps, address, the RISC-V instruction) followed by a dashed summary line with the group's total and its function. The first group above is a 17-instruction dispatcher loop — the EVM interpreter's opcode fetch and dispatch, 22.37% of the whole program — a prime target, and the second is a tight 3-instruction byte-scanning loop in bytecode analysis at 1.90%. Reach for the histogram after function-level profiling: it shows which lines inside a hot function are the hot loop, and confirms whether a compiler optimization actually landed.
Measure your own code: profile tags
To measure a region you choose — an algorithm, a loop, a critical section —
wrap it in profile-tag macros from ziskos. The companion tutorial adds a pair
to a guest step by step in
Using inline cost markers;
here is the full set. The macros have zero overhead outside the profiler and
measure either cost or steps, reporting either immediately (printed at
each end!) or as an accumulated end-of-run summary — eight macros in a 2×2:
| Report style | Cost | Steps |
|---|---|---|
| Immediate | profile_start! / profile_end! | profile_steps_start! / profile_steps_end! |
| Accumulated | profile_report_start! / profile_report_end! | profile_report_steps_start! / profile_report_steps_end! |
Use immediate for sections that run a few times, accumulated for sections that run
many. Each macro takes a bare label and must be closed by its matching end! with
the same label. You can nest and mix cost and steps, immediate and accumulated
tags, but they share one stack: each end! must close the most recently opened
tag, or the profiler aborts the run with Profile tag mismatch:
profile_start!(total); // cost of the whole run
for i in 0..100 {
profile_report_steps_start!(iteration); // accumulated steps per iteration
expensive_computation(i);
profile_report_steps_end!(iteration);
}
profile_report_start!(hash_phase); // accumulated cost
for item in items { compute_hash(item); }
profile_report_end!(hash_phase);
profile_end!(total);
A guest that contains profile_*! markers can be run and profiled, but
not proven: cargo-zisk prove fails with VerifyGlobalConstraints,
and with --asm it panics with Internal opcode Profile. Keep the
markers in a separate binary and prove the clean one.
-X prints the accumulated (report) tags at the end of the full report.
Add --profile-tags to print only the summary and the tags: the flag selects
sections, so the opcode tables and function rankings are left out. For the
inline-guest of the companion tutorial, which wraps its two phases in
cost and steps report tags:
ziskemu -e <elf> -i <input> -X --profile-tags
PROFILE TAGS STEPS (STEPS, % STEPS, CALLS, AVG, MIN, MAX)
----------------------------------------------------------------------------------
5,790,980 66.32% 1 5,790,980 5,790,980 5,790,980 COMPUTE_ROOT
2,937,047 33.63% 1 2,937,047 2,937,047 2,937,047 PREPARE_LEAVES
PROFILE TAGS COST (COST, % COST, CALLS, AVG, MIN, MAX)
----------------------------------------------------------------------------------
587,633,598 66.44% 1 587,633,598 587,633,598 587,633,598 COMPUTE_ROOT
296,448,956 33.52% 1 296,448,956 296,448,956 296,448,956 PREPARE_LEAVES
Each tag reports its total, share of steps or of the variable cost, call count, and the average, minimum, and maximum per call. Name tags descriptively and keep one tag per logical section — profile tags answer what is expensive, while the function rankings answer where.
Explore visually: the Firefox Profiler
For an interactive call graph — flame graphs, a timeline, search — export with
--profiler-output and open it at profiler.firefox.com
(Load a profile from file). Both -X and -S are required: without -X,
--profiler-output silently writes nothing. -X -S on its own does not write
the file either: pass --profiler-output, which defaults to profile.json.gz
when given no value. A name without .gz (for example
--profiler-output=profile.json) writes plain, uncompressed JSON. The companion
tutorial produces the same file via cargo-zisk run --profiling complete and
tours the views in
Exploring the call stack.
The output follows the
Firefox Profiler format spec,
so other compatible tools can read it too.
ziskemu -e <elf> -i <input> -X -S --profiler-output=profile.json.gz
More tools and a workflow
A few smaller tools round out the toolset:
-
Inspect call arguments. Pair
--roi-filterwith--track-call-args N(1–8 arguments, the RISC-Va0–a7registers) to log each call's arguments to a<function>.txtfile (one line per call).--track-separatorsets the delimiter (default;) and--track-output-paththe directory. It logs the raw register values — the actual value for scalars, but only the address for pointers — so it is best for scalar arguments or address patterns.bashziskemu -e <elf> -i <input> -S \--roi-filter "hash_function" --track-call-args 4 --track-output-path ./traces -
Quick checks.
--stepsprints only the step count;--with-progressreports progress every 16M steps on long runs;--no-thousands-sepgives machine-readable numbers. -
Everything at once. The flags compose — full statistics, symbols, detailed callers, 30 functions, 15 callers each, 50 instruction groups, a filter, argument tracking, and performance metrics (
-m):bashziskemu -e <elf> -i input.bin -X -S -D -T 30 -C 15 -H 50 \--roi-filter "sha256|hash" --track-call-args 6 --track-output-path ./profiling_data -m
A workflow that scales: start with -X, add -S to see the functions, -D
to see why they're expensive, and -H to see the hot instructions — then apply a
precompile or patch (see Optimizing your program)
and re-run to confirm the cost dropped. Chase the big percentages, profile
realistic inputs, and filter with --roi-filter in large codebases.
Worked example: which EVM opcodes cost the most?
Putting it together on a real program: to rank the cost of individual Ethereum opcodes in a stateless block validator, filter to the EVM interpreter's instruction functions — they all live under one namespace — and show only those:
ziskemu -S -X \
-e .../release/<block-validator> \
-i .../inputs/<block>.bin \
--roi-filter "revm_interpreter::instructions::" --top-roi-filter -T 200
TOP COST FUNCTIONS (COST, % VARIABLE COST, CALLS, COST/CALL, FUNCTION)
----------------------------------------------------------------------
2,859,161,019 14.13% 11,263 253,854 revm_interpreter::instructions::host::sload::<revm_interpre
830,635,321 4.11% 4,254 195,259 revm_interpreter::instructions::contract::call_helpers::loa
514,778,471 2.54% 2,478 207,739 revm_interpreter::instructions::contract::call::<250, revm_
475,657,830 2.35% 61,738 7,704 revm_interpreter::instructions::memory::mstore::<revm_inter
459,576,693 2.27% 122,284 3,758 revm_interpreter::instructions::stack::swap::<1, revm_inter
448,376,211 2.22% 242,442 1,849 revm_interpreter::instructions::stack::push::<2, revm_inter
322,914,275 1.60% 5,407 59,721 revm_interpreter::instructions::system::keccak256::<revm_in
305,536,614 1.51% 116,110 2,631 revm_interpreter::instructions::arithmetic::add::<revm_inte
…
From this single view you see the most expensive opcodes (sload at the top,
then the call family), the most frequently called ones (swap/push, with huge
call counts but small per-call cost), and the best optimization targets. No modification to the
ELF is needed — profiling reads the existing symbols; the only thing to know is
the naming convention of the functions you want to filter.
Where to go next
- Profiling your program — the hands-on
walkthrough with
cargo-zisk run --profiling, if you skipped it. - Optimizing your program — act on what you found by routing expensive work through ZisK precompiles, then re-profile.
- ziskemu CLI reference — the complete flag list.