<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>compiler/rustc_codegen_llvm/src/debuginfo/doc.md - fork/rust @ master</title>
<meta name="description" content="compiler/rustc_codegen_llvm/src/debuginfo/doc.md in fork/rust at master.">
<meta property="og:title" content="compiler/rustc_codegen_llvm/src/debuginfo/doc.md - fork/rust @ master">
<meta property="og:description" content="compiler/rustc_codegen_llvm/src/debuginfo/doc.md in fork/rust at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="3bcad65fbf67b6edf87c949531fbc13435882e6b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/rust</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rust</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">Auto merge of #103046 - JanBeh:PR_clarify_cmp_terminology, r=workingjubilee</span><span class="snapshot-sha sha" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">3bcad65fbf6</span><time datetime="2023-10-05T15:24:54+00:00" title="2023-10-05 15:24:54 +0000">2023-10-05</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/rust/ref/master/">master</a><strong>tags</strong><a href="/fork/rust/ref/1.39.0/">1.39.0</a><a href="/fork/rust/ref/1.40.0/">1.40.0</a><a href="/fork/rust/ref/1.41.0/">1.41.0</a><a href="/fork/rust/ref/1.41.1/">1.41.1</a><a href="/fork/rust/ref/1.42.0/">1.42.0</a><a href="/fork/rust/ref/1.43.0/">1.43.0</a><a href="/fork/rust/ref/1.43.1/">1.43.1</a><a href="/fork/rust/ref/1.44.0/">1.44.0</a><a class="all" href="/fork/rust/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rust/">rust</a> / <a href="/fork/rust/ref/master/tree/compiler/">compiler</a> / <a href="/fork/rust/ref/master/tree/compiler/rustc_codegen_llvm/">rustc_codegen_llvm</a> / <a href="/fork/rust/ref/master/tree/compiler/rustc_codegen_llvm/src/">src</a> / <a href="/fork/rust/ref/master/tree/compiler/rustc_codegen_llvm/src/debuginfo/">debuginfo</a> / <span class="cur">doc.md</span></nav>
<span class="view-stats"><span>6.0 KiB</span><span>131 lines</span></span><span class="actions"><a class="raw" href="/fork/rust/raw/aaec4e68c1743f193212acdf4cfe665c59a67ecc/compiler/rustc_codegen_llvm/src/debuginfo/doc.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Debug Info Module</h1>
<p>This module serves the purpose of generating debug symbols. We use LLVM's
<a href="https://llvm.org/docs/SourceLevelDebugging.html">source level debugging</a>
features for generating the debug information. The general principle is
this:</p>
<p>Given the right metadata in the LLVM IR, the LLVM code generator is able to
create DWARF debug symbols for the given code. The
<a href="https://llvm.org/docs/LangRef.html#metadata-type">metadata</a> is structured
much like DWARF <em>debugging information entries</em> (DIE), representing type
information such as datatype layout, function signatures, block layout,
variable location and scope information, etc. It is the purpose of this
module to generate correct metadata and insert it into the LLVM IR.</p>
<p>As the exact format of metadata trees may change between different LLVM
versions, we now use LLVM
<a href="https://llvm.org/docs/doxygen/html/classllvm_1_1DIBuilder.html">DIBuilder</a>
to create metadata where possible. This will hopefully ease the adaption of
this module to future LLVM versions.</p>
<p>The public API of the module is a set of functions that will insert the
correct metadata into the LLVM IR when called with the right parameters.
The module is thus driven from an outside client with functions like
<code>debuginfo::create_local_var_metadata(bx: block, local: &amp;ast::local)</code>.</p>
<p>Internally the module will try to reuse already created metadata by
utilizing a cache. The way to get a shared metadata node when needed is
thus to just call the corresponding function in this module:</p>
<pre>let file_metadata = file_metadata(cx, file);
</pre>
<p>The function will take care of probing the cache for an existing node for
that exact file path.</p>
<p>All private state used by the module is stored within either the
CodegenUnitDebugContext struct (owned by the CodegenCx) or the
FunctionDebugContext (owned by the FunctionCx).</p>
<p>This file consists of three conceptual sections:</p>
<ol>
<li>The public interface of the module</li>
<li>Module-internal metadata creation functions</li>
<li>Minor utility functions</li>
</ol>
<h2>Recursive Types</h2>
<p>Some kinds of types, such as structs and enums can be recursive. That means
that the type definition of some type X refers to some other type which in
turn (transitively) refers to X. This introduces cycles into the type
referral graph. A naive algorithm doing an on-demand, depth-first traversal
of this graph when describing types, can get trapped in an endless loop
when it reaches such a cycle.</p>
<p>For example, the following simple type for a singly-linked list...</p>
<pre>struct List {
    value: i32,
    tail: Option&lt;Box&lt;List&gt;&gt;,
}
</pre>
<p>will generate the following callstack with a naive DFS algorithm:</p>
<pre>describe(t = List)
  describe(t = i32)
  describe(t = Option&lt;Box&lt;List&gt;&gt;)
    describe(t = Box&lt;List&gt;)
      describe(t = List) // at the beginning again...
      ...
