Bring debugging information up to date.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@26759 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 1166 insertions, 636 deletions

diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html
index c735e4e781..6a3d675080 100644
--- a/docs/SourceLevelDebugging.html
+++ b/docs/SourceLevelDebugging.html
@@ -17,46 +17,41 @@
   <ol>
     <li><a href="#phil">Philosophy behind LLVM debugging information</a></li>
     <li><a href="#debugopt">Debugging optimized code</a></li>
-    <li><a href="#future">Future work</a></li>
   </ol></li>
-  <li><a href="#llvm-db">Using the <tt>llvm-db</tt> tool</a>
-  <ol>
-    <li><a href="#limitations">Limitations of <tt>llvm-db</tt></a></li>
-    <li><a href="#sample">A sample <tt>llvm-db</tt> session</a></li>
-    <li><a href="#startup">Starting the debugger</a></li>
-    <li><a href="#commands">Commands recognized by the debugger</a></li>
-  </ol></li>
-
-  <li><a href="#architecture">Architecture of the LLVM debugger</a>
-  <ol>
-    <li><a href="#arch_debugger">The Debugger and InferiorProcess classes</a></li>
-    <li><a href="#arch_info">The RuntimeInfo, ProgramInfo, and SourceLanguage classes</a></li>
-    <li><a href="#arch_llvm-db">The <tt>llvm-db</tt> tool</a></li>
-    <li><a href="#arch_todo">Short-term TODO list</a></li>
-  </ol></li>
-
   <li><a href="#format">Debugging information format</a>
   <ol>
-    <li><a href="#format_common_anchors">Anchors for global objects</a></li>
-    <li><a href="#format_common_stoppoint">Representing stopping points in the source program</a></li>
-    <li><a href="#format_common_lifetime">Object lifetimes and scoping</a></li>
-    <li><a href="#format_common_descriptors">Object descriptor formats</a>
+    <li><a href="#debug_info_descriptors">Debug information descriptors</a>
     <ul>
-      <li><a href="#format_common_source_files">Representation of source files</a></li>
-      <li><a href="#format_common_program_objects">Representation of program objects</a></li>
-      <li><a href="#format_common_object_contexts">Program object contexts</a></li>
+      <li><a href="#format_anchors">Anchor descriptors</a></li>
+      <li><a href="#format_compile_units">Compile unit descriptors</a></li>
+      <li><a href="#format_global_variables">Global variable descriptors</a></li>
+      <li><a href="#format_subprograms">Subprogram descriptors</a></li>
+      <li><a href="#format_basic_type">Basic type descriptors</a></li>
+      <li><a href="#format_derived_type">Derived type descriptors</a></li>
+      <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>
+    </ul></li>
+    <li><a href="#format_common_intrinsics">Debugger intrinsic functions</a>
+      <ul>
+      <li><a href="#format_common_stoppoint">llvm.dbg.stoppoint</a></li>
+      <li><a href="#format_common_func_start">llvm.dbg.func.start</a></li>
+      <li><a href="#format_common_region_start">llvm.dbg.region.start</a></li>
+      <li><a href="#format_common_region_end">llvm.dbg.region.end</a></li>
+      <li><a href="#format_common_declare">llvm.dbg.declare</a></li>
     </ul></li>
-    <li><a href="#format_common_intrinsics">Debugger intrinsic functions</a></li>
-    <li><a href="#format_common_tags">Values for debugger tags</a></li>
+    <li><a href="#format_common_stoppoints">Representing stopping points in the
+                                           source program</a></li>
   </ol></li>
   <li><a href="#ccxx_frontend">C/C++ front-end specific debug information</a>
   <ol>
