Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

LLVM Observatory

https://xuhongxu.com/llvm-observatory

Observe What InstCombine Does and Why — In Your Browser

LLVM’s InstCombine is the workhorse peephole pass: it rewrites IR thousands of times per compile, but when one of those rewrites surprises you, finding out which rule fired, why, and on what value usually means a local LLVM build, printf debugging, and a lot of patience.

Recommended Reading:

LLVM Observatory is a browser-based inspector for LLVM’s InstCombine and AggressiveInstCombine passes that skips all of that.

Paste IR, hit Run, and see what the passes did to it — value by value, visit by visit, iteration by iteration.

What you get

  • Values and replacements — every value the passes create or produce, and every replacement they make (replaceAllUsesWith), each with the stack that led to it.
  • Pattern matches — each match(V, P) call, whether it matched, and the inner values extracted from the pattern, shown as a tree that names the matchers as the source writes them.
  • Conditions (MC/DC) — whether each boolean sub-expression of a conditional in the pass evaluated to true or false, drawn as badges over the source.
  • Optimized IR — the module after any one iteration; the final IR by default.

The trace has a structured view with filters and pointer links between values and replacements, and a JSON view that matches --json on the command line. Clicking a rule or a stack frame opens its source with the conditions of that iteration, and Ctrl/⌘+click on a call jumps to its definition.

Why it’s useful

  • No build. It’s WebAssembly.
    LLVM is compiled with Emscripten and the whole pipeline runs in the page; there is no backend and nothing to install.
  • Real stacks, real sources.
    The hooks are small patches to LLVM’s sources that keep line numbers unchanged. Stacks are symbolized with the DWARF of the observed sources, so you see the rule that fired, not just the leaf IRBuilder helper.
  • Pick your LLVM.
    The web app observes the latest LLVM main. The command line tool and the build scripts can observe any LLVM release from 8 on.
  • Shareable.
    Share copies a link that holds the IR, so a reproducer can go straight into a bug report.

Who it’s for

  • Compiler engineers writing or reviewing InstCombine patches.
  • LLVM contributors triaging “this rewrite looks wrong” bug reports without having to build anything.
  • Anyone learning how InstCombine works — watching the fixed-point loop unfold on a small example is the fastest way to build intuition.

Examples

Tip

Try a tiny IR snippet first (a couple of adds with a 0 operand will do), switch to the structured view, and watch the rules fire.

Example 1

define i32 @f(i32 %x) {
  %a = add i32 %x, 0
  ret i32 %a
}

Example 2

; no rewrite in LLVM 21 and earlier
define i1 @src(i8 %x) {
  %lshr = lshr i8 4, %x
  %trunc = trunc i8 %lshr to i1
  ret i1 %trunc
}

Example 3

; no rewrite in LLVM 21 and earlier
define range(i32 0, 7) i32 @src(i32 %0) local_unnamed_addr #0 {
  %2 = insertelement <4 x i32> poison, i32 %0, i64 0
  %3 = shufflevector <4 x i32> %2, <4 x i32> poison, <4 x i32> zeroinitializer
  %4 = tail call i32 @llvm.vector.reduce.add.v4i32(<4 x i32> %3)
  ret i32 %4
}

Open Source

https://github.com/xuhongxu96/llvm-observatory

It’s built from a small patcher, a runtime and a driver that compile into one wasm module, plus a Node command line (observe.ts) for running the same observation outside the browser. Welcome contributions!