llvm.org GIT mirror llvm / 383e009
Updated information related to local variables and scopes. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@26982 91177308-0d34-0410-b5e6-96231b3b80d8 Jim Laskey 13 years ago
1 changed file(s) with 105 addition(s) and 33 deletion(s). Raw diff Collapse all Expand all
1515
  • Introduction
  • 1616
    1717
  • Philosophy behind LLVM debugging information
  • 18
  • Debug information consumers
  • 1819
  • Debugging optimized code
  • 1920
    2021
  • Debugging information format
  • 3132
  • Composite type descriptors
  • 3233
  • Subrange descriptors
  • 3334
  • Enumerator descriptors
  • 35
  • Local variables
  • 3436
    3537
  • Debugger intrinsic functions
  • 3638
    133135
    134136
    135137
    138 Debug information consumers
    139
    140
    141
    142

    The role of debug information is to provide meta information normally

    143 stripped away during the compilation process. This meta information provides an
    144 llvm user a relationship between generated code and the original program source
    145 code.

    146
    147

    Currently, debug information is consumed by the DwarfWriter to produce dwarf

    148 information used by the gdb debugger. Other targets could use the same
    149 information to produce stabs or other debug forms.

    150
    151

    It would also be reasonable to use debug information to feed profiling tools

    152 for analysis of generated code, or, tools for reconstructing the original source
    153 from generated code.

    154
    155

    TODO - expound a bit more.

    156
    157
    158
    159
    160
    136161 Debugging optimized code
    137162
    138163
    247272
    248273

    Consumers of LLVM debug information expect the descriptors for program

    249274 objects to start in a canonical format, but the descriptors can include
    250 additional information appended at the end that is source-language specific.
    251 All LLVM debugging information is versioned, allowing backwards compatibility in
    252 the case that the core structures need to change in some way. Also, all
    253 debugging information objects start with a tag to indicate what type of object
    254 it is. The source-language is allowed to define its own objects, by using
    255 unreserved tag numbers.

    275 additional information appended at the end that is source-language specific. All
    276 LLVM debugging information is versioned, allowing backwards compatibility in the
    277 case that the core structures need to change in some way. Also, all debugging
    278 information objects start with a tag to indicate what type of object it is. The
    279 source-language is allowed to define its own objects, by using unreserved tag
    280 numbers. We recommend using with tags in the range 0x1000 thru 0x2000 (there is
    281 a defined enum DW_TAG_user_base = 0x1000.)

    256282
    257283

    The fields of debug descriptors used internally by LLVM (MachineDebugInfo)

    258284 are restricted to only the simple data types int, uint,
    327353 %llvm.dbg.compile_unit.type = type {
    328354 uint, ;; Tag = 17 (DW_TAG_compile_unit)
    329355 { }*, ;; Compile unit anchor = cast = (%llvm.dbg.anchor.type* %llvm.dbg.compile_units to { }*)
    330 uint, ;; LLVM debug version number = 2
    356 uint, ;; LLVM debug version number = 3
    331357 uint, ;; Dwarf language identifier (ex. DW_LANG_C89)
    332358 sbyte*, ;; Source file name
    333359 sbyte*, ;; Source file directory (includes trailing slash)
    336362
    337363
    338364

    These descriptors contain the version number for the debug info (currently

    339 2), a source language ID for the file (we use the Dwarf 3.0 ID numbers, such as
    365 3), a source language ID for the file (we use the Dwarf 3.0 ID numbers, such as
    340366 DW_LANG_C89, DW_LANG_C_plus_plus, DW_LANG_Cobol74,
    341367 etc), three strings describing the filename, working directory of the compiler,
    342368 and an identifier string for the compiler that produced it.

    362388 { }*, ;; Reference to context descriptor
    363389 sbyte*, ;; Name
    364390 { }*, ;; Reference to compile unit where defined
    365 int, ;; Line number where defined
    391 uint, ;; Line number where defined
    366392 { }*, ;; Reference to type descriptor
    367393 bool, ;; True if the global is local to compile unit (static)
    368394 bool, ;; True if the global is defined in the compile unit (not extern)
    389415 { }*, ;; Reference to context descriptor
    390416 sbyte*, ;; Name
    391417 { }*, ;; Reference to compile unit where defined
    392 int, ;; Line number where defined
    418 uint, ;; Line number where defined
    393419 { }*, ;; Reference to type descriptor
    394420 bool, ;; True if the global is local to compile unit (static)
    395 bool, ;; True if the global is defined in the compile unit (not extern)
    396 { }* ;; Reference to array of member descriptors
    421 bool ;; True if the global is defined in the compile unit (not extern)
    397422 }
    398423
    399424
    400425

    These descriptors provide debug information about functions, methods and

    401 subprograms. The provide details such as name, return and argument types and
    402 where the subprogram is defined.

    403
    404

    The array of member descriptors is used to define arguments local variables

    405 and nested blocks.

    426 subprograms. They provide details such as name, return types and the source
    427 location where the subprogram is defined.

    406428
    407429
    408430
    415437
    
                      
                    
    416438 %llvm.dbg.block = type {
    417439 uint, ;; Tag = 13 (DW_TAG_lexical_block)
    418 { }* ;; Reference to array of member descriptors
    440 { }* ;; Reference to context descriptor
    419441 }
    420442
    421443
    438460 { }*, ;; Reference to context (typically a compile unit)
    439461 sbyte*, ;; Name (may be "" for anonymous types)
    440462 { }*, ;; Reference to compile unit where defined (may be NULL)
    441 int, ;; Line number where defined (may be 0)
    463 uint, ;; Line number where defined (may be 0)
    442464 uint, ;; Size in bits
    443465 uint, ;; Alignment in bits
    444466 uint, ;; Offset in bits
    484506 { }*, ;; Reference to context
    485507 sbyte*, ;; Name (may be "" for anonymous types)
    486508 { }*, ;; Reference to compile unit where defined (may be NULL)
    487 int, ;; Line number where defined (may be 0)
    509 uint, ;; Line number where defined (may be 0)
    488510 uint, ;; Size in bits
    489511 uint, ;; Alignment in bits
    490512 uint, ;; Offset in bits
    548570 { }*, ;; Reference to context
    549571 sbyte*, ;; Name (may be "" for anonymous types)
    550572 { }*, ;; Reference to compile unit where defined (may be NULL)
    551 int, ;; Line number where defined (may be 0)
    573 uint, ;; Line number where defined (may be 0)
    552574 uint, ;; Size in bits
    553575 uint, ;; Alignment in bits
    554576 uint, ;; Offset in bits
    637659
    638660
    639661
    662
    663 Local variables
    664
    665
    666
    667
    
                      
                    
    668 %llvm.dbg.variable.type = type {
    669 uint, ;; Tag (see below)
    670 { }*, ;; Context
    671 sbyte*, ;; Name
    672 { }*, ;; Reference to compile unit where defined
    673 uint, ;; Line number where defined
    674 { }* ;; Type descriptor
    675 }
    676
    677
    678

    These descriptors are used to define variables local to a sub program. The

    679 value of the tag depends on the usage of the variable;

    680
    681
    
                      
                    
    682 DW_TAG_auto_variable = 256
    683 DW_TAG_arg_variable = 257
    684 DW_TAG_return_variable = 258
    685
    686
    687

    An auto variable is any variable declared in the body of the function. An

    688 argument variable is any variable that appears as a formal argument to the
    689 function. A return variable is used to track the result of a function and has
    690 no source correspondent.

    691
    692

    The context is eitehr the subprogram or block where the variable is defined.

    693 Name the source variable name. Compile unit and line indicate where the
    694 variable was defined. Type descriptor defines the declared type of the
    695 variable.

    696
    697
    698
    699
    640700
    641701 Debugger intrinsic functions
    642702
    663723 argument si the column number (0 if unknown) and the third argument the source
    664724 compile unit. Code following a call to this intrinsic will have been defined in
    665725 close proximity of the line, column and file. This information holds until the
    666 next call to <a href="#format_common_stoppoint">lvm.dbg.stoppoint.

    726 next call to <tt>%
    727 href="#format_common_stoppoint">lvm.dbg.stoppoint.

    667728
    668729
    669730
    674735
    675736
    676737
    
                      
                    
    677 void %llvm.dbg.func.start( %llvm.dbg.subprogram.type* )
    738 void %llvm.dbg.func.start( { }* )
    678739
    679740
    680741

    This intrinsic is used to link the debug information in %

    681742 href="#format_subprograms">llvm.dbg.subprogram to the function. It also
    682743 defines the beginning of the function's declarative region (scope.) The
    683744 intrinsic should be called early in the function after the all the alloca
    684 instructions.

    745 instructions. It should be paired off with a closing %
    746 href="#format_common_region_end">llvm.dbg.region.end. The function's
    747 single argument is the %
    748 href="#format_subprograms">llvm.dbg.subprogram.type.

    685749
    686750
    687751
    692756
    693757
    694758
    
                      
                    
    695 void %llvm.dbg.region.start()
    759 void %llvm.dbg.region.start( { }* )
    696760
    697761
    698762

    This intrinsic is used to define the beginning of a declarative scope (ex.

    699763 block) for local language elements. It should be paired off with a closing
    700 %llvm.dbg.region.end.

    764 %llvm.dbg.region.end. The
    765 function's single argument is the %
    766 href="#format_blocks">llvm.dbg.block which is starting.

    767
    701768
    702769
    703770
    708775
    709776
    710777
    
                      
                    
    711 void %llvm.dbg.region.end()
    778 void %llvm.dbg.region.end( { }* )
    712779
    713780
    714781

    This intrinsic is used to define the end of a declarative scope (ex. block)

    715782 for local language elements. It should be paired off with an opening %
    716783 href="#format_common_region_start">llvm.dbg.region.start or %
    717 href="#format_common_func_start">llvm.dbg.func.start.

    784 href="#format_common_func_start">llvm.dbg.func.start. The function's
    785 single argument is either the %
    786 href="#format_blocks">llvm.dbg.block or the %
    787 href="#format_subprograms">llvm.dbg.subprogram.type which is
    788 ending.

    718789
    719790
    720791
    725796
    726797
    727798
    
                      
                    
    728 void %llvm.dbg.declare( {} *, ... )
    799 void %llvm.dbg.declare( { } *, { }* )
    729800
    730801
    731802

    This intrinsic provides information about a local element (ex. variable.)

    732 TODO - details.

    803 The first argument as a AllocA for the variable cast to a { }*. The second
    804 argument is the %llvm.dbg.variable
    805 containing the description of the variable, also cast to a { }*.

    733806
    734807
    735808
    10961169 ;; descriptor, one for the global's basic type and one for the subprogram's
    10971170 ;; compile unit.
    10981171 ;;
    1099 %llvm.dbg.subprogram.type = type { uint, { }*, { }*, sbyte*, { }*, bool, bool, { }* }
    1172 %llvm.dbg.subprogram.type = type { uint, { }*, { }*, sbyte*, { }*, bool, bool }
    11001173 %llvm.dbg.anchor.type = type { uint, uint }
    11011174 %llvm.dbg.compile_unit.type = ...
    11021175
    11191192 uint 1,
    11201193 { }* null,
    11211194 bool false,
    1122 bool true,
    1123 null }, section "llvm.metadata"
    1195 bool true }, section "llvm.metadata"
    11241196
    11251197 ;;
    11261198 ;; Define the name of the subprogram.