</pre>
<p>To break cycles like these, we use "stubs". That is, when
the algorithm encounters a possibly recursive type (any struct or enum), it
immediately creates a type description node and inserts it into the cache
<em>before</em> describing the members of the type. This type description is just
a stub (as type members are not described and added to it yet) but it
allows the algorithm to already refer to the type. After the stub is
inserted into the cache, the algorithm continues as before. If it now
encounters a recursive reference, it will hit the cache and does not try to
describe the type anew. This behavior is encapsulated in the
<code>type_map::build_type_with_children()</code> function.</p>
<h2>Source Locations and Line Information</h2>
<p>In addition to data type descriptions the debugging information must also
allow to map machine code locations back to source code locations in order
to be useful. This functionality is also handled in this module. The
following functions allow to control source mappings:</p>
<ul>
<li><code>set_source_location()</code></li>
<li><code>clear_source_location()</code></li>
<li><code>start_emitting_source_locations()</code></li>
</ul>
<p><code>set_source_location()</code> allows to set the current source location. All IR
instructions created after a call to this function will be linked to the
given source location, until another location is specified with
<code>set_source_location()</code> or the source location is cleared with
<code>clear_source_location()</code>. In the later case, subsequent IR instruction
will not be linked to any source location. As you can see, this is a
stateful API (mimicking the one in LLVM), so be careful with source
locations set by previous calls. It's probably best to not rely on any
specific state being present at a given point in code.</p>
<p>One topic that deserves some extra attention is <em>function prologues</em>. At
the beginning of a function's machine code there are typically a few
instructions for loading argument values into allocas and checking if
there's enough stack space for the function to execute. This <em>prologue</em> is
not visible in the source code and LLVM puts a special PROLOGUE END marker
into the line table at the first non-prologue instruction of the function.
In order to find out where the prologue ends, LLVM looks for the first
instruction in the function body that is linked to a source location. So,
when generating prologue instructions we have to make sure that we don't
emit source location information until the 'real' function body begins. For
this reason, source location emission is disabled by default for any new
function being codegened and is only activated after a call to the third
function from the list above, <code>start_emitting_source_locations()</code>. This
function should be called right before regularly starting to codegen the
top-level block of the given function.</p>
<p>There is one exception to the above rule: <code>llvm.dbg.declare</code> instruction
must be linked to the source location of the variable being declared. For
function parameters these <code>llvm.dbg.declare</code> instructions typically occur
in the middle of the prologue, however, they are ignored by LLVM's prologue
detection. The <code>create_argument_metadata()</code> and related functions take care
of linking the <code>llvm.dbg.declare</code> instructions to the correct source
locations even while source location emission is still disabled, so there
is no need to do anything special with source location handling here.</p>
</section><div class="code-panel"><pre class="code src" data-hl="compiler/rustc_codegen_llvm/src/debuginfo/doc.md"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"># Debug Info Module</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">This module serves the purpose of generating debug symbols. We use LLVM's</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">[source level debugging](https://llvm.org/docs/SourceLevelDebugging.html)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">features for generating the debug information. The general principle is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">this:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">Given the right metadata in the LLVM IR, the LLVM code generator is able to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">create DWARF debug symbols for the given code. The</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">[metadata](https://llvm.org/docs/LangRef.html#metadata-type) is structured</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">much like DWARF *debugging information entries* (DIE), representing type</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">information such as datatype layout, function signatures, block layout,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">variable location and scope information, etc. It is the purpose of this</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">module to generate correct metadata and insert it into the LLVM IR.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text">As the exact format of metadata trees may change between different LLVM</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">versions, we now use LLVM</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">[DIBuilder](https://llvm.org/docs/doxygen/html/classllvm_1_1DIBuilder.html)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">to create metadata where possible. This will hopefully ease the adaption of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">this module to future LLVM versions.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">The public API of the module is a set of functions that will insert the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">correct metadata into the LLVM IR when called with the right parameters.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">The module is thus driven from an outside client with functions like</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">`debuginfo::create_local_var_metadata(bx: block, local: &amp;ast::local)`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">Internally the module will try to reuse already created metadata by</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">utilizing a cache. The way to get a shared metadata node when needed is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">thus to just call the corresponding function in this module:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">```ignore (illustrative)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">let file_metadata = file_metadata(cx, file);</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">The function will take care of probing the cache for an existing node for</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">that exact file path.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">All private state used by the module is stored within either the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text">CodegenUnitDebugContext struct (owned by the CodegenCx) or the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">FunctionDebugContext (owned by the FunctionCx).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">This file consists of three conceptual sections:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">1. The public interface of the module</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">2. Module-internal metadata creation functions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text">3. Minor utility functions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">## Recursive Types</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">Some kinds of types, such as structs and enums can be recursive. That means</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text">that the type definition of some type X refers to some other type which in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text">turn (transitively) refers to X. This introduces cycles into the type</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">referral graph. A naive algorithm doing an on-demand, depth-first traversal</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text">of this graph when describing types, can get trapped in an endless loop</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">when it reaches such a cycle.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">For example, the following simple type for a singly-linked list...</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text">struct List {</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text">    value: i32,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text">    tail: Option&lt;Box&lt;List&gt;&gt;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text">}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">will generate the following callstack with a naive DFS algorithm:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">```ignore (illustrative)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text">describe(t = List)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text">  describe(t = i32)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text">  describe(t = Option&lt;Box&lt;List&gt;&gt;)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">    describe(t = Box&lt;List&gt;)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text">      describe(t = List) // at the beginning again...</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text">      ...</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text">To break cycles like these, we use &quot;stubs&quot;. That is, when</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text">the algorithm encounters a possibly recursive type (any struct or enum), it</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text">immediately creates a type description node and inserts it into the cache</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text">*before* describing the members of the type. This type description is just</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text">a stub (as type members are not described and added to it yet) but it</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text">allows the algorithm to already refer to the type. After the stub is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text">inserted into the cache, the algorithm continues as before. If it now</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text">encounters a recursive reference, it will hit the cache and does not try to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text">describe the type anew. This behavior is encapsulated in the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text">`type_map::build_type_with_children()` function.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text">## Source Locations and Line Information</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text">In addition to data type descriptions the debugging information must also</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text">allow to map machine code locations back to source code locations in order</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text">to be useful. This functionality is also handled in this module. The</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text">following functions allow to control source mappings:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text">+ `set_source_location()`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text">+ `clear_source_location()`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text">+ `start_emitting_source_locations()`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text">`set_source_location()` allows to set the current source location. All IR</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text">instructions created after a call to this function will be linked to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text">given source location, until another location is specified with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text">`set_source_location()` or the source location is cleared with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text">`clear_source_location()`. In the later case, subsequent IR instruction</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text">will not be linked to any source location. As you can see, this is a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text">stateful API (mimicking the one in LLVM), so be careful with source</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text">locations set by previous calls. It's probably best to not rely on any</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text">specific state being present at a given point in code.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text">One topic that deserves some extra attention is *function prologues*. At</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text">the beginning of a function's machine code there are typically a few</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text">instructions for loading argument values into allocas and checking if</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text">there's enough stack space for the function to execute. This *prologue* is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text">not visible in the source code and LLVM puts a special PROLOGUE END marker</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text">into the line table at the first non-prologue instruction of the function.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text">In order to find out where the prologue ends, LLVM looks for the first</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text">instruction in the function body that is linked to a source location. So,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text">when generating prologue instructions we have to make sure that we don't</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text">emit source location information until the 'real' function body begins. For</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text">this reason, source location emission is disabled by default for any new</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text">function being codegened and is only activated after a call to the third</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text">function from the list above, `start_emitting_source_locations()`. This</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text">function should be called right before regularly starting to codegen the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text">top-level block of the given function.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text">There is one exception to the above rule: `llvm.dbg.declare` instruction</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text">must be linked to the source location of the variable being declared. For</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text">function parameters these `llvm.dbg.declare` instructions typically occur</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text">in the middle of the prologue, however, they are ignored by LLVM's prologue</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text">detection. The `create_argument_metadata()` and related functions take care</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text">of linking the `llvm.dbg.declare` instructions to the correct source</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text">locations even while source location emission is still disabled, so there</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text">is no need to do anything special with source location handling here.</span></span></pre></div></div>
</main>
</body>
</html>
