This document is the central repository for all information pertaining to debug information in LLVM. It describes the actual format @@ -80,14 +80,12 @@ height="369"> Further, this document provides specific examples of what debug information for C/C++ looks like.

Philosophy behind LLVM debugging information -

+ -

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. @@ -133,11 +131,11 @@ height="369">

Debug information consumers -

+ -

The role of debug information is to provide meta information normally stripped away during the compilation process. This meta information provides @@ -157,11 +155,11 @@ height="369">

Debugging optimized code -

+ -

An extremely high priority of LLVM debugging information is to make it interact well with optimizations and analysis. In particular, the LLVM debug @@ -226,13 +224,15 @@ height="369">

+ -

Debugging information format -

+ -

LLVM debugging information has been carefully designed to make it possible for the optimizer to optimize the program and debugging information without @@ -265,14 +265,12 @@ height="369"> common to any source-language. The next section describes the data layout conventions used by the C and C++ front-ends.

- -

Debug information descriptors -

+ -

In consideration of the complexity and volume of debug information, LLVM provides a specification for well formed debug descriptors.

@@ -312,14 +310,12 @@ height="369">

The details of the various descriptors follow.

- -

Compile unit descriptors -

+ -

@@ -351,11 +347,11 @@ height="369">

File descriptors -

+ -

@@ -380,11 +376,11 @@ height="369">

Global variable descriptors -

+ -

@@ -407,16 +403,17 @@ height="369">

These descriptors provide debug information about globals variables. The -provide details such as name, type and where the variable is defined.

+provide details such as name, type and where the variable is defined. All +global variables are collected by named metadata !llvm.dbg.gv.

Subprogram descriptors -

+ -

@@ -432,30 +429,35 @@ provide details such as name, type and where the variable is 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)
-  i32       ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual
-  i32       ;; Index into a virtual function
+  i1,       ;; True if the global is defined in the compile unit (not extern)
+  i32,      ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual
+  i32,      ;; Index into a virtual function
   metadata, ;; indicates which base type contains the vtable pointer for the 
             ;; derived class
-  i1        ;; isArtificial
-  i1        ;; isOptimized
-  Function *;; Pointer to LLVM function
+  i1,       ;; isArtificial
+  i1,       ;; isOptimized
+  Function *,;; Pointer to LLVM function
+  metadata, ;; Lists function template parameters
+  metadata  ;; Function declaration descriptor
 }

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.

+ location where the subprogram is defined. + All subprogram descriptors are collected by a named metadata + !llvm.dbg.sp. +

Block descriptors -

+ -

@@ -463,7 +465,9 @@ provide details such as name, type and where the variable is defined.
   i32,     ;; Tag = 11 + LLVMDebugVersion (DW_TAG_lexical_block)
   metadata,;; Reference to context descriptor
   i32,     ;; Line number
-  i32      ;; Column number
+  i32,     ;; Column number
+  metadata,;; Reference to source file
+  i32      ;; Unique ID to identify blocks from a template function
 }

@@ -475,11 +479,11 @@ provide details such as name, type and where the variable is defined.

Basic type descriptors -

+ -

@@ -527,11 +531,11 @@ DW_ATE_unsigned_char = 8

Derived type descriptors -

+ -

@@ -544,7 +548,12 @@ DW_ATE_unsigned_char = 8
   i64,      ;; Size in bits
   i64,      ;; Alignment in bits
   i64,      ;; Offset in bits
-  metadata  ;; Reference to type derived from
+  metadata, ;; Reference to type derived from
+  metadata, ;; (optional) Name of the Objective C property assoicated with 
+            ;; Objective-C an ivar 
+  metadata, ;; (optional) Name of the Objective C property getter selector.
+  metadata, ;; (optional) Name of the Objective C property setter selector.
+  i32       ;; (optional) Objective C property attributes.
 }

@@ -594,11 +603,11 @@ DW_TAG_restrict_type = 55

Composite type descriptors -

+ -

@@ -644,7 +653,8 @@ DW_TAG_inheritance      = 28
 
 The members of enumeration types (tag = DW_TAG_enumeration_type) are
    enumerator descriptors, each representing
-   the definition of enumeration value for the set.
+   the definition of enumeration value for the set. All enumeration type
+   descriptors are collected by named metadata !llvm.dbg.enum.
 
 The members of structure (tag = DW_TAG_structure_type) or union (tag
    = DW_TAG_union_type) types are any one of
@@ -680,11 +690,11 @@ DW_TAG_inheritance      = 28

Subrange descriptors -

+ -

@@ -700,16 +710,17 @@ DW_TAG_inheritance      = 28
    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.
+   > high the array bounds are not included in generated debugging information.
+

Enumerator descriptors -

+ -

@@ -729,11 +740,11 @@ DW_TAG_inheritance      = 28

Local variables -

+ -

