Blame - llvm/docs/LangRef.html - toolchain/llvm-project

blob: b6f6f47256c3d5fd9ac08c3dadf60f487f3820f8 [file] [log] [blame]

Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
				2	"http://www.w3.org/TR/html4/strict.dtd">
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3	<html>
				4	<head>
				5	<title>LLVM Assembly Language Reference Manual</title>
Reid Spencer	cb84e43	2004-08-26 20:44:00 +0000	[diff] [blame]	6	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
				7	<meta name="author" content="Chris Lattner">
				8	<meta name="description"
				9	content="LLVM Assembly Language Reference Manual.">
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	10	<link rel="stylesheet" href="llvm.css" type="text/css">
				11	</head>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	12
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	13	<body>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	14
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	15	<div class="doc_title"> LLVM Language Reference Manual </div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	16	<ol>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	17	<li><a href="#abstract">Abstract</a></li>
				18	<li><a href="#introduction">Introduction</a></li>
				19	<li><a href="#identifiers">Identifiers</a></li>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	20	<li><a href="#highlevel">High Level Structure</a>
				21	<ol>
				22	<li><a href="#modulestructure">Module Structure</a></li>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	23	<li><a href="#linkage">Linkage Types</a></li>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	24	<li><a href="#callingconv">Calling Conventions</a></li>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	25	<li><a href="#globalvars">Global Variables</a></li>
Chris Lattner	91c15c4	2006-01-23 23:23:47 +0000	[diff] [blame]	26	<li><a href="#functionstructure">Functions</a></li>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	27	<li><a href="#paramattrs">Parameter Attributes</a></li>
Chris Lattner	91c15c4	2006-01-23 23:23:47 +0000	[diff] [blame]	28	<li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
Reid Spencer	50c723a	2007-02-19 23:54:10 +0000	[diff] [blame^]	29	<li><a href="#datalayout">Data Layout</a></li>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	30	</ol>
				31	</li>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	32	<li><a href="#typesystem">Type System</a>
				33	<ol>
Robert Bocchino	820bc75b	2006-02-17 21:18:08 +0000	[diff] [blame]	34	<li><a href="#t_primitive">Primitive Types</a>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	35	<ol>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	36	<li><a href="#t_classifications">Type Classifications</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	37	</ol>
				38	</li>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	39	<li><a href="#t_derived">Derived Types</a>
				40	<ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	41	<li><a href="#t_array">Array Type</a></li>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	42	<li><a href="#t_function">Function Type</a></li>
				43	<li><a href="#t_pointer">Pointer Type</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	44	<li><a href="#t_struct">Structure Type</a></li>
Andrew Lenharth	8df88e2	2006-12-08 17:13:00 +0000	[diff] [blame]	45	<li><a href="#t_pstruct">Packed Structure Type</a></li>
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	46	<li><a href="#t_vector">Vector Type</a></li>
Chris Lattner	37b6b09	2005-04-25 17:34:15 +0000	[diff] [blame]	47	<li><a href="#t_opaque">Opaque Type</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	48	</ol>
				49	</li>
				50	</ol>
				51	</li>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	52	<li><a href="#constants">Constants</a>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	53	<ol>
				54	<li><a href="#simpleconstants">Simple Constants</a>
				55	<li><a href="#aggregateconstants">Aggregate Constants</a>
				56	<li><a href="#globalconstants">Global Variable and Function Addresses</a>
				57	<li><a href="#undefvalues">Undefined Values</a>
				58	<li><a href="#constantexprs">Constant Expressions</a>
				59	</ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	60	</li>
Chris Lattner	98f013c	2006-01-25 23:47:57 +0000	[diff] [blame]	61	<li><a href="#othervalues">Other Values</a>
				62	<ol>
				63	<li><a href="#inlineasm">Inline Assembler Expressions</a>
				64	</ol>
				65	</li>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	66	<li><a href="#instref">Instruction Reference</a>
				67	<ol>
				68	<li><a href="#terminators">Terminator Instructions</a>
				69	<ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	70	<li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
				71	<li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	72	<li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
				73	<li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	74	<li><a href="#i_unwind">'<tt>unwind</tt>' Instruction</a></li>
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	75	<li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	76	</ol>
				77	</li>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	78	<li><a href="#binaryops">Binary Operations</a>
				79	<ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	80	<li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
				81	<li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
				82	<li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	83	<li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li>
				84	<li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li>
				85	<li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li>
Reid Spencer	7eb55b3	2006-11-02 01:53:59 +0000	[diff] [blame]	86	<li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li>
				87	<li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li>
				88	<li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	89	</ol>
				90	</li>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	91	<li><a href="#bitwiseops">Bitwise Binary Operations</a>
				92	<ol>
Reid Spencer	2ab0193	2007-02-02 13:57:07 +0000	[diff] [blame]	93	<li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
				94	<li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li>
				95	<li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	96	<li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	97	<li><a href="#i_or">'<tt>or</tt>' Instruction</a></li>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	98	<li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	99	</ol>
				100	</li>
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	101	<li><a href="#vectorops">Vector Operations</a>
				102	<ol>
				103	<li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
				104	<li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
				105	<li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	106	</ol>
				107	</li>
Chris Lattner	6ab6672	2006-08-15 00:45:58 +0000	[diff] [blame]	108	<li><a href="#memoryops">Memory Access and Addressing Operations</a>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	109	<ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	110	<li><a href="#i_malloc">'<tt>malloc</tt>' Instruction</a></li>
				111	<li><a href="#i_free">'<tt>free</tt>' Instruction</a></li>
				112	<li><a href="#i_alloca">'<tt>alloca</tt>' Instruction</a></li>
Robert Bocchino	820bc75b	2006-02-17 21:18:08 +0000	[diff] [blame]	113	<li><a href="#i_load">'<tt>load</tt>' Instruction</a></li>
				114	<li><a href="#i_store">'<tt>store</tt>' Instruction</a></li>
				115	<li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	116	</ol>
				117	</li>
Reid Spencer	97c5fa4	2006-11-08 01:18:52 +0000	[diff] [blame]	118	<li><a href="#convertops">Conversion Operations</a>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	119	<ol>
				120	<li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
				121	<li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
				122	<li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
				123	<li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
				124	<li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	125	<li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li>
				126	<li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li>
				127	<li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li>
				128	<li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li>
Reid Spencer	b7344ff	2006-11-11 21:00:47 +0000	[diff] [blame]	129	<li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li>
				130	<li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li>
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	131	<li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	132	</ol>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	133	<li><a href="#otherops">Other Operations</a>
				134	<ol>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	135	<li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li>
				136	<li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	137	<li><a href="#i_phi">'<tt>phi</tt>' Instruction</a></li>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	138	<li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	139	<li><a href="#i_call">'<tt>call</tt>' Instruction</a></li>
Chris Lattner	3333747	2006-01-13 23:26:01 +0000	[diff] [blame]	140	<li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a></li>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	141	</ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	142	</li>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	143	</ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	144	</li>
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	145	<li><a href="#intrinsics">Intrinsic Functions</a>
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	146	<ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	147	<li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
				148	<ol>
				149	<li><a href="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
				150	<li><a href="#i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a></li>
				151	<li><a href="#i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a></li>
				152	</ol>
				153	</li>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	154	<li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
				155	<ol>
				156	<li><a href="#i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
				157	<li><a href="#i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
				158	<li><a href="#i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
				159	</ol>
				160	</li>
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	161	<li><a href="#int_codegen">Code Generator Intrinsics</a>
				162	<ol>
				163	<li><a href="#i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
				164	<li><a href="#i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a></li>
Chris Lattner	2f0f001	2006-01-13 02:03:13 +0000	[diff] [blame]	165	<li><a href="#i_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li>
				166	<li><a href="#i_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
Chris Lattner	c8a2c22	2005-02-28 19:24:19 +0000	[diff] [blame]	167	<li><a href="#i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
Andrew Lenharth	b442791	2005-03-28 20:05:49 +0000	[diff] [blame]	168	<li><a href="#i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
Andrew Lenharth	01aa563	2005-11-11 16:47:30 +0000	[diff] [blame]	169	<li><a href="#i_readcyclecounter"><tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
John Criswell	aa1c3c1	2004-04-09 16:43:20 +0000	[diff] [blame]	170	</ol>
				171	</li>
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	172	<li><a href="#int_libc">Standard C Library Intrinsics</a>
				173	<ol>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	174	<li><a href="#i_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li>
				175	<li><a href="#i_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li>
				176	<li><a href="#i_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li>
Chris Lattner	069b5bd	2006-01-16 22:38:59 +0000	[diff] [blame]	177	<li><a href="#i_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li>
Chris Lattner	33b73f9	2006-09-08 06:34:02 +0000	[diff] [blame]	178	<li><a href="#i_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li>
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	179	</ol>
				180	</li>
Nate Begeman	0f223bb	2006-01-13 23:26:38 +0000	[diff] [blame]	181	<li><a href="#int_manip">Bit Manipulation Intrinsics</a>
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	182	<ol>
Nate Begeman	0f223bb	2006-01-13 23:26:38 +0000	[diff] [blame]	183	<li><a href="#i_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li>
Chris Lattner	b748c67	2006-01-16 22:34:14 +0000	[diff] [blame]	184	<li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li>
				185	<li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li>
				186	<li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li>
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	187	</ol>
				188	</li>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	189	<li><a href="#int_debugger">Debugger intrinsics</a></li>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	190	</ol>
				191	</li>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	192	</ol>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	193
				194	<div class="doc_author">
				195	<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
				196	and <a href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></p>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	197	</div>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	198
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	199	<!-- *********************************************************************** -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	200	<div class="doc_section"> <a name="abstract">Abstract </a></div>
				201	<!-- *********************************************************************** -->
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	202
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	203	<div class="doc_text">
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	204	<p>This document is a reference manual for the LLVM assembly language.
				205	LLVM is an SSA based representation that provides type safety,
				206	low-level operations, flexibility, and the capability of representing
				207	'all' high-level languages cleanly. It is the common code
				208	representation used throughout all phases of the LLVM compilation
				209	strategy.</p>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	210	</div>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	211
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	212	<!-- *********************************************************************** -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	213	<div class="doc_section"> <a name="introduction">Introduction</a> </div>
				214	<!-- *********************************************************************** -->
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	215
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	216	<div class="doc_text">
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	217
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	218	<p>The LLVM code representation is designed to be used in three
				219	different forms: as an in-memory compiler IR, as an on-disk bytecode
				220	representation (suitable for fast loading by a Just-In-Time compiler),
				221	and as a human readable assembly language representation. This allows
				222	LLVM to provide a powerful intermediate representation for efficient
				223	compiler transformations and analysis, while providing a natural means
				224	to debug and visualize the transformations. The three different forms
				225	of LLVM are all equivalent. This document describes the human readable
				226	representation and notation.</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	227
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	228	<p>The LLVM representation aims to be light-weight and low-level
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	229	while being expressive, typed, and extensible at the same time. It
				230	aims to be a "universal IR" of sorts, by being at a low enough level
				231	that high-level ideas may be cleanly mapped to it (similar to how
				232	microprocessors are "universal IR's", allowing many source languages to
				233	be mapped to them). By providing type information, LLVM can be used as
				234	the target of optimizations: for example, through pointer analysis, it
				235	can be proven that a C automatic variable is never accessed outside of
				236	the current function... allowing it to be promoted to a simple SSA
				237	value instead of a memory location.</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	238
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	239	</div>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	240
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	241	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	242	<div class="doc_subsubsection"> <a name="wellformed">Well-Formedness</a> </div>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	243
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	244	<div class="doc_text">
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	245
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	246	<p>It is important to note that this document describes 'well formed'
				247	LLVM assembly language. There is a difference between what the parser
				248	accepts and what is considered 'well formed'. For example, the
				249	following instruction is syntactically okay, but not well formed:</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	250
				251	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	252	%x = <a href="#i_add">add</a> i32 1, %x
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	253	</pre>
				254
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	255	<p>...because the definition of <tt>%x</tt> does not dominate all of
				256	its uses. The LLVM infrastructure provides a verification pass that may
				257	be used to verify that an LLVM module is well formed. This pass is
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	258	automatically run by the parser after parsing input assembly and by
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	259	the optimizer before it outputs bytecode. The violations pointed out
				260	by the verifier pass indicate bugs in transformation passes or input to
				261	the parser.</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	262
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	263	<!-- Describe the typesetting conventions here. --> </div>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	264
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	265	<!-- *********************************************************************** -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	266	<div class="doc_section"> <a name="identifiers">Identifiers</a> </div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	267	<!-- *********************************************************************** -->
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	268
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	269	<div class="doc_text">
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	270
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	271	<p>LLVM uses three different forms of identifiers, for different
				272	purposes:</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	273
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	274	<ol>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	275	<li>Named values are represented as a string of characters with a '%' prefix.
				276	For example, %foo, %DivisionByZero, %a.really.long.identifier. The actual
				277	regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
				278	Identifiers which require other characters in their names can be surrounded
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	279	with quotes. In this way, anything except a <tt>"</tt> character can be used
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	280	in a name.</li>
				281
				282	<li>Unnamed values are represented as an unsigned numeric value with a '%'
				283	prefix. For example, %12, %2, %44.</li>
				284
