LLVM IR and Tooling

Purpose

Guide agents through LLVM as a user: generating and inspecting IR, running existing optimisation passes with opt, lowering to assembly with llc, and diagnosing missed optimisations. For writing new LLVM passes (PassPlugin, llvm-lit testing), use skills/compiler-internals/llvm-passes instead.

Triggers

"Show me the LLVM IR for this function"
"How do I run an LLVM optimisation pass?"
"What does this LLVM IR instruction mean?"
"How do I write a custom LLVM pass?"
"Why isn't auto-vectorisation happening in LLVM?"

Workflow

1. Generate LLVM IR

# Emit textual IR (.ll)
clang -O0 -emit-llvm -S src.c -o src.ll

# Emit bitcode (.bc)
clang -O2 -emit-llvm -c src.c -o src.bc

# Disassemble bitcode to text
llvm-dis src.bc -o src.ll

2. Run optimisation passes with `opt`

# Apply a specific pass
opt -passes='mem2reg,instcombine,simplifycfg' src.ll -S -o out.ll

# Standard optimisation pipelines
opt -passes='default<O2>' src.ll -S -o out.ll
opt -passes='default<O3>' src.ll -S -o out.ll

# List available passes
opt --print-passes 2>&1 | less

# Print IR before and after a pass
opt -passes='instcombine' --print-before=instcombine --print-after=instcombine src.ll -S -o out.ll 2>&1 | less

3. Lower IR to assembly with `llc`

# Compile IR to object file
llc -filetype=obj src.ll -o src.o

# Compile to assembly
llc -filetype=asm -masm-syntax=intel src.ll -o src.s

# Target a specific CPU
llc -mcpu=skylake -mattr=+avx2 src.ll -o src.s

# Show available targets
llc --version

4. Inspect IR

Key IR constructs to understand:

Construct	Meaning
`alloca`	Stack allocation (pre-SSA; `mem2reg` promotes to registers)
`load`/`store`	Memory access
`getelementptr` (GEP)	Pointer arithmetic / field access
`phi`	SSA φ-node: merges values from predecessor blocks
`call`/`invoke`	Function call (`invoke` has exception edges)
`icmp`/`fcmp`	Integer/float comparison
`br`	Branch (conditional or unconditional)
`ret`	Return
`bitcast`	Reinterpret bits (no-op in codegen)
`ptrtoint`/`inttoptr`	Pointer↔integer (avoid where possible)

5. Key passes

Pass	Effect
`mem2reg`	Promote alloca to SSA registers
`instcombine`	Instruction combining / peephole
`simplifycfg`	CFG cleanup, dead block removal
`loop-vectorize`	Auto-vectorisation
`slp-vectorize`	Superword-level parallelism (straight-line vectorisation)
`inline`	Function inlining
`gvn`	Global value numbering (common subexpression elimination)
`licm`	Loop-invariant code motion
`loop-unroll`	Loop unrolling
`argpromotion`	Promote pointer args to values
`sroa`	Scalar Replacement of Aggregates

6. Debugging missed optimisations

# Why was a loop not vectorised?
clang -O2 -Rpass-missed=loop-vectorize -Rpass-analysis=loop-vectorize src.c

# Dump pass pipeline
clang -O2 -mllvm -debug-pass=Structure src.c -o /dev/null 2>&1 | less

# Print IR after each pass (very verbose)
opt -passes='default<O2>' -print-after-all src.ll -S 2>&1 | less

7. Useful llvm tools

Tool	Purpose
`llvm-dis`	Bitcode → textual IR
`llvm-as`	Textual IR → bitcode
`llvm-link`	Link multiple bitcode files
`llvm-lto`	Standalone LTO
`llvm-nm`	Symbols in bitcode/object
`llvm-objdump`	Disassemble objects
`llvm-profdata`	Merge/show PGO profiles
`llvm-cov`	Coverage reporting
`llvm-mca`	Machine code analyser (throughput/latency)

For binutils equivalents, see skills/binaries/binutils.

Related skills

Use skills/compiler-internals/llvm-passes for writing and testing custom LLVM passes
Use skills/compiler-internals/compiler-frontend for generating LLVM IR from an AST
Use skills/compiler-internals/jit-compilation for ORC JIT execution of LLVM IR
Use skills/compilers/clang for source-level Clang flags
Use skills/binaries/linkers-lto for LTO at link time
Use skills/profilers/linux-perf combined with llvm-mca for micro-architectural analysis

llvm