-    <li><a href="#ccxx_pse">Program Scope Entries</a>
-    <ul>
-      <li><a href="#ccxx_compilation_units">Compilation unit entries</a></li>
-      <li><a href="#ccxx_modules">Module, namespace, and importing entries</a></li>
-    </ul></li>
-    <li><a href="#ccxx_dataobjects">Data objects (program variables)</a></li>
+    <li><a href="#ccxx_compile_units">C/C++ source file information</a></li>
+    <li><a href="#ccxx_global_variable">C/C++ global variable information</a></li>
+    <li><a href="#ccxx_subprogram">C/C++ function information</a></li>
+    <li><a href="#ccxx_basic_types">C/C++ basic types</a></li>
+    <li><a href="#ccxx_derived_types">C/C++ derived types</a></li>
+    <li><a href="#ccxx_composite_types">C/C++ struct/union types</a></li>
+    <li><a href="#ccxx_enumeration_types">C/C++ enumeration types</a></li>
   </ol></li>
 </ul>
 </td>
@@ -67,7 +62,8 @@ height="369">
 </tr></table>
 
 <div class="doc_author">
-  <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
+  <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
+            and <a href="mailto:jlaskey@apple.com">Jim Laskey</a></p>
 </div>
 
 
@@ -78,15 +74,10 @@ 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="#llvm-db">user
-interface</a> for the <tt>llvm-db</tt> tool, which provides a 
-powerful <a href="#llvm-db">source-level debugger</a>
-to users of LLVM-based compilers.  It then describes the <a
-href="#architecture">various components</a> that make up the debugger and the
-libraries which future clients may use.  Finally, 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.</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>
 
@@ -133,15 +124,13 @@ 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 debugged, the 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 a
-specific language of family of languages.  The <a href="#llvm-db">LLVM
-debugger</a> is designed to be modular in its support for source-languages.</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, the debugger must be aware of the source-language, and is thus tied to
+a specific language of family of languages.</p>
 
 </div>
 
-
 <!-- ======================================================================= -->
 <div class="doc_subsection">
   <a name="debugopt">Debugging optimized code</a>
@@ -195,508 +184,531 @@ completely.</p>
 
 </div>
 
-<!-- ======================================================================= -->
-<div class="doc_subsection">
-  <a name="future">Future work</a>
+<!-- *********************************************************************** -->
+<div class="doc_section">
+  <a name="format">Debugging information format</a>
 </div>
+<!-- *********************************************************************** -->
 
 <div class="doc_text">
-<p>There are several important extensions that could be eventually added to the
-LLVM debugger.  The most important extension would be to upgrade the LLVM code
-generators to support debugging information.  This would also allow, for
-example, the X86 code generator to emit native objects that contain debugging
-information consumable by traditional source-level debuggers like GDB or
-DBX.</p>
 
-<p>Additionally, LLVM optimizations can be upgraded to incrementally update the
-debugging information, <a href="#commands">new commands</a> can be added to the
-debugger, and thread support could be added to the debugger.</p>
+<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>
 
-<p>The "SourceLanguage" modules provided by <tt>llvm-db</tt> could be
-substantially improved to provide good support for C++ language features like
-namespaces and scoping rules.</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>
+
+<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>
 
-<p>After working with the debugger for a while, perhaps the nicest improvement
-would be to add some sort of line editor, such as GNU readline (but one that is
-compatible with the LLVM license).</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 the debugger to form stack traces, show information about local
+variables, etc.</p>
 
-<p>For someone so inclined, it should be straight-forward to write different
-front-ends for the LLVM debugger, as the LLVM debugging engine is cleanly
-separated from the <tt>llvm-db</tt> front-end.  A new LLVM GUI debugger or IDE
-would be nice.</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>
 
 </div>
 
-<!-- *********************************************************************** -->
-<div class="doc_section">
-  <a name="llvm-db">Using the <tt>llvm-db</tt> tool</a>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="debug_info_descriptors">Debug information descriptors</a>
 </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>
+
+<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>
+
+<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>,
+<tt>bool</tt>, <tt>float</tt>, <tt>double</tt>, <tt>sbyte*</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>
+
+<pre>
+  %llvm.dbg.object.type = type {
+    uint,   ;; A tag
+    ...
+  }
+</pre>
 
