The role of debug information is to provide meta information normally +stripped away during the compilation process. This meta information provides an +llvm user a relationship between generated code and the original program source +code.
+ +Currently, debug information is consumed by the DwarfWriter to produce dwarf +information used by the gdb debugger. Other targets could use the same +information to produce stabs or other debug forms.
+ +It would also be reasonable to use debug information to feed profiling tools +for analysis of generated code, or, tools for reconstructing the original source +from generated code.
+ +TODO - expound a bit more.
+ +Consumers of LLVM debug information expect 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 allowed to define its own objects, by using -unreserved tag numbers.
+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 allowed to define its own objects, by using unreserved tag +numbers. We recommend using with tags in the range 0x1000 thru 0x2000 (there is +a defined enum DW_TAG_user_base = 0x1000.)The fields of debug descriptors used internally by LLVM (MachineDebugInfo) are restricted to only the simple data types int, uint, @@ -328,7 +354,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 = 2 + uint, ;; LLVM debug version number = 3 uint, ;; Dwarf language identifier (ex. DW_LANG_C89) sbyte*, ;; Source file name sbyte*, ;; Source file directory (includes trailing slash) @@ -337,7 +363,7 @@ deleted.These descriptors contain the version number for the debug info (currently -2), a source language ID for the file (we use the Dwarf 3.0 ID numbers, such as +3), 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.
@@ -363,7 +389,7 @@ line correspondence. { }*, ;; Reference to context descriptor sbyte*, ;; Name { }*, ;; Reference to compile unit where defined - int, ;; Line number where defined + uint, ;; 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) @@ -390,20 +416,16 @@ provide details such as name, type and where the variable is defined. { }*, ;; Reference to context descriptor sbyte*, ;; Name { }*, ;; Reference to compile unit where defined - int, ;; Line number where defined + uint, ;; 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 array of member descriptors + bool ;; True if the global is defined in the compile unit (not extern) }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.
+subprograms. They provide details such as name, return types and the source +location where the subprogram is defined.%llvm.dbg.block = type { uint, ;; Tag = 13 (DW_TAG_lexical_block) - { }* ;; Reference to array of member descriptors + { }* ;; Reference to context descriptor }@@ -439,7 +461,7 @@ and deeper nested blocks. { }*, ;; Reference to context (typically a compile unit) sbyte*, ;; Name (may be "" for anonymous types) { }*, ;; Reference to compile unit where defined (may be NULL) - int, ;; Line number where defined (may be 0) + uint, ;; Line number where defined (may be 0) uint, ;; Size in bits uint, ;; Alignment in bits uint, ;; Offset in bits @@ -485,7 +507,7 @@ one of the following; { }*, ;; Reference to context sbyte*, ;; Name (may be "" for anonymous types) { }*, ;; Reference to compile unit where defined (may be NULL) - int, ;; Line number where defined (may be 0) + uint, ;; Line number where defined (may be 0) uint, ;; Size in bits uint, ;; Alignment in bits uint, ;; Offset in bits @@ -549,7 +571,7 @@ NULL derived type. { }*, ;; Reference to context sbyte*, ;; Name (may be "" for anonymous types) { }*, ;; Reference to compile unit where defined (may be NULL) - int, ;; Line number where defined (may be 0) + uint, ;; Line number where defined (may be 0) uint, ;; Size in bits uint, ;; Alignment in bits uint, ;; Offset in bits @@ -637,6 +659,44 @@ value. + +
+ %llvm.dbg.variable.type = type { + uint, ;; Tag (see below) + { }*, ;; Context + sbyte*, ;; Name + { }*, ;; Reference to compile unit where defined + uint, ;; Line number where defined + { }* ;; Type descriptor + } ++ +
These descriptors are used to define variables local to a sub program. The +value of the tag depends on the usage of the variable;
+ ++ DW_TAG_auto_variable = 256 + DW_TAG_arg_variable = 257 + DW_TAG_return_variable = 258 ++ +
An auto variable is any variable declared in the body of the function. An +argument variable is any variable that appears as a formal argument to the +function. A return variable is used to track the result of a function and has +no source correspondent.
+ +The context is eitehr the subprogram or block where the variable is defined. +Name the source variable name. Compile unit and line indicate where the +variable was defined. Type descriptor defines the declared type of the +variable.
+ +- void %llvm.dbg.func.start( %llvm.dbg.subprogram.type* ) + void %llvm.dbg.func.start( { }* )
This intrinsic is used to link the debug information in %llvm.dbg.subprogram to the function. It also defines the beginning of the function's declarative region (scope.) The intrinsic should be called early in the function after the all the alloca -instructions.
+instructions. It should be paired off with a closing %llvm.dbg.region.end. The function's +single argument is the %llvm.dbg.subprogram.type.- void %llvm.dbg.region.start() + void %llvm.dbg.region.start( { }* )
This intrinsic is used to define the beginning of a declarative scope (ex. block) for local language elements. It should be paired off with a closing -%llvm.dbg.region.end.
+%llvm.dbg.region.end. The +function's single argument is the %llvm.dbg.block which is starting. +- void %llvm.dbg.region.end() + void %llvm.dbg.region.end( { }* )
This intrinsic is used to define the end of a declarative scope (ex. block) for local language elements. It should be paired off with an opening %llvm.dbg.region.start or %llvm.dbg.func.start.
+href="#format_common_func_start">llvm.dbg.func.start. The function's +single argument is either the %llvm.dbg.block or the %llvm.dbg.subprogram.type which is +ending.- void %llvm.dbg.declare( {} *, ... ) + void %llvm.dbg.declare( { } *, { }* )
This intrinsic provides information about a local element (ex. variable.) -TODO - details.
+The first argument as a AllocA for the variable cast to a { }*. The second +argument is the %llvm.dbg.variable +containing the description of the variable, also cast to a { }*.