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