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

blob: 73a45cb2c4c3a2f3a91aa09162d0ae2e04fff2fe [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
				133	a specific language of family of languages.</p>
				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
				145	llvm user a relationship between generated code and the original program source
				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
				178	function that have been deleted.</li>
				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
				183	features making it easy to write new transformations.</li>
				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
				770	href="#format_subprograms">llvm.dbg.subprogram</a></tt> to the function. It also
				771	defines the beginning of the function's declarative region (scope.) The
				772	intrinsic should be called early in the function after the all the alloca
				773	instructions. It should be paired off with a closing <tt>%<a
				774	href="#format_common_region_end">llvm.dbg.region.end</a></tt>. The function's
				775	single argument is the <tt>%<a
				776	href="#format_subprograms">llvm.dbg.subprogram.type</a></tt>.</p>
				777
				778	</div>
				779
				780	<!-- ======================================================================= -->
				781	<div class="doc_subsubsection">
				782	<a name="format_common_region_start">llvm.dbg.region.start</a>
				783	</div>
				784
				785	<div class="doc_text">
				786	<pre>
				787	void %<a href="#format_common_region_start">llvm.dbg.region.start</a>( { }* )
				788	</pre>
				789
				790	<p>This intrinsic is used to define the beginning of a declarative scope (ex.
				791	block) for local language elements. It should be paired off with a closing
				792	<tt>%<a href="#format_common_region_end">llvm.dbg.region.end</a></tt>. The
				793	function's single argument is the <tt>%<a
				794	href="#format_blocks">llvm.dbg.block</a></tt> which is starting.</p>
				795
				796
				797	</div>
				798
				799	<!-- ======================================================================= -->
				800	<div class="doc_subsubsection">
				801	<a name="format_common_region_end">llvm.dbg.region.end</a>
				802	</div>
				803
				804	<div class="doc_text">
				805	<pre>
				806	void %<a href="#format_common_region_end">llvm.dbg.region.end</a>( { }* )
				807	</pre>
				808
				809	<p>This intrinsic is used to define the end of a declarative scope (ex. block)
				810	for local language elements. It should be paired off with an opening <tt>%<a
				811	href="#format_common_region_start">llvm.dbg.region.start</a></tt> or <tt>%<a
				812	href="#format_common_func_start">llvm.dbg.func.start</a></tt>. The function's
				813	single argument is either the <tt>%<a
				814	href="#format_blocks">llvm.dbg.block</a></tt> or the <tt>%<a
				815	href="#format_subprograms">llvm.dbg.subprogram.type</a></tt> which is
				816	ending.</p>
				817
				818	</div>
				819
				820	<!-- ======================================================================= -->
				821	<div class="doc_subsubsection">
				822	<a name="format_common_declare">llvm.dbg.declare</a>
				823	</div>
				824
				825	<div class="doc_text">
				826	<pre>
				827	void %<a href="#format_common_declare">llvm.dbg.declare</a>( { } , { } )
				828	</pre>
				829
				830	<p>This intrinsic provides information about a local element (ex. variable.) The
				831	first argument is the alloca for the variable, cast to a <tt>{ }*</tt>. The
				832	second argument is the <tt>%<a
				833	href="#format_variables">llvm.dbg.variable</a></tt> containing the description
				834	of the variable, also cast to a <tt>{ }*</tt>.</p>
				835
				836	</div>
				837
				838	<!-- ======================================================================= -->
				839	<div class="doc_subsection">
				840	<a name="format_common_stoppoints">
				841	Representing stopping points in the source program
				842	</a>
				843	</div>
				844
				845	<div class="doc_text">
				846
				847	<p>LLVM debugger "stop points" are a key part of the debugging representation
				848	that allows the LLVM to maintain simple semantics for <a
				849	href="#debugopt">debugging optimized code</a>. The basic idea is that the
				850	front-end inserts calls to the <a
				851	href="#format_common_stoppoint">%<tt>llvm.dbg.stoppoint</tt></a> intrinsic
				852	function at every point in the program where a debugger should be able to
				853	inspect the program (these correspond to places a debugger stops when you
				854	"<tt>step</tt>" through it). The front-end can choose to place these as
				855	fine-grained as it would like (for example, before every subexpression
				856	evaluated), but it is recommended to only put them after every source statement
				857	that includes executable code.</p>
				858
				859	<p>Using calls to this intrinsic function to demark legal points for the
				860	debugger to inspect the program automatically disables any optimizations that
				861	could potentially confuse debugging information. To non-debug-information-aware
				862	transformations, these calls simply look like calls to an external function,
				863	which they must assume to do anything (including reading or writing to any part
				864	of reachable memory). On the other hand, it does not impact many optimizations,
				865	such as code motion of non-trapping instructions, nor does it impact
				866	optimization of subexpressions, code duplication transformations, or basic-block
				867	reordering transformations.</p>
				868
				869	</div>
				870
				871
				872	<!-- ======================================================================= -->
				873	<div class="doc_subsection">
				874	<a name="format_common_lifetime">Object lifetimes and scoping</a>
				875	</div>
				876
				877	<div class="doc_text">
				878	<p>In many languages, the local variables in functions can have their lifetime
				879	or scope limited to a subset of a function. In the C family of languages, for
				880	example, variables are only live (readable and writable) within the source block
				881	that they are defined in. In functional languages, values are only readable
				882	after they have been defined. Though this is a very obvious concept, it is also
				883	non-trivial to model in LLVM, because it has no notion of scoping in this sense,
				884	and does not want to be tied to a language's scoping rules.</p>
				885
				886	<p>In order to handle this, the LLVM debug format uses the notion of "regions"
				887	of a function, delineated by calls to intrinsic functions. These intrinsic
				888	functions define new regions of the program and indicate when the region
				889	lifetime expires. Consider the following C fragment, for example:</p>
				890
				891	<pre>
				892	1. void foo() {
				893	2. int X = ...;
				894	3. int Y = ...;
				895	4. {
				896	5. int Z = ...;
				897	6. ...
				898	7. }
				899	8. ...
				900	9. }
				901	</pre>
				902
				903	<p>Compiled to LLVM, this function would be represented like this:</p>
				904
				905	<pre>
				906	void %foo() {
				907	entry:
				908	%X = alloca int
				909	%Y = alloca int
				910	%Z = alloca int
				911
				912	...
				913
				914	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 )
				915
				916	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 )
				917
				918	call void %<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...)
				919	call void %<a href="#format_common_declare">llvm.dbg.declare</a>({}* %Y, ...)
				920
				921	<i>;; Evaluate expression on line 2, assigning to X.</i>
				922
				923	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 )
				924
				925	<i>;; Evaluate expression on line 3, assigning to Y.</i>
				926
				927	call void %<a href="#format_common_stoppoint">llvm.region.start</a>()
				928	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 )
				929	call void %<a href="#format_common_declare">llvm.dbg.declare</a>({}* %X, ...)
				930
				931	<i>;; Evaluate expression on line 5, assigning to Z.</i>
				932
				933	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 )
				934	call void %<a href="#format_common_region_end">llvm.region.end</a>()
				935
				936	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 )
				937
				938	call void %<a href="#format_common_region_end">llvm.region.end</a>()
				939
				940	ret void
				941	}
				942	</pre>
				943
				944	<p>This example illustrates a few important details about the LLVM debugging
				945	information. In particular, it shows how the various intrinsics are applied
				946	together to allow a debugger to analyze the relationship between statements,
				947	variable definitions, and the code used to implement the function.</p>
				948
				949	<p>The first intrinsic <tt>%<a
				950	href="#format_common_func_start">llvm.dbg.func.start</a></tt> provides
				951	a link with the <a href="#format_subprograms">subprogram descriptor</a>
				952	containing the details of this function. This call also defines the beginning
				953	of the function region, bounded by the <tt>%<a
				954	href="#format_common_region_end">llvm.region.end</a></tt> at the end of
				955	the function. This region is used to bracket the lifetime of variables declared
				956	within. For a function, this outer region defines a new stack frame whose
				957	lifetime ends when the region is ended.</p>
				958
				959	<p>It is possible to define inner regions for short term variables by using the
				960	%<a href="#format_common_stoppoint"><tt>llvm.region.start</tt></a> and <a
				961	href="#format_common_region_end"><tt>%llvm.region.end</tt></a> to bound a
				962	region. The inner region in this example would be for the block containing the
				963	declaration of Z.</p>
				964
				965	<p>Using regions to represent the boundaries of source-level functions allow
				966	LLVM interprocedural optimizations to arbitrarily modify LLVM functions without
				967	having to worry about breaking mapping information between the LLVM code and the
				968	and source-level program. In particular, the inliner requires no modification
				969	to support inlining with debugging information: there is no explicit correlation
				970	drawn between LLVM functions and their source-level counterparts (note however,
				971	that if the inliner inlines all instances of a non-strong-linkage function into
				972	its caller that it will not be possible for the user to manually invoke the
				973	inlined function from a debugger).</p>
				974
				975	<p>Once the function has been defined, the <a
				976	href="#format_common_stoppoint"><tt>stopping point</tt></a> corresponding to
				977	line #2 (column #2) of the function is encountered. At this point in the
				978	function, <b>no</b> local variables are live. As lines 2 and 3 of the example
				979	are executed, their variable definitions are introduced into the program using
				980	%<a href="#format_common_declare"><tt>llvm.dbg.declare</tt></a>, without the
				981	need to specify a new region. These variables do not require new regions to be
				982	introduced because they go out of scope at the same point in the program: line
				983	9.</p>
				984
				985	<p>In contrast, the <tt>Z</tt> variable goes out of scope at a different time,
				986	on line 7. For this reason, it is defined within the inner region, which kills
				987	the availability of <tt>Z</tt> before the code for line 8 is executed. In this
				988	way, regions can support arbitrary source-language scoping rules, as long as
				989	they can only be nested (ie, one scope cannot partially overlap with a part of
				990	another scope).</p>
				991
				992	<p>It is worth noting that this scoping mechanism is used to control scoping of
				993	all declarations, not just variable declarations. For example, the scope of a
				994	C++ using declaration is controlled with this and could change how name lookup is
				995	performed.</p>
				996
				997	</div>
				998
				999
				1000
				1001	<!-- *********************************************************************** -->
				1002	<div class="doc_section">
				1003	<a name="ccxx_frontend">C/C++ front-end specific debug information</a>
				1004	</div>
				1005	<!-- *********************************************************************** -->
				1006
				1007	<div class="doc_text">
				1008
				1009	<p>The C and C++ front-ends represent information about the program in a format
				1010	that is effectively identical to <a
				1011	href="http://www.eagercon.com/dwarf/dwarf3std.htm">Dwarf 3.0</a> in terms of
				1012	information content. This allows code generators to trivially support native
				1013	debuggers by generating standard dwarf information, and contains enough
				1014	information for non-dwarf targets to translate it as needed.</p>
				1015
				1016	<p>This section describes the forms used to represent C and C++ programs. Other
				1017	languages could pattern themselves after this (which itself is tuned to
				1018	representing programs in the same way that Dwarf 3 does), or they could choose
				1019	to provide completely different forms if they don't fit into the Dwarf model.
				1020	As support for debugging information gets added to the various LLVM
				1021	source-language front-ends, the information used should be documented here.</p>
				1022
				1023	<p>The following sections provide examples of various C/C++ constructs and the
				1024	debug information that would best describe those constructs.</p>
				1025
				1026	</div>
				1027
				1028	<!-- ======================================================================= -->
				1029	<div class="doc_subsection">
				1030	<a name="ccxx_compile_units">C/C++ source file information</a>
				1031	</div>
				1032
				1033	<div class="doc_text">
				1034
				1035	<p>Given the source files "MySource.cpp" and "MyHeader.h" located in the
				1036	directory "/Users/mine/sources", the following code;</p>
				1037
				1038	<pre>
				1039	#include "MyHeader.h"
				1040
				1041	int main(int argc, char *argv[]) {
				1042	return 0;
				1043	}
				1044	</pre>
				1045
				1046	<p>a C/C++ front-end would generate the following descriptors;</p>
				1047
				1048	<pre>
				1049	...
				1050	;;
				1051	;; Define types used. In this case we need one for compile unit anchors and one
				1052	;; for compile units.
				1053	;;
				1054	%<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
				1055	%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = type { uint, { }, uint, uint, sbyte, sbyte, sbyte }
				1056	...
				1057	;;
				1058	;; Define the anchor for compile units. Note that the second field of the
				1059	;; anchor is 17, which is the same as the tag for compile units
				1060	;; (17 = DW_TAG_compile_unit.)
				1061	;;
				1062	%<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"
				1063
				1064	;;
				1065	;; Define the compile unit for the source file "/Users/mine/sources/MySource.cpp".
				1066	;;
				1067	%<a href="#format_compile_units">llvm.dbg.compile_unit1</a> = internal constant %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> {
				1068	uint add(uint 17, uint 262144),
				1069	{ }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*),
				1070	uint 1,
				1071	uint 1,
				1072	sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0),
				1073	sbyte* getelementptr ([21 x sbyte]* %str2, int 0, int 0),
				1074	sbyte* getelementptr ([33 x sbyte]* %str3, int 0, int 0) }, section "llvm.metadata"
				1075
				1076	;;
				1077	;; Define the compile unit for the header file "/Users/mine/sources/MyHeader.h".
				1078	;;
				1079	%<a href="#format_compile_units">llvm.dbg.compile_unit2</a> = internal constant %<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> {
				1080	uint add(uint 17, uint 262144),
				1081	{ }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_units</a> to { }*),
				1082	uint 1,
				1083	uint 1,
				1084	sbyte* getelementptr ([11 x sbyte]* %str4, int 0, int 0),
				1085	sbyte* getelementptr ([21 x sbyte]* %str2, int 0, int 0),
				1086	sbyte* getelementptr ([33 x sbyte]* %str3, int 0, int 0) }, section "llvm.metadata"
				1087
				1088	;;
				1089	;; Define each of the strings used in the compile units.
				1090	;;
				1091	%str1 = internal constant [13 x sbyte] c"MySource.cpp\00", section "llvm.metadata";
				1092	%str2 = internal constant [21 x sbyte] c"/Users/mine/sources/\00", section "llvm.metadata";
				1093	%str3 = internal constant [33 x sbyte] c"4.0.1 LLVM (LLVM research group)\00", section "llvm.metadata";
				1094	%str4 = internal constant [11 x sbyte] c"MyHeader.h\00", section "llvm.metadata";
				1095	...
				1096	</pre>
				1097
				1098	</div>
				1099
				1100	<!-- ======================================================================= -->
				1101	<div class="doc_subsection">
				1102	<a name="ccxx_global_variable">C/C++ global variable information</a>
				1103	</div>
				1104
				1105	<div class="doc_text">
				1106
				1107	<p>Given an integer global variable declared as follows;</p>
				1108
				1109	<pre>
				1110	int MyGlobal = 100;
				1111	</pre>
				1112
				1113	<p>a C/C++ front-end would generate the following descriptors;</p>
				1114
				1115	<pre>
				1116	;;
				1117	;; Define types used. One for global variable anchors, one for the global
				1118	;; variable descriptor, one for the global's basic type and one for the global's
				1119	;; compile unit.
				1120	;;
				1121	%<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
				1122	%<a href="#format_global_variables">llvm.dbg.global_variable.type</a> = type { uint, { }, { }, sbyte, { }, uint, { }, bool, bool, { }, uint }
				1123	%<a href="#format_basic_type">llvm.dbg.basictype.type</a> = type { uint, { }, sbyte, { }*, int, uint, uint, uint, uint }
				1124	%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ...
				1125	...
				1126	;;
				1127	;; Define the global itself.
				1128	;;
				1129	%MyGlobal = global int 100
				1130	...
				1131	;;
				1132	;; Define the anchor for global variables. Note that the second field of the
				1133	;; anchor is 52, which is the same as the tag for global variables
				1134	;; (52 = DW_TAG_variable.)
				1135	;;
				1136	%<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"
				1137
				1138	;;
				1139	;; Define the global variable descriptor. Note the reference to the global
				1140	;; variable anchor and the global variable itself.
				1141	;;
				1142	%<a href="#format_global_variables">llvm.dbg.global_variable</a> = internal constant %<a href="#format_global_variables">llvm.dbg.global_variable.type</a> {
				1143	uint add(uint 52, uint 262144),
				1144	{ }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_global_variables">llvm.dbg.global_variables</a> to { }*),
				1145	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1146	sbyte* getelementptr ([9 x sbyte]* %str1, int 0, int 0),
				1147	sbyte* getelementptr ([1 x sbyte]* %str2, int 0, int 0),
				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	uint 1,
				1150	{ }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*),
				1151	bool false,
				1152	bool true,
				1153	{ }* cast (int* %MyGlobal to { }*) }, section "llvm.metadata"
				1154
				1155	;;
				1156	;; Define the basic type of 32 bit signed integer. Note that since int is an
				1157	;; intrinsic type the source file is NULL and line 0.
				1158	;;
				1159	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1160	uint add(uint 36, uint 262144),
				1161	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1162	sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0),
				1163	{ }* null,
				1164	int 0,
				1165	uint 32,
				1166	uint 32,
				1167	uint 0,
				1168	uint 5 }, section "llvm.metadata"
				1169
				1170	;;
				1171	;; Define the names of the global variable and basic type.
				1172	;;
				1173	%str1 = internal constant [9 x sbyte] c"MyGlobal\00", section "llvm.metadata"
				1174	%str2 = internal constant [1 x sbyte] c"\00", section "llvm.metadata"
				1175	%str3 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
				1176	</pre>
				1177
				1178	</div>
				1179
				1180	<!-- ======================================================================= -->
				1181	<div class="doc_subsection">
				1182	<a name="ccxx_subprogram">C/C++ function information</a>
				1183	</div>
				1184
				1185	<div class="doc_text">
				1186
				1187	<p>Given a function declared as follows;</p>
				1188
				1189	<pre>
				1190	int main(int argc, char *argv[]) {
				1191	return 0;
				1192	}
				1193	</pre>
				1194
				1195	<p>a C/C++ front-end would generate the following descriptors;</p>
				1196
				1197	<pre>
				1198	;;
				1199	;; Define types used. One for subprogram anchors, one for the subprogram
				1200	;; descriptor, one for the global's basic type and one for the subprogram's
				1201	;; compile unit.
				1202	;;
				1203	%<a href="#format_subprograms">llvm.dbg.subprogram.type</a> = type { uint, { }, { }, sbyte, { }, bool, bool }
				1204	%<a href="#format_anchors">llvm.dbg.anchor.type</a> = type { uint, uint }
				1205	%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a> = ...
				1206
				1207	;;
				1208	;; Define the anchor for subprograms. Note that the second field of the
				1209	;; anchor is 46, which is the same as the tag for subprograms
				1210	;; (46 = DW_TAG_subprogram.)
				1211	;;
				1212	%<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"
				1213
				1214	;;
				1215	;; Define the descriptor for the subprogram. TODO - more details.
				1216	;;
				1217	%<a href="#format_subprograms">llvm.dbg.subprogram</a> = internal constant %<a href="#format_subprograms">llvm.dbg.subprogram.type</a> {
				1218	uint add(uint 46, uint 262144),
				1219	{ }* cast (%<a href="#format_anchors">llvm.dbg.anchor.type</a>* %<a href="#format_subprograms">llvm.dbg.subprograms</a> to { }*),
				1220	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1221	sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0),
				1222	sbyte* getelementptr ([1 x sbyte]* %str2, int 0, int 0),
				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	uint 1,
				1225	{ }* null,
				1226	bool false,
				1227	bool true }, section "llvm.metadata"
				1228
				1229	;;
				1230	;; Define the name of the subprogram.
				1231	;;
				1232	%str1 = internal constant [5 x sbyte] c"main\00", section "llvm.metadata"
				1233	%str2 = internal constant [1 x sbyte] c"\00", section "llvm.metadata"
				1234
				1235	;;
				1236	;; Define the subprogram itself.
				1237	;;
				1238	int %main(int %argc, sbyte** %argv) {
				1239	...
				1240	}
				1241	</pre>
				1242
				1243	</div>
				1244
				1245	<!-- ======================================================================= -->
				1246	<div class="doc_subsection">
				1247	<a name="ccxx_basic_types">C/C++ basic types</a>
				1248	</div>
				1249
				1250	<div class="doc_text">
				1251
				1252	<p>The following are the basic type descriptors for C/C++ core types;</p>
				1253
				1254	</div>
				1255
				1256	<!-- ======================================================================= -->
				1257	<div class="doc_subsubsection">
				1258	<a name="ccxx_basic_type_bool">bool</a>
				1259	</div>
				1260
				1261	<div class="doc_text">
				1262
				1263	<pre>
				1264	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1265	uint add(uint 36, uint 262144),
				1266	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1267	sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0),
				1268	{ }* null,
				1269	int 0,
				1270	uint 32,
				1271	uint 32,
				1272	uint 0,
				1273	uint 2 }, section "llvm.metadata"
				1274	%str1 = internal constant [5 x sbyte] c"bool\00", section "llvm.metadata"
				1275	</pre>
				1276
				1277	</div>
				1278
				1279	<!-- ======================================================================= -->
				1280	<div class="doc_subsubsection">
				1281	<a name="ccxx_basic_char">char</a>
				1282	</div>
				1283
				1284	<div class="doc_text">
				1285
				1286	<pre>
				1287	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1288	uint add(uint 36, uint 262144),
				1289	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1290	sbyte* getelementptr ([5 x sbyte]* %str1, int 0, int 0),
				1291	{ }* null,
				1292	int 0,
				1293	uint 8,
				1294	uint 8,
				1295	uint 0,
				1296	uint 6 }, section "llvm.metadata"
				1297	%str1 = internal constant [5 x sbyte] c"char\00", section "llvm.metadata"
				1298	</pre>
				1299
				1300	</div>
				1301
				1302	<!-- ======================================================================= -->
				1303	<div class="doc_subsubsection">
				1304	<a name="ccxx_basic_unsigned_char">unsigned char</a>
				1305	</div>
				1306
				1307	<div class="doc_text">
				1308
				1309	<pre>
				1310	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1311	uint add(uint 36, uint 262144),
				1312	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1313	sbyte* getelementptr ([14 x sbyte]* %str1, int 0, int 0),
				1314	{ }* null,
				1315	int 0,
				1316	uint 8,
				1317	uint 8,
				1318	uint 0,
				1319	uint 8 }, section "llvm.metadata"
				1320	%str1 = internal constant [14 x sbyte] c"unsigned char\00", section "llvm.metadata"
				1321	</pre>
				1322
				1323	</div>
				1324
				1325	<!-- ======================================================================= -->
				1326	<div class="doc_subsubsection">
				1327	<a name="ccxx_basic_short">short</a>
				1328	</div>
				1329
				1330	<div class="doc_text">
				1331
				1332	<pre>
				1333	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1334	uint add(uint 36, uint 262144),
				1335	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1336	sbyte* getelementptr ([10 x sbyte]* %str1, int 0, int 0),
				1337	{ }* null,
				1338	int 0,
				1339	uint 16,
				1340	uint 16,
				1341	uint 0,
				1342	uint 5 }, section "llvm.metadata"
				1343	%str1 = internal constant [10 x sbyte] c"short int\00", section "llvm.metadata"
				1344	</pre>
				1345
				1346	</div>
				1347
				1348	<!-- ======================================================================= -->
				1349	<div class="doc_subsubsection">
				1350	<a name="ccxx_basic_unsigned_short">unsigned short</a>
				1351	</div>
				1352
				1353	<div class="doc_text">
				1354
				1355	<pre>
				1356	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1357	uint add(uint 36, uint 262144),
				1358	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1359	sbyte* getelementptr ([19 x sbyte]* %str1, int 0, int 0),
				1360	{ }* null,
				1361	int 0,
				1362	uint 16,
				1363	uint 16,
				1364	uint 0,
				1365	uint 7 }, section "llvm.metadata"
				1366	%str1 = internal constant [19 x sbyte] c"short unsigned int\00", section "llvm.metadata"
				1367	</pre>
				1368
				1369	</div>
				1370
				1371	<!-- ======================================================================= -->
				1372	<div class="doc_subsubsection">
				1373	<a name="ccxx_basic_int">int</a>
				1374	</div>
				1375
				1376	<div class="doc_text">
				1377
				1378	<pre>
				1379	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1380	uint add(uint 36, uint 262144),
				1381	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1382	sbyte* getelementptr ([4 x sbyte]* %str1, int 0, int 0),
				1383	{ }* null,
				1384	int 0,
				1385	uint 32,
				1386	uint 32,
				1387	uint 0,
				1388	uint 5 }, section "llvm.metadata"
				1389	%str1 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
				1390	</pre>
				1391
				1392	</div>
				1393
				1394	<!-- ======================================================================= -->
				1395	<div class="doc_subsubsection">
				1396	<a name="ccxx_basic_unsigned_int">unsigned int</a>
				1397	</div>
				1398
				1399	<div class="doc_text">
				1400
				1401	<pre>
				1402	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1403	uint add(uint 36, uint 262144),
				1404	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1405	sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0),
				1406	{ }* null,
				1407	int 0,
				1408	uint 32,
				1409	uint 32,
				1410	uint 0,
				1411	uint 7 }, section "llvm.metadata"
				1412	%str1 = internal constant [13 x sbyte] c"unsigned int\00", section "llvm.metadata"
				1413	</pre>
				1414
				1415	</div>
				1416
				1417	<!-- ======================================================================= -->
				1418	<div class="doc_subsubsection">
				1419	<a name="ccxx_basic_long_long">long long</a>
				1420	</div>
				1421
				1422	<div class="doc_text">
				1423
				1424	<pre>
				1425	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1426	uint add(uint 36, uint 262144),
				1427	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1428	sbyte* getelementptr ([14 x sbyte]* %str1, int 0, int 0),
				1429	{ }* null,
				1430	int 0,
				1431	uint 64,
				1432	uint 64,
				1433	uint 0,
				1434	uint 5 }, section "llvm.metadata"
				1435	%str1 = internal constant [14 x sbyte] c"long long int\00", section "llvm.metadata"
				1436	</pre>
				1437
				1438	</div>
				1439
				1440	<!-- ======================================================================= -->
				1441	<div class="doc_subsubsection">
				1442	<a name="ccxx_basic_unsigned_long_long">unsigned long long</a>
				1443	</div>
				1444
				1445	<div class="doc_text">
				1446
				1447	<pre>
				1448	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1449	uint add(uint 36, uint 262144),
				1450	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1451	sbyte* getelementptr ([23 x sbyte]* %str1, int 0, int 0),
				1452	{ }* null,
				1453	int 0,
				1454	uint 64,
				1455	uint 64,
				1456	uint 0,
				1457	uint 7 }, section "llvm.metadata"
				1458	%str1 = internal constant [23 x sbyte] c"long long unsigned int\00", section "llvm.metadata"
				1459	</pre>
				1460
				1461	</div>
				1462
				1463	<!-- ======================================================================= -->
				1464	<div class="doc_subsubsection">
				1465	<a name="ccxx_basic_float">float</a>
				1466	</div>
				1467
				1468	<div class="doc_text">
				1469
				1470	<pre>
				1471	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1472	uint add(uint 36, uint 262144),
				1473	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1474	sbyte* getelementptr ([6 x sbyte]* %str1, int 0, int 0),
				1475	{ }* null,
				1476	int 0,
				1477	uint 32,
				1478	uint 32,
				1479	uint 0,
				1480	uint 4 }, section "llvm.metadata"
				1481	%str1 = internal constant [6 x sbyte] c"float\00", section "llvm.metadata"
				1482	</pre>
				1483
				1484	</div>
				1485
				1486	<!-- ======================================================================= -->
				1487	<div class="doc_subsubsection">
				1488	<a name="ccxx_basic_double">double</a>
				1489	</div>
				1490
				1491	<div class="doc_text">
				1492
				1493	<pre>
				1494	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1495	uint add(uint 36, uint 262144),
				1496	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1497	sbyte* getelementptr ([7 x sbyte]* %str1, int 0, int 0),
				1498	{ }* null,
				1499	int 0,
				1500	uint 64,
				1501	uint 64,
				1502	uint 0,
				1503	uint 4 }, section "llvm.metadata"
				1504	%str1 = internal constant [7 x sbyte] c"double\00", section "llvm.metadata"
				1505	</pre>
				1506
				1507	</div>
				1508
				1509	<!-- ======================================================================= -->
				1510	<div class="doc_subsection">
				1511	<a name="ccxx_derived_types">C/C++ derived types</a>
				1512	</div>
				1513
				1514	<div class="doc_text">
				1515
				1516	<p>Given the following as an example of C/C++ derived type;</p>
				1517
				1518	<pre>
				1519	typedef const int *IntPtr;
				1520	</pre>
				1521
				1522	<p>a C/C++ front-end would generate the following descriptors;</p>
				1523
				1524	<pre>
				1525	;;
				1526	;; Define the typedef "IntPtr".
				1527	;;
				1528	%<a href="#format_derived_type">llvm.dbg.derivedtype1</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
				1529	uint add(uint 22, uint 262144),
				1530	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1531	sbyte* getelementptr ([7 x sbyte]* %str1, int 0, int 0),
				1532	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1533	int 1,
				1534	uint 0,
				1535	uint 0,
				1536	uint 0,
				1537	{ }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> to { }*) }, section "llvm.metadata"
				1538	%str1 = internal constant [7 x sbyte] c"IntPtr\00", section "llvm.metadata"
				1539
				1540	;;
				1541	;; Define the pointer type.
				1542	;;
				1543	%<a href="#format_derived_type">llvm.dbg.derivedtype2</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
				1544	uint add(uint 15, uint 262144),
				1545	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1546	sbyte* null,
				1547	{ }* null,
				1548	int 0,
				1549	uint 32,
				1550	uint 32,
				1551	uint 0,
				1552	{ }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> to { }*) }, section "llvm.metadata"
				1553
				1554	;;
				1555	;; Define the const type.
				1556	;;
				1557	%<a href="#format_derived_type">llvm.dbg.derivedtype3</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
				1558	uint add(uint 38, uint 262144),
				1559	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1560	sbyte* null,
				1561	{ }* null,
				1562	int 0,
				1563	uint 0,
				1564	uint 0,
				1565	uint 0,
				1566	{ }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype1</a> to { }*) }, section "llvm.metadata"
				1567
				1568	;;
				1569	;; Define the int type.
				1570	;;
				1571	%<a href="#format_basic_type">llvm.dbg.basictype1</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1572	uint add(uint 36, uint 262144),
				1573	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1574	sbyte* getelementptr ([4 x sbyte]* %str2, int 0, int 0),
				1575	{ }* null,
				1576	int 0,
				1577	uint 32,
				1578	uint 32,
				1579	uint 0,
				1580	uint 5 }, section "llvm.metadata"
				1581	%str2 = internal constant [4 x sbyte] c"int\00", section "llvm.metadata"
				1582	</pre>
				1583
				1584	</div>
				1585
				1586	<!-- ======================================================================= -->
				1587	<div class="doc_subsection">
				1588	<a name="ccxx_composite_types">C/C++ struct/union types</a>
				1589	</div>
				1590
				1591	<div class="doc_text">
				1592
				1593	<p>Given the following as an example of C/C++ struct type;</p>
				1594
				1595	<pre>
				1596	struct Color {
				1597	unsigned Red;
				1598	unsigned Green;
				1599	unsigned Blue;
				1600	};
				1601	</pre>
				1602
				1603	<p>a C/C++ front-end would generate the following descriptors;</p>
				1604
				1605	<pre>
				1606	;;
				1607	;; Define basic type for unsigned int.
				1608	;;
				1609	%<a href="#format_basic_type">llvm.dbg.basictype</a> = internal constant %<a href="#format_basic_type">llvm.dbg.basictype.type</a> {
				1610	uint add(uint 36, uint 262144),
				1611	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1612	sbyte* getelementptr ([13 x sbyte]* %str1, int 0, int 0),
				1613	{ }* null,
				1614	int 0,
				1615	uint 32,
				1616	uint 32,
				1617	uint 0,
				1618	uint 7 }, section "llvm.metadata"
				1619	%str1 = internal constant [13 x sbyte] c"unsigned int\00", section "llvm.metadata"
				1620
				1621	;;
				1622	;; Define composite type for struct Color.
				1623	;;
				1624	%<a href="#format_composite_type">llvm.dbg.compositetype</a> = internal constant %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> {
				1625	uint add(uint 19, uint 262144),
				1626	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1627	sbyte* getelementptr ([6 x sbyte]* %str2, int 0, int 0),
				1628	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1629	int 1,
				1630	uint 96,
				1631	uint 32,
				1632	uint 0,
				1633	{ }* null,
				1634	{ }* cast ([3 x { }] %llvm.dbg.array to { }*) }, section "llvm.metadata"
				1635	%str2 = internal constant [6 x sbyte] c"Color\00", section "llvm.metadata"
				1636
				1637	;;
				1638	;; Define the Red field.
				1639	;;
				1640	%<a href="#format_derived_type">llvm.dbg.derivedtype1</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
				1641	uint add(uint 13, uint 262144),
				1642	{ }* null,
				1643	sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0),
				1644	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1645	int 2,
				1646	uint 32,
				1647	uint 32,
				1648	uint 0,
				1649	{ }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata"
				1650	%str3 = internal constant [4 x sbyte] c"Red\00", section "llvm.metadata"
				1651
				1652	;;
				1653	;; Define the Green field.
				1654	;;
				1655	%<a href="#format_derived_type">llvm.dbg.derivedtype2</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
				1656	uint add(uint 13, uint 262144),
				1657	{ }* null,
				1658	sbyte* getelementptr ([6 x sbyte]* %str4, int 0, int 0),
				1659	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1660	int 3,
				1661	uint 32,
				1662	uint 32,
				1663	uint 32,
				1664	{ }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata"
				1665	%str4 = internal constant [6 x sbyte] c"Green\00", section "llvm.metadata"
				1666
				1667	;;
				1668	;; Define the Blue field.
				1669	;;
				1670	%<a href="#format_derived_type">llvm.dbg.derivedtype3</a> = internal constant %<a href="#format_derived_type">llvm.dbg.derivedtype.type</a> {
				1671	uint add(uint 13, uint 262144),
				1672	{ }* null,
				1673	sbyte* getelementptr ([5 x sbyte]* %str5, int 0, int 0),
				1674	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1675	int 4,
				1676	uint 32,
				1677	uint 32,
				1678	uint 64,
				1679	{ }* cast (%<a href="#format_basic_type">llvm.dbg.basictype.type</a>* %<a href="#format_basic_type">llvm.dbg.basictype</a> to { }*) }, section "llvm.metadata"
				1680	%str5 = internal constant [5 x sbyte] c"Blue\00", section "llvm.metadata"
				1681
				1682	;;
				1683	;; Define the array of fields used by the composite type Color.
				1684	;;
				1685	%llvm.dbg.array = internal constant [3 x { }*] [
				1686	{ }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype1</a> to { }*),
				1687	{ }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype2</a> to { }*),
				1688	{ }* cast (%<a href="#format_derived_type">llvm.dbg.derivedtype.type</a>* %<a href="#format_derived_type">llvm.dbg.derivedtype3</a> to { }*) ], section "llvm.metadata"
				1689	</pre>
				1690
				1691	</div>
				1692
				1693	<!-- ======================================================================= -->
				1694	<div class="doc_subsection">
				1695	<a name="ccxx_enumeration_types">C/C++ enumeration types</a>
				1696	</div>
				1697
				1698	<div class="doc_text">
				1699
				1700	<p>Given the following as an example of C/C++ enumeration type;</p>
				1701
				1702	<pre>
				1703	enum Trees {
				1704	Spruce = 100,
				1705	Oak = 200,
				1706	Maple = 300
				1707	};
				1708	</pre>
				1709
				1710	<p>a C/C++ front-end would generate the following descriptors;</p>
				1711
				1712	<pre>
				1713	;;
				1714	;; Define composite type for enum Trees
				1715	;;
				1716	%<a href="#format_composite_type">llvm.dbg.compositetype</a> = internal constant %<a href="#format_composite_type">llvm.dbg.compositetype.type</a> {
				1717	uint add(uint 4, uint 262144),
				1718	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1719	sbyte* getelementptr ([6 x sbyte]* %str1, int 0, int 0),
				1720	{ }* cast (%<a href="#format_compile_units">llvm.dbg.compile_unit.type</a>* %<a href="#format_compile_units">llvm.dbg.compile_unit</a> to { }*),
				1721	int 1,
				1722	uint 32,
				1723	uint 32,
				1724	uint 0,
				1725	{ }* null,
				1726	{ }* cast ([3 x { }] %llvm.dbg.array to { }*) }, section "llvm.metadata"
				1727	%str1 = internal constant [6 x sbyte] c"Trees\00", section "llvm.metadata"
				1728
				1729	;;
				1730	;; Define Spruce enumerator.
				1731	;;
				1732	%<a href="#format_enumeration">llvm.dbg.enumerator1</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
				1733	uint add(uint 40, uint 262144),
				1734	sbyte* getelementptr ([7 x sbyte]* %str2, int 0, int 0),
				1735	int 100 }, section "llvm.metadata"
				1736	%str2 = internal constant [7 x sbyte] c"Spruce\00", section "llvm.metadata"
				1737
				1738	;;
				1739	;; Define Oak enumerator.
				1740	;;
				1741	%<a href="#format_enumeration">llvm.dbg.enumerator2</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
				1742	uint add(uint 40, uint 262144),
				1743	sbyte* getelementptr ([4 x sbyte]* %str3, int 0, int 0),
				1744	int 200 }, section "llvm.metadata"
				1745	%str3 = internal constant [4 x sbyte] c"Oak\00", section "llvm.metadata"
				1746
				1747	;;
				1748	;; Define Maple enumerator.
				1749	;;
				1750	%<a href="#format_enumeration">llvm.dbg.enumerator3</a> = internal constant %<a href="#format_enumeration">llvm.dbg.enumerator.type</a> {
				1751	uint add(uint 40, uint 262144),
				1752	sbyte* getelementptr ([6 x sbyte]* %str4, int 0, int 0),
				1753	int 300 }, section "llvm.metadata"
				1754	%str4 = internal constant [6 x sbyte] c"Maple\00", section "llvm.metadata"
				1755
				1756	;;
				1757	;; Define the array of enumerators used by composite type Trees.
				1758	;;
				1759	%llvm.dbg.array = internal constant [3 x { }*] [
				1760	{ }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator1</a> to { }*),
				1761	{ }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator2</a> to { }*),
				1762	{ }* cast (%<a href="#format_enumeration">llvm.dbg.enumerator.type</a>* %<a href="#format_enumeration">llvm.dbg.enumerator3</a> to { }*) ], section "llvm.metadata"
				1763	</pre>
				1764
				1765	</div>
				1766
				1767	<!-- *********************************************************************** -->
				1768
				1769	<hr>
				1770	<address>
				1771	<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
				1772	src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
				1773	<a href="http://validator.w3.org/check/referer"><img
				1774	src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
				1775
				1776	<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
				1777	<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
				1778	Last modified: $Date$
				1779	</address>
				1780
				1781	</body>
				1782	</html>