00 LLVM IR and the Compilation Pipeline: From C Code to Machine Code

A compiler is a program that translates the source code humans read and write into machine code so the CPU can run it. A CPU can natively execute only machine code, so code written in a language like C must go through this translation once before it runs.

Depending on when the translation happens, the ways to run a program split broadly into three.

The difference between the three methods shows up as time once the same function is called repeatedly. The graph below shows per-call times for the same integer loop, called twelve times each as CPython (interpreter), numba² (JIT), and a C library compiled ahead of time with clang -O2 (AOT).

The interpreter repeats the same interpretation on every call and pays the same cost each time. The JIT pays its compilation cost on the first call (warmup³) and reuses the translated machine code afterwards, while the AOT build pays that cost before the program runs and is fast from the first call.

LLVM⁴ is an AOT compiler for native languages (languages that compile to machine code the CPU executes directly, with no virtual machine⁵) like C and C++.

The structure of stepping down through an intermediate language instead of translating source straight to machine code already appeared with nvcc in CUDA C Basics. nvcc, NVIDIA’s CUDA compiler, splits a .cu file into host code that runs on the CPU and device code that runs on the GPU, lowering the device code to PTX⁶, an intermediate instruction set, and then to SASS, the GPU’s machine code. CPU-side compilers step down through intermediate stages the same way, and LLVM is the representative one. In fact cicc, the device code compiler inside nvcc, is built on LLVM, so the two stacks correspond layer by layer.

The Pipeline

• Frontend (clang): Test.c → Test.ll. Parsing⁷ and type checking.
• Middle-end (opt): Test.ll → Test.ll'. Passes rewriting the IR, which is optimization.
• Backend (llc, as, ld): Test.ll' → Test.s → Test.o → a.out. Code generation and assembly.

A single IR (intermediate representation, the language between source and machine code) travels through all three stages: frontend, middle-end, and backend. Other compilers hold their IR only as in-memory objects, so it cannot be pulled out into a file. LLVM IR is text with a published grammar, so you can save it to a file, edit it by hand, and feed it back to the compiler.

From C to IR

The example is a two-function C file.

// Test.c
int func1(void) { int a = 4; return a; }
int main(void)  { return 0; }

clang -emit-llvm -S Test.c   # → Test.ll

-emit-llvm -S tells clang to stop at human-readable IR instead of going all the way to machine code. func1 in the resulting Test.ll reads as follows.

define i32 @func1() #0 {
  %1 = alloca i32, align 4
  store i32 4, ptr %1, align 4
  %2 = load i32, ptr %1, align 4
  ret i32 %2
}

These are the 4 symbols that appear in the body.

The target triple¹¹ at the top, the attributes¹² at the bottom, and the ! metadata are environment configuration, not needed for decoding the body.¹³

From IR to Assembly

llc Test.ll -o Test.s

llc is the backend tool that lowers IR to the assembly¹⁴ of the CPU named by the target triple¹¹, so the output assembly differs per target CPU: targeting x86-64 produces x86-64 assembly, ARM64 produces ARM64 assembly, RISC-V produces RISC-V assembly, and an option such as llc -mtriple=x86_64-pc-linux-gnu Test.ll switches the target. One IR fanning out to per-target backends is exactly the role of IR described in the pipeline section.

The following table maps func1 in the ARM64-target output.¹⁵

The backend assigns virtual names (%N) to physical places (registers, stack slots). An assembly file has 3 kinds of lines.

Change store i32 4 to store i32 9 in Test.ll, run llc again, and the output shows mov w8, #9. The IR text itself is the compiler input, so editing the IR alone changes the program without going through the frontend.

From Assembly to an Executable

Test.s is a text file holding instructions like mov w8, #4 as characters. A CPU, however, is a circuit that acts only when the fixed bit pattern of an instruction arrives, so it cannot execute character data like ’m’, ‘o’, ‘v’ as instructions. The assembler (as) therefore turns the text notation into instruction bit patterns, and the result is the object file Test.o.

A program is usually built from several source files, each becoming one object file, plus libraries (bundles of precompiled object files holding common functions such as printf). An object file is machine code but not runnable on its own, because the addresses of functions it calls in other object files or libraries are still unresolved. The linker (ld) collects those object files and libraries, fills in the missing addresses, and joins them into an executable. This process is called linking.

clang -c Test.s -o Test.o   # assemble
clang Test.o -o a.out       # link

Both steps can be invoked through the clang command, which calls as and ld internally.

Passes and Optimization Levels

A pass is a small program built into LLVM that sweeps over the entire IR once, performing one predetermined analysis or transformation. Each pass owns exactly one transformation.

Running passes splits into two ways. With opt you pick and run a single pass of your choosing, and with clang’s -O1 -O2 -O3 options a predefined list of passes runs in order. And the three options’ lists nest inside one another.¹⁹

The price of a higher level is compile time, and the passes -O3 adds trade code size for speed, which is why release builds usually stop at -O2.

The following command prints the actual contents of a list. Every pass in the table above is inside it.

opt -passes='default<O1>' -print-pipeline-passes Test.ll -S -o /dev/null

Watching Optimization as a Diff

The payoff of readable IR shows up when comparing before and after optimization.

clang -O1 -emit-llvm -S Test.c -o Test_O1.ll

Comparing Test.ll emitted at -O0 (the default, left) with Test_O1.ll emitted at -O1 (right) in the VS Code diff editor²⁰ gives the following.

Mapping the body of func1 line by line:

The optimization passes proved that this function stores 4 to memory and immediately loads it back, so the answer is always 4, and erased the variable’s existence. The C code did not change, the program went from four lines to one, and the whole event is captured in a text diff.

optnone

optnone is a do-not-optimize marker that clang attaches to the attributes¹² of every function when it emits IR at -O0. The marker shows itself as follows when experimenting with passes.

Apply mem2reg from the previous section on its own with opt.

opt -passes=mem2reg Test.ll -S -o Test_m2r.ll

The output comes back identical to the input. Before processing a function, opt reads its attributes and skips the function when it sees optnone. Attributes control whether passes run at all.

Emitting without the marker restores normal behavior.²¹

clang -Xclang -disable-O0-optnone -emit-llvm -S Test.c -o Test_noopt.ll
opt -passes=mem2reg Test_noopt.ll -S

func1 folds to a single ret i32 4. This option is the standard way to emit IR for pass experiments.

References

• LLVM for Grad Students: the What is LLVM? / The Pieces / Understanding LLVM IR chapters.
• LLVM Language Reference: the official definition of IR syntax.
• The Architecture of Open Source Applications: LLVM: Chris Lattner on the design background of LLVM.