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