-
-The llvm-db is designed to be a debugger providing an interface as similar to GDB as reasonable, but no more so than that.
-Because the Debugger and info classes implement all of the heavy lifting and
-analysis, llvm-db (which lives in llvm/tools/llvm-db) consists
-mainly of of code to interact with the user and parse commands. The CLIDebugger
-constructor registers all of the builtin commands for the debugger, and each
-command is implemented as a CLIDebugger::[name]Command method.
-
+
+ void %llvm.dbg.declare(metadata, metadata)
+
+
+
This intrinsic provides information about a local element (ex. variable.) The
+ first argument is metadata holding alloca for the variable.. The
+ second argument is
+ the %llvm.dbg.variable containing
+ the description of the variable.
+
+
+
In many languages, the local variables in functions can have their lifetimes
+ or scopes limited to a subset of a function. In the C family of languages,
+ for example, variables are only live (readable and writable) within the
+ source block that they are defined in. In functional languages, values are
+ only readable after they have been defined. Though this is a very obvious
+ concept, it is non-trivial to model in LLVM, because it has no notion of
+ scoping in this sense, and does not want to be tied to a language's scoping
+ rules.
+
+
In order to handle this, the LLVM debug format uses the metadata attached to
+ llvm instructions to encode line number and scoping information. Consider
+ the following C fragment, for example:
+
+
+
+1. void foo() {
+2. int X = 21;
+3. int Y = 22;
+4. {
+5. int Z = 23;
+6. Z = X;
+7. }
+8. X = Y;
+9. }
+
+
-
-FIXME: this section will eventually go away. These are notes to myself of
-things that should be implemented, but haven't yet.
-
-
-
-Breakpoints: Support is already implemented in the 'InferiorProcess'
-class, though it hasn't been tested yet. To finish breakpoint support, we need
-to implement breakCommand (which should reuse the linespec parser from the list
-command), and handle the fact that 'break foo' or 'break file.c:53' may insert
-multiple breakpoints. Also, if you say 'break file.c:53' and there is no
-stoppoint on line 53, the breakpoint should go on the next available line. My
-idea was to have the Debugger class provide a "Breakpoint" class which
-encapsulated this messiness, giving the debugger front-end a simple interface.
-The debugger front-end would have to map the really complex semantics of
-temporary breakpoints and 'conditional' breakpoints onto this intermediate
-level. Also, breakpoints should survive as much as possible across program
-reloads.
-
-
-
-UnixLocalInferiorProcess.cpp speedup: There is no reason for the debugged
-process to code gen the globals corresponding to debug information. The
-IntrinsicLowering object could instead change descriptors into constant expr
-casts of the constant address of the LLVM objects for the descriptors. This
-would also allow us to eliminate the mapping back and forth between physical
-addresses that must be done.
-
-
-Process deaths: The InferiorProcessDead exception should be extended to
-know "how" a process died, i.e., it was killed by a signal. This is easy to
-collect in the UnixLocalInferiorProcess, we just need to represent it.
+
Compiled to LLVM, this function would be represented like this:
+
+
+
+define void @foo() nounwind ssp {
+entry:
+ %X = alloca i32, align 4 ; <i32*> [#uses=4]
+ %Y = alloca i32, align 4 ; <i32*> [#uses=4]
+ %Z = alloca i32, align 4 ; <i32*> [#uses=3]
+ %0 = bitcast i32* %X to {}* ; <{}*> [#uses=1]
+ call void @llvm.dbg.declare({}* %0, metadata !0), !dbg !7
+ store i32 21, i32* %X, !dbg !8
+ %1 = bitcast i32* %Y to {}* ; <{}*> [#uses=1]
+ call void @llvm.dbg.declare({}* %1, metadata !9), !dbg !10
+ store i32 22, i32* %Y, !dbg !11
+ %2 = bitcast i32* %Z to {}* ; <{}*> [#uses=1]
+ call void @llvm.dbg.declare({}* %2, metadata !12), !dbg !14
+ store i32 23, i32* %Z, !dbg !15
+ %tmp = load i32* %X, !dbg !16 ; <i32> [#uses=1]
+ %tmp1 = load i32* %Y, !dbg !16 ; <i32> [#uses=1]
+ %add = add nsw i32 %tmp, %tmp1, !dbg !16 ; <i32> [#uses=1]
+ store i32 %add, i32* %Z, !dbg !16
+ %tmp2 = load i32* %Y, !dbg !17 ; <i32> [#uses=1]
+ store i32 %tmp2, i32* %X, !dbg !17
+ ret void, !dbg !18
+}
+
+declare void @llvm.dbg.declare({}*, metadata) nounwind readnone
+
+!0 = metadata !{i32 459008, metadata !1, metadata !"X",
+ metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
+!1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
+!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
+ metadata !"foo", metadata !3, i32 1, metadata !4,
+ i1 false, i1 true}; [DW_TAG_subprogram ]
+!3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
+ metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
+ i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
+!4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
+ i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
+!5 = metadata !{null}
+!6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
+ i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
+!7 = metadata !{i32 2, i32 7, metadata !1, null}
+!8 = metadata !{i32 2, i32 3, metadata !1, null}
+!9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
+ metadata !6}; [ DW_TAG_auto_variable ]
+!10 = metadata !{i32 3, i32 7, metadata !1, null}
+!11 = metadata !{i32 3, i32 3, metadata !1, null}
+!12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
+ metadata !6}; [ DW_TAG_auto_variable ]
+!13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
+!14 = metadata !{i32 5, i32 9, metadata !13, null}
+!15 = metadata !{i32 5, i32 5, metadata !13, null}
+!16 = metadata !{i32 6, i32 5, metadata !13, null}
+!17 = metadata !{i32 8, i32 3, metadata !1, null}
+!18 = metadata !{i32 9, i32 1, metadata !2, null}
+
+
+
+
This example illustrates a few important details about LLVM debugging
+ information. In particular, it shows how the llvm.dbg.declare
+ intrinsic and location information, which are attached to an instruction,
+ are applied together to allow a debugger to analyze the relationship between
+ statements, variable definitions, and the code used to implement the
+ function.
+
+
+
+call void @llvm.dbg.declare({}* %0, metadata !0), !dbg !7
+
+
+
+
The first intrinsic
+ %llvm.dbg.declare
+ encodes debugging information for the variable X. The metadata
+ !dbg !7 attached to the intrinsic provides scope information for the
+ variable X.
+
+
+
+!7 = metadata !{i32 2, i32 7, metadata !1, null}
+!1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
+!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
+ metadata !"foo", metadata !"foo", metadata !3, i32 1,
+ metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
+
+
+
+
Here !7 is metadata providing location information. It has four
+ fields: line number, column number, scope, and original scope. The original
+ scope represents inline location if this instruction is inlined inside a
+ caller, and is null otherwise. In this example, scope is encoded by
+ !1. !1 represents a lexical block inside the scope
+ !2, where !2 is a
+ subprogram descriptor. This way the
+ location information attached to the intrinsics indicates that the
+ variable X is declared at line number 2 at a function level scope in
+ function foo.
+
+
Now lets take another example.
+
+
+
+call void @llvm.dbg.declare({}* %2, metadata !12), !dbg !14
+
+
+
+
The second intrinsic
+ %llvm.dbg.declare
+ encodes debugging information for variable Z. The metadata
+ !dbg !14 attached to the intrinsic provides scope information for
+ the variable Z.
+
+
+
+!13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
+!14 = metadata !{i32 5, i32 9, metadata !13, null}
+
+
+
+
Here !14 indicates that Z is declared at line number 5 and
+ column number 9 inside of lexical scope !13. The lexical scope
+ itself resides inside of lexical scope !1 described above.
+
+
The scope information attached with each instruction provides a
+ straightforward way to find instructions covered by a scope.
-
LLVM debugging information has been carefully designed to make it possible
-for the optimizer to optimize the program and debugging information without
-necessarily having to know anything about debugging information. In particular,
-the global constant merging pass automatically eliminates duplicated debugging
-information (often caused by header files), the global dead code elimination
-pass automatically deletes debugging information for a function if it decides to
-delete the function, and the linker eliminates debug information when it merges
-linkonce functions.
-
-
To do this, most of the debugging information (descriptors for types,
-variables, functions, source files, etc) is inserted by the language front-end
-in the form of LLVM global variables. These LLVM global variables are no
-different from any other global variables, except that they have a web of LLVM
-intrinsic functions that point to them. If the last references to a particular
-piece of debugging information are deleted (for example, by the
--globaldce pass), the extraneous debug information will automatically
-become dead and be removed by the optimizer.
-
-
The debugger is designed to be agnostic about the contents of most of the
-debugging information. It uses a source-language-specific
-module to decode the information that represents variables, types,
-functions, namespaces, etc: this allows for arbitrary source-language semantics
-and type-systems to be used, as long as there is a module written for the
-debugger to interpret the information.
-
-
-
-To provide basic functionality, the LLVM debugger does have to make some
-assumptions about the source-level language being debugged, though it keeps
-these to a minimum. The only common features that the LLVM debugger assumes
-exist are source files, and program objects. These abstract objects are
-used by the debugger to form stack traces, show information about local
-variables, etc.
-
-
This section of the documentation first describes the representation aspects
-common to any source-language. The next section
-describes the data layout conventions used by the C and C++ front-ends.
+
The C and C++ front-ends represent information about the program in a format
+ that is effectively identical
+ to DWARF 3.0 in
+ terms of information content. This allows code generators to trivially
+ support native debuggers by generating standard dwarf information, and
+ contains enough information for non-dwarf targets to translate it as
+ needed.
+
+
This section describes the forms used to represent C and C++ programs. Other
+ languages could pattern themselves after this (which itself is tuned to
+ representing programs in the same way that DWARF 3 does), or they could
+ choose to provide completely different forms if they don't fit into the DWARF
+ model. As support for debugging information gets added to the various LLVM
+ source-language front-ends, the information used should be documented
+ here.
+
+
The following sections provide examples of various C/C++ constructs and the
+ debug information that would best describe those constructs.
-
-One important aspect of the LLVM debug representation is that it allows the LLVM
-debugger to efficiently index all of the global objects without having the scan
-the program. To do this, all of the global objects use "anchor" globals of type
-"{}", with designated names. These anchor objects obviously do not
-contain any content or meaning by themselves, but all of the global objects of a
-particular type (e.g., source file descriptors) contain a pointer to the anchor.
-This pointer allows the debugger to use def-use chains to find all global
-objects of that type.
-
-
-
-So far, the following names are recognized as anchors by the LLVM debugger:
-
-
-
- %llvm.dbg.translation_units = linkonce global {} {}
- %llvm.dbg.globals = linkonce global {} {}
-
-
-
-Using anchors in this way (where the source file descriptor points to the
-anchors, as opposed to having a list of source file descriptors) allows for the
-standard dead global elimination and merging passes to automatically remove
-unused debugging information. If the globals were kept track of through lists,
-there would always be an object pointing to the descriptors, thus would never be
-deleted.
-
+
Given the source files MySource.cpp and MyHeader.h located
+ in the directory /Users/mine/sources, the following code:
+
+
+
+#include "MyHeader.h"
+
+int main(int argc, char *argv[]) {
+ return 0;
+}
+
+
+
+
a C/C++ front-end would generate the following descriptors:
+
+
+
+...
+;;
+;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
+;;
+!2 = metadata !{
+ i32 524305, ;; Tag
+ i32 0, ;; Unused
+ i32 4, ;; Language Id
+ metadata !"MySource.cpp",
+ metadata !"/Users/mine/sources",
+ metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
+ i1 true, ;; Main Compile Unit
+ i1 false, ;; Optimized compile unit
+ metadata !"", ;; Compiler flags
+ i32 0} ;; Runtime version
+
+;;
+;; Define the file for the file "/Users/mine/sources/MySource.cpp".
+;;
+!1 = metadata !{
+ i32 524329, ;; Tag
+ metadata !"MySource.cpp",
+ metadata !"/Users/mine/sources",
+ metadata !2 ;; Compile unit
+}
+
+;;
+;; Define the file for the file "/Users/mine/sources/Myheader.h"
+;;
+!3 = metadata !{
+ i32 524329, ;; Tag
+ metadata !"Myheader.h"
+ metadata !"/Users/mine/sources",
+ metadata !2 ;; Compile unit
+}
+
+...
+
+
llvm::Instruction provides easy access to metadata attached with an
+instruction. One can extract line number information encoded in LLVM IR
+using Instruction::getMetadata() and
+DILocation::getLineNumber().
+
+ if (MDNode *N = I->getMetadata("dbg")) { // Here I is an LLVM instruction
+ DILocation Loc(N); // DILocation is in DebugInfo.h
+ unsigned Line = Loc.getLineNumber();
+ StringRef File = Loc.getFilename();
+ StringRef Dir = Loc.getDirectory();
+ }
+
+
-
LLVM debugger "stop points" are a key part of the debugging representation
-that allows the LLVM to maintain simple semantics for debugging optimized code. The basic idea is that the
-front-end inserts calls to the %llvm.dbg.stoppoint intrinsic function
-at every point in the program where the debugger should be able to inspect the
-program (these correspond to places the debugger stops when you "step"
-through it). The front-end can choose to place these as fine-grained as it
-would like (for example, before every subexpression evaluated), but it is
-recommended to only put them after every source statement that includes
-executable code.
-
-
-Using calls to this intrinsic function to demark legal points for the debugger
-to inspect the program automatically disables any optimizations that could
-potentially confuse debugging information. To non-debug-information-aware
-transformations, these calls simply look like calls to an external function,
-which they must assume to do anything (including reading or writing to any part
-of reachable memory). On the other hand, it does not impact many optimizations,
-such as code motion of non-trapping instructions, nor does it impact
-optimization of subexpressions, code duplication transformations, or basic-block
-reordering transformations.
-
-
-An important aspect of the calls to the %llvm.dbg.stoppoint intrinsic
-is that the function-local debugging information is woven together with use-def
-chains. This makes it easy for the debugger to, for example, locate the 'next'
-stop point. For a concrete example of stop points, see the example in the next section.
+
Given an integer global variable declared as follows:
+
+
+
+int MyGlobal = 100;
+
+
+
+
a C/C++ front-end would generate the following descriptors:
+
+
+
+;;
+;; Define the global itself.
+;;
+%MyGlobal = global int 100
+...
+;;
+;; List of debug info of globals
+;;
+!llvm.dbg.gv = !{!0}
+
+;;
+;; Define the global variable descriptor. Note the reference to the global
+;; variable anchor and the global variable itself.
+;;
+!0 = metadata !{
+ i32 524340, ;; Tag
+ i32 0, ;; Unused
+ metadata !1, ;; Context
+ metadata !"MyGlobal", ;; Name
+ metadata !"MyGlobal", ;; Display Name
+ metadata !"MyGlobal", ;; Linkage Name
+ metadata !3, ;; Compile Unit
+ i32 1, ;; Line Number
+ metadata !4, ;; Type
+ i1 false, ;; Is a local variable
+ i1 true, ;; Is this a definition
+ i32* @MyGlobal ;; The global variable
+}
+;;
+;; Define the basic type of 32 bit signed integer. Note that since int is an
+;; intrinsic type the source file is NULL and line 0.
+;;
+!4 = metadata !{
+ i32 524324, ;; Tag
+ metadata !1, ;; Context
+ metadata !"int", ;; Name
+ metadata !1, ;; File
+ i32 0, ;; Line number
+ i64 32, ;; Size in Bits
+ i64 32, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 5 ;; Encoding
+}
+
+
+
-
-In many languages, the local variables in functions can have their lifetime or
-scope limited to a subset of a function. In the C family of languages, for
-example, variables are only live (readable and writable) within the source block
-that they are defined in. In functional languages, values are only readable
-after they have been defined. Though this is a very obvious concept, it is also
-non-trivial to model in LLVM, because it has no notion of scoping in this sense,
-and does not want to be tied to a language's scoping rules.
-
-
-
-In order to handle this, the LLVM debug format uses the notion of "regions" of a
-function, delineated by calls to intrinsic functions. These intrinsic functions
-define new regions of the program and indicate when the region lifetime expires.
-Consider the following C fragment, for example:
-
-
-
-1. void foo() {
-2. int X = ...;
-3. int Y = ...;
-4. {
-5. int Z = ...;
-6. ...
-7. }
-8. ...
-9. }
-
-
-
-Compiled to LLVM, this function would be represented like this (FIXME: CHECK AND
-UPDATE THIS):
-
-
-
-void %foo() {
- %X = alloca int
- %Y = alloca int
- %Z = alloca int
- %D1 = call {}* %llvm.dbg.func.start(%lldb.global* %d.foo)
- %D2 = call {}* %llvm.dbg.stoppoint({}* %D1, uint 2, uint 2, %lldb.compile_unit* %file)
-
- %D3 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D2, ...)
- ;; Evaluate expression on line 2, assigning to X.
- %D4 = call {}* %llvm.dbg.stoppoint({}* %D3, uint 3, uint 2, %lldb.compile_unit* %file)
-
- %D5 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D4, ...)
- ;; Evaluate expression on line 3, assigning to Y.
- %D6 = call {}* %llvm.dbg.stoppoint({}* %D5, uint 5, uint 4, %lldb.compile_unit* %file)
-
- %D7 = call {}* %llvm.region.start({}* %D6)
- %D8 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D7, ...)
- ;; Evaluate expression on line 5, assigning to Z.
- %D9 = call {}* %llvm.dbg.stoppoint({}* %D8, uint 6, uint 4, %lldb.compile_unit* %file)
-
- ;; Code for line 6.
- %D10 = call {}* %llvm.region.end({}* %D9)
- %D11 = call {}* %llvm.dbg.stoppoint({}* %D10, uint 8, uint 2, %lldb.compile_unit* %file)
-
- ;; Code for line 8.
- %D12 = call {}* %llvm.region.end({}* %D11)
- ret void
+
+Given a function declared as follows:
+
+
+
+int main(int argc, char *argv[]) {
+ return 0;
}
-
-
-
-This example illustrates a few important details about the LLVM debugging
-information. In particular, it shows how the various intrinsics used are woven
-together with def-use and use-def chains, similar to how anchors are used with globals. This allows the
-debugger to analyze the relationship between statements, variable definitions,
-and the code used to implement the function.
-
-
-In this example, two explicit regions are defined, one with the definition of the %D1 variable and one with the
-definition of %D7. In the case of
-%D1, the debug information indicates that the function whose descriptor is specified as an argument to the
-intrinsic. This defines a new stack frame whose lifetime ends when the region
-is ended by the %D12 call.
-
-
-Using regions to represent the boundaries of source-level functions allow LLVM
-interprocedural optimizations to arbitrarily modify LLVM functions without
-having to worry about breaking mapping information between the LLVM code and the
-and source-level program. In particular, the inliner requires no modification
-to support inlining with debugging information: there is no explicit correlation
-drawn between LLVM functions and their source-level counterparts (note however,
-that if the inliner inlines all instances of a non-strong-linkage function into
-its caller that it will not be possible for the user to manually invoke the
-inlined function from the debugger).
-
-
-Once the function has been defined, the stopping point corresponding to line #2 of the
-function is encountered. At this point in the function, no local
-variables are live. As lines 2 and 3 of the example are executed, their
-variable definitions are automatically introduced into the program, without the
-need to specify a new region. These variables do not require new regions to be
-introduced because they go out of scope at the same point in the program: line
-9.
-
-
-
-In contrast, the Z variable goes out of scope at a different time, on
-line 7. For this reason, it is defined within the
-%D7 region, which kills the availability of Z before the
-code for line 8 is executed. In this way, regions can support arbitrary
-source-language scoping rules, as long as they can only be nested (ie, one scope
-cannot partially overlap with a part of another scope).
-
-
-
-It is worth noting that this scoping mechanism is used to control scoping of all
-declarations, not just variable declarations. For example, the scope of a C++
-using declaration is controlled with this, and the llvm-db C++ support
-routines could use this to change how name lookup is performed (though this is
-not implemented yet).
-
+
+
a C/C++ front-end would generate the following descriptors:
+
+
+
+;;
+;; Define the anchor for subprograms. Note that the second field of the
+;; anchor is 46, which is the same as the tag for subprograms
+;; (46 = DW_TAG_subprogram.)
+;;
+!6 = metadata !{
+ i32 524334, ;; Tag
+ i32 0, ;; Unused
+ metadata !1, ;; Context
+ metadata !"main", ;; Name
+ metadata !"main", ;; Display name
+ metadata !"main", ;; Linkage name
+ metadata !1, ;; File
+ i32 1, ;; Line number
+ metadata !4, ;; Type
+ i1 false, ;; Is local
+ i1 true ;; Is definition
+}
+;;
+;; Define the subprogram itself.
+;;
+define i32 @main(i32 %argc, i8** %argv) {
+...
+}
+
-
-The LLVM debugger expects the descriptors for program objects to start in a
-canonical format, but the descriptors can include additional information
-appended at the end that is source-language specific. All LLVM debugging
-information is versioned, allowing backwards compatibility in the case that the
-core structures need to change in some way. Also, all debugging information
-objects start with a tag to indicate what type
-of object it is. The source-language is allows to define its own objects, by
-using unreserved tag numbers.
-
The lowest-level descriptor are those describing the files containing the program source
-code, as most other descriptors (sometimes indirectly) refer to them.
-
-
-
- 
+