Wasm on Opensource internals

Liftoff and TurboFan: The Two WebAssembly Tiers

Jay Hubbert — Sat, 24 Oct 2026 09:40:00 +0000

TL;DR: Liftoff (src/wasm/baseline/liftoff-compiler.cc) compiles a wasm function in a single pass: the bytecode decoder is the compiler, there is no IR, no liveness analysis and no optimization. It keeps a stack of values, each either in a register or in a stack slot, and hands out registers on demand. The tier-up decision is made by a counter in the generated code itself: every backward branch subtracts the PC distance from a per-function budget, and when the budget goes negative the function calls Builtin::kWasmTriggerTierUp and the optimizing compiler is scheduled in the background.

Two compilers, one input format, two completely different philosophies.

Liftoff is the compiler you run when you want the function to exist now. It makes no attempt to produce good code; it makes an attempt to produce any code, quickly, and to make the decision about whether that was a mistake later. The optimizing compiler (Turboshaft, still called kTurbofan in the tier enum) is the compiler you run when you know the function matters.

The interesting part is the interface between them, because V8 does not use a call-count heuristic like it does for JavaScript. For wasm, the budget is burned down by the machine code the function itself executes.

Liftoff: a compiler that is also its own decoder

The entire shape of Liftoff is visible in one line:

 cpp
 
 
// src/wasm/baseline/liftoff-compiler.cc:11626
 WasmFullDecoder<Decoder::NoValidationTag, LiftoffCompiler> decoder(
 &zone, env->module, env->enabled_features,
 compiler_options.detected_features ? compiler_options.detected_features
 : &unused_detected_features,
 func_body, call_descriptor, env, &zone,
 NewLiftoffAssemblerBuffer(func_body_size), debug_sidetable_builder.get(),
 compiler_options, function_coverage_data);
 decoder.Decode();

decoder.Decode() calls back into the LiftoffCompiler once per wasm opcode, and the compiler emits machine code for it immediately. There is no graph, no SSA, no fixpoint iteration, no intermediate representation of any kind. The module was validated before instantiation, so Decoder::NoValidationTag is safe: Liftoff trusts the bytecode it is given.

The output is written straight into an AssemblerBuffer sized from the function body length, so there is no growth-and-copy phase either.

The consequence is that Liftoff cannot optimize, but it also cannot mispredict. There is no speculation to be wrong about, which is why Liftoff code is so much easier to debug: one wasm instruction maps to one contiguous run of machine code, and locals stay in their proper stack slots. V8 leans on this hard — when DevTools attaches, the whole module is tiered down to Liftoff:

 cpp
 
 
// src/wasm/module-compiler.cc:982
 if (is_in_debug_state) {
 return {ExecutionTier::kLiftoff, ExecutionTier::kLiftoff};
 }

The register allocator: a stack of values, not a graph

There is no liftoff-register-allocator.cc in V8 today, and no liftoff-value.h or liftoff-instruction.h either. The register allocation lives inside the assembler’s CacheState, and it works by keeping a stack of value states that mirrors the wasm operand stack.

 cpp
 
 
// src/wasm/baseline/liftoff-assembler.h:156
 SmallZoneVector<VarState, 16> stack_state;
 LiftoffRegList used_registers;
 uint32_t register_use_count[kAfterMaxLiftoffRegCode] = {0};
 LiftoffRegList last_spilled_regs;
 Register cached_instance_data = no_reg;

Each VarState is a small tagged union:

 cpp
 
 
// src/wasm/baseline/liftoff-varstate.h:13
class LiftoffVarState {
 public:
 enum Location : uint8_t { kStack, kRegister, kIntConst };

Three locations: on the stack, in a register, or — a nice touch — a compile-time integer constant that never needs a register at all.

The trick that avoids the classic linear-scan problems is that Liftoff does not compute liveness at all. A register is counted, not analysed:

 cpp
 
 
// src/wasm/baseline/liftoff-assembler.h:308
 void inc_used(LiftoffRegister reg) {
 DCHECK(!frozen);
 if (reg.is_pair()) {
 inc_used(reg.low());
 inc_used(reg.high());
 return;
 }
 used_registers.set(reg);
 DCHECK_GT(kMaxInt, register_use_count[reg.liftoff_code()]);
 ++register_use_count[reg.liftoff_code()];
 }

 // Returns whether this was the last use.
 void dec_used(LiftoffRegister reg) {
 ...
 int code = reg.liftoff_code();
 DCHECK_LT(0, register_use_count[code]);
 if (--register_use_count[code] == 0) used_registers.clear(reg);
 }

A register stays reserved exactly as long as some value on the operand stack still needs it. The use count is incremented when a value is pushed into a register and decremented when the value is popped or dropped; when it reaches zero, the register is free again. There is no interference graph, no live range computation, no spilling decision that requires looking ahead. The cost is that a register can be held longer than strictly necessary (the value stays on the stack until it is popped), and the benefit is that the whole thing is O(1) per operation.

When no register is free, one is spilled. The policy has two stages, and the first one is the interesting one:

 cpp
 
 
// src/wasm/baseline/liftoff-assembler.cc:1088
LiftoffRegister LiftoffAssembler::SpillOneRegister(LiftoffRegList candidates) {
 // Before spilling a regular stack slot, try to drop a "volatile" register
 // (used for caching the memory start or the instance itself). Those can be
 // reloaded without requiring a spill here.
 if (cache_state_.has_volatile_register(candidates)) {
 return cache_state_.take_volatile_register(candidates);
 }

 LiftoffRegister spilled_reg = cache_state_.GetNextSpillReg(candidates);
 SpillRegister(spilled_reg);
 return spilled_reg;
}

Liftoff keeps two “volatile” registers: one caches the instance data pointer and one caches the current memory’s base pointer. Both are recomputable, so evicting them costs nothing but a reload. Only when there is no volatile register to drop does it spill a real value — and then it picks round-robin, so that no register is spilled twice in a row while others are never spilled:

