Introduction
Compiler intermediate representations (IRs) are the backbone of code optimization. For over a decade, V8's Turbofan compiler used a Sea of Nodes (SoN) IR, which offered flexibility but eventually became a bottleneck. This guide outlines the practical steps the V8 team followed to transition to a more traditional Control-Flow Graph (CFG)-based IR, named Turboshaft. By the end, you'll understand the motivations, process, and key takeaways for similar migrations.
What You Need
- Deep understanding of compiler IRs – Familiarity with Sea of Nodes, CFG, and optimization passes.
- Knowledge of V8's architecture – Especially Turbofan, Crankshaft, and the overall pipeline.
- Team of experienced compiler engineers – This migration requires months of design, implementation, and testing.
- Performance benchmarking infrastructure – To measure improvements and regressions.
- Version control and incremental release process – Allows rolling out changes safely.
Step 1: Identify the Limitations of Your Current IR
The first step is recognizing why your existing IR no longer meets your needs. The V8 team encountered several critical issues with Sea of Nodes:
- Excessive hand-written assembly – Every IR operator addition required manual assembly code for four architectures (x64, ia32, arm, arm64).
- Struggles with asm.js optimization – The IR didn't handle control flow patterns needed for high-performance asm.js code.
- Inability to introduce control flow during lowering – Lowering high-level ops (e.g., JSAdd) to multiple branches (e.g., string vs. number addition) was impossible.
- No native try-catch support – Multiple engineers spent months attempting to add it without success.
- Performance cliffs and frequent bailouts – Unexpected spec failures could cause 100x slowdowns and deoptimization loops.
- Deoptimization cycles – The same speculative assumptions led to repeated recompilations.
Document these pain points to justify the investment and guide your new IR design.
Step 2: Design a New, More Flexible IR
Based on the identified shortcomings, design a CFG-based IR that addresses them. For V8, this became Turboshaft. Key design decisions include:
- Use explicit control flow – Allow operators to introduce branches and loops during lowering.
- Simplify operator lowering – Reduce the need for architecture-specific code by standardizing transitions.
- Support try-catch natively – Model control flow around exception handling.
- Reduce speculation overhead – Minimize performance cliffs by allowing graceful fallbacks.
- Enable incremental migration – Design the new IR to coexist with the old one during transition.
Prototype small components first to validate the design.
Step 3: Replace the Backend First
Start migration with the component that provides the most immediate benefit. V8 began with the JavaScript backend of Turbofan, converting it entirely to Turboshaft. This allowed the team to:
- Test the new IR on a large codebase with real-world benchmarks.
- Fix issues in backend lowering and instruction selection without affecting the frontend.
- Gradually retire Sea of Nodes for the backend, reducing maintenance overhead.
After the JavaScript backend was stable, extend the new IR to the WebAssembly pipeline. V8 completed this for the entire wasm pipeline, proving the design's viability.
Step 4: Replace the Builtin Pipeline Incrementally
The builtin pipeline (handling intrinsic functions) still uses some Sea of Nodes. Instead of a big-bang rewrite, replace builtins one by one. Each builtin migration involves:
- Identify the builtin's behavior and its IR usage.
- Implement the same functionality in Turboshaft.
- Test equivalently with the old and new IR.
- Deploy the new version and verify performance.
This approach minimizes risk and allows continuous delivery of improvements.
Step 5: Replace the Frontend Using a Complementary CFG IR
The JavaScript frontend (graph building and initial lowering) still uses Sea of Nodes. Rather than converting it to Turboshaft directly, V8 is replacing it with an entirely new CFG-based IR called Maglev. Maglev is designed specifically for frontend tasks like fast graph construction and speculative optimizations.
Steps to follow:
- Design Maglev to handle the same input as the old frontend.
- Implement it side-by-side with the existing frontend.
- Gradually enable Maglev for more functions.
- Monitor deoptimization rates and code quality.
- Once mature, retire the Sea of Nodes frontend entirely.
Step 6: Validate and Optimize at Each Stage
Throughout the migration, continuously validate:
- Correctness – Use fuzz testing and regression suites.
- Performance – Benchmark startup time, execution time, and memory.
- Stability – Monitor for crashes or increased deoptimizations.
Use A/B testing in production to catch regressions early.
Conclusion & Tips
Migrating a production compiler's IR is a multi-year effort, but the benefits—reduced complexity, fewer performance cliffs, and easier feature additions—make it worthwhile. Based on V8's experience, here are key tips:
- Start with a clear motivation: Document the pain points to align the team.
- Design for incremental adoption: Allow both IRs to coexist during transition.
- Prioritize backend first: It gives the most performance wins and reduces technical debt.
- Don't be afraid to create a second new IR: Maglev shows that specialized components can be cleaner than a monolithic replacement.
- Invest in testing automation: A migration of this scale will catch subtle bugs.
- Communicate progress openly: Regular updates help stakeholders understand delays and successes.
For more details on V8's journey, refer to the original blog post on the V8 blog. Internal links to each step: Step 1, Step 2, Step 3, Step 4, Step 5, Step 6.