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

blob: 57f2603e3541b498d53dd6203b9f4e7419254295 [file] [log] [blame]

Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	2	<html><head><title>LLVM Assembly Language Reference Manual</title></head>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	3	<body bgcolor=white>
				4
				5	<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	6	<tr><td>  <font size=+5 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>LLVM Language Reference Manual</b></font></td>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	7	</tr></table>
				8
				9	<ol>
				10	<li><a href="#abstract">Abstract</a>
				11	<li><a href="#introduction">Introduction</a>
				12	<li><a href="#identifiers">Identifiers</a>
				13	<li><a href="#typesystem">Type System</a>
				14	<ol>
				15	<li><a href="#t_primitive">Primitive Types</a>
				16	<ol>
				17	<li><a href="#t_classifications">Type Classifications</a>
				18	</ol>
				19	<li><a href="#t_derived">Derived Types</a>
				20	<ol>
				21	<li><a href="#t_array" >Array Type</a>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	22	<li><a href="#t_function">Function Type</a>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	23	<li><a href="#t_pointer">Pointer Type</a>
				24	<li><a href="#t_struct" >Structure Type</a>
Chris Lattner	690d99b	2002-08-29 18:33:48 +0000	[diff] [blame]	25	<!-- <li><a href="#t_packed" >Packed Type</a> -->
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	26	</ol>
				27	</ol>
				28	<li><a href="#highlevel">High Level Structure</a>
				29	<ol>
				30	<li><a href="#modulestructure">Module Structure</a>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	31	<li><a href="#globalvars">Global Variables</a>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	32	<li><a href="#functionstructure">Function Structure</a>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	33	</ol>
				34	<li><a href="#instref">Instruction Reference</a>
				35	<ol>
				36	<li><a href="#terminators">Terminator Instructions</a>
				37	<ol>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	38	<li><a href="#i_ret" >'<tt>ret</tt>' Instruction</a>
				39	<li><a href="#i_br" >'<tt>br</tt>' Instruction</a>
				40	<li><a href="#i_switch">'<tt>switch</tt>' Instruction</a>
				41	<li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	42	</ol>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	43	<li><a href="#binaryops">Binary Operations</a>
				44	<ol>
				45	<li><a href="#i_add" >'<tt>add</tt>' Instruction</a>
				46	<li><a href="#i_sub" >'<tt>sub</tt>' Instruction</a>
				47	<li><a href="#i_mul" >'<tt>mul</tt>' Instruction</a>
				48	<li><a href="#i_div" >'<tt>div</tt>' Instruction</a>
				49	<li><a href="#i_rem" >'<tt>rem</tt>' Instruction</a>
				50	<li><a href="#i_setcc">'<tt>set<i>cc</i></tt>' Instructions</a>
				51	</ol>
				52	<li><a href="#bitwiseops">Bitwise Binary Operations</a>
				53	<ol>
				54	<li><a href="#i_and">'<tt>and</tt>' Instruction</a>
				55	<li><a href="#i_or" >'<tt>or</tt>' Instruction</a>
				56	<li><a href="#i_xor">'<tt>xor</tt>' Instruction</a>
				57	<li><a href="#i_shl">'<tt>shl</tt>' Instruction</a>
				58	<li><a href="#i_shr">'<tt>shr</tt>' Instruction</a>
				59	</ol>
				60	<li><a href="#memoryops">Memory Access Operations</a>
				61	<ol>
				62	<li><a href="#i_malloc" >'<tt>malloc</tt>' Instruction</a>
				63	<li><a href="#i_free" >'<tt>free</tt>' Instruction</a>
				64	<li><a href="#i_alloca" >'<tt>alloca</tt>' Instruction</a>
				65	<li><a href="#i_load" >'<tt>load</tt>' Instruction</a>
				66	<li><a href="#i_store" >'<tt>store</tt>' Instruction</a>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	67	<li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	68	</ol>
				69	<li><a href="#otherops">Other Operations</a>
				70	<ol>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	71	<li><a href="#i_phi" >'<tt>phi</tt>' Instruction</a>
Chris Lattner	33ba0d9	2001-07-09 00:26:23 +0000	[diff] [blame]	72	<li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	73	<li><a href="#i_call" >'<tt>call</tt>' Instruction</a>
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	74	<li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	75	</ol>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	76	</ol>
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	77	<li><a href="#intrinsics">Intrinsic Functions</a>
				78	<ol>
				79	<li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
				80	<ol>
				81	<li><a href="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
				82	<li><a href="#i_va_end" >'<tt>llvm.va_end</tt>' Intrinsic</a>
				83	<li><a href="#i_va_copy" >'<tt>llvm.va_copy</tt>' Intrinsic</a>
Chris Lattner	b3ceec2	2003-08-28 22:12:25 +0000	[diff] [blame]	84	<li><a href="#i_unwind" >'<tt>llvm.unwind</tt>' Intrinsic</a>
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	85	</ol>
				86	</ol>
Chris Lattner	d816bcf	2002-08-30 21:50:21 +0000	[diff] [blame]	87
				88	<p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and <A href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></b><p>
				89
				90
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	91	</ol>
				92
				93
				94	<!-- *********************************************************************** -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	95	<p><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				96	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	97	<a name="abstract">Abstract
				98	</b></font></td></tr></table><ul>
				99	<!-- *********************************************************************** -->
				100
				101	<blockquote>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	102	This document is a reference manual for the LLVM assembly language. LLVM is
Chris Lattner	fde246a	2003-09-02 23:38:41 +0000	[diff] [blame^]	103	an SSA based representation that provides type safety, low-level operations,
				104	flexibility, and the capability of representing 'all' high-level languages
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	105	cleanly. It is the common code representation used throughout all phases of
				106	the LLVM compilation strategy.
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	107	</blockquote>
				108
				109
				110
				111
				112	<!-- *********************************************************************** -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	113	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				114	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	115	<a name="introduction">Introduction
				116	</b></font></td></tr></table><ul>
				117	<!-- *********************************************************************** -->
				118
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	119	The LLVM code representation is designed to be used in three different forms: as
Chris Lattner	fde246a	2003-09-02 23:38:41 +0000	[diff] [blame^]	120	an in-memory compiler IR, as an on-disk bytecode representation (suitable for
				121	fast loading by a Just-In-Time compiler), and as a human readable assembly
				122	language representation. This allows LLVM to provide a powerful intermediate
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	123	representation for efficient compiler transformations and analysis, while
				124	providing a natural means to debug and visualize the transformations. The three
				125	different forms of LLVM are all equivalent. This document describes the human
				126	readable representation and notation.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	127
Chris Lattner	fde246a	2003-09-02 23:38:41 +0000	[diff] [blame^]	128	The LLVM representation aims to be a light-weight and low-level while being
Chris Lattner	b7c6c2a	2002-06-25 20:20:08 +0000	[diff] [blame]	129	expressive, typed, and extensible at the same time. It aims to be a "universal
Chris Lattner	fde246a	2003-09-02 23:38:41 +0000	[diff] [blame^]	130	IR" of sorts, by being at a low enough level that high-level ideas may be
Chris Lattner	b7c6c2a	2002-06-25 20:20:08 +0000	[diff] [blame]	131	cleanly mapped to it (similar to how microprocessors are "universal IR's",
				132	allowing many source languages to be mapped to them). By providing type
				133	information, LLVM can be used as the target of optimizations: for example,
				134	through pointer analysis, it can be proven that a C automatic variable is never
				135	accessed outside of the current function... allowing it to be promoted to a
				136	simple SSA value instead of a memory location.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	137
				138	<!-- _______________________________________________________________________ -->
				139	</ul><a name="wellformed"><h4><hr size=0>Well Formedness</h4><ul>
				140
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	141	It is important to note that this document describes 'well formed' LLVM assembly
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	142	language. There is a difference between what the parser accepts and what is
				143	considered 'well formed'. For example, the following instruction is
				144	syntactically okay, but not well formed:<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	145
				146	<pre>
				147	%x = <a href="#i_add">add</a> int 1, %x
				148	</pre>
				149
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	150	...because the definition of <tt>%x</tt> does not dominate all of its uses. The
				151	LLVM infrastructure provides a verification pass that may be used to verify that
				152	an LLVM module is well formed. This pass is automatically run by the parser
				153	after parsing input assembly, and by the optimizer before it outputs bytecode.
				154	The violations pointed out by the verifier pass indicate bugs in transformation
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	155	passes or input to the parser.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	156
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	157	<!-- Describe the typesetting conventions here. -->
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	158
				159
				160	<!-- *********************************************************************** -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	161	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				162	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	163	<a name="identifiers">Identifiers
				164	</b></font></td></tr></table><ul>
				165	<!-- *********************************************************************** -->
				166
				167	LLVM uses three different forms of identifiers, for different purposes:<p>
				168
				169	<ol>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	170	<li>Numeric constants are represented as you would expect: 12, -3 123.421, etc. Floating point constants have an optional hexidecimal notation.
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	171	<li>Named values are represented as a string of characters with a '%' prefix. For example, %foo, %DivisionByZero, %a.really.long.identifier. The actual regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
				172	<li>Unnamed values are represented as an unsigned numeric value with a '%' prefix. For example, %12, %2, %44.
				173	</ol><p>
				174
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	175	LLVM requires the values start with a '%' sign for two reasons: Compilers don't
				176	need to worry about name clashes with reserved words, and the set of reserved
				177	words may be expanded in the future without penalty. Additionally, unnamed
				178	identifiers allow a compiler to quickly come up with a temporary variable
				179	without having to avoid symbol table conflicts.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	180
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	181	Reserved words in LLVM are very similar to reserved words in other languages.
				182	There are keywords for different opcodes ('<tt><a href="#i_add">add</a></tt>',
				183	'<tt><a href="#i_cast">cast</a></tt>', '<tt><a href="#i_ret">ret</a></tt>',
				184	etc...), for primitive type names ('<tt><a href="#t_void">void</a></tt>',
				185	'<tt><a href="#t_uint">uint</a></tt>', etc...), and others. These reserved
				186	words cannot conflict with variable names, because none of them start with a '%'
				187	character.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	188
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	189	Here is an example of LLVM code to multiply the integer variable '<tt>%X</tt>'
				190	by 8:<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	191
				192	The easy way:
				193	<pre>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	194	%result = <a href="#i_mul">mul</a> uint %X, 8
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	195	</pre>
				196
				197	After strength reduction:
				198	<pre>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	199	%result = <a href="#i_shl">shl</a> uint %X, ubyte 3
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	200	</pre>
				201
				202	And the hard way:
				203	<pre>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	204	<a href="#i_add">add</a> uint %X, %X <i>; yields {uint}:%0</i>
				205	<a href="#i_add">add</a> uint %0, %0 <i>; yields {uint}:%1</i>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	206	%result = <a href="#i_add">add</a> uint %1, %1
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	207	</pre>
				208
				209	This last way of multiplying <tt>%X</tt> by 8 illustrates several important lexical features of LLVM:<p>
				210
				211	<ol>
				212	<li>Comments are delimited with a '<tt>;</tt>' and go until the end of line.
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	213	<li>Unnamed temporaries are created when the result of a computation is not
				214	assigned to a named value.
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	215	<li>Unnamed temporaries are numbered sequentially
				216	</ol><p>
				217
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	218	...and it also show a convention that we follow in this document. When
				219	demonstrating instructions, we will follow an instruction with a comment that
				220	defines the type and name of value produced. Comments are shown in italic
				221	text.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	222
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	223	The one non-intuitive notation for constants is the optional hexidecimal form of
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	224	floating point constants. For example, the form '<tt>double
				225	0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
				226	4.5e+15</tt>' which is also supported by the parser. The only time hexadecimal
				227	floating point constants are useful (and the only time that they are generated
				228	by the disassembler) is when an FP constant has to be emitted that is not
				229	representable as a decimal floating point number exactly. For example, NaN's,
				230	infinities, and other special cases are represented in their IEEE hexadecimal
				231	format so that assembly and disassembly do not cause any bits to change in the
				232	constants.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	233
				234
				235	<!-- *********************************************************************** -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	236	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				237	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	238	<a name="typesystem">Type System
				239	</b></font></td></tr></table><ul>
				240	<!-- *********************************************************************** -->
				241
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	242	The LLVM type system is one of the most important features of the intermediate
Chris Lattner	b7c6c2a	2002-06-25 20:20:08 +0000	[diff] [blame]	243	representation. Being typed enables a number of optimizations to be performed
				244	on the IR directly, without having to do extra analyses on the side before the
				245	transformation. A strong type system makes it easier to read the generated code
				246	and enables novel analyses and transformations that are not feasible to perform
				247	on normal three address code representations.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	248
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	249	<!-- The written form for the type system was heavily influenced by the
				250	syntactic problems with types in the C language<sup><a
				251	href="#rw_stroustrup">1</a></sup>.<p> -->
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	252
				253
				254
				255	<!-- ======================================================================= -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	256	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				257	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	258	<a name="t_primitive">Primitive Types
				259	</b></font></td></tr></table><ul>
				260
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	261	The primitive types are the fundemental building blocks of the LLVM system. The
				262	current set of primitive types are as follows:<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	263
				264	<table border=0 align=center><tr><td>
				265
				266	<table border=1 cellspacing=0 cellpadding=4 align=center>
				267	<tr><td><tt>void</tt></td> <td>No value</td></tr>
				268	<tr><td><tt>ubyte</tt></td> <td>Unsigned 8 bit value</td></tr>
				269	<tr><td><tt>ushort</tt></td><td>Unsigned 16 bit value</td></tr>
				270	<tr><td><tt>uint</tt></td> <td>Unsigned 32 bit value</td></tr>
				271	<tr><td><tt>ulong</tt></td> <td>Unsigned 64 bit value</td></tr>
				272	<tr><td><tt>float</tt></td> <td>32 bit floating point value</td></tr>
				273	<tr><td><tt>label</tt></td> <td>Branch destination</td></tr>
				274	</table>
				275
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	276	</td><td valign=top>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	277
				278	<table border=1 cellspacing=0 cellpadding=4 align=center>
				279	<tr><td><tt>bool</tt></td> <td>True or False value</td></tr>
				280	<tr><td><tt>sbyte</tt></td> <td>Signed 8 bit value</td></tr>
				281	<tr><td><tt>short</tt></td> <td>Signed 16 bit value</td></tr>
				282	<tr><td><tt>int</tt></td> <td>Signed 32 bit value</td></tr>
				283	<tr><td><tt>long</tt></td> <td>Signed 64 bit value</td></tr>
				284	<tr><td><tt>double</tt></td><td>64 bit floating point value</td></tr>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	285	</table>
				286
				287	</td></tr></table><p>
				288
				289
				290
				291	<!-- _______________________________________________________________________ -->
				292	</ul><a name="t_classifications"><h4><hr size=0>Type Classifications</h4><ul>
				293
				294	These different primitive types fall into a few useful classifications:<p>
				295
				296	<table border=1 cellspacing=0 cellpadding=4 align=center>
				297	<tr><td><a name="t_signed">signed</td> <td><tt>sbyte, short, int, long, float, double</tt></td></tr>
				298	<tr><td><a name="t_unsigned">unsigned</td><td><tt>ubyte, ushort, uint, ulong</tt></td></tr>
Chris Lattner	b5561ff	2003-06-18 21:28:11 +0000	[diff] [blame]	299	<tr><td><a name="t_integer">integer</td><td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td></tr>
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	300	<tr><td><a name="t_integral">integral</td><td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td></tr>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	301	<tr><td><a name="t_floating">floating point</td><td><tt>float, double</tt></td></tr>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	302	<tr><td><a name="t_firstclass">first class</td><td><tt>bool, ubyte, sbyte, ushort, short,<br> uint, int, ulong, long, float, double, <a href="#t_pointer">pointer</a></tt></td></tr>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	303	</table><p>
				304
				305
				306
				307
				308
				309	<!-- ======================================================================= -->
				310	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				311	<a name="t_derived">Derived Types
				312	</b></font></td></tr></table><ul>
				313
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	314	The real power in LLVM comes from the derived types in the system. This is what
				315	allows a programmer to represent arrays, functions, pointers, and other useful
				316	types. Note that these derived types may be recursive: For example, it is
				317	possible to have a two dimensional array.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	318
				319
				320
				321	<!-- _______________________________________________________________________ -->
				322	</ul><a name="t_array"><h4><hr size=0>Array Type</h4><ul>
				323
				324	<h5>Overview:</h5>
				325
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	326	The array type is a very simple derived type that arranges elements sequentially
				327	in memory. The array type requires a size (number of elements) and an
				328	underlying data type.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	329
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	330	<h5>Syntax:</h5>
				331	<pre>
				332	[<# elements> x <elementtype>]
				333	</pre>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	334
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	335	The number of elements is a constant integer value, elementtype may be any type
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	336	with a size.<p>
				337
				338	<h5>Examples:</h5>
				339	<ul>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	340	<tt>[40 x int ]</tt>: Array of 40 integer values.<br>
				341	<tt>[41 x int ]</tt>: Array of 41 integer values.<br>
				342	<tt>[40 x uint]</tt>: Array of 40 unsigned integer values.<p>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	343	</ul>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	344
				345	Here are some examples of multidimensional arrays:<p>
				346	<ul>
				347	<table border=0 cellpadding=0 cellspacing=0>
				348	<tr><td><tt>[3 x [4 x int]]</tt></td><td>: 3x4 array integer values.</td></tr>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	349	<tr><td><tt>[12 x [10 x float]]</tt></td><td>: 2x10 array of single precision floating point values.</td></tr>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	350	<tr><td><tt>[2 x [3 x [4 x uint]]]</tt></td><td>: 2x3x4 array of unsigned integer values.</td></tr>
				351	</table>
				352	</ul>
				353
				354
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	355	<!-- _______________________________________________________________________ -->
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	356	</ul><a name="t_function"><h4><hr size=0>Function Type</h4><ul>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	357
				358	<h5>Overview:</h5>
				359
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	360	The function type can be thought of as a function signature. It consists of a
				361	return type and a list of formal parameter types. Function types are usually
				362	used when to build virtual function tables (which are structures of pointers to
				363	functions), for indirect function calls, and when defining a function.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	364
				365	<h5>Syntax:</h5>
				366	<pre>
				367	<returntype> (<parameter list>)
				368	</pre>
				369
Misha Brukman	bc0e998	2003-07-14 17:20:40 +0000	[diff] [blame]	370	Where '<tt><parameter list></tt>' is a comma-separated list of type
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	371	specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
				372	which indicates that the function takes a variable number of arguments. Note
				373	that there currently is no way to define a function in LLVM that takes a
				374	variable number of arguments, but it is possible to <b>call</b> a function that
				375	is vararg.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	376
				377	<h5>Examples:</h5>
				378	<ul>
				379	<table border=0 cellpadding=0 cellspacing=0>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	380
				381	<tr><td><tt>int (int)</tt></td><td>: function taking an <tt>int</tt>, returning
				382	an <tt>int</tt></td></tr>
				383
				384	<tr><td><tt>float (int, int ) </tt></td><td>: <a href="#t_pointer">Pointer</a>
				385	to a function that takes an <tt>int</tt> and a <a href="#t_pointer">pointer</a>
				386	to <tt>int</tt>, returning <tt>float</tt>.</td></tr>
				387
				388	<tr><td><tt>int (sbyte *, ...)</tt></td><td>: A vararg function that takes at
				389	least one <a href="#t_pointer">pointer</a> to <tt>sbyte</tt> (signed char in C),
				390	which returns an integer. This is the signature for <tt>printf</tt> in
				391	LLVM.</td></tr>
				392
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	393	</table>
				394	</ul>
				395
				396
				397
				398	<!-- _______________________________________________________________________ -->
				399	</ul><a name="t_struct"><h4><hr size=0>Structure Type</h4><ul>
				400
				401	<h5>Overview:</h5>
				402
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	403	The structure type is used to represent a collection of data members together in
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	404	memory. The packing of the field types is defined to match the ABI of the
				405	underlying processor. The elements of a structure may be any type that has a
				406	size.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	407
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	408	Structures are accessed using '<tt><a href="#i_load">load</a></tt> and '<tt><a
				409	href="#i_store">store</a></tt>' by getting a pointer to a field with the '<tt><a
				410	href="#i_getelementptr">getelementptr</a></tt>' instruction.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	411
				412	<h5>Syntax:</h5>
				413	<pre>
				414	{ <type list> }
				415	</pre>
				416
				417
				418	<h5>Examples:</h5>
				419	<table border=0 cellpadding=0 cellspacing=0>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	420
				421	<tr><td><tt>{ int, int, int }</tt></td><td>: a triple of three <tt>int</tt>
				422	values</td></tr>
				423
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	424	<tr><td><tt>{ float, int (int) * }</tt></td><td>: A pair, where the first
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	425	element is a <tt>float</tt> and the second element is a <a
				426	href="#t_pointer">pointer</a> to a <a href="t_function">function</a> that takes
				427	an <tt>int</tt>, returning an <tt>int</tt>.</td></tr>
				428
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	429	</table>
				430
				431
				432	<!-- _______________________________________________________________________ -->
				433	</ul><a name="t_pointer"><h4><hr size=0>Pointer Type</h4><ul>
				434
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	435	<h5>Overview:</h5>
				436
				437	As in many languages, the pointer type represents a pointer or reference to
				438	another object, which must live in memory.<p>
				439
				440	<h5>Syntax:</h5>
				441	<pre>
				442	<type> *
				443	</pre>
				444
				445	<h5>Examples:</h5>
				446
				447	<table border=0 cellpadding=0 cellspacing=0>
				448
				449	<tr><td><tt>[4x int]*</tt></td><td>: <a href="#t_pointer">pointer</a> to <a
				450	href="#t_array">array</a> of four <tt>int</tt> values</td></tr>
				451
				452	<tr><td><tt>int (int ) </tt></td><td>: A <a href="#t_pointer">pointer</a> to a
				453	<a href="t_function">function</a> that takes an <tt>int</tt>, returning an
				454	<tt>int</tt>.</td></tr>
				455
				456	</table>
				457	<p>
				458
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	459
				460	<!-- _______________________________________________________________________ -->
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	461	<!--
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	462	</ul><a name="t_packed"><h4><hr size=0>Packed Type</h4><ul>
				463
				464	Mention/decide that packed types work with saturation or not. Maybe have a packed+saturated type in addition to just a packed type.<p>
				465
				466	Packed types should be 'nonsaturated' because standard data types are not saturated. Maybe have a saturated packed type?<p>
				467
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	468	-->
				469
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	470
				471	<!-- *********************************************************************** -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	472	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				473	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	474	<a name="highlevel">High Level Structure
				475	</b></font></td></tr></table><ul>
				476	<!-- *********************************************************************** -->
				477
				478
				479	<!-- ======================================================================= -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	480	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				481	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	482	<a name="modulestructure">Module Structure
				483	</b></font></td></tr></table><ul>
				484
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	485	LLVM programs are composed of "Module"s, each of which is a translation unit of
				486	the input programs. Each module consists of functions, global variables, and
				487	symbol table entries. Modules may be combined together with the LLVM linker,
				488	which merges function (and global variable) definitions, resolves forward
				489	declarations, and merges symbol table entries. Here is an example of the "hello world" module:<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	490
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	491	<pre>
				492	<i>; Declare the string constant as a global constant...</i>
				493	<a href="#identifiers">%.LC0</a> = <a href="#linkage_decl">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x sbyte]</a> c"hello world\0A\00" <i>; [13 x sbyte]*</i>
				494
				495	<i>; Forward declaration of puts</i>
				496	<a href="#functionstructure">declare</a> int "puts"(sbyte) <i>; int(sbyte)* </i>
				497
				498	<i>; Definition of main function</i>
				499	int "main"() { <i>; int()* </i>
				500	<i>; Convert [13x sbyte]* to sbyte *...</i>
Chris Lattner	3dfa10b	2002-12-13 06:01:21 +0000	[diff] [blame]	501	%cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	502
				503	<i>; Call puts function to write out the string to stdout...</i>
				504	<a href="#i_call">call</a> int %puts(sbyte* %cast210) <i>; int</i>
				505	<a href="#i_ret">ret</a> int 0
				506	}
				507	</pre>
				508
				509	This example is made up of a <a href="#globalvars">global variable</a> named
				510	"<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and a
				511	<a href="#functionstructure">function definition</a> for "<tt>main</tt>".<p>
				512
				513	<a name="linkage_decl">
				514	In general, a module is made up of a list of global values, where both functions
				515	and global variables are global values. Global values are represented by a
				516	pointer to a memory location (in this case, a pointer to an array of char, and a
				517	pointer to a function), and can be either "internal" or externally accessible
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	518	(which corresponds to the static keyword in C, when used at global scope).<p>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	519
				520	For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
				521	another module defined a "<tt>.LC0</tt>" variable and was linked with this one,
				522	one of the two would be renamed, preventing a collision. Since "<tt>main</tt>"
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	523	and "<tt>puts</tt>" are external (i.e., lacking "<tt>internal</tt>"
				524	declarations), they are accessible outside of the current module. It is illegal
				525	for a function declaration to be "<tt>internal</tt>".<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	526
				527
				528	<!-- ======================================================================= -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	529	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				530	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				531	<a name="globalvars">Global Variables
				532	</b></font></td></tr></table><ul>
				533
				534	Global variables define regions of memory allocated at compilation time instead
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	535	of run-time. Global variables may optionally be initialized. A variable may
				536	be defined as a global "constant", which indicates that the contents of the
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	537	variable will never be modified (opening options for optimization). Constants
				538	must always have an initial value.<p>
				539
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	540	As SSA values, global variables define pointer values that are in scope
				541	(i.e. they dominate) for all basic blocks in the program. Global variables
				542	always define a pointer to their "content" type because they describe a region
				543	of memory, and all memory objects in LLVM are accessed through pointers.<p>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	544
				545
				546
				547	<!-- ======================================================================= -->
				548	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				549	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	550	<a name="functionstructure">Function Structure
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	551	</b></font></td></tr></table><ul>
				552
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	553	LLVM functions definitions are composed of a (possibly empty) argument list, an
				554	opening curly brace, a list of basic blocks, and a closing curly brace. LLVM
				555	function declarations are defined with the "<tt>declare</tt>" keyword, a
				556	function name and a function signature.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	557
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	558	A function definition contains a list of basic blocks, forming the CFG for the
				559	function. Each basic block may optionally start with a label (giving the basic
				560	block a symbol table entry), contains a list of instructions, and ends with a <a
				561	href="#terminators">terminator</a> instruction (such as a branch or function
				562	return).<p>
				563
				564	The first basic block in program is special in two ways: it is immediately
				565	executed on entrance to the function, and it is not allowed to have predecessor
				566	basic blocks (i.e. there can not be any branches to the entry block of a
				567	function).<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	568
				569
				570	<!-- *********************************************************************** -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	571	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				572	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	573	<a name="instref">Instruction Reference
				574	</b></font></td></tr></table><ul>
				575	<!-- *********************************************************************** -->
				576
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	577	The LLVM instruction set consists of several different classifications of
Chris Lattner	e489aa5	2002-08-14 17:55:59 +0000	[diff] [blame]	578	instructions: <a href="#terminators">terminator instructions</a>, <a
				579	href="#binaryops">binary instructions</a>, <a href="#memoryops">memory
				580	instructions</a>, and <a href="#otherops">other instructions</a>.<p>
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	581
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	582
				583	<!-- ======================================================================= -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	584	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				585	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	586	<a name="terminators">Terminator Instructions
				587	</b></font></td></tr></table><ul>
				588
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	589	As mentioned <a href="#functionstructure">previously</a>, every basic block in a
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	590	program ends with a "Terminator" instruction, which indicates which block should
				591	be executed after the current block is finished. These terminator instructions
				592	typically yield a '<tt>void</tt>' value: they produce control flow, not values
				593	(the one exception being the '<a href="#i_invoke"><tt>invoke</tt></a>'
				594	instruction).<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	595
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	596	There are four different terminator instructions: the '<a
				597	href="#i_ret"><tt>ret</tt></a>' instruction, the '<a
				598	href="#i_br"><tt>br</tt></a>' instruction, the '<a
				599	href="#i_switch"><tt>switch</tt></a>' instruction, and the '<a
				600	href="#i_invoke"><tt>invoke</tt></a>' instruction.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	601
				602
				603	<!-- _______________________________________________________________________ -->
				604	</ul><a name="i_ret"><h4><hr size=0>'<tt>ret</tt>' Instruction</h4><ul>
				605
				606	<h5>Syntax:</h5>
				607	<pre>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	608	ret <type> <value> <i>; Return a value from a non-void function</i>
				609	ret void <i>; Return from void function</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	610	</pre>
				611
				612	<h5>Overview:</h5>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	613
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	614	The '<tt>ret</tt>' instruction is used to return control flow (and a value) from
				615	a function, back to the caller.<p>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	616
				617	There are two forms of the '<tt>ret</tt>' instructruction: one that returns a
				618	value and then causes control flow, and one that just causes control flow to
				619	occur.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	620
				621	<h5>Arguments:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	622
				623	The '<tt>ret</tt>' instruction may return any '<a href="#t_firstclass">first
				624	class</a>' type. Notice that a function is not <a href="#wellformed">well
				625	formed</a> if there exists a '<tt>ret</tt>' instruction inside of the function
				626	that returns a value that does not match the return type of the function.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	627
				628	<h5>Semantics:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	629
				630	When the '<tt>ret</tt>' instruction is executed, control flow returns back to
				631	the calling function's context. If the instruction returns a value, that value
Misha Brukman	a3bbcb5	2002-10-29 23:06:16 +0000	[diff] [blame]	632	shall be propagated into the calling function's data space.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	633
				634	<h5>Example:</h5>
				635	<pre>
				636	ret int 5 <i>; Return an integer value of 5</i>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	637	ret void <i>; Return from a void function</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	638	</pre>
				639
				640
				641	<!-- _______________________________________________________________________ -->
				642	</ul><a name="i_br"><h4><hr size=0>'<tt>br</tt>' Instruction</h4><ul>
				643
				644	<h5>Syntax:</h5>
				645	<pre>
				646	br bool <cond>, label <iftrue>, label <iffalse>
				647	br label <dest> <i>; Unconditional branch</i>
				648	</pre>
				649
				650	<h5>Overview:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	651
				652	The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
				653	different basic block in the current function. There are two forms of this
				654	instruction, corresponding to a conditional branch and an unconditional
				655	branch.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	656
				657	<h5>Arguments:</h5>
				658
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	659	The conditional branch form of the '<tt>br</tt>' instruction takes a single
				660	'<tt>bool</tt>' value and two '<tt>label</tt>' values. The unconditional form
				661	of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
				662	target.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	663
				664	<h5>Semantics:</h5>
				665
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	666	Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>bool</tt>'
				667	argument is evaluated. If the value is <tt>true</tt>, control flows to the
				668	'<tt>iftrue</tt>' '<tt>label</tt>' argument. If "cond" is <tt>false</tt>,
				669	control flows to the '<tt>iffalse</tt>' '<tt>label</tt>' argument.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	670
				671	<h5>Example:</h5>
				672	<pre>
				673	Test:
				674	%cond = <a href="#i_setcc">seteq</a> int %a, %b
				675	br bool %cond, label %IfEqual, label %IfUnequal
				676	IfEqual:
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	677	<a href="#i_ret">ret</a> int 1
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	678	IfUnequal:
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	679	<a href="#i_ret">ret</a> int 0
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	680	</pre>
				681
				682
				683	<!-- _______________________________________________________________________ -->
				684	</ul><a name="i_switch"><h4><hr size=0>'<tt>switch</tt>' Instruction</h4><ul>
				685
				686	<h5>Syntax:</h5>
				687	<pre>
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	688	switch int <value>, label <defaultdest> [ int <val>, label &dest>, ... ]
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	689
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	690	</pre>
				691
				692	<h5>Overview:</h5>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	693
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	694	The '<tt>switch</tt>' instruction is used to transfer control flow to one of
				695	several different places. It is a generalization of the '<tt>br</tt>'
				696	instruction, allowing a branch to occur to one of many possible destinations.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	697
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	698	<h5>Arguments:</h5>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	699
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	700	The '<tt>switch</tt>' instruction uses three parameters: a '<tt>uint</tt>'
				701	comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
				702	an array of pairs of comparison value constants and '<tt>label</tt>'s.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	703
				704	<h5>Semantics:</h5>
				705
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	706	The <tt>switch</tt> instruction specifies a table of values and destinations.
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	707	When the '<tt>switch</tt>' instruction is executed, this table is searched for
				708	the given value. If the value is found, the corresponding destination is
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	709	branched to, otherwise the default value it transfered to.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	710
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	711	<h5>Implementation:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	712
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	713	Depending on properties of the target machine and the particular <tt>switch</tt>
				714	instruction, this instruction may be code generated as a series of chained
				715	conditional branches, or with a lookup table.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	716
				717	<h5>Example:</h5>
				718	<pre>
				719	<i>; Emulate a conditional br instruction</i>
				720	%Val = <a href="#i_cast">cast</a> bool %value to uint
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	721	switch int %Val, label %truedest [int 0, label %falsedest ]
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	722
				723	<i>; Emulate an unconditional br instruction</i>
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	724	switch int 0, label %dest [ ]
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	725
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	726	<i>; Implement a jump table:</i>
Chris Lattner	c29b125	2003-05-08 05:08:48 +0000	[diff] [blame]	727	switch int %val, label %otherwise [ int 0, label %onzero,
				728	int 1, label %onone,
				729	int 2, label %ontwo ]
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	730	</pre>
				731
				732
				733
				734	<!-- _______________________________________________________________________ -->
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	735	</ul><a name="i_invoke"><h4><hr size=0>'<tt>invoke</tt>' Instruction</h4><ul>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	736
				737	<h5>Syntax:</h5>
				738	<pre>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	739	<result> = invoke <ptr to function ty> %<function ptr val>(<function args>)
				740	to label <normal label> except label <exception label>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	741	</pre>
				742
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	743	<h5>Overview:</h5>
				744
Chris Lattner	b3ceec2	2003-08-28 22:12:25 +0000	[diff] [blame]	745	The '<tt>invoke</tt>' instruction causes control to transfer to a specified
				746	function, with the possibility of control flow transfer to either the
				747	'<tt>normal label</tt>' label or the '<tt>exception label</tt>'. If the callee
				748	function invokes the "<tt><a href="#i_ret">ret</a></tt>" instruction, control
				749	flow will return to the "normal" label. If the callee (or any indirect callees)
				750	calls the "<a href="#i_unwind"><tt>llvm.unwind</tt></a>" intrinsic, control is
				751	interrupted, and continued at the "except" label.<p>
				752
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	753
				754	<h5>Arguments:</h5>
				755
				756	This instruction requires several arguments:<p>
				757	<ol>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	758
				759	<li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	760	function value being invoked. In most cases, this is a direct function
Misha Brukman	e6fe671	2002-09-18 02:35:14 +0000	[diff] [blame]	761	invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
Chris Lattner	b3ceec2	2003-08-28 22:12:25 +0000	[diff] [blame]	762	an arbitrary pointer to function value.
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	763
				764	<li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
				765	function to be invoked.
				766
				767	<li>'<tt>function args</tt>': argument list whose types match the function
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	768	signature argument types. If the function signature indicates the function
				769	accepts a variable number of arguments, the extra arguments can be specified.
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	770
				771	<li>'<tt>normal label</tt>': the label reached when the called function executes
				772	a '<tt><a href="#i_ret">ret</a></tt>' instruction.
				773
Chris Lattner	b3ceec2	2003-08-28 22:12:25 +0000	[diff] [blame]	774	<li>'<tt>exception label</tt>': the label reached when a callee calls the <a
				775	href="#i_unwind"><tt>llvm.unwind</tt></a> intrinsic.
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	776	</ol>
				777
				778	<h5>Semantics:</h5>
				779
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	780	This instruction is designed to operate as a standard '<tt><a
				781	href="#i_call">call</a></tt>' instruction in most regards. The primary
Chris Lattner	b3ceec2	2003-08-28 22:12:25 +0000	[diff] [blame]	782	difference is that it establishes an association with a label, which is used by the runtime library to unwind the stack.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	783
Chris Lattner	b3ceec2	2003-08-28 22:12:25 +0000	[diff] [blame]	784	This instruction is used in languages with destructors to ensure that proper
				785	cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
				786	exception. Additionally, this is important for implementation of
				787	'<tt>catch</tt>' clauses in high-level languages that support them.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	788
				789	<h5>Example:</h5>
				790	<pre>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	791	%retval = invoke int %Test(int 15)
Chris Lattner	b3ceec2	2003-08-28 22:12:25 +0000	[diff] [blame]	792	to label %Continue
				793	except label %TestCleanup <i>; {int}:retval set</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	794	</pre>
				795
				796
				797
				798	<!-- ======================================================================= -->
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	799	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				800	<a name="binaryops">Binary Operations
				801	</b></font></td></tr></table><ul>
				802
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	803	Binary operators are used to do most of the computation in a program. They
				804	require two operands, execute an operation on them, and produce a single value.
				805	The result value of a binary operator is not neccesarily the same type as its
				806	operands.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	807
				808	There are several different binary operators:<p>
				809
				810
				811	<!-- _______________________________________________________________________ -->
				812	</ul><a name="i_add"><h4><hr size=0>'<tt>add</tt>' Instruction</h4><ul>
				813
				814	<h5>Syntax:</h5>
				815	<pre>
				816	<result> = add <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				817	</pre>
				818
				819	<h5>Overview:</h5>
				820	The '<tt>add</tt>' instruction returns the sum of its two operands.<p>
				821
				822	<h5>Arguments:</h5>
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	823	The two arguments to the '<tt>add</tt>' instruction must be either <a href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	824
				825	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	826
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	827	The value produced is the integer or floating point sum of the two operands.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	828
				829	<h5>Example:</h5>
				830	<pre>
				831	<result> = add int 4, %var <i>; yields {int}:result = 4 + %var</i>
				832	</pre>
				833
				834
				835	<!-- _______________________________________________________________________ -->
				836	</ul><a name="i_sub"><h4><hr size=0>'<tt>sub</tt>' Instruction</h4><ul>
				837
				838	<h5>Syntax:</h5>
				839	<pre>
				840	<result> = sub <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				841	</pre>
				842
				843	<h5>Overview:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	844
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	845	The '<tt>sub</tt>' instruction returns the difference of its two operands.<p>
				846
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	847	Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
				848	instruction present in most other intermediate representations.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	849
				850	<h5>Arguments:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	851
				852	The two arguments to the '<tt>sub</tt>' instruction must be either <a
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	853	href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	854	values. Both arguments must have identical types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	855
				856	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	857
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	858	The value produced is the integer or floating point difference of the two
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	859	operands.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	860
				861	<h5>Example:</h5>
				862	<pre>
				863	<result> = sub int 4, %var <i>; yields {int}:result = 4 - %var</i>
				864	<result> = sub int 0, %val <i>; yields {int}:result = -%var</i>
				865	</pre>
				866
				867	<!-- _______________________________________________________________________ -->
				868	</ul><a name="i_mul"><h4><hr size=0>'<tt>mul</tt>' Instruction</h4><ul>
				869
				870	<h5>Syntax:</h5>
				871	<pre>
				872	<result> = mul <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				873	</pre>
				874
				875	<h5>Overview:</h5>
				876	The '<tt>mul</tt>' instruction returns the product of its two operands.<p>
				877
				878	<h5>Arguments:</h5>
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	879	The two arguments to the '<tt>mul</tt>' instruction must be either <a href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	880
				881	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	882
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	883	The value produced is the integer or floating point product of the two
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	884	operands.<p>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	885
				886	There is no signed vs unsigned multiplication. The appropriate action is taken
				887	based on the type of the operand. <p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	888
				889
				890	<h5>Example:</h5>
				891	<pre>
				892	<result> = mul int 4, %var <i>; yields {int}:result = 4 * %var</i>
				893	</pre>
				894
				895
				896	<!-- _______________________________________________________________________ -->
				897	</ul><a name="i_div"><h4><hr size=0>'<tt>div</tt>' Instruction</h4><ul>
				898
				899	<h5>Syntax:</h5>
				900	<pre>
				901	<result> = div <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				902	</pre>
				903
				904	<h5>Overview:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	905
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	906	The '<tt>div</tt>' instruction returns the quotient of its two operands.<p>
				907
				908	<h5>Arguments:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	909
				910	The two arguments to the '<tt>div</tt>' instruction must be either <a
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	911	href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	912	values. Both arguments must have identical types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	913
				914	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	915
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	916	The value produced is the integer or floating point quotient of the two
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	917	operands.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	918
				919	<h5>Example:</h5>
				920	<pre>
				921	<result> = div int 4, %var <i>; yields {int}:result = 4 / %var</i>
				922	</pre>
				923
				924
				925	<!-- _______________________________________________________________________ -->
				926	</ul><a name="i_rem"><h4><hr size=0>'<tt>rem</tt>' Instruction</h4><ul>
				927
				928	<h5>Syntax:</h5>
				929	<pre>
				930	<result> = rem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				931	</pre>
				932
				933	<h5>Overview:</h5>
				934	The '<tt>rem</tt>' instruction returns the remainder from the division of its two operands.<p>
				935
				936	<h5>Arguments:</h5>
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	937	The two arguments to the '<tt>rem</tt>' instruction must be either <a href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	938
				939	<h5>Semantics:</h5>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	940
				941	This returns the <i>remainder</i> of a division (where the result has the same
				942	sign as the divisor), not the <i>modulus</i> (where the result has the same sign
				943	as the dividend) of a value. For more information about the difference, see: <a
				944	href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The Math
				945	Forum</a>.<p>
				946
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	947	<h5>Example:</h5>
				948	<pre>
				949	<result> = rem int 4, %var <i>; yields {int}:result = 4 % %var</i>
				950	</pre>
				951
				952
				953	<!-- _______________________________________________________________________ -->
				954	</ul><a name="i_setcc"><h4><hr size=0>'<tt>set<i>cc</i></tt>' Instructions</h4><ul>
				955
				956	<h5>Syntax:</h5>
				957	<pre>
				958	<result> = seteq <ty> <var1>, <var2> <i>; yields {bool}:result</i>
				959	<result> = setne <ty> <var1>, <var2> <i>; yields {bool}:result</i>
				960	<result> = setlt <ty> <var1>, <var2> <i>; yields {bool}:result</i>
				961	<result> = setgt <ty> <var1>, <var2> <i>; yields {bool}:result</i>
				962	<result> = setle <ty> <var1>, <var2> <i>; yields {bool}:result</i>
				963	<result> = setge <ty> <var1>, <var2> <i>; yields {bool}:result</i>
				964	</pre>
				965
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	966	<h5>Overview:</h5> The '<tt>set<i>cc</i></tt>' family of instructions returns a
				967	boolean value based on a comparison of their two operands.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	968
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	969	<h5>Arguments:</h5> The two arguments to the '<tt>set<i>cc</i></tt>'
				970	instructions must be of <a href="#t_firstclass">first class</a> or <a
				971	href="#t_pointer">pointer</a> type (it is not possible to compare
				972	'<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>' or '<tt>void</tt>'
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	973	values, etc...). Both arguments must have identical types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	974
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	975	The '<tt>setlt</tt>', '<tt>setgt</tt>', '<tt>setle</tt>', and '<tt>setge</tt>'
				976	instructions do not operate on '<tt>bool</tt>' typed arguments.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	977
				978	<h5>Semantics:</h5>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	979
				980	The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
				981	both operands are equal.<br>
				982
				983	The '<tt>setne</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
				984	both operands are unequal.<br>
				985
				986	The '<tt>setlt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
				987	the first operand is less than the second operand.<br>
				988
				989	The '<tt>setgt</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
				990	the first operand is greater than the second operand.<br>
				991
				992	The '<tt>setle</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
				993	the first operand is less than or equal to the second operand.<br>
				994
				995	The '<tt>setge</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
				996	the first operand is greater than or equal to the second operand.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	997
				998	<h5>Example:</h5>
				999	<pre>
				1000	<result> = seteq int 4, 5 <i>; yields {bool}:result = false</i>
				1001	<result> = setne float 4, 5 <i>; yields {bool}:result = true</i>
				1002	<result> = setlt uint 4, 5 <i>; yields {bool}:result = true</i>
				1003	<result> = setgt sbyte 4, 5 <i>; yields {bool}:result = false</i>
				1004	<result> = setle sbyte 4, 5 <i>; yields {bool}:result = true</i>
				1005	<result> = setge sbyte 4, 5 <i>; yields {bool}:result = false</i>
				1006	</pre>
				1007
				1008
				1009
				1010	<!-- ======================================================================= -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	1011	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1012	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1013	<a name="bitwiseops">Bitwise Binary Operations
				1014	</b></font></td></tr></table><ul>
				1015
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	1016	Bitwise binary operators are used to do various forms of bit-twiddling in a
				1017	program. They are generally very efficient instructions, and can commonly be
				1018	strength reduced from other instructions. They require two operands, execute an
				1019	operation on them, and produce a single value. The resulting value of the
				1020	bitwise binary operators is always the same type as its first operand.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1021
				1022	<!-- _______________________________________________________________________ -->
				1023	</ul><a name="i_and"><h4><hr size=0>'<tt>and</tt>' Instruction</h4><ul>
				1024
				1025	<h5>Syntax:</h5>
				1026	<pre>
				1027	<result> = and <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				1028	</pre>
				1029
				1030	<h5>Overview:</h5>
				1031	The '<tt>and</tt>' instruction returns the bitwise logical and of its two operands.<p>
				1032
				1033	<h5>Arguments:</h5>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1034
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	1035	The two arguments to the '<tt>and</tt>' instruction must be <a
				1036	href="#t_integral">integral</a> values. Both arguments must have identical
				1037	types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1038
				1039
				1040	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1041
				1042	The truth table used for the '<tt>and</tt>' instruction is:<p>
				1043
Chris Lattner	c98cbbc	2002-06-25 18:06:50 +0000	[diff] [blame]	1044	<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1045	<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
				1046	<tr><td>0</td> <td>0</td> <td>0</td></tr>
				1047	<tr><td>0</td> <td>1</td> <td>0</td></tr>
				1048	<tr><td>1</td> <td>0</td> <td>0</td></tr>
				1049	<tr><td>1</td> <td>1</td> <td>1</td></tr>
				1050	</table></center><p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1051
				1052
				1053	<h5>Example:</h5>
				1054	<pre>
				1055	<result> = and int 4, %var <i>; yields {int}:result = 4 & %var</i>
				1056	<result> = and int 15, 40 <i>; yields {int}:result = 8</i>
				1057	<result> = and int 4, 8 <i>; yields {int}:result = 0</i>
				1058	</pre>
				1059
				1060
				1061
				1062	<!-- _______________________________________________________________________ -->
				1063	</ul><a name="i_or"><h4><hr size=0>'<tt>or</tt>' Instruction</h4><ul>
				1064
				1065	<h5>Syntax:</h5>
				1066	<pre>
				1067	<result> = or <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				1068	</pre>
				1069
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1070	<h5>Overview:</h5> The '<tt>or</tt>' instruction returns the bitwise logical
				1071	inclusive or of its two operands.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1072
				1073	<h5>Arguments:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1074
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	1075	The two arguments to the '<tt>or</tt>' instruction must be <a
				1076	href="#t_integral">integral</a> values. Both arguments must have identical
				1077	types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1078
				1079
				1080	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1081
				1082	The truth table used for the '<tt>or</tt>' instruction is:<p>
				1083
Chris Lattner	c98cbbc	2002-06-25 18:06:50 +0000	[diff] [blame]	1084	<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1085	<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
				1086	<tr><td>0</td> <td>0</td> <td>0</td></tr>
				1087	<tr><td>0</td> <td>1</td> <td>1</td></tr>
				1088	<tr><td>1</td> <td>0</td> <td>1</td></tr>
				1089	<tr><td>1</td> <td>1</td> <td>1</td></tr>
				1090	</table></center><p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1091
				1092
				1093	<h5>Example:</h5>
				1094	<pre>
				1095	<result> = or int 4, %var <i>; yields {int}:result = 4 \| %var</i>
				1096	<result> = or int 15, 40 <i>; yields {int}:result = 47</i>
				1097	<result> = or int 4, 8 <i>; yields {int}:result = 12</i>
				1098	</pre>
				1099
				1100
				1101	<!-- _______________________________________________________________________ -->
				1102	</ul><a name="i_xor"><h4><hr size=0>'<tt>xor</tt>' Instruction</h4><ul>
				1103
				1104	<h5>Syntax:</h5>
				1105	<pre>
				1106	<result> = xor <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				1107	</pre>
				1108
				1109	<h5>Overview:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1110
				1111	The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of its
				1112	two operands.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1113
				1114	<h5>Arguments:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1115
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	1116	The two arguments to the '<tt>xor</tt>' instruction must be <a
				1117	href="#t_integral">integral</a> values. Both arguments must have identical
				1118	types.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1119
				1120
				1121	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1122
				1123	The truth table used for the '<tt>xor</tt>' instruction is:<p>
				1124
Chris Lattner	c98cbbc	2002-06-25 18:06:50 +0000	[diff] [blame]	1125	<center><table border=1 cellspacing=0 cellpadding=4>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1126	<tr><td>In0</td> <td>In1</td> <td>Out</td></tr>
				1127	<tr><td>0</td> <td>0</td> <td>0</td></tr>
				1128	<tr><td>0</td> <td>1</td> <td>1</td></tr>
				1129	<tr><td>1</td> <td>0</td> <td>1</td></tr>
				1130	<tr><td>1</td> <td>1</td> <td>0</td></tr>
				1131	</table></center><p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1132
				1133
				1134	<h5>Example:</h5>
				1135	<pre>
				1136	<result> = xor int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
				1137	<result> = xor int 15, 40 <i>; yields {int}:result = 39</i>
				1138	<result> = xor int 4, 8 <i>; yields {int}:result = 12</i>
				1139	</pre>
				1140
				1141
				1142	<!-- _______________________________________________________________________ -->
				1143	</ul><a name="i_shl"><h4><hr size=0>'<tt>shl</tt>' Instruction</h4><ul>
				1144
				1145	<h5>Syntax:</h5>
				1146	<pre>
				1147	<result> = shl <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
				1148	</pre>
				1149
				1150	<h5>Overview:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1151
				1152	The '<tt>shl</tt>' instruction returns the first operand shifted to the left a
				1153	specified number of bits.
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1154
				1155	<h5>Arguments:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1156
				1157	The first argument to the '<tt>shl</tt>' instruction must be an <a
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	1158	href="#t_integer">integer</a> type. The second argument must be an
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1159	'<tt>ubyte</tt>' type.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1160
				1161	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1162
				1163	The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1164
				1165
				1166	<h5>Example:</h5>
				1167	<pre>
				1168	<result> = shl int 4, ubyte %var <i>; yields {int}:result = 4 << %var</i>
				1169	<result> = shl int 4, ubyte 2 <i>; yields {int}:result = 16</i>
				1170	<result> = shl int 1, ubyte 10 <i>; yields {int}:result = 1024</i>
				1171	</pre>
				1172
				1173
				1174	<!-- _______________________________________________________________________ -->
				1175	</ul><a name="i_shr"><h4><hr size=0>'<tt>shr</tt>' Instruction</h4><ul>
				1176
				1177
				1178	<h5>Syntax:</h5>
				1179	<pre>
				1180	<result> = shr <ty> <var1>, ubyte <var2> <i>; yields {ty}:result</i>
				1181	</pre>
				1182
				1183	<h5>Overview:</h5>
				1184	The '<tt>shr</tt>' instruction returns the first operand shifted to the right a specified number of bits.
				1185
				1186	<h5>Arguments:</h5>
Chris Lattner	eaee9e1	2002-09-03 00:52:52 +0000	[diff] [blame]	1187	The first argument to the '<tt>shr</tt>' instruction must be an <a href="#t_integer">integer</a> type. The second argument must be an '<tt>ubyte</tt>' type.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1188
				1189	<h5>Semantics:</h5>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1190
				1191	If the first argument is a <a href="#t_signed">signed</a> type, the most
				1192	significant bit is duplicated in the newly free'd bit positions. If the first
				1193	argument is unsigned, zero bits shall fill the empty positions.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1194
				1195	<h5>Example:</h5>
				1196	<pre>
				1197	<result> = shr int 4, ubyte %var <i>; yields {int}:result = 4 >> %var</i>
Chris Lattner	8c6bb90	2003-06-18 21:30:51 +0000	[diff] [blame]	1198	<result> = shr uint 4, ubyte 1 <i>; yields {uint}:result = 2</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1199	<result> = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
Chris Lattner	8c6bb90	2003-06-18 21:30:51 +0000	[diff] [blame]	1200	<result> = shr sbyte 4, ubyte 3 <i>; yields {sbyte}:result = 0</i>
				1201	<result> = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1202	</pre>
				1203
				1204
				1205
				1206
				1207
				1208	<!-- ======================================================================= -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	1209	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1210	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1211	<a name="memoryops">Memory Access Operations
				1212	</b></font></td></tr></table><ul>
				1213
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1214	Accessing memory in SSA form is, well, sticky at best. This section describes how to read, write, allocate and free memory in LLVM.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1215
				1216
				1217	<!-- _______________________________________________________________________ -->
				1218	</ul><a name="i_malloc"><h4><hr size=0>'<tt>malloc</tt>' Instruction</h4><ul>
				1219
				1220	<h5>Syntax:</h5>
				1221	<pre>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1222	<result> = malloc <type>, uint <NumElements> <i>; yields {type*}:result</i>
				1223	<result> = malloc <type> <i>; yields {type*}:result</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1224	</pre>
				1225
				1226	<h5>Overview:</h5>
				1227	The '<tt>malloc</tt>' instruction allocates memory from the system heap and returns a pointer to it.<p>
				1228
				1229	<h5>Arguments:</h5>
				1230
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1231	The the '<tt>malloc</tt>' instruction allocates
				1232	<tt>sizeof(<type>)*NumElements</tt> bytes of memory from the operating
				1233	system, and returns a pointer of the appropriate type to the program. The
				1234	second form of the instruction is a shorter version of the first instruction
				1235	that defaults to allocating one element.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1236
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1237	'<tt>type</tt>' must be a sized type<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1238
				1239	<h5>Semantics:</h5>
				1240	Memory is allocated, a pointer is returned.<p>
				1241
				1242	<h5>Example:</h5>
				1243	<pre>
				1244	%array = malloc [4 x ubyte ] <i>; yields {[%4 x ubyte]*}:array</i>
				1245
				1246	%size = <a href="#i_add">add</a> uint 2, 2 <i>; yields {uint}:size = uint 4</i>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1247	%array1 = malloc ubyte, uint 4 <i>; yields {ubyte*}:array1</i>
				1248	%array2 = malloc [12 x ubyte], uint %size <i>; yields {[12 x ubyte]*}:array2</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1249	</pre>
				1250
				1251
				1252	<!-- _______________________________________________________________________ -->
				1253	</ul><a name="i_free"><h4><hr size=0>'<tt>free</tt>' Instruction</h4><ul>
				1254
				1255	<h5>Syntax:</h5>
				1256	<pre>
				1257	free <type> <value> <i>; yields {void}</i>
				1258	</pre>
				1259
				1260
				1261	<h5>Overview:</h5>
				1262	The '<tt>free</tt>' instruction returns memory back to the unused memory heap, to be reallocated in the future.<p>
				1263
				1264
				1265	<h5>Arguments:</h5>
				1266
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1267	'<tt>value</tt>' shall be a pointer value that points to a value that was
				1268	allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1269
				1270
				1271	<h5>Semantics:</h5>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1272
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1273	Access to the memory pointed to by the pointer is not longer defined after this instruction executes.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1274
				1275	<h5>Example:</h5>
				1276	<pre>
				1277	%array = <a href="#i_malloc">malloc</a> [4 x ubyte] <i>; yields {[4 x ubyte]*}:array</i>
				1278	free [4 x ubyte]* %array
				1279	</pre>
				1280
				1281
				1282	<!-- _______________________________________________________________________ -->
				1283	</ul><a name="i_alloca"><h4><hr size=0>'<tt>alloca</tt>' Instruction</h4><ul>
				1284
				1285	<h5>Syntax:</h5>
				1286	<pre>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1287	<result> = alloca <type>, uint <NumElements> <i>; yields {type*}:result</i>
				1288	<result> = alloca <type> <i>; yields {type*}:result</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1289	</pre>
				1290
				1291	<h5>Overview:</h5>
				1292
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1293	The '<tt>alloca</tt>' instruction allocates memory on the current stack frame of
				1294	the procedure that is live until the current function returns to its caller.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1295
				1296	<h5>Arguments:</h5>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1297
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1298	The the '<tt>alloca</tt>' instruction allocates
				1299	<tt>sizeof(<type>)*NumElements</tt> bytes of memory on the runtime stack,
				1300	returning a pointer of the appropriate type to the program. The second form of
				1301	the instruction is a shorter version of the first that defaults to allocating
				1302	one element.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1303
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1304	'<tt>type</tt>' may be any sized type.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1305
				1306	<h5>Semantics:</h5>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1307
				1308	Memory is allocated, a pointer is returned. '<tt>alloca</tt>'d memory is
				1309	automatically released when the function returns. The '<tt>alloca</tt>'
				1310	instruction is commonly used to represent automatic variables that must have an
				1311	address available, as well as spilled variables.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1312
				1313	<h5>Example:</h5>
				1314	<pre>
				1315	%ptr = alloca int <i>; yields {int*}:ptr</i>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1316	%ptr = alloca int, uint 4 <i>; yields {int*}:ptr</i>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1317	</pre>
				1318
				1319
				1320	<!-- _______________________________________________________________________ -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	1321	</ul><a name="i_load"><h4><hr size=0>'<tt>load</tt>' Instruction</h4><ul>
				1322
				1323	<h5>Syntax:</h5>
				1324	<pre>
				1325	<result> = load <ty>* <pointer>
				1326	</pre>
				1327
				1328	<h5>Overview:</h5>
				1329	The '<tt>load</tt>' instruction is used to read from memory.<p>
				1330
				1331	<h5>Arguments:</h5>
				1332
				1333	The argument to the '<tt>load</tt>' instruction specifies the memory address to load from. The pointer must point to a <a href="t_firstclass">first class</a> type.<p>
				1334
				1335	<h5>Semantics:</h5>
				1336
				1337	The location of memory pointed to is loaded.
				1338
				1339	<h5>Examples:</h5>
				1340	<pre>
				1341	%ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
				1342	<a href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
				1343	%val = load int* %ptr <i>; yields {int}:val = int 3</i>
				1344	</pre>
				1345
				1346
				1347
				1348
				1349	<!-- _______________________________________________________________________ -->
				1350	</ul><a name="i_store"><h4><hr size=0>'<tt>store</tt>' Instruction</h4><ul>
				1351
				1352	<h5>Syntax:</h5>
				1353	<pre>
				1354	store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
				1355	</pre>
				1356
				1357	<h5>Overview:</h5>
				1358	The '<tt>store</tt>' instruction is used to write to memory.<p>
				1359
				1360	<h5>Arguments:</h5>
				1361
				1362	There are two arguments to the '<tt>store</tt>' instruction: a value to store
				1363	and an address to store it into. The type of the '<tt><pointer></tt>'
				1364	operand must be a pointer to the type of the '<tt><value></tt>'
				1365	operand.<p>
				1366
				1367	<h5>Semantics:</h5> The contents of memory are updated to contain
				1368	'<tt><value></tt>' at the location specified by the
				1369	'<tt><pointer></tt>' operand.<p>
				1370
				1371	<h5>Example:</h5>
				1372	<pre>
				1373	%ptr = <a href="#i_alloca">alloca</a> int <i>; yields {int*}:ptr</i>
				1374	<a href="#i_store">store</a> int 3, int* %ptr <i>; yields {void}</i>
				1375	%val = load int* %ptr <i>; yields {int}:val = int 3</i>
				1376	</pre>
				1377
				1378
				1379
				1380
				1381	<!-- _______________________________________________________________________ -->
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1382	</ul><a name="i_getelementptr"><h4><hr size=0>'<tt>getelementptr</tt>' Instruction</h4><ul>
				1383
				1384	<h5>Syntax:</h5>
				1385	<pre>
Chris Lattner	3dfa10b	2002-12-13 06:01:21 +0000	[diff] [blame]	1386	<result> = getelementptr <ty>* <ptrval>{, long <aidx>\|, ubyte <sidx>}*
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1387	</pre>
				1388
				1389	<h5>Overview:</h5>
				1390
				1391	The '<tt>getelementptr</tt>' instruction is used to get the address of a
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1392	subelement of an aggregate data structure.<p>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1393
				1394	<h5>Arguments:</h5>
				1395
Chris Lattner	3dfa10b	2002-12-13 06:01:21 +0000	[diff] [blame]	1396	This instruction takes a list of <tt>long</tt> values and <tt>ubyte</tt>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1397	constants that indicate what form of addressing to perform. The actual types of
				1398	the arguments provided depend on the type of the first pointer argument. The
				1399	'<tt>getelementptr</tt>' instruction is used to index down through the type
				1400	levels of a structure.<p>
				1401
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1402	For example, lets consider a C code fragment and how it gets compiled to
				1403	LLVM:<p>
				1404
				1405	<pre>
				1406	struct RT {
				1407	char A;
				1408	int B[10][20];
				1409	char C;
				1410	};
				1411	struct ST {
				1412	int X;
				1413	double Y;
				1414	struct RT Z;
				1415	};
				1416
				1417	int foo(struct ST s) {
				1418	return &s[1].Z.B[5][13];
				1419	}
				1420	</pre>
				1421
				1422	The LLVM code generated by the GCC frontend is:
				1423
				1424	<pre>
				1425	%RT = type { sbyte, [10 x [20 x int]], sbyte }
				1426	%ST = type { int, double, %RT }
				1427
				1428	int* "foo"(%ST* %s) {
Chris Lattner	3dfa10b	2002-12-13 06:01:21 +0000	[diff] [blame]	1429	%reg = getelementptr %ST* %s, long 1, ubyte 2, ubyte 1, long 5, long 13
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1430	ret int* %reg
				1431	}
				1432	</pre>
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1433
				1434	<h5>Semantics:</h5>
				1435
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1436	The index types specified for the '<tt>getelementptr</tt>' instruction depend on
				1437	the pointer type that is being index into. <a href="t_pointer">Pointer</a> and
Chris Lattner	3dfa10b	2002-12-13 06:01:21 +0000	[diff] [blame]	1438	<a href="t_array">array</a> types require '<tt>long</tt>' values, and <a
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1439	href="t_struct">structure</a> types require '<tt>ubyte</tt>'
				1440	<b>constants</b>.<p>
				1441
				1442	In the example above, the first index is indexing into the '<tt>%ST*</tt>' type,
				1443	which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ int, double, %RT }</tt>'
				1444	type, a structure. The second index indexes into the third element of the
				1445	structure, yielding a '<tt>%RT</tt>' = '<tt>{ sbyte, [10 x [20 x int]], sbyte
				1446	}</tt>' type, another structure. The third index indexes into the second
				1447	element of the structure, yielding a '<tt>[10 x [20 x int]]</tt>' type, an
				1448	array. The two dimensions of the array are subscripted into, yielding an
				1449	'<tt>int</tt>' type. The '<tt>getelementptr</tt>' instruction return a pointer
				1450	to this element, thus yielding a '<tt>int*</tt>' type.<p>
				1451
				1452	Note that it is perfectly legal to index partially through a structure,
				1453	returning a pointer to an inner element. Because of this, the LLVM code for the
				1454	given testcase is equivalent to:<p>
				1455
				1456	<pre>
				1457	int* "foo"(%ST* %s) {
Chris Lattner	3dfa10b	2002-12-13 06:01:21 +0000	[diff] [blame]	1458	%t1 = getelementptr %ST* %s , long 1 <i>; yields %ST*:%t1</i>
				1459	%t2 = getelementptr %ST* %t1, long 0, ubyte 2 <i>; yields %RT*:%t2</i>
				1460	%t3 = getelementptr %RT* %t2, long 0, ubyte 1 <i>; yields [10 x [20 x int]]*:%t3</i>
				1461	%t4 = getelementptr [10 x [20 x int]]* %t3, long 0, long 5 <i>; yields [20 x int]*:%t4</i>
				1462	%t5 = getelementptr [20 x int]* %t4, long 0, long 13 <i>; yields int*:%t5</i>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1463	ret int* %t5
				1464	}
				1465	</pre>
				1466
				1467
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1468
				1469	<h5>Example:</h5>
				1470	<pre>
Chris Lattner	f31860b	2002-08-19 21:14:38 +0000	[diff] [blame]	1471	<i>; yields [12 x ubyte]*:aptr</i>
Chris Lattner	3dfa10b	2002-12-13 06:01:21 +0000	[diff] [blame]	1472	%aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
Chris Lattner	7faa883	2002-04-14 06:13:44 +0000	[diff] [blame]	1473	</pre>
				1474
				1475
				1476
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1477	<!-- ======================================================================= -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	1478	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1479	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1480	<a name="otherops">Other Operations
				1481	</b></font></td></tr></table><ul>
				1482
				1483	The instructions in this catagory are the "miscellaneous" functions, that defy better classification.<p>
				1484
				1485
				1486	<!-- _______________________________________________________________________ -->
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1487	</ul><a name="i_phi"><h4><hr size=0>'<tt>phi</tt>' Instruction</h4><ul>
Chris Lattner	33ba0d9	2001-07-09 00:26:23 +0000	[diff] [blame]	1488
				1489	<h5>Syntax:</h5>
				1490	<pre>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1491	<result> = phi <ty> [ <val0>, <label0>], ...
Chris Lattner	33ba0d9	2001-07-09 00:26:23 +0000	[diff] [blame]	1492	</pre>
				1493
				1494	<h5>Overview:</h5>
				1495
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1496	The '<tt>phi</tt>' instruction is used to implement the φ node in the SSA
				1497	graph representing the function.<p>
Chris Lattner	33ba0d9	2001-07-09 00:26:23 +0000	[diff] [blame]	1498
				1499	<h5>Arguments:</h5>
				1500
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1501	The type of the incoming values are specified with the first type field. After
				1502	this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with
				1503	one pair for each predecessor basic block of the current block.<p>
				1504
				1505	There must be no non-phi instructions between the start of a basic block and the
				1506	PHI instructions: i.e. PHI instructions must be first in a basic block.<p>
Chris Lattner	33ba0d9	2001-07-09 00:26:23 +0000	[diff] [blame]	1507
				1508	<h5>Semantics:</h5>
				1509
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1510	At runtime, the '<tt>phi</tt>' instruction logically takes on the value
				1511	specified by the parameter, depending on which basic block we came from in the
				1512	last <a href="#terminators">terminator</a> instruction.<p>
				1513
				1514	<h5>Example:</h5>
				1515
				1516	<pre>
				1517	Loop: ; Infinite loop that counts from 0 on up...
				1518	%indvar = phi uint [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
				1519	%nextindvar = add uint %indvar, 1
				1520	br label %Loop
				1521	</pre>
				1522
				1523
				1524	<!-- _______________________________________________________________________ -->
				1525	</ul><a name="i_cast"><h4><hr size=0>'<tt>cast .. to</tt>' Instruction</h4><ul>
				1526
				1527	<h5>Syntax:</h5>
				1528	<pre>
				1529	<result> = cast <ty> <value> to <ty2> <i>; yields ty2</i>
				1530	</pre>
				1531
				1532	<h5>Overview:</h5>
				1533
				1534	The '<tt>cast</tt>' instruction is used as the primitive means to convert
				1535	integers to floating point, change data type sizes, and break type safety (by
				1536	casting pointers).<p>
				1537
				1538	<h5>Arguments:</h5>
				1539
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1540	The '<tt>cast</tt>' instruction takes a value to cast, which must be a first
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1541	class value, and a type to cast it to, which must also be a first class type.<p>
				1542
				1543	<h5>Semantics:</h5>
				1544
				1545	This instruction follows the C rules for explicit casts when determining how the
				1546	data being cast must change to fit in its new container.<p>
				1547
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1548	When casting to bool, any value that would be considered true in the context of
				1549	a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
				1550	all else are '<tt>false</tt>'.<p>
Chris Lattner	33ba0d9	2001-07-09 00:26:23 +0000	[diff] [blame]	1551
Chris Lattner	f8856bc	2002-08-13 20:52:09 +0000	[diff] [blame]	1552	When extending an integral value from a type of one signness to another (for
				1553	example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
				1554	<b>source</b> value is signed, and zero-extended if the source value is
Chris Lattner	2b4dcbb	2002-08-15 19:36:05 +0000	[diff] [blame]	1555	unsigned. <tt>bool</tt> values are always zero extended into either zero or
				1556	one.<p>
Chris Lattner	f8856bc	2002-08-13 20:52:09 +0000	[diff] [blame]	1557
Chris Lattner	33ba0d9	2001-07-09 00:26:23 +0000	[diff] [blame]	1558	<h5>Example:</h5>
				1559	<pre>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1560	%X = cast int 257 to ubyte <i>; yields ubyte:1</i>
Chris Lattner	7bae395	2002-06-25 18:03:17 +0000	[diff] [blame]	1561	%Y = cast int 123 to bool <i>; yields bool:true</i>
Chris Lattner	33ba0d9	2001-07-09 00:26:23 +0000	[diff] [blame]	1562	</pre>
				1563
				1564
				1565
				1566	<!-- _______________________________________________________________________ -->
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1567	</ul><a name="i_call"><h4><hr size=0>'<tt>call</tt>' Instruction</h4><ul>
				1568
				1569	<h5>Syntax:</h5>
				1570	<pre>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1571	<result> = call <ty>* <fnptrval>(<param list>)
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1572	</pre>
				1573
				1574	<h5>Overview:</h5>
				1575
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1576	The '<tt>call</tt>' instruction represents a simple function call.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1577
				1578	<h5>Arguments:</h5>
				1579
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1580	This instruction requires several arguments:<p>
				1581	<ol>
				1582
				1583	<li>'<tt>ty</tt>': shall be the signature of the pointer to function value being
				1584	invoked. The argument types must match the types implied by this signature.<p>
				1585
				1586	<li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to be
				1587	invoked. In most cases, this is a direct function invocation, but indirect
Misha Brukman	e6fe671	2002-09-18 02:35:14 +0000	[diff] [blame]	1588	<tt>call</tt>s are just as possible, calling an arbitrary pointer to function
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1589	values.<p>
				1590
				1591	<li>'<tt>function args</tt>': argument list whose types match the function
				1592	signature argument types. If the function signature indicates the function
				1593	accepts a variable number of arguments, the extra arguments can be specified.
				1594	</ol>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1595
				1596	<h5>Semantics:</h5>
				1597
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1598	The '<tt>call</tt>' instruction is used to cause control flow to transfer to a
				1599	specified function, with its incoming arguments bound to the specified values.
				1600	Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called function,
				1601	control flow continues with the instruction after the function call, and the
				1602	return value of the function is bound to the result argument. This is a simpler
				1603	case of the <a href="#i_invoke">invoke</a> instruction.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1604
				1605	<h5>Example:</h5>
				1606	<pre>
				1607	%retval = call int %test(int %argc)
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1608	call int(sbyte, ...) %printf(sbyte* %msg, int 12, sbyte 42);
				1609
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1610	</pre>
				1611
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1612	<!-- _______________________________________________________________________ -->
				1613	</ul><a name="i_va_arg"><h4><hr size=0>'<tt>va_arg</tt>' Instruction</h4><ul>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1614
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1615	<h5>Syntax:</h5>
				1616	<pre>
				1617	<result> = va_arg <va_list>* <arglist>, <retty>
				1618	</pre>
				1619
				1620	<h5>Overview:</h5>
				1621
				1622	The '<tt>va_arg</tt>' instruction is used to access arguments passed through the
				1623	"variable argument" area of a function call. It corresponds directly to the
				1624	<tt>va_arg</tt> macro in C.<p>
				1625
				1626	<h5>Arguments:</h5>
				1627
				1628	This instruction takes a pointer to a <tt>valist</tt> value to read a new
				1629	argument from. The return type of the instruction is defined by the second
				1630	argument, a type.<p>
				1631
				1632	<h5>Semantics:</h5>
				1633
				1634	The '<tt>va_arg</tt>' instruction works just like the <tt>va_arg</tt> macro
				1635	available in C. In a target-dependent way, it reads the argument indicated by
				1636	the value the arglist points to, updates the arglist, then returns a value of
				1637	the specified type. This instruction should be used in conjunction with the
				1638	variable argument handling <a href="#int_varargs">Intrinsic Functions</a>.<p>
				1639
				1640	It is legal for this instruction to be called in a function which does not take
				1641	a variable number of arguments, for example, the <tt>vfprintf</tt> function.<p>
				1642
				1643	<tt>va_arg</tt> is an LLVM instruction instead of an <a
				1644	href="#intrinsics">intrinsic function</a> because the return type depends on an
				1645	argument.<p>
				1646
				1647	<h5>Example:</h5>
				1648
				1649	See the <a href="#int_varargs">variable argument processing</a> section.<p>
				1650
				1651	<!-- *********************************************************************** -->
Chris Lattner	2b7d320	2002-05-06 03:03:22 +0000	[diff] [blame]	1652	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				1653	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1654	<a name="intrinsics">Intrinsic Functions
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1655	</b></font></td></tr></table><ul>
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1656	<!-- *********************************************************************** -->
				1657
				1658	LLVM supports the notion of an "intrinsic function". These functions have well
				1659	known names and semantics, and are required to follow certain restrictions.
				1660	Overall, these instructions represent an extension mechanism for the LLVM
				1661	language that does not require changing all of the transformations in LLVM to
				1662	add to the language (or the bytecode reader/writer, the parser, etc...).<p>
				1663
				1664	Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
				1665	prefix is reserved in LLVM for intrinsic names, thus functions may not be named
				1666	this. Intrinsic functions must always be external functions: you cannot define
				1667	the body of intrinsic functions. Intrinsic functions may only be used in call
				1668	or invoke instructions: it is illegal to take the address of an intrinsic
				1669	function. Additionally, because intrinsic functions are part of the LLVM
				1670	language, it is required that they all be documented here if any are added.<p>
				1671
				1672	Unless an intrinsic function is target-specific, there must be a lowering pass
				1673	to eliminate the intrinsic or all backends must support the intrinsic
				1674	function.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1675
				1676
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1677	<!-- ======================================================================= -->
				1678	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1679	<tr><td> </td><td width="100%">  <font color="#EEEEFF" face="Georgia,Palatino"><b>
				1680	<a name="int_varargs">Variable Argument Handling Intrinsics
				1681	</b></font></td></tr></table><ul>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1682
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1683	Variable argument support is defined in LLVM with the <a
				1684	href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three intrinsic
				1685	functions. These function correspond almost directly to the similarly named
				1686	macros defined in the <tt><stdarg.h></tt> header file.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1687
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1688	All of these functions operate on arguments that use a target-specific type
				1689	"<tt>va_list</tt>". The LLVM assembly language reference manual does not define
				1690	what this type is, so all transformations should be prepared to handle
				1691	intrinsics with any type used.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1692
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1693	This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction
				1694	and the variable argument handling intrinsic functions are used.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1695
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1696	<pre>
				1697	int %test(int %X, ...) {
				1698	; Allocate two va_list items. On this target, va_list is of type sbyte*
				1699	%ap = alloca sbyte*
				1700	%aq = alloca sbyte*
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1701
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1702	; Initialize variable argument processing
Chris Lattner	a1a2097	2003-05-08 15:55:44 +0000	[diff] [blame]	1703	call void (sbyte*) %<a href="#i_va_start">llvm.va_start</a>(sbyte** %ap)
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1704
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1705	; Read a single integer argument
				1706	%tmp = <a href="#i_va_arg">va_arg</a> sbyte** %ap, int
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1707
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1708	; Demonstrate usage of llvm.va_copy and llvm_va_end
				1709	%apv = load sbyte** %ap
				1710	call void %<a href="#i_va_copy">llvm.va_copy</a>(sbyte** %aq, sbyte* %apv)
				1711	call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %aq)
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1712
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1713	; Stop processing of arguments.
				1714	call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %ap)
				1715	ret int %tmp
				1716	}
				1717	</pre>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1718
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1719	<!-- _______________________________________________________________________ -->
				1720	</ul><a name="i_va_start"><h4><hr size=0>'<tt>llvm.va_start</tt>' Intrinsic</h4><ul>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1721
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1722	<h5>Syntax:</h5>
				1723	<pre>
Chris Lattner	a1a2097	2003-05-08 15:55:44 +0000	[diff] [blame]	1724	call void (va_list) %llvm.va_start(<va_list>* <arglist>)
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1725	</pre>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1726
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1727	<h5>Overview:</h5>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1728
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1729	The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*<arglist></tt> for
				1730	subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt> and <tt><a
				1731	href="#i_va_end">llvm.va_end</a></tt>, and must be called before either are
				1732	invoked.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1733
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1734	<h5>Arguments:</h5>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1735
Chris Lattner	a1a2097	2003-05-08 15:55:44 +0000	[diff] [blame]	1736	The argument is a pointer to a <tt>va_list</tt> element to initialize.<p>
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1737
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1738	<h5>Semantics:</h5>
				1739
				1740	The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
				1741	macro available in C. In a target-dependent way, it initializes the
Chris Lattner	a1a2097	2003-05-08 15:55:44 +0000	[diff] [blame]	1742	<tt>va_list</tt> element the argument points to, so that the next call to
				1743	<tt>va_arg</tt> will produce the first variable argument passed to the function.
				1744	Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
				1745	last argument of the function, the compiler can figure that out.<p>
Chris Lattner	d9ad5b3	2003-05-08 04:57:36 +0000	[diff] [blame]	1746
				1747
				1748	<!-- _______________________________________________________________________ -->
				1749	</ul><a name="i_va_end"><h4><hr size=0>'<tt>llvm.va_end</tt>' Intrinsic</h4><ul>
				1750
				1751	<h5>Syntax:</h5>
				1752	<pre>
				1753	call void (va_list) %llvm.va_end(<va_list>* <arglist>)
				1754	</pre>
				1755
				1756	<h5>Overview:</h5>
				1757
				1758	The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*<arglist></tt> which
				1759	has been initialized previously with <tt><a
				1760	href="#i_va_begin">llvm.va_begin</a></tt>.<p>
				1761
				1762	<h5>Arguments:</h5>
				1763
				1764	The argument is a pointer to a <tt>va_list</tt> element to destroy.<p>
				1765
				1766	<h5>Semantics:</h5>
				1767
				1768	The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt> macro
				1769	available in C. In a target-dependent way, it destroys the <tt>va_list</tt>
				1770	that the argument points to. Calls to <a
				1771	href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
				1772	href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly with calls
				1773	to <tt>llvm.va_end</tt>.<p>
				1774
				1775
				1776
				1777	<!-- _______________________________________________________________________ -->
				1778	</ul><a name="i_va_copy"><h4><hr size=0>'<tt>llvm.va_copy</tt>' Intrinsic</h4><ul>
				1779
				1780	<h5>Syntax:</h5>
				1781	<pre>
				1782	call void (va_list, va_list) %va_copy(<va_list>* <destarglist>,
				1783	<va_list> <srcarglist>)
				1784	</pre>
				1785
				1786	<h5>Overview:</h5>
				1787
				1788	The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
				1789	the source argument list to the destination argument list.<p>
				1790
				1791	<h5>Arguments:</h5>
				1792
				1793	The first argument is a pointer to a <tt>va_list</tt> element to initialize.
				1794	The second argument is a <tt>va_list</tt> element to copy from.<p>
				1795
				1796
				1797	<h5>Semantics:</h5>
				1798
				1799	The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
				1800	available in C. In a target-dependent way, it copies the source
				1801	<tt>va_list</tt> element into the destination list. This intrinsic is necessary
				1802	because the <tt><a href="i_va_begin">llvm.va_begin</a></tt> intrinsic may be
				1803	arbitrarily complex and require memory allocation, for example.<p>
Chris Lattner	6536cfe	2002-05-06 22:08:29 +0000	[diff] [blame]	1804
				1805
Chris Lattner	b3ceec2	2003-08-28 22:12:25 +0000	[diff] [blame]	1806	<!-- _______________________________________________________________________ -->
				1807	</ul><a name="i_unwind"><h4><hr size=0>'<tt>llvm.unwind</tt>' Intrinsic</h4><ul>
				1808
				1809	<h5>Syntax:</h5>
				1810	<pre>
				1811	call void (void)* %llvm.unwind()
				1812	</pre>
				1813
				1814	<h5>Overview:</h5>
				1815
				1816	The '<tt>llvm.unwind</tt>' intrinsic unwinds the stack, continuing control flow
				1817	at the first callee in the dynamic call stack which used an <a
				1818	href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is
				1819	primarily used to implement exception handling.
				1820
				1821	<h5>Semantics:</h5>
				1822
				1823	The '<tt>llvm.unwind</tt>' intrinsic causes execution of the current function to
				1824	immediately halt. The dynamic call stack is then searched for the first <a
				1825	href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found,
				1826	execution continues at the "exceptional" destination block specified by the
				1827	invoke instruction. If there is no <tt>invoke</tt> instruction in the dynamic
				1828	call chain, undefined behavior results.
				1829
				1830
				1831
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1832	<!-- *********************************************************************** -->
				1833	</ul>
				1834	<!-- *********************************************************************** -->
				1835
				1836
				1837	<hr>
				1838	<font size=-1>
				1839	<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
				1840	<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
				1841	<!-- hhmts start -->
Chris Lattner	fde246a	2003-09-02 23:38:41 +0000	[diff] [blame^]	1842	Last modified: Tue Sep 2 18:38:09 CDT 2003
Chris Lattner	0095054	2001-06-06 20:29:01 +0000	[diff] [blame]	1843	<!-- hhmts end -->
				1844	</font>
				1845	</body></html>