Reid Spencer	8f08d80	2004-12-09 18:02:53 +0000	[diff] [blame]	285	<li>Constants, which are described in a <a href="#constants">section about
				286	constants</a>, below.</li>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	287	</ol>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	288
				289	<p>LLVM requires that values start with a '%' sign for two reasons: Compilers
				290	don't need to worry about name clashes with reserved words, and the set of
				291	reserved words may be expanded in the future without penalty. Additionally,
				292	unnamed identifiers allow a compiler to quickly come up with a temporary
				293	variable without having to avoid symbol table conflicts.</p>
				294
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	295	<p>Reserved words in LLVM are very similar to reserved words in other
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	296	languages. There are keywords for different opcodes
				297	('<tt><a href="#i_add">add</a></tt>',
				298	'<tt><a href="#i_bitcast">bitcast</a></tt>',
				299	'<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names ('<tt><a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	300	href="#t_void">void</a></tt>', '<tt><a href="#t_primitive">i32</a></tt>', etc...),
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	301	and others. These reserved words cannot conflict with variable names, because
				302	none of them start with a '%' character.</p>
				303
				304	<p>Here is an example of LLVM code to multiply the integer variable
				305	'<tt>%X</tt>' by 8:</p>
				306
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	307	<p>The easy way:</p>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	308
				309	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	310	%result = <a href="#i_mul">mul</a> i32 %X, 8
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	311	</pre>
				312
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	313	<p>After strength reduction:</p>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	314
				315	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	316	%result = <a href="#i_shl">shl</a> i32 %X, i8 3
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	317	</pre>
				318
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	319	<p>And the hard way:</p>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	320
				321	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	322	<a href="#i_add">add</a> i32 %X, %X <i>; yields {i32}:%0</i>
				323	<a href="#i_add">add</a> i32 %0, %0 <i>; yields {i32}:%1</i>
				324	%result = <a href="#i_add">add</a> i32 %1, %1
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	325	</pre>
				326
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	327	<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several
				328	important lexical features of LLVM:</p>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	329
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	330	<ol>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	331
				332	<li>Comments are delimited with a '<tt>;</tt>' and go until the end of
				333	line.</li>
				334
				335	<li>Unnamed temporaries are created when the result of a computation is not
				336	assigned to a named value.</li>
				337
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	338	<li>Unnamed temporaries are numbered sequentially</li>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	339
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	340	</ol>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	341
John Criswell	02fdc6f	2005-05-12 16:52:32 +0000	[diff] [blame]	342	<p>...and it also shows a convention that we follow in this document. When
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	343	demonstrating instructions, we will follow an instruction with a comment that
				344	defines the type and name of value produced. Comments are shown in italic
				345	text.</p>
				346
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	347	</div>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	348
				349	<!-- *********************************************************************** -->
				350	<div class="doc_section"> <a name="highlevel">High Level Structure</a> </div>
				351	<!-- *********************************************************************** -->
				352
				353	<!-- ======================================================================= -->
				354	<div class="doc_subsection"> <a name="modulestructure">Module Structure</a>
				355	</div>
				356
				357	<div class="doc_text">
				358
				359	<p>LLVM programs are composed of "Module"s, each of which is a
				360	translation unit of the input programs. Each module consists of
				361	functions, global variables, and symbol table entries. Modules may be
				362	combined together with the LLVM linker, which merges function (and
				363	global variable) definitions, resolves forward declarations, and merges
				364	symbol table entries. Here is an example of the "hello world" module:</p>
				365
				366	<pre><i>; Declare the string constant as a global constant...</i>
				367	<a href="#identifiers">%.LC0</a> = <a href="#linkage_internal">internal</a> <a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	368	href="#globalvars">constant</a> <a href="#t_array">[13 x i8 ]</a> c"hello world\0A\00" <i>; [13 x i8 ]*</i>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	369
				370	<i>; External declaration of the puts function</i>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	371	<a href="#functionstructure">declare</a> i32 %puts(i8 ) <i>; i32(i8 )* </i>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	372
Chris Lattner	d2d29a0	2006-06-13 03:05:47 +0000	[diff] [blame]	373	<i>; Global variable / Function body section separator</i>
				374	implementation
				375
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	376	<i>; Definition of main function</i>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	377	define i32 %main() { <i>; i32()* </i>
				378	<i>; Convert [13x i8 ]* to i8 *...</i>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	379	%cast210 = <a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	380	href="#i_getelementptr">getelementptr</a> [13 x i8 ]* %.LC0, i64 0, i64 0 <i>; i8 *</i>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	381
				382	<i>; Call puts function to write out the string to stdout...</i>
				383	<a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	384	href="#i_call">call</a> i32 %puts(i8 * %cast210) <i>; i32</i>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	385	<a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	386	href="#i_ret">ret</a> i32 0<br>}<br></pre>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	387
				388	<p>This example is made up of a <a href="#globalvars">global variable</a>
				389	named "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>"
				390	function, and a <a href="#functionstructure">function definition</a>
				391	for "<tt>main</tt>".</p>
				392
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	393	<p>In general, a module is made up of a list of global values,
				394	where both functions and global variables are global values. Global values are
				395	represented by a pointer to a memory location (in this case, a pointer to an
				396	array of char, and a pointer to a function), and have one of the following <a
				397	href="#linkage">linkage types</a>.</p>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	398
Chris Lattner	d2d29a0	2006-06-13 03:05:47 +0000	[diff] [blame]	399	<p>Due to a limitation in the current LLVM assembly parser (it is limited by
				400	one-token lookahead), modules are split into two pieces by the "implementation"
				401	keyword. Global variable prototypes and definitions must occur before the
				402	keyword, and function definitions must occur after it. Function prototypes may
				403	occur either before or after it. In the future, the implementation keyword may
				404	become a noop, if the parser gets smarter.</p>
				405
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	406	</div>
				407
				408	<!-- ======================================================================= -->
				409	<div class="doc_subsection">
				410	<a name="linkage">Linkage Types</a>
				411	</div>
				412
				413	<div class="doc_text">
				414
				415	<p>
				416	All Global Variables and Functions have one of the following types of linkage:
				417	</p>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	418
				419	<dl>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	420
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	421	<dt><tt><b><a name="linkage_internal">internal</a></b></tt> </dt>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	422
				423	<dd>Global values with internal linkage are only directly accessible by
				424	objects in the current module. In particular, linking code into a module with
				425	an internal global value may cause the internal to be renamed as necessary to
				426	avoid collisions. Because the symbol is internal to the module, all
				427	references can be updated. This corresponds to the notion of the
Chris Lattner	e20b470	2007-01-14 06:51:48 +0000	[diff] [blame]	428	'<tt>static</tt>' keyword in C.
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	429	</dd>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	430
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	431	<dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt>: </dt>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	432
Chris Lattner	e20b470	2007-01-14 06:51:48 +0000	[diff] [blame]	433	<dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
				434	the same name when linkage occurs. This is typically used to implement
				435	inline functions, templates, or other code which must be generated in each
				436	translation unit that uses it. Unreferenced <tt>linkonce</tt> globals are
				437	allowed to be discarded.
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	438	</dd>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	439
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	440	<dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	441
				442	<dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt> linkage,
				443	except that unreferenced <tt>weak</tt> globals may not be discarded. This is
Chris Lattner	e20b470	2007-01-14 06:51:48 +0000	[diff] [blame]	444	used for globals that may be emitted in multiple translation units, but that
				445	are not guaranteed to be emitted into every translation unit that uses them.
				446	One example of this are common globals in C, such as "<tt>int X;</tt>" at
				447	global scope.
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	448	</dd>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	449
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	450	<dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	451
				452	<dd>"<tt>appending</tt>" linkage may only be applied to global variables of
				453	pointer to array type. When two global variables with appending linkage are
				454	linked together, the two global arrays are appended together. This is the
				455	LLVM, typesafe, equivalent of having the system linker append together
				456	"sections" with identical names when .o files are linked.
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	457	</dd>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	458
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	459	<dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt>: </dt>
				460	<dd>The semantics of this linkage follow the ELF model: the symbol is weak
				461	until linked, if not linked, the symbol becomes null instead of being an
				462	undefined reference.
				463	</dd>
				464	</dl>
				465
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	466	<dt><tt><b><a name="linkage_external">externally visible</a></b></tt>:</dt>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	467
				468	<dd>If none of the above identifiers are used, the global is externally
				469	visible, meaning that it participates in linkage and can be used to resolve
				470	external symbol references.
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	471	</dd>
Anton Korobeynikov	d61d39e	2006-09-14 18:23:27 +0000	[diff] [blame]	472
Anton Korobeynikov	d61d39e	2006-09-14 18:23:27 +0000	[diff] [blame]	473	<p>
				474	The next two types of linkage are targeted for Microsoft Windows platform
				475	only. They are designed to support importing (exporting) symbols from (to)
				476	DLLs.
				477	</p>
				478
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	479	<dl>
Anton Korobeynikov	d61d39e	2006-09-14 18:23:27 +0000	[diff] [blame]	480	<dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt>: </dt>
				481
				482	<dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
				483	or variable via a global pointer to a pointer that is set up by the DLL
				484	exporting the symbol. On Microsoft Windows targets, the pointer name is
				485	formed by combining <code>_imp__</code> and the function or variable name.
				486	</dd>
				487
				488	<dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt>: </dt>
				489
				490	<dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
				491	pointer to a pointer in a DLL, so that it can be referenced with the
				492	<tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
				493	name is formed by combining <code>_imp__</code> and the function or variable
				494	name.
				495	</dd>
				496
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	497	</dl>
				498
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	499	<p><a name="linkage_external"></a>For example, since the "<tt>.LC0</tt>"
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	500	variable is defined to be internal, if another module defined a "<tt>.LC0</tt>"
				501	variable and was linked with this one, one of the two would be renamed,
				502	preventing a collision. Since "<tt>main</tt>" and "<tt>puts</tt>" are
				503	external (i.e., lacking any linkage declarations), they are accessible
Reid Spencer	92c671e	2007-01-05 00:59:10 +0000	[diff] [blame]	504	outside of the current module.</p>
				505	<p>It is illegal for a function <i>declaration</i>
				506	to have any linkage type other than "externally visible", <tt>dllimport</tt>,
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	507	or <tt>extern_weak</tt>.</p>
Chris Lattner	d79749a	2004-12-09 16:36:40 +0000	[diff] [blame]	508
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	509	</div>
				510
				511	<!-- ======================================================================= -->
				512	<div class="doc_subsection">
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	513	<a name="callingconv">Calling Conventions</a>
				514	</div>
				515
				516	<div class="doc_text">
				517
				518	<p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
				519	and <a href="#i_invoke">invokes</a> can all have an optional calling convention
				520	specified for the call. The calling convention of any pair of dynamic
				521	caller/callee must match, or the behavior of the program is undefined. The
				522	following calling conventions are supported by LLVM, and more may be added in
				523	the future:</p>
				524
				525	<dl>
				526	<dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
				527
				528	<dd>This calling convention (the default if no other calling convention is
				529	specified) matches the target C calling conventions. This calling convention
John Criswell	02fdc6f	2005-05-12 16:52:32 +0000	[diff] [blame]	530	supports varargs function calls and tolerates some mismatch in the declared
Reid Spencer	72ba499	2006-12-31 21:30:18 +0000	[diff] [blame]	531	prototype and implemented declaration of the function (as does normal C).
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	532	</dd>
				533
				534	<dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
				535
				536	<dd>This calling convention attempts to make calls as fast as possible
				537	(e.g. by passing things in registers). This calling convention allows the
				538	target to use whatever tricks it wants to produce fast code for the target,
Chris Lattner	c792eb3	2005-05-06 23:08:23 +0000	[diff] [blame]	539	without having to conform to an externally specified ABI. Implementations of
				540	this convention should allow arbitrary tail call optimization to be supported.
				541	This calling convention does not support varargs and requires the prototype of
				542	all callees to exactly match the prototype of the function definition.
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	543	</dd>
				544
				545	<dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
				546
				547	<dd>This calling convention attempts to make code in the caller as efficient
				548	as possible under the assumption that the call is not commonly executed. As
				549	such, these calls often preserve all registers so that the call does not break
				550	any live ranges in the caller side. This calling convention does not support
				551	varargs and requires the prototype of all callees to exactly match the
				552	prototype of the function definition.
				553	</dd>
				554
Chris Lattner	573f64e	2005-05-07 01:46:40 +0000	[diff] [blame]	555	<dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	556
				557	<dd>Any calling convention may be specified by number, allowing
				558	target-specific calling conventions to be used. Target specific calling
				559	conventions start at 64.
				560	</dd>
Chris Lattner	573f64e	2005-05-07 01:46:40 +0000	[diff] [blame]	561	</dl>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	562
				563	<p>More calling conventions can be added/defined on an as-needed basis, to
				564	support pascal conventions or any other well-known target-independent
				565	convention.</p>
				566
				567	</div>
				568
				569	<!-- ======================================================================= -->
				570	<div class="doc_subsection">
Anton Korobeynikov	c7f9f3d	2007-01-23 12:35:46 +0000	[diff] [blame]	571	<a name="visibility">Visibility Styles</a>
				572	</div>
				573
				574	<div class="doc_text">
				575
				576	<p>
				577	All Global Variables and Functions have one of the following visibility styles:
				578	</p>
				579
				580	<dl>
				581	<dt><b>"<tt>default</tt>" - Default style</b>:</dt>
				582
				583	<dd>On ELF, default visibility means that the declaration is visible to other
				584	modules and, in shared libraries, means that the declared entity may be
				585	overridden. On Darwin, default visibility means that the declaration is
				586	visible to other modules. Default visibility corresponds to "external
				587	linkage" in the language.
				588	</dd>
				589
				590	<dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt>
				591
				592	<dd>Two declarations of an object with hidden visibility refer to the same
				593	object if they are in the same shared object. Usually, hidden visibility
				594	indicates that the symbol will not be placed into the dynamic symbol table,
				595	so no other module (executable or shared library) can reference it
				596	directly.
				597	</dd>
				598
				599	</dl>
				600
				601	</div>
				602
				603	<!-- ======================================================================= -->
				604	<div class="doc_subsection">
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	605	<a name="globalvars">Global Variables</a>
				606	</div>
				607
				608	<div class="doc_text">
				609
Chris Lattner	5d5aede	2005-02-12 19:30:21 +0000	[diff] [blame]	610	<p>Global variables define regions of memory allocated at compilation time
Chris Lattner	662c872	2005-11-12 00:45:07 +0000	[diff] [blame]	611	instead of run-time. Global variables may optionally be initialized, may have
				612	an explicit section to be placed in, and may
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	613	have an optional explicit alignment specified. A
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	614	variable may be defined as a global "constant," which indicates that the
Chris Lattner	5d5aede	2005-02-12 19:30:21 +0000	[diff] [blame]	615	contents of the variable will <b>never</b> be modified (enabling better
				616	optimization, allowing the global data to be placed in the read-only section of
				617	an executable, etc). Note that variables that need runtime initialization
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	618	cannot be marked "constant" as there is a store to the variable.</p>
Chris Lattner	5d5aede	2005-02-12 19:30:21 +0000	[diff] [blame]	619
				620	<p>
				621	LLVM explicitly allows <em>declarations</em> of global variables to be marked
				622	constant, even if the final definition of the global is not. This capability
				623	can be used to enable slightly better optimization of the program, but requires
				624	the language definition to guarantee that optimizations based on the
				625	'constantness' are valid for the translation units that do not include the
				626	definition.
				627	</p>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	628
				629	<p>As SSA values, global variables define pointer values that are in
				630	scope (i.e. they dominate) all basic blocks in the program. Global
				631	variables always define a pointer to their "content" type because they
				632	describe a region of memory, and all memory objects in LLVM are
				633	accessed through pointers.</p>
				634
Chris Lattner	662c872	2005-11-12 00:45:07 +0000	[diff] [blame]	635	<p>LLVM allows an explicit section to be specified for globals. If the target
				636	supports it, it will emit globals to the section specified.</p>
				637
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	638	<p>An explicit alignment may be specified for a global. If not present, or if
				639	the alignment is set to zero, the alignment of the global is set by the target
				640	to whatever it feels convenient. If an explicit alignment is specified, the
				641	global is forced to have at least that much alignment. All alignments must be
				642	a power of 2.</p>
				643
Chris Lattner	5760c50	2007-01-14 00:27:09 +0000	[diff] [blame]	644	<p>For example, the following defines a global with an initializer, section,
				645	and alignment:</p>
				646
				647	<pre>
				648	%G = constant float 1.0, section "foo", align 4
				649	</pre>
				650
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	651	</div>
				652
				653
				654	<!-- ======================================================================= -->
				655	<div class="doc_subsection">
				656	<a name="functionstructure">Functions</a>
				657	</div>
				658
				659	<div class="doc_text">
				660
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	661	<p>LLVM function definitions consist of the "<tt>define</tt>" keyord,
				662	an optional <a href="#linkage">linkage type</a>, an optional
Anton Korobeynikov	c7f9f3d	2007-01-23 12:35:46 +0000	[diff] [blame]	663	<a href="#visibility">visibility style</a>, an optional
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	664	<a href="#callingconv">calling convention</a>, a return type, an optional
				665	<a href="#paramattrs">parameter attribute</a> for the return type, a function
				666	name, a (possibly empty) argument list (each with optional
Anton Korobeynikov	c7f9f3d	2007-01-23 12:35:46 +0000	[diff] [blame]	667	<a href="#paramattrs">parameter attributes</a>), an optional section, an
				668	optional alignment, an opening curly brace, a list of basic blocks, and a
				669	closing curly brace.
				670
				671	LLVM function declarations consist of the "<tt>declare</tt>" keyword, an
				672	optional <a href="#linkage">linkage type</a>, an optional
				673	<a href="#visibility">visibility style</a>, an optional
				674	<a href="#callingconv">calling convention</a>, a return type, an optional
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	675	<a href="#paramattrs">parameter attribute</a> for the return type, a function
				676	name, a possibly empty list of arguments, and an optional alignment.</p>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	677
				678	<p>A function definition contains a list of basic blocks, forming the CFG for
				679	the function. Each basic block may optionally start with a label (giving the
				680	basic block a symbol table entry), contains a list of instructions, and ends
				681	with a <a href="#terminators">terminator</a> instruction (such as a branch or
				682	function return).</p>
				683
John Criswell	02fdc6f	2005-05-12 16:52:32 +0000	[diff] [blame]	684	<p>The first basic block in a program is special in two ways: it is immediately
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	685	executed on entrance to the function, and it is not allowed to have predecessor
				686	basic blocks (i.e. there can not be any branches to the entry block of a
				687	function). Because the block can have no predecessors, it also cannot have any
				688	<a href="#i_phi">PHI nodes</a>.</p>
				689
				690	<p>LLVM functions are identified by their name and type signature. Hence, two
				691	functions with the same name but different parameter lists or return values are
Chris Lattner	455fc8c	2005-03-07 22:13:59 +0000	[diff] [blame]	692	considered different functions, and LLVM will resolve references to each
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	693	appropriately.</p>
				694
Chris Lattner	662c872	2005-11-12 00:45:07 +0000	[diff] [blame]	695	<p>LLVM allows an explicit section to be specified for functions. If the target
				696	supports it, it will emit functions to the section specified.</p>
				697
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	698	<p>An explicit alignment may be specified for a function. If not present, or if
				699	the alignment is set to zero, the alignment of the function is set by the target
				700	to whatever it feels convenient. If an explicit alignment is specified, the
				701	function is forced to have at least that much alignment. All alignments must be
				702	a power of 2.</p>
				703
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	704	</div>
				705
Chris Lattner	91c15c4	2006-01-23 23:23:47 +0000	[diff] [blame]	706	<!-- ======================================================================= -->
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	707	<div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div>
				708	<div class="doc_text">
				709	<p>The return type and each parameter of a function type may have a set of
				710	<i>parameter attributes</i> associated with them. Parameter attributes are
				711	used to communicate additional information about the result or parameters of
				712	a function. Parameter attributes are considered to be part of the function
				713	type so two functions types that differ only by the parameter attributes
				714	are different function types.</p>
				715
Reid Spencer	cf7ebf5	2007-01-15 18:27:39 +0000	[diff] [blame]	716	<p>Parameter attributes are simple keywords that follow the type specified. If
				717	multiple parameter attributes are needed, they are space separated. For
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	718	example:</p><pre>
Reid Spencer	cf7ebf5	2007-01-15 18:27:39 +0000	[diff] [blame]	719	%someFunc = i16 (i8 sext %someParam) zext
				720	%someFunc = i16 (i8 zext %someParam) zext</pre>
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	721	<p>Note that the two function types above are unique because the parameter has
Reid Spencer	cf7ebf5	2007-01-15 18:27:39 +0000	[diff] [blame]	722	a different attribute (sext in the first one, zext in the second). Also note
				723	that the attribute for the function result (zext) comes immediately after the
				724	argument list.</p>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	725
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	726	<p>Currently, only the following parameter attributes are defined:</p>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	727	<dl>
Reid Spencer	cf7ebf5	2007-01-15 18:27:39 +0000	[diff] [blame]	728	<dt><tt>zext</tt></dt>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	729	<dd>This indicates that the parameter should be zero extended just before
				730	a call to this function.</dd>
Reid Spencer	cf7ebf5	2007-01-15 18:27:39 +0000	[diff] [blame]	731	<dt><tt>sext</tt></dt>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	732	<dd>This indicates that the parameter should be sign extended just before
				733	a call to this function.</dd>
Anton Korobeynikov	e816685	2007-01-28 14:30:45 +0000	[diff] [blame]	734	<dt><tt>inreg</tt></dt>
				735	<dd>This indicates that the parameter should be placed in register (if
Anton Korobeynikov	e93c6e8	2007-01-28 15:27:21 +0000	[diff] [blame]	736	possible) during assembling function call. Support for this attribute is
				737	target-specific</dd>
Anton Korobeynikov	e816685	2007-01-28 14:30:45 +0000	[diff] [blame]	738	<dt><tt>sret</tt></dt>
Anton Korobeynikov	e93c6e8	2007-01-28 15:27:21 +0000	[diff] [blame]	739	<dd>This indicates that the parameter specifies the address of a structure
				740	that is the return value of the function in the source program.
				741	</dd>
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	742	</dl>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	743
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	744	</div>
				745
				746	<!-- ======================================================================= -->
Chris Lattner	91c15c4	2006-01-23 23:23:47 +0000	[diff] [blame]	747	<div class="doc_subsection">
Chris Lattner	9356489	2006-04-08 04:40:53 +0000	[diff] [blame]	748	<a name="moduleasm">Module-Level Inline Assembly</a>
Chris Lattner	91c15c4	2006-01-23 23:23:47 +0000	[diff] [blame]	749	</div>
				750
				751	<div class="doc_text">
				752	<p>
				753	Modules may contain "module-level inline asm" blocks, which corresponds to the
				754	GCC "file scope inline asm" blocks. These blocks are internally concatenated by
				755	LLVM and treated as a single unit, but may be separated in the .ll file if
				756	desired. The syntax is very simple:
				757	</p>
				758
				759	<div class="doc_code"><pre>
Chris Lattner	a1280ad	2006-01-24 00:37:20 +0000	[diff] [blame]	760	module asm "inline asm code goes here"
				761	module asm "more can go here"
Chris Lattner	91c15c4	2006-01-23 23:23:47 +0000	[diff] [blame]	762	</pre></div>
				763
				764	<p>The strings can contain any character by escaping non-printable characters.
				765	The escape sequence used is simply "\xx" where "xx" is the two digit hex code
				766	for the number.
				767	</p>
				768
				769	<p>
				770	The inline asm code is simply printed to the machine code .s file when
				771	assembly code is generated.
				772	</p>
				773	</div>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	774
Reid Spencer	50c723a	2007-02-19 23:54:10 +0000	[diff] [blame^]	775	<!-- ======================================================================= -->
				776	<div class="doc_subsection">
				777	<a name="datalayout">Data Layout</a>
				778	</div>
				779
				780	<div class="doc_text">
				781	<p>A module may specify a target specific data layout string that specifies how
				782	data is to be laid out in memory. The syntax for the data layout is simply:<br/>
				783	<pre> target datalayout = "<i>layout specification</i>"
				784	</pre>
				785	The <i>layout specification</i> consists of a list of specifications separated
				786	by the minus sign character ('-'). Each specification starts with a letter
				787	and may include other information after the letter to define some aspect of the
				788	data layout. The specifications accepted are as follows: </p>
				789	<dl>
				790	<dt><tt>E</tt></dt>
				791	<dd>Specifies that the target lays out data in big-endian form. That is, the
				792	bits with the most significance have the lowest address location.</dd>
				793	<dt><tt>e</tt></dt>
				794	<dd>Specifies that hte target lays out data in little-endian form. That is,
				795	the bits with the least significance have the lowest address location.</dd>
				796	<dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
				797	<dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
				798	<i>preferred</i> alignments. All sizes are in bits. Specifying the <i>pref</i>
				799	alignment is optional. If omitted, the preceding <tt>:</tt> should be omitted
				800	too.</dd>
				801	<dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
				802	<dd>This specifies the alignment for an integer type of a given bit
				803	<i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd>
				804	<dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
				805	<dd>This specifies the alignment for a vector type of a given bit
				806	<i>size</i>.</dd>
				807	<dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
				808	<dd>This specifies the alignment for a floating point type of a given bit
				809	<i>size</i>. The value of <i>size</i> must be either 32 (float) or 64
				810	(double).</dd>
				811	<dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
				812	<dd>This specifies the alignment for an aggregate type of a given bit
				813	<i>size</i>.</dd>
				814	</dl>
				815	<p>When constructing the data layout for a given target, LLVM starts with a
				816	default set of specifications which are then (possibly) overriden by the
				817	specifications in the <tt>datalayout</tt> keyword. The default specifications
				818	are given in this list:</p>
				819	<ul>
				820	<li><tt>E</tt> - big endian</li>
				821	<li><tt>p:32:64:64</tt> - 32-bit pointers with 64-bit alignment</li>
				822	<li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li>
				823	<li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li>
				824	<li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li>
				825	<li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li>
				826	<li><tt>i64:32:64</tt> - i64 has abi alignment of 32-bits but preferred
				827	alignment of 64-bits</li>
				828	<li><tt>f32:32:32</tt> - float is 32-bit aligned</li>
				829	<li><tt>f64:64:64</tt> - double is 64-bit aligned</li>
				830	<li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li>
				831	<li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li>
				832	<li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li>
				833	</ul>
				834	<p>When llvm is determining the alignment for a given type, it uses the
				835	following rules:
				836	<ol>
				837	<li>If the type sought is an exact match for one of the specifications, that
				838	specification is used.</li>
				839	<li>If no match is found, and the type sought is an integer type, then the
				840	smallest integer type that is larger than the bitwidth of the sought type is
				841	used. If none of the specifications are larger than the bitwidth then the the
				842	largest integer type is used. For example, given the default specifications
				843	above, the i7 type will use the alignment of i8 (next largest) while both
				844	i65 and i256 will use the alignment of i64 (largest specified).</li>
				845	<li>If no match is found, and the type sought is a vector type, then the
				846	largest vector type that is smaller than the sought vector type will be used
				847	as a fall back. This happens because <128 x double> can be implemented in
				848	terms of 64 <2 x double>, for example.</li>
				849	</ol>
				850	</div>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	851
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	852	<!-- *********************************************************************** -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	853	<div class="doc_section"> <a name="typesystem">Type System</a> </div>
				854	<!-- *********************************************************************** -->
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	855
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	856	<div class="doc_text">
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	857
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	858	<p>The LLVM type system is one of the most important features of the
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	859	intermediate representation. Being typed enables a number of
				860	optimizations to be performed on the IR directly, without having to do
				861	extra analyses on the side before the transformation. A strong type
				862	system makes it easier to read the generated code and enables novel
				863	analyses and transformations that are not feasible to perform on normal
				864	three address code representations.</p>
Chris Lattner	6af02f3	2004-12-09 16:11:40 +0000	[diff] [blame]	865
				866	</div>
				867
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	868	<!-- ======================================================================= -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	869	<div class="doc_subsection"> <a name="t_primitive">Primitive Types</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	870	<div class="doc_text">
John Criswell	417228d	2004-04-09 16:48:45 +0000	[diff] [blame]	871	<p>The primitive types are the fundamental building blocks of the LLVM
Chris Lattner	455fc8c	2005-03-07 22:13:59 +0000	[diff] [blame]	872	system. The current set of primitive types is as follows:</p>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	873
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	874	<table class="layout">
				875	<tr class="layout">
				876	<td class="left">
				877	<table>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	878	<tbody>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	879	<tr><th>Type</th><th>Description</th></tr>
				880	<tr><td><tt>void</tt></td><td>No value</td></tr>
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	881	<tr><td><tt>i8</tt></td><td>8-bit value</td></tr>
				882	<tr><td><tt>i32</tt></td><td>32-bit value</td></tr>
Misha Brukman	36c6bc1	2005-04-22 18:02:52 +0000	[diff] [blame]	883	<tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	884	<tr><td><tt>label</tt></td><td>Branch destination</td></tr>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	885	</tbody>
				886	</table>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	887	</td>
				888	<td class="right">
				889	<table>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	890	<tbody>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	891	<tr><th>Type</th><th>Description</th></tr>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	892	<tr><td><tt>i1</tt></td><td>True or False value</td></tr>
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	893	<tr><td><tt>i16</tt></td><td>16-bit value</td></tr>
				894	<tr><td><tt>i64</tt></td><td>64-bit value</td></tr>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	895	<tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	896	</tbody>
				897	</table>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	898	</td>
				899	</tr>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	900	</table>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	901	</div>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	902
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	903	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	904	<div class="doc_subsubsection"> <a name="t_classifications">Type
				905	Classifications</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	906	<div class="doc_text">
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	907	<p>These different primitive types fall into a few useful
				908	classifications:</p>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	909
				910	<table border="1" cellspacing="0" cellpadding="4">
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	911	<tbody>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	912	<tr><th>Classification</th><th>Types</th></tr>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	913	<tr>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	914	<td><a name="t_integer">integer</a></td>
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	915	<td><tt>i1, i8, i16, i32, i64</tt></td>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	916	</tr>
				917	<tr>
				918	<td><a name="t_floating">floating point</a></td>
				919	<td><tt>float, double</tt></td>
				920	</tr>
				921	<tr>
				922	<td><a name="t_firstclass">first class</a></td>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	923	<td><tt>i1, i8, i16, i32, i64, float, double, <br/>
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	924	<a href="#t_pointer">pointer</a>,<a href="#t_vector">vector</a></tt>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	925	</td>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	926	</tr>
				927	</tbody>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	928	</table>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	929
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	930	<p>The <a href="#t_firstclass">first class</a> types are perhaps the
				931	most important. Values of these types are the only ones which can be
				932	produced by instructions, passed as arguments, or used as operands to
				933	instructions. This means that all structures and arrays must be
				934	manipulated either by pointer or by component.</p>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	935	</div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	936
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	937	<!-- ======================================================================= -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	938	<div class="doc_subsection"> <a name="t_derived">Derived Types</a> </div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	939
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	940	<div class="doc_text">
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	941
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	942	<p>The real power in LLVM comes from the derived types in the system.
				943	This is what allows a programmer to represent arrays, functions,
				944	pointers, and other useful types. Note that these derived types may be
				945	recursive: For example, it is possible to have a two dimensional array.</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	946
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	947	</div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	948
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	949	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	950	<div class="doc_subsubsection"> <a name="t_array">Array Type</a> </div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	951
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	952	<div class="doc_text">
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	953
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	954	<h5>Overview:</h5>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	955
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	956	<p>The array type is a very simple derived type that arranges elements
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	957	sequentially in memory. The array type requires a size (number of
				958	elements) and an underlying data type.</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	959
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	960	<h5>Syntax:</h5>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	961
				962	<pre>
				963	[<# elements> x <elementtype>]
				964	</pre>
				965
John Criswell	02fdc6f	2005-05-12 16:52:32 +0000	[diff] [blame]	966	<p>The number of elements is a constant integer value; elementtype may
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	967	be any type with a size.</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	968
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	969	<h5>Examples:</h5>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	970	<table class="layout">
				971	<tr class="layout">
				972	<td class="left">
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	973	<tt>[40 x i32 ]</tt><br/>
				974	<tt>[41 x i32 ]</tt><br/>
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	975	<tt>[40 x i8]</tt><br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	976	</td>
				977	<td class="left">
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	978	Array of 40 32-bit integer values.<br/>
				979	Array of 41 32-bit integer values.<br/>
				980	Array of 40 8-bit integer values.<br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	981	</td>
				982	</tr>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	983	</table>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	984	<p>Here are some examples of multidimensional arrays:</p>
				985	<table class="layout">
				986	<tr class="layout">
				987	<td class="left">
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	988	<tt>[3 x [4 x i32]]</tt><br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	989	<tt>[12 x [10 x float]]</tt><br/>
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	990	<tt>[2 x [3 x [4 x i16]]]</tt><br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	991	</td>
				992	<td class="left">
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	993	3x4 array of 32-bit integer values.<br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	994	12x10 array of single precision floating point values.<br/>
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	995	2x3x4 array of 16-bit integer values.<br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	996	</td>
				997	</tr>
				998	</table>
Chris Lattner	c0ad71e	2005-06-24 17:22:57 +0000	[diff] [blame]	999
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	1000	<p>Note that 'variable sized arrays' can be implemented in LLVM with a zero
				1001	length array. Normally, accesses past the end of an array are undefined in
Chris Lattner	c0ad71e	2005-06-24 17:22:57 +0000	[diff] [blame]	1002	LLVM (e.g. it is illegal to access the 5th element of a 3 element array).
				1003	As a special case, however, zero length arrays are recognized to be variable
				1004	length. This allows implementation of 'pascal style arrays' with the LLVM
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1005	type "{ i32, [0 x float]}", for example.</p>
Chris Lattner	c0ad71e	2005-06-24 17:22:57 +0000	[diff] [blame]	1006
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1007	</div>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1008
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1009	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1010	<div class="doc_subsubsection"> <a name="t_function">Function Type</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1011	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1012	<h5>Overview:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1013	<p>The function type can be thought of as a function signature. It
				1014	consists of a return type and a list of formal parameter types.
John Criswell	a0d50d2	2003-11-25 21:45:46 +0000	[diff] [blame]	1015	Function types are usually used to build virtual function tables
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1016	(which are structures of pointers to functions), for indirect function
				1017	calls, and when defining a function.</p>
John Criswell	a0d50d2	2003-11-25 21:45:46 +0000	[diff] [blame]	1018	<p>
				1019	The return type of a function type cannot be an aggregate type.
				1020	</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1021	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1022	<pre> <returntype> (<parameter list>)<br></pre>
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	1023	<p>...where '<tt><parameter list></tt>' is a comma-separated list of type
Misha Brukman	20f9a62	2004-08-12 20:16:08 +0000	[diff] [blame]	1024	specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
Chris Lattner	5ed6061	2003-09-03 00:41:47 +0000	[diff] [blame]	1025	which indicates that the function takes a variable number of arguments.
				1026	Variable argument functions can access their arguments with the <a
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1027	href="#int_varargs">variable argument handling intrinsic</a> functions.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1028	<h5>Examples:</h5>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1029	<table class="layout">
				1030	<tr class="layout">
Reid Spencer	58c0871	2006-12-31 07:18:34 +0000	[diff] [blame]	1031	<td class="left"><tt>i32 (i32)</tt></td>
				1032	<td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1033	</td>
Reid Spencer	58c0871	2006-12-31 07:18:34 +0000	[diff] [blame]	1034	</tr><tr class="layout">
Reid Spencer	e6a338d	2007-01-15 18:28:34 +0000	[diff] [blame]	1035	<td class="left"><tt>float (i16 sext, i32 )
Reid Spencer	655dcc6	2006-12-31 07:20:23 +0000	[diff] [blame]	1036	</tt></td>
Reid Spencer	58c0871	2006-12-31 07:18:34 +0000	[diff] [blame]	1037	<td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
				1038	an <tt>i16</tt> that should be sign extended and a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1039	<a href="#t_pointer">pointer</a> to <tt>i32</tt>, returning
Reid Spencer	58c0871	2006-12-31 07:18:34 +0000	[diff] [blame]	1040	<tt>float</tt>.
				1041	</td>
				1042	</tr><tr class="layout">
				1043	<td class="left"><tt>i32 (i8*, ...)</tt></td>
				1044	<td class="left">A vararg function that takes at least one
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	1045	<a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
Reid Spencer	58c0871	2006-12-31 07:18:34 +0000	[diff] [blame]	1046	which returns an integer. This is the signature for <tt>printf</tt> in
				1047	LLVM.
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1048	</td>
				1049	</tr>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1050	</table>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	1051
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1052	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1053	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1054	<div class="doc_subsubsection"> <a name="t_struct">Structure Type</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1055	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1056	<h5>Overview:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1057	<p>The structure type is used to represent a collection of data members
				1058	together in memory. The packing of the field types is defined to match
				1059	the ABI of the underlying processor. The elements of a structure may
				1060	be any type that has a size.</p>
				1061	<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt>
				1062	and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a
				1063	field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>'
				1064	instruction.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1065	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1066	<pre> { <type list> }<br></pre>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1067	<h5>Examples:</h5>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1068	<table class="layout">
				1069	<tr class="layout">
				1070	<td class="left">
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1071	<tt>{ i32, i32, i32 }</tt><br/>
				1072	<tt>{ float, i32 (i32) * }</tt><br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1073	</td>
				1074	<td class="left">
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1075	a triple of three <tt>i32</tt> values<br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1076	A pair, where the first element is a <tt>float</tt> and the second element
				1077	is a <a href="#t_pointer">pointer</a> to a <a href="#t_function">function</a>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1078	that takes an <tt>i32</tt>, returning an <tt>i32</tt>.<br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1079	</td>
				1080	</tr>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1081	</table>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1082	</div>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1083
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1084	<!-- _______________________________________________________________________ -->
Andrew Lenharth	8df88e2	2006-12-08 17:13:00 +0000	[diff] [blame]	1085	<div class="doc_subsubsection"> <a name="t_pstruct">Packed Structure Type</a>
				1086	</div>
				1087	<div class="doc_text">
				1088	<h5>Overview:</h5>
				1089	<p>The packed structure type is used to represent a collection of data members
				1090	together in memory. There is no padding between fields. Further, the alignment
				1091	of a packed structure is 1 byte. The elements of a packed structure may
				1092	be any type that has a size.</p>
				1093	<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt>
				1094	and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a
				1095	field with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>'
				1096	instruction.</p>
				1097	<h5>Syntax:</h5>
				1098	<pre> < { <type list> } > <br></pre>
				1099	<h5>Examples:</h5>
				1100	<table class="layout">
				1101	<tr class="layout">
				1102	<td class="left">
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1103	<tt> < { i32, i32, i32 } > </tt><br/>
				1104	<tt> < { float, i32 (i32) * } > </tt><br/>
Andrew Lenharth	8df88e2	2006-12-08 17:13:00 +0000	[diff] [blame]	1105	</td>
				1106	<td class="left">
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1107	a triple of three <tt>i32</tt> values<br/>
Andrew Lenharth	8df88e2	2006-12-08 17:13:00 +0000	[diff] [blame]	1108	A pair, where the first element is a <tt>float</tt> and the second element
				1109	is a <a href="#t_pointer">pointer</a> to a <a href="#t_function">function</a>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1110	that takes an <tt>i32</tt>, returning an <tt>i32</tt>.<br/>
Andrew Lenharth	8df88e2	2006-12-08 17:13:00 +0000	[diff] [blame]	1111	</td>
				1112	</tr>
				1113	</table>
				1114	</div>
				1115
				1116	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1117	<div class="doc_subsubsection"> <a name="t_pointer">Pointer Type</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1118	<div class="doc_text">
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	1119	<h5>Overview:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1120	<p>As in many languages, the pointer type represents a pointer or
				1121	reference to another object, which must live in memory.</p>
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	1122	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1123	<pre> <type> *<br></pre>
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	1124	<h5>Examples:</h5>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1125	<table class="layout">
				1126	<tr class="layout">
				1127	<td class="left">
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1128	<tt>[4x i32]*</tt><br/>
				1129	<tt>i32 (i32 ) </tt><br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1130	</td>
				1131	<td class="left">
				1132	A <a href="#t_pointer">pointer</a> to <a href="#t_array">array</a> of
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1133	four <tt>i32</tt> values<br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1134	A <a href="#t_pointer">pointer</a> to a <a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1135	href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an
				1136	<tt>i32</tt>.<br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1137	</td>
				1138	</tr>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1139	</table>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1140	</div>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1141
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1142	<!-- _______________________________________________________________________ -->
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1143	<div class="doc_subsubsection"> <a name="t_vector">Vector Type</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1144	<div class="doc_text">
Chris Lattner	37b6b09	2005-04-25 17:34:15 +0000	[diff] [blame]	1145
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1146	<h5>Overview:</h5>
Chris Lattner	37b6b09	2005-04-25 17:34:15 +0000	[diff] [blame]	1147
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1148	<p>A vector type is a simple derived type that represents a vector
				1149	of elements. Vector types are used when multiple primitive data
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1150	are operated in parallel using a single instruction (SIMD).
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1151	A vector type requires a size (number of
Chris Lattner	330ce69	2005-11-10 01:44:22 +0000	[diff] [blame]	1152	elements) and an underlying primitive data type. Vectors must have a power
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1153	of two length (1, 2, 4, 8, 16 ...). Vector types are
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1154	considered <a href="#t_firstclass">first class</a>.</p>
Chris Lattner	37b6b09	2005-04-25 17:34:15 +0000	[diff] [blame]	1155
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1156	<h5>Syntax:</h5>
Chris Lattner	37b6b09	2005-04-25 17:34:15 +0000	[diff] [blame]	1157
				1158	<pre>
				1159	< <# elements> x <elementtype> >
				1160	</pre>
				1161
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	1162	<p>The number of elements is a constant integer value; elementtype may
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	1163	be any integer or floating point type.</p>
Chris Lattner	37b6b09	2005-04-25 17:34:15 +0000	[diff] [blame]	1164
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1165	<h5>Examples:</h5>
Chris Lattner	37b6b09	2005-04-25 17:34:15 +0000	[diff] [blame]	1166
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1167	<table class="layout">
				1168	<tr class="layout">
				1169	<td class="left">
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1170	<tt><4 x i32></tt><br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1171	<tt><8 x float></tt><br/>
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	1172	<tt><2 x i64></tt><br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1173	</td>
				1174	<td class="left">
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1175	Vector of 4 32-bit integer values.<br/>
				1176	Vector of 8 floating-point values.<br/>
				1177	Vector of 2 64-bit integer values.<br/>
Reid Spencer	c3c4c4f	2004-11-01 08:19:36 +0000	[diff] [blame]	1178	</td>
				1179	</tr>
				1180	</table>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1181	</div>
				1182
Chris Lattner	37b6b09	2005-04-25 17:34:15 +0000	[diff] [blame]	1183	<!-- _______________________________________________________________________ -->
				1184	<div class="doc_subsubsection"> <a name="t_opaque">Opaque Type</a> </div>
				1185	<div class="doc_text">
				1186
				1187	<h5>Overview:</h5>
				1188
				1189	<p>Opaque types are used to represent unknown types in the system. This
				1190	corresponds (for example) to the C notion of a foward declared structure type.
				1191	In LLVM, opaque types can eventually be resolved to any type (not just a
				1192	structure type).</p>
				1193
				1194	<h5>Syntax:</h5>
				1195
				1196	<pre>
				1197	opaque
				1198	</pre>
				1199
				1200	<h5>Examples:</h5>
				1201
				1202	<table class="layout">
				1203	<tr class="layout">
				1204	<td class="left">
				1205	<tt>opaque</tt>
				1206	</td>
				1207	<td class="left">
				1208	An opaque type.<br/>
				1209	</td>
				1210	</tr>
				1211	</table>
				1212	</div>
				1213
				1214
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1215	<!-- *********************************************************************** -->
				1216	<div class="doc_section"> <a name="constants">Constants</a> </div>
				1217	<!-- *********************************************************************** -->
				1218
				1219	<div class="doc_text">
				1220
				1221	<p>LLVM has several different basic types of constants. This section describes
				1222	them all and their syntax.</p>
				1223
				1224	</div>
				1225
				1226	<!-- ======================================================================= -->
Reid Spencer	8f08d80	2004-12-09 18:02:53 +0000	[diff] [blame]	1227	<div class="doc_subsection"><a name="simpleconstants">Simple Constants</a></div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1228
				1229	<div class="doc_text">
				1230
				1231	<dl>
				1232	<dt><b>Boolean constants</b></dt>
				1233
				1234	<dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	1235	constants of the <tt><a href="#t_primitive">i1</a></tt> type.
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1236	</dd>
				1237
				1238	<dt><b>Integer constants</b></dt>
				1239
Reid Spencer	8f08d80	2004-12-09 18:02:53 +0000	[diff] [blame]	1240	<dd>Standard integers (such as '4') are constants of the <a
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	1241	href="#t_integer">integer</a> type. Negative numbers may be used with
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1242	integer types.
				1243	</dd>
				1244
				1245	<dt><b>Floating point constants</b></dt>
				1246
				1247	<dd>Floating point constants use standard decimal notation (e.g. 123.421),
				1248	exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1249	notation (see below). Floating point constants must have a <a
				1250	href="#t_floating">floating point</a> type. </dd>
				1251
				1252	<dt><b>Null pointer constants</b></dt>
				1253
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	1254	<dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1255	and must be of <a href="#t_pointer">pointer type</a>.</dd>
				1256
				1257	</dl>
				1258
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	1259	<p>The one non-intuitive notation for constants is the optional hexadecimal form
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1260	of floating point constants. For example, the form '<tt>double
				1261	0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
				1262	4.5e+15</tt>'. The only time hexadecimal floating point constants are required
Reid Spencer	8f08d80	2004-12-09 18:02:53 +0000	[diff] [blame]	1263	(and the only time that they are generated by the disassembler) is when a
				1264	floating point constant must be emitted but it cannot be represented as a
				1265	decimal floating point number. For example, NaN's, infinities, and other
				1266	special values are represented in their IEEE hexadecimal format so that
				1267	assembly and disassembly do not cause any bits to change in the constants.</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1268
				1269	</div>
				1270
				1271	<!-- ======================================================================= -->
				1272	<div class="doc_subsection"><a name="aggregateconstants">Aggregate Constants</a>
				1273	</div>
				1274
				1275	<div class="doc_text">
Chris Lattner	455fc8c	2005-03-07 22:13:59 +0000	[diff] [blame]	1276	<p>Aggregate constants arise from aggregation of simple constants
				1277	and smaller aggregate constants.</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1278
				1279	<dl>
				1280	<dt><b>Structure constants</b></dt>
				1281
				1282	<dd>Structure constants are represented with notation similar to structure
				1283	type definitions (a comma separated list of elements, surrounded by braces
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1284	(<tt>{}</tt>)). For example: "<tt>{ i32 4, float 17.0, i32* %G }</tt>",
				1285	where "<tt>%G</tt>" is declared as "<tt>%G = external global i32</tt>". Structure constants
Chris Lattner	455fc8c	2005-03-07 22:13:59 +0000	[diff] [blame]	1286	must have <a href="#t_struct">structure type</a>, and the number and
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1287	types of elements must match those specified by the type.
				1288	</dd>
				1289
				1290	<dt><b>Array constants</b></dt>
				1291
				1292	<dd>Array constants are represented with notation similar to array type
				1293	definitions (a comma separated list of elements, surrounded by square brackets
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1294	(<tt>[]</tt>)). For example: "<tt>[ i32 42, i32 11, i32 74 ]</tt>". Array
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1295	constants must have <a href="#t_array">array type</a>, and the number and
				1296	types of elements must match those specified by the type.
				1297	</dd>
				1298
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1299	<dt><b>Vector constants</b></dt>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1300
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1301	<dd>Vector constants are represented with notation similar to vector type
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1302	definitions (a comma separated list of elements, surrounded by
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1303	less-than/greater-than's (<tt><></tt>)). For example: "<tt>< i32 42,
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1304	i32 11, i32 74, i32 100 ></tt>". VEctor constants must have <a
				1305	href="#t_vector">vector type</a>, and the number and types of elements must
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1306	match those specified by the type.
				1307	</dd>
				1308
				1309	<dt><b>Zero initialization</b></dt>
				1310
				1311	<dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
				1312	value to zero of <em>any</em> type, including scalar and aggregate types.
				1313	This is often used to avoid having to print large zero initializers (e.g. for
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	1314	large arrays) and is always exactly equivalent to using explicit zero
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1315	initializers.
				1316	</dd>
				1317	</dl>
				1318
				1319	</div>
				1320
				1321	<!-- ======================================================================= -->
				1322	<div class="doc_subsection">
				1323	<a name="globalconstants">Global Variable and Function Addresses</a>
				1324	</div>
				1325
				1326	<div class="doc_text">
				1327
				1328	<p>The addresses of <a href="#globalvars">global variables</a> and <a
				1329	href="#functionstructure">functions</a> are always implicitly valid (link-time)
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	1330	constants. These constants are explicitly referenced when the <a
				1331	href="#identifiers">identifier for the global</a> is used and always have <a
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1332	href="#t_pointer">pointer</a> type. For example, the following is a legal LLVM
				1333	file:</p>
				1334
				1335	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1336	%X = global i32 17
				1337	%Y = global i32 42
				1338	%Z = global [2 x i32] [ i32 %X, i32* %Y ]
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1339	</pre>
				1340
				1341	</div>
				1342
				1343	<!-- ======================================================================= -->
Reid Spencer	641f5c9	2004-12-09 18:13:12 +0000	[diff] [blame]	1344	<div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1345	<div class="doc_text">
Reid Spencer	641f5c9	2004-12-09 18:13:12 +0000	[diff] [blame]	1346	<p>The string '<tt>undef</tt>' is recognized as a type-less constant that has
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	1347	no specific value. Undefined values may be of any type and be used anywhere
Reid Spencer	641f5c9	2004-12-09 18:13:12 +0000	[diff] [blame]	1348	a constant is permitted.</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1349
Reid Spencer	641f5c9	2004-12-09 18:13:12 +0000	[diff] [blame]	1350	<p>Undefined values indicate to the compiler that the program is well defined
				1351	no matter what value is used, giving the compiler more freedom to optimize.
				1352	</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1353	</div>
				1354
				1355	<!-- ======================================================================= -->
				1356	<div class="doc_subsection"><a name="constantexprs">Constant Expressions</a>
				1357	</div>
				1358
				1359	<div class="doc_text">
				1360
				1361	<p>Constant expressions are used to allow expressions involving other constants
				1362	to be used as constants. Constant expressions may be of any <a
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	1363	href="#t_firstclass">first class</a> type and may involve any LLVM operation
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1364	that does not have side effects (e.g. load and call are not supported). The
				1365	following is the syntax for constant expressions:</p>
				1366
				1367	<dl>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1368	<dt><b><tt>trunc ( CST to TYPE )</tt></b></dt>
				1369	<dd>Truncate a constant to another type. The bit size of CST must be larger
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	1370	than the bit size of TYPE. Both types must be integers.</dd>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1371
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1372	<dt><b><tt>zext ( CST to TYPE )</tt></b></dt>
				1373	<dd>Zero extend a constant to another type. The bit size of CST must be
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	1374	smaller or equal to the bit size of TYPE. Both types must be integers.</dd>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1375
				1376	<dt><b><tt>sext ( CST to TYPE )</tt></b></dt>
				1377	<dd>Sign extend a constant to another type. The bit size of CST must be
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	1378	smaller or equal to the bit size of TYPE. Both types must be integers.</dd>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1379
				1380	<dt><b><tt>fptrunc ( CST to TYPE )</tt></b></dt>
				1381	<dd>Truncate a floating point constant to another floating point type. The
				1382	size of CST must be larger than the size of TYPE. Both types must be
				1383	floating point.</dd>
				1384
				1385	<dt><b><tt>fpext ( CST to TYPE )</tt></b></dt>
				1386	<dd>Floating point extend a constant to another type. The size of CST must be
				1387	smaller or equal to the size of TYPE. Both types must be floating point.</dd>
				1388
				1389	<dt><b><tt>fp2uint ( CST to TYPE )</tt></b></dt>
				1390	<dd>Convert a floating point constant to the corresponding unsigned integer
				1391	constant. TYPE must be an integer type. CST must be floating point. If the
				1392	value won't fit in the integer type, the results are undefined.</dd>
				1393
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	1394	<dt><b><tt>fptosi ( CST to TYPE )</tt></b></dt>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1395	<dd>Convert a floating point constant to the corresponding signed integer
				1396	constant. TYPE must be an integer type. CST must be floating point. If the
				1397	value won't fit in the integer type, the results are undefined.</dd>
				1398
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	1399	<dt><b><tt>uitofp ( CST to TYPE )</tt></b></dt>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1400	<dd>Convert an unsigned integer constant to the corresponding floating point
				1401	constant. TYPE must be floating point. CST must be of integer type. If the
				1402	value won't fit in the floating point type, the results are undefined.</dd>
				1403
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	1404	<dt><b><tt>sitofp ( CST to TYPE )</tt></b></dt>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1405	<dd>Convert a signed integer constant to the corresponding floating point
				1406	constant. TYPE must be floating point. CST must be of integer type. If the
				1407	value won't fit in the floating point type, the results are undefined.</dd>
				1408
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	1409	<dt><b><tt>ptrtoint ( CST to TYPE )</tt></b></dt>
				1410	<dd>Convert a pointer typed constant to the corresponding integer constant
				1411	TYPE must be an integer type. CST must be of pointer type. The CST value is
				1412	zero extended, truncated, or unchanged to make it fit in TYPE.</dd>
				1413
				1414	<dt><b><tt>inttoptr ( CST to TYPE )</tt></b></dt>
				1415	<dd>Convert a integer constant to a pointer constant. TYPE must be a
				1416	pointer type. CST must be of integer type. The CST value is zero extended,
				1417	truncated, or unchanged to make it fit in a pointer size. This one is
				1418	<i>really</i> dangerous!</dd>
				1419
				1420	<dt><b><tt>bitcast ( CST to TYPE )</tt></b></dt>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1421	<dd>Convert a constant, CST, to another TYPE. The size of CST and TYPE must be
				1422	identical (same number of bits). The conversion is done as if the CST value
				1423	was stored to memory and read back as TYPE. In other words, no bits change
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	1424	with this operator, just the type. This can be used for conversion of
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1425	vector types to any other type, as long as they have the same bit width. For
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	1426	pointers it is only valid to cast to another pointer type.
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	1427	</dd>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1428
				1429	<dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
				1430
				1431	<dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
				1432	constants. As with the <a href="#i_getelementptr">getelementptr</a>
				1433	instruction, the index list may have zero or more indexes, which are required
				1434	to make sense for the type of "CSTPTR".</dd>
				1435
Robert Bocchino	7e97a6d	2006-01-10 19:31:34 +0000	[diff] [blame]	1436	<dt><b><tt>select ( COND, VAL1, VAL2 )</tt></b></dt>
				1437
				1438	<dd>Perform the <a href="#i_select">select operation</a> on
Reid Spencer	9965ee7	2006-12-04 19:23:19 +0000	[diff] [blame]	1439	constants.</dd>
				1440
				1441	<dt><b><tt>icmp COND ( VAL1, VAL2 )</tt></b></dt>
				1442	<dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
				1443
				1444	<dt><b><tt>fcmp COND ( VAL1, VAL2 )</tt></b></dt>
				1445	<dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
Robert Bocchino	7e97a6d	2006-01-10 19:31:34 +0000	[diff] [blame]	1446
				1447	<dt><b><tt>extractelement ( VAL, IDX )</tt></b></dt>
				1448
				1449	<dd>Perform the <a href="#i_extractelement">extractelement
				1450	operation</a> on constants.
				1451
Robert Bocchino	f72fdfe	2006-01-15 20:48:27 +0000	[diff] [blame]	1452	<dt><b><tt>insertelement ( VAL, ELT, IDX )</tt></b></dt>
				1453
				1454	<dd>Perform the <a href="#i_insertelement">insertelement
Reid Spencer	9965ee7	2006-12-04 19:23:19 +0000	[diff] [blame]	1455	operation</a> on constants.</dd>
Robert Bocchino	f72fdfe	2006-01-15 20:48:27 +0000	[diff] [blame]	1456
Chris Lattner	016a0e5	2006-04-08 00:13:41 +0000	[diff] [blame]	1457
				1458	<dt><b><tt>shufflevector ( VEC1, VEC2, IDXMASK )</tt></b></dt>
				1459
				1460	<dd>Perform the <a href="#i_shufflevector">shufflevector
Reid Spencer	9965ee7	2006-12-04 19:23:19 +0000	[diff] [blame]	1461	operation</a> on constants.</dd>
Chris Lattner	016a0e5	2006-04-08 00:13:41 +0000	[diff] [blame]	1462
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1463	<dt><b><tt>OPCODE ( LHS, RHS )</tt></b></dt>
				1464
Reid Spencer	641f5c9	2004-12-09 18:13:12 +0000	[diff] [blame]	1465	<dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
				1466	be any of the <a href="#binaryops">binary</a> or <a href="#bitwiseops">bitwise
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1467	binary</a> operations. The constraints on operands are the same as those for
				1468	the corresponding instruction (e.g. no bitwise operations on floating point
John Criswell	02fdc6f	2005-05-12 16:52:32 +0000	[diff] [blame]	1469	values are allowed).</dd>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1470	</dl>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1471	</div>
Chris Lattner	b165261	2004-03-08 16:49:10 +0000	[diff] [blame]	1472
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1473	<!-- *********************************************************************** -->
Chris Lattner	98f013c	2006-01-25 23:47:57 +0000	[diff] [blame]	1474	<div class="doc_section"> <a name="othervalues">Other Values</a> </div>
				1475	<!-- *********************************************************************** -->
				1476
				1477	<!-- ======================================================================= -->
				1478	<div class="doc_subsection">
				1479	<a name="inlineasm">Inline Assembler Expressions</a>
				1480	</div>
				1481
				1482	<div class="doc_text">
				1483
				1484	<p>
				1485	LLVM supports inline assembler expressions (as opposed to <a href="#moduleasm">
				1486	Module-Level Inline Assembly</a>) through the use of a special value. This
				1487	value represents the inline assembler as a string (containing the instructions
				1488	to emit), a list of operand constraints (stored as a string), and a flag that
				1489	indicates whether or not the inline asm expression has side effects. An example
				1490	inline assembler expression is:
				1491	</p>
				1492
				1493	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1494	i32 (i32) asm "bswap $0", "=r,r"
Chris Lattner	98f013c	2006-01-25 23:47:57 +0000	[diff] [blame]	1495	</pre>
				1496
				1497	<p>
				1498	Inline assembler expressions may <b>only</b> be used as the callee operand of
				1499	a <a href="#i_call"><tt>call</tt> instruction</a>. Thus, typically we have:
				1500	</p>
				1501
				1502	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1503	%X = call i32 asm "<a href="#i_bswap">bswap</a> $0", "=r,r"(i32 %Y)
Chris Lattner	98f013c	2006-01-25 23:47:57 +0000	[diff] [blame]	1504	</pre>
				1505
				1506	<p>
				1507	Inline asms with side effects not visible in the constraint list must be marked
				1508	as having side effects. This is done through the use of the
				1509	'<tt>sideeffect</tt>' keyword, like so:
				1510	</p>
				1511
				1512	<pre>
				1513	call void asm sideeffect "eieio", ""()
				1514	</pre>
				1515
				1516	<p>TODO: The format of the asm and constraints string still need to be
				1517	documented here. Constraints on what can be done (e.g. duplication, moving, etc
				1518	need to be documented).
				1519	</p>
				1520
				1521	</div>
				1522
				1523	<!-- *********************************************************************** -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1524	<div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
				1525	<!-- *********************************************************************** -->
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1526
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1527	<div class="doc_text">
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1528
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1529	<p>The LLVM instruction set consists of several different
				1530	classifications of instructions: <a href="#terminators">terminator
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	1531	instructions</a>, <a href="#binaryops">binary instructions</a>,
				1532	<a href="#bitwiseops">bitwise binary instructions</a>, <a
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1533	href="#memoryops">memory instructions</a>, and <a href="#otherops">other
				1534	instructions</a>.</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1535
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1536	</div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1537
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1538	<!-- ======================================================================= -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1539	<div class="doc_subsection"> <a name="terminators">Terminator
				1540	Instructions</a> </div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1541
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1542	<div class="doc_text">
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1543
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1544	<p>As mentioned <a href="#functionstructure">previously</a>, every
				1545	basic block in a program ends with a "Terminator" instruction, which
				1546	indicates which block should be executed after the current block is
				1547	finished. These terminator instructions typically yield a '<tt>void</tt>'
				1548	value: they produce control flow, not values (the one exception being
				1549	the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction).</p>
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	1550	<p>There are six different terminator instructions: the '<a
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1551	href="#i_ret"><tt>ret</tt></a>' instruction, the '<a href="#i_br"><tt>br</tt></a>'
				1552	instruction, the '<a href="#i_switch"><tt>switch</tt></a>' instruction,
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1553	the '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the '<a
				1554	href="#i_unwind"><tt>unwind</tt></a>' instruction, and the '<a
				1555	href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1556
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1557	</div>
Chris Lattner	74d3f82	2004-12-09 17:30:23 +0000	[diff] [blame]	1558
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1559	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1560	<div class="doc_subsubsection"> <a name="i_ret">'<tt>ret</tt>'
				1561	Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1562	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1563	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1564	<pre> ret <type> <value> <i>; Return a value from a non-void function</i>
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	1565	ret void <i>; Return from void function</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1566	</pre>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1567	<h5>Overview:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1568	<p>The '<tt>ret</tt>' instruction is used to return control flow (and a
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	1569	value) from a function back to the caller.</p>
John Criswell	417228d	2004-04-09 16:48:45 +0000	[diff] [blame]	1570	<p>There are two forms of the '<tt>ret</tt>' instruction: one that
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1571	returns a value and then causes control flow, and one that just causes
				1572	control flow to occur.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1573	<h5>Arguments:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1574	<p>The '<tt>ret</tt>' instruction may return any '<a
				1575	href="#t_firstclass">first class</a>' type. Notice that a function is
				1576	not <a href="#wellformed">well formed</a> if there exists a '<tt>ret</tt>'
				1577	instruction inside of the function that returns a value that does not
				1578	match the return type of the function.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1579	<h5>Semantics:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1580	<p>When the '<tt>ret</tt>' instruction is executed, control flow
				1581	returns back to the calling function's context. If the caller is a "<a
John Criswell	40db33f	2004-06-25 15:16:57 +0000	[diff] [blame]	1582	href="#i_call"><tt>call</tt></a>" instruction, execution continues at
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1583	the instruction after the call. If the caller was an "<a
				1584	href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues
John Criswell	02fdc6f	2005-05-12 16:52:32 +0000	[diff] [blame]	1585	at the beginning of the "normal" destination block. If the instruction
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1586	returns a value, that value shall set the call or invoke instruction's
				1587	return value.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1588	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1589	<pre> ret i32 5 <i>; Return an integer value of 5</i>
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	1590	ret void <i>; Return from a void function</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1591	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1592	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1593	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1594	<div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1595	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1596	<h5>Syntax:</h5>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	1597	<pre> br i1 <cond>, label <iftrue>, label <iffalse><br> br label <dest> <i>; Unconditional branch</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1598	</pre>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1599	<h5>Overview:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1600	<p>The '<tt>br</tt>' instruction is used to cause control flow to
				1601	transfer to a different basic block in the current function. There are
				1602	two forms of this instruction, corresponding to a conditional branch
				1603	and an unconditional branch.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1604	<h5>Arguments:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1605	<p>The conditional branch form of the '<tt>br</tt>' instruction takes a
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	1606	single '<tt>i1</tt>' value and two '<tt>label</tt>' values. The
Reid Spencer	50c723a	2007-02-19 23:54:10 +0000	[diff] [blame^]	1607	unconditional form of the '<tt>br</tt>' instruction takes a single
				1608	'<tt>label</tt>' value as a target.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1609	<h5>Semantics:</h5>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	1610	<p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</tt>'
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1611	argument is evaluated. If the value is <tt>true</tt>, control flows
				1612	to the '<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>,
				1613	control flows to the '<tt>iffalse</tt>' <tt>label</tt> argument.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1614	<h5>Example:</h5>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	1615	<pre>Test:<br> %cond = <a href="#i_icmp">icmp</a> eq, i32 %a, %b<br> br i1 %cond, label %IfEqual, label %IfUnequal<br>IfEqual:<br> <a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1616	href="#i_ret">ret</a> i32 1<br>IfUnequal:<br> <a href="#i_ret">ret</a> i32 0<br></pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1617	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1618	<!-- _______________________________________________________________________ -->
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1619	<div class="doc_subsubsection">
				1620	<a name="i_switch">'<tt>switch</tt>' Instruction</a>
				1621	</div>
				1622
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1623	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1624	<h5>Syntax:</h5>
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1625
				1626	<pre>
				1627	switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
				1628	</pre>
				1629
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1630	<h5>Overview:</h5>
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1631
				1632	<p>The '<tt>switch</tt>' instruction is used to transfer control flow to one of
				1633	several different places. It is a generalization of the '<tt>br</tt>'
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1634	instruction, allowing a branch to occur to one of many possible
				1635	destinations.</p>
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1636
				1637
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1638	<h5>Arguments:</h5>
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1639
				1640	<p>The '<tt>switch</tt>' instruction uses three parameters: an integer
				1641	comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
				1642	an array of pairs of comparison value constants and '<tt>label</tt>'s. The
				1643	table is not allowed to contain duplicate constant entries.</p>
				1644
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1645	<h5>Semantics:</h5>
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1646
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1647	<p>The <tt>switch</tt> instruction specifies a table of values and
				1648	destinations. When the '<tt>switch</tt>' instruction is executed, this
John Criswell	bcbb18c	2004-06-25 16:05:06 +0000	[diff] [blame]	1649	table is searched for the given value. If the value is found, control flow is
				1650	transfered to the corresponding destination; otherwise, control flow is
				1651	transfered to the default destination.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1652
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1653	<h5>Implementation:</h5>
				1654
				1655	<p>Depending on properties of the target machine and the particular
				1656	<tt>switch</tt> instruction, this instruction may be code generated in different
John Criswell	bcbb18c	2004-06-25 16:05:06 +0000	[diff] [blame]	1657	ways. For example, it could be generated as a series of chained conditional
				1658	branches or with a lookup table.</p>
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1659
				1660	<h5>Example:</h5>
				1661
				1662	<pre>
				1663	<i>; Emulate a conditional br instruction</i>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	1664	%Val = <a href="#i_zext">zext</a> i1 %value to i32
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1665	switch i32 %Val, label %truedest [i32 0, label %falsedest ]
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1666
				1667	<i>; Emulate an unconditional br instruction</i>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1668	switch i32 0, label %dest [ ]
Chris Lattner	cf96c6c	2004-02-24 04:54:45 +0000	[diff] [blame]	1669
				1670	<i>; Implement a jump table:</i>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1671	switch i32 %val, label %otherwise [ i32 0, label %onzero
				1672	i32 1, label %onone
				1673	i32 2, label %ontwo ]
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1674	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1675	</div>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1676
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1677	<!-- _______________________________________________________________________ -->
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1678	<div class="doc_subsubsection">
				1679	<a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
				1680	</div>
				1681
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1682	<div class="doc_text">
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1683
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1684	<h5>Syntax:</h5>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1685
				1686	<pre>
				1687	<result> = invoke [<a href="#callingconv">cconv</a>] <ptr to function ty> %<function ptr val>(<function args>)
Chris Lattner	6b7a008	2006-05-14 18:23:06 +0000	[diff] [blame]	1688	to label <normal label> unwind label <exception label>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1689	</pre>
				1690
Chris Lattner	a8292f3	2002-05-06 22:08:29 +0000	[diff] [blame]	1691	<h5>Overview:</h5>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1692
				1693	<p>The '<tt>invoke</tt>' instruction causes control to transfer to a specified
				1694	function, with the possibility of control flow transfer to either the
John Criswell	02fdc6f	2005-05-12 16:52:32 +0000	[diff] [blame]	1695	'<tt>normal</tt>' label or the
				1696	'<tt>exception</tt>' label. If the callee function returns with the
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1697	"<tt><a href="#i_ret">ret</a></tt>" instruction, control flow will return to the
				1698	"normal" label. If the callee (or any indirect callees) returns with the "<a
John Criswell	02fdc6f	2005-05-12 16:52:32 +0000	[diff] [blame]	1699	href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted and
				1700	continued at the dynamically nearest "exception" label.</p>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1701
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1702	<h5>Arguments:</h5>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1703
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1704	<p>This instruction requires several arguments:</p>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1705
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1706	<ol>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1707	<li>
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	1708	The optional "cconv" marker indicates which <a href="callingconv">calling
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1709	convention</a> the call should use. If none is specified, the call defaults
				1710	to using C calling conventions.
				1711	</li>
				1712	<li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
				1713	function value being invoked. In most cases, this is a direct function
				1714	invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
				1715	an arbitrary pointer to function value.
				1716	</li>
				1717
				1718	<li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
				1719	function to be invoked. </li>
				1720
				1721	<li>'<tt>function args</tt>': argument list whose types match the function
				1722	signature argument types. If the function signature indicates the function
				1723	accepts a variable number of arguments, the extra arguments can be
				1724	specified. </li>
				1725
				1726	<li>'<tt>normal label</tt>': the label reached when the called function
				1727	executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
				1728
				1729	<li>'<tt>exception label</tt>': the label reached when a callee returns with
				1730	the <a href="#i_unwind"><tt>unwind</tt></a> instruction. </li>
				1731
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1732	</ol>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1733
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1734	<h5>Semantics:</h5>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1735
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1736	<p>This instruction is designed to operate as a standard '<tt><a
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1737	href="#i_call">call</a></tt>' instruction in most regards. The primary
				1738	difference is that it establishes an association with a label, which is used by
				1739	the runtime library to unwind the stack.</p>
				1740
				1741	<p>This instruction is used in languages with destructors to ensure that proper
				1742	cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
				1743	exception. Additionally, this is important for implementation of
				1744	'<tt>catch</tt>' clauses in high-level languages that support them.</p>
				1745
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1746	<h5>Example:</h5>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	1747	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1748	%retval = invoke i32 %Test(i32 15) to label %Continue
				1749	unwind label %TestCleanup <i>; {i32}:retval set</i>
				1750	%retval = invoke <a href="#callingconv">coldcc</a> i32 %Test(i32 15) to label %Continue
				1751	unwind label %TestCleanup <i>; {i32}:retval set</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1752	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1753	</div>
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1754
				1755
Chris Lattner	5ed6061	2003-09-03 00:41:47 +0000	[diff] [blame]	1756	<!-- _______________________________________________________________________ -->
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1757
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1758	<div class="doc_subsubsection"> <a name="i_unwind">'<tt>unwind</tt>'
				1759	Instruction</a> </div>
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1760
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1761	<div class="doc_text">
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1762
Chris Lattner	5ed6061	2003-09-03 00:41:47 +0000	[diff] [blame]	1763	<h5>Syntax:</h5>
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1764	<pre>
				1765	unwind
				1766	</pre>
				1767
Chris Lattner	5ed6061	2003-09-03 00:41:47 +0000	[diff] [blame]	1768	<h5>Overview:</h5>
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1769
				1770	<p>The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow
				1771	at the first callee in the dynamic call stack which used an <a
				1772	href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is
				1773	primarily used to implement exception handling.</p>
				1774
Chris Lattner	5ed6061	2003-09-03 00:41:47 +0000	[diff] [blame]	1775	<h5>Semantics:</h5>
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1776
				1777	<p>The '<tt>unwind</tt>' intrinsic causes execution of the current function to
				1778	immediately halt. The dynamic call stack is then searched for the first <a
				1779	href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found,
				1780	execution continues at the "exceptional" destination block specified by the
				1781	<tt>invoke</tt> instruction. If there is no <tt>invoke</tt> instruction in the
				1782	dynamic call chain, undefined behavior results.</p>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1783	</div>
Chris Lattner	08b7d5b	2004-10-16 18:04:13 +0000	[diff] [blame]	1784
				1785	<!-- _______________________________________________________________________ -->
				1786
				1787	<div class="doc_subsubsection"> <a name="i_unreachable">'<tt>unreachable</tt>'
				1788	Instruction</a> </div>
				1789
				1790	<div class="doc_text">
				1791
				1792	<h5>Syntax:</h5>
				1793	<pre>
				1794	unreachable
				1795	</pre>
				1796
				1797	<h5>Overview:</h5>
				1798
				1799	<p>The '<tt>unreachable</tt>' instruction has no defined semantics. This
				1800	instruction is used to inform the optimizer that a particular portion of the
				1801	code is not reachable. This can be used to indicate that the code after a
				1802	no-return function cannot be reached, and other facts.</p>
				1803
				1804	<h5>Semantics:</h5>
				1805
				1806	<p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
				1807	</div>
				1808
				1809
				1810
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1811	<!-- ======================================================================= -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1812	<div class="doc_subsection"> <a name="binaryops">Binary Operations</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1813	<div class="doc_text">
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1814	<p>Binary operators are used to do most of the computation in a
				1815	program. They require two operands, execute an operation on them, and
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	1816	produce a single value. The operands might represent
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1817	multiple data, as is the case with the <a href="#t_vector">vector</a> data type.
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1818	The result value of a binary operator is not
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1819	necessarily the same type as its operands.</p>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1820	<p>There are several different binary operators:</p>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1821	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1822	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1823	<div class="doc_subsubsection"> <a name="i_add">'<tt>add</tt>'
				1824	Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1825	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1826	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1827	<pre> <result> = add <ty> <var1>, <var2> <i>; yields {ty}:result</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1828	</pre>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1829	<h5>Overview:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1830	<p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1831	<h5>Arguments:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1832	<p>The two arguments to the '<tt>add</tt>' instruction must be either <a
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1833	href="#t_integer">integer</a> or <a href="#t_floating">floating point</a> values.
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1834	This instruction can also take <a href="#t_vector">vector</a> versions of the values.
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1835	Both arguments must have identical types.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1836	<h5>Semantics:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1837	<p>The value produced is the integer or floating point sum of the two
				1838	operands.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1839	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1840	<pre> <result> = add i32 4, %var <i>; yields {i32}:result = 4 + %var</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1841	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1842	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1843	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1844	<div class="doc_subsubsection"> <a name="i_sub">'<tt>sub</tt>'
				1845	Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1846	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1847	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1848	<pre> <result> = sub <ty> <var1>, <var2> <i>; yields {ty}:result</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1849	</pre>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1850	<h5>Overview:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1851	<p>The '<tt>sub</tt>' instruction returns the difference of its two
				1852	operands.</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1853	<p>Note that the '<tt>sub</tt>' instruction is used to represent the '<tt>neg</tt>'
				1854	instruction present in most other intermediate representations.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1855	<h5>Arguments:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1856	<p>The two arguments to the '<tt>sub</tt>' instruction must be either <a
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1857	href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1858	values.
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1859	This instruction can also take <a href="#t_vector">vector</a> versions of the values.
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1860	Both arguments must have identical types.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1861	<h5>Semantics:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1862	<p>The value produced is the integer or floating point difference of
				1863	the two operands.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1864	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1865	<pre> <result> = sub i32 4, %var <i>; yields {i32}:result = 4 - %var</i>
				1866	<result> = sub i32 0, %val <i>; yields {i32}:result = -%var</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1867	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1868	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1869	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1870	<div class="doc_subsubsection"> <a name="i_mul">'<tt>mul</tt>'
				1871	Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1872	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1873	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1874	<pre> <result> = mul <ty> <var1>, <var2> <i>; yields {ty}:result</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1875	</pre>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1876	<h5>Overview:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1877	<p>The '<tt>mul</tt>' instruction returns the product of its two
				1878	operands.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1879	<h5>Arguments:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1880	<p>The two arguments to the '<tt>mul</tt>' instruction must be either <a
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1881	href="#t_integer">integer</a> or <a href="#t_floating">floating point</a>
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1882	values.
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1883	This instruction can also take <a href="#t_vector">vector</a> versions of the values.
Chris Lattner	c8cb695	2004-08-12 19:12:28 +0000	[diff] [blame]	1884	Both arguments must have identical types.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1885	<h5>Semantics:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1886	<p>The value produced is the integer or floating point product of the
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1887	two operands.</p>
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	1888	<p>Because the operands are the same width, the result of an integer
				1889	multiplication is the same whether the operands should be deemed unsigned or
				1890	signed.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1891	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1892	<pre> <result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1893	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1894	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1895	<!-- _______________________________________________________________________ -->
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1896	<div class="doc_subsubsection"> <a name="i_udiv">'<tt>udiv</tt>' Instruction
				1897	</a></div>
				1898	<div class="doc_text">
				1899	<h5>Syntax:</h5>
				1900	<pre> <result> = udiv <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				1901	</pre>
				1902	<h5>Overview:</h5>
				1903	<p>The '<tt>udiv</tt>' instruction returns the quotient of its two
				1904	operands.</p>
				1905	<h5>Arguments:</h5>
				1906	<p>The two arguments to the '<tt>udiv</tt>' instruction must be
				1907	<a href="#t_integer">integer</a> values. Both arguments must have identical
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1908	types. This instruction can also take <a href="#t_vector">vector</a> versions
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1909	of the values in which case the elements must be integers.</p>
				1910	<h5>Semantics:</h5>
				1911	<p>The value produced is the unsigned integer quotient of the two operands. This
				1912	instruction always performs an unsigned division operation, regardless of
				1913	whether the arguments are unsigned or not.</p>
				1914	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1915	<pre> <result> = udiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1916	</pre>
				1917	</div>
				1918	<!-- _______________________________________________________________________ -->
				1919	<div class="doc_subsubsection"> <a name="i_sdiv">'<tt>sdiv</tt>' Instruction
				1920	</a> </div>
				1921	<div class="doc_text">
				1922	<h5>Syntax:</h5>
				1923	<pre> <result> = sdiv <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				1924	</pre>
				1925	<h5>Overview:</h5>
				1926	<p>The '<tt>sdiv</tt>' instruction returns the quotient of its two
				1927	operands.</p>
				1928	<h5>Arguments:</h5>
				1929	<p>The two arguments to the '<tt>sdiv</tt>' instruction must be
				1930	<a href="#t_integer">integer</a> values. Both arguments must have identical
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1931	types. This instruction can also take <a href="#t_vector">vector</a> versions
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1932	of the values in which case the elements must be integers.</p>
				1933	<h5>Semantics:</h5>
				1934	<p>The value produced is the signed integer quotient of the two operands. This
				1935	instruction always performs a signed division operation, regardless of whether
				1936	the arguments are signed or not.</p>
				1937	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1938	<pre> <result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1939	</pre>
				1940	</div>
				1941	<!-- _______________________________________________________________________ -->
				1942	<div class="doc_subsubsection"> <a name="i_fdiv">'<tt>fdiv</tt>'
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1943	Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	1944	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	1945	<h5>Syntax:</h5>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1946	<pre> <result> = fdiv <ty> <var1>, <var2> <i>; yields {ty}:result</i>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1947	</pre>
				1948	<h5>Overview:</h5>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1949	<p>The '<tt>fdiv</tt>' instruction returns the quotient of its two
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1950	operands.</p>
				1951	<h5>Arguments:</h5>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1952	<p>The two arguments to the '<tt>div</tt>' instruction must be
				1953	<a href="#t_floating">floating point</a> values. Both arguments must have
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	1954	identical types. This instruction can also take <a href="#t_vector">vector</a>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1955	versions of the values in which case the elements must be floating point.</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1956	<h5>Semantics:</h5>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1957	<p>The value produced is the floating point quotient of the two operands.</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1958	<h5>Example:</h5>
Reid Spencer	7e80b0b	2006-10-26 06:15:43 +0000	[diff] [blame]	1959	<pre> <result> = fdiv float 4.0, %var <i>; yields {float}:result = 4.0 / %var</i>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1960	</pre>
				1961	</div>
				1962	<!-- _______________________________________________________________________ -->
Reid Spencer	7eb55b3	2006-11-02 01:53:59 +0000	[diff] [blame]	1963	<div class="doc_subsubsection"> <a name="i_urem">'<tt>urem</tt>' Instruction</a>
				1964	</div>
				1965	<div class="doc_text">
				1966	<h5>Syntax:</h5>
				1967	<pre> <result> = urem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				1968	</pre>
				1969	<h5>Overview:</h5>
				1970	<p>The '<tt>urem</tt>' instruction returns the remainder from the
				1971	unsigned division of its two arguments.</p>
				1972	<h5>Arguments:</h5>
				1973	<p>The two arguments to the '<tt>urem</tt>' instruction must be
				1974	<a href="#t_integer">integer</a> values. Both arguments must have identical
				1975	types.</p>
				1976	<h5>Semantics:</h5>
				1977	<p>This instruction returns the unsigned integer <i>remainder</i> of a division.
				1978	This instruction always performs an unsigned division to get the remainder,
				1979	regardless of whether the arguments are unsigned or not.</p>
				1980	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	1981	<pre> <result> = urem i32 4, %var <i>; yields {i32}:result = 4 % %var</i>
Reid Spencer	7eb55b3	2006-11-02 01:53:59 +0000	[diff] [blame]	1982	</pre>
				1983
				1984	</div>
				1985	<!-- _______________________________________________________________________ -->
				1986	<div class="doc_subsubsection"> <a name="i_srem">'<tt>srem</tt>'
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1987	Instruction</a> </div>
				1988	<div class="doc_text">
				1989	<h5>Syntax:</h5>
Reid Spencer	7eb55b3	2006-11-02 01:53:59 +0000	[diff] [blame]	1990	<pre> <result> = srem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1991	</pre>
				1992	<h5>Overview:</h5>
Reid Spencer	7eb55b3	2006-11-02 01:53:59 +0000	[diff] [blame]	1993	<p>The '<tt>srem</tt>' instruction returns the remainder from the
				1994	signed division of its two operands.</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1995	<h5>Arguments:</h5>
Reid Spencer	7eb55b3	2006-11-02 01:53:59 +0000	[diff] [blame]	1996	<p>The two arguments to the '<tt>srem</tt>' instruction must be
				1997	<a href="#t_integer">integer</a> values. Both arguments must have identical
				1998	types.</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	1999	<h5>Semantics:</h5>
Reid Spencer	7eb55b3	2006-11-02 01:53:59 +0000	[diff] [blame]	2000	<p>This instruction returns the <i>remainder</i> of a division (where the result
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2001	has the same sign as the divisor), not the <i>modulus</i> (where the
				2002	result has the same sign as the dividend) of a value. For more
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	2003	information about the difference, see <a
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2004	href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
				2005	Math Forum</a>.</p>
				2006	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2007	<pre> <result> = srem i32 4, %var <i>; yields {i32}:result = 4 % %var</i>
Reid Spencer	7eb55b3	2006-11-02 01:53:59 +0000	[diff] [blame]	2008	</pre>
				2009
				2010	</div>
				2011	<!-- _______________________________________________________________________ -->
				2012	<div class="doc_subsubsection"> <a name="i_frem">'<tt>frem</tt>'
				2013	Instruction</a> </div>
				2014	<div class="doc_text">
				2015	<h5>Syntax:</h5>
				2016	<pre> <result> = frem <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				2017	</pre>
				2018	<h5>Overview:</h5>
				2019	<p>The '<tt>frem</tt>' instruction returns the remainder from the
				2020	division of its two operands.</p>
				2021	<h5>Arguments:</h5>
				2022	<p>The two arguments to the '<tt>frem</tt>' instruction must be
				2023	<a href="#t_floating">floating point</a> values. Both arguments must have
				2024	identical types.</p>
				2025	<h5>Semantics:</h5>
				2026	<p>This instruction returns the <i>remainder</i> of a division.</p>
				2027	<h5>Example:</h5>
				2028	<pre> <result> = frem float 4.0, %var <i>; yields {float}:result = 4.0 % %var</i>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2029	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2030	</div>
Robert Bocchino	820bc75b	2006-02-17 21:18:08 +0000	[diff] [blame]	2031
Reid Spencer	2ab0193	2007-02-02 13:57:07 +0000	[diff] [blame]	2032	<!-- ======================================================================= -->
				2033	<div class="doc_subsection"> <a name="bitwiseops">Bitwise Binary
				2034	Operations</a> </div>
				2035	<div class="doc_text">
				2036	<p>Bitwise binary operators are used to do various forms of
				2037	bit-twiddling in a program. They are generally very efficient
				2038	instructions and can commonly be strength reduced from other
				2039	instructions. They require two operands, execute an operation on them,
				2040	and produce a single value. The resulting value of the bitwise binary
				2041	operators is always the same type as its first operand.</p>
				2042	</div>
				2043
Reid Spencer	04e259b	2007-01-31 21:39:12 +0000	[diff] [blame]	2044	<!-- _______________________________________________________________________ -->
				2045	<div class="doc_subsubsection"> <a name="i_shl">'<tt>shl</tt>'
				2046	Instruction</a> </div>
				2047	<div class="doc_text">
				2048	<h5>Syntax:</h5>
				2049	<pre> <result> = shl <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				2050	</pre>
				2051	<h5>Overview:</h5>
				2052	<p>The '<tt>shl</tt>' instruction returns the first operand shifted to
				2053	the left a specified number of bits.</p>
				2054	<h5>Arguments:</h5>
				2055	<p>Both arguments to the '<tt>shl</tt>' instruction must be the same <a
				2056	href="#t_integer">integer</a> type.</p>
				2057	<h5>Semantics:</h5>
				2058	<p>The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.</p>
				2059	<h5>Example:</h5><pre>
				2060	<result> = shl i32 4, %var <i>; yields {i32}: 4 << %var</i>
				2061	<result> = shl i32 4, 2 <i>; yields {i32}: 16</i>
				2062	<result> = shl i32 1, 10 <i>; yields {i32}: 1024</i>
				2063	</pre>
				2064	</div>
				2065	<!-- _______________________________________________________________________ -->
				2066	<div class="doc_subsubsection"> <a name="i_lshr">'<tt>lshr</tt>'
				2067	Instruction</a> </div>
				2068	<div class="doc_text">
				2069	<h5>Syntax:</h5>
				2070	<pre> <result> = lshr <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				2071	</pre>
				2072
				2073	<h5>Overview:</h5>
				2074	<p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
				2075	operand shifted to the right a specified number of bits.</p>
				2076
				2077	<h5>Arguments:</h5>
				2078	<p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
				2079	<a href="#t_integer">integer</a> type.</p>
				2080
				2081	<h5>Semantics:</h5>
				2082	<p>This instruction always performs a logical shift right operation. The most
				2083	significant bits of the result will be filled with zero bits after the
				2084	shift.</p>
				2085
				2086	<h5>Example:</h5>
				2087	<pre>
				2088	<result> = lshr i32 4, 1 <i>; yields {i32}:result = 2</i>
				2089	<result> = lshr i32 4, 2 <i>; yields {i32}:result = 1</i>
				2090	<result> = lshr i8 4, 3 <i>; yields {i8}:result = 0</i>
				2091	<result> = lshr i8 -2, 1 <i>; yields {i8}:result = 0x7FFFFFFF </i>
				2092	</pre>
				2093	</div>
				2094
Reid Spencer	2ab0193	2007-02-02 13:57:07 +0000	[diff] [blame]	2095	<!-- _______________________________________________________________________ -->
Reid Spencer	04e259b	2007-01-31 21:39:12 +0000	[diff] [blame]	2096	<div class="doc_subsubsection"> <a name="i_ashr">'<tt>ashr</tt>'
				2097	Instruction</a> </div>
				2098	<div class="doc_text">
				2099
				2100	<h5>Syntax:</h5>
				2101	<pre> <result> = ashr <ty> <var1>, <var2> <i>; yields {ty}:result</i>
				2102	</pre>
				2103
				2104	<h5>Overview:</h5>
				2105	<p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
				2106	operand shifted to the right a specified number of bits.</p>
				2107
				2108	<h5>Arguments:</h5>
				2109	<p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
				2110	<a href="#t_integer">integer</a> type.</p>
				2111
				2112	<h5>Semantics:</h5>
				2113	<p>This instruction always performs an arithmetic shift right operation,
				2114	The most significant bits of the result will be filled with the sign bit
				2115	of <tt>var1</tt>.</p>
				2116
				2117	<h5>Example:</h5>
				2118	<pre>
				2119	<result> = ashr i32 4, 1 <i>; yields {i32}:result = 2</i>
				2120	<result> = ashr i32 4, 2 <i>; yields {i32}:result = 1</i>
				2121	<result> = ashr i8 4, 3 <i>; yields {i8}:result = 0</i>
				2122	<result> = ashr i8 -2, 1 <i>; yields {i8}:result = -1</i>
				2123	</pre>
				2124	</div>
				2125
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2126	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2127	<div class="doc_subsubsection"> <a name="i_and">'<tt>and</tt>'
				2128	Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2129	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2130	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2131	<pre> <result> = and <ty> <var1>, <var2> <i>; yields {ty}:result</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2132	</pre>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2133	<h5>Overview:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2134	<p>The '<tt>and</tt>' instruction returns the bitwise logical and of
				2135	its two operands.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2136	<h5>Arguments:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2137	<p>The two arguments to the '<tt>and</tt>' instruction must be <a
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	2138	href="#t_integer">integer</a> values. Both arguments must have
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2139	identical types.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2140	<h5>Semantics:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2141	<p>The truth table used for the '<tt>and</tt>' instruction is:</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2142	<p> </p>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	2143	<div style="align: center">
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2144	<table border="1" cellspacing="0" cellpadding="4">
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2145	<tbody>
				2146	<tr>
				2147	<td>In0</td>
				2148	<td>In1</td>
				2149	<td>Out</td>
				2150	</tr>
				2151	<tr>
				2152	<td>0</td>
				2153	<td>0</td>
				2154	<td>0</td>
				2155	</tr>
				2156	<tr>
				2157	<td>0</td>
				2158	<td>1</td>
				2159	<td>0</td>
				2160	</tr>
				2161	<tr>
				2162	<td>1</td>
				2163	<td>0</td>
				2164	<td>0</td>
				2165	</tr>
				2166	<tr>
				2167	<td>1</td>
				2168	<td>1</td>
				2169	<td>1</td>
				2170	</tr>
				2171	</tbody>
				2172	</table>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	2173	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2174	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2175	<pre> <result> = and i32 4, %var <i>; yields {i32}:result = 4 & %var</i>
				2176	<result> = and i32 15, 40 <i>; yields {i32}:result = 8</i>
				2177	<result> = and i32 4, 8 <i>; yields {i32}:result = 0</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2178	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2179	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2180	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2181	<div class="doc_subsubsection"> <a name="i_or">'<tt>or</tt>' Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2182	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2183	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2184	<pre> <result> = or <ty> <var1>, <var2> <i>; yields {ty}:result</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2185	</pre>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2186	<h5>Overview:</h5>
				2187	<p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive
				2188	or of its two operands.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2189	<h5>Arguments:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2190	<p>The two arguments to the '<tt>or</tt>' instruction must be <a
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	2191	href="#t_integer">integer</a> values. Both arguments must have
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2192	identical types.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2193	<h5>Semantics:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2194	<p>The truth table used for the '<tt>or</tt>' instruction is:</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2195	<p> </p>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	2196	<div style="align: center">
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2197	<table border="1" cellspacing="0" cellpadding="4">
				2198	<tbody>
				2199	<tr>
				2200	<td>In0</td>
				2201	<td>In1</td>
				2202	<td>Out</td>
				2203	</tr>
				2204	<tr>
				2205	<td>0</td>
				2206	<td>0</td>
				2207	<td>0</td>
				2208	</tr>
				2209	<tr>
				2210	<td>0</td>
				2211	<td>1</td>
				2212	<td>1</td>
				2213	</tr>
				2214	<tr>
				2215	<td>1</td>
				2216	<td>0</td>
				2217	<td>1</td>
				2218	</tr>
				2219	<tr>
				2220	<td>1</td>
				2221	<td>1</td>
				2222	<td>1</td>
				2223	</tr>
				2224	</tbody>
				2225	</table>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	2226	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2227	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2228	<pre> <result> = or i32 4, %var <i>; yields {i32}:result = 4 \| %var</i>
				2229	<result> = or i32 15, 40 <i>; yields {i32}:result = 47</i>
				2230	<result> = or i32 4, 8 <i>; yields {i32}:result = 12</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2231	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2232	</div>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2233	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2234	<div class="doc_subsubsection"> <a name="i_xor">'<tt>xor</tt>'
				2235	Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2236	<div class="doc_text">
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2237	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2238	<pre> <result> = xor <ty> <var1>, <var2> <i>; yields {ty}:result</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2239	</pre>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2240	<h5>Overview:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2241	<p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive
				2242	or of its two operands. The <tt>xor</tt> is used to implement the
				2243	"one's complement" operation, which is the "~" operator in C.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2244	<h5>Arguments:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2245	<p>The two arguments to the '<tt>xor</tt>' instruction must be <a
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	2246	href="#t_integer">integer</a> values. Both arguments must have
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2247	identical types.</p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2248	<h5>Semantics:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2249	<p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2250	<p> </p>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	2251	<div style="align: center">
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2252	<table border="1" cellspacing="0" cellpadding="4">
				2253	<tbody>
				2254	<tr>
				2255	<td>In0</td>
				2256	<td>In1</td>
				2257	<td>Out</td>
				2258	</tr>
				2259	<tr>
				2260	<td>0</td>
				2261	<td>0</td>
				2262	<td>0</td>
				2263	</tr>
				2264	<tr>
				2265	<td>0</td>
				2266	<td>1</td>
				2267	<td>1</td>
				2268	</tr>
				2269	<tr>
				2270	<td>1</td>
				2271	<td>0</td>
				2272	<td>1</td>
				2273	</tr>
				2274	<tr>
				2275	<td>1</td>
				2276	<td>1</td>
				2277	<td>0</td>
				2278	</tr>
				2279	</tbody>
				2280	</table>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	2281	</div>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2282	<p> </p>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2283	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2284	<pre> <result> = xor i32 4, %var <i>; yields {i32}:result = 4 ^ %var</i>
				2285	<result> = xor i32 15, 40 <i>; yields {i32}:result = 39</i>
				2286	<result> = xor i32 4, 8 <i>; yields {i32}:result = 12</i>
				2287	<result> = xor i32 %V, -1 <i>; yields {i32}:result = ~%V</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2288	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2289	</div>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2290
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2291	<!-- ======================================================================= -->
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2292	<div class="doc_subsection">
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2293	<a name="vectorops">Vector Operations</a>
				2294	</div>
				2295
				2296	<div class="doc_text">
				2297
				2298	<p>LLVM supports several instructions to represent vector operations in a
				2299	target-independent manner. This instructions cover the element-access and
				2300	vector-specific operations needed to process vectors effectively. While LLVM
				2301	does directly support these vector operations, many sophisticated algorithms
				2302	will want to use target-specific intrinsics to take full advantage of a specific
				2303	target.</p>
				2304
				2305	</div>
				2306
				2307	<!-- _______________________________________________________________________ -->
				2308	<div class="doc_subsubsection">
				2309	<a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
				2310	</div>
				2311
				2312	<div class="doc_text">
				2313
				2314	<h5>Syntax:</h5>
				2315
				2316	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2317	<result> = extractelement <n x <ty>> <val>, i32 <idx> <i>; yields <ty></i>
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2318	</pre>
				2319
				2320	<h5>Overview:</h5>
				2321
				2322	<p>
				2323	The '<tt>extractelement</tt>' instruction extracts a single scalar
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	2324	element from a vector at a specified index.
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2325	</p>
				2326
				2327
				2328	<h5>Arguments:</h5>
				2329
				2330	<p>
				2331	The first operand of an '<tt>extractelement</tt>' instruction is a
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	2332	value of <a href="#t_vector">vector</a> type. The second operand is
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2333	an index indicating the position from which to extract the element.
				2334	The index may be a variable.</p>
				2335
				2336	<h5>Semantics:</h5>
				2337
				2338	<p>
				2339	The result is a scalar of the same type as the element type of
				2340	<tt>val</tt>. Its value is the value at position <tt>idx</tt> of
				2341	<tt>val</tt>. If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
				2342	results are undefined.
				2343	</p>
				2344
				2345	<h5>Example:</h5>
				2346
				2347	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2348	%result = extractelement <4 x i32> %vec, i32 0 <i>; yields i32</i>
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2349	</pre>
				2350	</div>
				2351
				2352
				2353	<!-- _______________________________________________________________________ -->
				2354	<div class="doc_subsubsection">
				2355	<a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
				2356	</div>
				2357
				2358	<div class="doc_text">
				2359
				2360	<h5>Syntax:</h5>
				2361
				2362	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2363	<result> = insertelement <n x <ty>> <val>, <ty> <elt&gt, i32 <idx> <i>; yields <n x <ty>></i>
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2364	</pre>
				2365
				2366	<h5>Overview:</h5>
				2367
				2368	<p>
				2369	The '<tt>insertelement</tt>' instruction inserts a scalar
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	2370	element into a vector at a specified index.
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2371	</p>
				2372
				2373
				2374	<h5>Arguments:</h5>
				2375
				2376	<p>
				2377	The first operand of an '<tt>insertelement</tt>' instruction is a
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	2378	value of <a href="#t_vector">vector</a> type. The second operand is a
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2379	scalar value whose type must equal the element type of the first
				2380	operand. The third operand is an index indicating the position at
				2381	which to insert the value. The index may be a variable.</p>
				2382
				2383	<h5>Semantics:</h5>
				2384
				2385	<p>
Reid Spencer	404a325	2007-02-15 03:07:05 +0000	[diff] [blame]	2386	The result is a vector of the same type as <tt>val</tt>. Its
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2387	element values are those of <tt>val</tt> except at position
				2388	<tt>idx</tt>, where it gets the value <tt>elt</tt>. If <tt>idx</tt>
				2389	exceeds the length of <tt>val</tt>, the results are undefined.
				2390	</p>
				2391
				2392	<h5>Example:</h5>
				2393
				2394	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2395	%result = insertelement <4 x i32> %vec, i32 1, i32 0 <i>; yields <4 x i32></i>
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2396	</pre>
				2397	</div>
				2398
				2399	<!-- _______________________________________________________________________ -->
				2400	<div class="doc_subsubsection">
				2401	<a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
				2402	</div>
				2403
				2404	<div class="doc_text">
				2405
				2406	<h5>Syntax:</h5>
				2407
				2408	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2409	<result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <n x i32> <mask> <i>; yields <n x <ty>></i>
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2410	</pre>
				2411
				2412	<h5>Overview:</h5>
				2413
				2414	<p>
				2415	The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
				2416	from two input vectors, returning a vector of the same type.
				2417	</p>
				2418
				2419	<h5>Arguments:</h5>
				2420
				2421	<p>
				2422	The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
				2423	with types that match each other and types that match the result of the
				2424	instruction. The third argument is a shuffle mask, which has the same number
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2425	of elements as the other vector type, but whose element type is always 'i32'.
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2426	</p>
				2427
				2428	<p>
				2429	The shuffle mask operand is required to be a constant vector with either
				2430	constant integer or undef values.
				2431	</p>
				2432
				2433	<h5>Semantics:</h5>
				2434
				2435	<p>
				2436	The elements of the two input vectors are numbered from left to right across
				2437	both of the vectors. The shuffle mask operand specifies, for each element of
				2438	the result vector, which element of the two input registers the result element
				2439	gets. The element selector may be undef (meaning "don't care") and the second
				2440	operand may be undef if performing a shuffle from only one vector.
				2441	</p>
				2442
				2443	<h5>Example:</h5>
				2444
				2445	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2446	%result = shufflevector <4 x i32> %v1, <4 x i32> %v2,
				2447	<4 x i32> <i32 0, i32 4, i32 1, i32 5> <i>; yields <4 x i32></i>
				2448	%result = shufflevector <4 x i32> %v1, <4 x i32> undef,
				2449	<4 x i32> <i32 0, i32 1, i32 2, i32 3> <i>; yields <4 x i32></i> - Identity shuffle.
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2450	</pre>
				2451	</div>
				2452
Tanya Lattner	b138bbe	2006-04-14 19:24:33 +0000	[diff] [blame]	2453
Chris Lattner	ce83bff	2006-04-08 23:07:04 +0000	[diff] [blame]	2454	<!-- ======================================================================= -->
				2455	<div class="doc_subsection">
Chris Lattner	6ab6672	2006-08-15 00:45:58 +0000	[diff] [blame]	2456	<a name="memoryops">Memory Access and Addressing Operations</a>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2457	</div>
				2458
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2459	<div class="doc_text">
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2460
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2461	<p>A key design point of an SSA-based representation is how it
				2462	represents memory. In LLVM, no memory locations are in SSA form, which
				2463	makes things very simple. This section describes how to read, write,
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	2464	allocate, and free memory in LLVM.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2465
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2466	</div>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2467
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2468	<!-- _______________________________________________________________________ -->
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2469	<div class="doc_subsubsection">
				2470	<a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
				2471	</div>
				2472
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2473	<div class="doc_text">
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2474
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2475	<h5>Syntax:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2476
				2477	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2478	<result> = malloc <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2479	</pre>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2480
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2481	<h5>Overview:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2482
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2483	<p>The '<tt>malloc</tt>' instruction allocates memory from the system
				2484	heap and returns a pointer to it.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2485
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2486	<h5>Arguments:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2487
				2488	<p>The '<tt>malloc</tt>' instruction allocates
				2489	<tt>sizeof(<type>)*NumElements</tt>
John Criswell	a92e586	2004-02-24 16:13:56 +0000	[diff] [blame]	2490	bytes of memory from the operating system and returns a pointer of the
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2491	appropriate type to the program. If "NumElements" is specified, it is the
				2492	number of elements allocated. If an alignment is specified, the value result
				2493	of the allocation is guaranteed to be aligned to at least that boundary. If
				2494	not specified, or if zero, the target can choose to align the allocation on any
				2495	convenient boundary.</p>
				2496
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2497	<p>'<tt>type</tt>' must be a sized type.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2498
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2499	<h5>Semantics:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2500
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2501	<p>Memory is allocated using the system "<tt>malloc</tt>" function, and
				2502	a pointer is returned.</p>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2503
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2504	<h5>Example:</h5>
				2505
				2506	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2507	%array = malloc [4 x i8 ] <i>; yields {[%4 x i8]*}:array</i>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2508
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2509	%size = <a href="#i_add">add</a> i32 2, 2 <i>; yields {i32}:size = i32 4</i>
				2510	%array1 = malloc i8, i32 4 <i>; yields {i8*}:array1</i>
				2511	%array2 = malloc [12 x i8], i32 %size <i>; yields {[12 x i8]*}:array2</i>
				2512	%array3 = malloc i32, i32 4, align 1024 <i>; yields {i32*}:array3</i>
				2513	%array4 = malloc i32, align 1024 <i>; yields {i32*}:array4</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2514	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2515	</div>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2516
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2517	<!-- _______________________________________________________________________ -->
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2518	<div class="doc_subsubsection">
				2519	<a name="i_free">'<tt>free</tt>' Instruction</a>
				2520	</div>
				2521
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2522	<div class="doc_text">
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2523
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2524	<h5>Syntax:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2525
				2526	<pre>
				2527	free <type> <value> <i>; yields {void}</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2528	</pre>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2529
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2530	<h5>Overview:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2531
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2532	<p>The '<tt>free</tt>' instruction returns memory back to the unused
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	2533	memory heap to be reallocated in the future.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2534
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2535	<h5>Arguments:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2536
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2537	<p>'<tt>value</tt>' shall be a pointer value that points to a value
				2538	that was allocated with the '<tt><a href="#i_malloc">malloc</a></tt>'
				2539	instruction.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2540
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2541	<h5>Semantics:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2542
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	2543	<p>Access to the memory pointed to by the pointer is no longer defined
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2544	after this instruction executes.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2545
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2546	<h5>Example:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2547
				2548	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2549	%array = <a href="#i_malloc">malloc</a> [4 x i8] <i>; yields {[4 x i8]*}:array</i>
				2550	free [4 x i8]* %array
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2551	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2552	</div>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2553
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2554	<!-- _______________________________________________________________________ -->
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2555	<div class="doc_subsubsection">
				2556	<a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
				2557	</div>
				2558
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2559	<div class="doc_text">
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2560
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2561	<h5>Syntax:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2562
				2563	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2564	<result> = alloca <type>[, i32 <NumElements>][, align <alignment>] <i>; yields {type*}:result</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2565	</pre>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2566
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2567	<h5>Overview:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2568
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2569	<p>The '<tt>alloca</tt>' instruction allocates memory on the current
				2570	stack frame of the procedure that is live until the current function
				2571	returns to its caller.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2572
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2573	<h5>Arguments:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2574
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	2575	<p>The '<tt>alloca</tt>' instruction allocates <tt>sizeof(<type>)*NumElements</tt>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2576	bytes of memory on the runtime stack, returning a pointer of the
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2577	appropriate type to the program. If "NumElements" is specified, it is the
				2578	number of elements allocated. If an alignment is specified, the value result
				2579	of the allocation is guaranteed to be aligned to at least that boundary. If
				2580	not specified, or if zero, the target can choose to align the allocation on any
				2581	convenient boundary.</p>
				2582
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2583	<p>'<tt>type</tt>' may be any sized type.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2584
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2585	<h5>Semantics:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2586
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	2587	<p>Memory is allocated; a pointer is returned. '<tt>alloca</tt>'d
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2588	memory is automatically released when the function returns. The '<tt>alloca</tt>'
				2589	instruction is commonly used to represent automatic variables that must
				2590	have an address available. When the function returns (either with the <tt><a
John Criswell	c932bef	2005-05-12 16:55:34 +0000	[diff] [blame]	2591	href="#i_ret">ret</a></tt> or <tt><a href="#i_unwind">unwind</a></tt>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2592	instructions), the memory is reclaimed.</p>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2593
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2594	<h5>Example:</h5>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2595
				2596	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2597	%ptr = alloca i32 <i>; yields {i32*}:ptr</i>
				2598	%ptr = alloca i32, i32 4 <i>; yields {i32*}:ptr</i>
				2599	%ptr = alloca i32, i32 4, align 1024 <i>; yields {i32*}:ptr</i>
				2600	%ptr = alloca i32, align 1024 <i>; yields {i32*}:ptr</i>
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2601	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2602	</div>
Chris Lattner	54611b4	2005-11-06 08:02:57 +0000	[diff] [blame]	2603
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2604	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2605	<div class="doc_subsubsection"> <a name="i_load">'<tt>load</tt>'
				2606	Instruction</a> </div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2607	<div class="doc_text">
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2608	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2609	<pre> <result> = load <ty>* <pointer><br> <result> = volatile load <ty>* <pointer><br></pre>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2610	<h5>Overview:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2611	<p>The '<tt>load</tt>' instruction is used to read from memory.</p>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2612	<h5>Arguments:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2613	<p>The argument to the '<tt>load</tt>' instruction specifies the memory
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	2614	address from which to load. The pointer must point to a <a
Chris Lattner	10ee965	2004-06-03 22:57:15 +0000	[diff] [blame]	2615	href="#t_firstclass">first class</a> type. If the <tt>load</tt> is
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	2616	marked as <tt>volatile</tt>, then the optimizer is not allowed to modify
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2617	the number or order of execution of this <tt>load</tt> with other
				2618	volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
				2619	instructions. </p>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2620	<h5>Semantics:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2621	<p>The location of memory pointed to is loaded.</p>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2622	<h5>Examples:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2623	<pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2624	<a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2625	href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i>
				2626	%val = load i32* %ptr <i>; yields {i32}:val = i32 3</i>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2627	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2628	</div>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2629	<!-- _______________________________________________________________________ -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2630	<div class="doc_subsubsection"> <a name="i_store">'<tt>store</tt>'
				2631	Instruction</a> </div>
Reid Spencer	a89fb18	2006-11-09 21:18:01 +0000	[diff] [blame]	2632	<div class="doc_text">
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2633	<h5>Syntax:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2634	<pre> store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
Chris Lattner	12d456c	2003-09-08 18:27:49 +0000	[diff] [blame]	2635	volatile store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2636	</pre>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2637	<h5>Overview:</h5>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2638	<p>The '<tt>store</tt>' instruction is used to write to memory.</p>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2639	<h5>Arguments:</h5>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2640	<p>There are two arguments to the '<tt>store</tt>' instruction: a value
John Criswell	4c0cf7f	2005-10-24 16:17:18 +0000	[diff] [blame]	2641	to store and an address in which to store it. The type of the '<tt><pointer></tt>'
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2642	operand must be a pointer to the type of the '<tt><value></tt>'
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	2643	operand. If the <tt>store</tt> is marked as <tt>volatile</tt>, then the
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2644	optimizer is not allowed to modify the number or order of execution of
				2645	this <tt>store</tt> with other volatile <tt>load</tt> and <tt><a
				2646	href="#i_store">store</a></tt> instructions.</p>
				2647	<h5>Semantics:</h5>
				2648	<p>The contents of memory are updated to contain '<tt><value></tt>'
				2649	at the location specified by the '<tt><pointer></tt>' operand.</p>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2650	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2651	<pre> %ptr = <a href="#i_alloca">alloca</a> i32 <i>; yields {i32*}:ptr</i>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2652	<a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2653	href="#i_store">store</a> i32 3, i32* %ptr <i>; yields {void}</i>
				2654	%val = load i32* %ptr <i>; yields {i32}:val = i32 3</i>
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2655	</pre>
Reid Spencer	443460a	2006-11-09 21:15:49 +0000	[diff] [blame]	2656	</div>
				2657
Chris Lattner	095735d	2002-05-06 03:03:22 +0000	[diff] [blame]	2658	<!-- _______________________________________________________________________ -->
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2659	<div class="doc_subsubsection">
				2660	<a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
				2661	</div>
				2662
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2663	<div class="doc_text">
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	2664	<h5>Syntax:</h5>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2665	<pre>
				2666	<result> = getelementptr <ty>* <ptrval>{, <ty> <idx>}*
				2667	</pre>
				2668
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	2669	<h5>Overview:</h5>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2670
				2671	<p>
				2672	The '<tt>getelementptr</tt>' instruction is used to get the address of a
				2673	subelement of an aggregate data structure.</p>
				2674
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	2675	<h5>Arguments:</h5>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2676
Reid Spencer	cee005c	2006-12-04 21:29:24 +0000	[diff] [blame]	2677	<p>This instruction takes a list of integer operands that indicate what
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2678	elements of the aggregate object to index to. The actual types of the arguments
				2679	provided depend on the type of the first pointer argument. The
				2680	'<tt>getelementptr</tt>' instruction is used to index down through the type
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	2681	levels of a structure or to a specific index in an array. When indexing into a
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2682	structure, only <tt>i32</tt> integer constants are allowed. When indexing
Reid Spencer	cee005c	2006-12-04 21:29:24 +0000	[diff] [blame]	2683	into an array or pointer, only integers of 32 or 64 bits are allowed, and will
				2684	be sign extended to 64-bit values.</p>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2685
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2686	<p>For example, let's consider a C code fragment and how it gets
				2687	compiled to LLVM:</p>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2688
				2689	<pre>
				2690	struct RT {
				2691	char A;
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2692	i32 B[10][20];
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2693	char C;
				2694	};
				2695	struct ST {
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2696	i32 X;
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2697	double Y;
				2698	struct RT Z;
				2699	};
				2700
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2701	define i32 foo(struct ST s) {
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2702	return &s[1].Z.B[5][13];
				2703	}
				2704	</pre>
				2705
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2706	<p>The LLVM code generated by the GCC frontend is:</p>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2707
				2708	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2709	%RT = type { i8 , [10 x [20 x i32]], i8 }
				2710	%ST = type { i32, double, %RT }
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2711
Brian Gaeke	317ef96	2004-07-02 21:08:14 +0000	[diff] [blame]	2712	implementation
				2713
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2714	define i32* %foo(%ST* %s) {
Brian Gaeke	317ef96	2004-07-02 21:08:14 +0000	[diff] [blame]	2715	entry:
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2716	%reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
				2717	ret i32* %reg
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2718	}
				2719	</pre>
				2720
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	2721	<h5>Semantics:</h5>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2722
				2723	<p>The index types specified for the '<tt>getelementptr</tt>' instruction depend
John Criswell	4a3327e	2005-05-13 22:25:59 +0000	[diff] [blame]	2724	on the pointer type that is being indexed into. <a href="#t_pointer">Pointer</a>
Reid Spencer	cee005c	2006-12-04 21:29:24 +0000	[diff] [blame]	2725	and <a href="#t_array">array</a> types can use a 32-bit or 64-bit
Reid Spencer	c031269	2006-12-03 16:53:48 +0000	[diff] [blame]	2726	<a href="#t_integer">integer</a> type but the value will always be sign extended
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2727	to 64-bits. <a href="#t_struct">Structure</a> types, require <tt>i32</tt>
Reid Spencer	c031269	2006-12-03 16:53:48 +0000	[diff] [blame]	2728	<b>constants</b>.</p>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2729
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2730	<p>In the example above, the first index is indexing into the '<tt>%ST*</tt>'
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2731	type, which is a pointer, yielding a '<tt>%ST</tt>' = '<tt>{ i32, double, %RT
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2732	}</tt>' type, a structure. The second index indexes into the third element of
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2733	the structure, yielding a '<tt>%RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]],
				2734	i8 }</tt>' type, another structure. The third index indexes into the second
				2735	element of the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2736	array. The two dimensions of the array are subscripted into, yielding an
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2737	'<tt>i32</tt>' type. The '<tt>getelementptr</tt>' instruction returns a pointer
				2738	to this element, thus computing a value of '<tt>i32*</tt>' type.</p>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2739
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	2740	<p>Note that it is perfectly legal to index partially through a
				2741	structure, returning a pointer to an inner element. Because of this,
				2742	the LLVM code for the given testcase is equivalent to:</p>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2743
				2744	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2745	define i32* %foo(%ST* %s) {
				2746	%t1 = getelementptr %ST* %s, i32 1 <i>; yields %ST*:%t1</i>
				2747	%t2 = getelementptr %ST* %t1, i32 0, i32 2 <i>; yields %RT*:%t2</i>
				2748	%t3 = getelementptr %RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i>
				2749	%t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 <i>; yields [20 x i32]*:%t4</i>
				2750	%t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 <i>; yields i32*:%t5</i>
				2751	ret i32* %t5
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2752	}
Chris Lattner	a8292f3	2002-05-06 22:08:29 +0000	[diff] [blame]	2753	</pre>
Chris Lattner	c0ad71e	2005-06-24 17:22:57 +0000	[diff] [blame]	2754
				2755	<p>Note that it is undefined to access an array out of bounds: array and
				2756	pointer indexes must always be within the defined bounds of the array type.
				2757	The one exception for this rules is zero length arrays. These arrays are
				2758	defined to be accessible as variable length arrays, which requires access
				2759	beyond the zero'th element.</p>
				2760
Chris Lattner	6ab6672	2006-08-15 00:45:58 +0000	[diff] [blame]	2761	<p>The getelementptr instruction is often confusing. For some more insight
				2762	into how it works, see <a href="GetElementPtr.html">the getelementptr
				2763	FAQ</a>.</p>
				2764
Chris Lattner	590645f	2002-04-14 06:13:44 +0000	[diff] [blame]	2765	<h5>Example:</h5>
Chris Lattner	c0ad71e	2005-06-24 17:22:57 +0000	[diff] [blame]	2766
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2767	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2768	<i>; yields [12 x i8]*:aptr</i>
				2769	%aptr = getelementptr {i32, [12 x i8]}* %sptr, i64 0, i32 1
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2770	</pre>
Chris Lattner	33fd702	2004-04-05 01:30:49 +0000	[diff] [blame]	2771	</div>
Reid Spencer	443460a	2006-11-09 21:15:49 +0000	[diff] [blame]	2772
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	2773	<!-- ======================================================================= -->
Reid Spencer	97c5fa4	2006-11-08 01:18:52 +0000	[diff] [blame]	2774	<div class="doc_subsection"> <a name="convertops">Conversion Operations</a>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2775	</div>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2776	<div class="doc_text">
Reid Spencer	97c5fa4	2006-11-08 01:18:52 +0000	[diff] [blame]	2777	<p>The instructions in this category are the conversion instructions (casting)
				2778	which all take a single operand and a type. They perform various bit conversions
				2779	on the operand.</p>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	2780	</div>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	2781
Chris Lattner	a8292f3	2002-05-06 22:08:29 +0000	[diff] [blame]	2782	<!-- _______________________________________________________________________ -->
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	2783	<div class="doc_subsubsection">
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2784	<a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
				2785	</div>
				2786	<div class="doc_text">
				2787
				2788	<h5>Syntax:</h5>
				2789	<pre>
				2790	<result> = trunc <ty> <value> to <ty2> <i>; yields ty2</i>
				2791	</pre>
				2792
				2793	<h5>Overview:</h5>
				2794	<p>
				2795	The '<tt>trunc</tt>' instruction truncates its operand to the type <tt>ty2</tt>.
				2796	</p>
				2797
				2798	<h5>Arguments:</h5>
				2799	<p>
				2800	The '<tt>trunc</tt>' instruction takes a <tt>value</tt> to trunc, which must
				2801	be an <a href="#t_integer">integer</a> type, and a type that specifies the size
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	2802	and type of the result, which must be an <a href="#t_integer">integer</a>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	2803	type. The bit size of <tt>value</tt> must be larger than the bit size of
				2804	<tt>ty2</tt>. Equal sized types are not allowed.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2805
				2806	<h5>Semantics:</h5>
				2807	<p>
				2808	The '<tt>trunc</tt>' instruction truncates the high order bits in <tt>value</tt>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	2809	and converts the remaining bits to <tt>ty2</tt>. Since the source size must be
				2810	larger than the destination size, <tt>trunc</tt> cannot be a <i>no-op cast</i>.
				2811	It will always truncate bits.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2812
				2813	<h5>Example:</h5>
				2814	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2815	%X = trunc i32 257 to i8 <i>; yields i8:1</i>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	2816	%Y = trunc i32 123 to i1 <i>; yields i1:true</i>
				2817	%Y = trunc i32 122 to i1 <i>; yields i1:false</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2818	</pre>
				2819	</div>
				2820
				2821	<!-- _______________________________________________________________________ -->
				2822	<div class="doc_subsubsection">
				2823	<a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
				2824	</div>
				2825	<div class="doc_text">
				2826
				2827	<h5>Syntax:</h5>
				2828	<pre>
				2829	<result> = zext <ty> <value> to <ty2> <i>; yields ty2</i>
				2830	</pre>
				2831
				2832	<h5>Overview:</h5>
				2833	<p>The '<tt>zext</tt>' instruction zero extends its operand to type
				2834	<tt>ty2</tt>.</p>
				2835
				2836
				2837	<h5>Arguments:</h5>
				2838	<p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	2839	<a href="#t_integer">integer</a> type, and a type to cast it to, which must
				2840	also be of <a href="#t_integer">integer</a> type. The bit size of the
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	2841	<tt>value</tt> must be smaller than the bit size of the destination type,
				2842	<tt>ty2</tt>.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2843
				2844	<h5>Semantics:</h5>
				2845	<p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
				2846	bits until it reaches the size of the destination type, <tt>ty2</tt>. When the
				2847	the operand and the type are the same size, no bit filling is done and the
				2848	cast is considered a <i>no-op cast</i> because no bits change (only the type
				2849	changes).</p>
				2850
Reid Spencer	07c9c68	2007-01-12 15:46:11 +0000	[diff] [blame]	2851	<p>When zero extending from i1, the result will always be either 0 or 1.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2852
				2853	<h5>Example:</h5>
				2854	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2855	%X = zext i32 257 to i64 <i>; yields i64:257</i>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	2856	%Y = zext i1 true to i32 <i>; yields i32:1</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2857	</pre>
				2858	</div>
				2859
				2860	<!-- _______________________________________________________________________ -->
				2861	<div class="doc_subsubsection">
				2862	<a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
				2863	</div>
				2864	<div class="doc_text">
				2865
				2866	<h5>Syntax:</h5>
				2867	<pre>
				2868	<result> = sext <ty> <value> to <ty2> <i>; yields ty2</i>
				2869	</pre>
				2870
				2871	<h5>Overview:</h5>
				2872	<p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
				2873
				2874	<h5>Arguments:</h5>
				2875	<p>
				2876	The '<tt>sext</tt>' instruction takes a value to cast, which must be of
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	2877	<a href="#t_integer">integer</a> type, and a type to cast it to, which must
				2878	also be of <a href="#t_integer">integer</a> type. The bit size of the
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	2879	<tt>value</tt> must be smaller than the bit size of the destination type,
				2880	<tt>ty2</tt>.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2881
				2882	<h5>Semantics:</h5>
				2883	<p>
				2884	The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
				2885	bit (highest order bit) of the <tt>value</tt> until it reaches the bit size of
				2886	the type <tt>ty2</tt>. When the the operand and the type are the same size,
				2887	no bit filling is done and the cast is considered a <i>no-op cast</i> because
				2888	no bits change (only the type changes).</p>
				2889
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	2890	<p>When sign extending from i1, the extension always results in -1 or 0.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2891
				2892	<h5>Example:</h5>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2893	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	2894	%X = sext i8 -1 to i16 <i>; yields i16 :65535</i>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	2895	%Y = sext i1 true to i32 <i>; yields i32:-1</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2896	</pre>
				2897	</div>
				2898
				2899	<!-- _______________________________________________________________________ -->
				2900	<div class="doc_subsubsection">
Reid Spencer	2e2740d	2006-11-09 21:48:10 +0000	[diff] [blame]	2901	<a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
				2902	</div>
				2903
				2904	<div class="doc_text">
				2905
				2906	<h5>Syntax:</h5>
				2907
				2908	<pre>
				2909	<result> = fptrunc <ty> <value> to <ty2> <i>; yields ty2</i>
				2910	</pre>
				2911
				2912	<h5>Overview:</h5>
				2913	<p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
				2914	<tt>ty2</tt>.</p>
				2915
				2916
				2917	<h5>Arguments:</h5>
				2918	<p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
				2919	point</a> value to cast and a <a href="#t_floating">floating point</a> type to
				2920	cast it to. The size of <tt>value</tt> must be larger than the size of
				2921	<tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
				2922	<i>no-op cast</i>.</p>
				2923
				2924	<h5>Semantics:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	2925	<p> The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
				2926	<a href="#t_floating">floating point</a> type to a smaller
				2927	<a href="#t_floating">floating point</a> type. If the value cannot fit within
				2928	the destination type, <tt>ty2</tt>, then the results are undefined.</p>
Reid Spencer	2e2740d	2006-11-09 21:48:10 +0000	[diff] [blame]	2929
				2930	<h5>Example:</h5>
				2931	<pre>
				2932	%X = fptrunc double 123.0 to float <i>; yields float:123.0</i>
				2933	%Y = fptrunc double 1.0E+300 to float <i>; yields undefined</i>
				2934	</pre>
				2935	</div>
				2936
				2937	<!-- _______________________________________________________________________ -->
				2938	<div class="doc_subsubsection">
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2939	<a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
				2940	</div>
				2941	<div class="doc_text">
				2942
				2943	<h5>Syntax:</h5>
				2944	<pre>
				2945	<result> = fpext <ty> <value> to <ty2> <i>; yields ty2</i>
				2946	</pre>
				2947
				2948	<h5>Overview:</h5>
				2949	<p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
				2950	floating point value.</p>
				2951
				2952	<h5>Arguments:</h5>
				2953	<p>The '<tt>fpext</tt>' instruction takes a
				2954	<a href="#t_floating">floating point</a> <tt>value</tt> to cast,
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	2955	and a <a href="#t_floating">floating point</a> type to cast it to. The source
				2956	type must be smaller than the destination type.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2957
				2958	<h5>Semantics:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	2959	<p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
				2960	<a href="t_floating">floating point</a> type to a larger
				2961	<a href="t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
				2962	used to make a <i>no-op cast</i> because it always changes bits. Use
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	2963	<tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2964
				2965	<h5>Example:</h5>
				2966	<pre>
				2967	%X = fpext float 3.1415 to double <i>; yields double:3.1415</i>
				2968	%Y = fpext float 1.0 to float <i>; yields float:1.0 (no-op)</i>
				2969	</pre>
				2970	</div>
				2971
				2972	<!-- _______________________________________________________________________ -->
				2973	<div class="doc_subsubsection">
Reid Spencer	2eadb53	2007-01-21 00:29:26 +0000	[diff] [blame]	2974	<a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2975	</div>
				2976	<div class="doc_text">
				2977
				2978	<h5>Syntax:</h5>
				2979	<pre>
				2980	<result> = fp2uint <ty> <value> to <ty2> <i>; yields ty2</i>
				2981	</pre>
				2982
				2983	<h5>Overview:</h5>
				2984	<p>The '<tt>fp2uint</tt>' converts a floating point <tt>value</tt> to its
				2985	unsigned integer equivalent of type <tt>ty2</tt>.
				2986	</p>
				2987
				2988	<h5>Arguments:</h5>
				2989	<p>The '<tt>fp2uint</tt>' instruction takes a value to cast, which must be a
				2990	<a href="#t_floating">floating point</a> value, and a type to cast it to, which
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	2991	must be an <a href="#t_integer">integer</a> type.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	2992
				2993	<h5>Semantics:</h5>
				2994	<p> The '<tt>fp2uint</tt>' instruction converts its
				2995	<a href="#t_floating">floating point</a> operand into the nearest (rounding
				2996	towards zero) unsigned integer value. If the value cannot fit in <tt>ty2</tt>,
				2997	the results are undefined.</p>
				2998
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	2999	<p>When converting to i1, the conversion is done as a comparison against
				3000	zero. If the <tt>value</tt> was zero, the i1 result will be <tt>false</tt>.
				3001	If the <tt>value</tt> was non-zero, the i1 result will be <tt>true</tt>.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3002
				3003	<h5>Example:</h5>
				3004	<pre>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3005	%X = fp2uint double 123.0 to i32 <i>; yields i32:123</i>
				3006	%Y = fp2uint float 1.0E+300 to i1 <i>; yields i1:true</i>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3007	%X = fp2uint float 1.04E+17 to i8 <i>; yields undefined:1</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3008	</pre>
				3009	</div>
				3010
				3011	<!-- _______________________________________________________________________ -->
				3012	<div class="doc_subsubsection">
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3013	<a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3014	</div>
				3015	<div class="doc_text">
				3016
				3017	<h5>Syntax:</h5>
				3018	<pre>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3019	<result> = fptosi <ty> <value> to <ty2> <i>; yields ty2</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3020	</pre>
				3021
				3022	<h5>Overview:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3023	<p>The '<tt>fptosi</tt>' instruction converts
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3024	<a href="#t_floating">floating point</a> <tt>value</tt> to type <tt>ty2</tt>.
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3025	</p>
				3026
				3027
Chris Lattner	a8292f3	2002-05-06 22:08:29 +0000	[diff] [blame]	3028	<h5>Arguments:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3029	<p> The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3030	<a href="#t_floating">floating point</a> value, and a type to cast it to, which
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	3031	must also be an <a href="#t_integer">integer</a> type.</p>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3032
Chris Lattner	a8292f3	2002-05-06 22:08:29 +0000	[diff] [blame]	3033	<h5>Semantics:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3034	<p>The '<tt>fptosi</tt>' instruction converts its
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3035	<a href="#t_floating">floating point</a> operand into the nearest (rounding
				3036	towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
				3037	the results are undefined.</p>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3038
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3039	<p>When converting to i1, the conversion is done as a comparison against
				3040	zero. If the <tt>value</tt> was zero, the i1 result will be <tt>false</tt>.
				3041	If the <tt>value</tt> was non-zero, the i1 result will be <tt>true</tt>.</p>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3042
Chris Lattner	70de663	2001-07-09 00:26:23 +0000	[diff] [blame]	3043	<h5>Example:</h5>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3044	<pre>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3045	%X = fptosi double -123.0 to i32 <i>; yields i32:-123</i>
				3046	%Y = fptosi float 1.0E-247 to i1 <i>; yields i1:true</i>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3047	%X = fptosi float 1.04E+17 to i8 <i>; yields undefined:1</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3048	</pre>
				3049	</div>
				3050
				3051	<!-- _______________________________________________________________________ -->
				3052	<div class="doc_subsubsection">
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3053	<a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3054	</div>
				3055	<div class="doc_text">
				3056
				3057	<h5>Syntax:</h5>
				3058	<pre>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3059	<result> = uitofp <ty> <value> to <ty2> <i>; yields ty2</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3060	</pre>
				3061
				3062	<h5>Overview:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3063	<p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3064	integer and converts that value to the <tt>ty2</tt> type.</p>
				3065
				3066
				3067	<h5>Arguments:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3068	<p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be an
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	3069	<a href="#t_integer">integer</a> value, and a type to cast it to, which must
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3070	be a <a href="#t_floating">floating point</a> type.</p>
				3071
				3072	<h5>Semantics:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3073	<p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3074	integer quantity and converts it to the corresponding floating point value. If
				3075	the value cannot fit in the floating point value, the results are undefined.</p>
				3076
				3077
				3078	<h5>Example:</h5>
				3079	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3080	%X = uitofp i32 257 to float <i>; yields float:257.0</i>
				3081	%Y = uitofp i8 -1 to double <i>; yields double:255.0</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3082	</pre>
				3083	</div>
				3084
				3085	<!-- _______________________________________________________________________ -->
				3086	<div class="doc_subsubsection">
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3087	<a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3088	</div>
				3089	<div class="doc_text">
				3090
				3091	<h5>Syntax:</h5>
				3092	<pre>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3093	<result> = sitofp <ty> <value> to <ty2> <i>; yields ty2</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3094	</pre>
				3095
				3096	<h5>Overview:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3097	<p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3098	integer and converts that value to the <tt>ty2</tt> type.</p>
				3099
				3100	<h5>Arguments:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3101	<p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be an
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	3102	<a href="#t_integer">integer</a> value, and a type to cast it to, which must be
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3103	a <a href="#t_floating">floating point</a> type.</p>
				3104
				3105	<h5>Semantics:</h5>
Reid Spencer	51b0725	2006-11-09 23:03:26 +0000	[diff] [blame]	3106	<p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3107	integer quantity and converts it to the corresponding floating point value. If
				3108	the value cannot fit in the floating point value, the results are undefined.</p>
				3109
				3110	<h5>Example:</h5>
				3111	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3112	%X = sitofp i32 257 to float <i>; yields float:257.0</i>
				3113	%Y = sitofp i8 -1 to double <i>; yields double:-1.0</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3114	</pre>
				3115	</div>
				3116
				3117	<!-- _______________________________________________________________________ -->
				3118	<div class="doc_subsubsection">
Reid Spencer	b7344ff	2006-11-11 21:00:47 +0000	[diff] [blame]	3119	<a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
				3120	</div>
				3121	<div class="doc_text">
				3122
				3123	<h5>Syntax:</h5>
				3124	<pre>
				3125	<result> = ptrtoint <ty> <value> to <ty2> <i>; yields ty2</i>
				3126	</pre>
				3127
				3128	<h5>Overview:</h5>
				3129	<p>The '<tt>ptrtoint</tt>' instruction converts the pointer <tt>value</tt> to
				3130	the integer type <tt>ty2</tt>.</p>
				3131
				3132	<h5>Arguments:</h5>
				3133	<p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
				3134	must be a <a href="t_pointer">pointer</a> value, and a type to cast it to
				3135	<tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> type.
				3136
				3137	<h5>Semantics:</h5>
				3138	<p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
				3139	<tt>ty2</tt> by interpreting the pointer value as an integer and either
				3140	truncating or zero extending that value to the size of the integer type. If
				3141	<tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
				3142	<tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
				3143	are the same size, then nothing is done (<i>no-op cast</i>).</p>
				3144
				3145	<h5>Example:</h5>
				3146	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3147	%X = ptrtoint i32* %X to i8 <i>; yields truncation on 32-bit</i>
				3148	%Y = ptrtoint i32* %x to i64 <i>; yields zero extend on 32-bit</i>
Reid Spencer	b7344ff	2006-11-11 21:00:47 +0000	[diff] [blame]	3149	</pre>
				3150	</div>
				3151
				3152	<!-- _______________________________________________________________________ -->
				3153	<div class="doc_subsubsection">
				3154	<a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
				3155	</div>
				3156	<div class="doc_text">
				3157
				3158	<h5>Syntax:</h5>
				3159	<pre>
				3160	<result> = inttoptr <ty> <value> to <ty2> <i>; yields ty2</i>
				3161	</pre>
				3162
				3163	<h5>Overview:</h5>
				3164	<p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to
				3165	a pointer type, <tt>ty2</tt>.</p>
				3166
				3167	<h5>Arguments:</h5>
				3168	<p>The '<tt>inttoptr</tt>' instruction takes an <a href="i_integer">integer</a>
				3169	value to cast, and a type to cast it to, which must be a
Anton Korobeynikov	a0554d9	2007-01-12 19:20:47 +0000	[diff] [blame]	3170	<a href="#t_pointer">pointer</a> type.
Reid Spencer	b7344ff	2006-11-11 21:00:47 +0000	[diff] [blame]	3171
				3172	<h5>Semantics:</h5>
				3173	<p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
				3174	<tt>ty2</tt> by applying either a zero extension or a truncation depending on
				3175	the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
				3176	size of a pointer then a truncation is done. If <tt>value</tt> is smaller than
				3177	the size of a pointer then a zero extension is done. If they are the same size,
				3178	nothing is done (<i>no-op cast</i>).</p>
				3179
				3180	<h5>Example:</h5>
				3181	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3182	%X = inttoptr i32 255 to i32* <i>; yields zero extend on 64-bit</i>
				3183	%X = inttoptr i32 255 to i32* <i>; yields no-op on 32-bit </i>
				3184	%Y = inttoptr i16 0 to i32* <i>; yields zero extend on 32-bit</i>
Reid Spencer	b7344ff	2006-11-11 21:00:47 +0000	[diff] [blame]	3185	</pre>
				3186	</div>
				3187
				3188	<!-- _______________________________________________________________________ -->
				3189	<div class="doc_subsubsection">
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	3190	<a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3191	</div>
				3192	<div class="doc_text">
				3193
				3194	<h5>Syntax:</h5>
				3195	<pre>
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	3196	<result> = bitcast <ty> <value> to <ty2> <i>; yields ty2</i>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3197	</pre>
				3198
				3199	<h5>Overview:</h5>
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	3200	<p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3201	<tt>ty2</tt> without changing any bits.</p>
				3202
				3203	<h5>Arguments:</h5>
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	3204	<p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3205	a first class value, and a type to cast it to, which must also be a <a
				3206	href="#t_firstclass">first class</a> type. The bit sizes of <tt>value</tt>
Reid Spencer	e3db84c	2007-01-09 20:08:58 +0000	[diff] [blame]	3207	and the destination type, <tt>ty2</tt>, must be identical. If the source
				3208	type is a pointer, the destination type must also be a pointer.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3209
				3210	<h5>Semantics:</h5>
Reid Spencer	5b95064	2006-11-11 23:08:07 +0000	[diff] [blame]	3211	<p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
Reid Spencer	b7344ff	2006-11-11 21:00:47 +0000	[diff] [blame]	3212	<tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
				3213	this conversion. The conversion is done as if the <tt>value</tt> had been
				3214	stored to memory and read back as type <tt>ty2</tt>. Pointer types may only be
				3215	converted to other pointer types with this instruction. To convert pointers to
				3216	other types, use the <a href="#i_inttoptr">inttoptr</a> or
				3217	<a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
Reid Spencer	59b6b7d	2006-11-08 01:11:31 +0000	[diff] [blame]	3218
				3219	<h5>Example:</h5>
				3220	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3221	%X = bitcast i8 255 to i8 <i>; yields i8 :-1</i>
				3222	%Y = bitcast i32* %x to sint* <i>; yields sint*:%x</i>
				3223	%Z = bitcast <2xint> %V to i64; <i>; yields i64: %V</i>
Chris Lattner	70de663	2001-07-09 00:26:23 +0000	[diff] [blame]	3224	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3225	</div>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3226
Reid Spencer	97c5fa4	2006-11-08 01:18:52 +0000	[diff] [blame]	3227	<!-- ======================================================================= -->
				3228	<div class="doc_subsection"> <a name="otherops">Other Operations</a> </div>
				3229	<div class="doc_text">
				3230	<p>The instructions in this category are the "miscellaneous"
				3231	instructions, which defy better classification.</p>
				3232	</div>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3233
				3234	<!-- _______________________________________________________________________ -->
				3235	<div class="doc_subsubsection"><a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
				3236	</div>
				3237	<div class="doc_text">
				3238	<h5>Syntax:</h5>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3239	<pre> <result> = icmp <cond> <ty> <var1>, <var2>
				3240	<i>; yields {i1}:result</i>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3241	</pre>
				3242	<h5>Overview:</h5>
				3243	<p>The '<tt>icmp</tt>' instruction returns a boolean value based on comparison
				3244	of its two integer operands.</p>
				3245	<h5>Arguments:</h5>
				3246	<p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
				3247	the condition code which indicates the kind of comparison to perform. It is not
				3248	a value, just a keyword. The possibilities for the condition code are:
				3249	<ol>
				3250	<li><tt>eq</tt>: equal</li>
				3251	<li><tt>ne</tt>: not equal </li>
				3252	<li><tt>ugt</tt>: unsigned greater than</li>
				3253	<li><tt>uge</tt>: unsigned greater or equal</li>
				3254	<li><tt>ult</tt>: unsigned less than</li>
				3255	<li><tt>ule</tt>: unsigned less or equal</li>
				3256	<li><tt>sgt</tt>: signed greater than</li>
				3257	<li><tt>sge</tt>: signed greater or equal</li>
				3258	<li><tt>slt</tt>: signed less than</li>
				3259	<li><tt>sle</tt>: signed less or equal</li>
				3260	</ol>
Chris Lattner	c0f423a	2007-01-15 01:54:13 +0000	[diff] [blame]	3261	<p>The remaining two arguments must be <a href="#t_integer">integer</a> or
Reid Spencer	784ef79	2007-01-04 05:19:58 +0000	[diff] [blame]	3262	<a href="#t_pointer">pointer</a> typed. They must also be identical types.</p>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3263	<h5>Semantics:</h5>
				3264	<p>The '<tt>icmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
				3265	the condition code given as <tt>cond</tt>. The comparison performed always
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3266	yields a <a href="#t_primitive">i1</a> result, as follows:
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3267	<ol>
				3268	<li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
				3269	<tt>false</tt> otherwise. No sign interpretation is necessary or performed.
				3270	</li>
				3271	<li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
				3272	<tt>false</tt> otherwise. No sign interpretation is necessary or performed.
				3273	<li><tt>ugt</tt>: interprets the operands as unsigned values and yields
				3274	<tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
				3275	<li><tt>uge</tt>: interprets the operands as unsigned values and yields
				3276	<tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
				3277	<li><tt>ult</tt>: interprets the operands as unsigned values and yields
				3278	<tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
				3279	<li><tt>ule</tt>: interprets the operands as unsigned values and yields
				3280	<tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
				3281	<li><tt>sgt</tt>: interprets the operands as signed values and yields
				3282	<tt>true</tt> if <tt>var1</tt> is greater than <tt>var2</tt>.</li>
				3283	<li><tt>sge</tt>: interprets the operands as signed values and yields
				3284	<tt>true</tt> if <tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
				3285	<li><tt>slt</tt>: interprets the operands as signed values and yields
				3286	<tt>true</tt> if <tt>var1</tt> is less than <tt>var2</tt>.</li>
				3287	<li><tt>sle</tt>: interprets the operands as signed values and yields
				3288	<tt>true</tt> if <tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3289	</ol>
				3290	<p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
				3291	values are treated as integers and then compared.</p>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3292
				3293	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3294	<pre> <result> = icmp eq i32 4, 5 <i>; yields: result=false</i>
				3295	<result> = icmp ne float* %X, %X <i>; yields: result=false</i>
				3296	<result> = icmp ult i16 4, 5 <i>; yields: result=true</i>
				3297	<result> = icmp sgt i16 4, 5 <i>; yields: result=false</i>
				3298	<result> = icmp ule i16 -4, 5 <i>; yields: result=false</i>
				3299	<result> = icmp sge i16 4, 5 <i>; yields: result=false</i>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3300	</pre>
				3301	</div>
				3302
				3303	<!-- _______________________________________________________________________ -->
				3304	<div class="doc_subsubsection"><a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
				3305	</div>
				3306	<div class="doc_text">
				3307	<h5>Syntax:</h5>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3308	<pre> <result> = fcmp <cond> <ty> <var1>, <var2>
				3309	<i>; yields {i1}:result</i>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3310	</pre>
				3311	<h5>Overview:</h5>
				3312	<p>The '<tt>fcmp</tt>' instruction returns a boolean value based on comparison
				3313	of its floating point operands.</p>
				3314	<h5>Arguments:</h5>
				3315	<p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
				3316	the condition code which indicates the kind of comparison to perform. It is not
				3317	a value, just a keyword. The possibilities for the condition code are:
				3318	<ol>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3319	<li><tt>false</tt>: no comparison, always returns false</li>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3320	<li><tt>oeq</tt>: ordered and equal</li>
				3321	<li><tt>ogt</tt>: ordered and greater than </li>
				3322	<li><tt>oge</tt>: ordered and greater than or equal</li>
				3323	<li><tt>olt</tt>: ordered and less than </li>
				3324	<li><tt>ole</tt>: ordered and less than or equal</li>
				3325	<li><tt>one</tt>: ordered and not equal</li>
				3326	<li><tt>ord</tt>: ordered (no nans)</li>
				3327	<li><tt>ueq</tt>: unordered or equal</li>
				3328	<li><tt>ugt</tt>: unordered or greater than </li>
				3329	<li><tt>uge</tt>: unordered or greater than or equal</li>
				3330	<li><tt>ult</tt>: unordered or less than </li>
				3331	<li><tt>ule</tt>: unordered or less than or equal</li>
				3332	<li><tt>une</tt>: unordered or not equal</li>
				3333	<li><tt>uno</tt>: unordered (either nans)</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3334	<li><tt>true</tt>: no comparison, always returns true</li>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3335	</ol>
Reid Spencer	02e0d1d	2006-12-06 07:08:07 +0000	[diff] [blame]	3336	<p>In the preceding, <i>ordered</i> means that neither operand is a QNAN while
				3337	<i>unordered</i> means that either operand may be a QNAN.</p>
Reid Spencer	784ef79	2007-01-04 05:19:58 +0000	[diff] [blame]	3338	<p>The <tt>val1</tt> and <tt>val2</tt> arguments must be
				3339	<a href="#t_floating">floating point</a> typed. They must have identical
				3340	types.</p>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3341	<p>In the foregoing, <i>ordered</i> means that neither operand is a QNAN and
				3342	<i>unordered</i> means that either operand is a QNAN.</p>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3343	<h5>Semantics:</h5>
				3344	<p>The '<tt>fcmp</tt>' compares <tt>var1</tt> and <tt>var2</tt> according to
				3345	the condition code given as <tt>cond</tt>. The comparison performed always
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3346	yields a <a href="#t_primitive">i1</a> result, as follows:
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3347	<ol>
				3348	<li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3349	<li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3350	<tt>var1</tt> is equal to <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3351	<li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3352	<tt>var1</tt> is greather than <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3353	<li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3354	<tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3355	<li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3356	<tt>var1</tt> is less than <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3357	<li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3358	<tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3359	<li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3360	<tt>var1</tt> is not equal to <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3361	<li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
				3362	<li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3363	<tt>var1</tt> is equal to <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3364	<li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3365	<tt>var1</tt> is greater than <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3366	<li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3367	<tt>var1</tt> is greater than or equal to <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3368	<li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3369	<tt>var1</tt> is less than <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3370	<li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3371	<tt>var1</tt> is less than or equal to <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3372	<li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3373	<tt>var1</tt> is not equal to <tt>var2</tt>.</li>
Reid Spencer	f69acf3	2006-11-19 03:00:14 +0000	[diff] [blame]	3374	<li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3375	<li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
				3376	</ol>
Reid Spencer	c828a0e	2006-11-18 21:50:54 +0000	[diff] [blame]	3377
				3378	<h5>Example:</h5>
				3379	<pre> <result> = fcmp oeq float 4.0, 5.0 <i>; yields: result=false</i>
				3380	<result> = icmp one float 4.0, 5.0 <i>; yields: result=true</i>
				3381	<result> = icmp olt float 4.0, 5.0 <i>; yields: result=true</i>
				3382	<result> = icmp ueq double 1.0, 2.0 <i>; yields: result=false</i>
				3383	</pre>
				3384	</div>
				3385
Reid Spencer	97c5fa4	2006-11-08 01:18:52 +0000	[diff] [blame]	3386	<!-- _______________________________________________________________________ -->
				3387	<div class="doc_subsubsection"> <a name="i_phi">'<tt>phi</tt>'
				3388	Instruction</a> </div>
				3389	<div class="doc_text">
				3390	<h5>Syntax:</h5>
				3391	<pre> <result> = phi <ty> [ <val0>, <label0>], ...<br></pre>
				3392	<h5>Overview:</h5>
				3393	<p>The '<tt>phi</tt>' instruction is used to implement the φ node in
				3394	the SSA graph representing the function.</p>
				3395	<h5>Arguments:</h5>
				3396	<p>The type of the incoming values are specified with the first type
				3397	field. After this, the '<tt>phi</tt>' instruction takes a list of pairs
				3398	as arguments, with one pair for each predecessor basic block of the
				3399	current block. Only values of <a href="#t_firstclass">first class</a>
				3400	type may be used as the value arguments to the PHI node. Only labels
				3401	may be used as the label arguments.</p>
				3402	<p>There must be no non-phi instructions between the start of a basic
				3403	block and the PHI instructions: i.e. PHI instructions must be first in
				3404	a basic block.</p>
				3405	<h5>Semantics:</h5>
				3406	<p>At runtime, the '<tt>phi</tt>' instruction logically takes on the
				3407	value specified by the parameter, depending on which basic block we
				3408	came from in the last <a href="#terminators">terminator</a> instruction.</p>
				3409	<h5>Example:</h5>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3410	<pre>Loop: ; Infinite loop that counts from 0 on up...<br> %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]<br> %nextindvar = add i32 %indvar, 1<br> br label %Loop<br></pre>
Reid Spencer	97c5fa4	2006-11-08 01:18:52 +0000	[diff] [blame]	3411	</div>
				3412
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3413	<!-- _______________________________________________________________________ -->
				3414	<div class="doc_subsubsection">
				3415	<a name="i_select">'<tt>select</tt>' Instruction</a>
				3416	</div>
				3417
				3418	<div class="doc_text">
				3419
				3420	<h5>Syntax:</h5>
				3421
				3422	<pre>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3423	<result> = select i1 <cond>, <ty> <val1>, <ty> <val2> <i>; yields ty</i>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3424	</pre>
				3425
				3426	<h5>Overview:</h5>
				3427
				3428	<p>
				3429	The '<tt>select</tt>' instruction is used to choose one value based on a
				3430	condition, without branching.
				3431	</p>
				3432
				3433
				3434	<h5>Arguments:</h5>
				3435
				3436	<p>
				3437	The '<tt>select</tt>' instruction requires a boolean value indicating the condition, and two values of the same <a href="#t_firstclass">first class</a> type.
				3438	</p>
				3439
				3440	<h5>Semantics:</h5>
				3441
				3442	<p>
				3443	If the boolean condition evaluates to true, the instruction returns the first
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	3444	value argument; otherwise, it returns the second value argument.
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3445	</p>
				3446
				3447	<h5>Example:</h5>
				3448
				3449	<pre>
Reid Spencer	36a1542	2007-01-12 03:35:51 +0000	[diff] [blame]	3450	%X = select i1 true, i8 17, i8 42 <i>; yields i8:17</i>
Chris Lattner	b53c28d	2004-03-12 05:50:16 +0000	[diff] [blame]	3451	</pre>
				3452	</div>
				3453
Robert Bocchino	f72fdfe	2006-01-15 20:48:27 +0000	[diff] [blame]	3454
				3455	<!-- _______________________________________________________________________ -->
				3456	<div class="doc_subsubsection">
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3457	<a name="i_call">'<tt>call</tt>' Instruction</a>
				3458	</div>
				3459
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3460	<div class="doc_text">
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3461
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	3462	<h5>Syntax:</h5>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3463	<pre>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	3464	<result> = [tail] call [<a href="#callingconv">cconv</a>] <ty>* <fnptrval>(<param list>)
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3465	</pre>
				3466
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	3467	<h5>Overview:</h5>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3468
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3469	<p>The '<tt>call</tt>' instruction represents a simple function call.</p>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3470
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	3471	<h5>Arguments:</h5>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3472
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3473	<p>This instruction requires several arguments:</p>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3474
Chris Lattner	a8292f3	2002-05-06 22:08:29 +0000	[diff] [blame]	3475	<ol>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3476	<li>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	3477	<p>The optional "tail" marker indicates whether the callee function accesses
				3478	any allocas or varargs in the caller. If the "tail" marker is present, the
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3479	function call is eligible for tail call optimization. Note that calls may
				3480	be marked "tail" even if they do not occur before a <a
				3481	href="#i_ret"><tt>ret</tt></a> instruction.
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3482	</li>
				3483	<li>
Chris Lattner	0132aff	2005-05-06 22:57:40 +0000	[diff] [blame]	3484	<p>The optional "cconv" marker indicates which <a href="callingconv">calling
				3485	convention</a> the call should use. If none is specified, the call defaults
				3486	to using C calling conventions.
				3487	</li>
				3488	<li>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3489	<p>'<tt>ty</tt>': shall be the signature of the pointer to function value
				3490	being invoked. The argument types must match the types implied by this
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	3491	signature. This type can be omitted if the function is not varargs and
				3492	if the function type does not return a pointer to a function.</p>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3493	</li>
				3494	<li>
				3495	<p>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to
				3496	be invoked. In most cases, this is a direct function invocation, but
				3497	indirect <tt>call</tt>s are just as possible, calling an arbitrary pointer
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	3498	to function value.</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3499	</li>
				3500	<li>
				3501	<p>'<tt>function args</tt>': argument list whose types match the
Reid Spencer	d845d16	2005-05-01 22:22:57 +0000	[diff] [blame]	3502	function signature argument types. All arguments must be of
				3503	<a href="#t_firstclass">first class</a> type. If the function signature
				3504	indicates the function accepts a variable number of arguments, the extra
				3505	arguments can be specified.</p>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3506	</li>
Chris Lattner	a8292f3	2002-05-06 22:08:29 +0000	[diff] [blame]	3507	</ol>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3508
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	3509	<h5>Semantics:</h5>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3510
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3511	<p>The '<tt>call</tt>' instruction is used to cause control flow to
				3512	transfer to a specified function, with its incoming arguments bound to
				3513	the specified values. Upon a '<tt><a href="#i_ret">ret</a></tt>'
				3514	instruction in the called function, control flow continues with the
				3515	instruction after the function call, and the return value of the
				3516	function is bound to the result argument. This is a simpler case of
				3517	the <a href="#i_invoke">invoke</a> instruction.</p>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3518
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	3519	<h5>Example:</h5>
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3520
				3521	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3522	%retval = call i32 %test(i32 %argc)
				3523	call i32(i8 , ...) %printf(i8 * %msg, i32 12, i8 42);
				3524	%X = tail call i32 %foo()
				3525	%Y = tail call <a href="#callingconv">fastcc</a> i32 %foo()
Chris Lattner	e23c139	2005-05-06 05:47:36 +0000	[diff] [blame]	3526	</pre>
				3527
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3528	</div>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3529
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3530	<!-- _______________________________________________________________________ -->
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3531	<div class="doc_subsubsection">
Chris Lattner	3333747	2006-01-13 23:26:01 +0000	[diff] [blame]	3532	<a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3533	</div>
				3534
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3535	<div class="doc_text">
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3536
Chris Lattner	26ca62e	2003-10-18 05:51:36 +0000	[diff] [blame]	3537	<h5>Syntax:</h5>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3538
				3539	<pre>
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3540	<resultval> = va_arg <va_list*> <arglist>, <argty>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3541	</pre>
				3542
Chris Lattner	26ca62e	2003-10-18 05:51:36 +0000	[diff] [blame]	3543	<h5>Overview:</h5>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3544
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3545	<p>The '<tt>va_arg</tt>' instruction is used to access arguments passed through
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3546	the "variable argument" area of a function call. It is used to implement the
				3547	<tt>va_arg</tt> macro in C.</p>
				3548
Chris Lattner	26ca62e	2003-10-18 05:51:36 +0000	[diff] [blame]	3549	<h5>Arguments:</h5>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3550
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3551	<p>This instruction takes a <tt>va_list*</tt> value and the type of
				3552	the argument. It returns a value of the specified argument type and
Jeff Cohen	dc6bfea	2005-11-11 02:15:27 +0000	[diff] [blame]	3553	increments the <tt>va_list</tt> to point to the next argument. Again, the
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3554	actual type of <tt>va_list</tt> is target specific.</p>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3555
Chris Lattner	26ca62e	2003-10-18 05:51:36 +0000	[diff] [blame]	3556	<h5>Semantics:</h5>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3557
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3558	<p>The '<tt>va_arg</tt>' instruction loads an argument of the specified
				3559	type from the specified <tt>va_list</tt> and causes the
				3560	<tt>va_list</tt> to point to the next argument. For more information,
				3561	see the variable argument handling <a href="#int_varargs">Intrinsic
				3562	Functions</a>.</p>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3563
				3564	<p>It is legal for this instruction to be called in a function which does not
				3565	take a variable number of arguments, for example, the <tt>vfprintf</tt>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3566	function.</p>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3567
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3568	<p><tt>va_arg</tt> is an LLVM instruction instead of an <a
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	3569	href="#intrinsics">intrinsic function</a> because it takes a type as an
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3570	argument.</p>
				3571
Chris Lattner	26ca62e	2003-10-18 05:51:36 +0000	[diff] [blame]	3572	<h5>Example:</h5>
Chris Lattner	6a4a049	2004-09-27 21:51:25 +0000	[diff] [blame]	3573
				3574	<p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
				3575
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3576	</div>
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3577
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3578	<!-- *********************************************************************** -->
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3579	<div class="doc_section"> <a name="intrinsics">Intrinsic Functions</a> </div>
				3580	<!-- *********************************************************************** -->
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3581
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3582	<div class="doc_text">
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3583
				3584	<p>LLVM supports the notion of an "intrinsic function". These functions have
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	3585	well known names and semantics and are required to follow certain
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3586	restrictions. Overall, these instructions represent an extension mechanism for
				3587	the LLVM language that does not require changing all of the transformations in
				3588	LLVM to add to the language (or the bytecode reader/writer, the parser,
				3589	etc...).</p>
				3590
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	3591	<p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
				3592	prefix is reserved in LLVM for intrinsic names; thus, functions may not be named
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3593	this. Intrinsic functions must always be external functions: you cannot define
				3594	the body of intrinsic functions. Intrinsic functions may only be used in call
				3595	or invoke instructions: it is illegal to take the address of an intrinsic
				3596	function. Additionally, because intrinsic functions are part of the LLVM
				3597	language, it is required that they all be documented here if any are added.</p>
				3598
				3599
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	3600	<p>To learn how to add an intrinsic function, please see the <a
Chris Lattner	90391c1	2005-05-11 03:35:57 +0000	[diff] [blame]	3601	href="ExtendingLLVM.html">Extending LLVM Guide</a>.
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3602	</p>
				3603
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3604	</div>
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3605
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3606	<!-- ======================================================================= -->
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3607	<div class="doc_subsection">
				3608	<a name="int_varargs">Variable Argument Handling Intrinsics</a>
				3609	</div>
				3610
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3611	<div class="doc_text">
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3612
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3613	<p>Variable argument support is defined in LLVM with the <a
Chris Lattner	3333747	2006-01-13 23:26:01 +0000	[diff] [blame]	3614	href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3615	intrinsic functions. These functions are related to the similarly
				3616	named macros defined in the <tt><stdarg.h></tt> header file.</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3617
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3618	<p>All of these functions operate on arguments that use a
				3619	target-specific value type "<tt>va_list</tt>". The LLVM assembly
				3620	language reference manual does not define what this type is, so all
				3621	transformations should be prepared to handle intrinsics with any type
				3622	used.</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3623
Chris Lattner	30b868d	2006-05-15 17:26:46 +0000	[diff] [blame]	3624	<p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3625	instruction and the variable argument handling intrinsic functions are
				3626	used.</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3627
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3628	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3629	define i32 %test(i32 %X, ...) {
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3630	; Initialize variable argument processing
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3631	%ap = alloca i8 *
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3632	%ap2 = bitcast i8** %ap to i8*
				3633	call void %<a href="#i_va_start">llvm.va_start</a>(i8* %ap2)
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3634
				3635	; Read a single integer argument
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3636	%tmp = va_arg i8 ** %ap, i32
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3637
				3638	; Demonstrate usage of llvm.va_copy and llvm.va_end
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3639	%aq = alloca i8 *
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3640	%aq2 = bitcast i8** %aq to i8*
				3641	call void %<a href="#i_va_copy">llvm.va_copy</a>(i8 %aq2, i8 %ap2)
				3642	call void %<a href="#i_va_end">llvm.va_end</a>(i8* %aq2)
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3643
				3644	; Stop processing of arguments.
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3645	call void %<a href="#i_va_end">llvm.va_end</a>(i8* %ap2)
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3646	ret i32 %tmp
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3647	}
				3648	</pre>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3649	</div>
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3650
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3651	<!-- _______________________________________________________________________ -->
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3652	<div class="doc_subsubsection">
				3653	<a name="i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
				3654	</div>
				3655
				3656
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3657	<div class="doc_text">
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3658	<h5>Syntax:</h5>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3659	<pre> declare void %llvm.va_start(i8* <arglist>)<br></pre>
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3660	<h5>Overview:</h5>
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3661	<P>The '<tt>llvm.va_start</tt>' intrinsic initializes
				3662	<tt>*<arglist></tt> for subsequent use by <tt><a
				3663	href="#i_va_arg">va_arg</a></tt>.</p>
				3664
				3665	<h5>Arguments:</h5>
				3666
				3667	<P>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
				3668
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3669	<h5>Semantics:</h5>
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3670
				3671	<P>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
				3672	macro available in C. In a target-dependent way, it initializes the
				3673	<tt>va_list</tt> element the argument points to, so that the next call to
				3674	<tt>va_arg</tt> will produce the first variable argument passed to the function.
				3675	Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
				3676	last argument of the function, the compiler can figure that out.</p>
				3677
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3678	</div>
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3679
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3680	<!-- _______________________________________________________________________ -->
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3681	<div class="doc_subsubsection">
				3682	<a name="i_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
				3683	</div>
				3684
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3685	<div class="doc_text">
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3686	<h5>Syntax:</h5>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3687	<pre> declare void %llvm.va_end(i8* <arglist>)<br></pre>
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3688	<h5>Overview:</h5>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3689
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3690	<p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt><arglist></tt>
				3691	which has been initialized previously with <tt><a href="#i_va_start">llvm.va_start</a></tt>
				3692	or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3693
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3694	<h5>Arguments:</h5>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3695
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3696	<p>The argument is a <tt>va_list</tt> to destroy.</p>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3697
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3698	<h5>Semantics:</h5>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3699
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3700	<p>The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt>
Chris Lattner	48b383b0	2003-11-25 01:02:51 +0000	[diff] [blame]	3701	macro available in C. In a target-dependent way, it destroys the <tt>va_list</tt>.
				3702	Calls to <a href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
				3703	href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly
				3704	with calls to <tt>llvm.va_end</tt>.</p>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3705
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3706	</div>
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3707
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3708	<!-- _______________________________________________________________________ -->
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3709	<div class="doc_subsubsection">
				3710	<a name="i_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
				3711	</div>
				3712
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3713	<div class="doc_text">
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3714
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3715	<h5>Syntax:</h5>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3716
				3717	<pre>
Chris Lattner	db0790c	2007-01-08 07:55:15 +0000	[diff] [blame]	3718	declare void %llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3719	</pre>
				3720
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3721	<h5>Overview:</h5>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3722
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3723	<p>The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
				3724	the source argument list to the destination argument list.</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3725
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3726	<h5>Arguments:</h5>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3727
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3728	<p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
Andrew Lenharth	5305ea5	2005-06-22 20:38:11 +0000	[diff] [blame]	3729	The second argument is a pointer to a <tt>va_list</tt> element to copy from.</p>
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3730
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3731
Chris Lattner	bd64b4e	2003-05-08 04:57:36 +0000	[diff] [blame]	3732	<h5>Semantics:</h5>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3733
Andrew Lenharth	5fb787c	2005-06-18 18:28:17 +0000	[diff] [blame]	3734	<p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
				3735	available in C. In a target-dependent way, it copies the source
				3736	<tt>va_list</tt> element into the destination list. This intrinsic is necessary
				3737	because the <tt><a href="i_va_begin">llvm.va_begin</a></tt> intrinsic may be
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3738	arbitrarily complex and require memory allocation, for example.</p>
				3739
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	3740	</div>
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	3741
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	3742	<!-- ======================================================================= -->
				3743	<div class="doc_subsection">
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3744	<a name="int_gc">Accurate Garbage Collection Intrinsics</a>
				3745	</div>
				3746
				3747	<div class="doc_text">
				3748
				3749	<p>
				3750	LLVM support for <a href="GarbageCollection.html">Accurate Garbage
				3751	Collection</a> requires the implementation and generation of these intrinsics.
				3752	These intrinsics allow identification of <a href="#i_gcroot">GC roots on the
				3753	stack</a>, as well as garbage collector implementations that require <a
				3754	href="#i_gcread">read</a> and <a href="#i_gcwrite">write</a> barriers.
				3755	Front-ends for type-safe garbage collected languages should generate these
				3756	intrinsics to make use of the LLVM garbage collectors. For more details, see <a
				3757	href="GarbageCollection.html">Accurate Garbage Collection with LLVM</a>.
				3758	</p>
				3759	</div>
				3760
				3761	<!-- _______________________________________________________________________ -->
				3762	<div class="doc_subsubsection">
				3763	<a name="i_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
				3764	</div>
				3765
				3766	<div class="doc_text">
				3767
				3768	<h5>Syntax:</h5>
				3769
				3770	<pre>
Reid Spencer	7821d06	2005-04-26 20:50:44 +0000	[diff] [blame]	3771	declare void %llvm.gcroot(<ty>** %ptrloc, <ty2>* %metadata)
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3772	</pre>
				3773
				3774	<h5>Overview:</h5>
				3775
John Criswell	dfe6a86	2004-12-10 15:51:16 +0000	[diff] [blame]	3776	<p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3777	the code generator, and allows some metadata to be associated with it.</p>
				3778
				3779	<h5>Arguments:</h5>
				3780
				3781	<p>The first argument specifies the address of a stack object that contains the
				3782	root pointer. The second pointer (which must be either a constant or a global
				3783	value address) contains the meta-data to be associated with the root.</p>
				3784
				3785	<h5>Semantics:</h5>
				3786
				3787	<p>At runtime, a call to this intrinsics stores a null pointer into the "ptrloc"
				3788	location. At compile-time, the code generator generates information to allow
				3789	the runtime to find the pointer at GC safe points.
				3790	</p>
				3791
				3792	</div>
				3793
				3794
				3795	<!-- _______________________________________________________________________ -->
				3796	<div class="doc_subsubsection">
				3797	<a name="i_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
				3798	</div>
				3799
				3800	<div class="doc_text">
				3801
				3802	<h5>Syntax:</h5>
				3803
				3804	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3805	declare i8 * %llvm.gcread(i8 * %ObjPtr, i8 ** %Ptr)
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3806	</pre>
				3807
				3808	<h5>Overview:</h5>
				3809
				3810	<p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
				3811	locations, allowing garbage collector implementations that require read
				3812	barriers.</p>
				3813
				3814	<h5>Arguments:</h5>
				3815
Chris Lattner	f922807	2006-03-14 20:02:51 +0000	[diff] [blame]	3816	<p>The second argument is the address to read from, which should be an address
				3817	allocated from the garbage collector. The first object is a pointer to the
				3818	start of the referenced object, if needed by the language runtime (otherwise
				3819	null).</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3820
				3821	<h5>Semantics:</h5>
				3822
				3823	<p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
				3824	instruction, but may be replaced with substantially more complex code by the
				3825	garbage collector runtime, as needed.</p>
				3826
				3827	</div>
				3828
				3829
				3830	<!-- _______________________________________________________________________ -->
				3831	<div class="doc_subsubsection">
				3832	<a name="i_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
				3833	</div>
				3834
				3835	<div class="doc_text">
				3836
				3837	<h5>Syntax:</h5>
				3838
				3839	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3840	declare void %llvm.gcwrite(i8 * %P1, i8 * %Obj, i8 ** %P2)
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3841	</pre>
				3842
				3843	<h5>Overview:</h5>
				3844
				3845	<p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
				3846	locations, allowing garbage collector implementations that require write
				3847	barriers (such as generational or reference counting collectors).</p>
				3848
				3849	<h5>Arguments:</h5>
				3850
Chris Lattner	f922807	2006-03-14 20:02:51 +0000	[diff] [blame]	3851	<p>The first argument is the reference to store, the second is the start of the
				3852	object to store it to, and the third is the address of the field of Obj to
				3853	store to. If the runtime does not require a pointer to the object, Obj may be
				3854	null.</p>
Chris Lattner	757528b0b	2004-05-23 21:06:01 +0000	[diff] [blame]	3855
				3856	<h5>Semantics:</h5>
				3857
				3858	<p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
				3859	instruction, but may be replaced with substantially more complex code by the
				3860	garbage collector runtime, as needed.</p>
				3861
				3862	</div>
				3863
				3864
				3865
				3866	<!-- ======================================================================= -->
				3867	<div class="doc_subsection">
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	3868	<a name="int_codegen">Code Generator Intrinsics</a>
				3869	</div>
				3870
				3871	<div class="doc_text">
				3872	<p>
				3873	These intrinsics are provided by LLVM to expose special features that may only
				3874	be implemented with code generator support.
				3875	</p>
				3876
				3877	</div>
				3878
				3879	<!-- _______________________________________________________________________ -->
				3880	<div class="doc_subsubsection">
				3881	<a name="i_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
				3882	</div>
				3883
				3884	<div class="doc_text">
				3885
				3886	<h5>Syntax:</h5>
				3887	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3888	declare i8 *%llvm.returnaddress(i32 <level>)
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	3889	</pre>
				3890
				3891	<h5>Overview:</h5>
				3892
				3893	<p>
Chris Lattner	c1fb426	2006-10-15 20:05:59 +0000	[diff] [blame]	3894	The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
				3895	target-specific value indicating the return address of the current function
				3896	or one of its callers.
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	3897	</p>
				3898
				3899	<h5>Arguments:</h5>
				3900
				3901	<p>
				3902	The argument to this intrinsic indicates which function to return the address
				3903	for. Zero indicates the calling function, one indicates its caller, etc. The
				3904	argument is <b>required</b> to be a constant integer value.
				3905	</p>
				3906
				3907	<h5>Semantics:</h5>
				3908
				3909	<p>
				3910	The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer indicating
				3911	the return address of the specified call frame, or zero if it cannot be
				3912	identified. The value returned by this intrinsic is likely to be incorrect or 0
				3913	for arguments other than zero, so it should only be used for debugging purposes.
				3914	</p>
				3915
				3916	<p>
				3917	Note that calling this intrinsic does not prevent function inlining or other
Chris Lattner	2e6eb5f	2005-03-07 20:30:51 +0000	[diff] [blame]	3918	aggressive transformations, so the value returned may not be that of the obvious
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	3919	source-language caller.
				3920	</p>
				3921	</div>
				3922
				3923
				3924	<!-- _______________________________________________________________________ -->
				3925	<div class="doc_subsubsection">
				3926	<a name="i_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
				3927	</div>
				3928
				3929	<div class="doc_text">
				3930
				3931	<h5>Syntax:</h5>
				3932	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3933	declare i8 *%llvm.frameaddress(i32 <level>)
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	3934	</pre>
				3935
				3936	<h5>Overview:</h5>
				3937
				3938	<p>
Chris Lattner	c1fb426	2006-10-15 20:05:59 +0000	[diff] [blame]	3939	The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
				3940	target-specific frame pointer value for the specified stack frame.
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	3941	</p>
				3942
				3943	<h5>Arguments:</h5>
				3944
				3945	<p>
				3946	The argument to this intrinsic indicates which function to return the frame
				3947	pointer for. Zero indicates the calling function, one indicates its caller,
				3948	etc. The argument is <b>required</b> to be a constant integer value.
				3949	</p>
				3950
				3951	<h5>Semantics:</h5>
				3952
				3953	<p>
				3954	The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer indicating
				3955	the frame address of the specified call frame, or zero if it cannot be
				3956	identified. The value returned by this intrinsic is likely to be incorrect or 0
				3957	for arguments other than zero, so it should only be used for debugging purposes.
				3958	</p>
				3959
				3960	<p>
				3961	Note that calling this intrinsic does not prevent function inlining or other
Chris Lattner	2e6eb5f	2005-03-07 20:30:51 +0000	[diff] [blame]	3962	aggressive transformations, so the value returned may not be that of the obvious
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	3963	source-language caller.
				3964	</p>
				3965	</div>
				3966
Chris Lattner	c8a2c22	2005-02-28 19:24:19 +0000	[diff] [blame]	3967	<!-- _______________________________________________________________________ -->
				3968	<div class="doc_subsubsection">
Chris Lattner	2f0f001	2006-01-13 02:03:13 +0000	[diff] [blame]	3969	<a name="i_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
				3970	</div>
				3971
				3972	<div class="doc_text">
				3973
				3974	<h5>Syntax:</h5>
				3975	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	3976	declare i8 *%llvm.stacksave()
Chris Lattner	2f0f001	2006-01-13 02:03:13 +0000	[diff] [blame]	3977	</pre>
				3978
				3979	<h5>Overview:</h5>
				3980
				3981	<p>
				3982	The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state of
				3983	the function stack, for use with <a href="#i_stackrestore">
				3984	<tt>llvm.stackrestore</tt></a>. This is useful for implementing language
				3985	features like scoped automatic variable sized arrays in C99.
				3986	</p>
				3987
				3988	<h5>Semantics:</h5>
				3989
				3990	<p>
				3991	This intrinsic returns a opaque pointer value that can be passed to <a
				3992	href="#i_stackrestore"><tt>llvm.stackrestore</tt></a>. When an
				3993	<tt>llvm.stackrestore</tt> intrinsic is executed with a value saved from
				3994	<tt>llvm.stacksave</tt>, it effectively restores the state of the stack to the
				3995	state it was in when the <tt>llvm.stacksave</tt> intrinsic executed. In
				3996	practice, this pops any <a href="#i_alloca">alloca</a> blocks from the stack
				3997	that were allocated after the <tt>llvm.stacksave</tt> was executed.
				3998	</p>
				3999
				4000	</div>
				4001
				4002	<!-- _______________________________________________________________________ -->
				4003	<div class="doc_subsubsection">
				4004	<a name="i_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
				4005	</div>
				4006
				4007	<div class="doc_text">
				4008
				4009	<h5>Syntax:</h5>
				4010	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4011	declare void %llvm.stackrestore(i8 * %ptr)
Chris Lattner	2f0f001	2006-01-13 02:03:13 +0000	[diff] [blame]	4012	</pre>
				4013
				4014	<h5>Overview:</h5>
				4015
				4016	<p>
				4017	The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
				4018	the function stack to the state it was in when the corresponding <a
				4019	href="#llvm.stacksave"><tt>llvm.stacksave</tt></a> intrinsic executed. This is
				4020	useful for implementing language features like scoped automatic variable sized
				4021	arrays in C99.
				4022	</p>
				4023
				4024	<h5>Semantics:</h5>
				4025
				4026	<p>
				4027	See the description for <a href="#i_stacksave"><tt>llvm.stacksave</tt></a>.
				4028	</p>
				4029
				4030	</div>
				4031
				4032
				4033	<!-- _______________________________________________________________________ -->
				4034	<div class="doc_subsubsection">
Chris Lattner	c8a2c22	2005-02-28 19:24:19 +0000	[diff] [blame]	4035	<a name="i_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
				4036	</div>
				4037
				4038	<div class="doc_text">
				4039
				4040	<h5>Syntax:</h5>
				4041	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4042	declare void %llvm.prefetch(i8 * <address>,
				4043	i32 <rw>, i32 <locality>)
Chris Lattner	c8a2c22	2005-02-28 19:24:19 +0000	[diff] [blame]	4044	</pre>
				4045
				4046	<h5>Overview:</h5>
				4047
				4048
				4049	<p>
				4050	The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to insert
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	4051	a prefetch instruction if supported; otherwise, it is a noop. Prefetches have
				4052	no
				4053	effect on the behavior of the program but can change its performance
Chris Lattner	ff85107	2005-02-28 19:47:14 +0000	[diff] [blame]	4054	characteristics.
Chris Lattner	c8a2c22	2005-02-28 19:24:19 +0000	[diff] [blame]	4055	</p>
				4056
				4057	<h5>Arguments:</h5>
				4058
				4059	<p>
				4060	<tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the specifier
				4061	determining if the fetch should be for a read (0) or write (1), and
				4062	<tt>locality</tt> is a temporal locality specifier ranging from (0) - no
Chris Lattner	d3e641c	2005-03-07 20:31:38 +0000	[diff] [blame]	4063	locality, to (3) - extremely local keep in cache. The <tt>rw</tt> and
Chris Lattner	c8a2c22	2005-02-28 19:24:19 +0000	[diff] [blame]	4064	<tt>locality</tt> arguments must be constant integers.
				4065	</p>
				4066
				4067	<h5>Semantics:</h5>
				4068
				4069	<p>
				4070	This intrinsic does not modify the behavior of the program. In particular,
				4071	prefetches cannot trap and do not produce a value. On targets that support this
				4072	intrinsic, the prefetch can provide hints to the processor cache for better
				4073	performance.
				4074	</p>
				4075
				4076	</div>
				4077
Andrew Lenharth	b442791	2005-03-28 20:05:49 +0000	[diff] [blame]	4078	<!-- _______________________________________________________________________ -->
				4079	<div class="doc_subsubsection">
				4080	<a name="i_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
				4081	</div>
				4082
				4083	<div class="doc_text">
				4084
				4085	<h5>Syntax:</h5>
				4086	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4087	declare void %llvm.pcmarker( i32 <id> )
Andrew Lenharth	b442791	2005-03-28 20:05:49 +0000	[diff] [blame]	4088	</pre>
				4089
				4090	<h5>Overview:</h5>
				4091
				4092
				4093	<p>
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	4094	The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program Counter
				4095	(PC) in a region of
Andrew Lenharth	b442791	2005-03-28 20:05:49 +0000	[diff] [blame]	4096	code to simulators and other tools. The method is target specific, but it is
				4097	expected that the marker will use exported symbols to transmit the PC of the marker.
Jeff Cohen	dc6bfea	2005-11-11 02:15:27 +0000	[diff] [blame]	4098	The marker makes no guarantees that it will remain with any specific instruction
Chris Lattner	e64d41d	2005-11-15 06:07:55 +0000	[diff] [blame]	4099	after optimizations. It is possible that the presence of a marker will inhibit
Chris Lattner	b40261e	2006-03-24 07:16:10 +0000	[diff] [blame]	4100	optimizations. The intended use is to be inserted after optimizations to allow
John Criswell	8819056	2005-05-16 16:17:45 +0000	[diff] [blame]	4101	correlations of simulation runs.
Andrew Lenharth	b442791	2005-03-28 20:05:49 +0000	[diff] [blame]	4102	</p>
				4103
				4104	<h5>Arguments:</h5>
				4105
				4106	<p>
				4107	<tt>id</tt> is a numerical id identifying the marker.
				4108	</p>
				4109
				4110	<h5>Semantics:</h5>
				4111
				4112	<p>
				4113	This intrinsic does not modify the behavior of the program. Backends that do not
				4114	support this intrinisic may ignore it.
				4115	</p>
				4116
				4117	</div>
				4118
Andrew Lenharth	01aa563	2005-11-11 16:47:30 +0000	[diff] [blame]	4119	<!-- _______________________________________________________________________ -->
				4120	<div class="doc_subsubsection">
				4121	<a name="i_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
				4122	</div>
				4123
				4124	<div class="doc_text">
				4125
				4126	<h5>Syntax:</h5>
				4127	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4128	declare i64 %llvm.readcyclecounter( )
Andrew Lenharth	01aa563	2005-11-11 16:47:30 +0000	[diff] [blame]	4129	</pre>
				4130
				4131	<h5>Overview:</h5>
				4132
				4133
				4134	<p>
				4135	The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
				4136	counter register (or similar low latency, high accuracy clocks) on those targets
				4137	that support it. On X86, it should map to RDTSC. On Alpha, it should map to RPCC.
				4138	As the backing counters overflow quickly (on the order of 9 seconds on alpha), this
				4139	should only be used for small timings.
				4140	</p>
				4141
				4142	<h5>Semantics:</h5>
				4143
				4144	<p>
				4145	When directly supported, reading the cycle counter should not modify any memory.
				4146	Implementations are allowed to either return a application specific value or a
				4147	system wide value. On backends without support, this is lowered to a constant 0.
				4148	</p>
				4149
				4150	</div>
				4151
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4152	<!-- ======================================================================= -->
				4153	<div class="doc_subsection">
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	4154	<a name="int_libc">Standard C Library Intrinsics</a>
				4155	</div>
				4156
				4157	<div class="doc_text">
				4158	<p>
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4159	LLVM provides intrinsics for a few important standard C library functions.
				4160	These intrinsics allow source-language front-ends to pass information about the
				4161	alignment of the pointer arguments to the code generator, providing opportunity
				4162	for more efficient code generation.
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	4163	</p>
				4164
				4165	</div>
				4166
				4167	<!-- _______________________________________________________________________ -->
				4168	<div class="doc_subsubsection">
				4169	<a name="i_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
				4170	</div>
				4171
				4172	<div class="doc_text">
				4173
				4174	<h5>Syntax:</h5>
				4175	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4176	declare void %llvm.memcpy.i32(i8 * <dest>, i8 * <src>,
				4177	i32 <len>, i32 <align>)
				4178	declare void %llvm.memcpy.i64(i8 * <dest>, i8 * <src>,
				4179	i64 <len>, i32 <align>)
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	4180	</pre>
				4181
				4182	<h5>Overview:</h5>
				4183
				4184	<p>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4185	The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	4186	location to the destination location.
				4187	</p>
				4188
				4189	<p>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4190	Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
				4191	intrinsics do not return a value, and takes an extra alignment argument.
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	4192	</p>
				4193
				4194	<h5>Arguments:</h5>
				4195
				4196	<p>
				4197	The first argument is a pointer to the destination, the second is a pointer to
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4198	the source. The third argument is an integer argument
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	4199	specifying the number of bytes to copy, and the fourth argument is the alignment
				4200	of the source and destination locations.
				4201	</p>
				4202
Chris Lattner	4c67c48	2004-02-12 21:18:15 +0000	[diff] [blame]	4203	<p>
				4204	If the call to this intrinisic has an alignment value that is not 0 or 1, then
Chris Lattner	5316e5d	2006-03-04 00:02:10 +0000	[diff] [blame]	4205	the caller guarantees that both the source and destination pointers are aligned
				4206	to that boundary.
Chris Lattner	4c67c48	2004-02-12 21:18:15 +0000	[diff] [blame]	4207	</p>
				4208
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	4209	<h5>Semantics:</h5>
				4210
				4211	<p>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4212	The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the source
Chris Lattner	fee1146	2004-02-12 17:01:32 +0000	[diff] [blame]	4213	location to the destination location, which are not allowed to overlap. It
				4214	copies "len" bytes of memory over. If the argument is known to be aligned to
				4215	some boundary, this can be specified as the fourth argument, otherwise it should
				4216	be set to 0 or 1.
				4217	</p>
				4218	</div>
				4219
				4220
Chris Lattner	f30152e	2004-02-12 18:10:10 +0000	[diff] [blame]	4221	<!-- _______________________________________________________________________ -->
				4222	<div class="doc_subsubsection">
				4223	<a name="i_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
				4224	</div>
				4225
				4226	<div class="doc_text">
				4227
				4228	<h5>Syntax:</h5>
				4229	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4230	declare void %llvm.memmove.i32(i8 * <dest>, i8 * <src>,
				4231	i32 <len>, i32 <align>)
				4232	declare void %llvm.memmove.i64(i8 * <dest>, i8 * <src>,
				4233	i64 <len>, i32 <align>)
Chris Lattner	f30152e	2004-02-12 18:10:10 +0000	[diff] [blame]	4234	</pre>
				4235
				4236	<h5>Overview:</h5>
				4237
				4238	<p>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4239	The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the source
				4240	location to the destination location. It is similar to the
				4241	'<tt>llvm.memcmp</tt>' intrinsic but allows the two memory locations to overlap.
Chris Lattner	f30152e	2004-02-12 18:10:10 +0000	[diff] [blame]	4242	</p>
				4243
				4244	<p>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4245	Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
				4246	intrinsics do not return a value, and takes an extra alignment argument.
Chris Lattner	f30152e	2004-02-12 18:10:10 +0000	[diff] [blame]	4247	</p>
				4248
				4249	<h5>Arguments:</h5>
				4250
				4251	<p>
				4252	The first argument is a pointer to the destination, the second is a pointer to
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4253	the source. The third argument is an integer argument
Chris Lattner	f30152e	2004-02-12 18:10:10 +0000	[diff] [blame]	4254	specifying the number of bytes to copy, and the fourth argument is the alignment
				4255	of the source and destination locations.
				4256	</p>
				4257
Chris Lattner	4c67c48	2004-02-12 21:18:15 +0000	[diff] [blame]	4258	<p>
				4259	If the call to this intrinisic has an alignment value that is not 0 or 1, then
Chris Lattner	5316e5d	2006-03-04 00:02:10 +0000	[diff] [blame]	4260	the caller guarantees that the source and destination pointers are aligned to
				4261	that boundary.
Chris Lattner	4c67c48	2004-02-12 21:18:15 +0000	[diff] [blame]	4262	</p>
				4263
Chris Lattner	f30152e	2004-02-12 18:10:10 +0000	[diff] [blame]	4264	<h5>Semantics:</h5>
				4265
				4266	<p>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4267	The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the source
Chris Lattner	f30152e	2004-02-12 18:10:10 +0000	[diff] [blame]	4268	location to the destination location, which may overlap. It
				4269	copies "len" bytes of memory over. If the argument is known to be aligned to
				4270	some boundary, this can be specified as the fourth argument, otherwise it should
				4271	be set to 0 or 1.
				4272	</p>
				4273	</div>
				4274
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	4275
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4276	<!-- _______________________________________________________________________ -->
				4277	<div class="doc_subsubsection">
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4278	<a name="i_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4279	</div>
				4280
				4281	<div class="doc_text">
				4282
				4283	<h5>Syntax:</h5>
				4284	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4285	declare void %llvm.memset.i32(i8 * <dest>, i8 <val>,
				4286	i32 <len>, i32 <align>)
				4287	declare void %llvm.memset.i64(i8 * <dest>, i8 <val>,
				4288	i64 <len>, i32 <align>)
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4289	</pre>
				4290
				4291	<h5>Overview:</h5>
				4292
				4293	<p>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4294	The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a particular
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4295	byte value.
				4296	</p>
				4297
				4298	<p>
				4299	Note that, unlike the standard libc function, the <tt>llvm.memset</tt> intrinsic
				4300	does not return a value, and takes an extra alignment argument.
				4301	</p>
				4302
				4303	<h5>Arguments:</h5>
				4304
				4305	<p>
				4306	The first argument is a pointer to the destination to fill, the second is the
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4307	byte value to fill it with, the third argument is an integer
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4308	argument specifying the number of bytes to fill, and the fourth argument is the
				4309	known alignment of destination location.
				4310	</p>
				4311
				4312	<p>
				4313	If the call to this intrinisic has an alignment value that is not 0 or 1, then
Chris Lattner	5316e5d	2006-03-04 00:02:10 +0000	[diff] [blame]	4314	the caller guarantees that the destination pointer is aligned to that boundary.
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4315	</p>
				4316
				4317	<h5>Semantics:</h5>
				4318
				4319	<p>
Chris Lattner	0c8b259	2006-03-03 00:07:20 +0000	[diff] [blame]	4320	The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting at
				4321	the
Chris Lattner	3649c3a	2004-02-14 04:08:35 +0000	[diff] [blame]	4322	destination location. If the argument is known to be aligned to some boundary,
				4323	this can be specified as the fourth argument, otherwise it should be set to 0 or
				4324	1.
				4325	</p>
				4326	</div>
				4327
				4328
Chris Lattner	3b4f437	2004-06-11 02:28:03 +0000	[diff] [blame]	4329	<!-- _______________________________________________________________________ -->
				4330	<div class="doc_subsubsection">
Chris Lattner	069b5bd	2006-01-16 22:38:59 +0000	[diff] [blame]	4331	<a name="i_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
Chris Lattner	8a8f2e5	2005-07-21 01:29:16 +0000	[diff] [blame]	4332	</div>
				4333
				4334	<div class="doc_text">
				4335
				4336	<h5>Syntax:</h5>
				4337	<pre>
Chris Lattner	33b73f9	2006-09-08 06:34:02 +0000	[diff] [blame]	4338	declare float %llvm.sqrt.f32(float %Val)
				4339	declare double %llvm.sqrt.f64(double %Val)
Chris Lattner	8a8f2e5	2005-07-21 01:29:16 +0000	[diff] [blame]	4340	</pre>
				4341
				4342	<h5>Overview:</h5>
				4343
				4344	<p>
Reid Spencer	b4f9a6f	2006-01-16 21:12:35 +0000	[diff] [blame]	4345	The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
Chris Lattner	8a8f2e5	2005-07-21 01:29:16 +0000	[diff] [blame]	4346	returning the same value as the libm '<tt>sqrt</tt>' function would. Unlike
				4347	<tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined behavior for
				4348	negative numbers (which allows for better optimization).
				4349	</p>
				4350
				4351	<h5>Arguments:</h5>
				4352
				4353	<p>
				4354	The argument and return value are floating point numbers of the same type.
				4355	</p>
				4356
				4357	<h5>Semantics:</h5>
				4358
				4359	<p>
				4360	This function returns the sqrt of the specified operand if it is a positive
				4361	floating point number.
				4362	</p>
				4363	</div>
				4364
Chris Lattner	33b73f9	2006-09-08 06:34:02 +0000	[diff] [blame]	4365	<!-- _______________________________________________________________________ -->
				4366	<div class="doc_subsubsection">
				4367	<a name="i_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
				4368	</div>
				4369
				4370	<div class="doc_text">
				4371
				4372	<h5>Syntax:</h5>
				4373	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4374	declare float %llvm.powi.f32(float %Val, i32 %power)
				4375	declare double %llvm.powi.f64(double %Val, i32 %power)
Chris Lattner	33b73f9	2006-09-08 06:34:02 +0000	[diff] [blame]	4376	</pre>
				4377
				4378	<h5>Overview:</h5>
				4379
				4380	<p>
				4381	The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
				4382	specified (positive or negative) power. The order of evaluation of
				4383	multiplications is not defined.
				4384	</p>
				4385
				4386	<h5>Arguments:</h5>
				4387
				4388	<p>
				4389	The second argument is an integer power, and the first is a value to raise to
				4390	that power.
				4391	</p>
				4392
				4393	<h5>Semantics:</h5>
				4394
				4395	<p>
				4396	This function returns the first value raised to the second power with an
				4397	unspecified sequence of rounding operations.</p>
				4398	</div>
				4399
				4400
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4401	<!-- ======================================================================= -->
				4402	<div class="doc_subsection">
Nate Begeman	0f223bb	2006-01-13 23:26:38 +0000	[diff] [blame]	4403	<a name="int_manip">Bit Manipulation Intrinsics</a>
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4404	</div>
				4405
				4406	<div class="doc_text">
				4407	<p>
Nate Begeman	0f223bb	2006-01-13 23:26:38 +0000	[diff] [blame]	4408	LLVM provides intrinsics for a few important bit manipulation operations.
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4409	These allow efficient code generation for some algorithms.
				4410	</p>
				4411
				4412	</div>
				4413
				4414	<!-- _______________________________________________________________________ -->
				4415	<div class="doc_subsubsection">
Nate Begeman	0f223bb	2006-01-13 23:26:38 +0000	[diff] [blame]	4416	<a name="i_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
				4417	</div>
				4418
				4419	<div class="doc_text">
				4420
				4421	<h5>Syntax:</h5>
				4422	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4423	declare i16 %llvm.bswap.i16(i16 <id>)
				4424	declare i32 %llvm.bswap.i32(i32 <id>)
				4425	declare i64 %llvm.bswap.i64(i64 <id>)
Nate Begeman	0f223bb	2006-01-13 23:26:38 +0000	[diff] [blame]	4426	</pre>
				4427
				4428	<h5>Overview:</h5>
				4429
				4430	<p>
				4431	The '<tt>llvm.bwsap</tt>' family of intrinsics is used to byteswap a 16, 32 or
				4432	64 bit quantity. These are useful for performing operations on data that is not
				4433	in the target's native byte order.
				4434	</p>
				4435
				4436	<h5>Semantics:</h5>
				4437
				4438	<p>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4439	The <tt>llvm.bswap.16</tt> intrinsic returns an i16 value that has the high
				4440	and low byte of the input i16 swapped. Similarly, the <tt>llvm.bswap.i32</tt>
				4441	intrinsic returns an i32 value that has the four bytes of the input i32
				4442	swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the returned
				4443	i32 will have its bytes in 3, 2, 1, 0 order. The <tt>llvm.bswap.i64</tt>
				4444	intrinsic extends this concept to 64 bits.
Nate Begeman	0f223bb	2006-01-13 23:26:38 +0000	[diff] [blame]	4445	</p>
				4446
				4447	</div>
				4448
				4449	<!-- _______________________________________________________________________ -->
				4450	<div class="doc_subsubsection">
Reid Spencer	b4f9a6f	2006-01-16 21:12:35 +0000	[diff] [blame]	4451	<a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4452	</div>
				4453
				4454	<div class="doc_text">
				4455
				4456	<h5>Syntax:</h5>
				4457	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4458	declare i8 %llvm.ctpop.i8 (i8 <src>)
				4459	declare i16 %llvm.ctpop.i16(i16 <src>)
				4460	declare i32 %llvm.ctpop.i32(i32 <src>)
				4461	declare i64 %llvm.ctpop.i64(i64 <src>)
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4462	</pre>
				4463
				4464	<h5>Overview:</h5>
				4465
				4466	<p>
Chris Lattner	069b5bd	2006-01-16 22:38:59 +0000	[diff] [blame]	4467	The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set in a
				4468	value.
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4469	</p>
				4470
				4471	<h5>Arguments:</h5>
				4472
				4473	<p>
Chris Lattner	573f64e	2005-05-07 01:46:40 +0000	[diff] [blame]	4474	The only argument is the value to be counted. The argument may be of any
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	4475	integer type. The return type must match the argument type.
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4476	</p>
				4477
				4478	<h5>Semantics:</h5>
				4479
				4480	<p>
				4481	The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable.
				4482	</p>
				4483	</div>
				4484
				4485	<!-- _______________________________________________________________________ -->
				4486	<div class="doc_subsubsection">
Chris Lattner	b748c67	2006-01-16 22:34:14 +0000	[diff] [blame]	4487	<a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4488	</div>
				4489
				4490	<div class="doc_text">
				4491
				4492	<h5>Syntax:</h5>
				4493	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4494	declare i8 %llvm.ctlz.i8 (i8 <src>)
				4495	declare i16 %llvm.ctlz.i16(i16 <src>)
				4496	declare i32 %llvm.ctlz.i32(i32 <src>)
				4497	declare i64 %llvm.ctlz.i64(i64 <src>)
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4498	</pre>
				4499
				4500	<h5>Overview:</h5>
				4501
				4502	<p>
Reid Spencer	b4f9a6f	2006-01-16 21:12:35 +0000	[diff] [blame]	4503	The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
				4504	leading zeros in a variable.
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4505	</p>
				4506
				4507	<h5>Arguments:</h5>
				4508
				4509	<p>
Chris Lattner	573f64e	2005-05-07 01:46:40 +0000	[diff] [blame]	4510	The only argument is the value to be counted. The argument may be of any
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	4511	integer type. The return type must match the argument type.
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4512	</p>
				4513
				4514	<h5>Semantics:</h5>
				4515
				4516	<p>
Chris Lattner	efa20fa	2005-05-15 19:39:26 +0000	[diff] [blame]	4517	The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant) zeros
				4518	in a variable. If the src == 0 then the result is the size in bits of the type
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4519	of src. For example, <tt>llvm.ctlz(i32 2) = 30</tt>.
Andrew Lenharth	1d46352	2005-05-03 18:01:48 +0000	[diff] [blame]	4520	</p>
				4521	</div>
