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

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