Probe the uProf environment: binary, version, platform, active mode, results dir.

Call this before collecting. mode is "real" (actual AMDuProfCLI found), "mock" (deterministic synthetic backend — numbers are fabricated, useful only for testing tool plumbing), or "unavailable" (nothing runnable; notes explain how to fix). available_analyses lists the collect configs uprof_collect accepts; note that on non-AMD CPUs only 'tbp' actually works.

Run a uProf collection and store the result; returns a result_id handle.

Pass exactly one target: command (argv list, launched under the profiler) or pid (attach — requires duration_sec, since attach has no natural end). config is a collect config such as "tbp" or "hotspots" (uprof_check lists them; only 'tbp' works on non-AMD CPUs; allow_unknown=true forces an unlisted one). call_graph=true adds call-stack sampling; extra_events are raw -e event specs; label is a free-form tag for telling results apart later. timeout_sec caps how long the collection may run before it is killed (default 300s, or duration_sec when larger); raise it for long workloads. app_exit_code is the profiled program's own exit — a non-zero value is surfaced as a warning, so a crashed target does not masquerade as a clean profile. In mock mode the target command really runs but every profile number is synthetic. Feed the returned result_id to the report/compare tools.

List stored uProf results: result_id, config, target, mode, creation time.

Use to rediscover result_ids from earlier collections. Entries stamped mode "mock" contain synthetic numbers.

Parsed run overview of a stored result: duration, top hotspots, host details.

Generates the CSV report on first use (cached in the session dir afterwards). The fastest way to understand a collection before drilling into hotspots. result_id comes from uprof_collect or uprof_list_results.

Top-N hottest functions of a stored result, sorted by sample share descending.

top_n is clamped to 100; row_count_total and truncated say whether more rows exist. ignore_system_modules=true re-runs the report excluding kernel and system libraries so application code stands out. Start with the defaults.

Escape hatch: raw uProf CSV report text for a stored result, byte-capped.

uProf's report subcommand writes CSV files rather than printing to stdout, so this returns the contents of the generated report.csv (cached after first use). With extra_args (raw AMDuProfCLI report options, each starting with "-") the report is regenerated into report-raw.csv using those options. command is the CLI invocation that produces the file. Long output is head+tail truncated; read files under result_dir for the full data.

Compare two stored results function-by-function and issue a pass/fail verdict.

The core of an optimize loop: collect a baseline, change code, collect a candidate, compare. The verdict fails when the total or any significant function regresses more than threshold_pct; functions below noise_floor_pct of both runs never affect the verdict. With fail_on_regression=true a failing verdict raises a tool error carrying the reason — use that to gate automated loops.

Sample system power/frequency/thermal counters over time and summarize them.

events are timechart categories (power, frequency, temperature, voltage, current, dvfs, energy). Samples every interval_ms (minimum 10) for duration_sec, optionally while running command. Returns per-counter min/max/mean/last summaries, not the full series — the CSV stays in result_dir. Real data needs AMD hardware; in mock mode values are synthetic.

Parsed AMDuProfCLI info --system: CPU model/family, core counts, OS details.

Use to decide which collect configs the hardware supports before profiling. In mock mode the fields are synthetic.