Chris Lattner	3b4f437	2004-06-11 02:28:03 +0000	[diff] [blame]	4522
				4523
Chris Lattner	efa20fa	2005-05-15 19:39:26 +0000	[diff] [blame]	4524
				4525	<!-- _______________________________________________________________________ -->
				4526	<div class="doc_subsubsection">
Chris Lattner	b748c67	2006-01-16 22:34:14 +0000	[diff] [blame]	4527	<a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
Chris Lattner	efa20fa	2005-05-15 19:39:26 +0000	[diff] [blame]	4528	</div>
				4529
				4530	<div class="doc_text">
				4531
				4532	<h5>Syntax:</h5>
				4533	<pre>
Reid Spencer	b5ebf3d	2006-12-31 07:07:53 +0000	[diff] [blame]	4534	declare i8 %llvm.cttz.i8 (i8 <src>)
				4535	declare i16 %llvm.cttz.i16(i16 <src>)
				4536	declare i32 %llvm.cttz.i32(i32 <src>)
				4537	declare i64 %llvm.cttz.i64(i64 <src>)
Chris Lattner	efa20fa	2005-05-15 19:39:26 +0000	[diff] [blame]	4538	</pre>
				4539
				4540	<h5>Overview:</h5>
				4541
				4542	<p>
Reid Spencer	b4f9a6f	2006-01-16 21:12:35 +0000	[diff] [blame]	4543	The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
				4544	trailing zeros.
