Keep Your IR Alive: Why the .ll File Matters for Honest Timing

Why this lesson exists

When you run csperf run you get a JSON file that contains timing, machine metadata, and a reference to the generated LLVM IR. Many developers delete the .ll file after the run, thinking it’s just a temporary artifact. In reality, the IR is the explanation behind the numbers. Without it you lose the ability to trace why a particular optimization changed the timing.

Recap — where we are in the series

Ep 1 — Why a Single ./a.out Time Misleads Your Performance Claims — use csperf for reproducible evidence.
Ep 2 — Warm vs Cold: Why a Single Trial Misleads Performance Claims — warm‑up and repeat give credible data.
Ep 3 — Screenshots Aren't Evidence: Use csperf for Real Performance Artifacts — metadata‑rich artifacts beat screenshots.
Ep 4 — Comparing Across Machines: Why Metadata Matters in csperf — machine metadata enables honest comparison.
Ep 5 — csperf: A Lightweight Observatory for Honest Performance Tracking — observatory commands give quick evidence.
Ep 6 — csperf Doctor: First Command to Diagnose Toolchain Issues — doctor validates your toolchain.
Ep 7 — … — one concrete takeaway.
Ep 8 — … — one concrete takeaway.
Ep 9 — … — one concrete takeaway.
Ep 10 — … — one concrete takeaway.
Ep 11 — … — one concrete takeaway.
Ep 12 — … — one concrete takeaway.
Ep 13 — … — one concrete takeaway.
Ep 14 — … — one concrete takeaway.
Ep 15 — … — one concrete takeaway.
Ep 16 — … — one concrete takeaway.
Ep 17 — … — one concrete takeaway.
Ep 18 — … — one concrete takeaway.
Ep 19 — … — one concrete takeaway.
Ep 20 — … — one concrete takeaway.
Ep 21 — … — one concrete takeaway.
Ep 22 — … — one concrete takeaway.
Ep 23 — … — one concrete takeaway.
Ep 24 — … — one concrete takeaway.
Ep 25 — … — one concrete takeaway.

The misconception

People think the JSON output of csperf run is enough. They delete the accompanying .ll file, assuming the numbers are self‑explanatory. In practice, the IR is the only place where you can see which passes were applied, which optimizations were enabled, and why a particular timing was observed.

What problem csperf solves (this episode's slice)

csperf run already writes the LLVM IR to a file named ir.ll in the output directory. The JSON contains a ir_path field pointing to that file. By keeping the IR alongside the JSON you preserve a complete audit trail of the compilation that produced the timing.

Mental model

Run → csperf run produces ir.json and ir.ll.
Inspect → Open ir.ll to see the exact IR that was executed.
Compare → When you change compiler flags, run again and compare the new ir.ll to the old one.
Explain → If a timing improves, look for the new passes or lowered optimization levels in the IR.

Lab: install and first commands

pip install compilersutra-perf csperf doctor

Lab: what we ran on this machine

csperf run \ --input examples/cpp/matrix_traversal.cpp \ --backend cpu \ --output results/ir.json

The command above will:

Compile matrix_traversal.cpp with the default Clang backend.
Emit ir.ll in the results/ directory.
Write ir.json containing timing, metadata, and a reference to ir.ll.

Results (real numbers only)

Graph: trial wall_time_ms from this run's artifacts (not invented).

Artifacts missing for this episode — numbers withheld.

How to read the artifacts

Open results/ir.json.
Find the ir_path field; it points to results/ir.ll.
Open ir.ll and search for ; <opt> comments that indicate which passes ran.
Cross‑reference the execution_time_ms in the JSON with the IR to trace performance changes.

Common mistakes (teacher checklist)

Deleting ir.ll after a run – keep it for future comparison.
Ignoring the ir_path field – always check it to locate the IR.
Assuming the JSON alone explains everything – the IR is required for a full story.
Not version‑controlling the IR – add ir.ll to your repo or a dedicated artifact store.

Try this next (homework)

Do this tonight — Episode 27 starts by assuming you did.

Closing

Keeping the LLVM IR is like keeping a transcript of a conversation. The numbers are the summary; the IR is the verbatim record that lets you audit, explain, and reproduce the performance story.

The series so far

Ep 1 — Why a Single ./a.out Time Misleads Your Performance Claims — use csperf for reproducible evidence.
Ep 2 — Warm vs Cold: Why a Single Trial Misleads Performance Claims — warm‑up and repeat give credible data.
Ep 3 — Screenshots Aren't Evidence: Use csperf for Real Performance Artifacts — metadata‑rich artifacts beat screenshots.
Ep 4 — Comparing Across Machines: Why Metadata Matters in csperf — machine metadata enables honest comparison.
Ep 5 — csperf: A Lightweight Observatory for Honest Performance Tracking — observatory commands give quick evidence.
Ep 6 — csperf Doctor: First Command to Diagnose Toolchain Issues — doctor validates your toolchain.
Ep 7 — … — one concrete takeaway.
Ep 8 — … — one concrete takeaway.
Ep 9 — … — one concrete takeaway.
Ep 10 — … — one concrete takeaway.
Ep 11 — … — one concrete takeaway.
Ep 12 — … — one concrete takeaway.
Ep 13 — … — one concrete takeaway.
Ep 14 — … — one concrete takeaway.
Ep 15 — … — one concrete takeaway.
Ep 16 — … — one concrete takeaway.
Ep 17 — … — one concrete takeaway.
Ep 18 — … — one concrete takeaway.
Ep 19 — … — one concrete takeaway.
Ep 20 — … — one concrete takeaway.
Ep 21 — … — one concrete takeaway.
Ep 22 — … — one concrete takeaway.
Ep 23 — … — one concrete takeaway.
Ep 24 — … — one concrete takeaway.
Ep 25 — … — one concrete takeaway.