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

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