Profiling
Profiling in ZisK is cost-accurate: every instruction executed inside a labeled region is counted and attributed to that region. Use the profiling macros to identify which parts of your guest program drive up cost or step count before they become expensive at scale.
Overview
Profiling attributes proving work to specific regions of guest code. You wrap a region and the work spent inside is recorded against that label, so you can see which parts of a program dominate proof generation. Two quantities are measurable:
| Quantity | Description |
|---|---|
| Cost | Proving work for the region, weighted by instruction mix. |
| Steps | Raw RISC-V instruction count for the region. |
Accumulated report
These macros record region boundaries in the execution trace. Nothing is printed at runtime; the external profiler tool reads the trace after the run and accumulates results across regions.
profile_report
The pair profile_report_start! / profile_report_end! opens and
closes a named region whose proving cost is recorded in the
execution trace.
profile_report_start!(label)
// code to be profiled.
profile_report_end!(label)
Parameters
| Name | Type | Description |
|---|---|---|
label | identifier | A bare identifier that names the region. The matching profile_report_end! must be called with the same identifier. |
Example
use sha2::{Digest, Sha256};
let mut hasher = Sha256::new();
ziskos::profile_report_start!(HASH_LOOP);
for value in &input.values {
hasher.update(value.to_le_bytes());
}
let digest = hasher.finalize();
ziskos::profile_report_end!(HASH_LOOP);
profile_report_steps
The pair profile_report_steps_start! / profile_report_steps_end!
opens and closes a named region whose RISC-V step count is recorded
in the execution trace.
profile_report_steps_start!(label)
// code to be profiled.
profile_report_steps_end!(label)
Example
use sha2::{Digest, Sha256};
let mut hasher = Sha256::new();
ziskos::profile_report_steps_start!(HASH_LOOP);
for value in &input.values {
hasher.update(value.to_le_bytes());
}
let digest = hasher.finalize();
ziskos::profile_report_steps_end!(HASH_LOOP);
Inline reports
These macros print the measurement as [LABEL] N each time the
region closes, but only when the emulator collects statistics
(ziskemu -X, or cargo-zisk run -p inline). A plain
run prints nothing. Inline regions do not appear in the PROFILE TAGS
tables of the report; only the profile_report_* regions do.
profile
The pair profile_start! / profile_end! measures the proving cost
of a region and prints it at region close.
profile_start!(label)
// code to be profiled.
profile_end!(label)
Example
use sha2::{Digest, Sha256};
let mut state: [u8; 32] = [0u8; 32];
for value in &input.values {
ziskos::profile_start!(ROLLING_HASH);
let mut hasher = Sha256::new();
hasher.update(&state);
hasher.update(value.to_le_bytes());
state = hasher.finalize().into();
ziskos::profile_end!(ROLLING_HASH);
}
With ziskemu -X this prints one line per iteration:
[ROLLING_HASH] 276749
[ROLLING_HASH] 280558
...
profile_steps
The pair profile_steps_start! / profile_steps_end! measures the
step count of a region and prints it at region close.
profile_steps_start!(label)
// code to be profiled.
profile_steps_end!(label)
Example
use sha2::{Digest, Sha256};
let mut state: [u8; 32] = [0u8; 32];
for value in &input.values {
ziskos::profile_steps_start!(ROLLING_HASH);
let mut hasher = Sha256::new();
hasher.update(&state);
hasher.update(value.to_le_bytes());
state = hasher.finalize().into();
ziskos::profile_steps_end!(ROLLING_HASH);
}
Regions must be properly nested. All eight macros share one stack of
open regions, so you can nest cost and steps regions, and immediate and
accumulated ones, inside each other. But every end macro must close
the most recently opened region, with the same label. If the label does
not match, a run with statistics on (-X) aborts with a host panic
(exit code 101) Profile tag mismatch: expected '<open>', got '<label>'.
An end with no open region also aborts such a run. Without -X the
markers are not checked.
On native (non-zkVM) builds all eight macros expand to nothing.
A guest that contains profiling markers can be emulated, but not
proven: cargo-zisk prove fails with VerifyGlobalConstraints, and
the ASM emulator (--asm) panics with Internal opcode Profile. Remove
the macros (or put them behind a feature) before you prove.