---

yaml
---
r: 147270
b: refs/heads/try2
c: d35fff8
h: refs/heads/master
v: v3

Author: michaelwoerister

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 89b47d5557b52e0da7b95e70ed61f76db152664b
+refs/heads/try2: d35fff89944f583f4f96b384e3f5d075503e0d36
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/src/librustc/middle/trans/debuginfo.rs

@@ -85,6 +85,43 @@ continuation, storing all state needed to continue traversal at the type members
 been registered with the cache. (This implementation approach might be a tad over-engineered and
 may change in the future)
 
+
+## Source Locations and Line Information
+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:
+
++ set_source_location()
++ clear_source_location()
++ start_emitting_source_locations()
+
+`set_source_location()` 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 `set_source_location()` or the source location is cleared with
+`clear_source_location()`. 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.
+
+One topic that deserves some extra attention is *function prologues*. 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 *prologue* 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 translated and is only activated after a call to the
+third function from the list above, `start_emitting_source_locations()`. This function should be
+called right before regularly starting to translate the top-level block of the given function.
+
+There is one exception to the above rule: `llvm.dbg.declare` instruction must be linked to the
+source location of the variable being declared. For function parameters these `llvm.dbg.declare`
+instructions typically occur in the middle of the prologue, however, they are ignored by LLVM's
+prologue detection. The `create_argument_metadata()` and related functions take care of linking the
+`llvm.dbg.declare` 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.
+
 */