Skip to main content

Function analysis

Symbol-based ziskemu profiling, unlocked with -S / --read-symbols. Covers Regions of Interest (top-cost functions), function-name display, the PC histogram, call-argument tracking, and the Firefox Profiler export.

The views on this page need symbols. Add -S / --read-symbols to read the function names already present in the ELF (no instrumentation or debug build required) — then ziskemu can attribute cost to functions, group hot instructions, and track calls.

Regions of Interest​

With symbols loaded, the report ranks the most expensive functions — its Regions of Interest (ROI).

ziskemu -e program.elf -i input.bin -X -S
FlagShortDefaultDescription
--read-symbols-SfalseLoad function names/symbols from the ELF. Required for all function-level views.
--top-roi <N>-T25Number of top functions to display.
--top-roi-detail-DfalseDetailed breakdown per top function: where its cost comes from and who calls it.
--roi-callers <N>-C10Number of top callers to show per function (with -D).
--roi-filter <REGEX>—Mark functions whose name matches the regular expression as ROIs.
--top-roi-filterfalseShow only functions matching --roi-filter in the top lists.
--main-name <NAME>-MmainName of the program's entry-point function.

ZisK library functions​

The ZisK library code that the transpiler merges into the ROM has no ELF symbols. When a guest calls into it through zkvmcalls, ziskemu finds the library functions from the ROM itself and adds one ROI per function, named after the library's labels, for example ziskasm_zkvm_modexp. A function with no label is named after its address, as zisklib@0x<address>. Functions that share code are merged into one ROI named a|b. The run reports how many it added:

Added <N> ZisK library ROIs

These ROIs rank, filter, and show detail like any other function.

# Show only the EVM opcode implementations, top 200, by cost
ziskemu -e guest.elf -i input.bin -X -S \
--roi-filter "revm_interpreter::instructions::" --top-roi-filter -T 200

Call-stack tracking​

Attributing cost to callers means reconstructing the call stack from the executed instructions, and that heuristic can lose sync. GCC/C++ tail-recursion is the usual cause: a single machine ret unwinds several nested self-recursive frames that were tracked as separate calls — std::sort's __introsort_loop is the classic example.

FlagDefaultDescription
--callstack-mode <MODE>autoauto resyncs on a mismatch by discarding the collapsed frames until the one that returns into the current function. strict is the original behaviour: report STACK MISMATCH DETECTED and disable call-stack tracking for the rest of the run.

A zkvmcall reaches its ZisK library routine with a tail jump rather than a call, and the routine's ret returns straight to the guest caller. Call-stack tracking treats these jumps, and jumps between library functions, as tail calls, so the library cost is charged to the right caller.

Use strict when you want to know that the stack went out of sync rather than have it silently repaired — the caller attribution after a resync is a best guess.

Duplicate precompile calls by call path​

--duplicates-detail extends the duplicate-precompile analysis with the call paths the repeated calls came from, which needs symbols. See Precompile duplicates.

Function name display​

Rust symbols can be long. These flags control how function names are rendered in the reports:

FlagDefaultDescription
--compact-names <N>160Truncate displayed function names to N characters.
--no-compact-namesfalseDisable name truncation; show full names.

PC histogram​

-H / --top-histogram gives an instruction-level view: the most frequently executed program-counter addresses, grouped into sequences and attributed to their function when symbols are loaded. Useful for spotting hot loops.

ziskemu -e program.elf -i input.bin -X -S -H 50

The number after -H controls how many instruction groups to display; -S is required to resolve function names.

Function-call tracking​

Combine --roi-filter with --track-call-args to log the argument values of each call to matching functions — handy for finding common parameter patterns. Up to 8 arguments (RISC-V a0–a7) can be logged.

FlagDefaultDescription
--roi-filter <REGEX>—Functions to track (required).
--track-call-args <N>0Number of arguments to log per call (1–8). 0 disables tracking.
--track-separator <SEP>;Separator between argument values in the output.
--track-output-path <DIR>.Directory where one <function>.txt file per matched function is written. The file name is the function path with every non-alphanumeric character dropped, e.g. ziskosziskliblibkeccak256keccak256.txt for ziskos::zisklib::lib::keccak256::keccak256.
ziskemu -e guest.elf -i input.bin -S \
--roi-filter "hash_function" --track-call-args 4 --track-output-path ./traces

Firefox Profiler export​

--profiler-output writes the run as a Firefox Profiler trace you can load at profiler.firefox.com for interactive, flame-graph–style analysis. The trace is written only when you pass this flag together with -X -S, or when you run cargo-zisk run --profiling complete. Without -X -S the flag is silently ignored, and -X -S on its own does not write the trace either. Passing the flag without a value writes profile.json.gz.

# Compressed (recommended) or plain JSON
ziskemu -e program.elf -i input.bin -X -S --profiler-output=profile.json.gz

Putting it together​

A comprehensive profiling pass — statistics, symbols, detailed callers, histogram, a focused ROI filter, and call tracking:

ziskemu -e program.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

For a guided, tutorial-style walkthrough of this workflow, see Profiling in depth.