docs/SourceLevelDebugging.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6   <title>Source Level Debugging with LLVM</title>
   7   <link rel="stylesheet" href="llvm.css" type="text/css">
   8 </head>
   9 <body>
  10
  11 <h1>Source Level Debugging with LLVM</h1>
  12
  13 <table class="layout" style="width:100%">
  14   <tr class="layout">
  15     <td class="left">
  16 <ul>
  17   <li><a href="#introduction">Introduction</a>
  18   <ol>
  19     <li><a href="#phil">Philosophy behind LLVM debugging information</a></li>
  20     <li><a href="#consumers">Debug information consumers</a></li>
  21     <li><a href="#debugopt">Debugging optimized code</a></li>
  22   </ol></li>
  23   <li><a href="#format">Debugging information format</a>
  24   <ol>
  25     <li><a href="#debug_info_descriptors">Debug information descriptors</a>
  26     <ul>
  27       <li><a href="#format_compile_units">Compile unit descriptors</a></li>
  28       <li><a href="#format_files">File descriptors</a></li>
  29       <li><a href="#format_global_variables">Global variable descriptors</a></li>
  30       <li><a href="#format_subprograms">Subprogram descriptors</a></li>
  31       <li><a href="#format_blocks">Block descriptors</a></li>
  32       <li><a href="#format_basic_type">Basic type descriptors</a></li>
  33       <li><a href="#format_derived_type">Derived type descriptors</a></li>
  34       <li><a href="#format_composite_type">Composite type descriptors</a></li>
  35       <li><a href="#format_subrange">Subrange descriptors</a></li>
  36       <li><a href="#format_enumeration">Enumerator descriptors</a></li>
  37       <li><a href="#format_variables">Local variables</a></li>
  38     </ul></li>
  39     <li><a href="#format_common_intrinsics">Debugger intrinsic functions</a>
  40       <ul>
  41       <li><a href="#format_common_declare">llvm.dbg.declare</a></li>
  42       <li><a href="#format_common_value">llvm.dbg.value</a></li>
  43     </ul></li>
  44   </ol></li>
  45   <li><a href="#format_common_lifetime">Object lifetimes and scoping</a></li>
  46   <li><a href="#ccxx_frontend">C/C++ front-end specific debug information</a>
  47   <ol>
  48     <li><a href="#ccxx_compile_units">C/C++ source file information</a></li>
  49     <li><a href="#ccxx_global_variable">C/C++ global variable information</a></li>
  50     <li><a href="#ccxx_subprogram">C/C++ function information</a></li>
  51     <li><a href="#ccxx_basic_types">C/C++ basic types</a></li>
  52     <li><a href="#ccxx_derived_types">C/C++ derived types</a></li>
  53     <li><a href="#ccxx_composite_types">C/C++ struct/union types</a></li>
  54     <li><a href="#ccxx_enumeration_types">C/C++ enumeration types</a></li>
  55   </ol></li>
  56   <li><a href="#llvmdwarfextension">LLVM Dwarf Extensions</a>
  57     <ol>
  58       <li><a href="#objcproperty">Debugging Information Extension
  59           for Objective C Properties</a></li>
  60       <ul>
  61         <li><a href="#objcpropertyintroduction">Introduction</a></li>
  62         <li><a href="#objcpropertyproposal">Proposal</a></li>
  63         <li><a href="#objcpropertynewattributes">New DWARF Attributes</a></li>
  64         <li><a href="#objcpropertynewconstants">New DWARF Constants</a></li>
  65       </ul>
  66
  67     </ol>
  68   </li>
  69 </ul>
  70 </td>
  71 <td class="right">
  72 <img src="img/venusflytrap.jpg" alt="A leafy and green bug eater" width="247"
  73 height="369">
  74 </td>
  75 </tr></table>
  76
  77 <div class="doc_author">
  78   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
  79             and <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
  80 </div>
  81
  82
  83 <!-- *********************************************************************** -->
  84 <h2><a name="introduction">Introduction</a></h2>
  85 <!-- *********************************************************************** -->
  86
  87 <div>
  88
  89 <p>This document is the central repository for all information pertaining to
  90    debug information in LLVM.  It describes the <a href="#format">actual format
  91    that the LLVM debug information</a> takes, which is useful for those
  92    interested in creating front-ends or dealing directly with the information.
  93    Further, this document provides specific examples of what debug information
  94    for C/C++ looks like.</p>
  95
  96 <!-- ======================================================================= -->
  97 <h3>
  98   <a name="phil">Philosophy behind LLVM debugging information</a>
  99 </h3>
 100
 101 <div>
 102
 103 <p>The idea of the LLVM debugging information is to capture how the important
 104    pieces of the source-language's Abstract Syntax Tree map onto LLVM code.
 105    Several design aspects have shaped the solution that appears here.  The
 106    important ones are:</p>
 107
 108 <ul>
 109   <li>Debugging information should have very little impact on the rest of the
 110       compiler.  No transformations, analyses, or code generators should need to
 111       be modified because of debugging information.</li>
 112
 113   <li>LLVM optimizations should interact in <a href="#debugopt">well-defined and
 114       easily described ways</a> with the debugging information.</li>
 115
 116   <li>Because LLVM is designed to support arbitrary programming languages,
 117       LLVM-to-LLVM tools should not need to know anything about the semantics of
 118       the source-level-language.</li>
 119
 120   <li>Source-level languages are often <b>widely</b> different from one another.
 121       LLVM should not put any restrictions of the flavor of the source-language,
 122       and the debugging information should work with any language.</li>
 123
 124   <li>With code generator support, it should be possible to use an LLVM compiler
 125       to compile a program to native machine code and standard debugging
 126       formats.  This allows compatibility with traditional machine-code level
 127       debuggers, like GDB or DBX.</li>
 128 </ul>
 129
 130 <p>The approach used by the LLVM implementation is to use a small set
 131    of <a href="#format_common_intrinsics">intrinsic functions</a> to define a
 132    mapping between LLVM program objects and the source-level objects.  The
 133    description of the source-level program is maintained in LLVM metadata
 134    in an <a href="#ccxx_frontend">implementation-defined format</a>
 135    (the C/C++ front-end currently uses working draft 7 of
 136    the <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3
 137    standard</a>).</p>
 138
 139 <p>When a program is being debugged, a debugger interacts with the user and
 140    turns the stored debug information into source-language specific information.
 141    As such, a debugger must be aware of the source-language, and is thus tied to
 142    a specific language or family of languages.</p>
 143
 144 </div>
 145
 146 <!-- ======================================================================= -->
 147 <h3>
 148   <a name="consumers">Debug information consumers</a>
 149 </h3>
 150
 151 <div>
 152
 153 <p>The role of debug information is to provide meta information normally
 154    stripped away during the compilation process.  This meta information provides
 155    an LLVM user a relationship between generated code and the original program
 156    source code.</p>
 157
 158 <p>Currently, debug information is consumed by DwarfDebug to produce dwarf
 159    information used by the gdb debugger.  Other targets could use the same
 160    information to produce stabs or other debug forms.</p>
 161
 162 <p>It would also be reasonable to use debug information to feed profiling tools
 163    for analysis of generated code, or, tools for reconstructing the original
 164    source from generated code.</p>
 165
 166 <p>TODO - expound a bit more.</p>
 167
 168 </div>
 169
 170 <!-- ======================================================================= -->
 171 <h3>
 172   <a name="debugopt">Debugging optimized code</a>
 173 </h3>
 174
 175 <div>
 176
 177 <p>An extremely high priority of LLVM debugging information is to make it
 178    interact well with optimizations and analysis.  In particular, the LLVM debug
 179    information provides the following guarantees:</p>
 180
 181 <ul>
 182   <li>LLVM debug information <b>always provides information to accurately read
 183       the source-level state of the program</b>, regardless of which LLVM
 184       optimizations have been run, and without any modification to the
 185       optimizations themselves.  However, some optimizations may impact the
 186       ability to modify the current state of the program with a debugger, such
 187       as setting program variables, or calling functions that have been
 188       deleted.</li>
 189
 190   <li>As desired, LLVM optimizations can be upgraded to be aware of the LLVM
 191       debugging information, allowing them to update the debugging information
 192       as they perform aggressive optimizations.  This means that, with effort,
 193       the LLVM optimizers could optimize debug code just as well as non-debug
 194       code.</li>
 195
 196   <li>LLVM debug information does not prevent optimizations from
 197       happening (for example inlining, basic block reordering/merging/cleanup,
 198       tail duplication, etc).</li>
 199
 200   <li>LLVM debug information is automatically optimized along with the rest of
 201       the program, using existing facilities.  For example, duplicate
 202       information is automatically merged by the linker, and unused information
 203       is automatically removed.</li>
 204 </ul>
 205
 206 <p>Basically, the debug information allows you to compile a program with
 207    "<tt>-O0 -g</tt>" and get full debug information, allowing you to arbitrarily
 208    modify the program as it executes from a debugger.  Compiling a program with
 209    "<tt>-O3 -g</tt>" gives you full debug information that is always available
 210    and accurate for reading (e.g., you get accurate stack traces despite tail
 211    call elimination and inlining), but you might lose the ability to modify the
 212    program and call functions where were optimized out of the program, or
 213    inlined away completely.</p>
 214
 215 <p><a href="TestingGuide.html#quicktestsuite">LLVM test suite</a> provides a
 216    framework to test optimizer's handling of debugging information. It can be
 217    run like this:</p>
 218
 219 <div class="doc_code">
 220 <pre>
 221 % cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level
 222 % make TEST=dbgopt
 223 </pre>
 224 </div>
 225
 226 <p>This will test impact of debugging information on optimization passes. If
 227    debugging information influences optimization passes then it will be reported
 228    as a failure. See <a href="TestingGuide.html">TestingGuide</a> for more
 229    information on LLVM test infrastructure and how to run various tests.</p>
 230
 231 </div>
 232
 233 </div>
 234
 235 <!-- *********************************************************************** -->
 236 <h2>
 237   <a name="format">Debugging information format</a>
 238 </h2>
 239 <!-- *********************************************************************** -->
 240
 241 <div>
 242
 243 <p>LLVM debugging information has been carefully designed to make it possible
 244    for the optimizer to optimize the program and debugging information without
 245    necessarily having to know anything about debugging information.  In
 246    particular, the use of metadata avoids duplicated debugging information from
 247    the beginning, and the global dead code elimination pass automatically
 248    deletes debugging information for a function if it decides to delete the
 249    function. </p>
 250
 251 <p>To do this, most of the debugging information (descriptors for types,
 252    variables, functions, source files, etc) is inserted by the language
 253    front-end in the form of LLVM metadata. </p>
 254
 255 <p>Debug information is designed to be agnostic about the target debugger and
 256    debugging information representation (e.g. DWARF/Stabs/etc).  It uses a
 257    generic pass to decode the information that represents variables, types,
 258    functions, namespaces, etc: this allows for arbitrary source-language
 259    semantics and type-systems to be used, as long as there is a module
 260    written for the target debugger to interpret the information. </p>
 261
 262 <p>To provide basic functionality, the LLVM debugger does have to make some
 263    assumptions about the source-level language being debugged, though it keeps
 264    these to a minimum.  The only common features that the LLVM debugger assumes
 265    exist are <a href="#format_files">source files</a>,
 266    and <a href="#format_global_variables">program objects</a>.  These abstract
 267    objects are used by a debugger to form stack traces, show information about
 268    local variables, etc.</p>
 269
 270 <p>This section of the documentation first describes the representation aspects
 271    common to any source-language.  The <a href="#ccxx_frontend">next section</a>
 272    describes the data layout conventions used by the C and C++ front-ends.</p>
 273
 274 <!-- ======================================================================= -->
 275 <h3>
 276   <a name="debug_info_descriptors">Debug information descriptors</a>
 277 </h3>
 278
 279 <div>
 280
 281 <p>In consideration of the complexity and volume of debug information, LLVM
 282    provides a specification for well formed debug descriptors. </p>
 283
 284 <p>Consumers of LLVM debug information expect the descriptors for program
 285    objects to start in a canonical format, but the descriptors can include
 286    additional information appended at the end that is source-language
 287    specific. All LLVM debugging information is versioned, allowing backwards
 288    compatibility in the case that the core structures need to change in some
 289    way.  Also, all debugging information objects start with a tag to indicate
 290    what type of object it is.  The source-language is allowed to define its own
 291    objects, by using unreserved tag numbers.  We recommend using with tags in
 292    the range 0x1000 through 0x2000 (there is a defined enum DW_TAG_user_base =
 293    0x1000.)</p>
 294
 295 <p>The fields of debug descriptors used internally by LLVM
 296    are restricted to only the simple data types <tt>i32</tt>, <tt>i1</tt>,
 297    <tt>float</tt>, <tt>double</tt>, <tt>mdstring</tt> and <tt>mdnode</tt>. </p>
 298
 299 <div class="doc_code">
 300 <pre>
 301 !1 = metadata !{
 302   i32,   ;; A tag
 303   ...
 304 }
 305 </pre>
 306 </div>
 307
 308 <p><a name="LLVMDebugVersion">The first field of a descriptor is always an
 309    <tt>i32</tt> containing a tag value identifying the content of the
 310    descriptor.  The remaining fields are specific to the descriptor.  The values
 311    of tags are loosely bound to the tag values of DWARF information entries.
 312    However, that does not restrict the use of the information supplied to DWARF
 313    targets.  To facilitate versioning of debug information, the tag is augmented
 314    with the current debug version (LLVMDebugVersion = 8 &lt;&lt; 16 or
 315    0x80000 or 524288.)</a></p>
 316
 317 <p>The details of the various descriptors follow.</p>
 318
 319 <!-- ======================================================================= -->
 320 <h4>
 321   <a name="format_compile_units">Compile unit descriptors</a>
 322 </h4>
 323
 324 <div>
 325
 326 <div class="doc_code">
 327 <pre>
 328 !0 = metadata !{
 329   i32,       ;; Tag = 17 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 330              ;; (DW_TAG_compile_unit)
 331   i32,       ;; Unused field.
 332   i32,       ;; DWARF language identifier (ex. DW_LANG_C89)
 333   metadata,  ;; Source file name
 334   metadata,  ;; Source file directory (includes trailing slash)
 335   metadata   ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
 336   i1,        ;; True if this is a main compile unit.
 337   i1,        ;; True if this is optimized.
 338   metadata,  ;; Flags
 339   i32        ;; Runtime version
 340   metadata   ;; List of enums types
 341   metadata   ;; List of retained types
 342   metadata   ;; List of subprograms
 343   metadata   ;; List of global variables
 344 }
 345 </pre>
 346 </div>
 347
 348 <p>These descriptors contain a source language ID for the file (we use the DWARF
 349    3.0 ID numbers, such as <tt>DW_LANG_C89</tt>, <tt>DW_LANG_C_plus_plus</tt>,
 350    <tt>DW_LANG_Cobol74</tt>, etc), three strings describing the filename,
 351    working directory of the compiler, and an identifier string for the compiler
 352    that produced it.</p>
 353
 354 <p>Compile unit descriptors provide the root context for objects declared in a
 355    specific compilation unit. File descriptors are defined using this context.
 356    These descriptors are collected by a named metadata
 357    <tt>!llvm.dbg.cu</tt>. Compile unit descriptor keeps track of subprograms,
 358    global variables and type information.
 359
 360 </div>
 361
 362 <!-- ======================================================================= -->
 363 <h4>
 364   <a name="format_files">File descriptors</a>
 365 </h4>
 366
 367 <div>
 368
 369 <div class="doc_code">
 370 <pre>
 371 !0 = metadata !{
 372   i32,       ;; Tag = 41 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 373              ;; (DW_TAG_file_type)
 374   metadata,  ;; Source file name
 375   metadata,  ;; Source file directory (includes trailing slash)
 376   metadata   ;; Unused
 377 }
 378 </pre>
 379 </div>
 380
 381 <p>These descriptors contain information for a file. Global variables and top
 382    level functions would be defined using this context.k File descriptors also
 383    provide context for source line correspondence. </p>
 384
 385 <p>Each input file is encoded as a separate file descriptor in LLVM debugging
 386    information output. </p>
 387
 388 </div>
 389
 390 <!-- ======================================================================= -->
 391 <h4>
 392   <a name="format_global_variables">Global variable descriptors</a>
 393 </h4>
 394
 395 <div>
 396
 397 <div class="doc_code">
 398 <pre>
 399 !1 = metadata !{
 400   i32,      ;; Tag = 52 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 401             ;; (DW_TAG_variable)
 402   i32,      ;; Unused field.
 403   metadata, ;; Reference to context descriptor
 404   metadata, ;; Name
 405   metadata, ;; Display name (fully qualified C++ name)
 406   metadata, ;; MIPS linkage name (for C++)
 407   metadata, ;; Reference to file where defined
 408   i32,      ;; Line number where defined
 409   metadata, ;; Reference to type descriptor
 410   i1,       ;; True if the global is local to compile unit (static)
 411   i1,       ;; True if the global is defined in the compile unit (not extern)
 412   {}*       ;; Reference to the global variable
 413 }
 414 </pre>
 415 </div>
 416
 417 <p>These descriptors provide debug information about globals variables.  The
 418 provide details such as name, type and where the variable is defined. All
 419 global variables are collected by named metadata <tt>!llvm.dbg.gv</tt>.</p>
 420
 421 </div>
 422
 423 <!-- ======================================================================= -->
 424 <h4>
 425   <a name="format_subprograms">Subprogram descriptors</a>
 426 </h4>
 427
 428 <div>
 429
 430 <div class="doc_code">
 431 <pre>
 432 !2 = metadata !{
 433   i32,      ;; Tag = 46 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 434             ;; (DW_TAG_subprogram)
 435   i32,      ;; Unused field.
 436   metadata, ;; Reference to context descriptor
 437   metadata, ;; Name
 438   metadata, ;; Display name (fully qualified C++ name)
 439   metadata, ;; MIPS linkage name (for C++)
 440   metadata, ;; Reference to file where defined
 441   i32,      ;; Line number where defined
 442   metadata, ;; Reference to type descriptor
 443   i1,       ;; True if the global is local to compile unit (static)
 444   i1,       ;; True if the global is defined in the compile unit (not extern)
 445   i32,      ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual
 446   i32,      ;; Index into a virtual function
 447   metadata, ;; indicates which base type contains the vtable pointer for the
 448             ;; derived class
 449   i32,      ;; Flags - Artifical, Private, Protected, Explicit, Prototyped.
 450   i1,       ;; isOptimized
 451   Function *,;; Pointer to LLVM function
 452   metadata, ;; Lists function template parameters
 453   metadata  ;; Function declaration descriptor
 454   metadata  ;; List of function variables
 455 }
 456 </pre>
 457 </div>
 458
 459 <p>These descriptors provide debug information about functions, methods and
 460    subprograms.  They provide details such as name, return types and the source
 461    location where the subprogram is defined.
 462 </p>
 463
 464 </div>
 465
 466 <!-- ======================================================================= -->
 467 <h4>
 468   <a name="format_blocks">Block descriptors</a>
 469 </h4>
 470
 471 <div>
 472
 473 <div class="doc_code">
 474 <pre>
 475 !3 = metadata !{
 476   i32,     ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
 477   metadata,;; Reference to context descriptor
 478   i32,     ;; Line number
 479   i32,     ;; Column number
 480   metadata,;; Reference to source file
 481   i32      ;; Unique ID to identify blocks from a template function
 482 }
 483 </pre>
 484 </div>
 485
 486 <p>This descriptor provides debug information about nested blocks within a
 487    subprogram. The line number and column numbers are used to dinstinguish
 488    two lexical blocks at same depth. </p>
 489
 490 <div class="doc_code">
 491 <pre>
 492 !3 = metadata !{
 493   i32,     ;; Tag = 11 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_lexical_block)
 494   metadata ;; Reference to the scope we're annotating with a file change
 495   metadata,;; Reference to the file the scope is enclosed in.
 496 }
 497 </pre>
 498 </div>
 499
 500 <p>This descriptor provides a wrapper around a lexical scope to handle file
 501    changes in the middle of a lexical block.</p>
 502
 503 </div>
 504
 505 <!-- ======================================================================= -->
 506 <h4>
 507   <a name="format_basic_type">Basic type descriptors</a>
 508 </h4>
 509
 510 <div>
 511
 512 <div class="doc_code">
 513 <pre>
 514 !4 = metadata !{
 515   i32,      ;; Tag = 36 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 516             ;; (DW_TAG_base_type)
 517   metadata, ;; Reference to context
 518   metadata, ;; Name (may be "" for anonymous types)
 519   metadata, ;; Reference to file where defined (may be NULL)
 520   i32,      ;; Line number where defined (may be 0)
 521   i64,      ;; Size in bits
 522   i64,      ;; Alignment in bits
 523   i64,      ;; Offset in bits
 524   i32,      ;; Flags
 525   i32       ;; DWARF type encoding
 526 }
 527 </pre>
 528 </div>
 529
 530 <p>These descriptors define primitive types used in the code. Example int, bool
 531    and float.  The context provides the scope of the type, which is usually the
 532    top level.  Since basic types are not usually user defined the context
 533    and line number can be left as NULL and 0.  The size, alignment and offset
 534    are expressed in bits and can be 64 bit values.  The alignment is used to
 535    round the offset when embedded in a
 536    <a href="#format_composite_type">composite type</a> (example to keep float
 537    doubles on 64 bit boundaries.) The offset is the bit offset if embedded in
 538    a <a href="#format_composite_type">composite type</a>.</p>
 539
 540 <p>The type encoding provides the details of the type.  The values are typically
 541    one of the following:</p>
 542
 543 <div class="doc_code">
 544 <pre>
 545 DW_ATE_address       = 1
 546 DW_ATE_boolean       = 2
 547 DW_ATE_float         = 4
 548 DW_ATE_signed        = 5
 549 DW_ATE_signed_char   = 6
 550 DW_ATE_unsigned      = 7
 551 DW_ATE_unsigned_char = 8
 552 </pre>
 553 </div>
 554
 555 </div>
 556
 557 <!-- ======================================================================= -->
 558 <h4>
 559   <a name="format_derived_type">Derived type descriptors</a>
 560 </h4>
 561
 562 <div>
 563
 564 <div class="doc_code">
 565 <pre>
 566 !5 = metadata !{
 567   i32,      ;; Tag (see below)
 568   metadata, ;; Reference to context
 569   metadata, ;; Name (may be "" for anonymous types)
 570   metadata, ;; Reference to file where defined (may be NULL)
 571   i32,      ;; Line number where defined (may be 0)
 572   i64,      ;; Size in bits
 573   i64,      ;; Alignment in bits
 574   i64,      ;; Offset in bits
 575   i32,      ;; Flags to encode attributes, e.g. private
 576   metadata, ;; Reference to type derived from
 577   metadata, ;; (optional) Name of the Objective C property associated with
 578             ;; Objective-C an ivar
 579   metadata, ;; (optional) Name of the Objective C property getter selector.
 580   metadata, ;; (optional) Name of the Objective C property setter selector.
 581   i32       ;; (optional) Objective C property attributes.
 582 }
 583 </pre>
 584 </div>
 585
 586 <p>These descriptors are used to define types derived from other types.  The
 587 value of the tag varies depending on the meaning.  The following are possible
 588 tag values:</p>
 589
 590 <div class="doc_code">
 591 <pre>
 592 DW_TAG_formal_parameter = 5
 593 DW_TAG_member           = 13
 594 DW_TAG_pointer_type     = 15
 595 DW_TAG_reference_type   = 16
 596 DW_TAG_typedef          = 22
 597 DW_TAG_const_type       = 38
 598 DW_TAG_volatile_type    = 53
 599 DW_TAG_restrict_type    = 55
 600 </pre>
 601 </div>
 602
 603 <p><tt>DW_TAG_member</tt> is used to define a member of
 604    a <a href="#format_composite_type">composite type</a>
 605    or <a href="#format_subprograms">subprogram</a>.  The type of the member is
 606    the <a href="#format_derived_type">derived
 607    type</a>. <tt>DW_TAG_formal_parameter</tt> is used to define a member which
 608    is a formal argument of a subprogram.</p>
 609
 610 <p><tt>DW_TAG_typedef</tt> is used to provide a name for the derived type.</p>
 611
 612 <p><tt>DW_TAG_pointer_type</tt>, <tt>DW_TAG_reference_type</tt>,
 613    <tt>DW_TAG_const_type</tt>, <tt>DW_TAG_volatile_type</tt> and
 614    <tt>DW_TAG_restrict_type</tt> are used to qualify
 615    the <a href="#format_derived_type">derived type</a>. </p>
 616
 617 <p><a href="#format_derived_type">Derived type</a> location can be determined
 618    from the context and line number.  The size, alignment and offset are
 619    expressed in bits and can be 64 bit values.  The alignment is used to round
 620    the offset when embedded in a <a href="#format_composite_type">composite
 621    type</a> (example to keep float doubles on 64 bit boundaries.) The offset is
 622    the bit offset if embedded in a <a href="#format_composite_type">composite
 623    type</a>.</p>
 624
 625 <p>Note that the <tt>void *</tt> type is expressed as a type derived from NULL.
 626 </p>
 627
 628 </div>
 629
 630 <!-- ======================================================================= -->
 631 <h4>
 632   <a name="format_composite_type">Composite type descriptors</a>
 633 </h4>
 634
 635 <div>
 636
 637 <div class="doc_code">
 638 <pre>
 639 !6 = metadata !{
 640   i32,      ;; Tag (see below)
 641   metadata, ;; Reference to context
 642   metadata, ;; Name (may be "" for anonymous types)
 643   metadata, ;; Reference to file where defined (may be NULL)
 644   i32,      ;; Line number where defined (may be 0)
 645   i64,      ;; Size in bits
 646   i64,      ;; Alignment in bits
 647   i64,      ;; Offset in bits
 648   i32,      ;; Flags
 649   metadata, ;; Reference to type derived from
 650   metadata, ;; Reference to array of member descriptors
 651   i32       ;; Runtime languages
 652 }
 653 </pre>
 654 </div>
 655
 656 <p>These descriptors are used to define types that are composed of 0 or more
 657 elements.  The value of the tag varies depending on the meaning.  The following
 658 are possible tag values:</p>
 659
 660 <div class="doc_code">
 661 <pre>
 662 DW_TAG_array_type       = 1
 663 DW_TAG_enumeration_type = 4
 664 DW_TAG_structure_type   = 19
 665 DW_TAG_union_type       = 23
 666 DW_TAG_vector_type      = 259
 667 DW_TAG_subroutine_type  = 21
 668 DW_TAG_inheritance      = 28
 669 </pre>
 670 </div>
 671
 672 <p>The vector flag indicates that an array type is a native packed vector.</p>
 673
 674 <p>The members of array types (tag = <tt>DW_TAG_array_type</tt>) or vector types
 675    (tag = <tt>DW_TAG_vector_type</tt>) are <a href="#format_subrange">subrange
 676    descriptors</a>, each representing the range of subscripts at that level of
 677    indexing.</p>
 678
 679 <p>The members of enumeration types (tag = <tt>DW_TAG_enumeration_type</tt>) are
 680    <a href="#format_enumeration">enumerator descriptors</a>, each representing
 681    the definition of enumeration value for the set. All enumeration type
 682    descriptors are collected by named metadata <tt>!llvm.dbg.enum</tt>.</p>
 683
 684 <p>The members of structure (tag = <tt>DW_TAG_structure_type</tt>) or union (tag
 685    = <tt>DW_TAG_union_type</tt>) types are any one of
 686    the <a href="#format_basic_type">basic</a>,
 687    <a href="#format_derived_type">derived</a>
 688    or <a href="#format_composite_type">composite</a> type descriptors, each
 689    representing a field member of the structure or union.</p>
 690
 691 <p>For C++ classes (tag = <tt>DW_TAG_structure_type</tt>), member descriptors
 692    provide information about base classes, static members and member
 693    functions. If a member is a <a href="#format_derived_type">derived type
 694    descriptor</a> and has a tag of <tt>DW_TAG_inheritance</tt>, then the type
 695    represents a base class. If the member of is
 696    a <a href="#format_global_variables">global variable descriptor</a> then it
 697    represents a static member.  And, if the member is
 698    a <a href="#format_subprograms">subprogram descriptor</a> then it represents
 699    a member function.  For static members and member
 700    functions, <tt>getName()</tt> returns the members link or the C++ mangled
 701    name.  <tt>getDisplayName()</tt> the simplied version of the name.</p>
 702
 703 <p>The first member of subroutine (tag = <tt>DW_TAG_subroutine_type</tt>) type
 704    elements is the return type for the subroutine.  The remaining elements are
 705    the formal arguments to the subroutine.</p>
 706
 707 <p><a href="#format_composite_type">Composite type</a> location can be
 708    determined from the context and line number.  The size, alignment and
 709    offset are expressed in bits and can be 64 bit values.  The alignment is used
 710    to round the offset when embedded in
 711    a <a href="#format_composite_type">composite type</a> (as an example, to keep
 712    float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
 713    in a <a href="#format_composite_type">composite type</a>.</p>
 714
 715 </div>
 716
 717 <!-- ======================================================================= -->
 718 <h4>
 719   <a name="format_subrange">Subrange descriptors</a>
 720 </h4>
 721
 722 <div>
 723
 724 <div class="doc_code">
 725 <pre>
 726 !42 = metadata !{
 727   i32,    ;; Tag = 33 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a> (DW_TAG_subrange_type)
 728   i64,    ;; Low value
 729   i64     ;; High value
 730 }
 731 </pre>
 732 </div>
 733
 734 <p>These descriptors are used to define ranges of array subscripts for an array
 735    <a href="#format_composite_type">composite type</a>.  The low value defines
 736    the lower bounds typically zero for C/C++.  The high value is the upper
 737    bounds.  Values are 64 bit.  High - low + 1 is the size of the array.  If low
 738    > high the array bounds are not included in generated debugging information.
 739 </p>
 740
 741 </div>
 742
 743 <!-- ======================================================================= -->
 744 <h4>
 745   <a name="format_enumeration">Enumerator descriptors</a>
 746 </h4>
 747
 748 <div>
 749
 750 <div class="doc_code">
 751 <pre>
 752 !6 = metadata !{
 753   i32,      ;; Tag = 40 + <a href="#LLVMDebugVersion">LLVMDebugVersion</a>
 754             ;; (DW_TAG_enumerator)
 755   metadata, ;; Name
 756   i64       ;; Value
 757 }
 758 </pre>
 759 </div>
 760
 761 <p>These descriptors are used to define members of an
 762    enumeration <a href="#format_composite_type">composite type</a>, it
 763    associates the name to the value.</p>
 764
 765 </div>
 766
 767 <!-- ======================================================================= -->
 768 <h4>
 769   <a name="format_variables">Local variables</a>
 770 </h4>
 771
 772 <div>
 773
 774 <div class="doc_code">
 775 <pre>
 776 !7 = metadata !{
 777   i32,      ;; Tag (see below)
 778   metadata, ;; Context
 779   metadata, ;; Name
 780   metadata, ;; Reference to file where defined
 781   i32,      ;; 24 bit - Line number where defined
 782             ;; 8 bit - Argument number. 1 indicates 1st argument.
 783   metadata, ;; Type descriptor
 784   i32,      ;; flags
 785   metadata  ;; (optional) Reference to inline location
 786 }
 787 </pre>
 788 </div>
 789
 790 <p>These descriptors are used to define variables local to a sub program.  The
 791    value of the tag depends on the usage of the variable:</p>
 792
 793 <div class="doc_code">
 794 <pre>
 795 DW_TAG_auto_variable   = 256
 796 DW_TAG_arg_variable    = 257
 797 DW_TAG_return_variable = 258
 798 </pre>
 799 </div>
 800
 801 <p>An auto variable is any variable declared in the body of the function.  An
 802    argument variable is any variable that appears as a formal argument to the
 803    function.  A return variable is used to track the result of a function and
 804    has no source correspondent.</p>
 805
 806 <p>The context is either the subprogram or block where the variable is defined.
 807    Name the source variable name.  Context and line indicate where the
 808    variable was defined. Type descriptor defines the declared type of the
 809    variable.</p>
 810
 811 </div>
 812
 813 </div>
 814
 815 <!-- ======================================================================= -->
 816 <h3>
 817   <a name="format_common_intrinsics">Debugger intrinsic functions</a>
 818 </h3>
 819
 820 <div>
 821
 822 <p>LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to
 823    provide debug information at various points in generated code.</p>
 824
 825 <!-- ======================================================================= -->
 826 <h4>
 827   <a name="format_common_declare">llvm.dbg.declare</a>
 828 </h4>
 829
 830 <div>
 831 <pre>
 832   void %<a href="#format_common_declare">llvm.dbg.declare</a>(metadata, metadata)
 833 </pre>
 834
 835 <p>This intrinsic provides information about a local element (ex. variable.) The
 836    first argument is metadata holding alloca for the variable. The
 837    second argument is metadata containing description of the variable. </p>
 838 </div>
 839
 840 <!-- ======================================================================= -->
 841 <h4>
 842   <a name="format_common_value">llvm.dbg.value</a>
 843 </h4>
 844
 845 <div>
 846 <pre>
 847   void %<a href="#format_common_value">llvm.dbg.value</a>(metadata, i64, metadata)
 848 </pre>
 849
 850 <p>This intrinsic provides information when a user source variable is set to a
 851    new value.  The first argument is the new value (wrapped as metadata).  The
 852    second argument is the offset in the user source variable where the new value
 853    is written.  The third argument is metadata containing description of the
 854    user source variable. </p>
 855 </div>
 856
 857 </div>
 858
 859 <!-- ======================================================================= -->
 860 <h3>
 861   <a name="format_common_lifetime">Object lifetimes and scoping</a>
 862 </h3>
 863
 864 <div>
 865 <p>In many languages, the local variables in functions can have their lifetimes
 866    or scopes limited to a subset of a function.  In the C family of languages,
 867    for example, variables are only live (readable and writable) within the
 868    source block that they are defined in.  In functional languages, values are
 869    only readable after they have been defined.  Though this is a very obvious
 870    concept, it is non-trivial to model in LLVM, because it has no notion of
 871    scoping in this sense, and does not want to be tied to a language's scoping
 872    rules.</p>
 873
 874 <p>In order to handle this, the LLVM debug format uses the metadata attached to
 875    llvm instructions to encode line number and scoping information. Consider
 876    the following C fragment, for example:</p>
 877
 878 <div class="doc_code">
 879 <pre>
 880 1.  void foo() {
 881 2.    int X = 21;
 882 3.    int Y = 22;
 883 4.    {
 884 5.      int Z = 23;
 885 6.      Z = X;
 886 7.    }
 887 8.    X = Y;
 888 9.  }
 889 </pre>
 890 </div>
 891
 892 <p>Compiled to LLVM, this function would be represented like this:</p>
 893
 894 <div class="doc_code">
 895 <pre>
 896 define void @foo() nounwind ssp {
 897 entry:
 898   %X = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 899   %Y = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=4]
 900   %Z = alloca i32, align 4                        ; &lt;i32*&gt; [#uses=3]
 901   %0 = bitcast i32* %X to {}*                     ; &lt;{}*&gt; [#uses=1]
 902   call void @llvm.dbg.declare(metadata !{i32 * %X}, metadata !0), !dbg !7
 903   store i32 21, i32* %X, !dbg !8
 904   %1 = bitcast i32* %Y to {}*                     ; &lt;{}*&gt; [#uses=1]
 905   call void @llvm.dbg.declare(metadata !{i32 * %Y}, metadata !9), !dbg !10
 906   store i32 22, i32* %Y, !dbg !11
 907   %2 = bitcast i32* %Z to {}*                     ; &lt;{}*&gt; [#uses=1]
 908   call void @llvm.dbg.declare(metadata !{i32 * %Z}, metadata !12), !dbg !14
 909   store i32 23, i32* %Z, !dbg !15
 910   %tmp = load i32* %X, !dbg !16                   ; &lt;i32&gt; [#uses=1]
 911   %tmp1 = load i32* %Y, !dbg !16                  ; &lt;i32&gt; [#uses=1]
 912   %add = add nsw i32 %tmp, %tmp1, !dbg !16        ; &lt;i32&gt; [#uses=1]
 913   store i32 %add, i32* %Z, !dbg !16
 914   %tmp2 = load i32* %Y, !dbg !17                  ; &lt;i32&gt; [#uses=1]
 915   store i32 %tmp2, i32* %X, !dbg !17
 916   ret void, !dbg !18
 917 }
 918
 919 declare void @llvm.dbg.declare(metadata, metadata) nounwind readnone
 920
 921 !0 = metadata !{i32 459008, metadata !1, metadata !"X",
 922                 metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ]
 923 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 924 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo",
 925                metadata !"foo", metadata !3, i32 1, metadata !4,
 926                i1 false, i1 true}; [DW_TAG_subprogram ]
 927 !3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c",
 928                 metadata !"/private/tmp", metadata !"clang 1.1", i1 true,
 929                 i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ]
 930 !4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0,
 931                 i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ]
 932 !5 = metadata !{null}
 933 !6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0,
 934                 i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ]
 935 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 936 !8 = metadata !{i32 2, i32 3, metadata !1, null}
 937 !9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3,
 938                 metadata !6}; [ DW_TAG_auto_variable ]
 939 !10 = metadata !{i32 3, i32 7, metadata !1, null}
 940 !11 = metadata !{i32 3, i32 3, metadata !1, null}
 941 !12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5,
 942                  metadata !6}; [ DW_TAG_auto_variable ]
 943 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
 944 !14 = metadata !{i32 5, i32 9, metadata !13, null}
 945 !15 = metadata !{i32 5, i32 5, metadata !13, null}
 946 !16 = metadata !{i32 6, i32 5, metadata !13, null}
 947 !17 = metadata !{i32 8, i32 3, metadata !1, null}
 948 !18 = metadata !{i32 9, i32 1, metadata !2, null}
 949 </pre>
 950 </div>
 951
 952 <p>This example illustrates a few important details about LLVM debugging
 953    information. In particular, it shows how the <tt>llvm.dbg.declare</tt>
 954    intrinsic and location information, which are attached to an instruction,
 955    are applied together to allow a debugger to analyze the relationship between
 956    statements, variable definitions, and the code used to implement the
 957    function.</p>
 958
 959 <div class="doc_code">
 960 <pre>
 961 call void @llvm.dbg.declare(metadata, metadata !0), !dbg !7
 962 </pre>
 963 </div>
 964
 965 <p>The first intrinsic
 966    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
 967    encodes debugging information for the variable <tt>X</tt>. The metadata
 968    <tt>!dbg !7</tt> attached to the intrinsic provides scope information for the
 969    variable <tt>X</tt>.</p>
 970
 971 <div class="doc_code">
 972 <pre>
 973 !7 = metadata !{i32 2, i32 7, metadata !1, null}
 974 !1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ]
 975 !2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo",
 976                 metadata !"foo", metadata !"foo", metadata !3, i32 1,
 977                 metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ]
 978 </pre>
 979 </div>
 980
 981 <p>Here <tt>!7</tt> is metadata providing location information. It has four
 982    fields: line number, column number, scope, and original scope. The original
 983    scope represents inline location if this instruction is inlined inside a
 984    caller, and is null otherwise. In this example, scope is encoded by
 985    <tt>!1</tt>. <tt>!1</tt> represents a lexical block inside the scope
 986    <tt>!2</tt>, where <tt>!2</tt> is a
 987    <a href="#format_subprograms">subprogram descriptor</a>. This way the
 988    location information attached to the intrinsics indicates that the
 989    variable <tt>X</tt> is declared at line number 2 at a function level scope in
 990    function <tt>foo</tt>.</p>
 991
 992 <p>Now lets take another example.</p>
 993
 994 <div class="doc_code">
 995 <pre>
 996 call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14
 997 </pre>
 998 </div>
 999
