X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FSourceLevelDebugging.html;h=05a99e3d8e499c316b4e7fc786e7c25bf283cd8b;hb=9e6d1d1f5034347d237941f1bf08fba5c1583cd3;hp=ab9af996ba216cd28ffc1724234e00b395af8921;hpb=bdfb339b8d1d0480c42bfbcf76b96c1f7fcdec75;p=oota-llvm.git diff --git a/docs/SourceLevelDebugging.html b/docs/SourceLevelDebugging.html index ab9af996ba2..05a99e3d8e4 100644 --- a/docs/SourceLevelDebugging.html +++ b/docs/SourceLevelDebugging.html @@ -2,6 +2,7 @@ "http://www.w3.org/TR/html4/strict.dtd">
+This document is the central repository for all information pertaining to -debug information in LLVM. It describes how to use the llvm-db tool, which provides a -powerful source-level debugger to users of LLVM-based -compilers. When compiling a program in debug mode, the front-end in use adds -LLVM debugging information to the program in the form of normal LLVM program objects as well as a small set of LLVM intrinsic functions, which specify the mapping of the -program in LLVM form to the program in the source language. -
+ debug information in LLVM. It describes the actual format + that the LLVM debug information takes, which is useful for those + interested in creating front-ends or dealing directly with the information. + Further, this document provides specific examples of what debug information + for C/C++.-The idea of the LLVM debugging information is to capture how the important -pieces of the source-language's Abstract Syntax Tree map onto LLVM code. -Several design aspects have shaped the solution that appears here. The -important ones are:
+The idea of the LLVM debugging information is to capture how the important + pieces of the source-language's Abstract Syntax Tree map onto LLVM code. + Several design aspects have shaped the solution that appears here. The + important ones are:
-The approach used by the LLVM implementation is to use a small set + of intrinsic functions to define a + mapping between LLVM program objects and the source-level objects. The + description of the source-level program is maintained in LLVM metadata + in an implementation-defined format + (the C/C++ front-end currently uses working draft 7 of + the DWARF 3 + standard).
--The approach used by the LLVM implementation is to use a small set of intrinsic functions to define a mapping -between LLVM program objects and the source-level objects. The description of -the source-level program is maintained in LLVM global variables in an implementation-defined format (the C/C++ front-end -currently uses working draft 7 of the Dwarf 3 standard).
+When a program is being debugged, a debugger interacts with the user and + turns the stored debug information into source-language specific information. + As such, a debugger must be aware of the source-language, and is thus tied to + a specific language or family of languages.
--When a program is debugged, the debugger interacts with the user and turns the -stored debug information into source-language specific information. As such, -the debugger must be aware of the source-language, and is thus tied to a -specific language of family of languages. The LLVM -debugger is designed to be modular in its support for source-languages. -
+The role of debug information is to provide meta information normally + stripped away during the compilation process. This meta information provides + an LLVM user a relationship between generated code and the original program + source code.
+ +Currently, debug information is consumed by the DwarfWriter to produce dwarf + information used by the gdb debugger. Other targets could use the same + information to produce stabs or other debug forms.
+ +It would also be reasonable to use debug information to feed profiling tools + for analysis of generated code, or, tools for reconstructing the original + source from generated code.
+ +TODO - expound a bit more.
+ +-An extremely high priority of LLVM debugging information is to make it interact -well with optimizations and analysis. In particular, the LLVM debug information -provides the following guarantees:
-An extremely high priority of LLVM debugging information is to make it + interact well with optimizations and analysis. In particular, the LLVM debug + information provides the following guarantees:
-Basically, the debug information allows you to compile a program with + "-O0 -g" and get full debug information, allowing you to arbitrarily + modify the program as it executes from a debugger. Compiling a program with + "-O3 -g" gives you full debug information that is always available + and accurate for reading (e.g., you get accurate stack traces despite tail + call elimination and inlining), but you might lose the ability to modify the + program and call functions where were optimized out of the program, or + inlined away completely.
+ +LLVM test suite provides a + framework to test optimizer's handling of debugging information. It can be + run like this:
+ ++% cd llvm/projects/test-suite/MultiSource/Benchmarks # or some other level +% make TEST=dbgopt ++
This will test impact of debugging information on optimization passes. If + debugging information influences optimization passes then it will be reported + as a failure. See TestingGuide for more + information on LLVM test infrastructure and how to run various tests.
--Basically, the debug information allows you to compile a program with "-O0 --g" and get full debug information, allowing you to arbitrarily modify the -program as it executes from the debugger. Compiling a program with "-O3 --g" gives you full debug information that is always available and accurate -for reading (e.g., you get accurate stack traces despite tail call elimination -and inlining), but you might lose the ability to modify the program and call -functions where were optimized out of the program, or inlined away completely. -
+LLVM debugging information has been carefully designed to make it possible + for the optimizer to optimize the program and debugging information without + necessarily having to know anything about debugging information. In + particular, te use of metadadta avoids duplicated dubgging information from + the beginning, and the global dead code elimination pass automatically + deletes debugging information for a function if it decides to delete the + function.
-To do this, most of the debugging information (descriptors for types, + variables, functions, source files, etc) is inserted by the language + front-end in the form of LLVM metadata.
+ +Debug information is designed to be agnostic about the target debugger and + debugging information representation (e.g. DWARF/Stabs/etc). It uses a + generic pass to decode the information that represents variables, types, + functions, namespaces, etc: this allows for arbitrary source-language + semantics and type-systems to be used, as long as there is a module + written for the target debugger to interpret the information.
+ +To provide basic functionality, the LLVM debugger does have to make some + assumptions about the source-level language being debugged, though it keeps + these to a minimum. The only common features that the LLVM debugger assumes + exist are source files, + and program objects. These abstract + objects are used by a debugger to form stack traces, show information about + local variables, etc.
+This section of the documentation first describes the representation aspects + common to any source-language. The next section + describes the data layout conventions used by the C and C++ front-ends.
+ +-There are several important extensions that could be eventually added to the -LLVM debugger. The most important extension would be to upgrade the LLVM code -generators to support debugging information. This would also allow, for -example, the X86 code generator to emit native objects that contain debugging -information consumable by traditional source-level debuggers like GDB or -DBX.
--Additionally, LLVM optimizations can be upgraded to incrementally update the -debugging information, new commands can be added to the -debugger, and thread support could be added to the debugger.
+In consideration of the complexity and volume of debug information, LLVM + provides a specification for well formed debug descriptors.
+ +Consumers of LLVM debug information expect the descriptors for program + objects to start in a canonical format, but the descriptors can include + additional information appended at the end that is source-language + specific. All LLVM debugging information is versioned, allowing backwards + compatibility in the case that the core structures need to change in some + way. Also, all debugging information objects start with a tag to indicate + what type of object it is. The source-language is allowed to define its own + objects, by using unreserved tag numbers. We recommend using with tags in + the range 0x1000 through 0x2000 (there is a defined enum DW_TAG_user_base = + 0x1000.)
+ +The fields of debug descriptors used internally by LLVM + are restricted to only the simple data types int, uint, + bool, float, double, mdstring and + mdnode.
+ ++!1 = metadata !{ + uint, ;; A tag + ... +} ++
-The "SourceLanguage" modules provided by llvm-db could be substantially -improved to provide good support for C++ language features like namespaces and -scoping rules.
+ --After working with the debugger for a while, perhaps the nicest improvement -would be to add some sort of line editor, such as GNU readline (but that is -compatible with the LLVM license).
+The details of the various descriptors follow.
--For someone so inclined, it should be straight-forward to write different -front-ends for the LLVM debugger, as the LLVM debugging engine is cleanly -seperated from the llvm-db front-end. A GUI debugger or IDE would be -an interesting project. -
++!0 = metadata !{ + i32, ;; Tag = 17 + LLVMDebugVersion + ;; (DW_TAG_compile_unit) + i32, ;; Unused field. + i32, ;; DWARF language identifier (ex. DW_LANG_C89) + metadata, ;; Source file name + metadata, ;; Source file directory (includes trailing slash) + metadata ;; Producer (ex. "4.0.1 LLVM (LLVM research group)") + i1, ;; True if this is a main compile unit. + i1, ;; True if this is optimized. + metadata, ;; Flags + i32 ;; Runtime version +} ++
These descriptors contain a source language ID for the file (we use the DWARF + 3.0 ID numbers, such as DW_LANG_C89, DW_LANG_C_plus_plus, + DW_LANG_Cobol74, etc), three strings describing the filename, + working directory of the compiler, and an identifier string for the compiler + that produced it.
+ +Compile unit descriptors provide the root context for objects declared in a + specific source file. Global variables and top level functions would be + defined using this context. Compile unit descriptors also provide context + for source line correspondence.
+ +Each input file is encoded as a separate compile unit in LLVM debugging + information output. However, many target specific tool chains prefer to + encode only one compile unit in an object file. In this situation, the LLVM + code generator will include debugging information entities in the compile + unit that is marked as main compile unit. The code generator accepts maximum + one main compile unit per module. If a module does not contain any main + compile unit then the code generator will emit multiple compile units in the + output object file.
+ +-The llvm-db tool provides a GDB-like interface for source-level -debugging of programs. This tool provides many standard commands for inspecting -and modifying the program as it executes, loading new programs, single stepping, -placing breakpoints, etc. This section describes how to use the debugger. -
++!1 = metadata !{ + i32, ;; Tag = 52 + LLVMDebugVersion + ;; (DW_TAG_variable) + i32, ;; Unused field. + metadata, ;; Reference to context descriptor + metadata, ;; Name + metadata, ;; Display name (fully qualified C++ name) + metadata, ;; MIPS linkage name (for C++) + metadata, ;; Reference to compile unit where defined + i32, ;; Line number where defined + metadata, ;; Reference to type descriptor + i1, ;; True if the global is local to compile unit (static) + i1, ;; True if the global is defined in the compile unit (not extern) + { }* ;; Reference to the global variable +} ++
llvm-db has been designed to be as similar to GDB in its user -interface as possible. This should make it extremely easy to learn -llvm-db if you already know GDB. In general, llvm-db -provides the subset of GDB commands that are applicable to LLVM debugging users. -If there is a command missing that make a reasonable amount of sense within the -limitations of llvm-db, please report it as -a bug or, better yet, submit a patch to add it. :)
+These descriptors provide debug information about globals variables. The +provide details such as name, type and where the variable is defined.
llvm-db is the first LLVM debugger, and as such was designed to be -quick to prototype and build, and simple to extend. It is missing many many -features, though they should be easy to add over time (patches welcomed!). -Because the (currently only) debugger backend (implemented in -"lib/Debugger/UnixLocalInferiorProcess.cpp") was designed to work without any -cooperation from the code generators, it suffers from the following inherent -limitations:
++!2 = metadata !{ + i32, ;; Tag = 46 + LLVMDebugVersion + ;; (DW_TAG_subprogram) + i32, ;; Unused field. + metadata, ;; Reference to context descriptor + metadata, ;; Name + metadata, ;; Display name (fully qualified C++ name) + metadata, ;; MIPS linkage name (for C++) + metadata, ;; Reference to compile unit where defined + i32, ;; Line number where defined + metadata, ;; Reference to type descriptor + i1, ;; True if the global is local to compile unit (static) + i1 ;; True if the global is defined in the compile unit (not extern) +} ++
These descriptors provide debug information about functions, methods and + subprograms. They provide details such as name, return types and the source + location where the subprogram is defined.
+ ++!3 = metadata !{ + i32, ;; Tag = 13 + LLVMDebugVersion (DW_TAG_lexical_block) + metadata ;; Reference to context descriptor +} ++
These descriptors provide debug information about nested blocks within a + subprogram. The array of member descriptors is used to define local + variables and deeper nested blocks.
-That said, it is still quite useful, and all of these limitations can be -eliminated by integrating support for the debugger into the code generators. -See the future work section for ideas of how to extend -the LLVM debugger despite these limitations.
++!4 = metadata !{ + i32, ;; Tag = 36 + LLVMDebugVersion + ;; (DW_TAG_base_type) + metadata, ;; Reference to context (typically a compile unit) + metadata, ;; Name (may be "" for anonymous types) + metadata, ;; Reference to compile unit where defined (may be NULL) + i32, ;; Line number where defined (may be 0) + i64, ;; Size in bits + i64, ;; Alignment in bits + i64, ;; Offset in bits + i32, ;; Flags + i32 ;; DWARF type encoding +} ++
These descriptors define primitive types used in the code. Example int, bool + and float. The context provides the scope of the type, which is usually the + top level. Since basic types are not usually user defined the compile unit + and line number can be left as NULL and 0. The size, alignment and offset + are expressed in bits and can be 64 bit values. The alignment is used to + round the offset when embedded in a + composite type (example to keep float + doubles on 64 bit boundaries.) The offset is the bit offset if embedded in + a composite type.
+ +The type encoding provides the details of the type. The values are typically + one of the following:
+ ++DW_ATE_address = 1 +DW_ATE_boolean = 2 +DW_ATE_float = 4 +DW_ATE_signed = 5 +DW_ATE_signed_char = 6 +DW_ATE_unsigned = 7 +DW_ATE_unsigned_char = 8 +
-TODO -
++!5 = metadata !{ + i32, ;; Tag (see below) + metadata, ;; Reference to context + metadata, ;; Name (may be "" for anonymous types) + metadata, ;; Reference to compile unit where defined (may be NULL) + i32, ;; Line number where defined (may be 0) + i32, ;; Size in bits + i32, ;; Alignment in bits + i32, ;; Offset in bits + metadata ;; Reference to type derived from +} ++
These descriptors are used to define types derived from other types. The +value of the tag varies depending on the meaning. The following are possible +tag values:
+ ++DW_TAG_formal_parameter = 5 +DW_TAG_member = 13 +DW_TAG_pointer_type = 15 +DW_TAG_reference_type = 16 +DW_TAG_typedef = 22 +DW_TAG_const_type = 38 +DW_TAG_volatile_type = 53 +DW_TAG_restrict_type = 55 +
DW_TAG_member is used to define a member of + a composite type + or subprogram. The type of the member is + the derived + type. DW_TAG_formal_parameter is used to define a member which + is a formal argument of a subprogram.
+ +DW_TAG_typedef is used to provide a name for the derived type.
+ +DW_TAG_pointer_type,DW_TAG_reference_type, + DW_TAG_const_type, DW_TAG_volatile_type + and DW_TAG_restrict_type are used to qualify + the derived type.
+Derived type location can be determined + from the compile unit and line number. The size, alignment and offset are + expressed in bits and can be 64 bit values. The alignment is used to round + the offset when embedded in a composite + type (example to keep float doubles on 64 bit boundaries.) The offset is + the bit offset if embedded in a composite + type.
+ +Note that the void * type is expressed as a + llvm.dbg.derivedtype.type with tag of DW_TAG_pointer_type + and NULL derived type.
+ +There are three ways to start up the llvm-db debugger:
++!6 = metadata !{ + i32, ;; Tag (see below) + metadata, ;; Reference to context + metadata, ;; Name (may be "" for anonymous types) + metadata, ;; Reference to compile unit where defined (may be NULL) + i32, ;; Line number where defined (may be 0) + i64, ;; Size in bits + i64, ;; Alignment in bits + i64, ;; Offset in bits + i32, ;; Flags + metadata, ;; Reference to type derived from + metadata, ;; Reference to array of member descriptors + i32 ;; Runtime languages +} ++
These descriptors are used to define types that are composed of 0 or more +elements. The value of the tag varies depending on the meaning. The following +are possible tag values:
+ ++DW_TAG_array_type = 1 +DW_TAG_enumeration_type = 4 +DW_TAG_structure_type = 19 +DW_TAG_union_type = 23 +DW_TAG_vector_type = 259 +DW_TAG_subroutine_type = 21 +DW_TAG_inheritance = 28 ++
The vector flag indicates that an array type is a native packed vector.
+ +The members of array types (tag = DW_TAG_array_type) or vector types + (tag = DW_TAG_vector_type) are subrange + descriptors, each representing the range of subscripts at that level of + indexing.
+ +The members of enumeration types (tag = DW_TAG_enumeration_type) are + enumerator descriptors, each representing + the definition of enumeration value for the set.
+ +The members of structure (tag = DW_TAG_structure_type) or union (tag + = DW_TAG_union_type) types are any one of + the basic, + derived + or composite type descriptors, each + representing a field member of the structure or union.
+ +For C++ classes (tag = DW_TAG_structure_type), member descriptors + provide information about base classes, static members and member + functions. If a member is a derived type + descriptor and has a tag of DW_TAG_inheritance, then the type + represents a base class. If the member of is + a global variable descriptor then it + represents a static member. And, if the member is + a subprogram descriptor then it represents + a member function. For static members and member + functions, getName() returns the members link or the C++ mangled + name. getDisplayName() the simplied version of the name.
+ +The first member of subroutine (tag = DW_TAG_subroutine_type) type + elements is the return type for the subroutine. The remaining elements are + the formal arguments to the subroutine.
+ +Composite type location can be + determined from the compile unit and line number. The size, alignment and + offset are expressed in bits and can be 64 bit values. The alignment is used + to round the offset when embedded in + a composite type (as an example, to keep + float doubles on 64 bit boundaries.) The offset is the bit offset if embedded + in a composite type.
+ +When run with no options, just llvm-db, the debugger starts up -without a program loaded at all. You must use the file command to load a program, and the set args or run -commands to specify the arguments for the program.
+If you start the debugger with one argument, as llvm-db -<program>, the debugger will start up and load in the specified -program. You can then optionally specify arguments to the program with the set args or run -commands.
++%llvm.dbg.subrange.type = type { + i32, ;; Tag = 33 + LLVMDebugVersion (DW_TAG_subrange_type) + i64, ;; Low value + i64 ;; High value +} ++
The third way to start the program is with the --args option. This -option allows you to specify the program to load and the arguments to start out -with. Example use: llvm-db --args ls /home
+These descriptors are used to define ranges of array subscripts for an array + composite type. The low value defines + the lower bounds typically zero for C/C++. The high value is the upper + bounds. Values are 64 bit. High - low + 1 is the size of the array. If low + == high the array will be unbounded.
FIXME: this needs work obviously. See the GDB documentation for -information about what these do, or try 'help [command]' within -llvm-db to get information.
++!6 = metadata !{ + i32, ;; Tag = 40 + LLVMDebugVersion + ;; (DW_TAG_enumerator) + metadata, ;; Name + i64 ;; Value +} ++
-
These descriptors are used to define members of an + enumeration composite type, it + associates the name to the value.
-+!7 = metadata !{ + i32, ;; Tag (see below) + metadata, ;; Context + metadata, ;; Name + metadata, ;; Reference to compile unit where defined + i32, ;; Line number where defined + metadata ;; Type descriptor +} ++
These descriptors are used to define variables local to a sub program. The + value of the tag depends on the usage of the variable:
+ ++DW_TAG_auto_variable = 256 +DW_TAG_arg_variable = 257 +DW_TAG_return_variable = 258 +
An auto variable is any variable declared in the body of the function. An + argument variable is any variable that appears as a formal argument to the + function. A return variable is used to track the result of a function and + has no source correspondent.
+ +The context is either the subprogram or block where the variable is defined. + Name the source variable name. Compile unit and line indicate where the + variable was defined. Type descriptor defines the declared type of the + variable.
+ +-lib/Debugger - - UnixLocalInferiorProcess.cpp +LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to + provide debug information at various points in generated code.
-tools/llvm-db - - SourceLanguage interfaces - - ProgramInfo/RuntimeInfo - - Commands +
+ void %llvm.dbg.declare( { } *, metadata ) ++ +
This intrinsic provides information about a local element (ex. variable.) The + first argument is the alloca for the variable, cast to a { }*. The + second argument is + the %llvm.dbg.variable containing + the description of the variable.
In many languages, the local variables in functions can have their lifetimes + or scopes limited to a subset of a function. In the C family of languages, + for example, variables are only live (readable and writable) within the + source block that they are defined in. In functional languages, values are + only readable after they have been defined. Though this is a very obvious + concept, it is non-trivial to model in LLVM, because it has no notion of + scoping in this sense, and does not want to be tied to a language's scoping + rules.
+ +In order to handle this, the LLVM debug format uses the metadata attached to + llvm instructions to encode line nuber and scoping information. Consider the + following C fragment, for example:
+ ++1. void foo() { +2. int X = 21; +3. int Y = 22; +4. { +5. int Z = 23; +6. Z = X; +7. } +8. X = Y; +9. } ++
Compiled to LLVM, this function would be represented like this:
+ ++define void @foo() nounwind ssp { +entry: + %X = alloca i32, align 4 ; <i32*> [#uses=4] + %Y = alloca i32, align 4 ; <i32*> [#uses=4] + %Z = alloca i32, align 4 ; <i32*> [#uses=3] + %0 = bitcast i32* %X to { }* ; <{ }*> [#uses=1] + call void @llvm.dbg.declare({ }* %0, metadata !0), !dbg !7 + store i32 21, i32* %X, !dbg !8 + %1 = bitcast i32* %Y to { }* ; <{ }*> [#uses=1] + call void @llvm.dbg.declare({ }* %1, metadata !9), !dbg !10 + store i32 22, i32* %Y, !dbg !11 + %2 = bitcast i32* %Z to { }* ; <{ }*> [#uses=1] + call void @llvm.dbg.declare({ }* %2, metadata !12), !dbg !14 + store i32 23, i32* %Z, !dbg !15 + %tmp = load i32* %X, !dbg !16 ; <i32> [#uses=1] + %tmp1 = load i32* %Y, !dbg !16 ; <i32> [#uses=1] + %add = add nsw i32 %tmp, %tmp1, !dbg !16 ; <i32> [#uses=1] + store i32 %add, i32* %Z, !dbg !16 + %tmp2 = load i32* %Y, !dbg !17 ; <i32> [#uses=1] + store i32 %tmp2, i32* %X, !dbg !17 + ret void, !dbg !18 +} + +declare void @llvm.dbg.declare({ }*, metadata) nounwind readnone + +!0 = metadata !{i32 459008, metadata !1, metadata !"X", + metadata !3, i32 2, metadata !6}; [ DW_TAG_auto_variable ] +!1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ] +!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", metadata !"foo", + metadata !"foo", metadata !3, i32 1, metadata !4, + i1 false, i1 true}; [DW_TAG_subprogram ] +!3 = metadata !{i32 458769, i32 0, i32 12, metadata !"foo.c", + metadata !"/private/tmp", metadata !"clang 1.1", i1 true, + i1 false, metadata !"", i32 0}; [DW_TAG_compile_unit ] +!4 = metadata !{i32 458773, metadata !3, metadata !"", null, i32 0, i64 0, i64 0, + i64 0, i32 0, null, metadata !5, i32 0}; [DW_TAG_subroutine_type ] +!5 = metadata !{null} +!6 = metadata !{i32 458788, metadata !3, metadata !"int", metadata !3, i32 0, + i64 32, i64 32, i64 0, i32 0, i32 5}; [DW_TAG_base_type ] +!7 = metadata !{i32 2, i32 7, metadata !1, null} +!8 = metadata !{i32 2, i32 3, metadata !1, null} +!9 = metadata !{i32 459008, metadata !1, metadata !"Y", metadata !3, i32 3, + metadata !6}; [ DW_TAG_auto_variable ] +!10 = metadata !{i32 3, i32 7, metadata !1, null} +!11 = metadata !{i32 3, i32 3, metadata !1, null} +!12 = metadata !{i32 459008, metadata !13, metadata !"Z", metadata !3, i32 5, + metadata !6}; [ DW_TAG_auto_variable ] +!13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ] +!14 = metadata !{i32 5, i32 9, metadata !13, null} +!15 = metadata !{i32 5, i32 5, metadata !13, null} +!16 = metadata !{i32 6, i32 5, metadata !13, null} +!17 = metadata !{i32 8, i32 3, metadata !1, null} +!18 = metadata !{i32 9, i32 1, metadata !2, null} ++
This example illustrates a few important details about LLVM debugging + information. In particular, it shows how the llvm.dbg.declare + intrinsic and location information, which are attached to an instruction, + are applied together to allow a debugger to analyze the relationship between + statements, variable definitions, and the code used to implement the + function.
+ ++call void @llvm.dbg.declare({ }* %0, metadata !0), !dbg !7 ++
-FIXME: this section will eventually go away. These are notes to myself of -things that should be implemented, but haven't yet. -
+The first intrinsic + %llvm.dbg.declare + encodes debugging information for the variable X. The metadata + !dbg !7 attached to the intrinsic provides scope information for the + variable X.
+ ++!7 = metadata !{i32 2, i32 7, metadata !1, null} +!1 = metadata !{i32 458763, metadata !2}; [DW_TAG_lexical_block ] +!2 = metadata !{i32 458798, i32 0, metadata !3, metadata !"foo", + metadata !"foo", metadata !"foo", metadata !3, i32 1, + metadata !4, i1 false, i1 true}; [DW_TAG_subprogram ] ++
-Breakpoints: Support is already implemented in the 'InferiorProcess' -class, though it hasn't been tested yet. To finish breakpoint support, we need -to implement breakCommand (which should reuse the linespec parser from the list -command), and handle the fact that 'break foo' or 'break file.c:53' may insert -multiple breakpoints. Also, if you say 'break file.c:53' and there is no -stoppoint on line 53, the breakpoint should go on the next available line. My -idea was to have the Debugger class provide a "Breakpoint" class which -encapsulated this messiness, giving the debugger front-end a simple interface. -The debugger front-end would have to map the really complex semantics of -temporary breakpoints and 'conditional' breakpoints onto this intermediate -level. Also, breakpoints should survive as much as possible across program -reloads. -
+Here !7 is metadata providing location information. It has four + fields: line number, column number, scope, and original scope. The original + scope represents inline location if this instruction is inlined inside a + caller, and is null otherwise. In this example, scope is encoded by + !1. !1 represents a lexical block inside the scope + !2, where !2 is a + subprogram descriptor. This way the + location information attached to the intrinsics indicates that the + variable X is declared at line number 2 at a function level scope in + function foo.
+ +Now lets take another example.
+ ++call void @llvm.dbg.declare({ }* %2, metadata !12), !dbg !14 ++
The second intrinsic + %llvm.dbg.declare + encodes debugging information for variable Z. The metadata + !dbg !14 attached to the intrinsic provides scope information for + the variable Z.
+ ++!13 = metadata !{i32 458763, metadata !1}; [DW_TAG_lexical_block ] +!14 = metadata !{i32 5, i32 9, metadata !13, null} ++
-run (with args) & set args: These need to be implemented. -Currently run doesn't support setting arguments as part of the command. The -only tricky thing is handling quotes right and stuff.
+Here !14 indicates that Z is declaread at line number 5 and + column number 9 inside of lexical scope !13. The lexical scope + itself resides inside of lexical scope !1 described above.
--UnixLocalInferiorProcess.cpp speedup: There is no reason for the debugged -process to code gen the globals corresponding to debug information. The -IntrinsicLowering object could instead change descriptors into constant expr -casts of the constant address of the LLVM objects for the descriptors. This -would also allow us to eliminate the mapping back and forth between physical -addresses that must be done.
+The scope information attached with each instruction provides a + straightforward way to find instructions covered by a scope.
LLVM debugging information has been carefully designed to make it possible -for the optimizer to optimize the program and debugging information without -necessarily having to know anything about debugging information. In particular, -the global constant merging pass automatically eliminates duplicated debugging -information (often caused by header files), the global dead code elimination -pass automatically deletes debugging information for a function if it decides to -delete the function, and the linker eliminates debug information when it merges -linkonce functions.
- -To do this, most of the debugging information (descriptors for types, -variables, functions, source files, etc) is inserted by the language front-end -in the form of LLVM global variables. These LLVM global variables are no -different from any other global variables, except that they have a web of LLVM -intrinsic functions that point to them. If the last references to a particular -piece of debugging information are deleted (for example, by the --globaldce pass), the extraneous debug information will automatically -become dead and be removed by the optimizer.
- -The debugger is designed to be agnostic about the contents of most of the -debugging information. It uses a source-language-specific module to decode the -information that represents variables, types, functions, namespaces, etc: this -allows for arbitrary source-language semantics and type-systems to be used, as -long as there is a module written for the debugger to interpret the information. -
- --To provide basic functionality, the LLVM debugger does have to make some -assumptions about the source-level language being debugged, though it keeps -these to a minimum. The only common features that the LLVM debugger assumes -exist are source files, global objects (aka methods, messages, global -variables, etc), and local variables. -These abstract objects are used by the debugger to form stack traces, show -information about local variables, etc. - -
This section of the documentation first describes the representation aspects -common to any source-language. The next section -describes the data layout conventions used by the C and C++ -front-ends.
+The C and C++ front-ends represent information about the program in a format + that is effectively identical + to DWARF 3.0 in + terms of information content. This allows code generators to trivially + support native debuggers by generating standard dwarf information, and + contains enough information for non-dwarf targets to translate it as + needed.
+ +This section describes the forms used to represent C and C++ programs. Other + languages could pattern themselves after this (which itself is tuned to + representing programs in the same way that DWARF 3 does), or they could + choose to provide completely different forms if they don't fit into the DWARF + model. As support for debugging information gets added to the various LLVM + source-language front-ends, the information used should be documented + here.
+ +The following sections provide examples of various C/C++ constructs and the + debug information that would best describe those constructs.
-One important aspect of the LLVM debug representation is that it allows the LLVM -debugger to efficiently index all of the global objects without having the scan -the program. To do this, all of the global objects use "anchor" globals of type -"{}", with designated names. These anchor objects obviously do not -contain any content or meaning by themselves, but all of the global objects of a -particular type (e.g., source file descriptors) contain a pointer to the anchor. -This pointer allows the debugger to use def-use chains to find all global -objects of that type. -
--So far, the following names are recognized as anchors by the LLVM debugger: -
+Given the source files MySource.cpp and MyHeader.h located + in the directory /Users/mine/sources, the following code:
-- %llvm.dbg.translation_units = linkonce global {} {} - %llvm.dbg.globals = linkonce global {} {} -+
+#include "MyHeader.h" -+-Using anchors in this way (where the source file descriptor points to the -anchors, as opposed to having a list of source file descriptors) allows for the -standard dead global elimination and merging passes to automatically remove -unused debugging information. If the globals were kept track of through lists, -there would always be an object pointing to the descriptors, thus would never be -deleted. -
+int main(int argc, char *argv[]) { + return 0; +} +
a C/C++ front-end would generate the following descriptors:
+ ++... +;; +;; Define the compile unit for the source file "/Users/mine/sources/MySource.cpp". +;; +!3 = metadata !{ + i32 458769, ;; Tag + i32 0, ;; Unused + i32 4, ;; Language Id + metadata !"MySource.cpp", + metadata !"/Users/mine/sources", + metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)", + i1 true, ;; Main Compile Unit + i1 false, ;; Optimized compile unit + metadata !"", ;; Compiler flags + i32 0} ;; Runtime version + +;; +;; Define the compile unit for the header file "/Users/mine/sources/MyHeader.h". +;; +!1 = metadata !{ + i32 458769, ;; Tag + i32 0, ;; Unused + i32 4, ;; Language Id + metadata !"MyHeader.h", + metadata !"/Users/mine/sources", + metadata !"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)", + i1 false, ;; Main Compile Unit + i1 false, ;; Optimized compile unit + metadata !"", ;; Compiler flags + i32 0} ;; Runtime version + +... +
LLVM debugger "stop points" are a key part of the debugging representation -that allows the LLVM to maintain simple semantics for debugging optimized code. The basic idea is that the -front-end inserts calls to the %llvm.dbg.stoppoint intrinsic function -at every point in the program where the debugger should be able to inspect the -program (these correspond to places the debugger stops when you "step" -through it). The front-end can choose to place these as fine-grained as it -would like (for example, before every subexpression was evaluated), but it is -recommended to only put them after every source statement.
+Given an integer global variable declared as follows:
--Using calls to this intrinsic function to demark legal points for the debugger -to inspect the program automatically disables any optimizations that could -potentially confuse debugging information. To non-debug-information-aware -transformations, these calls simply look like calls to an external function, -which they must assume to do anything (including reading or writing to any part -of reachable memory). On the other hand, it does not impact many optimizations, -such as code motion of non-trapping instructions, nor does it impact -optimization of subexpressions, or any other code between the stop points.
++int MyGlobal = 100; ++
-An important aspect of the calls to the %llvm.dbg.stoppoint intrinsic -is that the function-local debugging information is woven together with use-def -chains. This makes it easy for the debugger to, for example, locate the 'next' -stop point. For a concrete example of stop points, see the next section.
+a C/C++ front-end would generate the following descriptors:
+ ++;; +;; Define the global itself. +;; +%MyGlobal = global int 100 +... +;; +;; List of debug info of globals +;; +!llvm.dbg.gv = !{!0} + +;; +;; Define the global variable descriptor. Note the reference to the global +;; variable anchor and the global variable itself. +;; +!0 = metadata !{ + i32 458804, ;; Tag + i32 0, ;; Unused + metadata !1, ;; Context + metadata !"MyGlobal", ;; Name + metadata !"MyGlobal", ;; Display Name + metadata !"MyGlobal", ;; Linkage Name + metadata !1, ;; Compile Unit + i32 1, ;; Line Number + metadata !2, ;; Type + i1 false, ;; Is a local variable + i1 true, ;; Is this a definition + i32* @MyGlobal ;; The global variable +} +;; +;; Define the basic type of 32 bit signed integer. Note that since int is an +;; intrinsic type the source file is NULL and line 0. +;; +!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"int", ;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 5 ;; Encoding +} + +
-In many languages, the local variables in functions can have their lifetime or -scope limited to a subset of a function. In the C family of languages, for -example, variables are only live (readable and writable) within the source block -that they are defined in. In functional languages, values are only readable -after they have been defined. Though this is a very obvious concept, it is also -non-trivial to model in LLVM, because it has no notion of scoping in this sense, -and does not want to be tied to a language's scoping rules. -
--In order to handle this, the LLVM debug format uses the notion of "regions" of a -function, delineated by calls to intrinsic functions. These intrinsic functions -define new regions of the program and indicate when the region lifetime expires. -Consider the following C fragment, for example: -
+Given a function declared as follows:
--1. void foo() { -2. int X = ...; -3. int Y = ...; -4. { -5. int Z = ...; -6. ... -7. } -8. ... -9. } -- -
-Compiled to LLVM, this function would be represented like this (FIXME: CHECK AND -UPDATE THIS): -
- --void %foo() { - %X = alloca int - %Y = alloca int - %Z = alloca int - %D1 = call {}* %llvm.dbg.func.start(%lldb.global* %d.foo) - %D2 = call {}* %llvm.dbg.stoppoint({}* %D1, uint 2, uint 2, %lldb.compile_unit* %file) - - %D3 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D2, ...) - ;; Evaluate expression on line 2, assigning to X. - %D4 = call {}* %llvm.dbg.stoppoint({}* %D3, uint 3, uint 2, %lldb.compile_unit* %file) - - %D5 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D4, ...) - ;; Evaluate expression on line 3, assigning to Y. - %D6 = call {}* %llvm.dbg.stoppoint({}* %D5, uint 5, uint 4, %lldb.compile_unit* %file) - - %D7 = call {}* %llvm.region.start({}* %D6) - %D8 = call {}* %llvm.dbg.DEFINEVARIABLE({}* %D7, ...) - ;; Evaluate expression on line 5, assigning to Z. - %D9 = call {}* %llvm.dbg.stoppoint({}* %D8, uint 6, uint 4, %lldb.compile_unit* %file) - - ;; Code for line 6. - %D10 = call {}* %llvm.region.end({}* %D9) - %D11 = call {}* %llvm.dbg.stoppoint({}* %D10, uint 8, uint 2, %lldb.compile_unit* %file) - - ;; Code for line 8. - %D12 = call {}* %llvm.region.end({}* %D11) - ret void -} -- -
-This example illustrates a few important details about the LLVM debugging -information. In particular, it shows how the various intrinsics used are woven -together with def-use and use-def chains, similar to how anchors are used with globals. This allows the -debugger to analyze the relationship between statements, variable definitions, -and the code used to implement the function.
- --In this example, two explicit regions are defined, one with the definition of the %D1 variable and one with the -definition of %D7. In the case of -%D1, the debug information indicates that the function whose descriptor is specified as an argument to the -intrinsic. This defines a new stack frame whose lifetime ends when the region -is ended by the %D12 call.
- --Representing the boundaries of functions with regions allows normal LLVM -interprocedural optimizations to change the boundaries of functions without -having to worry about breaking mapping information between LLVM and source-level -functions. In particular, the inlining optimization requires no modification to -support inlining with debugging information: there is no correlation drawn -between LLVM functions and their source-level counterparts.
- --Once the function has been defined, the stopping point corresponding to line #2 of the -function is encountered. At this point in the function, no local -variables are live. As lines 2 and 3 of the example are executed, their -variable definitions are automatically introduced into the program, without the -need to specify a new region. These variables do not require new regions to be -introduced because they go out of scope at the same point in the program: line -9. -
- --In contrast, the Z variable goes out of scope at a different time, on -line 7. For this reason, it is defined within the -%D7 region, which kills the availability of Z before the -code for line 8 is executed. Through the use of LLVM debugger regions, -arbitrary source-language scoping rules can be supported, as long as they can -only be nested (ie, one scope cannot partially overlap with a part of another -scope). -
- --It is worth noting that this scoping mechanism is used to control scoping of all -declarations, not just variable declarations. For example, the scope of a C++ -using declaration is controlled with this, and the llvm-db C++ support -routines could use this to change how name lookup is performed (though this is -not yet implemented). -
++int main(int argc, char *argv[]) { + return 0; +} ++
a C/C++ front-end would generate the following descriptors:
+ ++;; +;; Define the anchor for subprograms. Note that the second field of the +;; anchor is 46, which is the same as the tag for subprograms +;; (46 = DW_TAG_subprogram.) +;; +!0 = metadata !{ + i32 458798, ;; Tag + i32 0, ;; Unused + metadata !1, ;; Context + metadata !"main", ;; Name + metadata !"main", ;; Display name + metadata !"main", ;; Linkage name + metadata !1, ;; Compile unit + i32 1, ;; Line number + metadata !2, ;; Type + i1 false, ;; Is local + i1 true ;; Is definition +} +;; +;; Define the subprogram itself. +;; +define i32 @main(i32 %argc, i8** %argv) { +... +} +
The following are the basic type descriptors for C/C++ core types:
+ ++!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"bool", ;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 8, ;; Size in Bits + i64 8, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 2 ;; Encoding +} ++
+!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"char", ;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 8, ;; Size in Bits + i64 8, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 6 ;; Encoding +} ++
+!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"unsigned char", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 8, ;; Size in Bits + i64 8, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 8 ;; Encoding +} ++
+!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"short int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 16, ;; Size in Bits + i64 16, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 5 ;; Encoding +} ++
-The LLVM debugger expects the descriptors for global objects to start in a -canonical format, but the descriptors can include additional information -appended at the end. All LLVM debugging information is versioned, allowing -backwards compatibility in the case that the core structures need to change in -some way. The lowest-level descriptor are those describing the files containing the program source -code, all other descriptors refer to them. -
+ ++!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"short unsigned int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 16, ;; Size in Bits + i64 16, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 7 ;; Encoding +} +
-Source file descriptors were roughly patterned after the Dwarf "compile_unit" -object. The descriptor currently is defined to have the following LLVM -type:
--%lldb.compile_unit = type { - ushort, ;; LLVM debug version number - ushort, ;; Dwarf language identifier - sbyte*, ;; Filename - sbyte*, ;; Working directory when compiled - sbyte*, ;; Producer of the debug information - {}* ;; Anchor for llvm.dbg.translation_units ++-+!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"int", ;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 5 ;; Encoding } -+-These descriptors contain the version number for the debug info, a source -language ID for the file (we use the Dwarf 3.0 ID numbers, such as -DW_LANG_C89, DW_LANG_C_plus_plus, DW_LANG_Cobol74, -etc), three strings describing the filename, working directory of the compiler, -and an identifier string for the compiler that produced it, and the anchor for the descriptor. Here is an example -descriptor: -
+
-%arraytest_source_file = internal constant %lldb.compile_unit { - ushort 0, ; Version #0 - ushort 1, ; DW_LANG_C89 - sbyte* getelementptr ([12 x sbyte]* %.str_1, long 0, long 0), ; filename - sbyte* getelementptr ([12 x sbyte]* %.str_2, long 0, long 0), ; working dir - sbyte* getelementptr ([12 x sbyte]* %.str_3, long 0, long 0), ; producer - {}* %llvm.dbg.translation_units ; Anchor + ++ unsigned int ++ ++ ++ +++ ++!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"unsigned int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 7 ;; Encoding } -%.str_1 = internal constant [12 x sbyte] c"arraytest.c\00" -%.str_2 = internal constant [12 x sbyte] c"/home/sabre\00" -%.str_3 = internal constant [12 x sbyte] c"llvmgcc 3.4\00" -+ ++ long long ++ ++- ++++!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"long long int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 64, ;; Size in Bits + i64 64, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 5 ;; Encoding +} +---The LLVM debugger needs to know what the source-language global objects, in -order to build stack traces and other related activities. Because -source-languages have widly varying forms of global objects, the LLVM debugger -only expects the following fields in the descriptor for each global: -
--%lldb.global = type { - %lldb.compile_unit*, ;; The translation unit containing the global - sbyte*, ;; The global object 'name' - [type]*, ;; Source-language type descriptor for global - {}* ;; The anchor for llvm.dbg.globals ++-+!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"long long unsigned int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 64, ;; Size in Bits + i64 64, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 7 ;; Encoding } -+ +-The first field contains a pointer to the translation unit the function is -defined in. This pointer allows the debugger to find out which version of debug -information the function corresponds to. The second field contains a string -that the debugger can use to identify the subprogram if it does not contain -explicit support for the source-language in use. This should be some sort of -unmangled string that corresponds to the function somehow. -
+-Note again that descriptors can be extended to include source-language-specific -information in addition to the fields required by the LLVM debugger. See the section on the C/C++ front-end for more -information. -
+ ++ float+++ ++- ++!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"float", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 4 ;; Encoding +} ++--
+ ++++!2 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"double",;; Name + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 64, ;; Size in Bits + i64 64, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 4 ;; Encoding +} +--
+Given the following as an example of C/C++ derived type:
+ ++++typedef const int *IntPtr; +a C/C++ front-end would generate the following descriptors:
+ ++- - + + ++;; +;; Define the typedef "IntPtr". +;; +!2 = metadata !{ + i32 458774, ;; Tag + metadata !1, ;; Context + metadata !"IntPtr", ;; Name + metadata !3, ;; Compile unit + i32 0, ;; Line number + i64 0, ;; Size in bits + i64 0, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + metadata !4 ;; Derived From type +} +;; +;; Define the pointer type. +;; +!4 = metadata !{ + i32 458767, ;; Tag + metadata !1, ;; Context + metadata !"", ;; Name + metadata !1, ;; Compile unit + i32 0, ;; Line number + i64 64, ;; Size in bits + i64 64, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + metadata !5 ;; Derived From type +} +;; +;; Define the const type. +;; +!5 = metadata !{ + i32 458790, ;; Tag + metadata !1, ;; Context + metadata !"", ;; Name + metadata !1, ;; Compile unit + i32 0, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + metadata !6 ;; Derived From type +} +;; +;; Define the int type. +;; +!6 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"int", ;; Name + metadata !1, ;; Compile unit + i32 0, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + 5 ;; Encoding +} ++--The C and C++ front-ends represent information about the program in a format -that is effectively identical to Dwarf 3.0 in terms of -information content. This allows code generators to trivially support native -debuggers by generating standard dwarf information, and contains enough -information for non-dwarf targets to translate it other as needed.
+Given the following as an example of C/C++ struct type:
--TODO: document extensions to standard debugging objects, document how we -represent source types, etc. -
+++ ++struct Color { + unsigned Red; + unsigned Green; + unsigned Blue; +}; ++a C/C++ front-end would generate the following descriptors:
+ +++;; +;; Define basic type for unsigned int. +;; +!5 = metadata !{ + i32 458788, ;; Tag + metadata !1, ;; Context + metadata !"unsigned int", + metadata !1, ;; Compile Unit + i32 0, ;; Line number + i64 32, ;; Size in Bits + i64 32, ;; Align in Bits + i64 0, ;; Offset in Bits + i32 0, ;; Flags + i32 7 ;; Encoding +} +;; +;; Define composite type for struct Color. +;; +!2 = metadata !{ + i32 458771, ;; Tag + metadata !1, ;; Context + metadata !"Color", ;; Name + metadata !1, ;; Compile unit + i32 1, ;; Line number + i64 96, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + null, ;; Derived From + metadata !3, ;; Elements + i32 0 ;; Runtime Language +} + +;; +;; Define the Red field. +;; +!4 = metadata !{ + i32 458765, ;; Tag + metadata !1, ;; Context + metadata !"Red", ;; Name + metadata !1, ;; Compile Unit + i32 2, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + metadata !5 ;; Derived From type +} + +;; +;; Define the Green field. +;; +!6 = metadata !{ + i32 458765, ;; Tag + metadata !1, ;; Context + metadata !"Green", ;; Name + metadata !1, ;; Compile Unit + i32 3, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 32, ;; Offset in bits + i32 0, ;; Flags + metadata !5 ;; Derived From type +} + +;; +;; Define the Blue field. +;; +!7 = metadata !{ + i32 458765, ;; Tag + metadata !1, ;; Context + metadata !"Blue", ;; Name + metadata !1, ;; Compile Unit + i32 4, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 64, ;; Offset in bits + i32 0, ;; Flags + metadata !5 ;; Derived From type +} + +;; +;; Define the array of fields used by the composite type Color. +;; +!3 = metadata !{metadata !4, metadata !6, metadata !7} ++-+-
+Given the following as an example of C/C++ enumeration type:
+ ++++enum Trees { + Spruce = 100, + Oak = 200, + Maple = 300 +}; +a C/C++ front-end would generate the following descriptors:
+ +++ ++;; +;; Define composite type for enum Trees +;; +!2 = metadata !{ + i32 458756, ;; Tag + metadata !1, ;; Context + metadata !"Trees", ;; Name + metadata !1, ;; Compile unit + i32 1, ;; Line number + i64 32, ;; Size in bits + i64 32, ;; Align in bits + i64 0, ;; Offset in bits + i32 0, ;; Flags + null, ;; Derived From type + metadata !3, ;; Elements + i32 0 ;; Runtime language +} + +;; +;; Define the array of enumerators used by composite type Trees. +;; +!3 = metadata !{metadata !4, metadata !5, metadata !6} + +;; +;; Define Spruce enumerator. +;; +!4 = metadata !{i32 458792, metadata !"Spruce", i64 100} + +;; +;; Define Oak enumerator. +;; +!5 = metadata !{i32 458792, metadata !"Oak", i64 200} +;; +;; Define Maple enumerator. +;; +!6 = metadata !{i32 458792, metadata !"Maple", i64 300} + ++
- +