 cpp
 
 
// src/wasm/baseline/liftoff-assembler.h:374
 LiftoffRegister GetNextSpillReg(LiftoffRegList candidates) {
 DCHECK(!frozen);
 DCHECK(!candidates.is_empty());
 // This method should only be called if none of the candidates is free.
 DCHECK(candidates.MaskOut(used_registers).is_empty());
 LiftoffRegList unspilled = candidates.MaskOut(last_spilled_regs);
 if (unspilled.is_empty()) {
 unspilled = candidates;
 last_spilled_regs = {};
 }
 LiftoffRegister reg = unspilled.GetFirstRegSet();
 return reg;
 }

Control flow merges are handled by a ParallelMove, so a value that lives in register rax on one path and in a stack slot on another can be reconciled without materializing everything to the stack first.

The budget: bytes of machine code, not calls

Here is the part that differs from JavaScript tiering. V8 does not count invocations of a wasm function. It counts the machine code bytes the function has executed.

Each function gets a budget array entry at module creation:

 cpp
 
 
// src/wasm/wasm-code-manager.cc:1044
 // The tiering budget is accessed directly from generated code.
 static_assert(sizeof(*tiering_budgets_.get()) == sizeof(uint32_t));

 std::fill_n(tiering_budgets_.get(), module_->num_declared_functions,
 v8_flags.wasm_tiering_budget);

The comment matters: the array is uint32_t, not a tagged value, and it is not in the JS heap. It is allocated in the sandbox and read and written by the generated code itself, with no runtime call on the fast path.

The default budget is 13 000 000:

 cpp
 
 
// src/flags/flag-definitions.h:2091
DEFINE_INT(wasm_tiering_budget, 13'000'000,
 "budget for dynamic tiering (rough approximation of bytes executed")

Note “rough approximation of bytes executed”. The unit is the PC distance of a backward branch — the number of bytes of machine code between the branch and its target. A tight loop therefore burns budget fast (many backward branches, each costing the loop body size), and a function that is called many times but does little work burns it slowly.

Liftoff emits a check at every backward branch. The amount charged is the loop’s own size:

