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

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