---

yaml
---
r: 88654
b: refs/heads/snap-stage3
c: d35fff8
h: refs/heads/master
v: v3

Author: michaelwoerister

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: deeca5d586bfaa4aa60246f671a8d611d38f6248
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 89b47d5557b52e0da7b95e70ed61f76db152664b
+refs/heads/snap-stage3: d35fff89944f583f4f96b384e3f5d075503e0d36
 refs/heads/try: b160761e35efcd1207112b3b782c06633cf441a8
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/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.
+
 */