 cpp
 
 
// src/wasm/baseline/liftoff-compiler.cc:3978
 void BrImpl(FullDecoder* decoder, Control* target) {
 if (dynamic_tiering()) {
 if (target->is_loop()) {
 DCHECK(target->label.get()->is_bound());
 int jump_distance = __ pc_offset() - target->label.get()->pos();
 TierupCheck(decoder, decoder->position(), jump_distance);
 } else {

Forward branches are deliberately not charged, and the comment says why:

 cpp
 
 
// src/wasm/baseline/liftoff-compiler.cc:3985
 // To estimate time spent in this function more accurately, we could
 // increment the tiering budget on forward jumps. However, we don't
 // know the jump distance yet; using a blanket value has been tried
 // and found to not make a difference.

The check itself is two machine instructions plus a conditional branch. On x64:

 cpp
 
 
// src/wasm/baseline/x64/liftoff-assembler-x64-inl.h:374
void LiftoffAssembler::CheckTierUp(int declared_func_index, int budget_used,
 Label* ool_label,
 const FreezeCacheState& frozen) {
 Register instance_data = cache_state_.cached_instance_data;
 if (instance_data == no_reg) {
 instance_data = kScratchRegister;
 LoadInstanceDataFromFrame(instance_data);
 }

 Register budget_array = kScratchRegister; // Overwriting {instance_data}.
 movq(budget_array,
 FieldMemOperand(instance_data,
 WasmTrustedInstanceData::kTieringBudgetArrayOffset));

 int offset = kInt32Size * declared_func_index;
 subl(Operand{budget_array, offset}, Immediate(budget_used));
 j(negative, ool_label);
}

Load the budget array out of the instance data, subtract the amount spent, branch if it went negative. Three instructions on the hot path, no call, no branch misprediction in the common case (the branch is perfectly predicted until it is taken exactly once).

Liftoff adds a fixed surcharge for the cost of the check itself, and caps how much a single check can charge:

 cpp
 
 
// src/wasm/baseline/liftoff-compiler.cc:1193
 void TierupCheck(FullDecoder* decoder, WasmCodePosition position,
 int budget_used) {
 if (for_debugging_ != kNotForDebugging) return;
 SCOPED_CODE_COMMENT("tierup check");
 budget_used += kTierUpCostForCheck;
 // We never want to blow the entire budget at once.
 const int max_budget_use = std::max(1, v8_flags.wasm_tiering_budget / 4);
 if (budget_used > max_budget_use) budget_used = max_budget_use;

The cap matters: a function whose loop body is enormous must not be able to consume the whole 13 MB budget in one backedge, or the tier-up would be decided by a single branch rather than by how long the function ran.

The constants are documented in the compiler itself:

 cpp
 
 
// src/wasm/baseline/liftoff-compiler.cc:712
 // Some constants for tier-up checks.
 // In general we use the number of executed machine code bytes as an estimate
 // of how much time was spent in this function.
 // - {kTierUpCostForCheck} is the cost for checking for the tier-up itself,
 // which is added to the PC distance on every tier-up check. This cost is
 // for loading the tiering budget, subtracting from one entry in the array,
 // and the conditional branch if the value is negative.
 // - {kTierUpCostForFunctionEntry} reflects the cost for calling the frame
 // setup stub in the function prologue (the time is spent in another code
 // object and hence not reflected in the PC distance).
 static constexpr int kTierUpCostForCheck = 20;
 static constexpr int kTierUpCostForFunctionEntry = 40;

Twenty bytes for the check, forty for the function prologue’s call into the frame setup stub. It is an estimate of machine code bytes, and the estimates are calibrated by hand.

When the budget runs out

The negative budget branches to out-of-line code that calls a builtin:

 cpp
 
 
// src/wasm/baseline/liftoff-compiler.cc:862
 static OutOfLineCode* TierupCheck(
 Zone* zone, ZoneVector<OutOfLineCode*>* list, WasmCodePosition pos,
 ...
 OutOfLineCode* ool = zone->New<OutOfLineCode>();
 ool->builtin = Builtin::kWasmTriggerTierUp;

The out-of-line code is used because the tier-up path needs to spill every live register, and doing that inline would slow down every function that has a loop. The out-of-line block pushes the registers it needs and then calls the builtin.

That builtin ends up in Runtime_WasmTriggerTierUp:

 cpp
 
 
// src/runtime/runtime-wasm.cc:659
 } else {
 wasm::TriggerTierUp(isolate, trusted_data, func_index);
 }

and TriggerTierUp is where the decision to compile is actually made — and it is a decision with hysteresis, not a simple “compile now”:

 cpp
 
 
// src/wasm/module-compiler.cc:1526
 trusted_instance_data->tiering_budget_array()[array_index].store(
 v8_flags.wasm_tiering_budget, std::memory_order_relaxed);
 int& stored_priority =
 module->type_feedback.feedback_for_function[func_index].tierup_priority;
 if (stored_priority < kMaxInt) ++stored_priority;
 priority = stored_priority;
 }
 // Only create a compilation unit if this is the first time we detect this
 // function as hot (priority == 1), or if the priority increased
 // significantly. The latter is assumed to be the case if the priority
 // increased at least to four, and is a power of two.
 if (priority == 2 || !base::bits::IsPowerOfTwo(priority)) return;

The budget is reset to full, and the function’s “tier-up priority” is incremented. A compilation unit is only created when the priority hits a power of two. The effect: the first tier-up request compiles the function; a second request is ignored; the fourth and the eighth do compile it again (which matters when the optimizing compiler’s code was discarded for outdated assumptions); the third, fifth, sixth and seventh do not.

That is a hysteresis band, and it exists because the budget being exhausted is a proxy for “hot”, and proxies are noisy. A function whose budget hits zero once may just have had an unusual loop.

The optimizing compiler

The top tier is Turboshaft. ExecuteTurboshaftWasmCompilation is a one-liner that hands off to the general pipeline:

 cpp
 
 
// src/compiler/turboshaft/wasm-turboshaft-compiler.cc:14
wasm::WasmCompilationResult ExecuteTurboshaftWasmCompilation(
 wasm::CompilationEnv* env, compiler::WasmCompilationData& data,
 wasm::WasmDetectedFeatures* detected,
 DelayedCounterUpdates* counter_updates) {
 wasm::WasmCompilationResult result =
 Pipeline::GenerateWasmCode(env, data, detected, counter_updates);

Pipeline::GenerateWasmCode builds a Turboshaft graph from the wasm bytecode and then runs a wasm-specific list of phases:

 cpp
 
 
// src/compiler/pipeline.cc:3019
 CHECK(turboshaft_pipeline.Run<turboshaft::WasmLoweringPhase>());

 // TODO(14108): Do we need value numbering if wasm_opt is turned off?
 if (v8_flags.wasm_opt) {
 CHECK(turboshaft_pipeline.Run<turboshaft::WasmOptimizePhase>());
 }

The optimize phase is a CopyingPhase — each reducer rewrites the graph into a new one:

 cpp
 
 
// src/compiler/turboshaft/wasm-optimize-phase.cc:22
void WasmOptimizePhase::Run(PipelineData* data, Zone* temp_zone) {
 UnparkedScopeIfNeeded scope(data->broker(),
 v8_flags.turboshaft_trace_reduction);
 CopyingPhase<LateEscapeAnalysisReducer, MachineOptimizationReducer,
 MemoryOptimizationReducer, BranchEliminationReducer,
 LateLoadEliminationReducer, WasmCodeCoverageReducer,
 ValueNumberingReducer>::Run(data, temp_zone);
}

Escape analysis, wasm flavour

The escape analysis reducer looks for allocations whose only uses are stores into other objects. If an allocation never escapes, it does not need to be materialized on the heap at all — it can live in a register or a stack slot.

 cpp
 
 
// src/compiler/turboshaft/late-escape-analysis-reducer.cc:66
bool LateEscapeAnalysisAnalyzer::EscapesThroughUse(OpIndex alloc,
 OpIndex using_op_idx) {
 ...
 const Operation& op = graph_.Get(using_op_idx);
 if (const StoreOp* store_op = op.TryCast<StoreOp>()) {
 // A StoreOp only makes {alloc} escape if it uses {alloc} as the {value} or
 // the {index}. Put otherwise, StoreOp makes {alloc} escape if it writes
 // {alloc}, but not if it writes **to** {alloc}.
 return store_op->value() == alloc;
 }
 return true;
}

The subtlety is in the comment: storing to the allocation is fine, storing the allocation escapes. alloc.foo = 1 keeps alloc on the stack; other = alloc forces it into the heap.

There is also an older, TurboFan-era version of this reducer still in the tree, for the cases where wasm code is compiled by the TurboFan machine-graph pipeline (JS-to-wasm wrappers, and wasm inlined into JS):

 cpp
 
 
// src/compiler/wasm-escape-analysis.cc:29
 for (Edge edge : node->use_edges()) {
 if (NodeProperties::IsValueEdge(edge)) {
 if ((edge.from()->opcode() == IrOpcode::kPhi &&
 edge.from()->use_edges().empty()) ||
 (edge.index() == 0 &&
 (edge.from()->opcode() == IrOpcode::kStoreToObject ||
 edge.from()->opcode() == IrOpcode::kInitializeImmutableInObject))) {
 // StoreToObject, InitializeImmutableInObject and phis without uses can
 // be replaced and do not require the allocation.

The wasm-specific load elimination (src/compiler/wasm-load-elimination.cc) lives next to it and does the mirror-image job: it removes redundant loads from wasm locals and struct fields once the type feedback says they cannot have changed.

Tiering up in the background

The whole tier-up dance happens without blocking the caller. When the budget runs out, the runtime function schedules a top-tier compilation unit; the actual compilation happens on a background job, and the Liftoff code keeps running in the meantime.

That is not free of consequences. There is no on-stack replacement for wasm. V8’s own architecture document is explicit:

Tier-Up: V8 monitors execution frequency. When a function becomes “hot”, it triggers a tier-up to Turboshaft. Note though that we don’t do on-stack-replacement for Wasm. This means that if Turboshaft code becomes available after the function was called, the function call will complete its execution with Liftoff code.

So a long-running wasm function keeps running Liftoff code until it returns. The next call gets the optimized code.

The compilation units themselves live in a queue with work stealing:

 cpp
 
 
// src/wasm/module-compiler.cc:342
 std::optional<WasmCompilationUnit> GetNextUnitOfTier(Queue* public_queue,
 int tier) {

and top-tier units have a priority queue in front of the ordinary one, so a function that just got hot jumps the queue.

Trade-offs

What Liftoff buys. Compilation speed, and predictability. Because there is no IR and no fixpoint, Liftoff’s compile time is roughly linear in the size of the function, with a small constant. The V8 architecture document puts it at “tens of megabytes per second”. That is what makes lazy compilation viable: if the first call to a function costs a few microseconds, deferring the compile is nearly free.

What Liftoff costs.

Bad code. A value that is used once but computed three times is computed three times. A local that is live across a call but not across the loop is spilled on every iteration. Liftoff’s register allocator keeps values in registers longer than it needs to, because it cannot prove they are dead.
No constant folding, no inlining, no bounds-check elimination. The optimizing compiler does all of that; Liftoff does none of it.
A real risk of a permanent 2-3× slowdown for code that never triggers the budget. A function called ten times a second in a tight loop will trigger it; a function called ten times a second with a shallow call graph might not.

What the byte-counting budget buys over a call counter. It measures work, not frequency. A function called a million times that does almost nothing stays in Liftoff, which is correct. A function called three times that each spins for a second gets promoted, which is also correct. A pure invocation counter would get both of those wrong.

What it costs. The budget is a proxy, and proxies are noisy. That is why there is a hysteresis band with powers of two. It also means the tier-up decision depends on the shape of the generated code, which depends on the target architecture — the same wasm function has a different budget on x64 and on arm64. And the check is three instructions on every backward branch, including in functions that will never be promoted.

The bottom line

The mental model is: Liftoff is a code generator, not a compiler, and it does not try to be a good one. It decodes an opcode, emits the machine code, and moves on, keeping a stack of values and a counter of how many times each register is still needed.

The tier-up is not driven by a profiler or a call counter. It is driven by the program itself: every backward branch charges the size of the loop against a per-function budget of 13 million machine-code bytes, and when the budget goes negative the function asks to be recompiled. The recompilation happens in the background, and the caller does not wait.

And when the optimizing compiler does run, it is not TurboFan any more. It is Turboshaft, with its own wasm-specific phase list, its own escape analysis reducer, and its own load elimination.

The thing people get wrong

The belief that “Liftoff is just a simplified TurboFan” — a cheaper version of the same compiler with the optimizations switched off. It is not. Liftoff has no IR. TurboFan and Turboshaft build a graph, run reducers over it, and schedule the result onto a register allocator; the TurboFan-era wasm escape analysis reducer works on Nodes in a MachineGraph. Liftoff emits instructions as it decodes them, which is why it can compile tens of megabytes per second and why its output is debuggable instruction-by-instruction.

The second belief is that wasm tiering works like JavaScript tiering — call counts, feedback vectors, an invocation budget scaled by bytecode size. That is the JavaScript mechanism (see The Interrupt Budget), and wasm shares almost none of it. Wasm has no feedback vector, no bytecode array, and no interpreter. Its budget is a plain uint32_t array indexed by function, decremented by the generated code, and its unit is machine code bytes.

WebAssembly: How V8 Compiles a Module

Jay Hubbert — Sat, 24 Oct 2026 09:10:00 +0000

TL;DR: A wasm module is decoded into a WasmModule that keeps the wire bytes, not the code. Functions are compiled one at a time, on demand, when they are first called (CompileLazy in src/wasm/module-compiler.cc). The first version of a function is Liftoff code, emitted in a single pass straight from the bytecode; hot functions get recompiled in the background with the optimizing compiler. The generated code lives in V8’s own wasm code space, outside the JS heap, and can be serialized into a cache whose header carries a version hash, a CPU-feature hash and a flag hash — change any flag and the cache is dead.

Compiling WebAssembly is not compiling JavaScript. JavaScript has one object model, one type system, and a compiler that has to guess at types before it has any. Wasm has a static type system baked into the binary format, a linear memory, and a control flow that is already validated before a single instruction runs. That means V8’s wasm pipeline can be much more direct than its JS pipeline — and much more aggressive about deferring work.

The interesting parts are all about deferral. V8 tries hard not to compile a function until it is called, not to optimize it until it is hot, and not to persist any of it unless the embedder asks.

This is a tour of that pipeline as it exists in the V8 tree today, with the file names that actually exist (several of the classic names — wasm-code-cache.cc, wasm-lazy-compilation.cc, module-builder.cc as a pipeline stage — are gone; see the last section).

Stage 1: decoding, and what it deliberately does not do

The entry point for the whole thing is DecodeWasmModule, which builds a ModuleDecoderImpl and runs it:

 cpp
 
 
// src/wasm/module-decoder.cc:139
ModuleResult DecodeWasmModule(WasmEnabledFeatures enabled_features,
 base::Vector<const uint8_t> wire_bytes,
 bool validate_functions,
 WasmDetectedFeatures* detected_features) {
 TRACE_EVENT(TRACE_DISABLED_BY_DEFAULT("v8.wasm.detailed"),
 "wasm.DecodeWasmModule");
 ModuleDecoderImpl decoder{enabled_features, wire_bytes, detected_features};
 ModuleResult result = decoder.DecodeModule(validate_functions);
 return result;
}

The code section is walked, but the bodies are not parsed into an IR. The decoder records where each body starts and how long it is, and moves on:

 cpp
 
 
// src/wasm/module-decoder-impl.h:1549
 for (uint32_t i = 0; ok() && i < functions_count; ++i) {
 int function_index = module_->num_imported_functions + i;
 ...
 const uint8_t* pos = pc();
 uint32_t size = consume_u32v("body size", tracer_);
 ...
 uint32_t offset = pc_offset();
 consume_bytes(size, "function body");
 if (V8_UNLIKELY(failed())) break;
 DecodeFunctionBody(function_index, size, offset);

DecodeFunctionBody records a WireBytesRef — an offset and a length into the original byte buffer. That is the whole representation of a function body at this stage. V8 keeps the wire bytes alive for the lifetime of the module, and recompiles individual functions straight out of them later. This is why the wasm binary format’s “custom sections” and its byte-exact layout matter: they are the source code for the compiler, and the compiler is a compiler for a file format, not for a parsed AST.

There is no “module builder” stage in the pipeline. src/wasm/wasm-module-builder.cc exists, but it is the public C++ API (WasmModuleBuilder) that lets an embedder construct a wasm module programmatically and then serialize it back to bytes. It is a producer of wasm binaries, not a stage that consumes them.

Stage 2: lazy compilation, and the jump table that implements it

With --wasm-lazy-compilation (on by default), the module is instantiated without any function bodies compiled. Instead, the module gets a lazy compile table: a second jump table whose slots all point at a single builtin, Builtin::kWasmCompileLazy.

 cpp
 
 
// src/wasm/wasm-code-manager.cc:1259
 JumpTableAssembler::GenerateLazyCompileTable(
 lazy_compile_table_->instruction_start(), num_wasm_functions,
 module_->num_imported_functions, compile_lazy_address);

 JumpTableAssembler::InitializeJumpsToLazyCompileTable(
 code_space_data.jump_table->instruction_start(), num_wasm_functions,
 lazy_compile_table_->instruction_start());

So the first call to any function does not call that function. It calls the WasmCompileLazy builtin with the function index in a platform-specific register (kWasmCompileLazyFuncIndexRegister — edi on x64, x8 on arm64, r4 on arm32), and that builtin calls wasm::CompileLazy.

 cpp
 
 
// src/wasm/module-compiler.cc:1106
void CompileLazy(Isolate* isolate, NativeModule* native_module,
 int func_index) {
 ...
 ExecutionTierPair tiers =
 GetLazyCompilationTiers(native_module, func_index, is_in_debug_state);

 WasmCompilationUnit baseline_unit{
 func_index, tiers.baseline_tier,
 is_in_debug_state ? kForDebugging : kNotForDebugging, kAlreadyValidated};
 CompilationEnv env = CompilationEnv::ForModule(native_module);
 WasmDetectedFeatures detected_features;
 WasmCompilationResult result = baseline_unit.ExecuteCompilation(
 &env, compilation_state->GetWireBytesStorage().get(),
 native_module->counter_updates(), &detected_features);
 ...
 WasmCode* code =
 native_module->PublishCode(native_module->AddCompiledCode(result));
 ...
 if (v8_flags.wasm_lazy_compilation && tiers.baseline_tier < tiers.top_tier) {
 WasmCompilationUnit tiering_unit{func_index, tiers.top_tier,
 kNotForDebugging, kAlreadyValidated};
 compilation_state->CommitTopTierCompilationUnit(tiering_unit);
 }
}

Three things are worth noticing.

First, kAlreadyValidated. The module was fully validated before it could be instantiated, so the lazy compiler does not validate again. The comment in CompileLazy says so explicitly: “The module was fully validated before starting its execution, so lazy compilation cannot fail.” That is why the CHECK(result.succeeded()) is a CHECK and not a DCHECK.

Second, the first compilation of a lazily-compiled function is not necessarily Liftoff. It is whatever GetLazyCompilationTiers says, and that function is where compilation hints, the --wasm-tier-up-filter debug flag and the debug state all get folded in.

Third, and this is the elegant bit: the lazy compilation also schedules the top-tier compilation. Compiling a function with Liftoff is cheap but not free; compiling it with the optimizing compiler is expensive. So the moment a function is first touched, V8 puts both on the queue — the baseline one right now, on the stack, and the top-tier one on a background job.

Stage 3: the two compilers

WasmCompilationUnit::ExecuteCompilation is the fork in the road. The tier is a plain enum:

 cpp
 
 
// src/wasm/wasm-tier.h:20
// All the tiers of Wasm execution.
enum class ExecutionTier : int8_t {
 kNone,
#if V8_ENABLE_DRUMBRAKE
 kInterpreter,
#endif // V8_ENABLE_DRUMBRAKE
 kLiftoff,
 kTurbofan,
};

Note that the enum is still called kTurbofan, but the code it names is now produced by Turboshaft. V8’s wasm top tier migrated from TurboFan to Turboshaft, and the enum value was kept for compatibility with serialized code and with the profiler’s event names.

The dispatch itself:

 cpp
 
 
// src/wasm/function-compiler.cc:104
 result = ExecuteLiftoffCompilation(env, func_body, options);
 if (result.succeeded()) break;
 }

 // If --liftoff-only, do not fall back to turbofan, even if compilation
 // failed.
 if (v8_flags.liftoff_only) break;

 // If Liftoff failed, fall back to TurboFan.
 // TODO(wasm): We could actually stop or remove the tiering unit for this
 // function to avoid compiling it twice with TurboFan.
 [[fallthrough]];
 }
 case ExecutionTier::kTurbofan: {
#ifdef V8_ENABLE_TURBOFAN
 compiler::WasmCompilationData data(func_body);
 data.func_index = func_index_;
 data.wire_bytes_storage = wire_bytes_storage;
 data.validate_callees = validation_;
 result = compiler::turboshaft::ExecuteTurboshaftWasmCompilation(
 env, data, detected, counter_updates);

Liftoff is a single-pass compiler. There is no IR at all: the wasm bytecode decoder is the compiler’s visitor, and every decoded opcode emits machine code immediately.

 cpp
 
 
// src/wasm/baseline/liftoff-compiler.cc:11626
 WasmFullDecoder<Decoder::NoValidationTag, LiftoffCompiler> decoder(
 &zone, env->module, env->enabled_features,
 compiler_options.detected_features ? compiler_options.detected_features
 : &unused_detected_features,
 func_body, call_descriptor, env, &zone,
 NewLiftoffAssemblerBuffer(func_body_size), debug_sidetable_builder.get(),
 compiler_options, function_coverage_data);
 decoder.Decode();

Decoder::NoValidationTag is the tell: Liftoff trusts the module. The optimizing compiler, by contrast, builds a full graph, runs a stack of optimization phases over it, and only then emits code. See Liftoff and TurboFan: The Two WebAssembly Tiers for that side of the story.

Liftoff also has a way to say “I can’t do this”. When it hits something it does not implement, it bails out and the whole function is compiled by the optimizing compiler instead. V8 treats an unexpected bailout as a bug:

 cpp
 
 
// src/wasm/baseline/liftoff-compiler.cc:469
 // Otherwise, bailout is not allowed.
 FATAL("Liftoff bailout should not happen. Cause: %s\n", detail);

Only experimental features, missing CPU features and a handful of externally-maintained architectures are allowed to bail out.

Stage 4: the tiering state machine

Every function carries three pieces of tiering state, and they are packed into a single byte per function:

 cpp
 
 
// src/wasm/module-compiler.cc:820
 // Encoding of fields in the {compilation_progress_} vector.
 using RequiredBaselineTierField = base::BitField8<ExecutionTier, 0, 2>;
 using RequiredTopTierField = base::BitField8<ExecutionTier, 2, 2>;
 using ReachedTierField = base::BitField8<ExecutionTier, 4, 2>;

Two bits each: what tier the function must reach at the baseline, what tier it must reach at the top, and what tier it has actually reached. A uint8_t array indexed by declared function index is the entire tiering state of a module. There is no Maglev tier for wasm — the enum has three values, not four.

Which tiers a module wants is decided once, from the flags:

 cpp
 
 
// src/wasm/module-compiler.cc:976
ExecutionTierPair GetDefaultTiersPerModule(NativeModule* native_module,
 DebugState is_in_debug_state,
 bool lazy_module) {
 if (lazy_module) {
 return {ExecutionTier::kNone, ExecutionTier::kNone};
 }
 if (is_in_debug_state) {
 return {ExecutionTier::kLiftoff, ExecutionTier::kLiftoff};
 }
 ExecutionTier baseline_tier =
 v8_flags.liftoff ? ExecutionTier::kLiftoff : ExecutionTier::kTurbofan;
 bool eager_tier_up = !v8_flags.wasm_dynamic_tiering && v8_flags.wasm_tier_up;
 ExecutionTier top_tier =
 eager_tier_up ? ExecutionTier::kTurbofan : baseline_tier;
 return {baseline_tier, top_tier};
}

Read that carefully. If --wasm-dynamic-tiering is off (the default is on), and --wasm-tier-up is on, the top tier is TurboFan eagerly — every function gets compiled with the optimizing compiler up front. If dynamic tiering is on, the top tier equals the baseline tier, and the upgrade happens later, driven by the budget described in the Liftoff article.

Note also the debug state: when DevTools is attached, V8 tiers down. Both tiers become Liftoff, because Liftoff maps one wasm instruction to one contiguous run of machine code and keeps every local in its proper stack slot, while the optimizing compiler freely reorders and elides.

Stage 5: the code space

Wasm code does not live in the V8 heap’s code space. It lives in its own memory, managed by WasmCodeAllocator, and the reason is both architectural and adversarial.

The allocator reserves address space up front and commits pages lazily. The reservation size grows geometrically:

 cpp
 
 
// src/wasm/wasm-code-manager.cc:754
 size_t minimum_size = 2 * overhead;
 size_t suggested_size = std::max(
 std::max(RoundUp<kCodeAlignment>(needed_size) + overhead, minimum_size),
 total_reserved_so_far / 4);

 const size_t max_code_space_size =
 size_t{v8_flags.wasm_max_code_space_size_mb} * MB;

Three numbers bound this: overhead is the jump tables, minimum_size is twice that (so a tiny module still gets a usable code space), and the suggested size is at least a quarter of everything reserved so far, so the reservation grows exponentially rather than linearly. The hard cap is --wasm-max-code-space-size-mb, whose default is platform-dependent:

 cpp
 
 
// src/common/globals.h:511
#if V8_TARGET_ARCH_ARM64 || V8_TARGET_ARCH_LOONG64
// ARM64 and Loong64 only supports direct calls within a 128 MB range.
constexpr uint32_t kDefaultMaxWasmCodeSpaceSizeMb = 128;
#elif V8_TARGET_ARCH_PPC64
// Branches only take 26 bits.
constexpr uint32_t kDefaultMaxWasmCodeSpaceSizeMb = 32;
#else
// Use 1024 MB limit for code spaces on other platforms. This is smaller than
// the total allowed code space (kMaxWasmCodeMemory) to avoid unnecessarily
// big reservations, and to ensure that distances within a code space fit
// within a 32-bit signed integer.
constexpr uint32_t kDefaultMaxWasmCodeSpaceSizeMb = 1024;
#endif

The comment explains the real constraint: wasm functions call each other with direct branches, so two functions in the same code space must be within a 32-bit signed distance of each other. On PPC64, where branches are 26 bits, the limit drops to 32 MB. This is why a module can be spread over multiple code spaces with a far-jump table between them.

Committing is separate from reserving, and the committed total is capped process-wide:

 cpp
 
 
// src/wasm/wasm-code-manager.cc:911
 if (commit_start < commit_end) {
 for (base::AddressRegion split_range : SplitRangeByReservationsIfNeeded(
 {commit_start, commit_end - commit_start}, owned_code_space_)) {
 code_manager->Commit(split_range);
 }
 committed_code_space_.fetch_add(commit_end - commit_start);
 // Committed code cannot grow bigger than maximum code space size.
 DCHECK_LE(committed_code_space_.load(),
 v8_flags.wasm_max_committed_code_mb * MB);
 }

kMaxCommittedWasmCodeMB is 4095 — just under 4 GB — and the comment above it is explicit about why:

 cpp
 
 
// src/common/globals.h:502
// Total wasm code space per engine (i.e. per process) is limited to make
// certain attacks that rely on heap spraying harder.

Stage 6: the code cache, and how it is invalidated

V8 does have a wasm code cache, but it lives in src/wasm/wasm-serialization.cc, not in a file called wasm-code-cache.cc. The header is the interesting part:

 cpp
 
 
// src/wasm/wasm-serialization.cc:140
void WriteHeader(Writer* writer, WasmEnabledFeatures enabled_features,
 const CompileTimeImports& compile_imports) {
 DCHECK_EQ(0, writer->bytes_written());
 writer->Write(SerializedData::kMagicNumber);
 writer->Write(Version::Hash());
 writer->Write(CpuFeatures::SupportedFeatures().ToIntegral());
 writer->Write(FlagList::Hash());
 writer->Write(enabled_features.ToIntegral());
 ...

Five uint32_ts before any actual code: a magic number, a V8 version hash, the CPU features the binary was compiled for, the flag hash, and the enabled wasm features. Deserialization refuses anything whose header does not match byte for byte:

 cpp
 
 
// src/wasm/wasm-serialization.cc:1206
 if (!IsWasmCodegenAllowed(isolate, isolate->native_context())) return {};
 if (!HeaderMatches(data, enabled_features, compile_imports)) return {};

HeaderMatches does not compare hashes loosely — it recomputes the header and compares the bytes:

 cpp
 
 
// src/wasm/wasm-serialization.cc:1190
 const CompileTimeImports& compile_imports) {
 size_t header_size = MeasureHeader(compile_imports);
 if (data.size() < header_size) return false;
 base::SmallVector<uint8_t, 32> current_header(header_size);
 Writer writer(base::VectorOf(current_header));
 WriteHeader(&writer, enabled_features, compile_imports);
 DCHECK_EQ(header_size, writer.bytes_written());
 return base::VectorOf(current_header) == data.SubVector(0, header_size);
}

That is the invalidation mechanism in one sentence: the cache is valid only if recompiling it right now would produce the same header. Change the V8 version, move to a machine with a different CPU feature set, or change any flag that affects codegen, and the cached code is meaningless. The flag hash is computed by hashing every flag that is not at its default value, with a deliberate list of exclusions:

 cpp
 
 
// src/flags/flags.cc:634
 // We want to be able to flip --profile-deserialization without
 // causing the code cache to get invalidated by this hash.
 if (flag.PointsTo(&v8_flags.profile_deserialization)) continue;
 // Skip v8_flags.random_seed and v8_flags.predictable to allow predictable
 // code caching.
 if (flag.PointsTo(&v8_flags.random_seed)) continue;
 if (flag.PointsTo(&v8_flags.predictable)) continue;

The flags that do matter are the ones that change code layout: --liftoff, --wasm-tier-up, the SIMD and GC feature flags, and so on.

What gets serialized is not “the whole module” but a decision per function:

 cpp
 
 
// src/wasm/wasm-serialization.cc:483
void NativeModuleSerializer::WriteCode(
 const WasmCode* code, Writer* writer,
 const NativeModule::CallIndirectTargetMap& function_index_map) {
 if (code == nullptr) {
 writer->Write(kLazyFunction);
 return;
 }

 DCHECK_EQ(WasmCode::kWasmFunction, code->kind());
 // Only serialize TurboFan code, as Liftoff code can contain breakpoints or
 // non-relocatable constants.
 if (code->tier() != ExecutionTier::kTurbofan) {
 // We check if the function has been executed already. If so, we serialize
 // it as {kEagerFunction} so that upon deserialization the function will
 // get eagerly compiled with Liftoff (if enabled). If the function has not
 // been executed yet, we serialize it as {kLazyFunction}, and the function
 // will not get compiled upon deserialization.

Three cases: never executed → kLazyFunction, stay lazy. Executed but only Liftoff → kEagerFunction, recompile eagerly with Liftoff on deserialization. Optimized → kTurboFanFunction, serialize the actual machine code.

Liftoff code is never cached, and the reason is in the comment above: Liftoff code can contain breakpoints and non-relocatable constants. Compiling it is about as fast as reading it from a cache, so there is nothing to gain.

And the tiering budget is cached alongside, so that a function that had already burned half its budget does not get a fresh budget after a reload:

 cpp
 
 
// src/wasm/wasm-serialization.cc:505
 writer->Write(budget == static_cast<uint32_t>(v8_flags.wasm_tiering_budget)
 ? kLazyFunction
 : kEagerFunction);

Stage 7: when does V8 decide to cache?

The cache is not written eagerly. V8 emits a caching event when enough optimized code has accumulated:

 cpp
 
 
// src/wasm/module-compiler.cc:3980
 if (v8_flags.wasm_dynamic_tiering && outstanding_baseline_units_ == 0 &&
 bytes_since_last_chunk_ > 0 &&
 static_cast<size_t>(v8_flags.wasm_caching_threshold) <=
 bytes_since_last_chunk_) {

--wasm-caching-threshold is 1000 (bytes of top-tier code), and there is a hard threshold of 1 000 000 that bypasses the timeout. The timeout logic is the nice part: if code is still being produced, V8 waits; if the module has gone quiet, it caches immediately. A small module that never reaches 1000 bytes of optimized code may never be cached at all.

The event is the embedder’s cue. V8 itself does not own a disk cache for wasm — the browser does. The events are wasm.CompilationFailed, wasm.BaselineFinished and wasm.CompilationChunkFinished, and the embedder serializes the NativeModule itself when it sees the last one.

The async and streaming paths

WebAssembly.compile(bytes) and WebAssembly.compileStreaming(response) are not the same code path, and the difference is more than cosmetic.

compile hands the whole byte array to an AsyncCompileJob, which is a three-step state machine: decode on a background thread, prepare the native module on a background thread, finish on the foreground thread.

 cpp
 
 
// src/wasm/module-compiler.cc:2841
class AsyncCompileJob::DecodeModule : public AsyncCompileJob::CompileStep {
 public:
 void RunInBackground(AsyncCompileJob* job) override {
 DisallowHandleAllocation no_handle;
 DisallowHeapAllocation no_allocation;
 // Decode the module bytes.
 TRACE_COMPILE("(1) Decoding module...\n");
 ...
 ModuleResult result = DecodeWasmModule(
 enabled_features, job->wire_bytes_.module_bytes(), true,
 &job->delayed_counters_, &job->decoding_metrics_event_,
 DecodingMethod::kAsync, &job->detected_features_);

compileStreaming instead creates a StreamingDecoder, which is a byte-level state machine over the incoming chunks:

 cpp
 
 
// src/wasm/streaming-decoder.cc:71
// The decoding of a stream of wasm module bytes is organized in states. Each
// state provides a buffer to store the bytes required for the current state,
// information on how many bytes have already been received, how many bytes
// are needed, and a {Next} function which starts the next state once all
// bytes of the current state were received.
//
// The states change according to the following state diagram:
//
// Start
// |
// v
// DecodeModuleHeader
// | _________________________________________
// | | |
// v v |
// DecodeSectionID --> DecodeSectionLength --> DecodeSectionPayload
// A |
// | | (if the section id == code)
// | v
// | DecodeNumberOfFunctions -- > DecodeFunctionLength
// | A |
// | | v
// | (after all functions were read) | DecodeFunctionBody
// ------------------------------------- DecodeFunctionBody

The difference that matters: with streaming, V8 can start compiling function bodies before the whole module has arrived. It also means the module’s identity is known early — the cache is keyed on a hash of the sections up to the code section:

 cpp
 
 
// src/wasm/wasm-engine.cc:456
size_t NativeModuleCache::PrefixHash(base::Vector<const uint8_t> wire_bytes) {
 // Compute the hash as a combined hash of the sections up to the code section
 // header, to mirror the way streaming compilation does it.

So a streaming compile of a module whose prefix matches one already in the cache does not compile the module twice; it waits for the other thread to finish, or — in single-threaded mode — deliberately compiles it again and lets the cache de-duplicate the result.

Trade-offs

What it buys. Startup time scales with what you actually call, not with what the module contains. A 30 MB module with 8000 functions that calls three of them pays for three functions. Tiering means the 8000 never-called functions cost nothing but a few bytes of jump table.

What it costs.

A lazy call is not a fast call. The first call to a function goes through a builtin, a compile, and a jump-table patch. The call is dramatically slower than any subsequent one.
The tiering state is per-instance, the compiled code is per-module. Two instances of the same module share the machine code but not the tiering budgets, so one hot instance can promote the code for a cold one.
The cache header is a blunt instrument. Any change to any codegen-affecting flag invalidates every cached wasm module in the process. For a browser that means a flag change is a cold start.
Code space is committed lazily but reserved eagerly. A module that compiles 100 bytes of code can still reserve a code space sized for the whole module.

The bottom line

The wasm pipeline is a deferral machine. The decoder produces offsets, not code. The first call to a function compiles it, in one pass, with a compiler that has no IR at all. A budget burned down by the generated code itself decides when the optimizing compiler takes over, and it does so on a background thread while the Liftoff code keeps running. The resulting machine code lives outside the JS heap, in a code space whose size is bounded by branch-distance limits on one end and heap-spraying resistance on the other, and it can be serialized — but only with a header that says exactly which V8, which CPU and which flags produced it.

The mental model to keep: the wire bytes are the source code, the compile is per function and on demand, and the cache is only valid if recompiling would give the same bytes.

The thing people get wrong

Two misconceptions, both common.

The first is that “the wasm module is compiled when you call new WebAssembly.Module()”. It is not, unless lazy compilation is disabled. What happens at new WebAssembly.Module() is a decode and a validation; the machine code for a function appears when that function is first called. If you want to see this, compile a module with a thousand functions, instantiate it, and watch the code size stay at zero until you call something.

The second is that there is a file called wasm-code-cache.cc. There is not, and there has not been for a long time. The wasm code cache is src/wasm/wasm-serialization.cc (the serializer), the caching policy is src/wasm/module-compiler.cc (the events), and the disk cache itself belongs to the embedder, not to V8. V8 hands you a NativeModule and an event; what you do with them is your business.