docs/SourceLevelDebugging.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6   <title>Source Level Debugging with LLVM</title>
   7   <link rel="stylesheet" href="llvm.css" type="text/css">
   8 </head>
   9 <body>
  10
  11 <h1>Source Level Debugging with LLVM</h1>
  12
  13 <table class="layout" style="width:100%">
  14   <tr class="layout">
  15     <td class="left">
  16 <ul>
  17   <li><a href="#introduction">Introduction</a>
  18   <ol>
  19     <li><a href="#phil">Philosophy behind LLVM debugging information</a></li>
  20     <li><a href="#consumers">Debug information consumers</a></li>
  21     <li><a href="#debugopt">Debugging optimized code</a></li>
  22   </ol></li>
  23   <li><a href="#format">Debugging information format</a>
  24   <ol>
  25     <li><a href="#debug_info_descriptors">Debug information descriptors</a>
  26     <ul>
  27       <li><a href="#format_compile_units">Compile unit descriptors</a></li>
  28       <li><a href="#format_files">File descriptors</a></li>
  29       <li><a href="#format_global_variables">Global variable descriptors</a></li>
  30       <li><a href="#format_subprograms">Subprogram descriptors</a></li>
  31       <li><a href="#format_blocks">Block descriptors</a></li>
  32       <li><a href="#format_basic_type">Basic type descriptors</a></li>
  33       <li><a href="#format_derived_type">Derived type descriptors</a></li>
  34       <li><a href="#format_composite_type">Composite type descriptors</a></li>
  35       <li><a href="#format_subrange">Subrange descriptors</a></li>
  36       <li><a href="#format_enumeration">Enumerator descriptors</a></li>
  37       <li><a href="#format_variables">Local variables</a></li>
  38     </ul></li>
  39     <li><a href="#format_common_intrinsics">Debugger intrinsic functions</a>
  40       <ul>
  41       <li><a href="#format_common_declare">llvm.dbg.declare</a></li>
  42       <li><a href="#format_common_value">llvm.dbg.value</a></li>
  43     </ul></li>
  44   </ol></li>
  45   <li><a href="#format_common_lifetime">Object lifetimes and scoping</a></li>
  46   <li><a href="#ccxx_frontend">C/C++ front-end specific debug information</a>
  47   <ol>
  48     <li><a href="#ccxx_compile_units">C/C++ source file information</a></li>
  49     <li><a href="#ccxx_global_variable">C/C++ global variable information</a></li>
  50     <li><a href="#ccxx_subprogram">C/C++ function information</a></li>
  51     <li><a href="#ccxx_basic_types">C/C++ basic types</a></li>
  52     <li><a href="#ccxx_derived_types">C/C++ derived types</a></li>
  53     <li><a href="#ccxx_composite_types">C/C++ struct/union types</a></li>
  54     <li><a href="#ccxx_enumeration_types">C/C++ enumeration types</a></li>
  55   </ol></li>
  56   <li><a href="#llvmdwarfextension">LLVM Dwarf Extensions</a>
  57     <ol>
  58       <li><a href="#objcproperty">Debugging Information Extension
  59           for Objective C Properties</a></li>
  60       <ul>
  61         <li><a href="#objcpropertyintroduction">Introduction</a></li>
  62         <li><a href="#objcpropertyproposal">Proposal</a></li>
  63         <li><a href="#objcpropertynewattributes">New DWARF Attributes</a></li>
  64         <li><a href="#objcpropertynewconstants">New DWARF Constants</a></li>
  65       </ul>
  66       <li><a href="#acceltable">Name Accelerator Tables</a></li>
  67       <ul>
  68         <li><a href="#acceltableintroduction">Introduction</a></li>
  69         <li><a href="#acceltablehashes">Hash Tables</a></li>
  70         <li><a href="#acceltabledetails">Details</a></li>
  71         <li><a href="#acceltablecontents">Contents</a></li>
  72         <li><a href="#acceltableextensions">Language Extensions and File Format Changes</a></li>
  73       </ul>
  74     </ol>
  75   </li>
  76 </ul>
  77 </td>
  78 <td class="right">
  79 <img src="img/venusflytrap.jpg" alt="A leafy and green bug eater" width="247"
  80 height="369">
  81 </td>
  82 </tr></table>
  83
  84 <div class="doc_author">
  85   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
  86             and <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
  87 </div>
  88
  89
  90 <!-- *********************************************************************** -->
  91 <h2><a name="introduction">Introduction</a></h2>
  92 <!-- *********************************************************************** -->
  93
  94 <div>
  95
  96 <p>This document is the central repository for all information pertaining to
  97    debug information in LLVM.  It describes the <a href="#format">actual format
  98    that the LLVM debug information</a> takes, which is useful for those
  99    interested in creating front-ends or dealing directly with the information.
 100    Further, this document provides specific examples of what debug information
 101    for C/C++ looks like.</p>
 102
 103 <!-- ======================================================================= -->
 104 <h3>
 105   <a name="phil">Philosophy behind LLVM debugging information</a>
 106 </h3>
 107
 108 <div>
 109
 110 <p>The idea of the LLVM debugging information is to capture how the important
 111    pieces of the source-language's Abstract Syntax Tree map onto LLVM code.
 112    Several design aspects have shaped the solution that appears here.  The
 113    important ones are:</p>
 114
 115 <ul>
 116   <li>Debugging information should have very little impact on the rest of the
 117       compiler.  No transformations, analyses, or code generators should need to
 118       be modified because of debugging information.</li>
 119
 120   <li>LLVM optimizations should interact in <a href="#debugopt">well-defined and
 121       easily described ways</a> with the debugging information.</li>
 122
 123   <li>Because LLVM is designed to support arbitrary programming languages,
 124       LLVM-to-LLVM tools should not need to know anything about the semantics of
 125       the source-level-language.</li>
 126
 127   <li>Source-level languages are often <b>widely</b> different from one another.
 128       LLVM should not put any restrictions of the flavor of the source-language,
 129       and the debugging information should work with any language.</li>
 130
 131   <li>With code generator support, it should be possible to use an LLVM compiler
 132       to compile a program to native machine code and standard debugging
 133       formats.  This allows compatibility with traditional machine-code level
 134       debuggers, like GDB or DBX.</li>
 135 </ul>
 136
 137 <p>The approach used by the LLVM implementation is to use a small set
 138    of <a href="#format_common_intrinsics">intrinsic functions</a> to define a
 139    mapping between LLVM program objects and the source-level objects.  The
 140    description of the source-level program is maintained in LLVM metadata
 141    in an <a href="#ccxx_frontend">implementation-defined format</a>
 142    (the C/C++ front-end currently uses working draft 7 of
 143    the <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3
 144    standard</a>).</p>
 145
 146 <p>When a program is being debugged, a debugger interacts with the user and
 147    turns the stored debug information into source-language specific information.
 148    As such, a debugger must be aware of the source-language, and is thus tied to
 149    a specific language or family of languages.</p>
 150
 151 </div>
 152
 153 <!-- ======================================================================= -->
 154 <h3>
 155   <a name="consumers">Debug information consumers</a>
 156 </h3>
 157
 158 <div>
 159
 160 <p>The role of debug information is to provide meta information normally
 161    stripped away during the compilation process.  This meta information provides
 162    an LLVM user a relationship between generated code and the original program
 163    source code.</p>
 164
 165 <p>Currently, debug information is consumed by DwarfDebug to produce dwarf
 166    information used by the gdb debugger.  Other targets could use the same
 167    information to produce stabs or other debug forms.</p>
 168
 169 <p>It would also be reasonable to use debug information to feed profiling tools
 170    for analysis of generated code, or, tools for reconstructing the original
 171    source from generated code.</p>
 172
 173 <p>TODO - expound a bit more.</p>
 174
 175 </div>
 176
 177 <!-- ======================================================================= -->
 178 <h3>
 179   <a name="debugopt">Debugging optimized code</a>
 180 </h3>
 181
 182 <div>
 183
 184 <p>An extremely high priority of LLVM debugging information is to make it
 185    interact well with optimizations and analysis.  In particular, the LLVM debug
 186    information provides the following guarantees:</p>
 187
 188 <ul>
 189   <li>LLVM debug information <b>always provides information to accurately read
 190       the source-level state of the program</b>, regardless of which LLVM
 191       optimizations have been run, and without any modification to the
 192       optimizations themselves.  However, some optimizations may impact the
 193       ability to modify the current state of the program with a debugger, such
 194       as setting program variables, or calling functions that have been
 195       deleted.</li>
 196
 197   <li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM
 198       debugging information, allowing them to update the debugging information
 199       as they perform aggressive optimizations.  This means that, with effort,
 200       the LLVM optimizers could optimize debug code just as well as non-debug
 201       code.</li>
 202
 203   <li>LLVM debug information does not prevent optimizations from
 204       happening (for example inlining, basic block reordering/merging/cleanup,
 205       tail duplication, etc).</li>
 206
 207   <li>LLVM debug information is automatically optimized along with the rest of
 208       the program, using existing facilities.  For example, duplicate
 209       information is automatically merged by the linker, and unused information
 210       is automatically removed.</li>
 211 </ul>
 212
 213 <p>Basically, the debug information allows you to compile a program with
 214    "<tt>-O0 -g</tt>" and get full debug information, allowing you to arbitrarily
 215    modify the program as it executes from a debugger.  Compiling a program with
 216    "<tt>-O3 -g</tt>" gives you full debug information that is always available
 217    and accurate for reading (e.g., you get accurate stack traces despite tail
 218    call elimination and inlining), but you might lose the ability to modify the
 219    program and call functions where were optimized out of the program, or
 220    inlined away completely.</p>
 221
 222 <p><a href="TestingGuide.html#quicktestsuite">LLVM test suite</a> provides a
 223    framework to test optimizer's handling of debugging information. It can be
 224    run like this:</p>
 225
 226 <div class="doc_code">
 227 <pre>
 228 % cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
 229 % make TEST=dbgopt
 230 </pre>
 231 </div>
 232
 233 <p>This will test impact of debugging information on optimization passes. If
 234    debugging information influences optimization passes then it will be reported
 235    as a failure. See <a href="TestingGuide.html">TestingGuide</a> for more
 236    information on LLVM test infrastructure and how to run various tests.</p>
 237
 238 </div>
 239
 240 </div>
 241
 242 <!-- *********************************************************************** -->
 243 <h2>
 244   <a name="format">Debugging information format</a>
 245 </h2>
 246 <!-- *********************************************************************** -->
 247
 248 <div>
 249
 250 <p>LLVM debugging information has been carefully designed to make it possible
 251    for the optimizer to optimize the program and debugging information without
 252    necessarily having to know anything about debugging information.  In
 253    particular, the use of metadata avoids duplicated debugging information from
 254    the beginning, and the global dead code elimination pass automatically
 255    deletes debugging information for a function if it decides to delete the
 256    function. </p>
 257
 258 <p>To do this, most of the debugging information (descriptors for types,
 259    variables, functions, source files, etc) is inserted by the language
 260    front-end in the form of LLVM metadata. </p>
 261
 262 <p>Debug information is designed to be agnostic about the target debugger and
 263    debugging information representation (e.g. DWARF/Stabs/etc).  It uses a
 264    generic pass to decode the information that represents variables, types,
 265    functions, namespaces, etc: this allows for arbitrary source-language
 266    semantics and type-systems to be used, as long as there is a module
 267    written for the target debugger to interpret the information. </p>
 268
 269 <p>To provide basic functionality, the LLVM debugger does have to make some
 270    assumptions about the source-level language being debugged, though it keeps
 271    these to a minimum.  The only common features that the LLVM debugger assumes
 272    exist are <a href="#format_files">source files</a>,
 273    and <a href="#format_global_variables">program objects</a>.  These abstract
 274    objects are used by a debugger to form stack traces, show information about
 275    local variables, etc.</p>
 276
 277 <p>This section of the documentation first describes the representation aspects
 278    common to any source-language.  The <a href="#ccxx_frontend">next section</a>
 279    describes the data layout conventions used by the C and C++ front-ends.</p>
 280
 281 <!-- ======================================================================= -->
 282 <h3>
 283   <a name="debug_info_descriptors">Debug information descriptors</a>
 284 </h3>
 285
 286 <div>
 287
 288 <p>In consideration of the complexity and volume of debug information, LLVM
 289    provides a specification for well formed debug descriptors. </p>
 290
 291 <p>Consumers of LLVM debug information expect the descriptors for program
 292    objects to start in a canonical format, but the descriptors can include
 293    additional information appended at the end that is source-language
 294    specific. All LLVM debugging information is versioned, allowing backwards
 295    compatibility in the case that the core structures need to change in some
 296    way.  Also, all debugging information objects start with a tag to indicate
 297    what type of object it is.  The source-language is allowed to define its own
 298    objects, by using unreserved tag numbers.  We recommend using with tags in
 299    the range 0x1000 through 0x2000 (there is a defined enum DW_TAG_user_base =
 300    0x1000.)</p>
 301
 302 <p>The fields of debug descriptors used internally by LLVM
 303    are restricted to only the simple data types <tt>i32</tt>, <tt>i1</tt>,
 304    <tt>float</tt>, <tt>double</tt>, <tt>mdstring</tt> and <tt>mdnode</tt>. </p>
 305
 306 <div class="doc_code">
 307 <pre>
 308 !1 = metadata !{
 309   i32,   ;; A tag
 310   ...
 311 }
 312 </pre>
 313 </div>
 314
 315 <p><a name="LLVMDebugVersion">The first field of a descriptor is always an
 316    <tt>i32</tt> containing a tag value identifying the content of the
 317    descriptor.  The remaining fields are specific to the descriptor.  The values
 318    of tags are loosely bound to the tag values of DWARF information entries.
 319    However, that does not restrict the use of the information supplied to DWARF
 320    targets.  To facilitate versioning of debug information, the tag is augmented
 321    with the current debug version (LLVMDebugVersion = 8 &lt;&lt; 16 or
 322    0x80000 or 524288.)</a></p>
 323
 324 <p>The details of the various descriptors follow.</p>
 325
 326 <!-- ======================================================================= -->
 327 <h4>
 328   <a name="format_compile_units">Compile unit descriptors</a>
 329 </h4>
 330
 331 <div>
 332
 333 <div class="doc_code">
 334 <pre>
 335 !0 = metadata !{
 336   i32,       ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 337              ;; (DW_TAG_compile_unit)
 338   i32,       ;; Unused field.
 339   i32,       ;; DWARF language identifier (ex. DW_LANG_C89)
 340   metadata,  ;; Source file name
 341   metadata,  ;; Source file directory (includes trailing slash)
 342   metadata   ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
 343   i1,        ;; True if this is a main compile unit.
 344   i1,        ;; True if this is optimized.
 345   metadata,  ;; Flags
 346   i32        ;; Runtime version
 347   metadata   ;; List of enums types
 348   metadata   ;; List of retained types
 349   metadata   ;; List of subprograms
 350   metadata   ;; List of global variables
 351 }
 352 </pre>
 353 </div>
 354
 355 <p>These descriptors contain a source language ID for the file (we use the DWARF
 356    3.0 ID numbers, such as <tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>,
 357    <tt>DW_LANG_Cobol74</tt>, etc), three strings describing the filename,
 358    working directory of the compiler, and an identifier string for the compiler
 359    that produced it.</p>
 360
 361 <p>Compile unit descriptors provide the root context for objects declared in a
 362    specific compilation unit. File descriptors are defined using this context.
 363    These descriptors are collected by a named metadata
 364    <tt>!llvm.dbg.cu</tt>. Compile unit descriptor keeps track of subprograms,
 365    global variables and type information.
 366
 367 </div>
 368
 369 <!-- ======================================================================= -->
 370 <h4>
 371   <a name="format_files">File descriptors</a>
 372 </h4>
 373
 374 <div>
 375
 376 <div class="doc_code">
 377 <pre>
 378 !0 = metadata !{
 379   i32,       ;; Tag = 41 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 380              ;; (DW_TAG_file_type)
 381   metadata,  ;; Source file name
 382   metadata,  ;; Source file directory (includes trailing slash)
 383   metadata   ;; Unused
 384 }
 385 </pre>
 386 </div>
 387
 388 <p>These descriptors contain information for a file. Global variables and top
 389    level functions would be defined using this context.k File descriptors also
 390    provide context for source line correspondence. </p>
 391
 392 <p>Each input file is encoded as a separate file descriptor in LLVM debugging
 393    information output. </p>
 394
 395 </div>
 396
 397 <!-- ======================================================================= -->
 398 <h4>
 399   <a name="format_global_variables">Global variable descriptors</a>
 400 </h4>
 401
 402 <div>
 403
 404 <div class="doc_code">
 405 <pre>
 406 !1 = metadata !{
 407   i32,      ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 408             ;; (DW_TAG_variable)
 409   i32,      ;; Unused field.
 410   metadata, ;; Reference to context descriptor
 411   metadata, ;; Name
 412   metadata, ;; Display name (fully qualified C++ name)
 413   metadata, ;; MIPS linkage name (for C++)
 414   metadata, ;; Reference to file where defined
 415   i32,      ;; Line number where defined
 416   metadata, ;; Reference to type descriptor
 417   i1,       ;; True if the global is local to compile unit (static)
 418   i1,       ;; True if the global is defined in the compile unit (not extern)
 419   {}*       ;; Reference to the global variable
 420 }
 421 </pre>
 422 </div>
 423
 424 <p>These descriptors provide debug information about globals variables.  The
 425 provide details such as name, type and where the variable is defined. All
 426 global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p>
 427
 428 </div>
 429
 430 <!-- ======================================================================= -->
 431 <h4>
 432   <a name="format_subprograms">Subprogram descriptors</a>
 433 </h4>
 434
 435 <div>
 436
 437 <div class="doc_code">
 438 <pre>
 439 !2 = metadata !{
 440   i32,      ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 441             ;; (DW_TAG_subprogram)
 442   i32,      ;; Unused field.
 443   metadata, ;; Reference to context descriptor
 444   metadata, ;; Name
 445   metadata, ;; Display name (fully qualified C++ name)
 446   metadata, ;; MIPS linkage name (for C++)
 447   metadata, ;; Reference to file where defined
 448   i32,      ;; Line number where defined
 449   metadata, ;; Reference to type descriptor
 450   i1,       ;; True if the global is local to compile unit (static)
 451   i1,       ;; True if the global is defined in the compile unit (not extern)
 452   i32,      ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual
 453   i32,      ;; Index into a virtual function
 454   metadata, ;; indicates which base type contains the vtable pointer for the
 455             ;; derived class
 456   i32,      ;; Flags - Artifical, Private, Protected, Explicit, Prototyped.
 457   i1,       ;; isOptimized
 458   Function *,;; Pointer to LLVM function
 459   metadata, ;; Lists function template parameters
 460   metadata  ;; Function declaration descriptor
 461   metadata  ;; List of function variables
 462 }
 463 </pre>
 464 </div>
 465
 466 <p>These descriptors provide debug information about functions, methods and
 467    subprograms.  They provide details such as name, return types and the source
 468    location where the subprogram is defined.
 469 </p>
 470
 471 </div>
 472
 473 <!-- ======================================================================= -->
 474 <h4>
 475   <a name="format_blocks">Block descriptors</a>
 476 </h4>
 477
 478 <div>
 479
 480 <div class="doc_code">
 481 <pre>
 482 !3 = metadata !{
 483   i32,     ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
 484   metadata,;; Reference to context descriptor
 485   i32,     ;; Line number
 486   i32,     ;; Column number
 487   metadata,;; Reference to source file
 488   i32      ;; Unique ID to identify blocks from a template function
 489 }
 490 </pre>
 491 </div>
 492
 493 <p>This descriptor provides debug information about nested blocks within a
 494    subprogram. The line number and column numbers are used to dinstinguish
 495    two lexical blocks at same depth. </p>
 496
 497 <div class="doc_code">
 498 <pre>
 499 !3 = metadata !{
 500   i32,     ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
 501   metadata ;; Reference to the scope we're annotating with a file change
 502   metadata,;; Reference to the file the scope is enclosed in.
 503 }
 504 </pre>
 505 </div>
 506
 507 <p>This descriptor provides a wrapper around a lexical scope to handle file
 508    changes in the middle of a lexical block.</p>
 509
 510 </div>
 511
 512 <!-- ======================================================================= -->
 513 <h4>
 514   <a name="format_basic_type">Basic type descriptors</a>
 515 </h4>
 516
 517 <div>
 518
 519 <div class="doc_code">
 520 <pre>
 521 !4 = metadata !{
 522   i32,      ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 523             ;; (DW_TAG_base_type)
 524   metadata, ;; Reference to context
 525   metadata, ;; Name (may be "" for anonymous types)
 526   metadata, ;; Reference to file where defined (may be NULL)
 527   i32,      ;; Line number where defined (may be 0)
 528   i64,      ;; Size in bits
 529   i64,      ;; Alignment in bits
 530   i64,      ;; Offset in bits
 531   i32,      ;; Flags
 532   i32       ;; DWARF type encoding
 533 }
 534 </pre>
 535 </div>
 536
 537 <p>These descriptors define primitive types used in the code. Example int, bool
 538    and float.  The context provides the scope of the type, which is usually the
 539    top level.  Since basic types are not usually user defined the context
 540    and line number can be left as NULL and 0.  The size, alignment and offset
 541    are expressed in bits and can be 64 bit values.  The alignment is used to
 542    round the offset when embedded in a
 543    <a href="#format_composite_type">composite type</a> (example to keep float
 544    doubles on 64 bit boundaries.) The offset is the bit offset if embedded in
 545    a <a href="#format_composite_type">composite type</a>.</p>
 546
 547 <p>The type encoding provides the details of the type.  The values are typically
 548    one of the following:</p>
 549
 550 <div class="doc_code">
 551 <pre>
 552 DW_ATE_address       = 1
 553 DW_ATE_boolean       = 2
 554 DW_ATE_float         = 4
 555 DW_ATE_signed        = 5
 556 DW_ATE_signed_char   = 6
 557 DW_ATE_unsigned      = 7
 558 DW_ATE_unsigned_char = 8
 559 </pre>
 560 </div>
 561
 562 </div>
 563
 564 <!-- ======================================================================= -->
 565 <h4>
 566   <a name="format_derived_type">Derived type descriptors</a>
 567 </h4>
 568
 569 <div>
 570
 571 <div class="doc_code">
 572 <pre>
 573 !5 = metadata !{
 574   i32,      ;; Tag (see below)
 575   metadata, ;; Reference to context
 576   metadata, ;; Name (may be "" for anonymous types)
 577   metadata, ;; Reference to file where defined (may be NULL)
 578   i32,      ;; Line number where defined (may be 0)
 579   i64,      ;; Size in bits
 580   i64,      ;; Alignment in bits
 581   i64,      ;; Offset in bits
 582   i32,      ;; Flags to encode attributes, e.g. private
 583   metadata, ;; Reference to type derived from
 584   metadata, ;; (optional) Name of the Objective C property associated with
 585             ;; Objective-C an ivar
 586   metadata, ;; (optional) Name of the Objective C property getter selector.
 587   metadata, ;; (optional) Name of the Objective C property setter selector.
 588   i32       ;; (optional) Objective C property attributes.
 589 }
 590 </pre>
 591 </div>
 592
 593 <p>These descriptors are used to define types derived from other types.  The
 594 value of the tag varies depending on the meaning.  The following are possible
 595 tag values:</p>
 596
 597 <div class="doc_code">
 598 <pre>
 599 DW_TAG_formal_parameter = 5
 600 DW_TAG_member           = 13
 601 DW_TAG_pointer_type     = 15
 602 DW_TAG_reference_type   = 16
 603 DW_TAG_typedef          = 22
 604 DW_TAG_const_type       = 38
 605 DW_TAG_volatile_type    = 53
 606 DW_TAG_restrict_type    = 55
 607 </pre>
 608 </div>
 609
 610 <p><tt>DW_TAG_member</tt> is used to define a member of
 611    a <a href="#format_composite_type">composite type</a>
 612    or <a href="#format_subprograms">subprogram</a>.  The type of the member is
 613    the <a href="#format_derived_type">derived
 614    type</a>. <tt>DW_TAG_formal_parameter</tt> is used to define a member which
 615    is a formal argument of a subprogram.</p>
 616
 617 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p>
 618
 619 <p><tt>DW_TAG_pointer_type</tt>, <tt>DW_TAG_reference_type</tt>,
 620    <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt> and
 621    <tt>DW_TAG_restrict_type</tt> are used to qualify
 622    the <a href="#format_derived_type">derived type</a>. </p>
 623
 624 <p><a href="#format_derived_type">Derived type</a> location can be determined
 625    from the context and line number.  The size, alignment and offset are
 626    expressed in bits and can be 64 bit values.  The alignment is used to round
 627    the offset when embedded in a <a href="#format_composite_type">composite
 628    type</a> (example to keep float doubles on 64 bit boundaries.) The offset is
 629    the bit offset if embedded in a <a href="#format_composite_type">composite
 630    type</a>.</p>
 631
 632 <p>Note that the <tt>void *</tt> type is expressed as a type derived from NULL.
 633 </p>
 634
 635 </div>
 636
 637 <!-- ======================================================================= -->
 638 <h4>
 639   <a name="format_composite_type">Composite type descriptors</a>
 640 </h4>
 641
 642 <div>
 643
 644 <div class="doc_code">
 645 <pre>
 646 !6 = metadata !{
 647   i32,      ;; Tag (see below)
 648   metadata, ;; Reference to context
 649   metadata, ;; Name (may be "" for anonymous types)
 650   metadata, ;; Reference to file where defined (may be NULL)
 651   i32,      ;; Line number where defined (may be 0)
 652   i64,      ;; Size in bits
 653   i64,      ;; Alignment in bits
 654   i64,      ;; Offset in bits
 655   i32,      ;; Flags
 656   metadata, ;; Reference to type derived from
 657   metadata, ;; Reference to array of member descriptors
 658   i32       ;; Runtime languages
 659 }
 660 </pre>
 661 </div>
 662
 663 <p>These descriptors are used to define types that are composed of 0 or more
 664 elements.  The value of the tag varies depending on the meaning.  The following
 665 are possible tag values:</p>
 666
 667 <div class="doc_code">
 668 <pre>
 669 DW_TAG_array_type       = 1
 670 DW_TAG_enumeration_type = 4
 671 DW_TAG_structure_type   = 19
 672 DW_TAG_union_type       = 23
 673 DW_TAG_vector_type      = 259
 674 DW_TAG_subroutine_type  = 21
 675 DW_TAG_inheritance      = 28
 676 </pre>
 677 </div>
 678
 679 <p>The vector flag indicates that an array type is a native packed vector.</p>
 680
 681 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
 682    (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
 683    descriptors</a>, each representing the range of subscripts at that level of
 684    indexing.</p>
 685
 686 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
 687    <a href="#format_enumeration">enumerator descriptors</a>, each representing
 688    the definition of enumeration value for the set. All enumeration type
 689    descriptors are collected by named metadata <tt>!llvm.dbg.enum</tt>.</p>
 690
 691 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
 692    = <tt>DW_TAG_union_type</tt>) types are any one of
 693    the <a href="#format_basic_type">basic</a>,
 694    <a href="#format_derived_type">derived</a>
 695    or <a href="#format_composite_type">composite</a> type descriptors, each
 696    representing a field member of the structure or union.</p>
 697
 698 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
 699    provide information about base classes, static members and member
 700    functions. If a member is a <a href="#format_derived_type">derived type
 701    descriptor</a> and has a tag of <tt>DW_TAG_inheritance</tt>, then the type
 702    represents a base class. If the member of is
 703    a <a href="#format_global_variables">global variable descriptor</a> then it
 704    represents a static member.  And, if the member is
 705    a <a href="#format_subprograms">subprogram descriptor</a> then it represents
 706    a member function.  For static members and member
 707    functions, <tt>getName()</tt> returns the members link or the C++ mangled
 708    name.  <tt>getDisplayName()</tt> the simplied version of the name.</p>
 709
 710 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>) type
 711    elements is the return type for the subroutine.  The remaining elements are
 712    the formal arguments to the subroutine.</p>
 713
 714 <p><a href="#format_composite_type">Composite type</a> location can be
 715    determined from the context and line number.  The size, alignment and
 716    offset are expressed in bits and can be 64 bit values.  The alignment is used
 717    to round the offset when embedded in
 718    a <a href="#format_composite_type">composite type</a> (as an example, to keep
 719    float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
 720    in a <a href="#format_composite_type">composite type</a>.</p>
 721
 722 </div>
 723
 724 <!-- ======================================================================= -->
 725 <h4>
 726   <a name="format_subrange">Subrange descriptors</a>
 727 </h4>
 728
 729 <div>
 730
 731 <div class="doc_code">
 732 <pre>
 733 !42 = metadata !{
 734   i32,    ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
 735   i64,    ;; Low value
 736   i64     ;; High value
 737 }
 738 </pre>
 739 </div>
 740
 741 <p>These descriptors are used to define ranges of array subscripts for an array
 742    <a href="#format_composite_type">composite type</a>.  The low value defines
 743    the lower bounds typically zero for C/C++.  The high value is the upper
 744    bounds.  Values are 64 bit.  High - low + 1 is the size of the array.  If low
 745    > high the array bounds are not included in generated debugging information.
 746 </p>
 747
 748 </div>
 749
 750 <!-- ======================================================================= -->
 751 <h4>
 752   <a name="format_enumeration">Enumerator descriptors</a>
 753 </h4>
 754
 755 <div>
 756
 757 <div class="doc_code">
 758 <pre>
 759 !6 = metadata !{
 760   i32,      ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 761             ;; (DW_TAG_enumerator)
 762   metadata, ;; Name
 763   i64       ;; Value
 764 }
 765 </pre>
 766 </div>
 767
 768 <p>These descriptors are used to define members of an
 769    enumeration <a href="#format_composite_type">composite type</a>, it
 770    associates the name to the value.</p>
 771
 772 </div>
 773
 774 <!-- ======================================================================= -->
 775 <h4>
 776   <a name="format_variables">Local variables</a>
 777 </h4>
 778
 779 <div>
 780
 781 <div class="doc_code">
 782 <pre>
 783 !7 = metadata !{
 784   i32,      ;; Tag (see below)
 785   metadata, ;; Context
 786   metadata, ;; Name
 787   metadata, ;; Reference to file where defined
 788   i32,      ;; 24 bit - Line number where defined
 789             ;; 8 bit - Argument number. 1 indicates 1st argument.
 790   metadata, ;; Type descriptor
 791   i32,      ;; flags
 792   metadata  ;; (optional) Reference to inline location
 793 }
 794 </pre>
 795 </div>
 796
 797 <p>These descriptors are used to define variables local to a sub program.  The
 798    value of the tag depends on the usage of the variable:</p>
 799
 800 <div class="doc_code">
 801 <pre>
 802 DW_TAG_auto_variable   = 256
 803 DW_TAG_arg_variable    = 257
 804 DW_TAG_return_variable = 258
 805 </pre>
 806 </div>
 807
 808 <p>An auto variable is any variable declared in the body of the function.  An
 809    argument variable is any variable that appears as a formal argument to the
 810    function.  A return variable is used to track the result of a function and
 811    has no source correspondent.</p>
 812
 813 <p>The context is either the subprogram or block where the variable is defined.
 814    Name the source variable name.  Context and line indicate where the
 815    variable was defined. Type descriptor defines the declared type of the
 816    variable.</p>
 817
 818 </div>
 819
 820 </div>
 821
 822 <!-- ======================================================================= -->
 823 <h3>
 824   <a name="format_common_intrinsics">Debugger intrinsic functions</a>
 825 </h3>
 826
 827 <div>
 828
 829 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
 830    provide debug information at various points in generated code.</p>
 831
 832 <!-- ======================================================================= -->
 833 <h4>
 834   <a name="format_common_declare">llvm.dbg.declare</a>
 835 </h4>
 836
 837 <div>
 838 <pre>
 839   void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata)
 840 </pre>
 841
 842 <p>This intrinsic provides information about a local element (e.g., variable). The
 843    first argument is metadata holding the alloca for the variable. The
 844    second argument is metadata containing a description of the variable.</p>
 845 </div>
 846
 847 <!-- ======================================================================= -->
 848 <h4>
 849   <a name="format_common_value">llvm.dbg.value</a>
 850 </h4>
 851
 852 <div>
 853 <pre>
 854   void %<a href="#format_common_value">llvm.dbg.value</a>(metadata, i64, metadata)
 855 </pre>
 856
 857 <p>This intrinsic provides information when a user source variable is set to a
 858    new value.  The first argument is the new value (wrapped as metadata).  The
 859    second argument is the offset in the user source variable where the new value
 860    is written.  The third argument is metadata containing a description of the
 861    user source variable.</p>
 862 </div>
 863
 864 </div>
 865
 866 <!-- ======================================================================= -->
 867 <h3>
 868   <a name="format_common_lifetime">Object lifetimes and scoping</a>
 869 </h3>
 870
 871 <div>
 872 <p>In many languages, the local variables in functions can have their lifetimes
 873    or scopes limited to a subset of a function.  In the C family of languages,
 874    for example, variables are only live (readable and writable) within the
 875    source block that they are defined in.  In functional languages, values are
 876    only readable after they have been defined.  Though this is a very obvious
 877    concept, it is non-trivial to model in LLVM, because it has no notion of
 878    scoping in this sense, and does not want to be tied to a language's scoping
 879    rules.</p>
 880
 881 <p>In order to handle this, the LLVM debug format uses the metadata attached to
 882    llvm instructions to encode line number and scoping information. Consider
 883    the following C fragment, for example:</p>
 884
 885 <div class="doc_code">
 886 <pre>
 887 1.  void foo() {
 888 2.    int X = 21;
 889 3.    int Y = 22;
 890 4.    {
 891 5.      int Z = 23;
 892 6.      Z = X;
 893 7.    }
 894 8.    X = Y;
 895 9.  }
 896 </pre>
 897 </div>
 898
 899 <p>Compiled to LLVM, this function would be represented like this:</p>
 900
 901 <div class="doc_code">
 902 <pre>
 903 define void @foo() nounwind ssp {
 904 entry:
 905   %X = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 906   %Y = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 907   %Z = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=3]
 908   %0 = bitcast i32* %X to {}*                     ; &lt;{}*&gt; [#uses=1]
 909   call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7
 910   store i32 21, i32* %X, !dbg !8
 911   %1 = bitcast i32* %Y to {}*                     ; &lt;{}*&gt; [#uses=1]
 912   call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10
 913   store i32 22, i32* %Y, !dbg !11
 914   %2 = bitcast i32* %Z to {}*                     ; &lt;{}*&gt; [#uses=1]
 915   call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14
 916   store i32 23, i32* %Z, !dbg !15
 917   %tmp = load i32* %X, !dbg !16                   ; &lt;i32&gt; [#uses=1]
 918   %tmp1 = load i32* %Y, !dbg !16                  ; &lt;i32&gt; [#uses=1]
 919   %add = add nsw i32 %tmp, %tmp1, !dbg !16        ; &lt;i32&gt; [#uses=1]
 920   store i32 %add, i32* %Z, !dbg !16
 921   %tmp2 = load i32* %Y, !dbg !17                  ; &lt;i32&gt; [#uses=1]
 922   store i32 %tmp2, i32* %X, !dbg !17
 923   ret void, !dbg !18
 924 }
 925
 926 declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone
 927
 928 !0 = metadata !{i32 459008, metadata !1, metadata !"X",
 929                 metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
 930 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 931 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
 932                metadata !"foo", metadata !3, i32 1, metadata !4,
 933                i1 false, i1 true}; [DW_TAG_subprogram ]
 934 !3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
 935                 metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
 936                 i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
 937 !4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
 938                 i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
 939 !5 = metadata !{null}
 940 !6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
 941                 i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
 942 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 943 !8 = metadata !{i32 2, i32 3, metadata !1, null}
 944 !9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
 945                 metadata !6}; [ DW_TAG_auto_variable ]
 946 !10 = metadata !{i32 3, i32 7, metadata !1, null}
 947 !11 = metadata !{i32 3, i32 3, metadata !1, null}
 948 !12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
 949                  metadata !6}; [ DW_TAG_auto_variable ]
 950 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 951 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 952 !15 = metadata !{i32 5, i32 5, metadata !13, null}
 953 !16 = metadata !{i32 6, i32 5, metadata !13, null}
 954 !17 = metadata !{i32 8, i32 3, metadata !1, null}
 955 !18 = metadata !{i32 9, i32 1, metadata !2, null}
 956 </pre>
 957 </div>
 958
 959 <p>This example illustrates a few important details about LLVM debugging
 960    information. In particular, it shows how the <tt>llvm.dbg.declare</tt>
 961    intrinsic and location information, which are attached to an instruction,
 962    are applied together to allow a debugger to analyze the relationship between
 963    statements, variable definitions, and the code used to implement the
 964    function.</p>
 965
 966 <div class="doc_code">
 967 <pre>
 968 call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7
 969 </pre>
 970 </div>
 971
 972 <p>The first intrinsic
 973    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 974    encodes debugging information for the variable <tt>X</tt>. The metadata
 975    <tt>!dbg !7</tt> attached to the intrinsic provides scope information for the
 976    variable <tt>X</tt>.</p>
 977
 978 <div class="doc_code">
 979 <pre>
 980 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 981 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 982 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
 983                 metadata !"foo", metadata !"foo", metadata !3, i32 1,
 984                 metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
 985 </pre>
 986 </div>
 987
 988 <p>Here <tt>!7</tt> is metadata providing location information. It has four
 989    fields: line number, column number, scope, and original scope. The original
 990    scope represents inline location if this instruction is inlined inside a
 991    caller, and is null otherwise. In this example, scope is encoded by
 992    <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
 993    <tt>!2</tt>, where <tt>!2</tt> is a
 994    <a href="#format_subprograms">subprogram descriptor</a>. This way the
 995    location information attached to the intrinsics indicates that the
 996    variable <tt>X</tt> is declared at line number 2 at a function level scope in
 997    function <tt>foo</tt>.</p>
 998
 999 <p>Now lets take another example.</p>
1000
1001 <div class="doc_code">
1002 <pre>
1003 call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
1004 </pre>
1005 </div>
1006
1007 <p>The second intrinsic
1008    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
1009    encodes debugging information for variable <tt>Z</tt>. The metadata
1010    <tt>!dbg !14</tt> attached to the intrinsic provides scope information for
1011    the variable <tt>Z</tt>.</p>
1012
1013 <div class="doc_code">
1014 <pre>
1015 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
1016 !14 = metadata !{i32 5, i32 9, metadata !13, null}
1017 </pre>
1018 </div>
1019
1020 <p>Here <tt>!14</tt> indicates that <tt>Z</tt> is declared at line number 5 and
1021    column number 9 inside of lexical scope <tt>!13</tt>. The lexical scope
1022    itself resides inside of lexical scope <tt>!1</tt> described above.</p>
1023
1024 <p>The scope information attached with each instruction provides a
1025    straightforward way to find instructions covered by a scope.</p>
1026
1027 </div>
1028
1029 </div>
1030
1031 <!-- *********************************************************************** -->
1032 <h2>
1033   <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
1034 </h2>
1035 <!-- *********************************************************************** -->
1036
1037 <div>
1038
1039 <p>The C and C++ front-ends represent information about the program in a format
1040    that is effectively identical
1041    to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
1042    terms of information content.  This allows code generators to trivially
1043    support native debuggers by generating standard dwarf information, and
1044    contains enough information for non-dwarf targets to translate it as
1045    needed.</p>
1046
1047 <p>This section describes the forms used to represent C and C++ programs. Other
1048    languages could pattern themselves after this (which itself is tuned to
1049    representing programs in the same way that DWARF 3 does), or they could
1050    choose to provide completely different forms if they don't fit into the DWARF
1051    model.  As support for debugging information gets added to the various LLVM
1052    source-language front-ends, the information used should be documented
1053    here.</p>
1054
1055 <p>The following sections provide examples of various C/C++ constructs and the
1056    debug information that would best describe those constructs.</p>
1057
1058 <!-- ======================================================================= -->
1059 <h3>
1060   <a name="ccxx_compile_units">C/C++ source file information</a>
1061 </h3>
1062
1063 <div>
1064
1065 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
1066    in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
1067
1068 <div class="doc_code">
1069 <pre>
1070 #include "MyHeader.h"
1071
1072 int main(int argc, char *argv[]) {
1073   return 0;
1074 }
1075 </pre>
1076 </div>
1077
1078 <p>a C/C++ front-end would generate the following descriptors:</p>
1079
1080 <div class="doc_code">
1081 <pre>
1082 ...
1083 ;;
1084 ;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
1085 ;;
1086 !2 = metadata !{
1087   i32 524305,    ;; Tag
1088   i32 0,         ;; Unused
1089   i32 4,         ;; Language Id
1090   metadata !"MySource.cpp",
1091   metadata !"/Users/mine/sources",
1092   metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1093   i1 true,       ;; Main Compile Unit
1094   i1 false,      ;; Optimized compile unit
1095   metadata !"",  ;; Compiler flags
1096   i32 0}         ;; Runtime version
1097
1098 ;;
1099 ;; Define the file for the file "/Users/mine/sources/MySource.cpp".
1100 ;;
1101 !1 = metadata !{
1102   i32 524329,    ;; Tag
1103   metadata !"MySource.cpp",
1104   metadata !"/Users/mine/sources",
1105   metadata !2    ;; Compile unit
1106 }
1107
1108 ;;
1109 ;; Define the file for the file "/Users/mine/sources/Myheader.h"
1110 ;;
1111 !3 = metadata !{
1112   i32 524329,    ;; Tag
1113   metadata !"Myheader.h"
1114   metadata !"/Users/mine/sources",
1115   metadata !2    ;; Compile unit
1116 }
1117
1118 ...
1119 </pre>
1120 </div>
1121
1122 <p>llvm::Instruction provides easy access to metadata attached with an
1123 instruction. One can extract line number information encoded in LLVM IR
1124 using <tt>Instruction::getMetadata()</tt> and
1125 <tt>DILocation::getLineNumber()</tt>.
1126 <pre>
1127  if (MDNode *N = I->getMetadata("dbg")) {  // Here I is an LLVM instruction
1128    DILocation Loc(N);                      // DILocation is in DebugInfo.h
1129    unsigned Line = Loc.getLineNumber();
1130    StringRef File = Loc.getFilename();
1131    StringRef Dir = Loc.getDirectory();
1132  }
1133 </pre>
1134 </div>
1135
1136 <!-- ======================================================================= -->
1137 <h3>
1138   <a name="ccxx_global_variable">C/C++ global variable information</a>
1139 </h3>
1140
1141 <div>
1142
1143 <p>Given an integer global variable declared as follows:</p>
1144
1145 <div class="doc_code">
1146 <pre>
1147 int MyGlobal = 100;
1148 </pre>
1149 </div>
1150
1151 <p>a C/C++ front-end would generate the following descriptors:</p>
1152
1153 <div class="doc_code">
1154 <pre>
1155 ;;
1156 ;; Define the global itself.
1157 ;;
1158 %MyGlobal = global int 100
1159 ...
1160 ;;
1161 ;; List of debug info of globals
1162 ;;
1163 !llvm.dbg.gv = !{!0}
1164
1165 ;;
1166 ;; Define the global variable descriptor.  Note the reference to the global
1167 ;; variable anchor and the global variable itself.
1168 ;;
1169 !0 = metadata !{
1170   i32 524340,              ;; Tag
1171   i32 0,                   ;; Unused
1172   metadata !1,             ;; Context
1173   metadata !"MyGlobal",    ;; Name
1174   metadata !"MyGlobal",    ;; Display Name
1175   metadata !"MyGlobal",    ;; Linkage Name
1176   metadata !3,             ;; Compile Unit
1177   i32 1,                   ;; Line Number
1178   metadata !4,             ;; Type
1179   i1 false,                ;; Is a local variable
1180   i1 true,                 ;; Is this a definition
1181   i32* @MyGlobal           ;; The global variable
1182 }
1183
1184 ;;
1185 ;; Define the basic type of 32 bit signed integer.  Note that since int is an
1186 ;; intrinsic type the source file is NULL and line 0.
1187 ;;
1188 !4 = metadata !{
1189   i32 524324,              ;; Tag
1190   metadata !1,             ;; Context
1191   metadata !"int",         ;; Name
1192   metadata !1,             ;; File
1193   i32 0,                   ;; Line number
1194   i64 32,                  ;; Size in Bits
1195   i64 32,                  ;; Align in Bits
1196   i64 0,                   ;; Offset in Bits
1197   i32 0,                   ;; Flags
1198   i32 5                    ;; Encoding
1199 }
1200
1201 </pre>
1202 </div>
1203
1204 </div>
1205
1206 <!-- ======================================================================= -->
1207 <h3>
1208   <a name="ccxx_subprogram">C/C++ function information</a>
1209 </h3>
1210
1211 <div>
1212
1213 <p>Given a function declared as follows:</p>
1214
1215 <div class="doc_code">
1216 <pre>
1217 int main(int argc, char *argv[]) {
1218   return 0;
1219 }
1220 </pre>
1221 </div>
1222
1223 <p>a C/C++ front-end would generate the following descriptors:</p>
1224
1225 <div class="doc_code">
1226 <pre>
1227 ;;
1228 ;; Define the anchor for subprograms.  Note that the second field of the
1229 ;; anchor is 46, which is the same as the tag for subprograms
1230 ;; (46 = DW_TAG_subprogram.)
1231 ;;
1232 !6 = metadata !{
1233   i32 524334,        ;; Tag
1234   i32 0,             ;; Unused
1235   metadata !1,       ;; Context
1236   metadata !"main",  ;; Name
1237   metadata !"main",  ;; Display name
1238   metadata !"main",  ;; Linkage name
1239   metadata !1,       ;; File
1240   i32 1,             ;; Line number
1241   metadata !4,       ;; Type
1242   i1 false,          ;; Is local
1243   i1 true,           ;; Is definition
1244   i32 0,             ;; Virtuality attribute, e.g. pure virtual function
1245   i32 0,             ;; Index into virtual table for C++ methods
1246   i32 0,             ;; Type that holds virtual table.
1247   i32 0,             ;; Flags
1248   i1 false,          ;; True if this function is optimized
1249   Function *,        ;; Pointer to llvm::Function
1250   null               ;; Function template parameters
1251 }
1252 ;;
1253 ;; Define the subprogram itself.
1254 ;;
1255 define i32 @main(i32 %argc, i8** %argv) {
1256 ...
1257 }
1258 </pre>
1259 </div>
1260
1261 </div>
1262
1263 <!-- ======================================================================= -->
1264 <h3>
1265   <a name="ccxx_basic_types">C/C++ basic types</a>
1266 </h3>
1267
1268 <div>
1269
1270 <p>The following are the basic type descriptors for C/C++ core types:</p>
1271
1272 <!-- ======================================================================= -->
1273 <h4>
1274   <a name="ccxx_basic_type_bool">bool</a>
1275 </h4>
1276
1277 <div>
1278
1279 <div class="doc_code">
1280 <pre>
1281 !2 = metadata !{
1282   i32 524324,        ;; Tag
1283   metadata !1,       ;; Context
1284   metadata !"bool",  ;; Name
1285   metadata !1,       ;; File
1286   i32 0,             ;; Line number
1287   i64 8,             ;; Size in Bits
1288   i64 8,             ;; Align in Bits
1289   i64 0,             ;; Offset in Bits
1290   i32 0,             ;; Flags
1291   i32 2              ;; Encoding
1292 }
1293 </pre>
1294 </div>
1295
1296 </div>
1297
1298 <!-- ======================================================================= -->
1299 <h4>
1300   <a name="ccxx_basic_char">char</a>
1301 </h4>
1302
1303 <div>
1304
1305 <div class="doc_code">
1306 <pre>
1307 !2 = metadata !{
1308   i32 524324,        ;; Tag
1309   metadata !1,       ;; Context
1310   metadata !"char",  ;; Name
1311   metadata !1,       ;; File
1312   i32 0,             ;; Line number
1313   i64 8,             ;; Size in Bits
1314   i64 8,             ;; Align in Bits
1315   i64 0,             ;; Offset in Bits
1316   i32 0,             ;; Flags
1317   i32 6              ;; Encoding
1318 }
1319 </pre>
1320 </div>
1321
1322 </div>
1323
1324 <!-- ======================================================================= -->
1325 <h4>
1326   <a name="ccxx_basic_unsigned_char">unsigned char</a>
1327 </h4>
1328
1329 <div>
1330
1331 <div class="doc_code">
1332 <pre>
1333 !2 = metadata !{
1334   i32 524324,        ;; Tag
1335   metadata !1,       ;; Context
1336   metadata !"unsigned char",
1337   metadata !1,       ;; File
1338   i32 0,             ;; Line number
1339   i64 8,             ;; Size in Bits
1340   i64 8,             ;; Align in Bits
1341   i64 0,             ;; Offset in Bits
1342   i32 0,             ;; Flags
1343   i32 8              ;; Encoding
1344 }
1345 </pre>
1346 </div>
1347
1348 </div>
1349
1350 <!-- ======================================================================= -->
1351 <h4>
1352   <a name="ccxx_basic_short">short</a>
1353 </h4>
1354
1355 <div>
1356
1357 <div class="doc_code">
1358 <pre>
1359 !2 = metadata !{
1360   i32 524324,        ;; Tag
1361   metadata !1,       ;; Context
1362   metadata !"short int",
1363   metadata !1,       ;; File
1364   i32 0,             ;; Line number
1365   i64 16,            ;; Size in Bits
1366   i64 16,            ;; Align in Bits
1367   i64 0,             ;; Offset in Bits
1368   i32 0,             ;; Flags
1369   i32 5              ;; Encoding
1370 }
1371 </pre>
1372 </div>
1373
1374 </div>
1375
1376 <!-- ======================================================================= -->
1377 <h4>
1378   <a name="ccxx_basic_unsigned_short">unsigned short</a>
1379 </h4>
1380
1381 <div>
1382
1383 <div class="doc_code">
1384 <pre>
1385 !2 = metadata !{
1386   i32 524324,        ;; Tag
1387   metadata !1,       ;; Context
1388   metadata !"short unsigned int",
1389   metadata !1,       ;; File
1390   i32 0,             ;; Line number
1391   i64 16,            ;; Size in Bits
1392   i64 16,            ;; Align in Bits
1393   i64 0,             ;; Offset in Bits
1394   i32 0,             ;; Flags
1395   i32 7              ;; Encoding
1396 }
1397 </pre>
1398 </div>
1399
1400 </div>
1401
1402 <!-- ======================================================================= -->
1403 <h4>
1404   <a name="ccxx_basic_int">int</a>
1405 </h4>
1406
1407 <div>
1408
1409 <div class="doc_code">
1410 <pre>
1411 !2 = metadata !{
1412   i32 524324,        ;; Tag
1413   metadata !1,       ;; Context
1414   metadata !"int",   ;; Name
1415   metadata !1,       ;; File
1416   i32 0,             ;; Line number
1417   i64 32,            ;; Size in Bits
1418   i64 32,            ;; Align in Bits
1419   i64 0,             ;; Offset in Bits
1420   i32 0,             ;; Flags
1421   i32 5              ;; Encoding
1422 }
1423 </pre></div>
1424
1425 </div>
1426
1427 <!-- ======================================================================= -->
1428 <h4>
1429   <a name="ccxx_basic_unsigned_int">unsigned int</a>
1430 </h4>
1431
1432 <div>
1433
1434 <div class="doc_code">
1435 <pre>
1436 !2 = metadata !{
1437   i32 524324,        ;; Tag
1438   metadata !1,       ;; Context
1439   metadata !"unsigned int",
1440   metadata !1,       ;; File
1441   i32 0,             ;; Line number
1442   i64 32,            ;; Size in Bits
1443   i64 32,            ;; Align in Bits
1444   i64 0,             ;; Offset in Bits
1445   i32 0,             ;; Flags
1446   i32 7              ;; Encoding
1447 }
1448 </pre>
1449 </div>
1450
1451 </div>
1452
1453 <!-- ======================================================================= -->
1454 <h4>
1455   <a name="ccxx_basic_long_long">long long</a>
1456 </h4>
1457
1458 <div>
1459
1460 <div class="doc_code">
1461 <pre>
1462 !2 = metadata !{
1463   i32 524324,        ;; Tag
1464   metadata !1,       ;; Context
1465   metadata !"long long int",
1466   metadata !1,       ;; File
1467   i32 0,             ;; Line number
1468   i64 64,            ;; Size in Bits
1469   i64 64,            ;; Align in Bits
1470   i64 0,             ;; Offset in Bits
1471   i32 0,             ;; Flags
1472   i32 5              ;; Encoding
1473 }
1474 </pre>
1475 </div>
1476
1477 </div>
1478
1479 <!-- ======================================================================= -->
1480 <h4>
1481   <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1482 </h4>
1483
1484 <div>
1485
1486 <div class="doc_code">
1487 <pre>
1488 !2 = metadata !{
1489   i32 524324,        ;; Tag
1490   metadata !1,       ;; Context
1491   metadata !"long long unsigned int",
1492   metadata !1,       ;; File
1493   i32 0,             ;; Line number
1494   i64 64,            ;; Size in Bits
1495   i64 64,            ;; Align in Bits
1496   i64 0,             ;; Offset in Bits
1497   i32 0,             ;; Flags
1498   i32 7              ;; Encoding
1499 }
1500 </pre>
1501 </div>
1502
1503 </div>
1504
1505 <!-- ======================================================================= -->
1506 <h4>
1507   <a name="ccxx_basic_float">float</a>
1508 </h4>
1509
1510 <div>
1511
1512 <div class="doc_code">
1513 <pre>
1514 !2 = metadata !{
1515   i32 524324,        ;; Tag
1516   metadata !1,       ;; Context
1517   metadata !"float",
1518   metadata !1,       ;; File
1519   i32 0,             ;; Line number
1520   i64 32,            ;; Size in Bits
1521   i64 32,            ;; Align in Bits
1522   i64 0,             ;; Offset in Bits
1523   i32 0,             ;; Flags
1524   i32 4              ;; Encoding
1525 }
1526 </pre>
1527 </div>
1528
1529 </div>
1530
1531 <!-- ======================================================================= -->
1532 <h4>
1533   <a name="ccxx_basic_double">double</a>
1534 </h4>
1535
1536 <div>
1537
1538 <div class="doc_code">
1539 <pre>
1540 !2 = metadata !{
1541   i32 524324,        ;; Tag
1542   metadata !1,       ;; Context
1543   metadata !"double",;; Name
1544   metadata !1,       ;; File
1545   i32 0,             ;; Line number
1546   i64 64,            ;; Size in Bits
1547   i64 64,            ;; Align in Bits
1548   i64 0,             ;; Offset in Bits
1549   i32 0,             ;; Flags
1550   i32 4              ;; Encoding
1551 }
1552 </pre>
1553 </div>
1554
1555 </div>
1556
1557 </div>
1558
1559 <!-- ======================================================================= -->
1560 <h3>
1561   <a name="ccxx_derived_types">C/C++ derived types</a>
1562 </h3>
1563
1564 <div>
1565
1566 <p>Given the following as an example of C/C++ derived type:</p>
1567
1568 <div class="doc_code">
1569 <pre>
1570 typedef const int *IntPtr;
1571 </pre>
1572 </div>
1573
1574 <p>a C/C++ front-end would generate the following descriptors:</p>
1575
1576 <div class="doc_code">
1577 <pre>
1578 ;;
1579 ;; Define the typedef "IntPtr".
1580 ;;
1581 !2 = metadata !{
1582   i32 524310,          ;; Tag
1583   metadata !1,         ;; Context
1584   metadata !"IntPtr",  ;; Name
1585   metadata !3,         ;; File
1586   i32 0,               ;; Line number
1587   i64 0,               ;; Size in bits
1588   i64 0,               ;; Align in bits
1589   i64 0,               ;; Offset in bits
1590   i32 0,               ;; Flags
1591   metadata !4          ;; Derived From type
1592 }
1593
1594 ;;
1595 ;; Define the pointer type.
1596 ;;
1597 !4 = metadata !{
1598   i32 524303,          ;; Tag
1599   metadata !1,         ;; Context
1600   metadata !"",        ;; Name
1601   metadata !1,         ;; File
1602   i32 0,               ;; Line number
1603   i64 64,              ;; Size in bits
1604   i64 64,              ;; Align in bits
1605   i64 0,               ;; Offset in bits
1606   i32 0,               ;; Flags
1607   metadata !5          ;; Derived From type
1608 }
1609 ;;
1610 ;; Define the const type.
1611 ;;
1612 !5 = metadata !{
1613   i32 524326,          ;; Tag
1614   metadata !1,         ;; Context
1615   metadata !"",        ;; Name
1616   metadata !1,         ;; File
1617   i32 0,               ;; Line number
1618   i64 32,              ;; Size in bits
1619   i64 32,              ;; Align in bits
1620   i64 0,               ;; Offset in bits
1621   i32 0,               ;; Flags
1622   metadata !6          ;; Derived From type
1623 }
1624 ;;
1625 ;; Define the int type.
1626 ;;
1627 !6 = metadata !{
1628   i32 524324,          ;; Tag
1629   metadata !1,         ;; Context
1630   metadata !"int",     ;; Name
1631   metadata !1,         ;; File
1632   i32 0,               ;; Line number
1633   i64 32,              ;; Size in bits
1634   i64 32,              ;; Align in bits
1635   i64 0,               ;; Offset in bits
1636   i32 0,               ;; Flags
1637   5                    ;; Encoding
1638 }
1639 </pre>
1640 </div>
1641
1642 </div>
1643
1644 <!-- ======================================================================= -->
1645 <h3>
1646   <a name="ccxx_composite_types">C/C++ struct/union types</a>
1647 </h3>
1648
1649 <div>
1650
1651 <p>Given the following as an example of C/C++ struct type:</p>
1652
1653 <div class="doc_code">
1654 <pre>
1655 struct Color {
1656   unsigned Red;
1657   unsigned Green;
1658   unsigned Blue;
1659 };
1660 </pre>
1661 </div>
1662
1663 <p>a C/C++ front-end would generate the following descriptors:</p>
1664
1665 <div class="doc_code">
1666 <pre>
1667 ;;
1668 ;; Define basic type for unsigned int.
1669 ;;
1670 !5 = metadata !{
1671   i32 524324,        ;; Tag
1672   metadata !1,       ;; Context
1673   metadata !"unsigned int",
1674   metadata !1,       ;; File
1675   i32 0,             ;; Line number
1676   i64 32,            ;; Size in Bits
1677   i64 32,            ;; Align in Bits
1678   i64 0,             ;; Offset in Bits
1679   i32 0,             ;; Flags
1680   i32 7              ;; Encoding
1681 }
1682 ;;
1683 ;; Define composite type for struct Color.
1684 ;;
1685 !2 = metadata !{
1686   i32 524307,        ;; Tag
1687   metadata !1,       ;; Context
1688   metadata !"Color", ;; Name
1689   metadata !1,       ;; Compile unit
1690   i32 1,             ;; Line number
1691   i64 96,            ;; Size in bits
1692   i64 32,            ;; Align in bits
1693   i64 0,             ;; Offset in bits
1694   i32 0,             ;; Flags
1695   null,              ;; Derived From
1696   metadata !3,       ;; Elements
1697   i32 0              ;; Runtime Language
1698 }
1699
1700 ;;
1701 ;; Define the Red field.
1702 ;;
1703 !4 = metadata !{
1704   i32 524301,        ;; Tag
1705   metadata !1,       ;; Context
1706   metadata !"Red",   ;; Name
1707   metadata !1,       ;; File
1708   i32 2,             ;; Line number
1709   i64 32,            ;; Size in bits
1710   i64 32,            ;; Align in bits
1711   i64 0,             ;; Offset in bits
1712   i32 0,             ;; Flags
1713   metadata !5        ;; Derived From type
1714 }
1715
1716 ;;
1717 ;; Define the Green field.
1718 ;;
1719 !6 = metadata !{
1720   i32 524301,        ;; Tag
1721   metadata !1,       ;; Context
1722   metadata !"Green", ;; Name
1723   metadata !1,       ;; File
1724   i32 3,             ;; Line number
1725   i64 32,            ;; Size in bits
1726   i64 32,            ;; Align in bits
1727   i64 32,             ;; Offset in bits
1728   i32 0,             ;; Flags
1729   metadata !5        ;; Derived From type
1730 }
1731
1732 ;;
1733 ;; Define the Blue field.
1734 ;;
1735 !7 = metadata !{
1736   i32 524301,        ;; Tag
1737   metadata !1,       ;; Context
1738   metadata !"Blue",  ;; Name
1739   metadata !1,       ;; File
1740   i32 4,             ;; Line number
1741   i64 32,            ;; Size in bits
1742   i64 32,            ;; Align in bits
1743   i64 64,             ;; Offset in bits
1744   i32 0,             ;; Flags
1745   metadata !5        ;; Derived From type
1746 }
1747
1748 ;;
1749 ;; Define the array of fields used by the composite type Color.
1750 ;;
1751 !3 = metadata !{metadata !4, metadata !6, metadata !7}
1752 </pre>
1753 </div>
1754
1755 </div>
1756
1757 <!-- ======================================================================= -->
1758 <h3>
1759   <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1760 </h3>
1761
1762 <div>
1763
1764 <p>Given the following as an example of C/C++ enumeration type:</p>
1765
1766 <div class="doc_code">
1767 <pre>
1768 enum Trees {
1769   Spruce = 100,
1770   Oak = 200,
1771   Maple = 300
1772 };
1773 </pre>
1774 </div>
1775
1776 <p>a C/C++ front-end would generate the following descriptors:</p>
1777
1778 <div class="doc_code">
1779 <pre>
1780 ;;
1781 ;; Define composite type for enum Trees
1782 ;;
1783 !2 = metadata !{
1784   i32 524292,        ;; Tag
1785   metadata !1,       ;; Context
1786   metadata !"Trees", ;; Name
1787   metadata !1,       ;; File
1788   i32 1,             ;; Line number
1789   i64 32,            ;; Size in bits
1790   i64 32,            ;; Align in bits
1791   i64 0,             ;; Offset in bits
1792   i32 0,             ;; Flags
1793   null,              ;; Derived From type
1794   metadata !3,       ;; Elements
1795   i32 0              ;; Runtime language
1796 }
1797
1798 ;;
1799 ;; Define the array of enumerators used by composite type Trees.
1800 ;;
1801 !3 = metadata !{metadata !4, metadata !5, metadata !6}
1802
1803 ;;
1804 ;; Define Spruce enumerator.
1805 ;;
1806 !4 = metadata !{i32 524328, metadata !"Spruce", i64 100}
1807
1808 ;;
1809 ;; Define Oak enumerator.
1810 ;;
1811 !5 = metadata !{i32 524328, metadata !"Oak", i64 200}
1812
1813 ;;
1814 ;; Define Maple enumerator.
1815 ;;
1816 !6 = metadata !{i32 524328, metadata !"Maple", i64 300}
1817
1818 </pre>
1819 </div>
1820
1821 </div>
1822
1823 </div>
1824
1825
1826 <!-- *********************************************************************** -->
1827 <h2>
1828   <a name="llvmdwarfextension">Debugging information format</a>
1829 </h2>
1830 <!-- *********************************************************************** -->
1831 <div>
1832 <!-- ======================================================================= -->
1833 <h3>
1834   <a name="objcproperty">Debugging Information Extension for Objective C
1835 Properties</a></li>
1836 </h3>
1837 <div>
1838 <!-- *********************************************************************** -->
1839 <h4>
1840   <a name="objcpropertyintroduction">Introduction</a>
1841 </h4>
1842 <!-- *********************************************************************** -->
1843
1844 <div>
1845 <p>Objective C provides a simpler way to declare and define accessor methods
1846 using declared properties. The language provides features to declare a
1847 property and to let compiler synthesize accessor methods.
1848 </p>
1849
1850 <p>The debugger lets developer inspect Objective C interfaces and their
1851 instance variables and class variables. However, the debugger does not know
1852 anything about the properties defined in Objective C interfaces. The debugger
1853 consumes information generated by compiler in DWARF format. The format does
1854 not support encoding of Objective C properties. This proposal describes DWARF
1855 extensions to encode Objective C properties, which the debugger can use to let
1856 developers inspect Objective C properties.
1857 </p>
1858
1859 </div>
1860
1861
1862 <!-- *********************************************************************** -->
1863 <h4>
1864   <a name="objcpropertyproposal">Proposal</a>
1865 </h4>
1866 <!-- *********************************************************************** -->
1867
1868 <div>
1869 <p>Objective C properties exist separately from class members. A property
1870 can be defined only by &quot;setter&quot; and &quot;getter&quot; selectors, and
1871 be calculated anew on each access.  Or a property can just be a direct access
1872 to some declared ivar.  Finally it can have an ivar &quot;automatically
1873 synthesized&quot; for it by the compiler, in which case the property can be
1874 referred to in user code directly using the standard C dereference syntax as
1875 well as through the property &quot;dot&quot; syntax, but there is no entry in
1876 the @interface declaration corresponding to this ivar.
1877 </p>
1878 <p>
1879 To facilitate debugging, these properties we will add a new DWARF TAG into the
1880 DW_TAG_structure_type definition for the class to hold the description of a
1881 given property, and a set of DWARF attributes that provide said description.
1882 The property tag will also contain the name and declared type of the property.
1883 </p>
1884 <p>
1885 If there is a related ivar, there will also be a DWARF property attribute placed
1886 in the DW_TAG_member DIE for that ivar referring back to the property TAG for
1887 that property. And in the case where the compiler synthesizes the ivar directly,
1888 the compiler is expected to generate a DW_TAG_member for that ivar (with the
1889 DW_AT_artificial set to 1), whose name will be the name used to access this
1890 ivar directly in code, and with the property attribute pointing back to the
1891 property it is backing.
1892 </p>
1893 <p>
1894 The following examples will serve as illustration for our discussion:
1895 </p>
1896
1897 <div class="doc_code">
1898 <pre>
1899 @interface I1 {
1900   int n2;
1901 }
1902
1903 @property int p1;
1904 @property int p2;
1905 @end
1906
1907 @implementation I1
1908 @synthesize p1;
1909 @synthesize p2 = n2;
1910 @end
1911 </pre>
1912 </div>
1913
1914 <p>
1915 This produces the following DWARF (this is a &quot;pseudo dwarfdump&quot; output):
1916 </p>
1917 <div class="doc_code">
1918 <pre>
1919 0x00000100:  TAG_structure_type [7] *
1920                AT_APPLE_runtime_class( 0x10 )
1921                AT_name( "I1" )
1922                AT_decl_file( "Objc_Property.m" )
1923                AT_decl_line( 3 )
1924
1925 0x00000110    TAG_APPLE_property
1926                 AT_name ( "p1" )
1927                 AT_type ( {0x00000150} ( int ) )
1928
1929 0x00000120:   TAG_APPLE_property
1930                 AT_name ( "p2" )
1931                 AT_type ( {0x00000150} ( int ) )
1932
1933 0x00000130:   TAG_member [8]
1934                 AT_name( "_p1" )
1935                 AT_APPLE_property ( {0x00000110} "p1" )
1936                 AT_type( {0x00000150} ( int ) )
1937                 AT_artificial ( 0x1 )
1938
1939 0x00000140:    TAG_member [8]
1940                  AT_name( "n2" )
1941                  AT_APPLE_property ( {0x00000120} "p2" )
1942                  AT_type( {0x00000150} ( int ) )
1943
1944 0x00000150:  AT_type( ( int ) )
1945 </pre>
1946 </div>
1947
1948 <p> Note, the current convention is that the name of the ivar for an
1949 auto-synthesized property is the name of the property from which it derives with
1950 an underscore prepended, as is shown in the example.
1951 But we actually don't need to know this convention, since we are given the name
1952 of the ivar directly.
1953 </p>
1954
1955 <p>
1956 Also, it is common practice in ObjC to have different property declarations in
1957 the @interface and @implementation - e.g. to provide a read-only property in
1958 the interface,and a read-write interface in the implementation.  In that case,
1959 the compiler should emit whichever property declaration will be in force in the
1960 current translation unit.
1961 </p>
1962
1963 <p> Developers can decorate a property with attributes which are encoded using
1964 DW_AT_APPLE_property_attribute.
1965 </p>
1966
1967 <div class="doc_code">
1968 <pre>
1969 @property (readonly, nonatomic) int pr;
1970 </pre>
1971 </div>
1972 <p>
1973 Which produces a property tag:
1974 <p>
1975 <div class="doc_code">
1976 <pre>
1977 TAG_APPLE_property [8]
1978   AT_name( "pr" )
1979   AT_type ( {0x00000147} (int) )
1980   AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
1981 </pre>
1982 </div>
1983
1984 <p> The setter and getter method names are attached to the property using
1985 DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes.
1986 </p>
1987 <div class="doc_code">
1988 <pre>
1989 @interface I1
1990 @property (setter=myOwnP3Setter:) int p3;
1991 -(void)myOwnP3Setter:(int)a;
1992 @end
1993
1994 @implementation I1
1995 @synthesize p3;
1996 -(void)myOwnP3Setter:(int)a{ }
1997 @end
1998 </pre>
1999 </div>
2000
2001 <p>
2002 The DWARF for this would be:
2003 </p>
2004 <div class="doc_code">
2005 <pre>
2006 0x000003bd: TAG_structure_type [7] *
2007               AT_APPLE_runtime_class( 0x10 )
2008               AT_name( "I1" )
2009               AT_decl_file( "Objc_Property.m" )
2010               AT_decl_line( 3 )
2011
2012 0x000003cd      TAG_APPLE_property
2013                   AT_name ( "p3" )
2014                   AT_APPLE_property_setter ( "myOwnP3Setter:" )
2015                   AT_type( {0x00000147} ( int ) )
2016
2017 0x000003f3:     TAG_member [8]
2018                   AT_name( "_p3" )
2019                   AT_type ( {0x00000147} ( int ) )
2020                   AT_APPLE_property ( {0x000003cd} )
2021                   AT_artificial ( 0x1 )
2022 </pre>
2023 </div>
2024
2025 </div>
2026
2027 <!-- *********************************************************************** -->
2028 <h4>
2029   <a name="objcpropertynewtags">New DWARF Tags</a>
2030 </h4>
2031 <!-- *********************************************************************** -->
2032
2033 <div>
2034 <table border="1" cellspacing="0">
2035   <tr>
2036     <th width=200 >TAG</th>
2037     <th width=200 >Value</th>
2038   </tr>
2039   <tr>
2040     <td width=200 >DW_TAG_APPLE_property</td>
2041     <td width=200 >0x4200</td>
2042   </tr>
2043 </table>
2044
2045 </div>
2046
2047 <!-- *********************************************************************** -->
2048 <h4>
2049   <a name="objcpropertynewattributes">New DWARF Attributes</a>
2050 </h4>
2051 <!-- *********************************************************************** -->
2052
2053 <div>
2054 <table border="1" cellspacing="0">
2055   <tr>
2056     <th width=200 >Attribute</th>
2057     <th width=200 >Value</th>
2058     <th width=200 >Classes</th>
2059   </tr>
2060   <tr>
2061     <td width=200 >DW_AT_APPLE_property</td>
2062     <td width=200 >0x3fed</td>
2063     <td width=200 >Reference</td>
2064   </tr>
2065   <tr>
2066     <td width=200 >DW_AT_APPLE_property_getter</td>
2067     <td width=200 >0x3fe9</td>
2068     <td width=200 >String</td>
2069   </tr>
2070   <tr>
2071     <td width=200 >DW_AT_APPLE_property_setter</td>
2072     <td width=200 >0x3fea</td>
2073     <td width=200 >String</td>
2074   </tr>
2075   <tr>
2076     <td width=200 >DW_AT_APPLE_property_attribute</td>
2077     <td width=200 >0x3feb</td>
2078     <td width=200 >Constant</td>
2079   </tr>
2080 </table>
2081
2082 </div>
2083
2084 <!-- *********************************************************************** -->
2085 <h4>
2086   <a name="objcpropertynewconstants">New DWARF Constants</a>
2087 </h4>
2088 <!-- *********************************************************************** -->
2089
2090 <div>
2091 <table border="1" cellspacing="0">
2092   <tr>
2093     <th width=200 >Name</th>
2094     <th width=200 >Value</th>
2095   </tr>
2096   <tr>
2097     <td width=200 >DW_AT_APPLE_PROPERTY_readonly</td>
2098     <td width=200 >0x1</td>
2099   </tr>
2100   <tr>
2101     <td width=200 >DW_AT_APPLE_PROPERTY_readwrite</td>
2102     <td width=200 >0x2</td>
2103   </tr>
2104   <tr>
2105     <td width=200 >DW_AT_APPLE_PROPERTY_assign</td>
2106     <td width=200 >0x4</td>
2107   </tr>
2108   <tr>
2109     <td width=200 >DW_AT_APPLE_PROPERTY_retain</td>
2110     <td width=200 >0x8</td>
2111   </tr>
2112   <tr>
2113     <td width=200 >DW_AT_APPLE_PROPERTY_copy</td>
2114     <td width=200 >0x10</td>
2115   </tr>
2116   <tr>
2117     <td width=200 >DW_AT_APPLE_PROPERTY_nonatomic</td>
2118     <td width=200 >0x20</td>
2119   </tr>
2120 </table>
2121
2122 </div>
2123 </div>
2124 </div>
2125
2126 <div>
2127 <!-- ======================================================================= -->
2128 <h3>
2129   <a name="acceltable">Name Accelerator Tables</a>
2130 </h3>
2131 <!-- ======================================================================= -->
2132 <!-- ======================================================================= -->
2133 <h4>
2134   <a name="acceltableintroduction">Introduction</a>
2135 </h4>
2136 <!-- ======================================================================= -->
2137 <div>
2138 <p>The .debug_pubnames and .debug_pubtypes formats are not what a debugger
2139   needs. The "pub" in the section name indicates that the entries in the
2140   table are publicly visible names only. This means no static or hidden
2141   functions show up in the .debug_pubnames. No static variables or private class
2142   variables are in the .debug_pubtypes. Many compilers add different things to
2143   these tables, so we can't rely upon the contents between gcc, icc, or clang.
2144
2145 <p>The typical query given by users tends not to match up with the contents of
2146   these tables. For example, the DWARF spec states that "In the case of the
2147   name of a function member or static data member of a C++ structure, class or
2148   union, the name presented in the .debug_pubnames section is not the simple
2149   name given by the DW_AT_name attribute of the referenced debugging information
2150   entry, but rather the fully qualified name of the data or function member."
2151   So the only names in these tables for complex C++ entries is a fully
2152   qualified name.  Debugger users tend not to enter their search strings as
2153   "a::b::c(int,const Foo&) const", but rather as "c", "b::c" , or "a::b::c".  So
2154   the name entered in the name table must be demangled in order to chop it up
2155   appropriately and additional names must be manually entered into the table
2156   to make it effective as a name lookup table for debuggers to use.
2157
2158 <p>All debuggers currently ignore the .debug_pubnames table as a result of
2159   its inconsistent and useless public-only name content making it a waste of
2160   space in the object file. These tables, when they are written to disk, are
2161   not sorted in any way, leaving every debugger to do its own parsing
2162   and sorting. These tables also include an inlined copy of the string values
2163   in the table itself making the tables much larger than they need to be on
2164   disk, especially for large C++ programs.
2165
2166 <p>Can't we just fix the sections by adding all of the names we need to this
2167   table? No, because that is not what the tables are defined to contain and we
2168   won't know the difference between the old bad tables and the new good tables.
2169   At best we could make our own renamed sections that contain all of the data
2170   we need.
2171
2172 <p>These tables are also insufficient for what a debugger like LLDB needs.
2173   LLDB uses clang for its expression parsing where LLDB acts as a PCH. LLDB is
2174   then often asked to look for type "foo" or namespace "bar", or list items in
2175   namespace "baz". Namespaces are not included in the pubnames or pubtypes
2176   tables. Since clang asks a lot of questions when it is parsing an expression,
2177   we need to be very fast when looking up names, as it happens a lot. Having new
2178   accelerator tables that are optimized for very quick lookups will benefit
2179   this type of debugging experience greatly.
2180
2181 <p>We would like to generate name lookup tables that can be mapped into
2182   memory from disk, and used as is, with little or no up-front parsing. We would
2183   also be able to control the exact content of these different tables so they
2184   contain exactly what we need. The Name Accelerator Tables were designed
2185   to fix these issues. In order to solve these issues we need to:
2186 <ul>
2187   <li>Have a format that can be mapped into memory from disk and used as is</li>
2188   <li>Lookups should be very fast</li>
2189   <li>Extensible table format so these tables can be made by many producers</li>
2190   <li>Contain all of the names needed for typical lookups out of the box</li>
2191   <li>Strict rules for the contents of tables</li>
2192 </ul>
2193 <p>Table size is important and the accelerator table format should allow the
2194   reuse of strings from common string tables so the strings for the names are
2195   not duplicated. We also want to make sure the table is ready to be used as-is
2196   by simply mapping the table into memory with minimal header parsing.
2197
2198 <p>The name lookups need to be fast and optimized for the kinds of lookups
2199   that debuggers tend to do. Optimally we would like to touch as few parts of
2200   the mapped table as possible when doing a name lookup and be able to quickly
2201   find the name entry we are looking for, or discover there are no matches. In
2202   the case of debuggers we optimized for lookups that fail most of the time.
2203
2204 <p>Each table that is defined should have strict rules on exactly what is in
2205   the accelerator tables and documented so clients can rely on the content.
2206 </div>
2207 <!-- ======================================================================= -->
2208 <h4>
2209   <a name="acceltablehashes">Hash Tables</a>
2210 </h4>
2211 <!-- ======================================================================= -->
2212 <div>
2213 <h5>Standard Hash Tables</h5>
2214 <p>Typical hash tables have a header, buckets, and each bucket points to the
2215 bucket contents:
2216 <div class="doc_code">
2217 <pre>
2218 .------------.
2219 |  HEADER    |
2220 |------------|
2221 |  BUCKETS   |
2222 |------------|
2223 |  DATA      |
2224 `------------'
2225 </pre>
2226 </div>
2227 <p>The BUCKETS are an array of offsets to DATA for each hash:
2228 <div class="doc_code">
2229 <pre>
2230 .------------.
2231 | 0x00001000 | BUCKETS[0]
2232 | 0x00002000 | BUCKETS[1]
2233 | 0x00002200 | BUCKETS[2]
2234 | 0x000034f0 | BUCKETS[3]
2235 |            | ...
2236 | 0xXXXXXXXX | BUCKETS[n_buckets]
2237 '------------'
2238 </pre>
2239 </div>
2240 <p>So for bucket[3] in the example above, we have an offset into the table
2241   0x000034f0 which points to a chain of entries for the bucket. Each bucket
2242   must contain a next pointer, full 32 bit hash value, the string itself,
2243   and the data for the current string value.
2244 <div class="doc_code">
2245 <pre>
2246             .------------.
2247 0x000034f0: | 0x00003500 | next pointer
2248             | 0x12345678 | 32 bit hash
2249             | "erase"    | string value
2250             | data[n]    | HashData for this bucket
2251             |------------|
2252 0x00003500: | 0x00003550 | next pointer
2253             | 0x29273623 | 32 bit hash
2254             | "dump"     | string value
2255             | data[n]    | HashData for this bucket
2256             |------------|
2257 0x00003550: | 0x00000000 | next pointer
2258             | 0x82638293 | 32 bit hash
2259             | "main"     | string value
2260             | data[n]    | HashData for this bucket
2261             `------------'
2262 </pre>
2263 </div>
2264 <p>The problem with this layout for debuggers is that we need to optimize for
2265   the negative lookup case where the symbol we're searching for is not present.
2266   So if we were to lookup "printf" in the table above, we would make a 32 hash
2267   for "printf", it might match bucket[3]. We would need to go to the offset
2268   0x000034f0 and start looking to see if our 32 bit hash matches. To do so, we
2269   need to read the next pointer, then read the hash, compare it, and skip to
2270   the next bucket. Each time we are skipping many bytes in memory and touching
2271   new cache pages just to do the compare on the full 32 bit hash. All of these
2272   accesses then tell us that we didn't have a match.
2273
2274 <h5>Name Hash Tables</h5>
2275
2276 <p>To solve the issues mentioned above we have structured the hash tables
2277   a bit differently: a header, buckets, an array of all unique 32 bit hash
2278   values, followed by an array of hash value data offsets, one for each hash
2279   value, then the data for all hash values:
2280 <div class="doc_code">
2281 <pre>
2282 .-------------.
2283 |  HEADER     |
2284 |-------------|
2285 |  BUCKETS    |
2286 |-------------|
2287 |  HASHES     |
2288 |-------------|
2289 |  OFFSETS    |
2290 |-------------|
2291 |  DATA       |
2292 `-------------'
2293 </pre>
2294 </div>
2295 <p>The BUCKETS in the name tables are an index into the HASHES array. By
2296   making all of the full 32 bit hash values contiguous in memory, we allow
2297   ourselves to efficiently check for a match while touching as little
2298   memory as possible. Most often checking the 32 bit hash values is as far as
2299   the lookup goes. If it does match, it usually is a match with no collisions.
2300   So for a table with "n_buckets" buckets, and "n_hashes" unique 32 bit hash
2301   values, we can clarify the contents of the BUCKETS, HASHES and OFFSETS as:
2302 <div class="doc_code">
2303 <pre>
2304 .-------------------------.
2305 |  HEADER.magic           | uint32_t
2306 |  HEADER.version         | uint16_t
2307 |  HEADER.hash_function   | uint16_t
2308 |  HEADER.bucket_count    | uint32_t
2309 |  HEADER.hashes_count    | uint32_t
2310 |  HEADER.header_data_len | uint32_t
2311 |  HEADER_DATA            | HeaderData
2312 |-------------------------|
2313 |  BUCKETS                | uint32_t[n_buckets] // 32 bit hash indexes
2314 |-------------------------|
2315 |  HASHES                 | uint32_t[n_buckets] // 32 bit hash values
2316 |-------------------------|
2317 |  OFFSETS                | uint32_t[n_buckets] // 32 bit offsets to hash value data
2318 |-------------------------|
2319 |  ALL HASH DATA          |
2320 `-------------------------'
2321 </pre>
2322 </div>
2323 <p>So taking the exact same data from the standard hash example above we end up
2324   with:
2325 <div class="doc_code">
2326 <pre>
2327             .------------.
2328             | HEADER     |
2329             |------------|
2330             |          0 | BUCKETS[0]
2331             |          2 | BUCKETS[1]
2332             |          5 | BUCKETS[2]
2333             |          6 | BUCKETS[3]
2334             |            | ...
2335             |        ... | BUCKETS[n_buckets]
2336             |------------|
2337             | 0x........ | HASHES[0]
2338             | 0x........ | HASHES[1]
2339             | 0x........ | HASHES[2]
2340             | 0x........ | HASHES[3]
2341             | 0x........ | HASHES[4]
2342             | 0x........ | HASHES[5]
2343             | 0x12345678 | HASHES[6]    hash for BUCKETS[3]
2344             | 0x29273623 | HASHES[7]    hash for BUCKETS[3]
2345             | 0x82638293 | HASHES[8]    hash for BUCKETS[3]
2346             | 0x........ | HASHES[9]
2347             | 0x........ | HASHES[10]
2348             | 0x........ | HASHES[11]
2349             | 0x........ | HASHES[12]
2350             | 0x........ | HASHES[13]
2351             | 0x........ | HASHES[n_hashes]
2352             |------------|
2353             | 0x........ | OFFSETS[0]
2354             | 0x........ | OFFSETS[1]
2355             | 0x........ | OFFSETS[2]
2356             | 0x........ | OFFSETS[3]
2357             | 0x........ | OFFSETS[4]
2358             | 0x........ | OFFSETS[5]
2359             | 0x000034f0 | OFFSETS[6]   offset for BUCKETS[3]
2360             | 0x00003500 | OFFSETS[7]   offset for BUCKETS[3]
2361             | 0x00003550 | OFFSETS[8]   offset for BUCKETS[3]
2362             | 0x........ | OFFSETS[9]
2363             | 0x........ | OFFSETS[10]
2364             | 0x........ | OFFSETS[11]
2365             | 0x........ | OFFSETS[12]
2366             | 0x........ | OFFSETS[13]
2367             | 0x........ | OFFSETS[n_hashes]
2368             |------------|
2369             |            |
2370             |            |
2371             |            |
2372             |            |
2373             |            |
2374             |------------|
2375 0x000034f0: | 0x00001203 | .debug_str ("erase")
2376             | 0x00000004 | A 32 bit array count - number of HashData with name "erase"
2377             | 0x........ | HashData[0]
2378             | 0x........ | HashData[1]
2379             | 0x........ | HashData[2]
2380             | 0x........ | HashData[3]
2381             | 0x00000000 | String offset into .debug_str (terminate data for hash)
2382             |------------|
2383 0x00003500: | 0x00001203 | String offset into .debug_str ("collision")
2384             | 0x00000002 | A 32 bit array count - number of HashData with name "collision"
2385             | 0x........ | HashData[0]
2386             | 0x........ | HashData[1]
2387             | 0x00001203 | String offset into .debug_str ("dump")
2388             | 0x00000003 | A 32 bit array count - number of HashData with name "dump"
2389             | 0x........ | HashData[0]
2390             | 0x........ | HashData[1]
2391             | 0x........ | HashData[2]
2392             | 0x00000000 | String offset into .debug_str (terminate data for hash)
2393             |------------|
2394 0x00003550: | 0x00001203 | String offset into .debug_str ("main")
2395             | 0x00000009 | A 32 bit array count - number of HashData with name "main"
2396             | 0x........ | HashData[0]
2397             | 0x........ | HashData[1]
2398             | 0x........ | HashData[2]
2399             | 0x........ | HashData[3]
2400             | 0x........ | HashData[4]
2401             | 0x........ | HashData[5]
2402             | 0x........ | HashData[6]
2403             | 0x........ | HashData[7]
2404             | 0x........ | HashData[8]
2405             | 0x00000000 | String offset into .debug_str (terminate data for hash)
2406             `------------'
2407 </pre>
2408 </div>
2409 <p>So we still have all of the same data, we just organize it more efficiently
2410   for debugger lookup. If we repeat the same "printf" lookup from above, we
2411   would hash "printf" and find it matches BUCKETS[3] by taking the 32 bit hash
2412   value and modulo it by n_buckets. BUCKETS[3] contains "6" which is the index
2413   into the HASHES table. We would then compare any consecutive 32 bit hashes
2414   values in the HASHES array as long as the hashes would be in BUCKETS[3]. We
2415   do this by verifying that each subsequent hash value modulo n_buckets is still
2416   3. In the case of a failed lookup we would access the memory for BUCKETS[3], and
2417   then compare a few consecutive 32 bit hashes before we know that we have no match.
2418   We don't end up marching through multiple words of memory and we really keep the
2419   number of processor data cache lines being accessed as small as possible.
2420
2421 <p>The string hash that is used for these lookup tables is the Daniel J.
2422   Bernstein hash which is also used in the ELF GNU_HASH sections. It is a very
2423   good hash for all kinds of names in programs with very few hash collisions.
2424
2425 <p>Empty buckets are designated by using an invalid hash index of UINT32_MAX.
2426 </div>
2427 <!-- ======================================================================= -->
2428 <h4>
2429   <a name="acceltabledetails">Details</a>
2430 </h4>
2431 <!-- ======================================================================= -->
2432 <div>
2433 <p>These name hash tables are designed to be generic where specializations of
2434   the table get to define additional data that goes into the header
2435   ("HeaderData"), how the string value is stored ("KeyType") and the content
2436   of the data for each hash value.
2437
2438 <h5>Header Layout</h5>
2439 <p>The header has a fixed part, and the specialized part. The exact format of
2440   the header is:
2441 <div class="doc_code">
2442 <pre>
2443 struct Header
2444 {
2445   uint32_t   magic;           // 'HASH' magic value to allow endian detection
2446   uint16_t   version;         // Version number
2447   uint16_t   hash_function;   // The hash function enumeration that was used
2448   uint32_t   bucket_count;    // The number of buckets in this hash table
2449   uint32_t   hashes_count;    // The total number of unique hash values and hash data offsets in this table
2450   uint32_t   header_data_len; // The bytes to skip to get to the hash indexes (buckets) for correct alignment
2451                               // Specifically the length of the following HeaderData field - this does not
2452                               // include the size of the preceding fields
2453   HeaderData header_data;     // Implementation specific header data
2454 };
2455 </pre>
2456 </div>
2457 <p>The header starts with a 32 bit "magic" value which must be 'HASH' encoded as
2458   an ASCII integer. This allows the detection of the start of the hash table and
2459   also allows the table's byte order to be determined so the table can be
2460   correctly extracted. The "magic" value is followed by a 16 bit version number
2461   which allows the table to be revised and modified in the future. The current
2462   version number is 1. "hash_function" is a uint16_t enumeration that specifies
2463   which hash function was used to produce this table. The current values for the
2464   hash function enumerations include:
2465 <div class="doc_code">
2466 <pre>
2467 enum HashFunctionType
2468 {
2469   eHashFunctionDJB = 0u, // Daniel J Bernstein hash function
2470 };
2471 </pre>
2472 </div>
2473 <p>"bucket_count" is a 32 bit unsigned integer that represents how many buckets
2474   are in the BUCKETS array. "hashes_count" is the number of unique 32 bit hash
2475   values that are in the HASHES array, and is the same number of offsets are
2476   contained in the OFFSETS array. "header_data_len" specifies the size in
2477   bytes of the HeaderData that is filled in by specialized versions of this
2478   table.
2479
2480 <h5>Fixed Lookup</h5>
2481 <p>The header is followed by the buckets, hashes, offsets, and hash value
2482   data.
2483 <div class="doc_code">
2484 <pre>
2485 struct FixedTable
2486 {
2487   uint32_t buckets[Header.bucket_count];  // An array of hash indexes into the "hashes[]" array below
2488   uint32_t hashes [Header.hashes_count];  // Every unique 32 bit hash for the entire table is in this table
2489   uint32_t offsets[Header.hashes_count];  // An offset that corresponds to each item in the "hashes[]" array above
2490 };
2491 </pre>
2492 </div>
2493 <p>"buckets" is an array of 32 bit indexes into the "hashes" array. The
2494   "hashes" array contains all of the 32 bit hash values for all names in the
2495   hash table. Each hash in the "hashes" table has an offset in the "offsets"
2496   array that points to the data for the hash value.
2497
2498 <p>This table setup makes it very easy to repurpose these tables to contain
2499   different data, while keeping the lookup mechanism the same for all tables.
2500   This layout also makes it possible to save the table to disk and map it in
2501   later and do very efficient name lookups with little or no parsing.
2502
2503 <p>DWARF lookup tables can be implemented in a variety of ways and can store
2504   a lot of information for each name. We want to make the DWARF tables
2505   extensible and able to store the data efficiently so we have used some of the
2506   DWARF features that enable efficient data storage to define exactly what kind
2507   of data we store for each name.
2508
2509 <p>The "HeaderData" contains a definition of the contents of each HashData
2510   chunk. We might want to store an offset to all of the debug information
2511   entries (DIEs) for each name. To keep things extensible, we create a list of
2512   items, or Atoms, that are contained in the data for each name. First comes the
2513   type of the data in each atom:
2514 <div class="doc_code">
2515 <pre>
2516 enum AtomType
2517 {
2518   eAtomTypeNULL       = 0u,
2519   eAtomTypeDIEOffset  = 1u,   // DIE offset, check form for encoding
2520   eAtomTypeCUOffset   = 2u,   // DIE offset of the compiler unit header that contains the item in question
2521   eAtomTypeTag        = 3u,   // DW_TAG_xxx value, should be encoded as DW_FORM_data1 (if no tags exceed 255) or DW_FORM_data2
2522   eAtomTypeNameFlags  = 4u,   // Flags from enum NameFlags
2523   eAtomTypeTypeFlags  = 5u,   // Flags from enum TypeFlags
2524 };
2525 </pre>
2526 </div>
2527 <p>The enumeration values and their meanings are:
2528 <div class="doc_code">
2529 <pre>
2530   eAtomTypeNULL       - a termination atom that specifies the end of the atom list
2531   eAtomTypeDIEOffset  - an offset into the .debug_info section for the DWARF DIE for this name
2532   eAtomTypeCUOffset   - an offset into the .debug_info section for the CU that contains the DIE
2533   eAtomTypeDIETag     - The DW_TAG_XXX enumeration value so you don't have to parse the DWARF to see what it is
2534   eAtomTypeNameFlags  - Flags for functions and global variables (isFunction, isInlined, isExternal...)
2535   eAtomTypeTypeFlags  - Flags for types (isCXXClass, isObjCClass, ...)
2536 </pre>
2537 </div>
2538 <p>Then we allow each atom type to define the atom type and how the data for
2539   each atom type data is encoded:
2540 <div class="doc_code">
2541 <pre>
2542 struct Atom
2543 {
2544   uint16_t type;  // AtomType enum value
2545   uint16_t form;  // DWARF DW_FORM_XXX defines
2546 };
2547 </pre>
2548 </div>
2549 <p>The "form" type above is from the DWARF specification and defines the
2550   exact encoding of the data for the Atom type. See the DWARF specification for
2551   the DW_FORM_ definitions.
2552 <div class="doc_code">
2553 <pre>
2554 struct HeaderData
2555 {
2556   uint32_t die_offset_base;
2557   uint32_t atom_count;
2558   Atoms    atoms[atom_count0];
2559 };
2560 </pre>
2561 </div>
2562 <p>"HeaderData" defines the base DIE offset that should be added to any atoms
2563   that are encoded using the DW_FORM_ref1, DW_FORM_ref2, DW_FORM_ref4,
2564   DW_FORM_ref8 or DW_FORM_ref_udata. It also defines what is contained in
2565   each "HashData" object -- Atom.form tells us how large each field will be in
2566   the HashData and the Atom.type tells us how this data should be interpreted.
2567
2568 <p>For the current implementations of the ".apple_names" (all functions + globals),
2569   the ".apple_types" (names of all types that are defined), and the
2570   ".apple_namespaces" (all namespaces), we currently set the Atom array to be:
2571 <div class="doc_code">
2572 <pre>
2573 HeaderData.atom_count = 1;
2574 HeaderData.atoms[0].type = eAtomTypeDIEOffset;
2575 HeaderData.atoms[0].form = DW_FORM_data4;
2576 </pre>
2577 </div>
2578 <p>This defines the contents to be the DIE offset (eAtomTypeDIEOffset) that is
2579   encoded as a 32 bit value (DW_FORM_data4). This allows a single name to have
2580   multiple matching DIEs in a single file, which could come up with an inlined
2581   function for instance. Future tables could include more information about the
2582   DIE such as flags indicating if the DIE is a function, method, block,
2583   or inlined.
2584
2585 <p>The KeyType for the DWARF table is a 32 bit string table offset into the
2586   ".debug_str" table. The ".debug_str" is the string table for the DWARF which
2587   may already contain copies of all of the strings. This helps make sure, with
2588   help from the compiler, that we reuse the strings between all of the DWARF
2589   sections and keeps the hash table size down. Another benefit to having the
2590   compiler generate all strings as DW_FORM_strp in the debug info, is that
2591   DWARF parsing can be made much faster.
2592
2593 <p>After a lookup is made, we get an offset into the hash data. The hash data
2594   needs to be able to deal with 32 bit hash collisions, so the chunk of data
2595   at the offset in the hash data consists of a triple:
2596 <div class="doc_code">
2597 <pre>
2598 uint32_t str_offset
2599 uint32_t hash_data_count
2600 HashData[hash_data_count]
2601 </pre>
2602 </div>
2603 <p>If "str_offset" is zero, then the bucket contents are done. 99.9% of the
2604   hash data chunks contain a single item (no 32 bit hash collision):
2605 <div class="doc_code">
2606 <pre>
2607 .------------.
2608 | 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")
2609 | 0x00000004 | uint32_t HashData count
2610 | 0x........ | uint32_t HashData[0] DIE offset
2611 | 0x........ | uint32_t HashData[1] DIE offset
2612 | 0x........ | uint32_t HashData[2] DIE offset
2613 | 0x........ | uint32_t HashData[3] DIE offset
2614 | 0x00000000 | uint32_t KeyType (end of hash chain)
2615 `------------'
2616 </pre>
2617 </div>
2618 <p>If there are collisions, you will have multiple valid string offsets:
2619 <div class="doc_code">
2620 <pre>
2621 .------------.
2622 | 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")
2623 | 0x00000004 | uint32_t HashData count
2624 | 0x........ | uint32_t HashData[0] DIE offset
2625 | 0x........ | uint32_t HashData[1] DIE offset
2626 | 0x........ | uint32_t HashData[2] DIE offset
2627 | 0x........ | uint32_t HashData[3] DIE offset
2628 | 0x00002023 | uint32_t KeyType (.debug_str[0x0002023] => "print")
2629 | 0x00000002 | uint32_t HashData count
2630 | 0x........ | uint32_t HashData[0] DIE offset
2631 | 0x........ | uint32_t HashData[1] DIE offset
2632 | 0x00000000 | uint32_t KeyType (end of hash chain)
2633 `------------'
2634 </pre>
2635 </div>
2636 <p>Current testing with real world C++ binaries has shown that there is around 1
2637   32 bit hash collision per 100,000 name entries.
2638 </div>
2639 <!-- ======================================================================= -->
2640 <h4>
2641   <a name="acceltablecontents">Contents</a>
2642 </h4>
2643 <!-- ======================================================================= -->
2644 <div>
2645 <p>As we said, we want to strictly define exactly what is included in the
2646   different tables. For DWARF, we have 3 tables: ".apple_names", ".apple_types",
2647   and ".apple_namespaces".
2648
2649 <p>".apple_names" sections should contain an entry for each DWARF DIE whose
2650   DW_TAG is a DW_TAG_label, DW_TAG_inlined_subroutine, or DW_TAG_subprogram that
2651   has address attributes: DW_AT_low_pc, DW_AT_high_pc, DW_AT_ranges or
2652   DW_AT_entry_pc. It also contains DW_TAG_variable DIEs that have a DW_OP_addr
2653   in the location (global and static variables). All global and static variables
2654   should be included, including those scoped withing functions and classes. For
2655   example using the following code:
2656 <div class="doc_code">
2657 <pre>
2658 static int var = 0;
2659
2660 void f ()
2661 {
2662   static int var = 0;
2663 }
2664 </pre>
2665 </div>
2666 <p>Both of the static "var" variables would be included in the table. All
2667   functions should emit both their full names and their basenames. For C or C++,
2668   the full name is the mangled name (if available) which is usually in the
2669   DW_AT_MIPS_linkage_name attribute, and the DW_AT_name contains the function
2670   basename. If global or static variables have a mangled name in a
2671   DW_AT_MIPS_linkage_name attribute, this should be emitted along with the
2672   simple name found in the DW_AT_name attribute.
2673
2674 <p>".apple_types" sections should contain an entry for each DWARF DIE whose
2675   tag is one of:
2676 <ul>
2677   <li>DW_TAG_array_type</li>
2678   <li>DW_TAG_class_type</li>
2679   <li>DW_TAG_enumeration_type</li>
2680   <li>DW_TAG_pointer_type</li>
2681   <li>DW_TAG_reference_type</li>
2682   <li>DW_TAG_string_type</li>
2683   <li>DW_TAG_structure_type</li>
2684   <li>DW_TAG_subroutine_type</li>
2685   <li>DW_TAG_typedef</li>
2686   <li>DW_TAG_union_type</li>
2687   <li>DW_TAG_ptr_to_member_type</li>
2688   <li>DW_TAG_set_type</li>
2689   <li>DW_TAG_subrange_type</li>
2690   <li>DW_TAG_base_type</li>
2691   <li>DW_TAG_const_type</li>
2692   <li>DW_TAG_constant</li>
2693   <li>DW_TAG_file_type</li>
2694   <li>DW_TAG_namelist</li>
2695   <li>DW_TAG_packed_type</li>
2696   <li>DW_TAG_volatile_type</li>
2697   <li>DW_TAG_restrict_type</li>
2698   <li>DW_TAG_interface_type</li>
2699   <li>DW_TAG_unspecified_type</li>
2700   <li>DW_TAG_shared_type</li>
2701 </ul>
2702 <p>Only entries with a DW_AT_name attribute are included, and the entry must
2703   not be a forward declaration (DW_AT_declaration attribute with a non-zero value).
2704   For example, using the following code:
2705 <div class="doc_code">
2706 <pre>
2707 int main ()
2708 {
2709   int *b = 0;
2710   return *b;
2711 }
2712 </pre>
2713 </div>
2714 <p>We get a few type DIEs:
2715 <div class="doc_code">
2716 <pre>
2717 0x00000067:     TAG_base_type [5]
2718                 AT_encoding( DW_ATE_signed )
2719                 AT_name( "int" )
2720                 AT_byte_size( 0x04 )
2721
2722 0x0000006e:     TAG_pointer_type [6]
2723                 AT_type( {0x00000067} ( int ) )
2724                 AT_byte_size( 0x08 )
2725 </pre>
2726 </div>
2727 <p>The DW_TAG_pointer_type is not included because it does not have a DW_AT_name.
2728
2729 <p>".apple_namespaces" section should contain all DW_TAG_namespace DIEs. If
2730   we run into a namespace that has no name this is an anonymous namespace,
2731   and the name should be output as "(anonymous namespace)" (without the quotes).
2732   Why? This matches the output of the abi::cxa_demangle() that is in the standard
2733   C++ library that demangles mangled names.
2734 </div>
2735
2736 <!-- ======================================================================= -->
2737 <h4>
2738   <a name="acceltableextensions">Language Extensions and File Format Changes</a>
2739 </h4>
2740 <!-- ======================================================================= -->
2741 <div>
2742 <h5>Objective-C Extensions</h5>
2743 <p>".apple_objc" section should contain all DW_TAG_subprogram DIEs for an
2744   Objective-C class. The name used in the hash table is the name of the
2745   Objective-C class itself. If the Objective-C class has a category, then an
2746   entry is made for both the class name without the category, and for the class
2747   name with the category. So if we have a DIE at offset 0x1234 with a name
2748   of method "-[NSString(my_additions) stringWithSpecialString:]", we would add
2749   an entry for "NSString" that points to DIE 0x1234, and an entry for
2750   "NSString(my_additions)" that points to 0x1234. This allows us to quickly
2751   track down all Objective-C methods for an Objective-C class when doing
2752   expressions. It is needed because of the dynamic nature of Objective-C where
2753   anyone can add methods to a class. The DWARF for Objective-C methods is also
2754   emitted differently from C++ classes where the methods are not usually
2755   contained in the class definition, they are scattered about across one or more
2756   compile units. Categories can also be defined in different shared libraries.
2757   So we need to be able to quickly find all of the methods and class functions
2758   given the Objective-C class name, or quickly find all methods and class
2759   functions for a class + category name. This table does not contain any selector
2760   names, it just maps Objective-C class names (or class names + category) to all
2761   of the methods and class functions. The selectors are added as function
2762   basenames in the .debug_names section.
2763
2764 <p>In the ".apple_names" section for Objective-C functions, the full name is the
2765   entire function name with the brackets ("-[NSString stringWithCString:]") and the
2766   basename is the selector only ("stringWithCString:").
2767
2768 <h5>Mach-O Changes</h5>
2769 <p>The sections names for the apple hash tables are for non mach-o files. For
2770   mach-o files, the sections should be contained in the "__DWARF" segment with
2771   names as follows:
2772 <ul>
2773   <li>".apple_names" -> "__apple_names"</li>
2774   <li>".apple_types" -> "__apple_types"</li>
2775   <li>".apple_namespaces" -> "__apple_namespac" (16 character limit)</li>
2776   <li> ".apple_objc" -> "__apple_objc"</li>
2777 </ul>
2778 </div>
2779 </div>
2780
2781 <!-- *********************************************************************** -->
2782
2783 <hr>
2784 <address>
2785   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
2786   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
2787   <a href="http://validator.w3.org/check/referer"><img
2788   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
2789
2790   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
2791   <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
2792   Last modified: $Date$
2793 </address>
2794
2795 </body>
2796 </html>