Migrating a Compiler from Sea of Nodes to Control-Flow Graph: A Step-by-Step Guide

By • min read

<h2>Introduction</h2> <p>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.</p><figure style="margin:20px 0"><img src="https://v8.dev/_img/leaving-the-sea-of-nodes/CFG-example-1.svg" alt="Migrating a Compiler from Sea of Nodes to Control-Flow Graph: A Step-by-Step Guide" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: v8.dev</figcaption></figure> <h2>What You Need</h2> <ul> <li><strong>Deep understanding of compiler IRs</strong> – Familiarity with Sea of Nodes, CFG, and optimization passes.</li> <li><strong>Knowledge of V8's architecture</strong> – Especially Turbofan, Crankshaft, and the overall pipeline.</li> <li><strong>Team of experienced compiler engineers</strong> – This migration requires months of design, implementation, and testing.</li> <li><strong>Performance benchmarking infrastructure</strong> – To measure improvements and regressions.</li> <li><strong>Version control and incremental release process</strong> – Allows rolling out changes safely.</li> </ul> <h2>Step 1: Identify the Limitations of Your Current IR</h2> <p>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:</p> <ul> <li><strong>Excessive hand-written assembly</strong> – Every IR operator addition required manual assembly code for four architectures (x64, ia32, arm, arm64).</li> <li><strong>Struggles with asm.js optimization</strong> – The IR didn't handle control flow patterns needed for high-performance asm.js code.</li> <li><strong>Inability to introduce control flow during lowering</strong> – Lowering high-level ops (e.g., JSAdd) to multiple branches (e.g., string vs. number addition) was impossible.</li> <li><strong>No native try-catch support</strong> – Multiple engineers spent months attempting to add it without success.</li> <li><strong>Performance cliffs and frequent bailouts</strong> – Unexpected spec failures could cause 100x slowdowns and deoptimization loops.</li> <li><strong>Deoptimization cycles</strong> – The same speculative assumptions led to repeated recompilations.</li> </ul> <p>Document these pain points to justify the investment and guide your new IR design.</p> <h2>Step 2: Design a New, More Flexible IR</h2> <p>Based on the identified shortcomings, design a CFG-based IR that addresses them. For V8, this became Turboshaft. Key design decisions include:</p> <ul> <li><strong>Use explicit control flow</strong> – Allow operators to introduce branches and loops during lowering.</li> <li><strong>Simplify operator lowering</strong> – Reduce the need for architecture-specific code by standardizing transitions.</li> <li><strong>Support try-catch natively</strong> – Model control flow around exception handling.</li> <li><strong>Reduce speculation overhead</strong> – Minimize performance cliffs by allowing graceful fallbacks.</li> <li><strong>Enable incremental migration</strong> – Design the new IR to coexist with the old one during transition.</li> </ul> <p>Prototype small components first to validate the design.</p> <h2>Step 3: Replace the Backend First</h2> <p>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:</p> <ul> <li>Test the new IR on a large codebase with real-world benchmarks.</li> <li>Fix issues in backend lowering and instruction selection without affecting the frontend.</li> <li>Gradually retire Sea of Nodes for the backend, reducing maintenance overhead.</li> </ul> <p>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.</p> <h2>Step 4: Replace the Builtin Pipeline Incrementally</h2> <p>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:</p> <ol> <li>Identify the builtin's behavior and its IR usage.</li> <li>Implement the same functionality in Turboshaft.</li> <li>Test equivalently with the old and new IR.</li> <li>Deploy the new version and verify performance.</li> </ol> <p>This approach minimizes risk and allows continuous delivery of improvements.</p> <h2>Step 5: Replace the Frontend Using a Complementary CFG IR</h2> <p>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 <strong>Maglev</strong>. Maglev is designed specifically for frontend tasks like fast graph construction and speculative optimizations.</p> <p>Steps to follow:</p> <ul> <li>Design Maglev to handle the same input as the old frontend.</li> <li>Implement it side-by-side with the existing frontend.</li> <li>Gradually enable Maglev for more functions.</li> <li>Monitor deoptimization rates and code quality.</li> <li>Once mature, retire the Sea of Nodes frontend entirely.</li> </ul> <h2>Step 6: Validate and Optimize at Each Stage</h2> <p>Throughout the migration, continuously validate:</p> <ul> <li><strong>Correctness</strong> – Use fuzz testing and regression suites.</li> <li><strong>Performance</strong> – Benchmark startup time, execution time, and memory.</li> <li><strong>Stability</strong> – Monitor for crashes or increased deoptimizations.</li> </ul> <p>Use A/B testing in production to catch regressions early.</p> <h2>Conclusion &amp; Tips</h2> <p>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:</p> <ul> <li><strong>Start with a clear motivation:</strong> Document the pain points to align the team.</li> <li><strong>Design for incremental adoption:</strong> Allow both IRs to coexist during transition.</li> <li><strong>Prioritize backend first:</strong> It gives the most performance wins and reduces technical debt.</li> <li><strong>Don't be afraid to create a second new IR:</strong> Maglev shows that specialized components can be cleaner than a monolithic replacement.</li> <li><strong>Invest in testing automation:</strong> A migration of this scale will catch subtle bugs.</li> <li><strong>Communicate progress openly:</strong> Regular updates help stakeholders understand delays and successes.</li> </ul> <p>For more details on V8's journey, refer to the original blog post on the V8 blog. Internal links to each step: <a href='#step1'>Step 1</a>, <a href='#step2'>Step 2</a>, <a href='#step3'>Step 3</a>, <a href='#step4'>Step 4</a>, <a href='#step5'>Step 5</a>, <a href='#step6'>Step 6</a>.</p>