diff options
Diffstat (limited to 'docs/SourceLevelDebugging.html')
| -rw-r--r-- | docs/SourceLevelDebugging.html | 1112 |
1 files changed, 613 insertions, 499 deletions
diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index 1b3aaf7e69..190d729f5d 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -2,6 +2,7 @@ "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <title>Source Level Debugging with LLVM</title> <link rel="stylesheet" href="llvm.css" type="text/css"> </head> @@ -77,10 +78,11 @@ height="369"> <div class="doc_text"> <p>This document is the central repository for all information pertaining to -debug information in LLVM. It describes the <a href="#format">actual format -that the LLVM debug information</a> takes, which is useful for those interested -in creating front-ends or dealing directly with the information. Further, this -document provides specifc examples of what debug information for C/C++.</p> + debug information in LLVM. It describes the <a href="#format">actual format + that the LLVM debug information</a> takes, which is useful for those + interested in creating front-ends or dealing directly with the information. + Further, this document provides specifc examples of what debug information + for C/C++.</p> </div> @@ -92,45 +94,45 @@ document provides specifc examples of what debug information for C/C++.</p> <div class="doc_text"> <p>The idea of the LLVM debugging information is to capture how the important -pieces of the source-language's Abstract Syntax Tree map onto LLVM code. -Several design aspects have shaped the solution that appears here. The -important ones are:</p> + pieces of the source-language's Abstract Syntax Tree map onto LLVM code. + Several design aspects have shaped the solution that appears here. The + important ones are:</p> <ul> -<li>Debugging information should have very little impact on the rest of the -compiler. No transformations, analyses, or code generators should need to be -modified because of debugging information.</li> + <li>Debugging information should have very little impact on the rest of the + compiler. No transformations, analyses, or code generators should need to + be modified because of debugging information.</li> -<li>LLVM optimizations should interact in <a href="#debugopt">well-defined and -easily described ways</a> with the debugging information.</li> + <li>LLVM optimizations should interact in <a href="#debugopt">well-defined and + easily described ways</a> with the debugging information.</li> -<li>Because LLVM is designed to support arbitrary programming languages, -LLVM-to-LLVM tools should not need to know anything about the semantics of the -source-level-language.</li> + <li>Because LLVM is designed to support arbitrary programming languages, + LLVM-to-LLVM tools should not need to know anything about the semantics of + the source-level-language.</li> -<li>Source-level languages are often <b>widely</b> different from one another. -LLVM should not put any restrictions of the flavor of the source-language, and -the debugging information should work with any language.</li> - -<li>With code generator support, it should be possible to use an LLVM compiler -to compile a program to native machine code and standard debugging formats. -This allows compatibility with traditional machine-code level debuggers, like -GDB or DBX.</li> + <li>Source-level languages are often <b>widely</b> different from one another. + LLVM should not put any restrictions of the flavor of the source-language, + and the debugging information should work with any language.</li> + <li>With code generator support, it should be possible to use an LLVM compiler + to compile a program to native machine code and standard debugging + formats. This allows compatibility with traditional machine-code level + debuggers, like GDB or DBX.</li> </ul> -<p>The approach used by the LLVM implementation is to use a small set of <a -href="#format_common_intrinsics">intrinsic functions</a> to define a mapping -between LLVM program objects and the source-level objects. The description of -the source-level program is maintained in LLVM global variables in an <a -href="#ccxx_frontend">implementation-defined format</a> (the C/C++ front-end -currently uses working draft 7 of the <a -href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3 standard</a>).</p> +<p>The approach used by the LLVM implementation is to use a small set + of <a href="#format_common_intrinsics">intrinsic functions</a> to define a + mapping between LLVM program objects and the source-level objects. The + description of the source-level program is maintained in LLVM global + variables in an <a href="#ccxx_frontend">implementation-defined format</a> + (the C/C++ front-end currently uses working draft 7 of + the <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3 + standard</a>).</p> <p>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, a debugger must be aware of the source-language, and is thus tied to -a specific language or family of languages.</p> + turns the stored debug information into source-language specific information. + As such, a debugger must be aware of the source-language, and is thus tied to + a specific language or family of languages.</p> </div> @@ -140,18 +142,19 @@ a specific language or family of languages.</p> </div> <div class="doc_text"> + <p>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.</p> + stripped away during the compilation process. This meta information provides + an LLVM user a relationship between generated code and the original program + source code.</p> <p>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.</p> + information used by the gdb debugger. Other targets could use the same + information to produce stabs or other debug forms.</p> <p>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.</p> + for analysis of generated code, or, tools for reconstructing the original + source from generated code.</p> <p>TODO - expound a bit more.</p> @@ -165,52 +168,53 @@ from generated code.</p> <div class="doc_text"> <p>An extremely high priority of LLVM debugging information is to make it -interact well with optimizations and analysis. In particular, the LLVM debug -information provides the following guarantees:</p> + interact well with optimizations and analysis. In particular, the LLVM debug + information provides the following guarantees:</p> <ul> - -<li>LLVM debug information <b>always provides information to accurately read the -source-level state of the program</b>, regardless of which LLVM optimizations -have been run, and without any modification to the optimizations themselves. -However, some optimizations may impact the ability to modify the current state -of the program with a debugger, such as setting program variables, or calling -functions that have been deleted.</li> - -<li>LLVM optimizations gracefully interact with debugging information. If they -are not aware of debug information, they are automatically disabled as necessary -in the cases that would invalidate the debug info. This retains the LLVM -features, making it easy to write new transformations.</li> - -<li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM -debugging information, allowing them to update the debugging information as they -perform aggressive optimizations. This means that, with effort, the LLVM -optimizers could optimize debug code just as well as non-debug code.</li> - -<li>LLVM debug information does not prevent many important optimizations from -happening (for example inlining, basic block reordering/merging/cleanup, tail -duplication, etc), further reducing the amount of the compiler that eventually -is "aware" of debugging information.</li> - -<li>LLVM debug information is automatically optimized along with the rest of the -program, using existing facilities. For example, duplicate information is -automatically merged by the linker, and unused information is automatically -removed.</li> - + <li>LLVM debug information <b>always provides information to accurately read + the source-level state of the program</b>, regardless of which LLVM + optimizations have been run, and without any modification to the + optimizations themselves. However, some optimizations may impact the + ability to modify the current state of the program with a debugger, such + as setting program variables, or calling functions that have been + deleted.</li> + + <li>LLVM optimizations gracefully interact with debugging information. If + they are not aware of debug information, they are automatically disabled + as necessary in the cases that would invalidate the debug info. This + retains the LLVM features, making it easy to write new + transformations.</li> + + <li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM + debugging information, allowing them to update the debugging information + as they perform aggressive optimizations. This means that, with effort, + the LLVM optimizers could optimize debug code just as well as non-debug + code.</li> + + <li>LLVM debug information does not prevent many important optimizations from + happening (for example inlining, basic block reordering/merging/cleanup, + tail duplication, etc), further reducing the amount of the compiler that + eventually is "aware" of debugging information.</li> + + <li>LLVM debug information is automatically optimized along with the rest of + the program, using existing facilities. For example, duplicate + information is automatically merged by the linker, and unused information + is automatically removed.</li> </ul> <p>Basically, the debug information allows you to compile a program with -"<tt>-O0 -g</tt>" and get full debug information, allowing you to arbitrarily -modify the program as it executes from a debugger. Compiling a program with -"<tt>-O3 -g</tt>" 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 -and call functions where were optimized out of the program, or inlined away -completely.</p> + "<tt>-O0 -g</tt>" and get full debug information, allowing you to arbitrarily + modify the program as it executes from a debugger. Compiling a program with + "<tt>-O3 -g</tt>" 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 and call functions where were optimized out of the program, or + inlined away completely.</p> <p><a href="TestingGuide.html#quicktestsuite">LLVM test suite</a> provides a -framework to test optimizer's handling of debugging information. It can be run -like this:</p> + framework to test optimizer's handling of debugging information. It can be + run like this:</p> <div class="doc_code"> <pre> @@ -219,12 +223,10 @@ like this:</p> </pre> </div> -<p> -This will test impact of debugging information on optimization passes. If -debugging information influences optimization passes then it will be reported -as a failure. See <a href="TestingGuide.html">TestingGuide</a> -for more information on LLVM test infrastructure and how to run various tests. -</p> +<p>This will test impact of debugging information on optimization passes. If + debugging information influences optimization passes then it will be reported + as a failure. See <a href="TestingGuide.html">TestingGuide</a> for more + information on LLVM test infrastructure and how to run various tests.</p> </div> @@ -237,44 +239,45 @@ for more information on LLVM test infrastructure and how to run various tests. <div class="doc_text"> <p>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 -<tt>linkonce</tt> functions.</p> + 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 <tt>linkonce</tt> functions.</p> <p>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 -<tt>-globaldce</tt> pass), the extraneous debug information will automatically -become dead and be removed by the optimizer.</p> + 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 + <tt>-globaldce</tt> pass), the extraneous debug information will + automatically become dead and be removed by the optimizer.</p> <p>Debug information is designed to be agnostic about the target debugger and -debugging information representation (e.g. DWARF/Stabs/etc). It uses a generic -machine debug information pass 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 target debugger to interpret the information. In -addition, debug global variables are declared in the <tt>"llvm.metadata"</tt> -section. All values declared in this section are stripped away after target -debug information is constructed and before the program object is emitted.</p> + debugging information representation (e.g. DWARF/Stabs/etc). It uses a + generic machine debug information pass 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 target debugger to interpret the + information. In addition, debug global variables are declared in + the <tt>"llvm.metadata"</tt> section. All values declared in this section + are stripped away after target debug information is constructed and before + the program object is emitted.</p> <p>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 <a href="#format_compile_units">source files</a>, and <a -href="#format_global_variables">program objects</a>. These abstract objects are -used by a debugger to form stack traces, show information about local -variables, etc.</p> + 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 <a href="#format_compile_units">source files</a>, + and <a href="#format_global_variables">program objects</a>. These abstract + objects are used by a debugger to form stack traces, show information about + local variables, etc.</p> <p>This section of the documentation first describes the representation aspects -common to any source-language. The <a href="#ccxx_frontend">next section</a> -describes the data layout conventions used by the C and C++ front-ends.</p> + common to any source-language. The <a href="#ccxx_frontend">next section</a> + describes the data layout conventions used by the C and C++ front-ends.</p> </div> @@ -284,42 +287,48 @@ describes the data layout conventions used by the C and C++ front-ends.</p> </div> <div class="doc_text"> + <p>In consideration of the complexity and volume of debug information, LLVM -provides a specification for well formed debug global variables. The constant -value of each of these globals is one of a limited set of structures, known as -debug descriptors.</p> + provides a specification for well formed debug global variables. The + constant value of each of these globals is one of a limited set of + structures, known as debug descriptors.</p> <p>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. We recommend using with tags in the range 0x1000 thru 0x2000 (there is -a defined enum DW_TAG_user_base = 0x1000.)</p> + 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. We recommend using with tags in + the range 0x1000 thru 0x2000 (there is a defined enum DW_TAG_user_base = + 0x1000.)</p> <p>The fields of debug descriptors used internally by LLVM (MachineModuleInfo) -are restricted to only the simple data types <tt>int</tt>, <tt>uint</tt>, -<tt>bool</tt>, <tt>float</tt>, <tt>double</tt>, <tt>i8*</tt> and <tt> { }* -</tt>. References to arbitrary values are handled using a <tt> { }* </tt> and a -cast to <tt> { }* </tt> expression; typically references to other field -descriptors, arrays of descriptors or global variables.</p> + are restricted to only the simple data types <tt>int</tt>, <tt>uint</tt>, + <tt>bool</tt>, <tt>float</tt>, <tt>double</tt>, <tt>i8*</tt> and + <tt>{ }*</tt>. References to arbitrary values are handled using a + <tt>{ }*</tt> and a cast to <tt>{ }*</tt> expression; typically + references to other field descriptors, arrays of descriptors or global + variables.</p> +<div class="doc_code"> <pre> - %llvm.dbg.object.type = type { - uint, ;; A tag - ... - } +%llvm.dbg.object.type = type { + uint, ;; A tag + ... +} </pre> +</div> <p><a name="LLVMDebugVersion">The first field of a descriptor is always an -<tt>uint</tt> containing a tag value identifying the content of the descriptor. -The remaining fields are specific to the descriptor. The values of tags are -loosely bound to the tag values of Dwarf information entries. However, that -does not restrict the use of the information supplied to Dwarf targets. To -facilitate versioning of debug information, the tag is augmented with the -current debug version (LLVMDebugVersion = 4 << 16 or 0x40000 or 262144.)</a></p> + <tt>uint</tt> containing a tag value identifying the content of the + descriptor. The remaining fields are specific to the descriptor. The values + of tags are loosely bound to the tag values of DWARF information entries. + However, that does not restrict the use of the information supplied to DWARF + targets. To facilitate versioning of debug information, the tag is augmented + with the current debug version (LLVMDebugVersion = 4 << 16 or 0x40000 or + 262144.)</a></p> <p>The details of the various descriptors follow.</p> @@ -332,34 +341,48 @@ current debug version (LLVMDebugVersion = 4 << 16 or 0x40000 or 262144.)</a></p> <div class="doc_text"> +<div class="doc_code"> <pre> - %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { - uint, ;; Tag = 0 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> - uint ;; Tag of descriptors grouped by the anchor - } +%<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { + i32, ;; Tag = 0 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> + i32 ;; Tag of descriptors grouped by the anchor +} </pre> +</div> <p>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" -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 -a debugger to use def-use chains to find all global objects of that type.</p> + 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 a debugger to use def-use chains to find all global objects of that + type.</p> <p>The following names are recognized as anchors by LLVM:</p> +<div class="doc_code"> <pre> - %<a href="#format_compile_units">llvm.dbg.compile_units</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { uint 0, uint 17 } ;; DW_TAG_compile_unit - %<a href="#format_global_variables">llvm.dbg.global_variables</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { uint 0, uint 52 } ;; DW_TAG_variable - %<a href="#format_subprograms">llvm.dbg.subprograms</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { uint 0, uint 46 } ;; DW_TAG_subprogram +%<a href="#format_compile_units">llvm.dbg.compile_units</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { + i32 0, + i32 17 +} ;; DW_TAG_compile_unit +%<a href="#format_global_variables">llvm.dbg.global_variables</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { + i32 0, + i32 52 +} ;; DW_TAG_variable +%<a href="#format_subprograms">llvm.dbg.subprograms</a> = linkonce constant %<a href="#format_anchors">llvm.dbg.anchor.type</a> { + i32 0, + i32 46 +} ;; DW_TAG_subprogram </pre> +</div> <p>Using anchors in this way (where the compile unit descriptor points to the -anchors, as opposed to having a list of compile unit 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.</p> + anchors, as opposed to having a list of compile unit 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.</p> </div> @@ -370,37 +393,43 @@ deleted.</p> <div class="doc_text"> +<div class="doc_code"> <pre> - %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type { - uint, ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_compile_unit) - { }*, ;; Compile unit anchor = cast = (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*) - uint, ;; Dwarf language identifier (ex. DW_LANG_C89) - i8*, ;; Source file name - i8*, ;; Source file directory (includes trailing slash) - i8* ;; Producer (ex. "4.0.1 LLVM (LLVM research group)") - bool ;; True if this is a main compile unit. - } +%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type { + i32, ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_compile_unit) + { }*, ;; Compile unit anchor = cast = (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*) + i32, ;; DWARF language identifier (ex. DW_LANG_C89) + i8*, ;; Source file name + i8*, ;; Source file directory (includes trailing slash) + i8* ;; Producer (ex. "4.0.1 LLVM (LLVM research group)") + i1, ;; True if this is a main compile unit. + i1, ;; True if this is optimized. + i8*, ;; Flags + i32 ;; Runtime version +} </pre> +</div> + +<p>These descriptors contain a source language ID for the file (we use the DWARF + 3.0 ID numbers, such as <tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>, + <tt>DW_LANG_Cobol74</tt>, etc), three strings describing the filename, + working directory of the compiler, and an identifier string for the compiler + that produced it.</p> -<p>These descriptors contain a source language ID for the file (we use the Dwarf -3.0 ID numbers, such as <tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>, -<tt>DW_LANG_Cobol74</tt>, etc), three strings describing the filename, working -directory of the compiler, and an identifier string for the compiler that -produced it.</p> +<p>Compile unit descriptors provide the root context for objects declared in a + specific source file. Global variables and top level functions would be + defined using this context. Compile unit descriptors also provide context + for source line correspondence.</p> -<p> Compile unit descriptors provide the root context for objects declared in a -specific source file. Global variables and top level functions would be defined -using this context. Compile unit descriptors also provide context for source -line correspondence.</p> +<p>Each input file is encoded as a separate compile unit in LLVM debugging + information output. However, many target specific tool chains prefer to + encode only one compile unit in an object file. In this situation, the LLVM + code generator will include debugging information entities in the compile + unit that is marked as main compile unit. The code generator accepts maximum + one main compile unit per module. If a module does not contain any main + compile unit then the code generator will emit multiple compile units in the + output object file.</p> -<p> Each input file is encoded as a separate compile unit in LLVM debugging -information output. However, many target specific tool chains prefer to encode -only one compile unit in an object file. In this situation, the LLVM code -generator will include debugging information entities in the compile unit -that is marked as main compile unit. The code generator accepts maximum one main -compile unit per module. If a module does not contain any main compile unit -then the code generator will emit multiple compile units in the output object -file. </div> <!-- ======================================================================= --> @@ -410,22 +439,24 @@ file. <div class="doc_text"> +<div class="doc_code"> <pre> - %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type { - uint, ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_variable) - { }*, ;; Global variable anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to { }*), - { }*, ;; Reference to context descriptor - i8*, ;; Name - i8*, ;; Display name (fully qualified C++ name) - i8*, ;; MIPS linkage name (for C++) - { }*, ;; Reference to compile unit 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 the global variable - } +%<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type { + i32, ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_variable) + { }*, ;; Global variable anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to { }*), + { }*, ;; Reference to context descriptor + i8*, ;; Name + i8*, ;; Display name (fully qualified C++ name) + i8*, ;; MIPS linkage name (for C++) + { }*, ;; Reference to compile unit where defined + i32, ;; Line number where defined + { }*, ;; Reference to type descriptor + i1, ;; True if the global is local to compile unit (static) + i1, ;; True if the global is defined in the compile unit (not extern) + { }* ;; Reference to the global variable +} </pre> +</div> <p>These descriptors provide debug information about globals variables. The provide details such as name, type and where the variable is defined.</p> @@ -439,27 +470,30 @@ provide details such as name, type and where the variable is defined.</p> <div class="doc_text"> +<div class="doc_code"> <pre> - %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { - uint, ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subprogram) - { }*, ;; Subprogram anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to { }*), - { }*, ;; Reference to context descriptor - i8*, ;; Name - i8*, ;; Display name (fully qualified C++ name) - i8*, ;; MIPS linkage name (for C++) - { }*, ;; Reference to compile unit 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) - } +%<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { + i32, ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subprogram) + { }*, ;; Subprogram anchor = cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to { }*), + { }*, ;; Reference to context descriptor + i8*, ;; Name + i8*, ;; Display name (fully qualified C++ name) + i8*, ;; MIPS linkage name (for C++) + { }*, ;; Reference to compile unit where defined + i32, ;; Line number where defined + { }*, ;; Reference to type descriptor + i1, ;; True if the global is local to compile unit (static) + i1 ;; True if the global is defined in the compile unit (not extern) +} </pre> +</div> <p>These descriptors provide debug information about functions, methods and -subprograms. They provide details such as name, return types and the source -location where the subprogram is defined.</p> + subprograms. They provide details such as name, return types and the source + location where the subprogram is defined.</p> </div> + <!-- ======================================================================= --> <div class="doc_subsubsection"> <a name="format_blocks">Block descriptors</a> @@ -467,16 +501,18 @@ location where the subprogram is defined.</p> <div class="doc_text"> +<div class="doc_code"> <pre> - %<a href="#format_blocks">llvm.dbg.block</a> = type { - i32, ;; Tag = 13 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block) - { }* ;; Reference to context descriptor - } +%<a href="#format_blocks">llvm.dbg.block</a> = type { + i32, ;; Tag = 13 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block) + { }* ;; Reference to context descriptor +} </pre> +</div> <p>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.</p> + subprogram. The array of member descriptors is used to define local + variables and deeper nested blocks.</p> </div> @@ -487,42 +523,47 @@ and deeper nested blocks.</p> <div class="doc_text"> +<div class="doc_code"> <pre> - %<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type { - uint, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_base_type) - { }*, ;; Reference to context (typically a compile unit) - i8*, ;; Name (may be "" for anonymous types) - { }*, ;; Reference to compile unit where defined (may be NULL) - uint, ;; Line number where defined (may be 0) - i64, ;; Size in bits - i64, ;; Alignment in bits - uint, ;; Offset in bits - uint ;; Dwarf type encoding - } +%<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type { + i32, ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_base_type) + { }*, ;; Reference to context (typically a compile unit) + i8*, ;; Name (may be "" for anonymous types) + { }*, ;; Reference to compile unit where defined (may be NULL) + i32, ;; Line number where defined (may be 0) + i64, ;; Size in bits + i64, ;; Alignment in bits + i64, ;; Offset in bits + i32, ;; Flags + i32 ;; DWARF type encoding +} </pre> +</div> <p>These descriptors define primitive types used in the code. Example int, bool -and float. The context provides the scope of the type, which is usually the top -level. Since basic types are not usually user defined the compile unit and line -number can be left as NULL and 0. The size, alignment and offset are expressed -in bits and can be 64 bit values. The alignment is used to round the offset -when embedded in a <a href="#format_composite_type">composite type</a> -(example to keep float doubles on 64 bit boundaries.) The offset is the bit -offset if embedded in a <a href="#format_composite_type">composite -type</a>.</p> + and float. The context provides the scope of the type, which is usually the + top level. Since basic types are not usually user defined the compile unit + and line number can be left as NULL and 0. The size, alignment and offset + are expressed in bits and can be 64 bit values. The alignment is used to + round the offset when embedded in a + <a href="#format_composite_type">composite type</a> (example to keep float + doubles on 64 bit boundaries.) The offset is the bit offset if embedded in + a <a href="#format_composite_type">composite type</a>.</p> <p>The type encoding provides the details of the type. The values are typically -one of the following:</p> + one of the following:</p> +<div class="doc_code"> <pre> - DW_ATE_address = 1 - DW_ATE_boolean = 2 - DW_ATE_float = 4 - DW_ATE_signed = 5 - DW_ATE_signed_char = 6 - DW_ATE_unsigned = 7 - DW_ATE_unsigned_char = 8 +DW_ATE_address = 1 +DW_ATE_boolean = 2 +DW_ATE_float = 4 +DW_ATE_signed = 5 +DW_ATE_signed_char = 6 +DW_ATE_unsigned = 7 +DW_ATE_unsigned_char = 8 </pre> +</div> </div> @@ -533,60 +574,64 @@ one of the following:</p> <div class="doc_text"> +<div class="doc_code"> <pre> - %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> = type { - uint, ;; Tag (see below) - { }*, ;; Reference to context - i8*, ;; Name (may be "" for anonymous types) - { }*, ;; Reference to compile unit where defined (may be NULL) - uint, ;; Line number where defined (may be 0) - uint, ;; Size in bits - uint, ;; Alignment in bits - uint, ;; Offset in bits - { }* ;; Reference to type derived from - } +%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> = type { + i32, ;; Tag (see below) + { }*, ;; Reference to context + i8*, ;; Name (may be "" for anonymous types) + { }*, ;; Reference to compile unit where defined (may be NULL) + i32, ;; Line number where defined (may be 0) + i32, ;; Size in bits + i32, ;; Alignment in bits + i32, ;; Offset in bits + { }* ;; Reference to type derived from +} </pre> +</div> <p>These descriptors are used to define types derived from other types. The value of the tag varies depending on the meaning. The following are possible tag values:</p> +<div class="doc_code"> <pre> - DW_TAG_formal_parameter = 5 - DW_TAG_member = 13 - DW_TAG_pointer_type = 15 - DW_TAG_reference_type = 16 - DW_TAG_typedef = 22 - DW_TAG_const_type = 38 - DW_TAG_volatile_type = 53 - DW_TAG_restrict_type = 55 +DW_TAG_formal_parameter = 5 +DW_TAG_member = 13 +DW_TAG_pointer_type = 15 +DW_TAG_reference_type = 16 +DW_TAG_typedef = 22 +DW_TAG_const_type = 38 +DW_TAG_volatile_type = 53 +DW_TAG_restrict_type = 55 </pre> +</div> -<p> <tt>DW_TAG_member</tt> is used to define a member of a <a -href="#format_composite_typ |