backend/backend-agnostic.html - rust-lang/rustc-dev-guide - Git at Google

 <!DOCTYPE HTML>
 <html lang="en" class="light sidebar-visible" dir="ltr">
     <head>
         <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
         <title>Backend Agnostic Codegen - Rust Compiler Development Guide</title>


         <!-- Custom HTML head -->

         <meta name="description" content="A guide to developing the Rust compiler (rustc)">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <meta name="theme-color" content="#ffffff">

         <link rel="icon" href="../favicon.svg">
         <link rel="shortcut icon" href="../favicon.png">
         <link rel="stylesheet" href="../css/variables.css">
         <link rel="stylesheet" href="../css/general.css">
         <link rel="stylesheet" href="../css/chrome.css">
         <link rel="stylesheet" href="../css/print.css" media="print">

         <!-- Fonts -->
         <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
         <link rel="stylesheet" href="../fonts/fonts.css">

         <!-- Highlight.js Stylesheets -->
         <link rel="stylesheet" id="highlight-css" href="../highlight.css">
         <link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
         <link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">

         <!-- Custom theme stylesheets -->
         <link rel="stylesheet" href="../pagetoc.css">


         <!-- Provide site root and default themes to javascript -->
         <script>
             const path_to_root = "../";
             const default_light_theme = "light";
             const default_dark_theme = "navy";
             window.path_to_searchindex_js = "../searchindex.js";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="../toc.js"></script>
     </head>
     <body>
     <div id="mdbook-help-container">
         <div id="mdbook-help-popup">
             <h2 class="mdbook-help-title">Keyboard shortcuts</h2>
             <div>
                 <p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
                 <p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
                 <p>Press <kbd>?</kbd> to show this help</p>
                 <p>Press <kbd>Esc</kbd> to hide this help</p>
             </div>
         </div>
     </div>
     <div id="body-container">
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
         <script>
             try {
                 let theme = localStorage.getItem('mdbook-theme');
                 let sidebar = localStorage.getItem('mdbook-sidebar');

                 if (theme.startsWith('"') && theme.endsWith('"')) {
                     localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                 }

                 if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                     localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                 }
             } catch (e) { }
         </script>

         <!-- Set the theme before any content is loaded, prevents flash -->
         <script>
             const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
             let theme;
             try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
             if (theme === null || theme === undefined) { theme = default_theme; }
             const html = document.documentElement;
             html.classList.remove('light')
             html.classList.add(theme);
             html.classList.add("js");
         </script>

         <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

         <!-- Hide / unhide sidebar before it is displayed -->
         <script>
             let sidebar = null;
             const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
             if (document.body.clientWidth >= 1080) {
                 try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                 sidebar = sidebar || 'visible';
             } else {
                 sidebar = 'hidden';
                 sidebar_toggle.checked = false;
             }
             if (sidebar === 'visible') {
                 sidebar_toggle.checked = true;
             } else {
                 html.classList.remove('sidebar-visible');
             }
         </script>

         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <!-- populated by js -->
             <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
             <noscript>
                 <iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
             </noscript>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                 <div class="sidebar-resize-indicator"></div>
             </div>
         </nav>

         <div id="page-wrapper" class="page-wrapper">

             <div class="page">
                 <div id="menu-bar-hover-placeholder"></div>
                 <div id="menu-bar" class="menu-bar sticky">
                     <div class="left-buttons">
                         <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                             <i class="fa fa-bars"></i>
                         </label>
                         <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                             <i class="fa fa-paint-brush"></i>
                         </button>
                         <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                             <li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                         </ul>
                         <button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
                             <i class="fa fa-search"></i>
                         </button>
                     </div>

                     <h1 class="menu-title">Rust Compiler Development Guide</h1>

                     <div class="right-buttons">
                         <a href="../print.html" title="Print this book" aria-label="Print this book">
                             <i id="print-button" class="fa fa-print"></i>
                         </a>
                         <a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
                         <a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/backend/backend-agnostic.md" title="Suggest an edit" aria-label="Suggest an edit" rel="edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>

                     </div>
                 </div>

                 <div id="search-wrapper" class="hidden">
                     <form id="searchbar-outer" class="searchbar-outer">
                         <div class="search-wrapper">
                             <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                             <div class="spinner-wrapper">
                                 <i class="fa fa-spinner fa-spin"></i>
                             </div>
                         </div>
                     </form>
                     <div id="searchresults-outer" class="searchresults-outer hidden">
                         <div id="searchresults-header" class="searchresults-header"></div>
                         <ul id="searchresults">
                         </ul>
                     </div>
                 </div>

                 <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                 <script>
                     document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                     document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                     Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                         link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                     });
                 </script>

                 <div id="content" class="content">
                     <main>
                         <h1 id="backend-agnostic-codegen"><a class="header" href="#backend-agnostic-codegen">Backend Agnostic Codegen</a></h1>
 <p><a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/index.html"><code>rustc_codegen_ssa</code></a>
 provides an abstract interface for all backends to implement,
 namely LLVM, <a href="https://github.com/rust-lang/rustc_codegen_cranelift">Cranelift</a>, and <a href="https://github.com/rust-lang/rustc_codegen_gcc">GCC</a>.</p>
 <p>Below is some background information on the refactoring that created this
 abstract interface.</p>
 <h2 id="refactoring-of-rustc_codegen_llvm"><a class="header" href="#refactoring-of-rustc_codegen_llvm">Refactoring of <code>rustc_codegen_llvm</code></a></h2>
 <p>by Denis Merigoux, October 23rd 2018</p>
 <h3 id="state-of-the-code-before-the-refactoring"><a class="header" href="#state-of-the-code-before-the-refactoring">State of the code before the refactoring</a></h3>
 <p>All the code related to the compilation of MIR into LLVM IR was contained
 inside the <code>rustc_codegen_llvm</code> crate. Here is the breakdown of the most
 important elements:</p>
 <ul>
 <li>the <code>back</code> folder (7,800 LOC) implements the mechanisms for creating the
 different object files and archive through LLVM, but also the communication
 mechanisms for parallel code generation;</li>
 <li>the <code>debuginfo</code> (3,200 LOC) folder contains all code that passes debug
 information down to LLVM;</li>
 <li>the <code>llvm</code> (2,200 LOC) folder defines the FFI necessary to communicate with
 LLVM using the C++ API;</li>
 <li>the <code>mir</code> (4,300 LOC) folder implements the actual lowering from MIR to LLVM
 IR;</li>
 <li>the <code>base.rs</code> (1,300 LOC) file contains some helper functions but also the
 high-level code that launches the code generation and distributes the work.</li>
 <li>the <code>builder.rs</code> (1,200 LOC) file contains all the functions generating
 individual LLVM IR instructions inside a basic block;</li>
 <li>the <code>common.rs</code> (450 LOC) contains various helper functions and all the
 functions generating LLVM static values;</li>
 <li>the <code>type_.rs</code> (300 LOC) defines most of the type translations to LLVM IR.</li>
 </ul>
 <p>The goal of this refactoring is to separate inside this crate code that is
 specific to the LLVM from code that can be reused for other rustc backends. For
 instance, the <code>mir</code> folder is almost entirely backend-specific but it relies
 heavily on other parts of the crate. The separation of the code must not affect
 the logic of the code nor its performance.</p>
 <p>For these reasons, the separation process involves two transformations that
 have to be done at the same time for the resulting code to compile:</p>
 <ol>
 <li>replace all the LLVM-specific types by generics inside function signatures
 and structure definitions;</li>
 <li>encapsulate all functions calling the LLVM FFI inside a set of traits that
 will define the interface between backend-agnostic code and the backend.</li>
 </ol>
 <p>While the LLVM-specific code will be left in <code>rustc_codegen_llvm</code>, all the new
 traits and backend-agnostic code will be moved in <code>rustc_codegen_ssa</code> (name
 suggestion by @eddyb).</p>
 <h3 id="generic-types-and-structures"><a class="header" href="#generic-types-and-structures">Generic types and structures</a></h3>
 <p>@irinagpopa started to parametrize the types of <code>rustc_codegen_llvm</code> by a
 generic <code>Value</code> type, implemented in LLVM by a reference <code>&amp;'ll Value</code>. This
 work has been extended to all structures inside the <code>mir</code> folder and elsewhere,
 as well as for LLVM's <code>BasicBlock</code> and <code>Type</code> types.</p>
 <p>The two most important structures for the LLVM codegen are <code>CodegenCx</code> and
 <code>Builder</code>. They are parametrized by multiple lifetime parameters and the type
 for <code>Value</code>.</p>
 <pre><code class="language-rust ignore">struct CodegenCx&lt;'ll, 'tcx&gt; {
   /* ... */
 }

 struct Builder&lt;'a, 'll, 'tcx&gt; {
   cx: &amp;'a CodegenCx&lt;'ll, 'tcx&gt;,
   /* ... */
 }</code></pre>
 <p><code>CodegenCx</code> is used to compile one codegen-unit that can contain multiple
 functions, whereas <code>Builder</code> is created to compile one basic block.</p>
 <p>The code in <code>rustc_codegen_llvm</code> has to deal with multiple explicit lifetime
 parameters, that correspond to the following:</p>
 <ul>
 <li><code>'tcx</code> is the longest lifetime, that corresponds to the original <code>TyCtxt</code>
 containing the program's information;</li>
 <li><code>'a</code> is a short-lived reference of a <code>CodegenCx</code> or another object inside a
 struct;</li>
 <li><code>'ll</code> is the lifetime of references to LLVM objects such as <code>Value</code> or
 <code>Type</code>.</li>
 </ul>
 <p>Although there are already many lifetime parameters in the code, making it
 generic uncovered situations where the borrow-checker was passing only due to
 the special nature of the LLVM objects manipulated (they are extern pointers).
 For instance, an additional lifetime parameter had to be added to
 <code>LocalAnalyser</code> in <code>analyse.rs</code>, leading to the definition:</p>
 <pre><code class="language-rust ignore">struct LocalAnalyzer&lt;'mir, 'a, 'tcx&gt; {
   /* ... */
 }</code></pre>
 <p>However, the two most important structures <code>CodegenCx</code> and <code>Builder</code> are not
 defined in the backend-agnostic code. Indeed, their content is highly specific
 of the backend and it makes more sense to leave their definition to the backend
 implementor than to allow just a narrow spot via a generic field for the
 backend's context.</p>
 <h3 id="traits-and-interface"><a class="header" href="#traits-and-interface">Traits and interface</a></h3>
 <p>Because they have to be defined by the backend, <code>CodegenCx</code> and <code>Builder</code> will
 be the structures implementing all the traits defining the backend's interface.
 These traits are defined in the folder <code>rustc_codegen_ssa/traits</code> and all the
 backend-agnostic code is parametrized by them. For instance, let us explain how
 a function in <code>base.rs</code> is parametrized:</p>
 <pre><code class="language-rust ignore">pub fn codegen_instance&lt;'a, 'tcx, Bx: BuilderMethods&lt;'a, 'tcx&gt;&gt;(
     cx: &amp;'a Bx::CodegenCx,
     instance: Instance&lt;'tcx&gt;
 ) {
     /* ... */
 }</code></pre>
 <p>In this signature, we have the two lifetime parameters explained earlier and
 the master type <code>Bx</code> which satisfies the trait <code>BuilderMethods</code> corresponding
 to the interface satisfied by the <code>Builder</code> struct. The <code>BuilderMethods</code>
 defines an associated type <code>Bx::CodegenCx</code> that itself satisfies the
 <code>CodegenMethods</code> traits implemented by the struct <code>CodegenCx</code>.</p>
 <p>On the trait side, here is an example with part of the definition of
 <code>BuilderMethods</code> in <code>traits/builder.rs</code>:</p>
 <pre><code class="language-rust ignore">pub trait BuilderMethods&lt;'a, 'tcx&gt;:
     HasCodegen&lt;'tcx&gt;
     + DebugInfoBuilderMethods&lt;'tcx&gt;
     + ArgTypeMethods&lt;'tcx&gt;
     + AbiBuilderMethods&lt;'tcx&gt;
     + IntrinsicCallMethods&lt;'tcx&gt;
     + AsmBuilderMethods&lt;'tcx&gt;
 {
     fn new_block&lt;'b&gt;(
         cx: &amp;'a Self::CodegenCx,
         llfn: Self::Function,
         name: &amp;'b str
     ) -&gt; Self;
     /* ... */
     fn cond_br(
         &amp;mut self,
         cond: Self::Value,
         then_llbb: Self::BasicBlock,
         else_llbb: Self::BasicBlock,
     );
     /* ... */
 }</code></pre>
 <p>Finally, a master structure implementing the <code>ExtraBackendMethods</code> trait is
 used for high-level codegen-driving functions like <code>codegen_crate</code> in
 <code>base.rs</code>. For LLVM, it is the empty <code>LlvmCodegenBackend</code>.
 <code>ExtraBackendMethods</code> should be implemented by the same structure that
 implements the <code>CodegenBackend</code> defined in
 <code>rustc_codegen_utils/codegen_backend.rs</code>.</p>
 <p>During the traitification process, certain functions have been converted from
 methods of a local structure to methods of <code>CodegenCx</code> or <code>Builder</code> and a
 corresponding <code>self</code> parameter has been added. Indeed, LLVM stores information
 internally that it can access when called through its API. This information
 does not show up in a Rust data structure carried around when these methods are
 called. However, when implementing a Rust backend for <code>rustc</code>, these methods
 will need information from <code>CodegenCx</code>, hence the additional parameter (unused
 in the LLVM implementation of the trait).</p>
 <h3 id="state-of-the-code-after-the-refactoring"><a class="header" href="#state-of-the-code-after-the-refactoring">State of the code after the refactoring</a></h3>
 <p>The traits offer an API which is very similar to the API of LLVM. This is not
 the best solution since LLVM has a very special way of doing things: when
 adding another backend, the traits definition might be changed in order to
 offer more flexibility.</p>
 <p>However, the current separation between backend-agnostic and LLVM-specific code
 has allowed the reuse of a significant part of the old <code>rustc_codegen_llvm</code>.
 Here is the new LOC breakdown between backend-agnostic (BA) and LLVM for the
 most important elements:</p>
 <ul>
 <li><code>back</code> folder: 3,800 (BA) vs 4,100 (LLVM);</li>
 <li><code>mir</code> folder: 4,400 (BA) vs 0 (LLVM);</li>
 <li><code>base.rs</code>: 1,100 (BA) vs 250 (LLVM);</li>
 <li><code>builder.rs</code>: 1,400 (BA) vs 0 (LLVM);</li>
 <li><code>common.rs</code>: 350 (BA) vs 350 (LLVM);</li>
 </ul>
 <p>The <code>debuginfo</code> folder has been left almost untouched by the splitting and is
 specific to LLVM. Only its high-level features have been traitified.</p>
 <p>The new <code>traits</code> folder has 1500 LOC only for trait definitions. Overall, the
 27,000 LOC-sized old <code>rustc_codegen_llvm</code> code has been split into the new
 18,500 LOC-sized new <code>rustc_codegen_llvm</code> and the 12,000 LOC-sized
 <code>rustc_codegen_ssa</code>. We can say that this refactoring allowed the reuse of
 approximately 10,000 LOC that would otherwise have had to be duplicated between
 the multiple backends of <code>rustc</code>.</p>
 <p>The refactored version of <code>rustc</code>'s backend introduced no regression over the
 test suite nor in performance benchmark, which is in coherence with the nature
 of the refactoring that used only compile-time parametricity (no trait
 objects).</p>

                     </main>

                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
                             <a rel="prev" href="../backend/debugging.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>

                             <a rel="next prefetch" href="../backend/implicit-caller-location.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>

                         <div style="clear: both"></div>
                     </nav>
                 </div>
             </div>

             <nav class="nav-wide-wrapper" aria-label="Page navigation">
                     <a rel="prev" href="../backend/debugging.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <i class="fa fa-angle-left"></i>
                     </a>

                     <a rel="next prefetch" href="../backend/implicit-caller-location.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                         <i class="fa fa-angle-right"></i>
                     </a>
             </nav>

         </div>


         <script>
             window.playground_copyable = true;
         </script>


         <script src="../elasticlunr.min.js"></script>
         <script src="../mark.min.js"></script>
         <script src="../searcher.js"></script>

         <script src="../clipboard.min.js"></script>
         <script src="../highlight.js"></script>
         <script src="../book.js"></script>

         <!-- Custom JS scripts -->
         <script src="../mermaid.min.js"></script>
         <script src="../mermaid-init.js"></script>
         <script src="../pagetoc.js"></script>


     </div>
     </body>
 </html>
	<!DOCTYPE HTML>
	<html lang="en" class="light sidebar-visible" dir="ltr">
	<head>
	<!-- Book generated using mdBook -->
	<meta charset="UTF-8">
	<title>Backend Agnostic Codegen - Rust Compiler Development Guide</title>


	<!-- Custom HTML head -->

	<meta name="description" content="A guide to developing the Rust compiler (rustc)">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<meta name="theme-color" content="#ffffff">

	<link rel="icon" href="../favicon.svg">
	<link rel="shortcut icon" href="../favicon.png">
	<link rel="stylesheet" href="../css/variables.css">
	<link rel="stylesheet" href="../css/general.css">
	<link rel="stylesheet" href="../css/chrome.css">
	<link rel="stylesheet" href="../css/print.css" media="print">

	<!-- Fonts -->
	<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
	<link rel="stylesheet" href="../fonts/fonts.css">

	<!-- Highlight.js Stylesheets -->
	<link rel="stylesheet" id="highlight-css" href="../highlight.css">
	<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
	<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">

	<!-- Custom theme stylesheets -->
	<link rel="stylesheet" href="../pagetoc.css">


	<!-- Provide site root and default themes to javascript -->
	<script>
	const path_to_root = "../";
	const default_light_theme = "light";
	const default_dark_theme = "navy";
	window.path_to_searchindex_js = "../searchindex.js";
	</script>
	<!-- Start loading toc.js asap -->
	<script src="../toc.js"></script>
	</head>
	<body>
	<div id="mdbook-help-container">
	<div id="mdbook-help-popup">
	<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
	<div>
	<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
	<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
	<p>Press <kbd>?</kbd> to show this help</p>
	<p>Press <kbd>Esc</kbd> to hide this help</p>
	</div>
	</div>
	</div>
	<div id="body-container">
	<!-- Work around some values being stored in localStorage wrapped in quotes -->
	<script>
	try {
	let theme = localStorage.getItem('mdbook-theme');
	let sidebar = localStorage.getItem('mdbook-sidebar');

	if (theme.startsWith('"') && theme.endsWith('"')) {
	localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
	}

	if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
	localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
	}
	} catch (e) { }
	</script>

	<!-- Set the theme before any content is loaded, prevents flash -->
	<script>
	const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
	let theme;
	try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
	if (theme === null \|\| theme === undefined) { theme = default_theme; }
	const html = document.documentElement;
	html.classList.remove('light')
	html.classList.add(theme);
	html.classList.add("js");
	</script>

	<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

	<!-- Hide / unhide sidebar before it is displayed -->
	<script>
	let sidebar = null;
	const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
	if (document.body.clientWidth >= 1080) {
	try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
	sidebar = sidebar \|\| 'visible';
	} else {
	sidebar = 'hidden';
	sidebar_toggle.checked = false;
	}
	if (sidebar === 'visible') {
	sidebar_toggle.checked = true;
	} else {
	html.classList.remove('sidebar-visible');
	}
	</script>

	<nav id="sidebar" class="sidebar" aria-label="Table of contents">
	<!-- populated by js -->
	<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
	<noscript>
	<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
	</noscript>
	<div id="sidebar-resize-handle" class="sidebar-resize-handle">
	<div class="sidebar-resize-indicator"></div>
	</div>
	</nav>

	<div id="page-wrapper" class="page-wrapper">

	<div class="page">
	<div id="menu-bar-hover-placeholder"></div>
	<div id="menu-bar" class="menu-bar sticky">
	<div class="left-buttons">
	<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
	<i class="fa fa-bars"></i>
	</label>
	<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
	<i class="fa fa-paint-brush"></i>
	</button>
	<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
	<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
	<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
	<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
	<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
	<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
	<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
	</ul>
	<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
	<i class="fa fa-search"></i>
	</button>
	</div>

	<h1 class="menu-title">Rust Compiler Development Guide</h1>

	<div class="right-buttons">
	<a href="../print.html" title="Print this book" aria-label="Print this book">
	<i id="print-button" class="fa fa-print"></i>
	</a>
	<a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
	<i id="git-repository-button" class="fa fa-github"></i>
	</a>
	<a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/backend/backend-agnostic.md" title="Suggest an edit" aria-label="Suggest an edit" rel="edit">
	<i id="git-edit-button" class="fa fa-edit"></i>
	</a>

	</div>
	</div>

	<div id="search-wrapper" class="hidden">
	<form id="searchbar-outer" class="searchbar-outer">
	<div class="search-wrapper">
	<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
	<div class="spinner-wrapper">
	<i class="fa fa-spinner fa-spin"></i>
	</div>
	</div>
	</form>
	<div id="searchresults-outer" class="searchresults-outer hidden">
	<div id="searchresults-header" class="searchresults-header"></div>
	<ul id="searchresults">
	</ul>
	</div>
	</div>

	<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
	<script>
	document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
	document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
	Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
	link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
	});
	</script>

	<div id="content" class="content">
	<main>
	<h1 id="backend-agnostic-codegen"><a class="header" href="#backend-agnostic-codegen">Backend Agnostic Codegen</a></h1>
	<p><a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/index.html"><code>rustc_codegen_ssa</code></a>
	provides an abstract interface for all backends to implement,
	namely LLVM, <a href="https://github.com/rust-lang/rustc_codegen_cranelift">Cranelift</a>, and <a href="https://github.com/rust-lang/rustc_codegen_gcc">GCC</a>.</p>
	<p>Below is some background information on the refactoring that created this
	abstract interface.</p>
	<h2 id="refactoring-of-rustc_codegen_llvm"><a class="header" href="#refactoring-of-rustc_codegen_llvm">Refactoring of <code>rustc_codegen_llvm</code></a></h2>
	<p>by Denis Merigoux, October 23rd 2018</p>
	<h3 id="state-of-the-code-before-the-refactoring"><a class="header" href="#state-of-the-code-before-the-refactoring">State of the code before the refactoring</a></h3>
	<p>All the code related to the compilation of MIR into LLVM IR was contained
	inside the <code>rustc_codegen_llvm</code> crate. Here is the breakdown of the most
	important elements:</p>
	<ul>
	<li>the <code>back</code> folder (7,800 LOC) implements the mechanisms for creating the
	different object files and archive through LLVM, but also the communication
	mechanisms for parallel code generation;</li>
	<li>the <code>debuginfo</code> (3,200 LOC) folder contains all code that passes debug
	information down to LLVM;</li>
	<li>the <code>llvm</code> (2,200 LOC) folder defines the FFI necessary to communicate with
	LLVM using the C++ API;</li>
	<li>the <code>mir</code> (4,300 LOC) folder implements the actual lowering from MIR to LLVM
	IR;</li>
	<li>the <code>base.rs</code> (1,300 LOC) file contains some helper functions but also the
	high-level code that launches the code generation and distributes the work.</li>
	<li>the <code>builder.rs</code> (1,200 LOC) file contains all the functions generating
	individual LLVM IR instructions inside a basic block;</li>
	<li>the <code>common.rs</code> (450 LOC) contains various helper functions and all the
	functions generating LLVM static values;</li>
	<li>the <code>type_.rs</code> (300 LOC) defines most of the type translations to LLVM IR.</li>
	</ul>
	<p>The goal of this refactoring is to separate inside this crate code that is
	specific to the LLVM from code that can be reused for other rustc backends. For
	instance, the <code>mir</code> folder is almost entirely backend-specific but it relies
	heavily on other parts of the crate. The separation of the code must not affect
	the logic of the code nor its performance.</p>
	<p>For these reasons, the separation process involves two transformations that
	have to be done at the same time for the resulting code to compile:</p>
	<ol>
	<li>replace all the LLVM-specific types by generics inside function signatures
	and structure definitions;</li>
	<li>encapsulate all functions calling the LLVM FFI inside a set of traits that
	will define the interface between backend-agnostic code and the backend.</li>
	</ol>
	<p>While the LLVM-specific code will be left in <code>rustc_codegen_llvm</code>, all the new
	traits and backend-agnostic code will be moved in <code>rustc_codegen_ssa</code> (name
	suggestion by @eddyb).</p>
	<h3 id="generic-types-and-structures"><a class="header" href="#generic-types-and-structures">Generic types and structures</a></h3>
	<p>@irinagpopa started to parametrize the types of <code>rustc_codegen_llvm</code> by a
	generic <code>Value</code> type, implemented in LLVM by a reference <code>&'ll Value</code>. This
	work has been extended to all structures inside the <code>mir</code> folder and elsewhere,
	as well as for LLVM's <code>BasicBlock</code> and <code>Type</code> types.</p>
	<p>The two most important structures for the LLVM codegen are <code>CodegenCx</code> and
	<code>Builder</code>. They are parametrized by multiple lifetime parameters and the type
	for <code>Value</code>.</p>
	<pre><code class="language-rust ignore">struct CodegenCx<'ll, 'tcx> {
	/* ... */
	}

	struct Builder<'a, 'll, 'tcx> {
	cx: &'a CodegenCx<'ll, 'tcx>,
	/* ... */
	}</code></pre>
	<p><code>CodegenCx</code> is used to compile one codegen-unit that can contain multiple
	functions, whereas <code>Builder</code> is created to compile one basic block.</p>
	<p>The code in <code>rustc_codegen_llvm</code> has to deal with multiple explicit lifetime
	parameters, that correspond to the following:</p>
	<ul>
	<li><code>'tcx</code> is the longest lifetime, that corresponds to the original <code>TyCtxt</code>
	containing the program's information;</li>
	<li><code>'a</code> is a short-lived reference of a <code>CodegenCx</code> or another object inside a
	struct;</li>
	<li><code>'ll</code> is the lifetime of references to LLVM objects such as <code>Value</code> or
	<code>Type</code>.</li>
	</ul>
	<p>Although there are already many lifetime parameters in the code, making it
	generic uncovered situations where the borrow-checker was passing only due to
	the special nature of the LLVM objects manipulated (they are extern pointers).
	For instance, an additional lifetime parameter had to be added to
	<code>LocalAnalyser</code> in <code>analyse.rs</code>, leading to the definition:</p>
	<pre><code class="language-rust ignore">struct LocalAnalyzer<'mir, 'a, 'tcx> {
	/* ... */
	}</code></pre>
	<p>However, the two most important structures <code>CodegenCx</code> and <code>Builder</code> are not
	defined in the backend-agnostic code. Indeed, their content is highly specific
	of the backend and it makes more sense to leave their definition to the backend
	implementor than to allow just a narrow spot via a generic field for the
	backend's context.</p>
	<h3 id="traits-and-interface"><a class="header" href="#traits-and-interface">Traits and interface</a></h3>
	<p>Because they have to be defined by the backend, <code>CodegenCx</code> and <code>Builder</code> will
	be the structures implementing all the traits defining the backend's interface.
	These traits are defined in the folder <code>rustc_codegen_ssa/traits</code> and all the
	backend-agnostic code is parametrized by them. For instance, let us explain how
	a function in <code>base.rs</code> is parametrized:</p>
	<pre><code class="language-rust ignore">pub fn codegen_instance<'a, 'tcx, Bx: BuilderMethods<'a, 'tcx>>(
	cx: &'a Bx::CodegenCx,
	instance: Instance<'tcx>
	) {
	/* ... */
	}</code></pre>
	<p>In this signature, we have the two lifetime parameters explained earlier and
	the master type <code>Bx</code> which satisfies the trait <code>BuilderMethods</code> corresponding
	to the interface satisfied by the <code>Builder</code> struct. The <code>BuilderMethods</code>
	defines an associated type <code>Bx::CodegenCx</code> that itself satisfies the
	<code>CodegenMethods</code> traits implemented by the struct <code>CodegenCx</code>.</p>
	<p>On the trait side, here is an example with part of the definition of
	<code>BuilderMethods</code> in <code>traits/builder.rs</code>:</p>
	<pre><code class="language-rust ignore">pub trait BuilderMethods<'a, 'tcx>:
	HasCodegen<'tcx>
	+ DebugInfoBuilderMethods<'tcx>
	+ ArgTypeMethods<'tcx>
	+ AbiBuilderMethods<'tcx>
	+ IntrinsicCallMethods<'tcx>
	+ AsmBuilderMethods<'tcx>
	{
	fn new_block<'b>(
	cx: &'a Self::CodegenCx,
	llfn: Self::Function,
	name: &'b str
	) -> Self;
	/* ... */
	fn cond_br(
	&mut self,
	cond: Self::Value,
	then_llbb: Self::BasicBlock,
	else_llbb: Self::BasicBlock,
	);
	/* ... */
	}</code></pre>
	<p>Finally, a master structure implementing the <code>ExtraBackendMethods</code> trait is
	used for high-level codegen-driving functions like <code>codegen_crate</code> in
	<code>base.rs</code>. For LLVM, it is the empty <code>LlvmCodegenBackend</code>.
	<code>ExtraBackendMethods</code> should be implemented by the same structure that
	implements the <code>CodegenBackend</code> defined in
	<code>rustc_codegen_utils/codegen_backend.rs</code>.</p>
	<p>During the traitification process, certain functions have been converted from
	methods of a local structure to methods of <code>CodegenCx</code> or <code>Builder</code> and a
	corresponding <code>self</code> parameter has been added. Indeed, LLVM stores information
	internally that it can access when called through its API. This information
	does not show up in a Rust data structure carried around when these methods are
	called. However, when implementing a Rust backend for <code>rustc</code>, these methods
	will need information from <code>CodegenCx</code>, hence the additional parameter (unused
	in the LLVM implementation of the trait).</p>
	<h3 id="state-of-the-code-after-the-refactoring"><a class="header" href="#state-of-the-code-after-the-refactoring">State of the code after the refactoring</a></h3>
	<p>The traits offer an API which is very similar to the API of LLVM. This is not
	the best solution since LLVM has a very special way of doing things: when
	adding another backend, the traits definition might be changed in order to
	offer more flexibility.</p>
	<p>However, the current separation between backend-agnostic and LLVM-specific code
	has allowed the reuse of a significant part of the old <code>rustc_codegen_llvm</code>.
	Here is the new LOC breakdown between backend-agnostic (BA) and LLVM for the
	most important elements:</p>
	<ul>
	<li><code>back</code> folder: 3,800 (BA) vs 4,100 (LLVM);</li>
	<li><code>mir</code> folder: 4,400 (BA) vs 0 (LLVM);</li>
	<li><code>base.rs</code>: 1,100 (BA) vs 250 (LLVM);</li>
	<li><code>builder.rs</code>: 1,400 (BA) vs 0 (LLVM);</li>
	<li><code>common.rs</code>: 350 (BA) vs 350 (LLVM);</li>
	</ul>
	<p>The <code>debuginfo</code> folder has been left almost untouched by the splitting and is
	specific to LLVM. Only its high-level features have been traitified.</p>
	<p>The new <code>traits</code> folder has 1500 LOC only for trait definitions. Overall, the
	27,000 LOC-sized old <code>rustc_codegen_llvm</code> code has been split into the new
	18,500 LOC-sized new <code>rustc_codegen_llvm</code> and the 12,000 LOC-sized
	<code>rustc_codegen_ssa</code>. We can say that this refactoring allowed the reuse of
	approximately 10,000 LOC that would otherwise have had to be duplicated between
	the multiple backends of <code>rustc</code>.</p>
	<p>The refactored version of <code>rustc</code>'s backend introduced no regression over the
	test suite nor in performance benchmark, which is in coherence with the nature
	of the refactoring that used only compile-time parametricity (no trait
	objects).</p>

	</main>

	<nav class="nav-wrapper" aria-label="Page navigation">
	<!-- Mobile navigation buttons -->
	<a rel="prev" href="../backend/debugging.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
	<i class="fa fa-angle-left"></i>
	</a>

	<a rel="next prefetch" href="../backend/implicit-caller-location.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
	<i class="fa fa-angle-right"></i>
	</a>

	<div style="clear: both"></div>
	</nav>
	</div>
	</div>

	<nav class="nav-wide-wrapper" aria-label="Page navigation">
	<a rel="prev" href="../backend/debugging.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
	<i class="fa fa-angle-left"></i>
	</a>

	<a rel="next prefetch" href="../backend/implicit-caller-location.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
	<i class="fa fa-angle-right"></i>
	</a>
	</nav>

	</div>




	<script>
	window.playground_copyable = true;
	</script>


	<script src="../elasticlunr.min.js"></script>
	<script src="../mark.min.js"></script>
	<script src="../searcher.js"></script>

	<script src="../clipboard.min.js"></script>
	<script src="../highlight.js"></script>
	<script src="../book.js"></script>

	<!-- Custom JS scripts -->
	<script src="../mermaid.min.js"></script>
	<script src="../mermaid-init.js"></script>
	<script src="../pagetoc.js"></script>



	</div>
	</body>
	</html>