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

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