@@ -742,7 +753,8 @@ DW_TAG_inheritance      = 28
   metadata, ;; Context
   metadata, ;; Name
   metadata, ;; Reference to file where defined
-  i32,      ;; Line number where defined
+  i32,      ;; 24 bit - Line number where defined
+            ;; 8 bit - Argument number. 1 indicates 1st argument.
   metadata  ;; Type descriptor
 }

@@ -771,39 +783,39 @@ DW_TAG_return_variable = 258

+ -

Debugger intrinsic functions -

+ -

LLVM uses several intrinsic functions (name prefixed with "llvm.dbg") to provide debug information at various points in generated code.

- -

llvm.dbg.declare -

+ -

   void %llvm.dbg.declare(metadata, metadata)

This intrinsic provides information about a local element (ex. variable.) The - first argument is metadata holding alloca for the variable.. The + first argument is metadata holding alloca for the variable. The second argument is metadata containing description of the variable.

llvm.dbg.value -

+ -

   void %llvm.dbg.value(metadata, i64, metadata)

@@ -815,12 +827,14 @@ DW_TAG_return_variable = 258 user source variable.

+ -

Object lifetimes and scoping -

+ -

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 @@ -978,13 +992,15 @@ call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14

+ -

C/C++ front-end specific debug information -

+ -

The C and C++ front-ends represent information about the program in a format that is effectively identical @@ -1005,14 +1021,12 @@ call void @llvm.dbg.declare(metadata, metadata !12), !dbg !14

The following sections provide examples of various C/C++ constructs and the debug information that would best describe those constructs.

- -

C/C++ source file information -

+ -

Given the source files MySource.cpp and MyHeader.h located in the directory /Users/mine/sources, the following code:

@@ -1086,11 +1100,11 @@ using Instruction::getMetadata() and

C/C++ global variable information -

+ -

Given an integer global variable declared as follows:

@@ -1156,11 +1170,11 @@ int MyGlobal = 100;

C/C++ function information -

+ -

Given a function declared as follows:

@@ -1192,7 +1206,14 @@ int main(int argc, char *argv[]) { i32 1, ;; Line number metadata !4, ;; Type i1 false, ;; Is local - i1 true ;; Is definition + i1 true, ;; Is definition + i32 0, ;; Virtuality attribute, e.g. pure virtual function + i32 0, ;; Index into virtual table for C++ methods + i32 0, ;; Type that holds virtual table. + i32 0, ;; Flags + i1 false, ;; True if this function is optimized + Function *, ;; Pointer to llvm::Function + null ;; Function template parameters } ;; ;; Define the subprogram itself. @@ -1206,22 +1227,20 @@ define i32 @main(i32 %argc, i8** %argv) {

C/C++ basic types -

+ -

The following are the basic type descriptors for C/C++ core types:

- -

bool -

+ -

@@ -1243,11 +1262,11 @@ define i32 @main(i32 %argc, i8** %argv) {

char -

+ -

@@ -1269,11 +1288,11 @@ define i32 @main(i32 %argc, i8** %argv) {

unsigned char -

+ -

@@ -1295,11 +1314,11 @@ define i32 @main(i32 %argc, i8** %argv) {

short -

+ -

@@ -1321,11 +1340,11 @@ define i32 @main(i32 %argc, i8** %argv) {

unsigned short -

+ -

@@ -1347,11 +1366,11 @@ define i32 @main(i32 %argc, i8** %argv) {

int -

+ -

@@ -1372,11 +1391,11 @@ define i32 @main(i32 %argc, i8** %argv) {

unsigned int -

+ -

@@ -1398,11 +1417,11 @@ define i32 @main(i32 %argc, i8** %argv) {

long long -

+ -

@@ -1424,11 +1443,11 @@ define i32 @main(i32 %argc, i8** %argv) {

unsigned long long -

+ -

@@ -1450,11 +1469,11 @@ define i32 @main(i32 %argc, i8** %argv) {

float -

+ -

@@ -1476,11 +1495,11 @@ define i32 @main(i32 %argc, i8** %argv) {

double -

+ -

@@ -1501,12 +1520,14 @@ define i32 @main(i32 %argc, i8** %argv) {

+ -

C/C++ derived types -

+ -

Given the following as an example of C/C++ derived type:

@@ -1587,11 +1608,11 @@ typedef const int *IntPtr;

C/C++ struct/union types -

+ -

Given the following as an example of C/C++ struct type:

@@ -1700,11 +1721,11 @@ struct Color {

C/C++ enumeration types -

+ -

Given the following as an example of C/C++ enumeration type:

@@ -1765,6 +1786,8 @@ enum Trees {

@@ -1775,8 +1798,8 @@ enum Trees { src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"> Chris Lattner
- LLVM Compiler Infrastructure
- Last modified: $Date: 2011-02-03 01:22:17 +0100 (Thu, 03 Feb 2011) $ + LLVM Compiler Infrastructure
+ Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ -- cgit v1.1

Source Level Debugging with LLVM

Introduction