Chris Lattner	efa20fa	2005-05-15 19:39:26 +0000	[diff] [blame]	4545	</p>
				4546
				4547	<h5>Arguments:</h5>
				4548
				4549	<p>
				4550	The only argument is the value to be counted. The argument may be of any
Reid Spencer	3e628eb9	2007-01-04 16:43:23 +0000	[diff] [blame]	4551	integer type. The return type must match the argument type.
Chris Lattner	efa20fa	2005-05-15 19:39:26 +0000	[diff] [blame]	4552	</p>
				4553
				4554	<h5>Semantics:</h5>
				4555
				4556	<p>
				4557	The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant) zeros
				4558	in a variable. If the src == 0 then the result is the size in bits of the type
				4559	of src. For example, <tt>llvm.cttz(2) = 1</tt>.
				4560	</p>
				4561	</div>
				4562
Chris Lattner	941515c	2004-01-06 05:31:32 +0000	[diff] [blame]	4563	<!-- ======================================================================= -->
				4564	<div class="doc_subsection">
				4565	<a name="int_debugger">Debugger Intrinsics</a>
				4566	</div>
				4567
				4568	<div class="doc_text">
				4569	<p>
				4570	The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt> prefix),
				4571	are described in the <a
				4572	href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source Level
				4573	Debugging</a> document.
				4574	</p>
				4575	</div>
				4576
				4577
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	4578	<!-- *********************************************************************** -->
Chris Lattner	2f7c963	2001-06-06 20:29:01 +0000	[diff] [blame]	4579	<hr>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	4580	<address>
				4581	<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
				4582	src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
				4583	<a href="http://validator.w3.org/check/referer"><img
				4584	src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
				4585
				4586	<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
Reid Spencer	ca05854	2006-03-14 05:39:39 +0000	[diff] [blame]	4587	<a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
Misha Brukman	c501f55	2004-03-01 17:47:27 +0000	[diff] [blame]	4588	Last modified: $Date$
				4589	</address>
Misha Brukman	7630785	2003-11-08 01:05:38 +0000	[diff] [blame]	4590	</body>
				4591	</html>