Changes in directory llvm/docs:
SourceLevelDebugging.html updated: 1.15 -> 1.16 --- Log message: Updated information related to local variables and scopes. --- Diffs of the changes: (+106 -34) SourceLevelDebugging.html | 140 ++++++++++++++++++++++++++++++++++------------ 1 files changed, 106 insertions(+), 34 deletions(-) Index: llvm/docs/SourceLevelDebugging.html diff -u llvm/docs/SourceLevelDebugging.html:1.15 llvm/docs/SourceLevelDebugging.html:1.16 --- llvm/docs/SourceLevelDebugging.html:1.15 Wed Mar 15 13:10:52 2006 +++ llvm/docs/SourceLevelDebugging.html Thu Mar 23 11:54:33 2006 @@ -16,6 +16,7 @@ <li><a href="#introduction">Introduction</a> <ol> <li><a href="#phil">Philosophy behind LLVM debugging information</a></li> + <li><a href="#consumers">Debug information consumers</a></li> <li><a href="#debugopt">Debugging optimized code</a></li> </ol></li> <li><a href="#format">Debugging information format</a> @@ -32,6 +33,7 @@ <li><a href="#format_composite_type">Composite type descriptors</a></li> <li><a href="#format_subrange">Subrange descriptors</a></li> <li><a href="#format_enumeration">Enumerator descriptors</a></li> + <li><a href="#format_variables">Local variables</a></li> </ul></li> <li><a href="#format_common_intrinsics">Debugger intrinsic functions</a> <ul> @@ -134,6 +136,29 @@ <!-- ======================================================================= --> <div class="doc_subsection"> + <a name="consumers">Debug information consumers</a> +</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> + +<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> + +<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> + +<p>TODO - expound a bit more.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> <a name="debugopt">Debugging optimized code</a> </div> @@ -248,12 +273,13 @@ <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.</p> +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 (MachineDebugInfo) are restricted to only the simple data types <tt>int</tt>, <tt>uint</tt>, @@ -328,7 +354,7 @@ %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type { uint, ;; Tag = 17 (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, ;; 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 @@ </pre> <p>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 <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> @@ -363,7 +389,7 @@ { }*, ;; 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 @@ { }*, ;; 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) } </pre> <p>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.</p> - -<p>The array of member descriptors is used to define arguments local variables -and nested blocks.</p> +subprograms. They provide details such as name, return types and the source +location where the subprogram is defined.</p> </div> <!-- ======================================================================= --> @@ -416,7 +438,7 @@ <pre> %<a href="#format_blocks">llvm.dbg.block</a> = type { uint, ;; Tag = 13 (DW_TAG_lexical_block) - { }* ;; Reference to array of member descriptors + { }* ;; Reference to context descriptor } </pre> @@ -439,7 +461,7 @@ { }*, ;; 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 @@ { }*, ;; 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 @@ { }*, ;; 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 @@ -638,6 +660,44 @@ </div> <!-- ======================================================================= --> +<div class="doc_subsubsection"> + <a name="format_variables">Local variables</a> +</div> + +<div class="doc_text"> +<pre> + %<a href="#format_variables">llvm.dbg.variable.type</a> = type { + uint, ;; Tag (see below) + { }*, ;; Context + sbyte*, ;; Name + { }*, ;; Reference to compile unit where defined + uint, ;; Line number where defined + { }* ;; Type descriptor + } +</pre> + +<p>These descriptors are used to define variables local to a sub program. The +value of the tag depends on the usage of the variable;</p> + +<pre> + DW_TAG_auto_variable = 256 + DW_TAG_arg_variable = 257 + DW_TAG_return_variable = 258 +</pre> + +<p>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.</p> + +<p>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.</p> + +</div> + +<!-- ======================================================================= --> <div class="doc_subsection"> <a name="format_common_intrinsics">Debugger intrinsic functions</a> </div> @@ -664,7 +724,8 @@ argument si the column number (0 if unknown) and the third argument the source compile unit. Code following a call to this intrinsic will have been defined in close proximity of the line, column and file. This information holds until the -next call to <a href="#format_common_stoppoint">lvm.dbg.stoppoint</a>.</p> +next call to <tt>%<a +href="#format_common_stoppoint">lvm.dbg.stoppoint</a></tt>.</p> </div> @@ -675,14 +736,17 @@ <div class="doc_text"> <pre> - void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( %<a href="#format_subprograms">llvm.dbg.subprogram.type</a>* ) + void %<a href="#format_common_func_start">llvm.dbg.func.start</a>( { }* ) </pre> <p>This intrinsic is used to link the debug information in <tt>%<a href="#format_subprograms">llvm.dbg.subprogram</a></tt> 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.</p> +instructions. It should be paired off with a closing <tt>%<a +href="#format_common_region_end">llvm.dbg.region.end</a></tt>. The function's +single argument is the <tt>%<a +href="#format_subprograms">llvm.dbg.subprogram.type</a></tt>.</p> </div> @@ -693,12 +757,15 @@ <div class="doc_text"> <pre> - void %<a href="#format_common_region_start">llvm.dbg.region.start</a>() + void %<a href="#format_common_region_start">llvm.dbg.region.start</a>( { }* ) </pre> <p>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 -<tt>%<a href="#format_common_region_end">llvm.dbg.region.end</a></tt>.</p> +<tt>%<a href="#format_common_region_end">llvm.dbg.region.end</a></tt>. The +function's single argument is the <tt>%<a +href="#format_blocks">llvm.dbg.block</a></tt> which is starting.</p> + </div> @@ -709,13 +776,17 @@ <div class="doc_text"> <pre> - void %<a href="#format_common_region_end">llvm.dbg.region.end</a>() + void %<a href="#format_common_region_end">llvm.dbg.region.end</a>( { }* ) </pre> <p>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 <tt>%<a href="#format_common_region_start">llvm.dbg.region.start</a></tt> or <tt>%<a -href="#format_common_func_start">llvm.dbg.func.start</a></tt>.</p> +href="#format_common_func_start">llvm.dbg.func.start</a></tt>. The function's +single argument is either the <tt>%<a +href="#format_blocks">llvm.dbg.block</a></tt> or the <tt>%<a +href="#format_subprograms">llvm.dbg.subprogram.type</a></tt> which is +ending.</p> </div> @@ -726,11 +797,13 @@ <div class="doc_text"> <pre> - void %<a href="#format_common_declare">llvm.dbg.declare</a>( {} *, ... ) + void %<a href="#format_common_declare">llvm.dbg.declare</a>( { } *, { }* ) </pre> <p>This intrinsic provides information about a local element (ex. variable.) -TODO - details.</p> +The first argument as a AllocA for the variable cast to a <tt>{ }*</tt>. The second +argument is the <tt>%<a href="#format_variables">llvm.dbg.variable</a></tt> +containing the description of the variable, also cast to a <tt>{ }*</tt>.</p> </div> @@ -1097,7 +1170,7 @@ ;; descriptor, one for the global's basic type and one for the subprogram's ;; compile unit. ;; -%<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { uint, { }*, { }*, sbyte*, { }*, bool, bool, { }* } +%<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { uint, { }*, { }*, sbyte*, { }*, bool, bool } %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint } %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ... @@ -1120,8 +1193,7 @@ uint 1, { }* null, bool false, - bool true, - null }, section "llvm.metadata" + bool true }, section "llvm.metadata" ;; ;; Define the name of the subprogram. @@ -1671,7 +1743,7 @@ <a href="mailto:[EMAIL PROTECTED]">Chris Lattner</a><br> <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> - Last modified: $Date: 2006/03/15 19:10:52 $ + Last modified: $Date: 2006/03/23 17:54:33 $ </address> </body> _______________________________________________ llvm-commits mailing list llvm-commits@cs.uiuc.edu http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits