| 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>, 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> |