Skip to main content

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:

QuantityDescription
CostProving work for the region, weighted by instruction mix.
StepsRaw 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​

NameTypeDescription
labelidentifierA 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);
}


warning

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.

note

On native (non-zkVM) builds all eight macros expand to nothing.

Remove profiling markers before proving

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.