LLVM IR and tooling

Contract

Field	Bound contract
Trigger	The user wants to see the IR for a function, run or inspect optimization passes with opt, lower IR to assembly with llc, read an IR construct, or find out why a transform did not fire.
Authority	Read-only. Commands write .ll, .bc, .s, and .o files only into a scratch location the user names; the project tree is not modified. Rollback is deleting the scratch outputs. No remote mutation.
Side effect	Scratch IR and object files; chat output.
Done	The requested IR, pass output, or lowering exists in the scratch location, and each construct or remark the user asked about has a one-line reading.

Inputs

• LLVM version: required, from opt --version. Current stable is LLVM 23.1.0; pass names below are new-pass-manager names and apply to any line since 14.
• Source file or existing .ll/.bc file: required.
• Target CPU and features when lowering: optional; defaults to the host.
• The question: required. One of emit, transform, lower, read, or diagnose.

Procedure

1. Emit IR. Textual: clang -O0 -emit-llvm -S src.c -o src.ll. Bitcode: clang -O2 -emit-llvm -c src.c -o src.bc. Convert: llvm-dis src.bc -o src.ll, llvm-as src.ll -o src.bc. Emit at -O0 when the goal is to read the front end's output, at -O2 when the goal is to read what the optimizer produced. Done when: the .ll file exists.

2. Run passes with opt. Named passes: opt -passes='mem2reg,instcombine,simplifycfg' src.ll -S -o out.ll. Standard pipelines: opt -passes='default<O2>' src.ll -S -o out.ll. List available passes: opt --print-passes. Show the full pipeline clang builds: clang -O2 -mllvm -print-pipeline-passes -c src.c -o /dev/null. Dump IR after every pass: opt -passes='default<O2>' -print-after-all src.ll -S 2>&1, which is verbose; redirect it to a file. Done when: the transformed IR exists and the pass list is stated.

3. Lower with llc. Object: llc -filetype=obj src.ll -o src.o. Assembly: llc -filetype=asm src.ll -o src.s; Intel syntax on x86 is --x86-asm-syntax=intel. CPU and features: llc -mcpu=skylake -mattr=+avx2 src.ll -o src.s. Registered targets: llc --version. Done when: the assembly or object exists.

4. Read the IR using the construct table; expand any construct the user names from the reference. Done when: each construct in the question has a reading.

   Construct	Meaning
   alloca	Stack slot; mem2reg promotes it to SSA values
   load, store	Memory access through an opaque ptr
   getelementptr	Address arithmetic for fields and elements
   phi	SSA merge of values from predecessor blocks
   call, invoke	Call; invoke carries exception edges
   icmp, fcmp	Integer and float comparison
   br, switch, ret	Control flow and return
   trunc, zext, sext, bitcast	Width and representation changes
   ptrtoint, inttoptr	Pointer and integer conversion; avoid where possible

5. Name the pass that owns a transform from the table when the user asks why something did or did not happen. Done when: the pass is named.

   Pass	Effect
   mem2reg, sroa	Promote allocas and split aggregates into SSA values
   instcombine	Peephole instruction combining
   simplifycfg	Control-flow cleanup, dead-block removal
   gvn, early-cse	Redundancy elimination
   licm	Loop-invariant code motion
   loop-unroll	Loop unrolling
   loop-vectorize, slp-vectorize	Loop and straight-line vectorization
   inline	Function inlining
   argpromotion	Pointer arguments to values
   tailcallelim, reassociate, dce	Tail calls, reassociation, dead code

6. Diagnose a missed transform from source with remarks: clang -O2 -Rpass-missed=loop-vectorize -Rpass-analysis=loop-vectorize src.c. When the answer needs IR before and after one pass, use opt -passes='<pass>' -print-before=<pass> -print-after=<pass> on the .ll file. Done when: the analysis remark or the IR diff names the blocker.

7. Point to the companion tools by task: llvm-link joins bitcode files, llvm-lto runs standalone LTO, llvm-nm and llvm-objdump inspect objects, llvm-profdata merges profiles, llvm-cov reports coverage, llvm-mca estimates throughput and latency of an assembly block. GNU equivalents: use binutils. Done when: the tool for the follow-up task is named.

Failure and recovery

Failure class	Behavior
Pass name unknown to opt	Run opt --print-passes and pick the matching name; legacy -passname spellings are not accepted by the new pass manager.
llc rejects a flag	Run llc --help-hidden for the target-specific spelling; -masm-syntax=intel is not a flag, --x86-asm-syntax=intel is.
Front-end question rather than IR question	Lexer, parser, and IR generation from an AST: use compiler-frontend.
Runtime code generation	ORC JIT and in-memory execution: use jit-compilation.
New pass wanted	Writing and testing a PassPlugin: use llvm-passes.

Output

The scratch files produced (.ll, .bc, .s, .o) with the exact commands that made them, plus a chat reading of each construct, pass, or remark the user asked about.