1000 <p>The second intrinsic
1001    <tt>%<a href="#format_common_declare">llvm.dbg.declare</a></tt>
1002    encodes debugging information for variable <tt>Z</tt>. The metadata
1003    <tt>!dbg !14</tt> attached to the intrinsic provides scope information for
1004    the variable <tt>Z</tt>.</p>
1005
1006 <div class="doc_code">
1007 <pre>
1008 !13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ]
1009 !14 = metadata !{i32 5, i32 9, metadata !13, null}
1010 </pre>
1011 </div>
1012
1013 <p>Here <tt>!14</tt> indicates that <tt>Z</tt> is declared at line number 5 and
1014    column number 9 inside of lexical scope <tt>!13</tt>. The lexical scope
1015    itself resides inside of lexical scope <tt>!1</tt> described above.</p>
1016
1017 <p>The scope information attached with each instruction provides a
1018    straightforward way to find instructions covered by a scope.</p>
1019
1020 </div>
1021
1022 </div>
1023
1024 <!-- *********************************************************************** -->
1025 <h2>
1026   <a name="ccxx_frontend">C/C++ front-end specific debug information</a>
1027 </h2>
1028 <!-- *********************************************************************** -->
1029
1030 <div>
1031
1032 <p>The C and C++ front-ends represent information about the program in a format
1033    that is effectively identical
1034    to <a href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> in
1035    terms of information content.  This allows code generators to trivially
1036    support native debuggers by generating standard dwarf information, and
1037    contains enough information for non-dwarf targets to translate it as
1038    needed.</p>
1039
1040 <p>This section describes the forms used to represent C and C++ programs. Other
1041    languages could pattern themselves after this (which itself is tuned to
1042    representing programs in the same way that DWARF 3 does), or they could
1043    choose to provide completely different forms if they don't fit into the DWARF
1044    model.  As support for debugging information gets added to the various LLVM
1045    source-language front-ends, the information used should be documented
1046    here.</p>
1047
1048 <p>The following sections provide examples of various C/C++ constructs and the
1049    debug information that would best describe those constructs.</p>
1050
1051 <!-- ======================================================================= -->
1052 <h3>
1053   <a name="ccxx_compile_units">C/C++ source file information</a>
1054 </h3>
1055
1056 <div>
1057
1058 <p>Given the source files <tt>MySource.cpp</tt> and <tt>MyHeader.h</tt> located
1059    in the directory <tt>/Users/mine/sources</tt>, the following code:</p>
1060
1061 <div class="doc_code">
1062 <pre>
1063 #include "MyHeader.h"
1064
1065 int main(int argc, char *argv[]) {
1066   return 0;
1067 }
1068 </pre>
1069 </div>
1070
1071 <p>a C/C++ front-end would generate the following descriptors:</p>
1072
1073 <div class="doc_code">
1074 <pre>
1075 ...
1076 ;;
1077 ;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
1078 ;;
1079 !2 = metadata !{
1080   i32 524305,    ;; Tag
1081   i32 0,         ;; Unused
1082   i32 4,         ;; Language Id
1083   metadata !"MySource.cpp",
1084   metadata !"/Users/mine/sources",
1085   metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)",
1086   i1 true,       ;; Main Compile Unit
1087   i1 false,      ;; Optimized compile unit
1088   metadata !"",  ;; Compiler flags
1089   i32 0}         ;; Runtime version
1090
1091 ;;
1092 ;; Define the file for the file "/Users/mine/sources/MySource.cpp".
1093 ;;
1094 !1 = metadata !{
1095   i32 524329,    ;; Tag
1096   metadata !"MySource.cpp",
1097   metadata !"/Users/mine/sources",
1098   metadata !2    ;; Compile unit
1099 }
1100
1101 ;;
1102 ;; Define the file for the file "/Users/mine/sources/Myheader.h"
1103 ;;
1104 !3 = metadata !{
1105   i32 524329,    ;; Tag
1106   metadata !"Myheader.h"
1107   metadata !"/Users/mine/sources",
1108   metadata !2    ;; Compile unit
1109 }
1110
1111 ...
1112 </pre>
1113 </div>
1114
1115 <p>llvm::Instruction provides easy access to metadata attached with an
1116 instruction. One can extract line number information encoded in LLVM IR
1117 using <tt>Instruction::getMetadata()</tt> and
1118 <tt>DILocation::getLineNumber()</tt>.
1119 <pre>
1120  if (MDNode *N = I->getMetadata("dbg")) {  // Here I is an LLVM instruction
1121    DILocation Loc(N);                      // DILocation is in DebugInfo.h
1122    unsigned Line = Loc.getLineNumber();
1123    StringRef File = Loc.getFilename();
1124    StringRef Dir = Loc.getDirectory();
1125  }
1126 </pre>
1127 </div>
1128
1129 <!-- ======================================================================= -->
1130 <h3>
1131   <a name="ccxx_global_variable">C/C++ global variable information</a>
1132 </h3>
1133
1134 <div>
1135
1136 <p>Given an integer global variable declared as follows:</p>
1137
1138 <div class="doc_code">
1139 <pre>
1140 int MyGlobal = 100;
1141 </pre>
1142 </div>
1143
1144 <p>a C/C++ front-end would generate the following descriptors:</p>
1145
1146 <div class="doc_code">
1147 <pre>
1148 ;;
1149 ;; Define the global itself.
1150 ;;
1151 %MyGlobal = global int 100
1152 ...
1153 ;;
1154 ;; List of debug info of globals
1155 ;;
1156 !llvm.dbg.gv = !{!0}
1157
1158 ;;
1159 ;; Define the global variable descriptor.  Note the reference to the global
1160 ;; variable anchor and the global variable itself.
1161 ;;
1162 !0 = metadata !{
1163   i32 524340,              ;; Tag
1164   i32 0,                   ;; Unused
1165   metadata !1,             ;; Context
1166   metadata !"MyGlobal",    ;; Name
1167   metadata !"MyGlobal",    ;; Display Name
1168   metadata !"MyGlobal",    ;; Linkage Name
1169   metadata !3,             ;; Compile Unit
1170   i32 1,                   ;; Line Number
1171   metadata !4,             ;; Type
1172   i1 false,                ;; Is a local variable
1173   i1 true,                 ;; Is this a definition
1174   i32* @MyGlobal           ;; The global variable
1175 }
1176
1177 ;;
1178 ;; Define the basic type of 32 bit signed integer.  Note that since int is an
1179 ;; intrinsic type the source file is NULL and line 0.
1180 ;;
1181 !4 = metadata !{
1182   i32 524324,              ;; Tag
1183   metadata !1,             ;; Context
1184   metadata !"int",         ;; Name
1185   metadata !1,             ;; File
1186   i32 0,                   ;; Line number
1187   i64 32,                  ;; Size in Bits
1188   i64 32,                  ;; Align in Bits
1189   i64 0,                   ;; Offset in Bits
1190   i32 0,                   ;; Flags
1191   i32 5                    ;; Encoding
1192 }
1193
1194 </pre>
1195 </div>
1196
1197 </div>
1198
1199 <!-- ======================================================================= -->
1200 <h3>
1201   <a name="ccxx_subprogram">C/C++ function information</a>
1202 </h3>
1203
1204 <div>
1205
1206 <p>Given a function declared as follows:</p>
1207
1208 <div class="doc_code">
1209 <pre>
1210 int main(int argc, char *argv[]) {
1211   return 0;
1212 }
1213 </pre>
1214 </div>
1215
1216 <p>a C/C++ front-end would generate the following descriptors:</p>
1217
1218 <div class="doc_code">
1219 <pre>
1220 ;;
1221 ;; Define the anchor for subprograms.  Note that the second field of the
1222 ;; anchor is 46, which is the same as the tag for subprograms
1223 ;; (46 = DW_TAG_subprogram.)
1224 ;;
1225 !6 = metadata !{
1226   i32 524334,        ;; Tag
1227   i32 0,             ;; Unused
1228   metadata !1,       ;; Context
1229   metadata !"main",  ;; Name
1230   metadata !"main",  ;; Display name
1231   metadata !"main",  ;; Linkage name
1232   metadata !1,       ;; File
1233   i32 1,             ;; Line number
1234   metadata !4,       ;; Type
1235   i1 false,          ;; Is local
1236   i1 true,           ;; Is definition
1237   i32 0,             ;; Virtuality attribute, e.g. pure virtual function
1238   i32 0,             ;; Index into virtual table for C++ methods
1239   i32 0,             ;; Type that holds virtual table.
1240   i32 0,             ;; Flags
1241   i1 false,          ;; True if this function is optimized
1242   Function *,        ;; Pointer to llvm::Function
1243   null               ;; Function template parameters
1244 }
1245 ;;
1246 ;; Define the subprogram itself.
1247 ;;
1248 define i32 @main(i32 %argc, i8** %argv) {
1249 ...
1250 }
1251 </pre>
1252 </div>
1253
1254 </div>
1255
1256 <!-- ======================================================================= -->
1257 <h3>
1258   <a name="ccxx_basic_types">C/C++ basic types</a>
1259 </h3>
1260
1261 <div>
1262
1263 <p>The following are the basic type descriptors for C/C++ core types:</p>
1264
1265 <!-- ======================================================================= -->
1266 <h4>
1267   <a name="ccxx_basic_type_bool">bool</a>
1268 </h4>
1269
1270 <div>
1271
1272 <div class="doc_code">
1273 <pre>
1274 !2 = metadata !{
1275   i32 524324,        ;; Tag
1276   metadata !1,       ;; Context
1277   metadata !"bool",  ;; Name
1278   metadata !1,       ;; File
1279   i32 0,             ;; Line number
1280   i64 8,             ;; Size in Bits
1281   i64 8,             ;; Align in Bits
1282   i64 0,             ;; Offset in Bits
1283   i32 0,             ;; Flags
1284   i32 2              ;; Encoding
1285 }
1286 </pre>
1287 </div>
1288
1289 </div>
1290
1291 <!-- ======================================================================= -->
1292 <h4>
1293   <a name="ccxx_basic_char">char</a>
1294 </h4>
1295
1296 <div>
1297
1298 <div class="doc_code">
1299 <pre>
1300 !2 = metadata !{
1301   i32 524324,        ;; Tag
1302   metadata !1,       ;; Context
1303   metadata !"char",  ;; Name
1304   metadata !1,       ;; File
1305   i32 0,             ;; Line number
1306   i64 8,             ;; Size in Bits
1307   i64 8,             ;; Align in Bits
1308   i64 0,             ;; Offset in Bits
1309   i32 0,             ;; Flags
1310   i32 6              ;; Encoding
1311 }
1312 </pre>
1313 </div>
1314
1315 </div>
1316
1317 <!-- ======================================================================= -->
1318 <h4>
1319   <a name="ccxx_basic_unsigned_char">unsigned char</a>
1320 </h4>
1321
1322 <div>
1323
1324 <div class="doc_code">
1325 <pre>
1326 !2 = metadata !{
1327   i32 524324,        ;; Tag
1328   metadata !1,       ;; Context
1329   metadata !"unsigned char",
1330   metadata !1,       ;; File
1331   i32 0,             ;; Line number
1332   i64 8,             ;; Size in Bits
1333   i64 8,             ;; Align in Bits
1334   i64 0,             ;; Offset in Bits
1335   i32 0,             ;; Flags
1336   i32 8              ;; Encoding
1337 }
1338 </pre>
1339 </div>
1340
1341 </div>
1342
1343 <!-- ======================================================================= -->
1344 <h4>
1345   <a name="ccxx_basic_short">short</a>
1346 </h4>
1347
1348 <div>
1349
1350 <div class="doc_code">
1351 <pre>
1352 !2 = metadata !{
1353   i32 524324,        ;; Tag
1354   metadata !1,       ;; Context
1355   metadata !"short int",
1356   metadata !1,       ;; File
1357   i32 0,             ;; Line number
1358   i64 16,            ;; Size in Bits
1359   i64 16,            ;; Align in Bits
1360   i64 0,             ;; Offset in Bits
1361   i32 0,             ;; Flags
1362   i32 5              ;; Encoding
1363 }
1364 </pre>
1365 </div>
1366
1367 </div>
1368
1369 <!-- ======================================================================= -->
1370 <h4>
1371   <a name="ccxx_basic_unsigned_short">unsigned short</a>
1372 </h4>
1373
1374 <div>
1375
1376 <div class="doc_code">
1377 <pre>
1378 !2 = metadata !{
1379   i32 524324,        ;; Tag
1380   metadata !1,       ;; Context
1381   metadata !"short unsigned int",
1382   metadata !1,       ;; File
1383   i32 0,             ;; Line number
1384   i64 16,            ;; Size in Bits
1385   i64 16,            ;; Align in Bits
1386   i64 0,             ;; Offset in Bits
1387   i32 0,             ;; Flags
1388   i32 7              ;; Encoding
1389 }
1390 </pre>
1391 </div>
1392
1393 </div>
1394
1395 <!-- ======================================================================= -->
1396 <h4>
1397   <a name="ccxx_basic_int">int</a>
1398 </h4>
1399
1400 <div>
1401
1402 <div class="doc_code">
1403 <pre>
1404 !2 = metadata !{
1405   i32 524324,        ;; Tag
1406   metadata !1,       ;; Context
1407   metadata !"int",   ;; Name
1408   metadata !1,       ;; File
1409   i32 0,             ;; Line number
1410   i64 32,            ;; Size in Bits
1411   i64 32,            ;; Align in Bits
1412   i64 0,             ;; Offset in Bits
1413   i32 0,             ;; Flags
1414   i32 5              ;; Encoding
1415 }
1416 </pre></div>
1417
1418 </div>
1419
1420 <!-- ======================================================================= -->
1421 <h4>
1422   <a name="ccxx_basic_unsigned_int">unsigned int</a>
1423 </h4>
1424
1425 <div>
1426
1427 <div class="doc_code">
1428 <pre>
1429 !2 = metadata !{
1430   i32 524324,        ;; Tag
1431   metadata !1,       ;; Context
1432   metadata !"unsigned int",
1433   metadata !1,       ;; File
1434   i32 0,             ;; Line number
1435   i64 32,            ;; Size in Bits
1436   i64 32,            ;; Align in Bits
1437   i64 0,             ;; Offset in Bits
1438   i32 0,             ;; Flags
1439   i32 7              ;; Encoding
1440 }
1441 </pre>
1442 </div>
1443
1444 </div>
1445
1446 <!-- ======================================================================= -->
1447 <h4>
1448   <a name="ccxx_basic_long_long">long long</a>
1449 </h4>
1450
1451 <div>
1452
1453 <div class="doc_code">
1454 <pre>
1455 !2 = metadata !{
1456   i32 524324,        ;; Tag
1457   metadata !1,       ;; Context
1458   metadata !"long long int",
1459   metadata !1,       ;; File
1460   i32 0,             ;; Line number
1461   i64 64,            ;; Size in Bits
1462   i64 64,            ;; Align in Bits
1463   i64 0,             ;; Offset in Bits
1464   i32 0,             ;; Flags
1465   i32 5              ;; Encoding
1466 }
1467 </pre>
1468 </div>
1469
1470 </div>
1471
1472 <!-- ======================================================================= -->
1473 <h4>
1474   <a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
1475 </h4>
1476
1477 <div>
1478
1479 <div class="doc_code">
1480 <pre>
1481 !2 = metadata !{
1482   i32 524324,        ;; Tag
1483   metadata !1,       ;; Context
1484   metadata !"long long unsigned int",
1485   metadata !1,       ;; File
1486   i32 0,             ;; Line number
1487   i64 64,            ;; Size in Bits
1488   i64 64,            ;; Align in Bits
1489   i64 0,             ;; Offset in Bits
1490   i32 0,             ;; Flags
1491   i32 7              ;; Encoding
1492 }
1493 </pre>
1494 </div>
1495
1496 </div>
1497
1498 <!-- ======================================================================= -->
1499 <h4>
1500   <a name="ccxx_basic_float">float</a>
1501 </h4>
1502
1503 <div>
1504
1505 <div class="doc_code">
1506 <pre>
1507 !2 = metadata !{
1508   i32 524324,        ;; Tag
1509   metadata !1,       ;; Context
1510   metadata !"float",
1511   metadata !1,       ;; File
1512   i32 0,             ;; Line number
1513   i64 32,            ;; Size in Bits
1514   i64 32,            ;; Align in Bits
1515   i64 0,             ;; Offset in Bits
1516   i32 0,             ;; Flags
1517   i32 4              ;; Encoding
1518 }
1519 </pre>
1520 </div>
1521
1522 </div>
1523
1524 <!-- ======================================================================= -->
1525 <h4>
1526   <a name="ccxx_basic_double">double</a>
1527 </h4>
1528
1529 <div>
1530
1531 <div class="doc_code">
1532 <pre>
1533 !2 = metadata !{
1534   i32 524324,        ;; Tag
1535   metadata !1,       ;; Context
1536   metadata !"double",;; Name
1537   metadata !1,       ;; File
1538   i32 0,             ;; Line number
1539   i64 64,            ;; Size in Bits
1540   i64 64,            ;; Align in Bits
1541   i64 0,             ;; Offset in Bits
1542   i32 0,             ;; Flags
1543   i32 4              ;; Encoding
1544 }
1545 </pre>
1546 </div>
1547
1548 </div>
1549
1550 </div>
1551
1552 <!-- ======================================================================= -->
1553 <h3>
1554   <a name="ccxx_derived_types">C/C++ derived types</a>
1555 </h3>
1556
1557 <div>
1558
1559 <p>Given the following as an example of C/C++ derived type:</p>
1560
1561 <div class="doc_code">
1562 <pre>
1563 typedef const int *IntPtr;
1564 </pre>
1565 </div>
1566
1567 <p>a C/C++ front-end would generate the following descriptors:</p>
1568
1569 <div class="doc_code">
1570 <pre>
1571 ;;
1572 ;; Define the typedef "IntPtr".
1573 ;;
1574 !2 = metadata !{
1575   i32 524310,          ;; Tag
1576   metadata !1,         ;; Context
1577   metadata !"IntPtr",  ;; Name
1578   metadata !3,         ;; File
1579   i32 0,               ;; Line number
1580   i64 0,               ;; Size in bits
1581   i64 0,               ;; Align in bits
1582   i64 0,               ;; Offset in bits
1583   i32 0,               ;; Flags
1584   metadata !4          ;; Derived From type
1585 }
1586
1587 ;;
1588 ;; Define the pointer type.
1589 ;;
1590 !4 = metadata !{
1591   i32 524303,          ;; Tag
1592   metadata !1,         ;; Context
1593   metadata !"",        ;; Name
1594   metadata !1,         ;; File
1595   i32 0,               ;; Line number
1596   i64 64,              ;; Size in bits
1597   i64 64,              ;; Align in bits
1598   i64 0,               ;; Offset in bits
1599   i32 0,               ;; Flags
1600   metadata !5          ;; Derived From type
1601 }
1602 ;;
1603 ;; Define the const type.
1604 ;;
1605 !5 = metadata !{
1606   i32 524326,          ;; Tag
1607   metadata !1,         ;; Context
1608   metadata !"",        ;; Name
1609   metadata !1,         ;; File
1610   i32 0,               ;; Line number
1611   i64 32,              ;; Size in bits
1612   i64 32,              ;; Align in bits
1613   i64 0,               ;; Offset in bits
1614   i32 0,               ;; Flags
1615   metadata !6          ;; Derived From type
1616 }
1617 ;;
1618 ;; Define the int type.
1619 ;;
1620 !6 = metadata !{
1621   i32 524324,          ;; Tag
1622   metadata !1,         ;; Context
1623   metadata !"int",     ;; Name
1624   metadata !1,         ;; File
1625   i32 0,               ;; Line number
1626   i64 32,              ;; Size in bits
1627   i64 32,              ;; Align in bits
1628   i64 0,               ;; Offset in bits
1629   i32 0,               ;; Flags
1630   5                    ;; Encoding
1631 }
1632 </pre>
1633 </div>
1634
1635 </div>
1636
1637 <!-- ======================================================================= -->
1638 <h3>
1639   <a name="ccxx_composite_types">C/C++ struct/union types</a>
1640 </h3>
1641
1642 <div>
1643
1644 <p>Given the following as an example of C/C++ struct type:</p>
1645
1646 <div class="doc_code">
1647 <pre>
1648 struct Color {
1649   unsigned Red;
1650   unsigned Green;
1651   unsigned Blue;
1652 };
1653 </pre>
1654 </div>
1655
1656 <p>a C/C++ front-end would generate the following descriptors:</p>
1657
1658 <div class="doc_code">
1659 <pre>
1660 ;;
1661 ;; Define basic type for unsigned int.
1662 ;;
1663 !5 = metadata !{
1664   i32 524324,        ;; Tag
1665   metadata !1,       ;; Context
1666   metadata !"unsigned int",
1667   metadata !1,       ;; File
1668   i32 0,             ;; Line number
1669   i64 32,            ;; Size in Bits
1670   i64 32,            ;; Align in Bits
1671   i64 0,             ;; Offset in Bits
1672   i32 0,             ;; Flags
1673   i32 7              ;; Encoding
1674 }
1675 ;;
1676 ;; Define composite type for struct Color.
1677 ;;
1678 !2 = metadata !{
1679   i32 524307,        ;; Tag
1680   metadata !1,       ;; Context
1681   metadata !"Color", ;; Name
1682   metadata !1,       ;; Compile unit
1683   i32 1,             ;; Line number
1684   i64 96,            ;; Size in bits
1685   i64 32,            ;; Align in bits
1686   i64 0,             ;; Offset in bits
1687   i32 0,             ;; Flags
1688   null,              ;; Derived From
1689   metadata !3,       ;; Elements
1690   i32 0              ;; Runtime Language
1691 }
1692
1693 ;;
1694 ;; Define the Red field.
1695 ;;
1696 !4 = metadata !{
1697   i32 524301,        ;; Tag
1698   metadata !1,       ;; Context
1699   metadata !"Red",   ;; Name
1700   metadata !1,       ;; File
1701   i32 2,             ;; Line number
1702   i64 32,            ;; Size in bits
1703   i64 32,            ;; Align in bits
1704   i64 0,             ;; Offset in bits
1705   i32 0,             ;; Flags
1706   metadata !5        ;; Derived From type
1707 }
1708
1709 ;;
1710 ;; Define the Green field.
1711 ;;
1712 !6 = metadata !{
1713   i32 524301,        ;; Tag
1714   metadata !1,       ;; Context
1715   metadata !"Green", ;; Name
1716   metadata !1,       ;; File
1717   i32 3,             ;; Line number
1718   i64 32,            ;; Size in bits
1719   i64 32,            ;; Align in bits
1720   i64 32,             ;; Offset in bits
1721   i32 0,             ;; Flags
1722   metadata !5        ;; Derived From type
1723 }
1724
1725 ;;
1726 ;; Define the Blue field.
1727 ;;
1728 !7 = metadata !{
1729   i32 524301,        ;; Tag
1730   metadata !1,       ;; Context
1731   metadata !"Blue",  ;; Name
1732   metadata !1,       ;; File
1733   i32 4,             ;; Line number
1734   i64 32,            ;; Size in bits
1735   i64 32,            ;; Align in bits
1736   i64 64,             ;; Offset in bits
1737   i32 0,             ;; Flags
1738   metadata !5        ;; Derived From type
1739 }
1740
1741 ;;
1742 ;; Define the array of fields used by the composite type Color.
1743 ;;
1744 !3 = metadata !{metadata !4, metadata !6, metadata !7}
1745 </pre>
1746 </div>
1747
1748 </div>
1749
1750 <!-- ======================================================================= -->
1751 <h3>
1752   <a name="ccxx_enumeration_types">C/C++ enumeration types</a>
1753 </h3>
1754
1755 <div>
1756
1757 <p>Given the following as an example of C/C++ enumeration type:</p>
1758
1759 <div class="doc_code">
1760 <pre>
1761 enum Trees {
1762   Spruce = 100,
1763   Oak = 200,
1764   Maple = 300
1765 };
1766 </pre>
1767 </div>
1768
1769 <p>a C/C++ front-end would generate the following descriptors:</p>
1770
1771 <div class="doc_code">
1772 <pre>
1773 ;;
1774 ;; Define composite type for enum Trees
1775 ;;
1776 !2 = metadata !{
1777   i32 524292,        ;; Tag
1778   metadata !1,       ;; Context
1779   metadata !"Trees", ;; Name
1780   metadata !1,       ;; File
1781   i32 1,             ;; Line number
1782   i64 32,            ;; Size in bits
1783   i64 32,            ;; Align in bits
1784   i64 0,             ;; Offset in bits
1785   i32 0,             ;; Flags
1786   null,              ;; Derived From type
1787   metadata !3,       ;; Elements
1788   i32 0              ;; Runtime language
1789 }
1790
1791 ;;
1792 ;; Define the array of enumerators used by composite type Trees.
1793 ;;
1794 !3 = metadata !{metadata !4, metadata !5, metadata !6}
1795
1796 ;;
1797 ;; Define Spruce enumerator.
1798 ;;
1799 !4 = metadata !{i32 524328, metadata !"Spruce", i64 100}
1800
1801 ;;
1802 ;; Define Oak enumerator.
1803 ;;
1804 !5 = metadata !{i32 524328, metadata !"Oak", i64 200}
1805
1806 ;;
1807 ;; Define Maple enumerator.
1808 ;;
1809 !6 = metadata !{i32 524328, metadata !"Maple", i64 300}
1810
1811 </pre>
1812 </div>
1813
1814 </div>
1815
1816 </div>
1817
1818
1819 <!-- *********************************************************************** -->
1820 <h2>
1821   <a name="llvmdwarfextension">Debugging information format</a>
1822 </h2>
1823 <!-- *********************************************************************** -->
1824 <div>
1825 <!-- ======================================================================= -->
1826 <h3>
1827   <a name="objcproperty">Debugging Information Extension for Objective C
1828 Properties</a></li>
1829 </h3>
1830 <div>
1831 <!-- *********************************************************************** -->
1832 <h4>
1833   <a name="objcpropertyintroduction">Introduction</a>
1834 </h4>
1835 <!-- *********************************************************************** -->
1836
1837 <div>
1838 <p>Objective C provides a simpler way to declare and define accessor methods
1839 using declared properties. The language provides features to declare a
1840 property and to let compiler synthesize accessor methods.
1841 </p>
1842
1843 <p>The debugger lets developer inspect Objective C interfaces and their
1844 instance variables and class variables. However, the debugger does not know
1845 anything about the properties defined in Objective C interfaces. The debugger
1846 consumes information generated by compiler in DWARF format. The format does
1847 not support encoding of Objective C properties. This proposal describes DWARF
1848 extensions to encode Objective C properties, which the debugger can use to let
1849 developers inspect Objective C properties.
1850 </p>
1851
1852 </div>
1853
1854
1855 <!-- *********************************************************************** -->
1856 <h4>
1857   <a name="objcpropertyproposal">Proposal</a>
1858 </h4>
1859 <!-- *********************************************************************** -->
1860
1861 <div>
1862 <p>Objective C properties exist separately from class members. A property
1863 can be defined only by &quot;setter&quot; and &quot;getter&quot; selectors, and
1864 be calculated anew on each access.  Or a property can just be a direct access
1865 to some declared ivar.  Finally it can have an ivar &quot;automatically
1866 synthesized&quot; for it by the compiler, in which case the property can be
1867 referred to in user code directly using the standard C dereference syntax as
1868 well as through the property &quot;dot&quot; syntax, but there is no entry in
1869 the @interface declaration corresponding to this ivar.
1870 </p>
1871 <p>
1872 To facilitate debugging, these properties we will add a new DWARF TAG into the
1873 DW_TAG_structure_type definition for the class to hold the description of a
1874 given property, and a set of DWARF attributes that provide said description.
1875 The property tag will also contain the name and declared type of the property.
1876 </p>
1877 <p>
1878 If there is a related ivar, there will also be a DWARF property attribute placed
1879 in the DW_TAG_member DIE for that ivar referring back to the property TAG for
1880 that property. And in the case where the compiler synthesizes the ivar directly,
1881 the compiler is expected to generate a DW_TAG_member for that ivar (with the
1882 DW_AT_artificial set to 1), whose name will be the name used to access this
1883 ivar directly in code, and with the property attribute pointing back to the
1884 property it is backing.
1885 </p>
1886 <p>
1887 The following examples will serve as illustration for our discussion:
1888 </p>
1889
1890 <div class="doc_code">
1891 <pre>
1892 @interface I1 {
1893   int n2;
1894 }
1895
1896 @property int p1;
1897 @property int p2;
1898 @end
1899
1900 @implementation I1
1901 @synthesize p1;
1902 @synthesize p2 = n2;
1903 @end
1904 </pre>
1905 </div>
1906
1907 <p>
1908 This produces the following DWARF (this is a &quot;pseudo dwarfdump&quot; output):
1909 </p>
1910 <div class="doc_code">
1911 <pre>
1912 0x00000100:  TAG_structure_type [7] *
1913                AT_APPLE_runtime_class( 0x10 )
1914                AT_name( "I1" )
1915                AT_decl_file( "Objc_Property.m" )
1916                AT_decl_line( 3 )
1917
1918 0x00000110    TAG_APPLE_property
1919                 AT_name ( "p1" )
1920                 AT_type ( {0x00000150} ( int ) )
1921
1922 0x00000120:   TAG_APPLE_property
1923                 AT_name ( "p2" )
1924                 AT_type ( {0x00000150} ( int ) )
1925
1926 0x00000130:   TAG_member [8]
1927                 AT_name( "_p1" )
1928                 AT_APPLE_property ( {0x00000110} "p1" )
1929                 AT_type( {0x00000150} ( int ) )
1930                 AT_artificial ( 0x1 )
1931
1932 0x00000140:    TAG_member [8]
1933                  AT_name( "n2" )
1934                  AT_APPLE_property ( {0x00000120} "p2" )
1935                  AT_type( {0x00000150} ( int ) )
1936
1937 0x00000150:  AT_type( ( int ) )
1938 </pre>
1939 </div>
1940
1941 <p> Note, the current convention is that the name of the ivar for an
1942 auto-synthesized property is the name of the property from which it derives with
1943 an underscore prepended, as is shown in the example.
1944 But we actually don't need to know this convention, since we are given the name
1945 of the ivar directly.
1946 </p>
1947
1948 <p>
1949 Also, it is common practice in ObjC to have different property declarations in
1950 the @interface and @implementation - e.g. to provide a read-only property in
1951 the interface,and a read-write interface in the implementation.  In that case,
1952 the compiler should emit whichever property declaration will be in force in the
1953 current translation unit.
1954 </p>
1955
1956 <p> Developers can decorate a property with attributes which are encoded using
1957 DW_AT_APPLE_property_attribute.
1958 </p>
1959
1960 <div class="doc_code">
1961 <pre>
1962 @property (readonly, nonatomic) int pr;
1963 </pre>
1964 </div>
1965 <p>
1966 Which produces a property tag:
1967 <p>
1968 <div class="doc_code">
1969 <pre>
1970 TAG_APPLE_property [8]
1971   AT_name( "pr" )
1972   AT_type ( {0x00000147} (int) )
1973   AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
1974 </pre>
1975 </div>
1976
1977 <p> The setter and getter method names are attached to the property using
1978 DW_AT_APPLE_property_setter and DW_AT_APPLE_property_getter attributes.
1979 </p>
1980 <div class="doc_code">
1981 <pre>
1982 @interface I1
1983 @property (setter=myOwnP3Setter:) int p3;
1984 -(void)myOwnP3Setter:(int)a;
1985 @end
1986
1987 @implementation I1
1988 @synthesize p3;
1989 -(void)myOwnP3Setter:(int)a{ }
1990 @end
1991 </pre>
1992 </div>
1993
1994 <p>
1995 The DWARF for this would be:
1996 </p>
1997 <div class="doc_code">
1998 <pre>
1999 0x000003bd: TAG_structure_type [7] *
2000               AT_APPLE_runtime_class( 0x10 )
2001               AT_name( "I1" )
2002               AT_decl_file( "Objc_Property.m" )
2003               AT_decl_line( 3 )
2004
2005 0x000003cd      TAG_APPLE_property
2006                   AT_name ( "p3" )
2007                   AT_APPLE_property_setter ( "myOwnP3Setter:" )
2008                   AT_type( {0x00000147} ( int ) )
2009
2010 0x000003f3:     TAG_member [8]
2011                   AT_name( "_p3" )
2012                   AT_type ( {0x00000147} ( int ) )
2013                   AT_APPLE_property ( {0x000003cd} )
2014                   AT_artificial ( 0x1 )
2015 </pre>
2016 </div>
2017
2018 </div>
2019
2020 <!-- *********************************************************************** -->
2021 <h4>
2022   <a name="objcpropertynewtags">New DWARF Tags</a>
2023 </h4>
2024 <!-- *********************************************************************** -->
2025
2026 <div>
2027 <table border="1" cellspacing="0">
2028   <tr>
2029     <th width=200 >TAG</th>
2030     <th width=200 >Value</th>
2031   </tr>
2032   <tr>
2033     <td width=200 >DW_TAG_APPLE_property</td>
2034     <td width=200 >0x4200</td>
2035   </tr>
2036 </table>
2037
2038 </div>
2039
2040 <!-- *********************************************************************** -->
2041 <h4>
2042   <a name="objcpropertynewattributes">New DWARF Attributes</a>
2043 </h4>
2044 <!-- *********************************************************************** -->
2045
2046 <div>
2047 <table border="1" cellspacing="0">
2048   <tr>
2049     <th width=200 >Attribute</th>
2050     <th width=200 >Value</th>
2051     <th width=200 >Classes</th>
2052   </tr>
2053   <tr>
2054     <td width=200 >DW_AT_APPLE_property</td>
2055     <td width=200 >0x3fed</td>
2056     <td width=200 >Reference</td>
2057   </tr>
2058   <tr>
2059     <td width=200 >DW_AT_APPLE_property_getter</td>
2060     <td width=200 >0x3fe9</td>
2061     <td width=200 >String</td>
2062   </tr>
2063   <tr>
2064     <td width=200 >DW_AT_APPLE_property_setter</td>
2065     <td width=200 >0x3fea</td>
2066     <td width=200 >String</td>
2067   </tr>
2068   <tr>
2069     <td width=200 >DW_AT_APPLE_property_attribute</td>
2070     <td width=200 >0x3feb</td>
2071     <td width=200 >Constant</td>
2072   </tr>
2073 </table>
2074
2075 </div>
2076
2077 <!-- *********************************************************************** -->
2078 <h4>
2079   <a name="objcpropertynewconstants">New DWARF Constants</a>
2080 </h4>
2081 <!-- *********************************************************************** -->
2082
2083 <div>
2084 <table border="1" cellspacing="0">
2085   <tr>
2086     <th width=200 >Name</th>
2087     <th width=200 >Value</th>
2088   </tr>
2089   <tr>
2090     <td width=200 >DW_AT_APPLE_PROPERTY_readonly</td>
2091     <td width=200 >0x1</td>
2092   </tr>
2093   <tr>
2094     <td width=200 >DW_AT_APPLE_PROPERTY_readwrite</td>
2095     <td width=200 >0x2</td>
2096   </tr>
2097   <tr>
2098     <td width=200 >DW_AT_APPLE_PROPERTY_assign</td>
2099     <td width=200 >0x4</td>
2100   </tr>
2101   <tr>
2102     <td width=200 >DW_AT_APPLE_PROPERTY_retain</td>
2103     <td width=200 >0x8</td>
2104   </tr>
2105   <tr>
2106     <td width=200 >DW_AT_APPLE_PROPERTY_copy</td>
2107     <td width=200 >0x10</td>
2108   </tr>
2109   <tr>
2110     <td width=200 >DW_AT_APPLE_PROPERTY_nonatomic</td>
2111     <td width=200 >0x20</td>
2112   </tr>
2113 </table>
2114
2115 </div>
2116 </div>
2117 </div>
2118
2119 <!-- *********************************************************************** -->
2120
2121 <hr>
2122 <address>
2123   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
2124   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
2125   <a href="http://validator.w3.org/check/referer"><img
2126   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
2127
2128   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
2129   <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
2130   Last modified: $Date$
2131 </address>
2132
2133 </body>
2134 </html>