-<p>The <tt>llvm-db</tt> tool provides a GDB-like interface for source-level
-debugging of programs.  This tool provides many standard commands for inspecting
-and modifying the program as it executes, loading new programs, single stepping,
-placing breakpoints, etc.  This section describes how to use the debugger.</p>
+<p>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.</p>
 
-<p><tt>llvm-db</tt> has been designed to be as similar to GDB in its user
-interface as possible.  This should make it extremely easy to learn
-<tt>llvm-db</tt> if you already know <tt>GDB</tt>.  In general, <tt>llvm-db</tt>
-provides the subset of GDB commands that are applicable to LLVM debugging users.
-If there is a command missing that make a reasonable amount of sense within the
-<a href="#limitations">limitations of <tt>llvm-db</tt></a>, please report it as
-a bug or, better yet, submit a patch to add it.</p>
+<p>The details of the various descriptors follow.</p>
 
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
-  <a name="limitations">Limitations of <tt>llvm-db</tt></a>
+<div class="doc_subsubsection">
+  <a name="format_anchors">Anchor descriptors</a>
 </div>
 
 <div class="doc_text">
 
-<p><tt>llvm-db</tt> is designed to be modular and easy to extend.  This
-extensibility was key to getting the debugger up-and-running quickly, because we
-can start with simple-but-unsophisicated implementations of various components.
-Because of this, it is currently missing many features, though they should be
-easy to add over time (patches welcomed!).  The biggest inherent limitations of
-<tt>llvm-db</tt> are currently due to extremely simple <a
-href="#arch_debugger">debugger backend</a> (implemented in
-"lib/Debugger/UnixLocalInferiorProcess.cpp") which is designed to work without
-any cooperation from the code generators.  Because it is so simple, it suffers
-from the following inherent limitations:</p>
+<pre>
+  %<a href="#format_anchors">llvm.dbg.anchor.type</a> = type {
+    uint,   ;; Tag = 0
+    uint    ;; Tag of descriptors grouped by the anchor
+  }
+</pre>
 
-<ul>
+<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
+the debugger to use def-use chains to find all global objects of that type.</p>
 
-<li>Running a program in <tt>llvm-db</tt> is a bit slower than running it with
-<tt>lli</tt> (i.e., in the JIT).</li>
+<p>The following names are recognized as anchors by LLVM:</p>
 
-<li>Inspection of the target hardware is not supported.  This means that you
-cannot, for example, print the contents of X86 registers.</li>
+<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
+</pre>
 
-<li>Inspection of LLVM code is not supported.  This means that you cannot print
-the contents of arbitrary LLVM values, or use commands such as <tt>stepi</tt>.
-This also means that you cannot debug code without debug information.</li>
+<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>
 
-<li>Portions of the debugger run in the same address space as the program being
-debugged.  This means that memory corruption by the program could trample on
-portions of the debugger.</li>
+</div>
 
-<li>Attaching to existing processes and core files is not currently
-supported.</li>
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+  <a name="format_compile_units">Compile unit descriptors</a>
+</div>
 
-</ul>
+<div class="doc_text">
 
-<p>That said, the debugger is still quite useful, and all of these limitations
-can be eliminated by integrating support for the debugger into the code
-generators, and writing a new <a href="#arch_debugger">InferiorProcess</a>
-subclass to use it.  See the <a href="#future">future work</a> section for ideas
-of how to extend the LLVM debugger despite these limitations.</p>
+<pre>
+  %<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 = 1
+    uint,   ;; Dwarf language identifier (ex. DW_LANG_C89) 
+    sbyte*, ;; Source file name
+    sbyte*, ;; Source file directory (includes trailing slash)
+    sbyte*  ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
+  }
+</pre>
 
