Blame - docs/SourceLevelDebugging.html - platform/external/llvm

blob: 172ede02e6afd19bbed7a9a607243a23ad398045 [file] [log] [blame]

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