llvm-ir-and-passes

LLVM IR and Passes

Purpose

Teach agents to read and reason about LLVM IR (SSA, types, terminators), navigate the standard pass pipeline, and use opt/llvm-dis for inspection. Complements skills/compilers/llvm (toolchain) and skills/compiler-internals/llvm-passes (writing plugins) — not merged.

When to Use

• Understanding what -O2 changed in generated IR
• Triaging miscompiles between Clang versions
• Preparing to write a custom pass
• Teaching SSA and dominance without writing C++ passes yet

Workflow

1. LLVM IR structure

; Function in SSA form
define i32 @add(i32 %a, i32 %b) {
entry:
  %sum = add i32 %a, %b
  ret i32 %sum
}

Key concepts: basic blocks, PHI nodes at merges, typed values (i32, ptr, vectors).

2. Emit IR from Clang

clang -S -emit-llvm -O0 -o foo.ll foo.c
clang -c -emit-llvm -O2 -o foo.bc foo.c
llvm-dis foo.bc -o foo.ll

3. Standard optimization pipeline (New PM)

Clang -O2 roughly runs:

SimplifyCFG → InstCombine → GVN → LICM → LoopVectorize → ...

Inspect with:

opt -passes='default<O2>' -S foo.ll -o foo-opt.ll
opt -passes='default<O2>' -print-passes foo.ll 2>&1 | head

4. Useful analysis passes

Pass	Shows
-passes=print<domtree>	Dominator tree
-passes=print<loops>	Loop nests
-passes=print-alias-sets	Alias sets

opt -passes='print<domtree>' -disable-output foo.ll

5. Reading PHI and UB

merge:
  %v = phi i32 [ %a, %then ], [ %b, %else ]

undef and poison in IR model LLVM poison semantics — distinct from C UB but related.

6. Compare before/after

opt -passes='instcombine,simplifycfg' -S foo.ll -o - | diff -u foo.ll -

7. Agent usage

/llvm-ir-and-passes Explain this PHI node and which pass likely created it

Common Problems

Symptom	Cause	Fix
Pass not found	LLVM version rename	opt --print-passes for your build
IR mismatch	Different LLVM major	Match clang/opt versions
"optnone" blocks opts	-O0 attribute	Compile with -O1+
Huge IR	Inlined headers	-fno-discard-value-names off; filter function
Wrong pipeline	Legacy vs NPM	Use -passes= syntax

Related Skills

• skills/compilers/llvm — toolchain overview
• skills/compiler-internals/llvm-passes — writing PassPlugins
• skills/compiler-internals/compiler-optimizations-deep — RA and ISel
• skills/compiler-internals/compiler-frontend — IR generation
• skills/rust/rustc-basics — rustc --emit=llvm-ir