-</div>
+<p>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
+<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>  
+
+</div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
-  <a name="sample">A sample <tt>llvm-db</tt> session</a>
+<div class="doc_subsubsection">
+  <a name="format_global_variables">Global variable descriptors</a>
 </div>
 
 <div class="doc_text">
 
-<p>TODO: this is obviously lame, when more is implemented, this can be much
-better.</p>
-
 <pre>
-$ <b>llvm-db funccall</b>
-llvm-db: The LLVM source-level debugger
-Loading program... successfully loaded 'funccall.bc'!
-(llvm-db) <b>create</b>
-Starting program: funccall.bc
-main at funccall.c:9:2
-9 ->            q = 0;
-(llvm-db) <b>list main</b>
-4       void foo() {
-5               int t = q;
-6               q = t + 1;
-7       }
-8       int main() {
-9 ->            q = 0;
-10              foo();
-11              q = q - 1;
-12
-13              return q;
-(llvm-db) <b>list</b>
-14      }
-(llvm-db) <b>step</b>
-10 ->           foo();
-(llvm-db) <b>s</b>
-foo at funccall.c:5:2
-5 ->            int t = q;
-(llvm-db) <b>bt</b>
-#0 ->   0x85ffba0 in foo at funccall.c:5:2
-#1      0x85ffd98 in main at funccall.c:10:2
-(llvm-db) <b>finish</b>
-main at funccall.c:11:2
-11 ->           q = q - 1;
-(llvm-db) <b>s</b>
-13 ->           return q;
-(llvm-db) <b>s</b>
-The program stopped with exit code 0
-(llvm-db) <b>quit</b>
-$
+  %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type {
+    uint,   ;; Tag = 52 (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 compile unit
+    sbyte*, ;; Name
+    {  }*,  ;; 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
+  }
 </pre>
 
+<p>These descriptors provide debug information about globals variables.  The
+provide details such as name, type and where the variable is defined.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+  <a name="format_subprograms">Subprogram descriptors</a>
 </div>
 
+<div class="doc_text">
+
+<pre>
+  %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type {
+    uint,   ;; Tag = 46 (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 compile unit
+    sbyte*, ;; Name
+    {  }*,  ;; 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
+  }
+
+</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>
 
+</div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
-  <a name="startup">Starting the debugger</a>
+<div class="doc_subsubsection">
+  <a name="format_basic_type">Basic type descriptors</a>
 </div>
 
 <div class="doc_text">
 
-<p>There are three ways to start up the <tt>llvm-db</tt> debugger:</p>
+<pre>
+  %<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type {
+    uint,   ;; Tag = 36 (DW_TAG_base_type)
+    {  }*,  ;; 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,   ;; Size in bits
+    uint,   ;; Alignment in bits
+    uint,   ;; Offset in bits
+    uint    ;; Dwarf type encoding
+  }
+</pre>
 
-<p>When run with no options, just <tt>llvm-db</tt>, the debugger starts up
-without a program loaded at all.  You must use the <a
-href="#c_file"><tt>file</tt> command</a> to load a program, and the <a
-href="#c_set_args"><tt>set args</tt></a> or <a href="#c_run"><tt>run</tt></a>
-commands to specify the arguments for the program.</p>
+<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>
 
-<p>If you start the debugger with one argument, as <tt>llvm-db
-&lt;program&gt;</tt>, the debugger will start up and load in the specified
-program.  You can then optionally specify arguments to the program with the <a
-href="#c_set_args"><tt>set args</tt></a> or <a href="#c_run"><tt>run</tt></a>
-commands.</p>
+<p>The type encoding provides the details of the type.  The values are typically
+one of the following;</p>
 
-<p>The third way to start the program is with the <tt>--args</tt> option.  This
-option allows you to specify the program to load and the arguments to start out
-with.  <!-- No options to <tt>llvm-db</tt> may be specified after the
-<tt>-args</tt> option. --> Example use: <tt>llvm-db --args ls /home</tt></p>
+<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
+</pre>
 
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
-  <a name="commands">Commands recognized by the debugger</a>
+<div class="doc_subsubsection">
+  <a name="format_derived_type">Derived type descriptors</a>
 </div>
 
 <div class="doc_text">
 
-<p>FIXME: this needs work obviously.  See the <a
-href="http://sources.redhat.com/gdb/documentation/">GDB documentation</a> for
-information about what these do, or try '<tt>help [command]</tt>' within
-<tt>llvm-db</tt> to get information.</p>
+<pre>
+  %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> = type {
+    uint,   ;; Tag (see below)
+    {  }*,  ;; 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,   ;; Size in bits
+    uint,   ;; Alignment in bits
+    uint,   ;; Offset in bits
+    {  }*   ;; Reference to type derived from
+  }
+</pre>
 
-<p>
-<h2>General usage:</h2>
-<ul>
-<li>help [command]</li>
-<li>quit</li>
-<li><a name="c_file">file</a> [program]</li>
-</ul>
+<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>
 
-<h2>Program inspection and interaction:</h2>
-<ul>
-<li>create (start the program, stopping it ASAP in <tt>main</tt>)</li>
-<li>kill</li>
-<li>run [args]</li>
-<li>step [num]</li>
-<li>next [num]</li>
-<li>cont</li>
-<li>finish</li>
-
-<li>list [start[, end]]</li>
-<li>info source</li>
-<li>info sources</li>
-<li>info functions</li>
-</ul>
+<pre>
+  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>
 
-<h2>Call stack inspection:</h2>
-<ul>
-<li>backtrace</li>
-<li>up [n]</li>
-<li>down [n]</li>
-<li>frame [n]</li>
-</ul>
+<p> <tt>DW_TAG_member</tt> is used to define a member of a <a
+href="#format_composite_type">composite type</a>.  The type of the member is the
+<a href="#format_derived_type">derived type</a>.</p>
 
+<p><tt>DW_TAG_typedef</tt> is used to
+provide a name for the derived type.</p>
 
-<h2>Debugger inspection and interaction:</h2>
-<ul>
-<li>info target</li>
-<li>show prompt</li>
-<li>set prompt</li>
-<li>show listsize</li>
-<li>set listsize</li>
-<li>show language</li>
-<li>set language</li>
-<li>show args</li>
-<li>set args [args]</li>
-</ul>
+<p><tt>DW_TAG_pointer_type</tt>,
+<tt>DW_TAG_reference_type</tt>, <tt>DW_TAG_const_type</tt>,
+<tt>DW_TAG_volatile_type</tt> and <tt>DW_TAG_restrict_type</tt> are used to
+qualify the <a href="#format_derived_type">derived type</a>. </p>
 
-<h2>TODO:</h2>
-<ul>
-<li>info frame</li>
-<li>break</li>
-<li>print</li>
-<li>ptype</li>
-
-<li>info types</li>
-<li>info variables</li>
-<li>info program</li>
-
-<li>info args</li>
-<li>info locals</li>
-<li>info catch</li>
-<li>... many others</li>
-</ul>
+<p><a href="#format_derived_type">Derived type</a> location can be determined
+from the compile unit and line number.  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>Note that the <tt>void *</tt> type is expressed as a
+<tt>llvm.dbg.derivedtype.type</tt> with tag of <tt>DW_TAG_pointer_type</tt> and
+NULL derived type.</p>
 
 </div>
 
-<!-- *********************************************************************** -->
-<div class="doc_section">
-  <a name="architecture">Architecture of the LLVM debugger</a>
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+  <a name="format_composite_type">Composite type descriptors</a>
 </div>
-<!-- *********************************************************************** -->
 
 <div class="doc_text">
-<p>The LLVM debugger is built out of three distinct layers of software.  These
-layers provide clients with different interface options depending on what pieces
-of they want to implement themselves, and it also promotes code modularity and
-good design.  The three layers are the <a href="#arch_debugger">Debugger
-interface</a>, the <a href="#arch_info">"info" interfaces</a>, and the <a
-href="#arch_llvm-db"><tt>llvm-db</tt> tool</a> itself.</p>
+
+<pre>
+  %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> = type {
+    uint,   ;; Tag (see below)
+    {  }*,  ;; 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,   ;; Size in bits
+    uint,   ;; Alignment in bits
+    uint,   ;; Offset in bits
+    {  }*   ;; Reference to array of member descriptors
+  }
+</pre>
+
+<p>These descriptors are used to define types that are composed of 0 or more
+elements.  The value of the tag varies depending on the meaning.  The following
+are possible tag values;</p>
+
+<pre>
+  DW_TAG_array_type = 1
+  DW_TAG_enumeration_type = 4
+  DW_TAG_structure_type = 19
+  DW_TAG_union_type = 23
+</pre>
+
+<p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) are <a
+href="#format_subrange">subrange descriptors</a>, each representing the range of
+subscripts at that level of indexing.</p>
+
+<p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
+<a href="#format_enumeration">enumerator descriptors</a>, each representing the
+definition of enumeration value
+for the set.</p>
+
+<p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
+= <tt>DW_TAG_union_type</tt>) types are any one of the <a
+href="#format_basic_type">basic</a>, <a href="#format_derived_type">derived</a>
+or <a href="#format_composite_type">composite</a> type descriptors, each
+representing a field member of the structure or union.</p>
+
+<p><a href="#format_composite_type">Composite type</a> location can be
+determined from the compile unit and line number.  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> (as an 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>
+
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection">
-  <a name="arch_debugger">The Debugger and InferiorProcess classes</a>
+<div class="doc_subsubsection">
+  <a name="format_subrange">Subrange descriptors</a>
 </div>
 
 <div class="doc_text">
-<p>The Debugger class (defined in the <tt>include/llvm/Debugger/</tt> directory)
-is a low-level class which is used to maintain information about the loaded
-program, as well as start and stop the program running as necessary.  This class
-does not provide any high-level analysis or control over the program, only
-exposing simple interfaces like <tt>load/unloadProgram</tt>,
-<tt>create/killProgram</tt>, <tt>step/next/finish/contProgram</tt>, and
-low-level methods for installing breakpoints.</p>
-
-<p>
-The Debugger class is itself a wrapper around the lowest-level InferiorProcess
-class.  This class is used to represent an instance of the program running under
-debugger control.  The InferiorProcess class can be implemented in different
-ways for different targets and execution scenarios (e.g., remote debugging).
-The InferiorProcess class exposes a small and simple collection of interfaces
-which are useful for inspecting the current state of the program (such as
-collecting stack trace information, reading the memory image of the process,
-etc).  The interfaces in this class are designed to be as low-level and simple
-as possible, to make it easy to create new instances of the class.
-</p>
-
-<p>
-The Debugger class exposes the currently active instance of InferiorProcess
-through the <tt>Debugger::getRunningProcess</tt> method, which returns a
-<tt>const</tt> reference to the class.  This means that clients of the Debugger
-class can only <b>inspect</b> the running instance of the program directly.  To
-change the executing process in some way, they must use the interces exposed by
-the Debugger class.
-</p>
+
+<pre>
+  %<a href="#format_subrange">llvm.dbg.subrange.type</a> = type {
+    uint,   ;; Tag = 33 (DW_TAG_subrange_type)
+    uint,   ;; Low value
+    uint    ;; High value
+  }
+</pre>
+
+<p>These descriptors are used to define ranges of array subscripts for an array
+<a href="#format_composite_type">composite type</a>.  The low value defines the
+lower bounds typically zero for C/C++.  The high value is the upper bounds. 
+Values are 64 bit.  High - low + 1 is the size of the array.  If
+low == high the array will be unbounded.</p>
+
 </div>