From: Jim Laskey Date: Wed, 15 Mar 2006 19:10:52 +0000 (+0000) Subject: Update doc to reflect changes in subprogram and block descriptors. X-Git-Url: http://plrg.eecs.uci.edu/git/?a=commitdiff_plain;h=3d11beeaddc26700dbcdf5bac464e4a2dacf6e60;p=oota-llvm.git Update doc to reflect changes in subprogram and block descriptors. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@26783 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index 3cbd64e8529..db2c65339c9 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -26,6 +26,7 @@
  • Compile unit descriptors
  • Global variable descriptors
  • Subprogram descriptors
    • +
  • Block descriptors
  • Basic type descriptors
  • Derived type descriptors
  • Composite type descriptors
    • @@ -126,7 +127,7 @@ href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3 standard).

    When a program is being debugged, a debugger interacts with the user and turns the stored debug information into source-language specific information. -As such, the debugger must be aware of the source-language, and is thus tied to +As such, a debugger must be aware of the source-language, and is thus tied to a specific language of family of languages.

    @@ -175,7 +176,7 @@ removed.

    Basically, the debug information allows you to compile a program with "-O0 -g" and get full debug information, allowing you to arbitrarily -modify the program as it executes from the debugger. Compiling a program with +modify the program as it executes from a debugger. Compiling a program with "-O3 -g" gives you full debug information that is always available and accurate for reading (e.g., you get accurate stack traces despite tail call elimination and inlining), but you might lose the ability to modify the program @@ -225,7 +226,7 @@ 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 +used by a debugger to form stack traces, show information about local variables, etc.

    This section of the documentation first describes the representation aspects @@ -297,7 +298,7 @@ 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" descriptors with designated names. All of the global objects of a particular type (e.g., compile units) contain a pointer to the anchor. This pointer allows -the debugger to use def-use chains to find all global objects of that type.

    +a debugger to use def-use chains to find all global objects of that type.

    The following names are recognized as anchors by LLVM:

    @@ -327,7 +328,7 @@ deleted.

    %llvm.dbg.compile_unit.type = type { uint, ;; Tag = 17 (DW_TAG_compile_unit) { }*, ;; Compile unit anchor = cast = (%llvm.dbg.anchor.type* %llvm.dbg.compile_units to { }*) - uint, ;; LLVM debug version number = 1 + uint, ;; LLVM debug version number = 2 uint, ;; Dwarf language identifier (ex. DW_LANG_C89) sbyte*, ;; Source file name sbyte*, ;; Source file directory (includes trailing slash) @@ -336,7 +337,7 @@ deleted.

    These descriptors contain the version number for the debug info (currently -1), a source language ID for the file (we use the Dwarf 3.0 ID numbers, such as +2), a source language ID for the file (we use the Dwarf 3.0 ID numbers, such as DW_LANG_C89, DW_LANG_C_plus_plus, DW_LANG_Cobol74, etc), three strings describing the filename, working directory of the compiler, and an identifier string for the compiler that produced it.

    @@ -359,13 +360,14 @@ line correspondence.

    %llvm.dbg.global_variable.type = type { uint, ;; Tag = 52 (DW_TAG_variable) { }*, ;; Global variable anchor = cast (%llvm.dbg.anchor.type* %llvm.dbg.global_variables to { }*), - { }*, ;; Reference to compile unit + { }*, ;; Reference to context descriptor sbyte*, ;; Name + { }*, ;; Reference to compile unit where defined + int, ;; Line number where defined { }*, ;; Reference to type descriptor bool, ;; True if the global is local to compile unit (static) bool, ;; True if the global is defined in the compile unit (not extern) - { }*, ;; Reference to the global variable - uint ;; Line number in compile unit where variable is defined + { }* ;; Reference to the global variable } @@ -385,20 +387,43 @@ provide details such as name, type and where the variable is defined.

    %llvm.dbg.subprogram.type = type { uint, ;; Tag = 46 (DW_TAG_subprogram) { }*, ;; Subprogram anchor = cast (%llvm.dbg.anchor.type* %llvm.dbg.subprograms to { }*), - { }*, ;; Reference to compile unit + { }*, ;; Reference to context descriptor sbyte*, ;; Name + { }*, ;; Reference to compile unit where defined + int, ;; Line number where defined { }*, ;; Reference to type descriptor bool, ;; True if the global is local to compile unit (static) - bool ;; True if the global is defined in the compile unit (not extern) - TODO - MORE TO COME + bool, ;; True if the global is defined in the compile unit (not extern) + { }* ;; Reference to array of member descriptors } -

    These descriptors provide debug information about functions, methods and subprograms. The provide details such as name, return and argument types and where the subprogram is defined.

    +

    The array of member descriptors is used to define arguments local variables +and nested blocks.

    + + + +
    + Block descriptors +
    + +
    + +
    +  %llvm.dbg.block = type {
+    uint,   ;; Tag = 13 (DW_TAG_lexical_block)
+    {  }*   ;; Reference to array of member descriptors
+  }
+
    + +

    These descriptors provide debug information about nested blocks within a +subprogram. The array of member descriptors is used to define local variables +and deeper nested blocks.

    +
    @@ -473,6 +498,7 @@ value of the tag varies depending on the meaning. The following are possible tag values;

    +  DW_TAG_formal_parameter = 5
   DW_TAG_member = 13
   DW_TAG_pointer_type = 15
   DW_TAG_reference_type = 16
@@ -483,8 +509,10 @@ tag values;

    DW_TAG_member is used to define a member of a composite type. The type of the member is the -derived type.

    +href="#format_composite_type">composite type or subprogram. The type of the member is the derived type. DW_TAG_formal_parameter +is used to define a member which is a formal argument of a subprogram.

    DW_TAG_typedef is used to provide a name for the derived type.

    @@ -720,8 +748,8 @@ 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 +function at every point in the program where a debugger should be able to +inspect the program (these correspond to places a 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 @@ -841,7 +869,7 @@ 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).

    +inlined function from a debugger).

    Once the function has been defined, the stopping point corresponding to @@ -990,7 +1018,7 @@ int MyGlobal = 100; ;; compile unit. ;; %llvm.dbg.anchor.type = type { uint, uint } -%llvm.dbg.global_variable.type = type { uint, { }*, { }*, sbyte*, { }*, bool, bool, { }*, uint } +%llvm.dbg.global_variable.type = type { uint, { }*, { }*, sbyte*, { }*, uint, { }*, bool, bool, { }*, uint } %llvm.dbg.basictype.type = type { uint, { }*, sbyte*, { }*, int, uint, uint, uint, uint } %llvm.dbg.compile_unit.type = ... ... @@ -1015,11 +1043,12 @@ int MyGlobal = 100; { }* cast (%llvm.dbg.anchor.type* %llvm.dbg.global_variables to { }*), { }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to { }*), sbyte* getelementptr ([9 x sbyte]* %str1, int 0, int 0), + { }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to { }*), + uint 1, { }* cast (%llvm.dbg.basictype.type* %llvm.dbg.basictype to { }*), bool false, bool true, - { }* cast (int* %MyGlobal to { }*), - uint 1 }, section "llvm.metadata" + { }* cast (int* %MyGlobal to { }*) }, section "llvm.metadata" ;; ;; Define the basic type of 32 bit signed integer. Note that since int is an @@ -1068,7 +1097,7 @@ int main(int argc, char *argv[]) { ;; descriptor, one for the global's basic type and one for the subprogram's ;; compile unit. ;; -%llvm.dbg.subprogram.type = type { uint, { }*, { }*, sbyte*, { }*, bool, bool } +%llvm.dbg.subprogram.type = type { uint, { }*, { }*, sbyte*, { }*, bool, bool, { }* } %llvm.dbg.anchor.type = type { uint, uint } %llvm.dbg.compile_unit.type = ... @@ -1087,9 +1116,12 @@ int main(int argc, char *argv[]) { { }* cast (%llvm.dbg.anchor.type* %llvm.dbg.subprograms to { }*), { }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to { }*), sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0), + { }* cast (%llvm.dbg.compile_unit.type* %llvm.dbg.compile_unit to { }*), + uint 1, { }* null, bool false, - bool true }, section "llvm.metadata" + bool true, + null }, section "llvm.metadata" ;; ;; Define the name of the subprogram.