<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- saved from url=(0038)http://wiki.llvm.org/Debug_Information -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="Content-Style-Type" content="text/css">
<meta name="generator" content="MediaWiki 1.15.4">
<meta name="keywords" content="Debug Information">
<link rel="alternate" type="application/x-wiki" title="Edit" href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit">
<link rel="edit" title="Edit" href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit">
<link rel="shortcut icon" href="http://wiki.llvm.org/favicon.ico">
<link rel="search" type="application/opensearchdescription+xml" href="http://wiki.llvm.org/opensearch_desc.php" title="LLVM (en)">
<link title="Creative Commons" type="application/rdf+xml" href="http://wiki.llvm.org/index.php?title=Debug_Information&action=creativecommons" rel="meta">
<link rel="copyright" href="http://creativecommons.org/licenses/by/3.0/">
<link rel="alternate" type="application/rss+xml" title="LLVM RSS feed" href="http://wiki.llvm.org/index.php?title=Special:RecentChanges&feed=rss">
<link rel="alternate" type="application/atom+xml" title="LLVM Atom feed" href="http://wiki.llvm.org/index.php?title=Special:RecentChanges&feed=atom">
<title>Debug Information - LLVM</title>
<link rel="stylesheet" href="./Debug Information - LLVM_files/shared.css" type="text/css" media="screen">
<link rel="stylesheet" href="./Debug Information - LLVM_files/commonPrint.css" type="text/css" media="print">
<link rel="stylesheet" href="./Debug Information - LLVM_files/index.php" type="text/css">
<link rel="stylesheet" href="./Debug Information - LLVM_files/index(1).php" type="text/css" media="print">
<link rel="stylesheet" href="./Debug Information - LLVM_files/index(2).php" type="text/css">
<link rel="stylesheet" href="./Debug Information - LLVM_files/index(3).php" type="text/css">
<!--[if lt IE 7]><script type="text/javascript" src="/skins/common/IEFixes.js?207"></script>
<meta http-equiv="imagetoolbar" content="no" /><![endif]-->
<script type="text/javascript">/*<![CDATA[*/
var skin = "myskin";
var stylepath = "/skins";
var wgArticlePath = "/$1";
var wgScriptPath = "";
var wgScript = "/index.php";
var wgVariantArticlePath = false;
var wgActionPaths = {};
var wgServer = "http://wiki.llvm.org";
var wgCanonicalNamespace = "";
var wgCanonicalSpecialPageName = false;
var wgNamespaceNumber = 0;
var wgPageName = "Debug_Information";
var wgTitle = "Debug Information";
var wgAction = "view";
var wgArticleId = "101";
var wgIsArticle = true;
var wgUserName = "Rengolin";
var wgUserGroups = ["*", "user", "autoconfirmed"];
var wgUserLanguage = "en";
var wgContentLanguage = "en";
var wgBreakFrames = false;
var wgCurRevisionId = 1053;
var wgVersion = "1.15.4";
var wgEnableAPI = true;
var wgEnableWriteAPI = true;
var wgSeparatorTransformTable = ["", ""];
var wgDigitTransformTable = ["", ""];
var wgRestrictionEdit = [];
var wgRestrictionMove = [];
var wgAjaxWatch = {"watchMsg": "Watch", "unwatchMsg": "Unwatch", "watchingMsg": "Watching...", "unwatchingMsg": "Unwatching..."};
/*]]>*/</script>
<script type="text/javascript" src="./Debug Information - LLVM_files/wikibits.js"><!-- wikibits js --></script><style type="text/css">@import "/skins/myskin/KHTMLFixes.css";</style>
<!-- Head Scripts -->
<script type="text/javascript" src="./Debug Information - LLVM_files/ajax.js"></script>
<script type="text/javascript" src="./Debug Information - LLVM_files/ajaxwatch.js"></script>
<script type="text/javascript" src="./Debug Information - LLVM_files/index(4).php"><!-- site js --></script>
<link rel="stylesheet" href="http://llvm.org/docs/llvm.css" type="text/css">
<body class="mediawiki ltr ns-0 ns-subject page-Debug_Information skin-myskin">
<div id="globalWrapper">
<div id="column-content">
<div id="content">
<a name="top" id="top"></a>
<h1 id="firstHeading" class="firstHeading">Debug Information</h1>
<div id="bodyContent">
<h3 id="siteSub">From LLVM</h3>
<div id="contentSub"></div>
<div id="jump-to-nav">Jump to: <a href="http://wiki.llvm.org/Debug_Information#column-one">navigation</a>, <a href="http://wiki.llvm.org/Debug_Information#searchInput">search</a></div> <!-- start content -->
<table id="toc" class="toc" summary="Contents"><tbody><tr><td><div id="toctitle"><h2>Contents</h2> <span class="toctoggle">[<a id="togglelink" class="internal" href="javascript:toggleToc()">hide</a>]</span></div>
<ul>
<li class="toclevel-1"><a href="http://wiki.llvm.org/Debug_Information#LLVM_Debug_Info_with_Metadata"><span class="tocnumber">1</span> <span class="toctext">LLVM Debug Info with Metadata</span></a>
<ul>
<li class="toclevel-2"><a href="http://wiki.llvm.org/Debug_Information#Abstract"><span class="tocnumber">1.1</span> <span class="toctext">Abstract</span></a></li>
<li class="toclevel-2"><a href="http://wiki.llvm.org/Debug_Information#Introduction"><span class="tocnumber">1.2</span> <span class="toctext">Introduction</span></a>
<ul>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#Constructing_Debug_Information"><span class="tocnumber">1.2.1</span> <span class="toctext">Constructing Debug Information</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DIFactory"><span class="tocnumber">1.2.2</span> <span class="toctext">DIFactory</span></a>
<ul>
<li class="toclevel-4"><a href="http://wiki.llvm.org/Debug_Information#Basic_Helper_Functions:"><span class="tocnumber">1.2.2.1</span> <span class="toctext">Basic Helper Functions:</span></a></li>
</ul>
</li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DICompileUnit"><span class="tocnumber">1.2.3</span> <span class="toctext">DICompileUnit</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DIFile"><span class="tocnumber">1.2.4</span> <span class="toctext">DIFile</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DIType"><span class="tocnumber">1.2.5</span> <span class="toctext">DIType</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DIGlobalVariable"><span class="tocnumber">1.2.6</span> <span class="toctext">DIGlobalVariable</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DISubprogram"><span class="tocnumber">1.2.7</span> <span class="toctext">DISubprogram</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DIVariable"><span class="tocnumber">1.2.8</span> <span class="toctext">DIVariable</span></a></li>
</ul>
</li>
<li class="toclevel-2"><a href="http://wiki.llvm.org/Debug_Information#Accessing_Debug_Information"><span class="tocnumber">1.3</span> <span class="toctext">Accessing Debug Information</span></a></li>
<li class="toclevel-2"><a href="http://wiki.llvm.org/Debug_Information#Debug_Line_Information"><span class="tocnumber">1.4</span> <span class="toctext">Debug Line Information</span></a>
<ul>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#Front-End:_Clang.2FDebugInfo"><span class="tocnumber">1.4.1</span> <span class="toctext">Front-End: Clang/DebugInfo</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#Back-End:_AsmPrinter"><span class="tocnumber">1.4.2</span> <span class="toctext">Back-End: AsmPrinter</span></a></li>
</ul>
</li>
<li class="toclevel-2"><a href="http://wiki.llvm.org/Debug_Information#Further_discussions"><span class="tocnumber">1.5</span> <span class="toctext">Further discussions</span></a>
<ul>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#Polymorphism:"><span class="tocnumber">1.5.1</span> <span class="toctext">Polymorphism:</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DIDescriptor_as_base_type:"><span class="tocnumber">1.5.2</span> <span class="toctext">DIDescriptor as base type:</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#Validation:"><span class="tocnumber">1.5.3</span> <span class="toctext">Validation:</span></a></li>
<li class="toclevel-3"><a href="http://wiki.llvm.org/Debug_Information#DIBuilder:"><span class="tocnumber">1.5.4</span> <span class="toctext">DIBuilder:</span></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</td></tr></tbody></table><script type="text/javascript"> if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); } </script>
<a name="LLVM_Debug_Info_with_Metadata" id="LLVM_Debug_Info_with_Metadata"></a><h1><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=1" title="Edit section: LLVM Debug Info with Metadata">edit</a>]</span> <span class="mw-headline"> LLVM Debug Info with Metadata </span></h1>
<a name="Abstract" id="Abstract"></a><h2><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=2" title="Edit section: Abstract">edit</a>]</span> <span class="mw-headline"> Abstract </span></h2>
<p>How to produce debug information in LLVM has changed considerably since 2.7. A new extensible metadata engine provides a flexible way of attaching extra information to LLVM Values and to make sure only needed additional information will be kept in the IR. There is already a long document on how the debug information is presented in the IR, but here, we provide a simple description on how to use the DebugInfo API for building debug information in the IR level from a generic AST descriptions.
</p>
<a name="Introduction" id="Introduction"></a><h2><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=3" title="Edit section: Introduction">edit</a>]</span> <span class="mw-headline"> Introduction </span></h2>
<p>This document describes how to use the DI helpers to build debug information, starting with an AST generated by a typical frontend. LLVM Values do not capture all of the information in the AST, such as the original declared types and qualifiers, or position information such as file/line/column. For this reason, DI helpers are used to annotate the LLVM Values so that this information can be recovered later.
</p><p>The basic idea about building debug information is that of using metadata to represent the DWARF fields of each Value. In LLVM, metadata is represented by a MDNode, which points to a Value. MDNodes can have any number of fields, so you can store different DWARF information (line info, type info, etc) using only MDNodes.
</p><p>In order to make sure the MDNodes are built correctly (with the correct number of parameters in the right order), some helper classes were written to help you extract information from (and put a type on) MDNodes. Those are the DI* classes, all deriving from DIDescriptor.
</p><p>Also, MDNodes are only exported if they point to some Value (including other MDNodes) that are also exported. This is a simple and efficient way of pruning unused metadata.
</p><p>In the IR level, only the metadata is present, no DWARF information is generated. Later on, in the CodeGen phase, the debug backend take this metadata and transfrom it into DWARF symbols, either by the ASM printer or the object writer in the MC infrastructure.
</p>
<a name="Constructing_Debug_Information" id="Constructing_Debug_Information"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=4" title="Edit section: Constructing Debug Information">edit</a>]</span> <span class="mw-headline"> Constructing Debug Information </span></h3>
<p>All DI Helpers are composed of an MDNode pointer and a set of utility member functions to extract information from the node.
</p><p>Each DI* class can be constructed using the DIFactory, which accepts a list of MDNodes and assign them to an internal array in the right order. There is no veryfication of types in this building process yet (see discussions below), so please make sure you're passing the correct parameters in the correct order.
</p><p>The basic hierarchy for a normal program is to have compilation units as the base of the debug tree, with files, sub-programs (functions, procedures) and global variables attached to them. Each variable (global or local) has a type associated.
</p><p>Files are NOT compilation units. In languages like C, the compiled file (say foo.c in clang -c foo.c) is both a file and a compilation units. Included files, like stdio.h are only files.
</p><p>All statements belong to a lexical block, that itself can belong to another, in a tree structure. The root lexical block in each tree belongs to a sub-program.
Graphical example:
</p><p>Take the following C program as an example (foo.c):
</p>
<pre> 1: #include
2:
3: int global = 10;
4:
5: int main() {
6: int local = 5;
7: for (; local < global; local++)
8: printf("Local = %d", local);
9: }
</pre>
<p>Could be represented as:
</p>
<pre> * CompileUnit: foo.c
o File: foo.c
o File: stdio.h
o GlobalVar: global [line 3, col 5]
+ Type: int
o SubProgram: main [line 5, col 5]
+ Type: function (int (void))
+ LexicalBlock (whole main) [line 5, col 12]
# Variable: local [line 6, col 9]
* Type: int
# LexicalBlock (for increment) [line 7, col 26]
# LexicalBlock (for body) [line 8, col 8]
</pre>
<p><a href="http://wiki.llvm.org/index.php?title=Special:Upload&wpDestFile=Dwarf.png" class="new" title="File:Dwarf.png">File:Dwarf.png</a>
</p><p>However incomplete this representation is, it gives an idea on how the basic elements are stored to provide a meaningful Dwarf information for debuggers to be able to step throug your program and inspect variables and expressions.
</p>
<a name="DIFactory" id="DIFactory"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=5" title="Edit section: DIFactory">edit</a>]</span> <span class="mw-headline"> DIFactory </span></h3>
<p>Contains all methods for creating DI* objects (and its MDNodes) from the list of parameters passed to the functions.
</p><p>Use these methods to create all debug information (rather than creating the arrays manually). It provides some basic guarantees on how many arguments and the basic type (DI* type) of some of them. While they're not actually validating everything yet, it's the logical place to add validation in the future.
</p>
<a name="Basic_Helper_Functions:" id="Basic_Helper_Functions:"></a><h4><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=6" title="Edit section: Basic Helper Functions:">edit</a>]</span> <span class="mw-headline"> Basic Helper Functions: </span></h4>
<p>Creates a compilation unit:
</p>
<pre> DICompileUnit CreateCompileUnit(...);
</pre>
<p>Creates a file associated to that compilation unit:
</p>
<pre> DIFile CreateFile(..., DICompileUnit CU);
</pre>
<p>Creates a function inside that file:
</p>
<pre> DISubprogram CreateSubprogram(..., DIFile F, ...);
</pre>
<p>Creates a lexical block inside that function (to which variables will be associated with):
</p>
<pre> DILexicalBlock CreateLexicalBlock(DIDescriptor Context, ...);
</pre>
<p>Creates a variable inside a lexical block:
</p>
<pre> DIVariable CreateVariable(..., DIDescriptor Context, ...);
</pre>
<p>Creates the type of that variable, function:
</p>
<pre> DIBasicType CreateBasicType(DIDescriptor Context, ...);
</pre>
<a name="DICompileUnit" id="DICompileUnit"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=7" title="Edit section: DICompileUnit">edit</a>]</span> <span class="mw-headline"> DICompileUnit </span></h3>
<p>Compilation unit is the file you are compiling, generally passed via command line. So, when you say compiler file.c, file.c is your compilation unit. As you'll see below, it is also a file, along with its included files, that get attached to this compilation unit.
</p><p>When compiling multiple files in the same command (ex. compiler file1.c file2.c), each file is a separate compilation unit.
</p><p>To create a compilation unit, we need a few information about the file and the system:
</p>
<ul><li> The language used on the file, from the Dwarf.h header file, for example dwarf::DW_LANG_C99.
</li><li> The file name.
</li><li> The directory containing the file. This could be the current directory . or the full path.
</li><li> The compiler name, version and whatever you feel important to put in that identifies your compiler.
</li></ul>
<p>Example:
</p><p>DICompileUnit cunit = factory.CreateCompileUnit(
</p>
<pre> dwarf::DW_LANG_C99,
"main.c",
"/home/username/src",
"my pet compiler v1.0");
</pre>
<p>Save that object (context, global), as you'll need it for the main file itself and all additional files that were included from it.
</p>
<a name="DIFile" id="DIFile"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=8" title="Edit section: DIFile">edit</a>]</span> <span class="mw-headline"> DIFile </span></h3>
<p>Files are all source and header files included in a compilation unit. Line information must be associated with a specific file, so it's important that you keep track of the files correctly and on which line/column the statement appears.
</p><p>For every file, source or header, you need to create a DIFile for it. With DIFiles, you can attach functions (DISubprogram) and global variables (DIGlobalVariable). The parameters are:
</p>
<ul><li> The file name.
</li><li> The directory containing the file.
</li><li> The compilation unit created above.
</li></ul>
<p>Example:
</p><p>DIFile file = factory.CreateFile(
</p>
<pre> "main.c",
"/home/username/",
cunit);
</pre>
<p>In a nutshel: when you compile multiple files, each file in the list is a compilation unit. For each compilation unit, there are multiple files: the file itself and all included files from it. So, for each compilation unit, you should create a DICompileUnit and for all files in that unit, you should create a DIFile attached to it.
</p>
<a name="DIType" id="DIType"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=9" title="Edit section: DIType">edit</a>]</span> <span class="mw-headline"> DIType </span></h3>
<p>Types (variables, functions, etc) are represented in DIType variants, which is derived as follows: Base types (int, float, etc) are represented as DIBasicType; pointers, consts, volatile, packed and typerefs as DIDerivedType; and all aggregate (arrays, structs, classes) as well as functions as DICompositeType.
</p><p>DIBasicType can be constructed by using:
</p>
<ul><li> The context, which is always the compilation unit, since base types are language specific.
</li><li> The name of the type. In C/C++, these would be "int", "float", etc. depending on their types and sizes.
</li><li> The file For base types, this is irrelevant.
</li><li> The line number in that file, also irrelevant.
</li><li> The size of the type, in bits.
</li><li> The alignment of the type, in bits.
</li><li> The offset of the type, in bits. For base types, this is generally zero.
</li><li> The flags Platform specific. Put zero unless you know what you're doing.
</li><li> The Dwarf encoding of the type. If it is boolean, float (single or double), signed (any size), etc.
</li></ul>
<p>Example:
</p><p>// Ex. "int" on 32-bit architectures are generally:
DIBasicType int_type =
</p>
<pre> factory.CreateBasicType(
/* DIDescriptor */ context = cunit,
/* StringRef */ "int",
/* DIFile */ file, /* unsigned */ line,
/* unsigned */ size = 32, /* unsigned */ align = 32, /* unsigned */ offset = 0,
/* unsigned */ flags = 0,
/* unsigned */ DW_ATE_signed
);
</pre>
<p>Other, more complex types (arrays, structs, unions, classes, subroutines) can be created using the DICompositeType using the right Dwarf TAG (DW_TAG_array_type, DW_TAG_structure_type, etc).
</p><p>Types such as pointers, typerefs (const, volatile etc.), and struc/class members can be created using the DIDerivedType, again with the appropriate TAGs (DW_TAG_pointer_type, DW_TAG_const_type, DW_TAG_member etc.)
</p>
<a name="DIGlobalVariable" id="DIGlobalVariable"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=10" title="Edit section: DIGlobalVariable">edit</a>]</span> <span class="mw-headline"> DIGlobalVariable </span></h3>
<p>Each (source/header) file has its own global variables. Some variables are local to the unit (static), some are only declarations, etc. All that information needs to encoded in the debug symbols.
</p><p>Globals variables are represented by the DIGlobalVariable class:
</p>
<ul><li> The context where it belongs. This could be the file itself, or some lexical block (ex. namespaces).
</li><li> The name of the global variable as it appears in the source. Unnamed objects must have empty string.
</li><li> The display name of the global variable. Use the same as in name.
</li><li> The linkage name of the global variable. In C++ this is the mangled name. If no mangling is necessary, it's just the same as the name.
</li><li> The file it belongs to. One of the created above, which could be a header file or the source file itself.
</li><li> The line in the file above.
</li><li> The type of the variable. See DIType
</li><li> If it's local to this compilation unit (static).
</li><li> If it's definition as well as declaration.
</li><li> The global variable it referst to. This is used to infer more information when lowering DWARF information.
</li></ul>
<p>Example:
</p><p>// On source, this variable:
7: static int Foo = 42;
</p><p>// Is created:
DIGlobalVariable gv =
</p>
<pre> factory.CreateGlobalVariable(
/* DIDescriptor */ context = cunit,
/* StringRef */ name = "Foo", display_name = "Foo", linkage_name = "Foo",
/* DIFile */ file, /* unsigned */ line = 7,
/* DIType */ type = int_type,
/* bool */ isLocal = true,
/* bool */ isDefinition = true,
/* GlobalVariable* */ global);
</pre>
<a name="DISubprogram" id="DISubprogram"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=11" title="Edit section: DISubprogram">edit</a>]</span> <span class="mw-headline"> DISubprogram </span></h3>
<p>Subprograms are functions, procedures, member functions, etc. It's represented by DISubprogram, that needs the following information:
</p>
<ul><li> The context where it belongs. This could be the file itself, or some lexical block (ex. namespaces).
</li><li> The name of the function as it appears in the source.
</li><li> The display name of the function. Same as above.
</li><li> The linkage name of the function. In C++ this is the mangled name. Omit this field if no mangling is necessary.
</li><li> The file it belongs to. One of the created above, which could be a header file or the source file itself.
</li><li> The line in the file above.
</li><li> The return type of the function. See DIType
</li><li> If it's local to this compilation unit (static).
</li><li> If it's definition as well as declaration.
</li><li> VK, VIndex, DIType t
</li><li> If it was generated by the compiler, set isArtificial to true.
</li><li> If it was optimized by the front-end, set isOptimized to true.
</li><li> The Function* (Value*) it referst to. This is used to infer more information when lowering DWARF information. (ex. if it is variadic)
</li></ul>
<p>Example:
</p><p>// In source, the function:
11: int my_function ( char* name, int size );
</p><p>// Is created:
DISubprogram func =
</p>
<pre> factory.CreateSubprogram(
/* DIDescriptor */ context = cunit,
/* StringRef */ name = "my_function", name = "my_function", name = "my_function",
/* DIFile */ file, /* unsigned */ line = 11,
/* DIType */ type = int_type,
/* bool */ isLocal = false,
/* bool */ isDefinition = false,
VK, VIndex, t,
/* bool */ isArtificial = false,
/* bool */ isOptimized = false,
/* Function* */ function
);
</pre>
<p>This way, the function will appear on the list of global symbols, with proper return type and parameters, but you also need to associate the parameters to local variables (See DIVariable) in order to see their values while debugging.
</p>
<a name="DIVariable" id="DIVariable"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=12" title="Edit section: DIVariable">edit</a>]</span> <span class="mw-headline"> DIVariable </span></h3>
<p>.
</p><p>DIVariable can be constructed by using:
</p>
<ul><li> The Dwarf TAG type, which defines the typeof variable (argument, auto, etc).
</li><li> The context, which is always the compilation unit, since base types are language specific.
</li><li> The name of the type. In C/C++, these would be "int", "float", etc. depending on their types and sizes.
</li><li> The file For base types, this is irrelevant.
</li><li> The line number in that file, also irrelevant.
</li><li> The type of the variable. See DIType
</li><li> If it's to preserve the symbol.
</li></ul>
<p>Example:
</p><p>// On source, this variable:
215: int Bar = 135;
</p><p>// Is created:
DIVariable var =
</p>
<pre> factory.CreateVariable(
/* llvm_dwarf_constants */ dwarf::DW_TAG_auto_variable,
/* DIDescriptor */ context = lex_block,
/* StringRef */ "Bar",
/* DIFile */ file, /* unsigned */ line = 215,
/* DIType */ type = int_type,
/* bool */ preserve = true
);
</pre>
<p>Arguments are created the same way, but with dwarf::DW_TAG_arg_variable.
</p><p>Once you got hold of the DIVariable and created the Value* for that variable, you have to declare the variable, and associate the debug location to that declare, so the debugger can capture its value during run time. For that you have to get hold of the variable itself (Value*), the debug information you just created (DIVariable) and the basic block you're going to declare the variable. That will insert an %llvm.dbg.declare({}*, metadata) call in the block you're emitting code.
</p><p>// Declare
Instruction* instr =
</p>
<pre> factory.InsertDeclare(
/* Value* */ variable,
/* DIVariable */ debug_info,
/* BasicBlock* */ block);
</pre>
<a name="Accessing_Debug_Information" id="Accessing_Debug_Information"></a><h2><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=13" title="Edit section: Accessing Debug Information">edit</a>]</span> <span class="mw-headline"> Accessing Debug Information </span></h2>
<p>TODO
</p>
<a name="Debug_Line_Information" id="Debug_Line_Information"></a><h2><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=14" title="Edit section: Debug Line Information">edit</a>]</span> <span class="mw-headline"> Debug Line Information </span></h2>
<p>With all program objects assigned to debug information, we can start thinking about line information. As you go along, stepping the source, the debugger needs to know which instruction belongs to which source file/line and what was the context at that time, to be able to print variables, etc.
</p><p>To associate line information with IR instructions (including llvm.dgb.declare calls), you have to use the DebugLoc class, as associate it to the instruction or the IRBuilder itself, which will then pass it to every instruction it creates.
</p><p>It is important, then, that you keep the builder up-to-date regarding DebugLocation, so you can export the correct line information and the debugger can step correctly through the user's code.
</p><p>Creating a debug location:
</p>
<pre> DebugLoc dbg = DebugLoc::get(line, column, context);
</pre>
<p>Associating with instructions
</p>
<pre> Instruction* instr = factory.InsertDeclare(...);
instr->setDebugLoc(dbg);
</pre>
<p>Associating with the IRBuilder
</p>
<pre> IRBuilder<> irb(bb);
irb.SetCurrentDebugLocation(dbg);
// This will export the correct line information automatically
irb.CreateAloca(...);
</pre>
<p>Whatch out, DebugLoc's context is actually an MDNode*. Because DIDescriptor overloads the * operator, passing a DIDescriptor works here, so don't be tempted to save the MDNode (to use it later?), as you'll lose the information of which type of debug information it is.
Debug Info Path within LLVM
</p><p>The Debug Info has to be created by the front end (as it has the line information, as well as additional type information that LLVM IR doesn't keep. This information, cerated with the help of the DIFactory, has to be lowered by LLVM into ASM/object information.
</p>
<a name="Front-End:_Clang.2FDebugInfo" id="Front-End:_Clang.2FDebugInfo"></a><h4><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=15" title="Edit section: Front-End: Clang/DebugInfo">edit</a>]</span> <span class="mw-headline"> Front-End: Clang/DebugInfo </span></h4>
<p>A good example on how to tie up the debug information can be found at Clang's tools/clang/lib/CodeGen/CGDebugInfo.h and it's used by the tools/clang/lib/CodeGen/CodeGen*.cpp files.
</p><p>Also, the pass responsible for printing the debug information in the IR is lib/Analysis/ModuleDebugInfoPrinter.cpp.
</p>
<a name="Back-End:_AsmPrinter" id="Back-End:_AsmPrinter"></a><h4><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=16" title="Edit section: Back-End: AsmPrinter">edit</a>]</span> <span class="mw-headline"> Back-End: AsmPrinter </span></h4>
<p>Once the debug information is encoded in metadata nodes (MDNodes and MDValues), LLVM lowers this information using lib/CodeGen/AsmPrinter/DwarfDebug.cpp.
</p>
<a name="Further_discussions" id="Further_discussions"></a><h2><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=17" title="Edit section: Further discussions">edit</a>]</span> <span class="mw-headline"> Further discussions </span></h2>
<a name="Polymorphism:" id="Polymorphism:"></a><h4><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=18" title="Edit section: Polymorphism:">edit</a>]</span> <span class="mw-headline"> Polymorphism: </span></h4>
<p>There is a simple hierarchy in the classes, but mostly to aggregate functionality in the helper functions than to create a proper polymorphism. In that sense, all DI* objects are passed by value (since they're normally the size of a pointer). That fact creates some problems, as we'll see below.
</p><p>To create DI* objects you should use the DIFactory (from DebugInfo.h). You can create the objects by directly calling their constructors, but that won't guarantee you get the parameters right. The DIFactory has some simple methods for creating variables, functions, files, types and its variations that makes it much easier to deal with debug information.
</p><p>Remember, the DI* classes are only wrappers to MDNodes, and MDNodes can easlily be passed around by themselves. It means that it could happen that you pass a DIType MDNode and re-wrap it on a DIFile, which will then get the wrong information when using the helper functions.
</p><p>Although DIDescripto has an isBasicType() method, you're not obliged to use it when converting types, and you lose that information anyway when you get the MDNode inside. And since DIDescriptors overload the * and -> operators, to use proper polymorphism, a major refactoring will be required.
</p>
<a name="DIDescriptor_as_base_type:" id="DIDescriptor_as_base_type:"></a><h4><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=19" title="Edit section: DIDescriptor as base type:">edit</a>]</span> <span class="mw-headline"> DIDescriptor as base type: </span></h4>
<p>It's here we see the first problem with not using polymorphism. DIDescriptor is used as a generic type for the context (which can be files, functions, lexical blocks, variables) but you can't pass a DILexicalBlock in place of a DIDescriptor, unless you have an explicit constructor (or some other copy mechanism) that allows it.
</p><p>DIDescriptor also has is'SubType'() methods, to indicate their sub-types, so you can convert them back to their original type, but for that, you need a block of (if)/(else if) statements, which is less than ideal. Still, the constructors are in place, which allows us to do the basic debug information costruction in this text. We shall not need to cast the objects back to their original type.
</p><p>As you can see, the context of a variable is the lexical block it belongs to, and its context is the subprogram, whose context is the file (or another lexical block, if inside a namespace) and so on.
</p>
<a name="Validation:" id="Validation:"></a><h4><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=20" title="Edit section: Validation:">edit</a>]</span> <span class="mw-headline"> Validation: </span></h4>
<p>It has been reported in the list that some debug data is generated incorrectly when using the DIFactory. Although it's impossible to validate and fix all problems, a simple validation like the one done in IR could catch most of the simple errors that would, in the back-end, generate bad information.
</p>
<a name="DIBuilder:" id="DIBuilder:"></a><h3><span class="editsection">[<a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit§ion=21" title="Edit section: DIBuilder:">edit</a>]</span> <span class="mw-headline"> DIBuilder: </span></h3>
<p>There is a new, under development, helpers called DIBuilder that will, eventually, replace the DIFactory. Some of the discussions above will be addressed when designing the new interface, which will be closely designed to match the current style.
</p>
<!--
NewPP limit report
Preprocessor node count: 22/1000000
Post-expand include size: 0/2097152 bytes
Template argument size: 0/2097152 bytes
Expensive parser function count: 0/100
-->
<!-- Saved in parser cache with key wikidb:pcache:idhash:101-0!1!0!!en!2 and timestamp 20101111082235 -->
<div class="printfooter">
Retrieved from "<a href="./Debug Information - LLVM_files/Debug Information - LLVM.html">http://wiki.llvm.org/Debug_Information</a>"</div>
<!-- end content -->
<div class="visualClear"></div>
</div>
</div>
</div>
<div id="column-one">
<div id="p-cactions" class="portlet">
<h5>Views</h5>
<div class="pBody">
<ul>
<li id="ca-nstab-main" class="selected"><a href="./Debug Information - LLVM_files/Debug Information - LLVM.html" title="View the content page [ctrl-alt-c]" accesskey="c">Page</a></li>
<li id="ca-talk" class="new"><a href="http://wiki.llvm.org/index.php?title=Talk:Debug_Information&action=edit&redlink=1" title="Discussion about the content page [ctrl-alt-t]" accesskey="t">Discussion</a></li>
<li id="ca-edit"><a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=edit" title="You can edit this page. Please use the preview button before saving [ctrl-alt-e]" accesskey="e">Edit</a></li>
<li id="ca-history"><a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=history" title="Past revisions of this page [ctrl-alt-h]" accesskey="h">History</a></li>
<li id="ca-move"><a href="http://wiki.llvm.org/Special:MovePage/Debug_Information" title="Move this page [ctrl-alt-m]" accesskey="m">Move</a></li>
<li id="ca-watch"><a href="http://wiki.llvm.org/index.php?title=Debug_Information&action=watch" title="Add this page to your watchlist [ctrl-alt-w]" accesskey="w">Watch</a></li> </ul>
</div>
</div>
<div class="portlet" id="p-personal">
<h5>Personal tools</h5>
<div class="pBody">
<ul>
<li id="pt-userpage"><a href="http://wiki.llvm.org/User:Rengolin" title="Your user page [ctrl-alt-.]" accesskey="." class="new">Rengolin</a></li>
<li id="pt-mytalk"><a href="http://wiki.llvm.org/User_talk:Rengolin" title="Your talk page [ctrl-alt-n]" accesskey="n" class="new">My talk</a></li>
<li id="pt-preferences"><a href="http://wiki.llvm.org/Special:Preferences" title="Your preferences">My preferences</a></li>
<li id="pt-watchlist"><a href="http://wiki.llvm.org/Special:Watchlist" title="The list of pages you are monitoring for changes [ctrl-alt-l]" accesskey="l">My watchlist</a></li>
<li id="pt-mycontris"><a href="http://wiki.llvm.org/Special:Contributions/Rengolin" title="List of your contributions [ctrl-alt-y]" accesskey="y">My contributions</a></li>
<li id="pt-logout"><a href="http://wiki.llvm.org/index.php?title=Special:UserLogout&returnto=Debug_Information" title="Log out">Log out</a></li>
</ul>
</div>
</div>
<div class="portlet" id="p-logo">
<a style="background-image: url(/images/llvmlogo.png);" href="http://wiki.llvm.org/Main_Page" title="Visit the main page [ctrl-alt-z]" accesskey="z"></a>
</div>
<script type="text/javascript"> if (window.isMSIE55) fixalpha(); </script>
<div class="generated-sidebar portlet" id="p-navigation">
<h5>Navigation</h5>
<div class="pBody">
<ul>
<li id="n-mainpage-description"><a href="http://wiki.llvm.org/Main_Page">Main page</a></li>
<li id="n-portal"><a href="http://wiki.llvm.org/LLVM:Community_Portal" title="About the project, what you can do, where to find things">Community portal</a></li>
<li id="n-currentevents"><a href="http://wiki.llvm.org/LLVM:Current_events" title="Find background information on current events">Current events</a></li>
<li id="n-recentchanges"><a href="http://wiki.llvm.org/Special:RecentChanges" title="The list of recent changes in the wiki [ctrl-alt-r]" accesskey="r">Recent changes</a></li>
<li id="n-randompage"><a href="http://wiki.llvm.org/Special:Random" title="Load a random page [ctrl-alt-x]" accesskey="x">Random page</a></li>
<li id="n-help"><a href="http://wiki.llvm.org/Help:Contents" title="The place to find out">Help</a></li>
</ul>
</div>
</div>
<div id="p-search" class="portlet">
<h5><label for="searchInput">Search</label></h5>
<div id="searchBody" class="pBody">
<form action="http://wiki.llvm.org/index.php" id="searchform"><div>
<input type="hidden" name="title" value="Special:Search">
<input id="searchInput" name="search" type="text" title="Search LLVM [ctrl-alt-f]" accesskey="f" value="">
<input type="submit" name="go" class="searchButton" id="searchGoButton" value="Go" title="Go to a page with this exact name if exists">
<input type="submit" name="fulltext" class="searchButton" id="mw-searchButton" value="Search" title="Search the pages for this text">
</div></form>
</div>
</div>
<div class="portlet" id="p-tb">
<h5>Toolbox</h5>
<div class="pBody">
<ul>
<li id="t-whatlinkshere"><a href="http://wiki.llvm.org/Special:WhatLinksHere/Debug_Information" title="List of all wiki pages that link here [ctrl-alt-j]" accesskey="j">What links here</a></li>
<li id="t-recentchangeslinked"><a href="http://wiki.llvm.org/Special:RecentChangesLinked/Debug_Information" title="Recent changes in pages linked from this page [ctrl-alt-k]" accesskey="k">Related changes</a></li>
<li id="t-upload"><a href="http://wiki.llvm.org/Special:Upload" title="Upload files [ctrl-alt-u]" accesskey="u">Upload file</a></li>
<li id="t-specialpages"><a href="http://wiki.llvm.org/Special:SpecialPages" title="List of all special pages [ctrl-alt-q]" accesskey="q">Special pages</a></li>
<li id="t-print"><a href="http://wiki.llvm.org/index.php?title=Debug_Information&printable=yes" rel="alternate" title="Printable version of this page [ctrl-alt-p]" accesskey="p">Printable version</a></li> <li id="t-permalink"><a href="http://wiki.llvm.org/index.php?title=Debug_Information&oldid=1053" title="Permanent link to this revision of the page">Permanent link</a></li> </ul>
</div>
</div>
</div><!-- end of the left (by default at least) column -->
<div class="visualClear"></div>
<div id="footer">
<div id="f-poweredbyico"><a href="http://www.mediawiki.org/"><img src="./Debug Information - LLVM_files/poweredby_mediawiki_88x31.png" alt="Powered by MediaWiki"></a></div>
<div id="f-copyrightico"><a href="http://creativecommons.org/licenses/by/3.0/"><img src="./Debug Information - LLVM_files/88x31.png" alt="Attribution 3.0 Unported"></a></div>
<ul id="f-list">
<li id="lastmod"> This page was last modified on 7 November 2010, at 05:51.</li>
<li id="viewcount">This page has been accessed 268 times.</li>
<li id="copyright">Content is available under <a href="http://creativecommons.org/licenses/by/3.0/" class="external " title="http://creativecommons.org/licenses/by/3.0/">Attribution 3.0 Unported</a>.</li>
<li id="privacy"><a href="http://wiki.llvm.org/LLVM:Privacy_policy" title="LLVM:Privacy policy">Privacy policy</a></li>
<li id="about"><a href="http://wiki.llvm.org/LLVM:About" title="LLVM:About">About LLVM</a></li>
<li id="disclaimer"><a href="http://wiki.llvm.org/LLVM:General_disclaimer" title="LLVM:General disclaimer">Disclaimers</a></li>
</ul>
</div>
</div>
<script type="text/javascript">if (window.runOnloadHook) runOnloadHook();</script>
<!-- Served in 0.042 secs. -->
<div style="background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; background-color: rgb(255, 255, 191); border-top-width: 0px; border-right-width: 0px; border-bottom-width: 0px; border-left-width: 0px; border-style: initial; border-color: initial; color: rgb(0, 0, 0); margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; padding-top: 0px; padding-right: 0px; padding-bottom: 0px; padding-left: 0px; font-family: arial, sans-serif; font-size: 13px; font-style: normal; font-variant: normal; font-weight: normal; height: auto; line-height: normal; text-align: left; width: auto; direction: ltr; z-index: 99995; background-position: initial initial; background-repeat: initial initial; "></div></body></html>