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

blob: 6a3d675080b8ad178977834fd4efebfe889c5735 [file] [log] [blame]

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