Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 1 | ============================== |
| 2 | LLVM Language Reference Manual |
| 3 | ============================== |
| 4 | |
| 5 | .. contents:: |
| 6 | :local: |
| 7 | :depth: 3 |
| 8 | |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 9 | Abstract |
| 10 | ======== |
| 11 | |
| 12 | This document is a reference manual for the LLVM assembly language. LLVM |
| 13 | is a Static Single Assignment (SSA) based representation that provides |
| 14 | type safety, low-level operations, flexibility, and the capability of |
| 15 | representing 'all' high-level languages cleanly. It is the common code |
| 16 | representation used throughout all phases of the LLVM compilation |
| 17 | strategy. |
| 18 | |
| 19 | Introduction |
| 20 | ============ |
| 21 | |
| 22 | The LLVM code representation is designed to be used in three different |
| 23 | forms: as an in-memory compiler IR, as an on-disk bitcode representation |
| 24 | (suitable for fast loading by a Just-In-Time compiler), and as a human |
| 25 | readable assembly language representation. This allows LLVM to provide a |
| 26 | powerful intermediate representation for efficient compiler |
| 27 | transformations and analysis, while providing a natural means to debug |
| 28 | and visualize the transformations. The three different forms of LLVM are |
| 29 | all equivalent. This document describes the human readable |
| 30 | representation and notation. |
| 31 | |
| 32 | The LLVM representation aims to be light-weight and low-level while |
| 33 | being expressive, typed, and extensible at the same time. It aims to be |
| 34 | a "universal IR" of sorts, by being at a low enough level that |
| 35 | high-level ideas may be cleanly mapped to it (similar to how |
| 36 | microprocessors are "universal IR's", allowing many source languages to |
| 37 | be mapped to them). By providing type information, LLVM can be used as |
| 38 | the target of optimizations: for example, through pointer analysis, it |
| 39 | can be proven that a C automatic variable is never accessed outside of |
| 40 | the current function, allowing it to be promoted to a simple SSA value |
| 41 | instead of a memory location. |
| 42 | |
| 43 | .. _wellformed: |
| 44 | |
| 45 | Well-Formedness |
| 46 | --------------- |
| 47 | |
| 48 | It is important to note that this document describes 'well formed' LLVM |
| 49 | assembly language. There is a difference between what the parser accepts |
| 50 | and what is considered 'well formed'. For example, the following |
| 51 | instruction is syntactically okay, but not well formed: |
| 52 | |
| 53 | .. code-block:: llvm |
| 54 | |
| 55 | %x = add i32 1, %x |
| 56 | |
| 57 | because the definition of ``%x`` does not dominate all of its uses. The |
| 58 | LLVM infrastructure provides a verification pass that may be used to |
| 59 | verify that an LLVM module is well formed. This pass is automatically |
| 60 | run by the parser after parsing input assembly and by the optimizer |
| 61 | before it outputs bitcode. The violations pointed out by the verifier |
| 62 | pass indicate bugs in transformation passes or input to the parser. |
| 63 | |
| 64 | .. _identifiers: |
| 65 | |
| 66 | Identifiers |
| 67 | =========== |
| 68 | |
| 69 | LLVM identifiers come in two basic types: global and local. Global |
| 70 | identifiers (functions, global variables) begin with the ``'@'`` |
| 71 | character. Local identifiers (register names, types) begin with the |
| 72 | ``'%'`` character. Additionally, there are three different formats for |
| 73 | identifiers, for different purposes: |
| 74 | |
| 75 | #. Named values are represented as a string of characters with their |
| 76 | prefix. For example, ``%foo``, ``@DivisionByZero``, |
| 77 | ``%a.really.long.identifier``. The actual regular expression used is |
| 78 | '``[%@][a-zA-Z$._][a-zA-Z$._0-9]*``'. Identifiers which require other |
| 79 | characters in their names can be surrounded with quotes. Special |
| 80 | characters may be escaped using ``"\xx"`` where ``xx`` is the ASCII |
| 81 | code for the character in hexadecimal. In this way, any character can |
| 82 | be used in a name value, even quotes themselves. |
| 83 | #. Unnamed values are represented as an unsigned numeric value with |
| 84 | their prefix. For example, ``%12``, ``@2``, ``%44``. |
| 85 | #. Constants, which are described in the section Constants_ below. |
| 86 | |
| 87 | LLVM requires that values start with a prefix for two reasons: Compilers |
| 88 | don't need to worry about name clashes with reserved words, and the set |
| 89 | of reserved words may be expanded in the future without penalty. |
| 90 | Additionally, unnamed identifiers allow a compiler to quickly come up |
| 91 | with a temporary variable without having to avoid symbol table |
| 92 | conflicts. |
| 93 | |
| 94 | Reserved words in LLVM are very similar to reserved words in other |
| 95 | languages. There are keywords for different opcodes ('``add``', |
| 96 | '``bitcast``', '``ret``', etc...), for primitive type names ('``void``', |
| 97 | '``i32``', etc...), and others. These reserved words cannot conflict |
| 98 | with variable names, because none of them start with a prefix character |
| 99 | (``'%'`` or ``'@'``). |
| 100 | |
| 101 | Here is an example of LLVM code to multiply the integer variable |
| 102 | '``%X``' by 8: |
| 103 | |
| 104 | The easy way: |
| 105 | |
| 106 | .. code-block:: llvm |
| 107 | |
| 108 | %result = mul i32 %X, 8 |
| 109 | |
| 110 | After strength reduction: |
| 111 | |
| 112 | .. code-block:: llvm |
| 113 | |
Dmitri Gribenko | 126fde5 | 2013-01-26 13:30:13 +0000 | [diff] [blame] | 114 | %result = shl i32 %X, 3 |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 115 | |
| 116 | And the hard way: |
| 117 | |
| 118 | .. code-block:: llvm |
| 119 | |
| 120 | %0 = add i32 %X, %X ; yields {i32}:%0 |
| 121 | %1 = add i32 %0, %0 ; yields {i32}:%1 |
| 122 | %result = add i32 %1, %1 |
| 123 | |
| 124 | This last way of multiplying ``%X`` by 8 illustrates several important |
| 125 | lexical features of LLVM: |
| 126 | |
| 127 | #. Comments are delimited with a '``;``' and go until the end of line. |
| 128 | #. Unnamed temporaries are created when the result of a computation is |
| 129 | not assigned to a named value. |
| 130 | #. Unnamed temporaries are numbered sequentially |
| 131 | |
| 132 | It also shows a convention that we follow in this document. When |
| 133 | demonstrating instructions, we will follow an instruction with a comment |
| 134 | that defines the type and name of value produced. |
| 135 | |
| 136 | High Level Structure |
| 137 | ==================== |
| 138 | |
| 139 | Module Structure |
| 140 | ---------------- |
| 141 | |
| 142 | LLVM programs are composed of ``Module``'s, each of which is a |
| 143 | translation unit of the input programs. Each module consists of |
| 144 | functions, global variables, and symbol table entries. Modules may be |
| 145 | combined together with the LLVM linker, which merges function (and |
| 146 | global variable) definitions, resolves forward declarations, and merges |
| 147 | symbol table entries. Here is an example of the "hello world" module: |
| 148 | |
| 149 | .. code-block:: llvm |
| 150 | |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 151 | ; Declare the string constant as a global constant. |
| 152 | @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 153 | |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 154 | ; External declaration of the puts function |
| 155 | declare i32 @puts(i8* nocapture) nounwind |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 156 | |
| 157 | ; Definition of main function |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 158 | define i32 @main() { ; i32()* |
| 159 | ; Convert [13 x i8]* to i8 *... |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 160 | %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0 |
| 161 | |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 162 | ; Call puts function to write out the string to stdout. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 163 | call i32 @puts(i8* %cast210) |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 164 | ret i32 0 |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 165 | } |
| 166 | |
| 167 | ; Named metadata |
| 168 | !1 = metadata !{i32 42} |
| 169 | !foo = !{!1, null} |
| 170 | |
| 171 | This example is made up of a :ref:`global variable <globalvars>` named |
| 172 | "``.str``", an external declaration of the "``puts``" function, a |
| 173 | :ref:`function definition <functionstructure>` for "``main``" and |
| 174 | :ref:`named metadata <namedmetadatastructure>` "``foo``". |
| 175 | |
| 176 | In general, a module is made up of a list of global values (where both |
| 177 | functions and global variables are global values). Global values are |
| 178 | represented by a pointer to a memory location (in this case, a pointer |
| 179 | to an array of char, and a pointer to a function), and have one of the |
| 180 | following :ref:`linkage types <linkage>`. |
| 181 | |
| 182 | .. _linkage: |
| 183 | |
| 184 | Linkage Types |
| 185 | ------------- |
| 186 | |
| 187 | All Global Variables and Functions have one of the following types of |
| 188 | linkage: |
| 189 | |
| 190 | ``private`` |
| 191 | Global values with "``private``" linkage are only directly |
| 192 | accessible by objects in the current module. In particular, linking |
| 193 | code into a module with an private global value may cause the |
| 194 | private to be renamed as necessary to avoid collisions. Because the |
| 195 | symbol is private to the module, all references can be updated. This |
| 196 | doesn't show up in any symbol table in the object file. |
| 197 | ``linker_private`` |
| 198 | Similar to ``private``, but the symbol is passed through the |
| 199 | assembler and evaluated by the linker. Unlike normal strong symbols, |
| 200 | they are removed by the linker from the final linked image |
| 201 | (executable or dynamic library). |
| 202 | ``linker_private_weak`` |
| 203 | Similar to "``linker_private``", but the symbol is weak. Note that |
| 204 | ``linker_private_weak`` symbols are subject to coalescing by the |
| 205 | linker. The symbols are removed by the linker from the final linked |
| 206 | image (executable or dynamic library). |
| 207 | ``internal`` |
| 208 | Similar to private, but the value shows as a local symbol |
| 209 | (``STB_LOCAL`` in the case of ELF) in the object file. This |
| 210 | corresponds to the notion of the '``static``' keyword in C. |
| 211 | ``available_externally`` |
| 212 | Globals with "``available_externally``" linkage are never emitted |
| 213 | into the object file corresponding to the LLVM module. They exist to |
| 214 | allow inlining and other optimizations to take place given knowledge |
| 215 | of the definition of the global, which is known to be somewhere |
| 216 | outside the module. Globals with ``available_externally`` linkage |
| 217 | are allowed to be discarded at will, and are otherwise the same as |
| 218 | ``linkonce_odr``. This linkage type is only allowed on definitions, |
| 219 | not declarations. |
| 220 | ``linkonce`` |
| 221 | Globals with "``linkonce``" linkage are merged with other globals of |
| 222 | the same name when linkage occurs. This can be used to implement |
| 223 | some forms of inline functions, templates, or other code which must |
| 224 | be generated in each translation unit that uses it, but where the |
| 225 | body may be overridden with a more definitive definition later. |
| 226 | Unreferenced ``linkonce`` globals are allowed to be discarded. Note |
| 227 | that ``linkonce`` linkage does not actually allow the optimizer to |
| 228 | inline the body of this function into callers because it doesn't |
| 229 | know if this definition of the function is the definitive definition |
| 230 | within the program or whether it will be overridden by a stronger |
| 231 | definition. To enable inlining and other optimizations, use |
| 232 | "``linkonce_odr``" linkage. |
| 233 | ``weak`` |
| 234 | "``weak``" linkage has the same merging semantics as ``linkonce`` |
| 235 | linkage, except that unreferenced globals with ``weak`` linkage may |
| 236 | not be discarded. This is used for globals that are declared "weak" |
| 237 | in C source code. |
| 238 | ``common`` |
| 239 | "``common``" linkage is most similar to "``weak``" linkage, but they |
| 240 | are used for tentative definitions in C, such as "``int X;``" at |
| 241 | global scope. Symbols with "``common``" linkage are merged in the |
| 242 | same way as ``weak symbols``, and they may not be deleted if |
| 243 | unreferenced. ``common`` symbols may not have an explicit section, |
| 244 | must have a zero initializer, and may not be marked |
| 245 | ':ref:`constant <globalvars>`'. Functions and aliases may not have |
| 246 | common linkage. |
| 247 | |
| 248 | .. _linkage_appending: |
| 249 | |
| 250 | ``appending`` |
| 251 | "``appending``" linkage may only be applied to global variables of |
| 252 | pointer to array type. When two global variables with appending |
| 253 | linkage are linked together, the two global arrays are appended |
| 254 | together. This is the LLVM, typesafe, equivalent of having the |
| 255 | system linker append together "sections" with identical names when |
| 256 | .o files are linked. |
| 257 | ``extern_weak`` |
| 258 | The semantics of this linkage follow the ELF object file model: the |
| 259 | symbol is weak until linked, if not linked, the symbol becomes null |
| 260 | instead of being an undefined reference. |
| 261 | ``linkonce_odr``, ``weak_odr`` |
| 262 | Some languages allow differing globals to be merged, such as two |
| 263 | functions with different semantics. Other languages, such as |
| 264 | ``C++``, ensure that only equivalent globals are ever merged (the |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 265 | "one definition rule" --- "ODR"). Such languages can use the |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 266 | ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the |
| 267 | global will only be merged with equivalent globals. These linkage |
| 268 | types are otherwise the same as their non-``odr`` versions. |
| 269 | ``linkonce_odr_auto_hide`` |
| 270 | Similar to "``linkonce_odr``", but nothing in the translation unit |
| 271 | takes the address of this definition. For instance, functions that |
| 272 | had an inline definition, but the compiler decided not to inline it. |
| 273 | ``linkonce_odr_auto_hide`` may have only ``default`` visibility. The |
| 274 | symbols are removed by the linker from the final linked image |
| 275 | (executable or dynamic library). |
| 276 | ``external`` |
| 277 | If none of the above identifiers are used, the global is externally |
| 278 | visible, meaning that it participates in linkage and can be used to |
| 279 | resolve external symbol references. |
| 280 | |
| 281 | The next two types of linkage are targeted for Microsoft Windows |
| 282 | platform only. They are designed to support importing (exporting) |
| 283 | symbols from (to) DLLs (Dynamic Link Libraries). |
| 284 | |
| 285 | ``dllimport`` |
| 286 | "``dllimport``" linkage causes the compiler to reference a function |
| 287 | or variable via a global pointer to a pointer that is set up by the |
| 288 | DLL exporting the symbol. On Microsoft Windows targets, the pointer |
| 289 | name is formed by combining ``__imp_`` and the function or variable |
| 290 | name. |
| 291 | ``dllexport`` |
| 292 | "``dllexport``" linkage causes the compiler to provide a global |
| 293 | pointer to a pointer in a DLL, so that it can be referenced with the |
| 294 | ``dllimport`` attribute. On Microsoft Windows targets, the pointer |
| 295 | name is formed by combining ``__imp_`` and the function or variable |
| 296 | name. |
| 297 | |
| 298 | For example, since the "``.LC0``" variable is defined to be internal, if |
| 299 | another module defined a "``.LC0``" variable and was linked with this |
| 300 | one, one of the two would be renamed, preventing a collision. Since |
| 301 | "``main``" and "``puts``" are external (i.e., lacking any linkage |
| 302 | declarations), they are accessible outside of the current module. |
| 303 | |
| 304 | It is illegal for a function *declaration* to have any linkage type |
| 305 | other than ``external``, ``dllimport`` or ``extern_weak``. |
| 306 | |
| 307 | Aliases can have only ``external``, ``internal``, ``weak`` or |
| 308 | ``weak_odr`` linkages. |
| 309 | |
| 310 | .. _callingconv: |
| 311 | |
| 312 | Calling Conventions |
| 313 | ------------------- |
| 314 | |
| 315 | LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and |
| 316 | :ref:`invokes <i_invoke>` can all have an optional calling convention |
| 317 | specified for the call. The calling convention of any pair of dynamic |
| 318 | caller/callee must match, or the behavior of the program is undefined. |
| 319 | The following calling conventions are supported by LLVM, and more may be |
| 320 | added in the future: |
| 321 | |
| 322 | "``ccc``" - The C calling convention |
| 323 | This calling convention (the default if no other calling convention |
| 324 | is specified) matches the target C calling conventions. This calling |
| 325 | convention supports varargs function calls and tolerates some |
| 326 | mismatch in the declared prototype and implemented declaration of |
| 327 | the function (as does normal C). |
| 328 | "``fastcc``" - The fast calling convention |
| 329 | This calling convention attempts to make calls as fast as possible |
| 330 | (e.g. by passing things in registers). This calling convention |
| 331 | allows the target to use whatever tricks it wants to produce fast |
| 332 | code for the target, without having to conform to an externally |
| 333 | specified ABI (Application Binary Interface). `Tail calls can only |
| 334 | be optimized when this, the GHC or the HiPE convention is |
| 335 | used. <CodeGenerator.html#id80>`_ This calling convention does not |
| 336 | support varargs and requires the prototype of all callees to exactly |
| 337 | match the prototype of the function definition. |
| 338 | "``coldcc``" - The cold calling convention |
| 339 | This calling convention attempts to make code in the caller as |
| 340 | efficient as possible under the assumption that the call is not |
| 341 | commonly executed. As such, these calls often preserve all registers |
| 342 | so that the call does not break any live ranges in the caller side. |
| 343 | This calling convention does not support varargs and requires the |
| 344 | prototype of all callees to exactly match the prototype of the |
| 345 | function definition. |
| 346 | "``cc 10``" - GHC convention |
| 347 | This calling convention has been implemented specifically for use by |
| 348 | the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_. |
| 349 | It passes everything in registers, going to extremes to achieve this |
| 350 | by disabling callee save registers. This calling convention should |
| 351 | not be used lightly but only for specific situations such as an |
| 352 | alternative to the *register pinning* performance technique often |
| 353 | used when implementing functional programming languages. At the |
| 354 | moment only X86 supports this convention and it has the following |
| 355 | limitations: |
| 356 | |
| 357 | - On *X86-32* only supports up to 4 bit type parameters. No |
| 358 | floating point types are supported. |
| 359 | - On *X86-64* only supports up to 10 bit type parameters and 6 |
| 360 | floating point parameters. |
| 361 | |
| 362 | This calling convention supports `tail call |
| 363 | optimization <CodeGenerator.html#id80>`_ but requires both the |
| 364 | caller and callee are using it. |
| 365 | "``cc 11``" - The HiPE calling convention |
| 366 | This calling convention has been implemented specifically for use by |
| 367 | the `High-Performance Erlang |
| 368 | (HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the* |
| 369 | native code compiler of the `Ericsson's Open Source Erlang/OTP |
| 370 | system <http://www.erlang.org/download.shtml>`_. It uses more |
| 371 | registers for argument passing than the ordinary C calling |
| 372 | convention and defines no callee-saved registers. The calling |
| 373 | convention properly supports `tail call |
| 374 | optimization <CodeGenerator.html#id80>`_ but requires that both the |
| 375 | caller and the callee use it. It uses a *register pinning* |
| 376 | mechanism, similar to GHC's convention, for keeping frequently |
| 377 | accessed runtime components pinned to specific hardware registers. |
| 378 | At the moment only X86 supports this convention (both 32 and 64 |
| 379 | bit). |
| 380 | "``cc <n>``" - Numbered convention |
| 381 | Any calling convention may be specified by number, allowing |
| 382 | target-specific calling conventions to be used. Target specific |
| 383 | calling conventions start at 64. |
| 384 | |
| 385 | More calling conventions can be added/defined on an as-needed basis, to |
| 386 | support Pascal conventions or any other well-known target-independent |
| 387 | convention. |
| 388 | |
| 389 | Visibility Styles |
| 390 | ----------------- |
| 391 | |
| 392 | All Global Variables and Functions have one of the following visibility |
| 393 | styles: |
| 394 | |
| 395 | "``default``" - Default style |
| 396 | On targets that use the ELF object file format, default visibility |
| 397 | means that the declaration is visible to other modules and, in |
| 398 | shared libraries, means that the declared entity may be overridden. |
| 399 | On Darwin, default visibility means that the declaration is visible |
| 400 | to other modules. Default visibility corresponds to "external |
| 401 | linkage" in the language. |
| 402 | "``hidden``" - Hidden style |
| 403 | Two declarations of an object with hidden visibility refer to the |
| 404 | same object if they are in the same shared object. Usually, hidden |
| 405 | visibility indicates that the symbol will not be placed into the |
| 406 | dynamic symbol table, so no other module (executable or shared |
| 407 | library) can reference it directly. |
| 408 | "``protected``" - Protected style |
| 409 | On ELF, protected visibility indicates that the symbol will be |
| 410 | placed in the dynamic symbol table, but that references within the |
| 411 | defining module will bind to the local symbol. That is, the symbol |
| 412 | cannot be overridden by another module. |
| 413 | |
| 414 | Named Types |
| 415 | ----------- |
| 416 | |
| 417 | LLVM IR allows you to specify name aliases for certain types. This can |
| 418 | make it easier to read the IR and make the IR more condensed |
| 419 | (particularly when recursive types are involved). An example of a name |
| 420 | specification is: |
| 421 | |
| 422 | .. code-block:: llvm |
| 423 | |
| 424 | %mytype = type { %mytype*, i32 } |
| 425 | |
| 426 | You may give a name to any :ref:`type <typesystem>` except |
| 427 | ":ref:`void <t_void>`". Type name aliases may be used anywhere a type is |
| 428 | expected with the syntax "%mytype". |
| 429 | |
| 430 | Note that type names are aliases for the structural type that they |
| 431 | indicate, and that you can therefore specify multiple names for the same |
| 432 | type. This often leads to confusing behavior when dumping out a .ll |
| 433 | file. Since LLVM IR uses structural typing, the name is not part of the |
| 434 | type. When printing out LLVM IR, the printer will pick *one name* to |
| 435 | render all types of a particular shape. This means that if you have code |
| 436 | where two different source types end up having the same LLVM type, that |
| 437 | the dumper will sometimes print the "wrong" or unexpected type. This is |
| 438 | an important design point and isn't going to change. |
| 439 | |
| 440 | .. _globalvars: |
| 441 | |
| 442 | Global Variables |
| 443 | ---------------- |
| 444 | |
| 445 | Global variables define regions of memory allocated at compilation time |
| 446 | instead of run-time. Global variables may optionally be initialized, may |
| 447 | have an explicit section to be placed in, and may have an optional |
| 448 | explicit alignment specified. |
| 449 | |
| 450 | A variable may be defined as ``thread_local``, which means that it will |
| 451 | not be shared by threads (each thread will have a separated copy of the |
| 452 | variable). Not all targets support thread-local variables. Optionally, a |
| 453 | TLS model may be specified: |
| 454 | |
| 455 | ``localdynamic`` |
| 456 | For variables that are only used within the current shared library. |
| 457 | ``initialexec`` |
| 458 | For variables in modules that will not be loaded dynamically. |
| 459 | ``localexec`` |
| 460 | For variables defined in the executable and only used within it. |
| 461 | |
| 462 | The models correspond to the ELF TLS models; see `ELF Handling For |
| 463 | Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for |
| 464 | more information on under which circumstances the different models may |
| 465 | be used. The target may choose a different TLS model if the specified |
| 466 | model is not supported, or if a better choice of model can be made. |
| 467 | |
Michael Gottesman | f573588 | 2013-01-31 05:48:48 +0000 | [diff] [blame] | 468 | A variable may be defined as a global ``constant``, which indicates that |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 469 | the contents of the variable will **never** be modified (enabling better |
| 470 | optimization, allowing the global data to be placed in the read-only |
| 471 | section of an executable, etc). Note that variables that need runtime |
Michael Gottesman | 3480487 | 2013-01-31 05:44:04 +0000 | [diff] [blame] | 472 | initialization cannot be marked ``constant`` as there is a store to the |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 473 | variable. |
| 474 | |
| 475 | LLVM explicitly allows *declarations* of global variables to be marked |
| 476 | constant, even if the final definition of the global is not. This |
| 477 | capability can be used to enable slightly better optimization of the |
| 478 | program, but requires the language definition to guarantee that |
| 479 | optimizations based on the 'constantness' are valid for the translation |
| 480 | units that do not include the definition. |
| 481 | |
| 482 | As SSA values, global variables define pointer values that are in scope |
| 483 | (i.e. they dominate) all basic blocks in the program. Global variables |
| 484 | always define a pointer to their "content" type because they describe a |
| 485 | region of memory, and all memory objects in LLVM are accessed through |
| 486 | pointers. |
| 487 | |
| 488 | Global variables can be marked with ``unnamed_addr`` which indicates |
| 489 | that the address is not significant, only the content. Constants marked |
| 490 | like this can be merged with other constants if they have the same |
| 491 | initializer. Note that a constant with significant address *can* be |
| 492 | merged with a ``unnamed_addr`` constant, the result being a constant |
| 493 | whose address is significant. |
| 494 | |
| 495 | A global variable may be declared to reside in a target-specific |
| 496 | numbered address space. For targets that support them, address spaces |
| 497 | may affect how optimizations are performed and/or what target |
| 498 | instructions are used to access the variable. The default address space |
| 499 | is zero. The address space qualifier must precede any other attributes. |
| 500 | |
| 501 | LLVM allows an explicit section to be specified for globals. If the |
| 502 | target supports it, it will emit globals to the section specified. |
| 503 | |
| 504 | An explicit alignment may be specified for a global, which must be a |
| 505 | power of 2. If not present, or if the alignment is set to zero, the |
| 506 | alignment of the global is set by the target to whatever it feels |
| 507 | convenient. If an explicit alignment is specified, the global is forced |
| 508 | to have exactly that alignment. Targets and optimizers are not allowed |
| 509 | to over-align the global if the global has an assigned section. In this |
| 510 | case, the extra alignment could be observable: for example, code could |
| 511 | assume that the globals are densely packed in their section and try to |
| 512 | iterate over them as an array, alignment padding would break this |
| 513 | iteration. |
| 514 | |
| 515 | For example, the following defines a global in a numbered address space |
| 516 | with an initializer, section, and alignment: |
| 517 | |
| 518 | .. code-block:: llvm |
| 519 | |
| 520 | @G = addrspace(5) constant float 1.0, section "foo", align 4 |
| 521 | |
| 522 | The following example defines a thread-local global with the |
| 523 | ``initialexec`` TLS model: |
| 524 | |
| 525 | .. code-block:: llvm |
| 526 | |
| 527 | @G = thread_local(initialexec) global i32 0, align 4 |
| 528 | |
| 529 | .. _functionstructure: |
| 530 | |
| 531 | Functions |
| 532 | --------- |
| 533 | |
| 534 | LLVM function definitions consist of the "``define``" keyword, an |
| 535 | optional :ref:`linkage type <linkage>`, an optional :ref:`visibility |
| 536 | style <visibility>`, an optional :ref:`calling convention <callingconv>`, |
| 537 | an optional ``unnamed_addr`` attribute, a return type, an optional |
| 538 | :ref:`parameter attribute <paramattrs>` for the return type, a function |
| 539 | name, a (possibly empty) argument list (each with optional :ref:`parameter |
| 540 | attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`, |
| 541 | an optional section, an optional alignment, an optional :ref:`garbage |
| 542 | collector name <gc>`, an opening curly brace, a list of basic blocks, |
| 543 | and a closing curly brace. |
| 544 | |
| 545 | LLVM function declarations consist of the "``declare``" keyword, an |
| 546 | optional :ref:`linkage type <linkage>`, an optional :ref:`visibility |
| 547 | style <visibility>`, an optional :ref:`calling convention <callingconv>`, |
| 548 | an optional ``unnamed_addr`` attribute, a return type, an optional |
| 549 | :ref:`parameter attribute <paramattrs>` for the return type, a function |
| 550 | name, a possibly empty list of arguments, an optional alignment, and an |
| 551 | optional :ref:`garbage collector name <gc>`. |
| 552 | |
| 553 | A function definition contains a list of basic blocks, forming the CFG |
| 554 | (Control Flow Graph) for the function. Each basic block may optionally |
| 555 | start with a label (giving the basic block a symbol table entry), |
| 556 | contains a list of instructions, and ends with a |
| 557 | :ref:`terminator <terminators>` instruction (such as a branch or function |
| 558 | return). |
| 559 | |
| 560 | The first basic block in a function is special in two ways: it is |
| 561 | immediately executed on entrance to the function, and it is not allowed |
| 562 | to have predecessor basic blocks (i.e. there can not be any branches to |
| 563 | the entry block of a function). Because the block can have no |
| 564 | predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`. |
| 565 | |
| 566 | LLVM allows an explicit section to be specified for functions. If the |
| 567 | target supports it, it will emit functions to the section specified. |
| 568 | |
| 569 | An explicit alignment may be specified for a function. If not present, |
| 570 | or if the alignment is set to zero, the alignment of the function is set |
| 571 | by the target to whatever it feels convenient. If an explicit alignment |
| 572 | is specified, the function is forced to have at least that much |
| 573 | alignment. All alignments must be a power of 2. |
| 574 | |
| 575 | If the ``unnamed_addr`` attribute is given, the address is know to not |
| 576 | be significant and two identical functions can be merged. |
| 577 | |
| 578 | Syntax:: |
| 579 | |
| 580 | define [linkage] [visibility] |
| 581 | [cconv] [ret attrs] |
| 582 | <ResultType> @<FunctionName> ([argument list]) |
| 583 | [fn Attrs] [section "name"] [align N] |
| 584 | [gc] { ... } |
| 585 | |
| 586 | Aliases |
| 587 | ------- |
| 588 | |
| 589 | Aliases act as "second name" for the aliasee value (which can be either |
| 590 | function, global variable, another alias or bitcast of global value). |
| 591 | Aliases may have an optional :ref:`linkage type <linkage>`, and an optional |
| 592 | :ref:`visibility style <visibility>`. |
| 593 | |
| 594 | Syntax:: |
| 595 | |
| 596 | @<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee> |
| 597 | |
| 598 | .. _namedmetadatastructure: |
| 599 | |
| 600 | Named Metadata |
| 601 | -------------- |
| 602 | |
| 603 | Named metadata is a collection of metadata. :ref:`Metadata |
| 604 | nodes <metadata>` (but not metadata strings) are the only valid |
| 605 | operands for a named metadata. |
| 606 | |
| 607 | Syntax:: |
| 608 | |
| 609 | ; Some unnamed metadata nodes, which are referenced by the named metadata. |
| 610 | !0 = metadata !{metadata !"zero"} |
| 611 | !1 = metadata !{metadata !"one"} |
| 612 | !2 = metadata !{metadata !"two"} |
| 613 | ; A named metadata. |
| 614 | !name = !{!0, !1, !2} |
| 615 | |
| 616 | .. _paramattrs: |
| 617 | |
| 618 | Parameter Attributes |
| 619 | -------------------- |
| 620 | |
| 621 | The return type and each parameter of a function type may have a set of |
| 622 | *parameter attributes* associated with them. Parameter attributes are |
| 623 | used to communicate additional information about the result or |
| 624 | parameters of a function. Parameter attributes are considered to be part |
| 625 | of the function, not of the function type, so functions with different |
| 626 | parameter attributes can have the same function type. |
| 627 | |
| 628 | Parameter attributes are simple keywords that follow the type specified. |
| 629 | If multiple parameter attributes are needed, they are space separated. |
| 630 | For example: |
| 631 | |
| 632 | .. code-block:: llvm |
| 633 | |
| 634 | declare i32 @printf(i8* noalias nocapture, ...) |
| 635 | declare i32 @atoi(i8 zeroext) |
| 636 | declare signext i8 @returns_signed_char() |
| 637 | |
| 638 | Note that any attributes for the function result (``nounwind``, |
| 639 | ``readonly``) come immediately after the argument list. |
| 640 | |
| 641 | Currently, only the following parameter attributes are defined: |
| 642 | |
| 643 | ``zeroext`` |
| 644 | This indicates to the code generator that the parameter or return |
| 645 | value should be zero-extended to the extent required by the target's |
| 646 | ABI (which is usually 32-bits, but is 8-bits for a i1 on x86-64) by |
| 647 | the caller (for a parameter) or the callee (for a return value). |
| 648 | ``signext`` |
| 649 | This indicates to the code generator that the parameter or return |
| 650 | value should be sign-extended to the extent required by the target's |
| 651 | ABI (which is usually 32-bits) by the caller (for a parameter) or |
| 652 | the callee (for a return value). |
| 653 | ``inreg`` |
| 654 | This indicates that this parameter or return value should be treated |
| 655 | in a special target-dependent fashion during while emitting code for |
| 656 | a function call or return (usually, by putting it in a register as |
| 657 | opposed to memory, though some targets use it to distinguish between |
| 658 | two different kinds of registers). Use of this attribute is |
| 659 | target-specific. |
| 660 | ``byval`` |
| 661 | This indicates that the pointer parameter should really be passed by |
| 662 | value to the function. The attribute implies that a hidden copy of |
| 663 | the pointee is made between the caller and the callee, so the callee |
| 664 | is unable to modify the value in the caller. This attribute is only |
| 665 | valid on LLVM pointer arguments. It is generally used to pass |
| 666 | structs and arrays by value, but is also valid on pointers to |
| 667 | scalars. The copy is considered to belong to the caller not the |
| 668 | callee (for example, ``readonly`` functions should not write to |
| 669 | ``byval`` parameters). This is not a valid attribute for return |
| 670 | values. |
| 671 | |
| 672 | The byval attribute also supports specifying an alignment with the |
| 673 | align attribute. It indicates the alignment of the stack slot to |
| 674 | form and the known alignment of the pointer specified to the call |
| 675 | site. If the alignment is not specified, then the code generator |
| 676 | makes a target-specific assumption. |
| 677 | |
| 678 | ``sret`` |
| 679 | This indicates that the pointer parameter specifies the address of a |
| 680 | structure that is the return value of the function in the source |
| 681 | program. This pointer must be guaranteed by the caller to be valid: |
Eli Bendersky | 98202c0 | 2013-01-23 22:05:19 +0000 | [diff] [blame] | 682 | loads and stores to the structure may be assumed by the callee |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 683 | not to trap and to be properly aligned. This may only be applied to |
| 684 | the first parameter. This is not a valid attribute for return |
| 685 | values. |
| 686 | ``noalias`` |
| 687 | This indicates that pointer values `*based* <pointeraliasing>` on |
| 688 | the argument or return value do not alias pointer values which are |
| 689 | not *based* on it, ignoring certain "irrelevant" dependencies. For a |
| 690 | call to the parent function, dependencies between memory references |
| 691 | from before or after the call and from those during the call are |
| 692 | "irrelevant" to the ``noalias`` keyword for the arguments and return |
| 693 | value used in that call. The caller shares the responsibility with |
| 694 | the callee for ensuring that these requirements are met. For further |
| 695 | details, please see the discussion of the NoAlias response in `alias |
| 696 | analysis <AliasAnalysis.html#MustMayNo>`_. |
| 697 | |
| 698 | Note that this definition of ``noalias`` is intentionally similar |
| 699 | to the definition of ``restrict`` in C99 for function arguments, |
| 700 | though it is slightly weaker. |
| 701 | |
| 702 | For function return values, C99's ``restrict`` is not meaningful, |
| 703 | while LLVM's ``noalias`` is. |
| 704 | ``nocapture`` |
| 705 | This indicates that the callee does not make any copies of the |
| 706 | pointer that outlive the callee itself. This is not a valid |
| 707 | attribute for return values. |
| 708 | |
| 709 | .. _nest: |
| 710 | |
| 711 | ``nest`` |
| 712 | This indicates that the pointer parameter can be excised using the |
| 713 | :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid |
| 714 | attribute for return values. |
| 715 | |
| 716 | .. _gc: |
| 717 | |
| 718 | Garbage Collector Names |
| 719 | ----------------------- |
| 720 | |
| 721 | Each function may specify a garbage collector name, which is simply a |
| 722 | string: |
| 723 | |
| 724 | .. code-block:: llvm |
| 725 | |
| 726 | define void @f() gc "name" { ... } |
| 727 | |
| 728 | The compiler declares the supported values of *name*. Specifying a |
| 729 | collector which will cause the compiler to alter its output in order to |
| 730 | support the named garbage collection algorithm. |
| 731 | |
| 732 | .. _fnattrs: |
| 733 | |
| 734 | Function Attributes |
| 735 | ------------------- |
| 736 | |
| 737 | Function attributes are set to communicate additional information about |
| 738 | a function. Function attributes are considered to be part of the |
| 739 | function, not of the function type, so functions with different function |
| 740 | attributes can have the same function type. |
| 741 | |
| 742 | Function attributes are simple keywords that follow the type specified. |
| 743 | If multiple attributes are needed, they are space separated. For |
| 744 | example: |
| 745 | |
| 746 | .. code-block:: llvm |
| 747 | |
| 748 | define void @f() noinline { ... } |
| 749 | define void @f() alwaysinline { ... } |
| 750 | define void @f() alwaysinline optsize { ... } |
| 751 | define void @f() optsize { ... } |
| 752 | |
| 753 | ``address_safety`` |
| 754 | This attribute indicates that the address safety analysis is enabled |
| 755 | for this function. |
| 756 | ``alignstack(<n>)`` |
| 757 | This attribute indicates that, when emitting the prologue and |
| 758 | epilogue, the backend should forcibly align the stack pointer. |
| 759 | Specify the desired alignment, which must be a power of two, in |
| 760 | parentheses. |
| 761 | ``alwaysinline`` |
| 762 | This attribute indicates that the inliner should attempt to inline |
| 763 | this function into callers whenever possible, ignoring any active |
| 764 | inlining size threshold for this caller. |
| 765 | ``nonlazybind`` |
| 766 | This attribute suppresses lazy symbol binding for the function. This |
| 767 | may make calls to the function faster, at the cost of extra program |
| 768 | startup time if the function is not called during program startup. |
| 769 | ``inlinehint`` |
| 770 | This attribute indicates that the source code contained a hint that |
| 771 | inlining this function is desirable (such as the "inline" keyword in |
| 772 | C/C++). It is just a hint; it imposes no requirements on the |
| 773 | inliner. |
| 774 | ``naked`` |
| 775 | This attribute disables prologue / epilogue emission for the |
| 776 | function. This can have very system-specific consequences. |
| 777 | ``noimplicitfloat`` |
| 778 | This attributes disables implicit floating point instructions. |
| 779 | ``noinline`` |
| 780 | This attribute indicates that the inliner should never inline this |
| 781 | function in any situation. This attribute may not be used together |
| 782 | with the ``alwaysinline`` attribute. |
| 783 | ``noredzone`` |
| 784 | This attribute indicates that the code generator should not use a |
| 785 | red zone, even if the target-specific ABI normally permits it. |
| 786 | ``noreturn`` |
| 787 | This function attribute indicates that the function never returns |
| 788 | normally. This produces undefined behavior at runtime if the |
| 789 | function ever does dynamically return. |
| 790 | ``nounwind`` |
| 791 | This function attribute indicates that the function never returns |
| 792 | with an unwind or exceptional control flow. If the function does |
| 793 | unwind, its runtime behavior is undefined. |
| 794 | ``optsize`` |
| 795 | This attribute suggests that optimization passes and code generator |
| 796 | passes make choices that keep the code size of this function low, |
| 797 | and otherwise do optimizations specifically to reduce code size. |
| 798 | ``readnone`` |
| 799 | This attribute indicates that the function computes its result (or |
| 800 | decides to unwind an exception) based strictly on its arguments, |
| 801 | without dereferencing any pointer arguments or otherwise accessing |
| 802 | any mutable state (e.g. memory, control registers, etc) visible to |
| 803 | caller functions. It does not write through any pointer arguments |
| 804 | (including ``byval`` arguments) and never changes any state visible |
| 805 | to callers. This means that it cannot unwind exceptions by calling |
| 806 | the ``C++`` exception throwing methods. |
| 807 | ``readonly`` |
| 808 | This attribute indicates that the function does not write through |
| 809 | any pointer arguments (including ``byval`` arguments) or otherwise |
| 810 | modify any state (e.g. memory, control registers, etc) visible to |
| 811 | caller functions. It may dereference pointer arguments and read |
| 812 | state that may be set in the caller. A readonly function always |
| 813 | returns the same value (or unwinds an exception identically) when |
| 814 | called with the same set of arguments and global state. It cannot |
| 815 | unwind an exception by calling the ``C++`` exception throwing |
| 816 | methods. |
| 817 | ``returns_twice`` |
| 818 | This attribute indicates that this function can return twice. The C |
| 819 | ``setjmp`` is an example of such a function. The compiler disables |
| 820 | some optimizations (like tail calls) in the caller of these |
| 821 | functions. |
| 822 | ``ssp`` |
| 823 | This attribute indicates that the function should emit a stack |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 824 | smashing protector. It is in the form of a "canary" --- a random value |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 825 | placed on the stack before the local variables that's checked upon |
| 826 | return from the function to see if it has been overwritten. A |
| 827 | heuristic is used to determine if a function needs stack protectors |
Bill Wendling | e4957fb | 2013-01-23 06:43:53 +0000 | [diff] [blame] | 828 | or not. The heuristic used will enable protectors for functions with: |
Dmitri Gribenko | d8acb28 | 2013-01-29 23:14:41 +0000 | [diff] [blame] | 829 | |
Bill Wendling | e4957fb | 2013-01-23 06:43:53 +0000 | [diff] [blame] | 830 | - Character arrays larger than ``ssp-buffer-size`` (default 8). |
| 831 | - Aggregates containing character arrays larger than ``ssp-buffer-size``. |
| 832 | - Calls to alloca() with variable sizes or constant sizes greater than |
| 833 | ``ssp-buffer-size``. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 834 | |
| 835 | If a function that has an ``ssp`` attribute is inlined into a |
| 836 | function that doesn't have an ``ssp`` attribute, then the resulting |
| 837 | function will have an ``ssp`` attribute. |
| 838 | ``sspreq`` |
| 839 | This attribute indicates that the function should *always* emit a |
| 840 | stack smashing protector. This overrides the ``ssp`` function |
| 841 | attribute. |
| 842 | |
| 843 | If a function that has an ``sspreq`` attribute is inlined into a |
| 844 | function that doesn't have an ``sspreq`` attribute or which has an |
Bill Wendling | 114baee | 2013-01-23 06:41:41 +0000 | [diff] [blame] | 845 | ``ssp`` or ``sspstrong`` attribute, then the resulting function will have |
| 846 | an ``sspreq`` attribute. |
| 847 | ``sspstrong`` |
| 848 | This attribute indicates that the function should emit a stack smashing |
Bill Wendling | e4957fb | 2013-01-23 06:43:53 +0000 | [diff] [blame] | 849 | protector. This attribute causes a strong heuristic to be used when |
| 850 | determining if a function needs stack protectors. The strong heuristic |
| 851 | will enable protectors for functions with: |
Dmitri Gribenko | d8acb28 | 2013-01-29 23:14:41 +0000 | [diff] [blame] | 852 | |
Bill Wendling | e4957fb | 2013-01-23 06:43:53 +0000 | [diff] [blame] | 853 | - Arrays of any size and type |
| 854 | - Aggregates containing an array of any size and type. |
| 855 | - Calls to alloca(). |
| 856 | - Local variables that have had their address taken. |
| 857 | |
| 858 | This overrides the ``ssp`` function attribute. |
Bill Wendling | 114baee | 2013-01-23 06:41:41 +0000 | [diff] [blame] | 859 | |
| 860 | If a function that has an ``sspstrong`` attribute is inlined into a |
| 861 | function that doesn't have an ``sspstrong`` attribute, then the |
| 862 | resulting function will have an ``sspstrong`` attribute. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 863 | ``uwtable`` |
| 864 | This attribute indicates that the ABI being targeted requires that |
| 865 | an unwind table entry be produce for this function even if we can |
| 866 | show that no exceptions passes by it. This is normally the case for |
| 867 | the ELF x86-64 abi, but it can be disabled for some compilation |
| 868 | units. |
James Molloy | 67ae135 | 2012-12-20 16:04:27 +0000 | [diff] [blame] | 869 | ``noduplicate`` |
| 870 | This attribute indicates that calls to the function cannot be |
| 871 | duplicated. A call to a ``noduplicate`` function may be moved |
| 872 | within its parent function, but may not be duplicated within |
| 873 | its parent function. |
| 874 | |
| 875 | A function containing a ``noduplicate`` call may still |
| 876 | be an inlining candidate, provided that the call is not |
| 877 | duplicated by inlining. That implies that the function has |
| 878 | internal linkage and only has one call site, so the original |
| 879 | call is dead after inlining. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 880 | |
| 881 | .. _moduleasm: |
| 882 | |
| 883 | Module-Level Inline Assembly |
| 884 | ---------------------------- |
| 885 | |
| 886 | Modules may contain "module-level inline asm" blocks, which corresponds |
| 887 | to the GCC "file scope inline asm" blocks. These blocks are internally |
| 888 | concatenated by LLVM and treated as a single unit, but may be separated |
| 889 | in the ``.ll`` file if desired. The syntax is very simple: |
| 890 | |
| 891 | .. code-block:: llvm |
| 892 | |
| 893 | module asm "inline asm code goes here" |
| 894 | module asm "more can go here" |
| 895 | |
| 896 | The strings can contain any character by escaping non-printable |
| 897 | characters. The escape sequence used is simply "\\xx" where "xx" is the |
| 898 | two digit hex code for the number. |
| 899 | |
| 900 | The inline asm code is simply printed to the machine code .s file when |
| 901 | assembly code is generated. |
| 902 | |
| 903 | Data Layout |
| 904 | ----------- |
| 905 | |
| 906 | A module may specify a target specific data layout string that specifies |
| 907 | how data is to be laid out in memory. The syntax for the data layout is |
| 908 | simply: |
| 909 | |
| 910 | .. code-block:: llvm |
| 911 | |
| 912 | target datalayout = "layout specification" |
| 913 | |
| 914 | The *layout specification* consists of a list of specifications |
| 915 | separated by the minus sign character ('-'). Each specification starts |
| 916 | with a letter and may include other information after the letter to |
| 917 | define some aspect of the data layout. The specifications accepted are |
| 918 | as follows: |
| 919 | |
| 920 | ``E`` |
| 921 | Specifies that the target lays out data in big-endian form. That is, |
| 922 | the bits with the most significance have the lowest address |
| 923 | location. |
| 924 | ``e`` |
| 925 | Specifies that the target lays out data in little-endian form. That |
| 926 | is, the bits with the least significance have the lowest address |
| 927 | location. |
| 928 | ``S<size>`` |
| 929 | Specifies the natural alignment of the stack in bits. Alignment |
| 930 | promotion of stack variables is limited to the natural stack |
| 931 | alignment to avoid dynamic stack realignment. The stack alignment |
| 932 | must be a multiple of 8-bits. If omitted, the natural stack |
| 933 | alignment defaults to "unspecified", which does not prevent any |
| 934 | alignment promotions. |
| 935 | ``p[n]:<size>:<abi>:<pref>`` |
| 936 | This specifies the *size* of a pointer and its ``<abi>`` and |
| 937 | ``<pref>``\erred alignments for address space ``n``. All sizes are in |
| 938 | bits. Specifying the ``<pref>`` alignment is optional. If omitted, the |
| 939 | preceding ``:`` should be omitted too. The address space, ``n`` is |
| 940 | optional, and if not specified, denotes the default address space 0. |
| 941 | The value of ``n`` must be in the range [1,2^23). |
| 942 | ``i<size>:<abi>:<pref>`` |
| 943 | This specifies the alignment for an integer type of a given bit |
| 944 | ``<size>``. The value of ``<size>`` must be in the range [1,2^23). |
| 945 | ``v<size>:<abi>:<pref>`` |
| 946 | This specifies the alignment for a vector type of a given bit |
| 947 | ``<size>``. |
| 948 | ``f<size>:<abi>:<pref>`` |
| 949 | This specifies the alignment for a floating point type of a given bit |
| 950 | ``<size>``. Only values of ``<size>`` that are supported by the target |
| 951 | will work. 32 (float) and 64 (double) are supported on all targets; 80 |
| 952 | or 128 (different flavors of long double) are also supported on some |
| 953 | targets. |
| 954 | ``a<size>:<abi>:<pref>`` |
| 955 | This specifies the alignment for an aggregate type of a given bit |
| 956 | ``<size>``. |
| 957 | ``s<size>:<abi>:<pref>`` |
| 958 | This specifies the alignment for a stack object of a given bit |
| 959 | ``<size>``. |
| 960 | ``n<size1>:<size2>:<size3>...`` |
| 961 | This specifies a set of native integer widths for the target CPU in |
| 962 | bits. For example, it might contain ``n32`` for 32-bit PowerPC, |
| 963 | ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of |
| 964 | this set are considered to support most general arithmetic operations |
| 965 | efficiently. |
| 966 | |
| 967 | When constructing the data layout for a given target, LLVM starts with a |
| 968 | default set of specifications which are then (possibly) overridden by |
| 969 | the specifications in the ``datalayout`` keyword. The default |
| 970 | specifications are given in this list: |
| 971 | |
| 972 | - ``E`` - big endian |
| 973 | - ``p:64:64:64`` - 64-bit pointers with 64-bit alignment |
Patrik Hagglund | 3b5f0b0 | 2013-01-30 09:02:06 +0000 | [diff] [blame] | 974 | - ``S0`` - natural stack alignment is unspecified |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 975 | - ``i1:8:8`` - i1 is 8-bit (byte) aligned |
| 976 | - ``i8:8:8`` - i8 is 8-bit (byte) aligned |
| 977 | - ``i16:16:16`` - i16 is 16-bit aligned |
| 978 | - ``i32:32:32`` - i32 is 32-bit aligned |
| 979 | - ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred |
| 980 | alignment of 64-bits |
Patrik Hagglund | 3b5f0b0 | 2013-01-30 09:02:06 +0000 | [diff] [blame] | 981 | - ``f16:16:16`` - half is 16-bit aligned |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 982 | - ``f32:32:32`` - float is 32-bit aligned |
| 983 | - ``f64:64:64`` - double is 64-bit aligned |
Patrik Hagglund | 3b5f0b0 | 2013-01-30 09:02:06 +0000 | [diff] [blame] | 984 | - ``f128:128:128`` - quad is 128-bit aligned |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 985 | - ``v64:64:64`` - 64-bit vector is 64-bit aligned |
| 986 | - ``v128:128:128`` - 128-bit vector is 128-bit aligned |
Patrik Hagglund | 3b5f0b0 | 2013-01-30 09:02:06 +0000 | [diff] [blame] | 987 | - ``a0:0:64`` - aggregates are 64-bit aligned |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 988 | |
| 989 | When LLVM is determining the alignment for a given type, it uses the |
| 990 | following rules: |
| 991 | |
| 992 | #. If the type sought is an exact match for one of the specifications, |
| 993 | that specification is used. |
| 994 | #. If no match is found, and the type sought is an integer type, then |
| 995 | the smallest integer type that is larger than the bitwidth of the |
| 996 | sought type is used. If none of the specifications are larger than |
| 997 | the bitwidth then the largest integer type is used. For example, |
| 998 | given the default specifications above, the i7 type will use the |
| 999 | alignment of i8 (next largest) while both i65 and i256 will use the |
| 1000 | alignment of i64 (largest specified). |
| 1001 | #. If no match is found, and the type sought is a vector type, then the |
| 1002 | largest vector type that is smaller than the sought vector type will |
| 1003 | be used as a fall back. This happens because <128 x double> can be |
| 1004 | implemented in terms of 64 <2 x double>, for example. |
| 1005 | |
| 1006 | The function of the data layout string may not be what you expect. |
| 1007 | Notably, this is not a specification from the frontend of what alignment |
| 1008 | the code generator should use. |
| 1009 | |
| 1010 | Instead, if specified, the target data layout is required to match what |
| 1011 | the ultimate *code generator* expects. This string is used by the |
| 1012 | mid-level optimizers to improve code, and this only works if it matches |
| 1013 | what the ultimate code generator uses. If you would like to generate IR |
| 1014 | that does not embed this target-specific detail into the IR, then you |
| 1015 | don't have to specify the string. This will disable some optimizations |
| 1016 | that require precise layout information, but this also prevents those |
| 1017 | optimizations from introducing target specificity into the IR. |
| 1018 | |
| 1019 | .. _pointeraliasing: |
| 1020 | |
| 1021 | Pointer Aliasing Rules |
| 1022 | ---------------------- |
| 1023 | |
| 1024 | Any memory access must be done through a pointer value associated with |
| 1025 | an address range of the memory access, otherwise the behavior is |
| 1026 | undefined. Pointer values are associated with address ranges according |
| 1027 | to the following rules: |
| 1028 | |
| 1029 | - A pointer value is associated with the addresses associated with any |
| 1030 | value it is *based* on. |
| 1031 | - An address of a global variable is associated with the address range |
| 1032 | of the variable's storage. |
| 1033 | - The result value of an allocation instruction is associated with the |
| 1034 | address range of the allocated storage. |
| 1035 | - A null pointer in the default address-space is associated with no |
| 1036 | address. |
| 1037 | - An integer constant other than zero or a pointer value returned from |
| 1038 | a function not defined within LLVM may be associated with address |
| 1039 | ranges allocated through mechanisms other than those provided by |
| 1040 | LLVM. Such ranges shall not overlap with any ranges of addresses |
| 1041 | allocated by mechanisms provided by LLVM. |
| 1042 | |
| 1043 | A pointer value is *based* on another pointer value according to the |
| 1044 | following rules: |
| 1045 | |
| 1046 | - A pointer value formed from a ``getelementptr`` operation is *based* |
| 1047 | on the first operand of the ``getelementptr``. |
| 1048 | - The result value of a ``bitcast`` is *based* on the operand of the |
| 1049 | ``bitcast``. |
| 1050 | - A pointer value formed by an ``inttoptr`` is *based* on all pointer |
| 1051 | values that contribute (directly or indirectly) to the computation of |
| 1052 | the pointer's value. |
| 1053 | - The "*based* on" relationship is transitive. |
| 1054 | |
| 1055 | Note that this definition of *"based"* is intentionally similar to the |
| 1056 | definition of *"based"* in C99, though it is slightly weaker. |
| 1057 | |
| 1058 | LLVM IR does not associate types with memory. The result type of a |
| 1059 | ``load`` merely indicates the size and alignment of the memory from |
| 1060 | which to load, as well as the interpretation of the value. The first |
| 1061 | operand type of a ``store`` similarly only indicates the size and |
| 1062 | alignment of the store. |
| 1063 | |
| 1064 | Consequently, type-based alias analysis, aka TBAA, aka |
| 1065 | ``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR. |
| 1066 | :ref:`Metadata <metadata>` may be used to encode additional information |
| 1067 | which specialized optimization passes may use to implement type-based |
| 1068 | alias analysis. |
| 1069 | |
| 1070 | .. _volatile: |
| 1071 | |
| 1072 | Volatile Memory Accesses |
| 1073 | ------------------------ |
| 1074 | |
| 1075 | Certain memory accesses, such as :ref:`load <i_load>`'s, |
| 1076 | :ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be |
| 1077 | marked ``volatile``. The optimizers must not change the number of |
| 1078 | volatile operations or change their order of execution relative to other |
| 1079 | volatile operations. The optimizers *may* change the order of volatile |
| 1080 | operations relative to non-volatile operations. This is not Java's |
| 1081 | "volatile" and has no cross-thread synchronization behavior. |
| 1082 | |
Andrew Trick | 9a6dd02 | 2013-01-30 21:19:35 +0000 | [diff] [blame] | 1083 | IR-level volatile loads and stores cannot safely be optimized into |
| 1084 | llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are |
| 1085 | flagged volatile. Likewise, the backend should never split or merge |
| 1086 | target-legal volatile load/store instructions. |
| 1087 | |
Andrew Trick | 946317d | 2013-01-31 00:49:39 +0000 | [diff] [blame] | 1088 | .. admonition:: Rationale |
| 1089 | |
| 1090 | Platforms may rely on volatile loads and stores of natively supported |
| 1091 | data width to be executed as single instruction. For example, in C |
| 1092 | this holds for an l-value of volatile primitive type with native |
| 1093 | hardware support, but not necessarily for aggregate types. The |
| 1094 | frontend upholds these expectations, which are intentionally |
| 1095 | unspecified in the IR. The rules above ensure that IR transformation |
| 1096 | do not violate the frontend's contract with the language. |
| 1097 | |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 1098 | .. _memmodel: |
| 1099 | |
| 1100 | Memory Model for Concurrent Operations |
| 1101 | -------------------------------------- |
| 1102 | |
| 1103 | The LLVM IR does not define any way to start parallel threads of |
| 1104 | execution or to register signal handlers. Nonetheless, there are |
| 1105 | platform-specific ways to create them, and we define LLVM IR's behavior |
| 1106 | in their presence. This model is inspired by the C++0x memory model. |
| 1107 | |
| 1108 | For a more informal introduction to this model, see the :doc:`Atomics`. |
| 1109 | |
| 1110 | We define a *happens-before* partial order as the least partial order |
| 1111 | that |
| 1112 | |
| 1113 | - Is a superset of single-thread program order, and |
| 1114 | - When a *synchronizes-with* ``b``, includes an edge from ``a`` to |
| 1115 | ``b``. *Synchronizes-with* pairs are introduced by platform-specific |
| 1116 | techniques, like pthread locks, thread creation, thread joining, |
| 1117 | etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering |
| 1118 | Constraints <ordering>`). |
| 1119 | |
| 1120 | Note that program order does not introduce *happens-before* edges |
| 1121 | between a thread and signals executing inside that thread. |
| 1122 | |
| 1123 | Every (defined) read operation (load instructions, memcpy, atomic |
| 1124 | loads/read-modify-writes, etc.) R reads a series of bytes written by |
| 1125 | (defined) write operations (store instructions, atomic |
| 1126 | stores/read-modify-writes, memcpy, etc.). For the purposes of this |
| 1127 | section, initialized globals are considered to have a write of the |
| 1128 | initializer which is atomic and happens before any other read or write |
| 1129 | of the memory in question. For each byte of a read R, R\ :sub:`byte` |
| 1130 | may see any write to the same byte, except: |
| 1131 | |
| 1132 | - If write\ :sub:`1` happens before write\ :sub:`2`, and |
| 1133 | write\ :sub:`2` happens before R\ :sub:`byte`, then |
| 1134 | R\ :sub:`byte` does not see write\ :sub:`1`. |
| 1135 | - If R\ :sub:`byte` happens before write\ :sub:`3`, then |
| 1136 | R\ :sub:`byte` does not see write\ :sub:`3`. |
| 1137 | |
| 1138 | Given that definition, R\ :sub:`byte` is defined as follows: |
| 1139 | |
| 1140 | - If R is volatile, the result is target-dependent. (Volatile is |
| 1141 | supposed to give guarantees which can support ``sig_atomic_t`` in |
| 1142 | C/C++, and may be used for accesses to addresses which do not behave |
| 1143 | like normal memory. It does not generally provide cross-thread |
| 1144 | synchronization.) |
| 1145 | - Otherwise, if there is no write to the same byte that happens before |
| 1146 | R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte. |
| 1147 | - Otherwise, if R\ :sub:`byte` may see exactly one write, |
| 1148 | R\ :sub:`byte` returns the value written by that write. |
| 1149 | - Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may |
| 1150 | see are atomic, it chooses one of the values written. See the :ref:`Atomic |
| 1151 | Memory Ordering Constraints <ordering>` section for additional |
| 1152 | constraints on how the choice is made. |
| 1153 | - Otherwise R\ :sub:`byte` returns ``undef``. |
| 1154 | |
| 1155 | R returns the value composed of the series of bytes it read. This |
| 1156 | implies that some bytes within the value may be ``undef`` **without** |
| 1157 | the entire value being ``undef``. Note that this only defines the |
| 1158 | semantics of the operation; it doesn't mean that targets will emit more |
| 1159 | than one instruction to read the series of bytes. |
| 1160 | |
| 1161 | Note that in cases where none of the atomic intrinsics are used, this |
| 1162 | model places only one restriction on IR transformations on top of what |
| 1163 | is required for single-threaded execution: introducing a store to a byte |
| 1164 | which might not otherwise be stored is not allowed in general. |
| 1165 | (Specifically, in the case where another thread might write to and read |
| 1166 | from an address, introducing a store can change a load that may see |
| 1167 | exactly one write into a load that may see multiple writes.) |
| 1168 | |
| 1169 | .. _ordering: |
| 1170 | |
| 1171 | Atomic Memory Ordering Constraints |
| 1172 | ---------------------------------- |
| 1173 | |
| 1174 | Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`, |
| 1175 | :ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`, |
| 1176 | :ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take |
| 1177 | an ordering parameter that determines which other atomic instructions on |
| 1178 | the same address they *synchronize with*. These semantics are borrowed |
| 1179 | from Java and C++0x, but are somewhat more colloquial. If these |
| 1180 | descriptions aren't precise enough, check those specs (see spec |
| 1181 | references in the :doc:`atomics guide <Atomics>`). |
| 1182 | :ref:`fence <i_fence>` instructions treat these orderings somewhat |
| 1183 | differently since they don't take an address. See that instruction's |
| 1184 | documentation for details. |
| 1185 | |
| 1186 | For a simpler introduction to the ordering constraints, see the |
| 1187 | :doc:`Atomics`. |
| 1188 | |
| 1189 | ``unordered`` |
| 1190 | The set of values that can be read is governed by the happens-before |
| 1191 | partial order. A value cannot be read unless some operation wrote |
| 1192 | it. This is intended to provide a guarantee strong enough to model |
| 1193 | Java's non-volatile shared variables. This ordering cannot be |
| 1194 | specified for read-modify-write operations; it is not strong enough |
| 1195 | to make them atomic in any interesting way. |
| 1196 | ``monotonic`` |
| 1197 | In addition to the guarantees of ``unordered``, there is a single |
| 1198 | total order for modifications by ``monotonic`` operations on each |
| 1199 | address. All modification orders must be compatible with the |
| 1200 | happens-before order. There is no guarantee that the modification |
| 1201 | orders can be combined to a global total order for the whole program |
| 1202 | (and this often will not be possible). The read in an atomic |
| 1203 | read-modify-write operation (:ref:`cmpxchg <i_cmpxchg>` and |
| 1204 | :ref:`atomicrmw <i_atomicrmw>`) reads the value in the modification |
| 1205 | order immediately before the value it writes. If one atomic read |
| 1206 | happens before another atomic read of the same address, the later |
| 1207 | read must see the same value or a later value in the address's |
| 1208 | modification order. This disallows reordering of ``monotonic`` (or |
| 1209 | stronger) operations on the same address. If an address is written |
| 1210 | ``monotonic``-ally by one thread, and other threads ``monotonic``-ally |
| 1211 | read that address repeatedly, the other threads must eventually see |
| 1212 | the write. This corresponds to the C++0x/C1x |
| 1213 | ``memory_order_relaxed``. |
| 1214 | ``acquire`` |
| 1215 | In addition to the guarantees of ``monotonic``, a |
| 1216 | *synchronizes-with* edge may be formed with a ``release`` operation. |
| 1217 | This is intended to model C++'s ``memory_order_acquire``. |
| 1218 | ``release`` |
| 1219 | In addition to the guarantees of ``monotonic``, if this operation |
| 1220 | writes a value which is subsequently read by an ``acquire`` |
| 1221 | operation, it *synchronizes-with* that operation. (This isn't a |
| 1222 | complete description; see the C++0x definition of a release |
| 1223 | sequence.) This corresponds to the C++0x/C1x |
| 1224 | ``memory_order_release``. |
| 1225 | ``acq_rel`` (acquire+release) |
| 1226 | Acts as both an ``acquire`` and ``release`` operation on its |
| 1227 | address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``. |
| 1228 | ``seq_cst`` (sequentially consistent) |
| 1229 | In addition to the guarantees of ``acq_rel`` (``acquire`` for an |
| 1230 | operation which only reads, ``release`` for an operation which only |
| 1231 | writes), there is a global total order on all |
| 1232 | sequentially-consistent operations on all addresses, which is |
| 1233 | consistent with the *happens-before* partial order and with the |
| 1234 | modification orders of all the affected addresses. Each |
| 1235 | sequentially-consistent read sees the last preceding write to the |
| 1236 | same address in this global order. This corresponds to the C++0x/C1x |
| 1237 | ``memory_order_seq_cst`` and Java volatile. |
| 1238 | |
| 1239 | .. _singlethread: |
| 1240 | |
| 1241 | If an atomic operation is marked ``singlethread``, it only *synchronizes |
| 1242 | with* or participates in modification and seq\_cst total orderings with |
| 1243 | other operations running in the same thread (for example, in signal |
| 1244 | handlers). |
| 1245 | |
| 1246 | .. _fastmath: |
| 1247 | |
| 1248 | Fast-Math Flags |
| 1249 | --------------- |
| 1250 | |
| 1251 | LLVM IR floating-point binary ops (:ref:`fadd <i_fadd>`, |
| 1252 | :ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`, |
| 1253 | :ref:`frem <i_frem>`) have the following flags that can set to enable |
| 1254 | otherwise unsafe floating point operations |
| 1255 | |
| 1256 | ``nnan`` |
| 1257 | No NaNs - Allow optimizations to assume the arguments and result are not |
| 1258 | NaN. Such optimizations are required to retain defined behavior over |
| 1259 | NaNs, but the value of the result is undefined. |
| 1260 | |
| 1261 | ``ninf`` |
| 1262 | No Infs - Allow optimizations to assume the arguments and result are not |
| 1263 | +/-Inf. Such optimizations are required to retain defined behavior over |
| 1264 | +/-Inf, but the value of the result is undefined. |
| 1265 | |
| 1266 | ``nsz`` |
| 1267 | No Signed Zeros - Allow optimizations to treat the sign of a zero |
| 1268 | argument or result as insignificant. |
| 1269 | |
| 1270 | ``arcp`` |
| 1271 | Allow Reciprocal - Allow optimizations to use the reciprocal of an |
| 1272 | argument rather than perform division. |
| 1273 | |
| 1274 | ``fast`` |
| 1275 | Fast - Allow algebraically equivalent transformations that may |
| 1276 | dramatically change results in floating point (e.g. reassociate). This |
| 1277 | flag implies all the others. |
| 1278 | |
| 1279 | .. _typesystem: |
| 1280 | |
| 1281 | Type System |
| 1282 | =========== |
| 1283 | |
| 1284 | The LLVM type system is one of the most important features of the |
| 1285 | intermediate representation. Being typed enables a number of |
| 1286 | optimizations to be performed on the intermediate representation |
| 1287 | directly, without having to do extra analyses on the side before the |
| 1288 | transformation. A strong type system makes it easier to read the |
| 1289 | generated code and enables novel analyses and transformations that are |
| 1290 | not feasible to perform on normal three address code representations. |
| 1291 | |
| 1292 | Type Classifications |
| 1293 | -------------------- |
| 1294 | |
| 1295 | The types fall into a few useful classifications: |
| 1296 | |
| 1297 | |
| 1298 | .. list-table:: |
| 1299 | :header-rows: 1 |
| 1300 | |
| 1301 | * - Classification |
| 1302 | - Types |
| 1303 | |
| 1304 | * - :ref:`integer <t_integer>` |
| 1305 | - ``i1``, ``i2``, ``i3``, ... ``i8``, ... ``i16``, ... ``i32``, ... |
| 1306 | ``i64``, ... |
| 1307 | |
| 1308 | * - :ref:`floating point <t_floating>` |
| 1309 | - ``half``, ``float``, ``double``, ``x86_fp80``, ``fp128``, |
| 1310 | ``ppc_fp128`` |
| 1311 | |
| 1312 | |
| 1313 | * - first class |
| 1314 | |
| 1315 | .. _t_firstclass: |
| 1316 | |
| 1317 | - :ref:`integer <t_integer>`, :ref:`floating point <t_floating>`, |
| 1318 | :ref:`pointer <t_pointer>`, :ref:`vector <t_vector>`, |
| 1319 | :ref:`structure <t_struct>`, :ref:`array <t_array>`, |
| 1320 | :ref:`label <t_label>`, :ref:`metadata <t_metadata>`. |
| 1321 | |
| 1322 | * - :ref:`primitive <t_primitive>` |
| 1323 | - :ref:`label <t_label>`, |
| 1324 | :ref:`void <t_void>`, |
| 1325 | :ref:`integer <t_integer>`, |
| 1326 | :ref:`floating point <t_floating>`, |
| 1327 | :ref:`x86mmx <t_x86mmx>`, |
| 1328 | :ref:`metadata <t_metadata>`. |
| 1329 | |
| 1330 | * - :ref:`derived <t_derived>` |
| 1331 | - :ref:`array <t_array>`, |
| 1332 | :ref:`function <t_function>`, |
| 1333 | :ref:`pointer <t_pointer>`, |
| 1334 | :ref:`structure <t_struct>`, |
| 1335 | :ref:`vector <t_vector>`, |
| 1336 | :ref:`opaque <t_opaque>`. |
| 1337 | |
| 1338 | The :ref:`first class <t_firstclass>` types are perhaps the most important. |
| 1339 | Values of these types are the only ones which can be produced by |
| 1340 | instructions. |
| 1341 | |
| 1342 | .. _t_primitive: |
| 1343 | |
| 1344 | Primitive Types |
| 1345 | --------------- |
| 1346 | |
| 1347 | The primitive types are the fundamental building blocks of the LLVM |
| 1348 | system. |
| 1349 | |
| 1350 | .. _t_integer: |
| 1351 | |
| 1352 | Integer Type |
| 1353 | ^^^^^^^^^^^^ |
| 1354 | |
| 1355 | Overview: |
| 1356 | """"""""" |
| 1357 | |
| 1358 | The integer type is a very simple type that simply specifies an |
| 1359 | arbitrary bit width for the integer type desired. Any bit width from 1 |
| 1360 | bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified. |
| 1361 | |
| 1362 | Syntax: |
| 1363 | """"""" |
| 1364 | |
| 1365 | :: |
| 1366 | |
| 1367 | iN |
| 1368 | |
| 1369 | The number of bits the integer will occupy is specified by the ``N`` |
| 1370 | value. |
| 1371 | |
| 1372 | Examples: |
| 1373 | """"""""" |
| 1374 | |
| 1375 | +----------------+------------------------------------------------+ |
| 1376 | | ``i1`` | a single-bit integer. | |
| 1377 | +----------------+------------------------------------------------+ |
| 1378 | | ``i32`` | a 32-bit integer. | |
| 1379 | +----------------+------------------------------------------------+ |
| 1380 | | ``i1942652`` | a really big integer of over 1 million bits. | |
| 1381 | +----------------+------------------------------------------------+ |
| 1382 | |
| 1383 | .. _t_floating: |
| 1384 | |
| 1385 | Floating Point Types |
| 1386 | ^^^^^^^^^^^^^^^^^^^^ |
| 1387 | |
| 1388 | .. list-table:: |
| 1389 | :header-rows: 1 |
| 1390 | |
| 1391 | * - Type |
| 1392 | - Description |
| 1393 | |
| 1394 | * - ``half`` |
| 1395 | - 16-bit floating point value |
| 1396 | |
| 1397 | * - ``float`` |
| 1398 | - 32-bit floating point value |
| 1399 | |
| 1400 | * - ``double`` |
| 1401 | - 64-bit floating point value |
| 1402 | |
| 1403 | * - ``fp128`` |
| 1404 | - 128-bit floating point value (112-bit mantissa) |
| 1405 | |
| 1406 | * - ``x86_fp80`` |
| 1407 | - 80-bit floating point value (X87) |
| 1408 | |
| 1409 | * - ``ppc_fp128`` |
| 1410 | - 128-bit floating point value (two 64-bits) |
| 1411 | |
| 1412 | .. _t_x86mmx: |
| 1413 | |
| 1414 | X86mmx Type |
| 1415 | ^^^^^^^^^^^ |
| 1416 | |
| 1417 | Overview: |
| 1418 | """"""""" |
| 1419 | |
| 1420 | The x86mmx type represents a value held in an MMX register on an x86 |
| 1421 | machine. The operations allowed on it are quite limited: parameters and |
| 1422 | return values, load and store, and bitcast. User-specified MMX |
| 1423 | instructions are represented as intrinsic or asm calls with arguments |
| 1424 | and/or results of this type. There are no arrays, vectors or constants |
| 1425 | of this type. |
| 1426 | |
| 1427 | Syntax: |
| 1428 | """"""" |
| 1429 | |
| 1430 | :: |
| 1431 | |
| 1432 | x86mmx |
| 1433 | |
| 1434 | .. _t_void: |
| 1435 | |
| 1436 | Void Type |
| 1437 | ^^^^^^^^^ |
| 1438 | |
| 1439 | Overview: |
| 1440 | """"""""" |
| 1441 | |
| 1442 | The void type does not represent any value and has no size. |
| 1443 | |
| 1444 | Syntax: |
| 1445 | """"""" |
| 1446 | |
| 1447 | :: |
| 1448 | |
| 1449 | void |
| 1450 | |
| 1451 | .. _t_label: |
| 1452 | |
| 1453 | Label Type |
| 1454 | ^^^^^^^^^^ |
| 1455 | |
| 1456 | Overview: |
| 1457 | """"""""" |
| 1458 | |
| 1459 | The label type represents code labels. |
| 1460 | |
| 1461 | Syntax: |
| 1462 | """"""" |
| 1463 | |
| 1464 | :: |
| 1465 | |
| 1466 | label |
| 1467 | |
| 1468 | .. _t_metadata: |
| 1469 | |
| 1470 | Metadata Type |
| 1471 | ^^^^^^^^^^^^^ |
| 1472 | |
| 1473 | Overview: |
| 1474 | """"""""" |
| 1475 | |
| 1476 | The metadata type represents embedded metadata. No derived types may be |
| 1477 | created from metadata except for :ref:`function <t_function>` arguments. |
| 1478 | |
| 1479 | Syntax: |
| 1480 | """"""" |
| 1481 | |
| 1482 | :: |
| 1483 | |
| 1484 | metadata |
| 1485 | |
| 1486 | .. _t_derived: |
| 1487 | |
| 1488 | Derived Types |
| 1489 | ------------- |
| 1490 | |
| 1491 | The real power in LLVM comes from the derived types in the system. This |
| 1492 | is what allows a programmer to represent arrays, functions, pointers, |
| 1493 | and other useful types. Each of these types contain one or more element |
| 1494 | types which may be a primitive type, or another derived type. For |
| 1495 | example, it is possible to have a two dimensional array, using an array |
| 1496 | as the element type of another array. |
| 1497 | |
| 1498 | .. _t_aggregate: |
| 1499 | |
| 1500 | Aggregate Types |
| 1501 | ^^^^^^^^^^^^^^^ |
| 1502 | |
| 1503 | Aggregate Types are a subset of derived types that can contain multiple |
| 1504 | member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are |
| 1505 | aggregate types. :ref:`Vectors <t_vector>` are not considered to be |
| 1506 | aggregate types. |
| 1507 | |
| 1508 | .. _t_array: |
| 1509 | |
| 1510 | Array Type |
| 1511 | ^^^^^^^^^^ |
| 1512 | |
| 1513 | Overview: |
| 1514 | """"""""" |
| 1515 | |
| 1516 | The array type is a very simple derived type that arranges elements |
| 1517 | sequentially in memory. The array type requires a size (number of |
| 1518 | elements) and an underlying data type. |
| 1519 | |
| 1520 | Syntax: |
| 1521 | """"""" |
| 1522 | |
| 1523 | :: |
| 1524 | |
| 1525 | [<# elements> x <elementtype>] |
| 1526 | |
| 1527 | The number of elements is a constant integer value; ``elementtype`` may |
| 1528 | be any type with a size. |
| 1529 | |
| 1530 | Examples: |
| 1531 | """"""""" |
| 1532 | |
| 1533 | +------------------+--------------------------------------+ |
| 1534 | | ``[40 x i32]`` | Array of 40 32-bit integer values. | |
| 1535 | +------------------+--------------------------------------+ |
| 1536 | | ``[41 x i32]`` | Array of 41 32-bit integer values. | |
| 1537 | +------------------+--------------------------------------+ |
| 1538 | | ``[4 x i8]`` | Array of 4 8-bit integer values. | |
| 1539 | +------------------+--------------------------------------+ |
| 1540 | |
| 1541 | Here are some examples of multidimensional arrays: |
| 1542 | |
| 1543 | +-----------------------------+----------------------------------------------------------+ |
| 1544 | | ``[3 x [4 x i32]]`` | 3x4 array of 32-bit integer values. | |
| 1545 | +-----------------------------+----------------------------------------------------------+ |
| 1546 | | ``[12 x [10 x float]]`` | 12x10 array of single precision floating point values. | |
| 1547 | +-----------------------------+----------------------------------------------------------+ |
| 1548 | | ``[2 x [3 x [4 x i16]]]`` | 2x3x4 array of 16-bit integer values. | |
| 1549 | +-----------------------------+----------------------------------------------------------+ |
| 1550 | |
| 1551 | There is no restriction on indexing beyond the end of the array implied |
| 1552 | by a static type (though there are restrictions on indexing beyond the |
| 1553 | bounds of an allocated object in some cases). This means that |
| 1554 | single-dimension 'variable sized array' addressing can be implemented in |
| 1555 | LLVM with a zero length array type. An implementation of 'pascal style |
| 1556 | arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for |
| 1557 | example. |
| 1558 | |
| 1559 | .. _t_function: |
| 1560 | |
| 1561 | Function Type |
| 1562 | ^^^^^^^^^^^^^ |
| 1563 | |
| 1564 | Overview: |
| 1565 | """"""""" |
| 1566 | |
| 1567 | The function type can be thought of as a function signature. It consists |
| 1568 | of a return type and a list of formal parameter types. The return type |
| 1569 | of a function type is a first class type or a void type. |
| 1570 | |
| 1571 | Syntax: |
| 1572 | """"""" |
| 1573 | |
| 1574 | :: |
| 1575 | |
| 1576 | <returntype> (<parameter list>) |
| 1577 | |
| 1578 | ...where '``<parameter list>``' is a comma-separated list of type |
| 1579 | specifiers. Optionally, the parameter list may include a type ``...``, |
| 1580 | which indicates that the function takes a variable number of arguments. |
| 1581 | Variable argument functions can access their arguments with the |
| 1582 | :ref:`variable argument handling intrinsic <int_varargs>` functions. |
| 1583 | '``<returntype>``' is any type except :ref:`label <t_label>`. |
| 1584 | |
| 1585 | Examples: |
| 1586 | """"""""" |
| 1587 | |
| 1588 | +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
| 1589 | | ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` | |
| 1590 | +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 1591 | | ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. | |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 1592 | +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
| 1593 | | ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. | |
| 1594 | +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
| 1595 | | ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values | |
| 1596 | +---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
| 1597 | |
| 1598 | .. _t_struct: |
| 1599 | |
| 1600 | Structure Type |
| 1601 | ^^^^^^^^^^^^^^ |
| 1602 | |
| 1603 | Overview: |
| 1604 | """"""""" |
| 1605 | |
| 1606 | The structure type is used to represent a collection of data members |
| 1607 | together in memory. The elements of a structure may be any type that has |
| 1608 | a size. |
| 1609 | |
| 1610 | Structures in memory are accessed using '``load``' and '``store``' by |
| 1611 | getting a pointer to a field with the '``getelementptr``' instruction. |
| 1612 | Structures in registers are accessed using the '``extractvalue``' and |
| 1613 | '``insertvalue``' instructions. |
| 1614 | |
| 1615 | Structures may optionally be "packed" structures, which indicate that |
| 1616 | the alignment of the struct is one byte, and that there is no padding |
| 1617 | between the elements. In non-packed structs, padding between field types |
| 1618 | is inserted as defined by the DataLayout string in the module, which is |
| 1619 | required to match what the underlying code generator expects. |
| 1620 | |
| 1621 | Structures can either be "literal" or "identified". A literal structure |
| 1622 | is defined inline with other types (e.g. ``{i32, i32}*``) whereas |
| 1623 | identified types are always defined at the top level with a name. |
| 1624 | Literal types are uniqued by their contents and can never be recursive |
| 1625 | or opaque since there is no way to write one. Identified types can be |
| 1626 | recursive, can be opaqued, and are never uniqued. |
| 1627 | |
| 1628 | Syntax: |
| 1629 | """"""" |
| 1630 | |
| 1631 | :: |
| 1632 | |
| 1633 | %T1 = type { <type list> } ; Identified normal struct type |
| 1634 | %T2 = type <{ <type list> }> ; Identified packed struct type |
| 1635 | |
| 1636 | Examples: |
| 1637 | """"""""" |
| 1638 | |
| 1639 | +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
| 1640 | | ``{ i32, i32, i32 }`` | A triple of three ``i32`` values | |
| 1641 | +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 1642 | | ``{ float, i32 (i32) * }`` | A pair, where the first element is a ``float`` and the second element is a :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32``, returning an ``i32``. | |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 1643 | +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
| 1644 | | ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. | |
| 1645 | +------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |
| 1646 | |
| 1647 | .. _t_opaque: |
| 1648 | |
| 1649 | Opaque Structure Types |
| 1650 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 1651 | |
| 1652 | Overview: |
| 1653 | """"""""" |
| 1654 | |
| 1655 | Opaque structure types are used to represent named structure types that |
| 1656 | do not have a body specified. This corresponds (for example) to the C |
| 1657 | notion of a forward declared structure. |
| 1658 | |
| 1659 | Syntax: |
| 1660 | """"""" |
| 1661 | |
| 1662 | :: |
| 1663 | |
| 1664 | %X = type opaque |
| 1665 | %52 = type opaque |
| 1666 | |
| 1667 | Examples: |
| 1668 | """"""""" |
| 1669 | |
| 1670 | +--------------+-------------------+ |
| 1671 | | ``opaque`` | An opaque type. | |
| 1672 | +--------------+-------------------+ |
| 1673 | |
| 1674 | .. _t_pointer: |
| 1675 | |
| 1676 | Pointer Type |
| 1677 | ^^^^^^^^^^^^ |
| 1678 | |
| 1679 | Overview: |
| 1680 | """"""""" |
| 1681 | |
| 1682 | The pointer type is used to specify memory locations. Pointers are |
| 1683 | commonly used to reference objects in memory. |
| 1684 | |
| 1685 | Pointer types may have an optional address space attribute defining the |
| 1686 | numbered address space where the pointed-to object resides. The default |
| 1687 | address space is number zero. The semantics of non-zero address spaces |
| 1688 | are target-specific. |
| 1689 | |
| 1690 | Note that LLVM does not permit pointers to void (``void*``) nor does it |
| 1691 | permit pointers to labels (``label*``). Use ``i8*`` instead. |
| 1692 | |
| 1693 | Syntax: |
| 1694 | """"""" |
| 1695 | |
| 1696 | :: |
| 1697 | |
| 1698 | <type> * |
| 1699 | |
| 1700 | Examples: |
| 1701 | """"""""" |
| 1702 | |
| 1703 | +-------------------------+--------------------------------------------------------------------------------------------------------------+ |
| 1704 | | ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. | |
| 1705 | +-------------------------+--------------------------------------------------------------------------------------------------------------+ |
| 1706 | | ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. | |
| 1707 | +-------------------------+--------------------------------------------------------------------------------------------------------------+ |
| 1708 | | ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. | |
| 1709 | +-------------------------+--------------------------------------------------------------------------------------------------------------+ |
| 1710 | |
| 1711 | .. _t_vector: |
| 1712 | |
| 1713 | Vector Type |
| 1714 | ^^^^^^^^^^^ |
| 1715 | |
| 1716 | Overview: |
| 1717 | """"""""" |
| 1718 | |
| 1719 | A vector type is a simple derived type that represents a vector of |
| 1720 | elements. Vector types are used when multiple primitive data are |
| 1721 | operated in parallel using a single instruction (SIMD). A vector type |
| 1722 | requires a size (number of elements) and an underlying primitive data |
| 1723 | type. Vector types are considered :ref:`first class <t_firstclass>`. |
| 1724 | |
| 1725 | Syntax: |
| 1726 | """"""" |
| 1727 | |
| 1728 | :: |
| 1729 | |
| 1730 | < <# elements> x <elementtype> > |
| 1731 | |
| 1732 | The number of elements is a constant integer value larger than 0; |
| 1733 | elementtype may be any integer or floating point type, or a pointer to |
| 1734 | these types. Vectors of size zero are not allowed. |
| 1735 | |
| 1736 | Examples: |
| 1737 | """"""""" |
| 1738 | |
| 1739 | +-------------------+--------------------------------------------------+ |
| 1740 | | ``<4 x i32>`` | Vector of 4 32-bit integer values. | |
| 1741 | +-------------------+--------------------------------------------------+ |
| 1742 | | ``<8 x float>`` | Vector of 8 32-bit floating-point values. | |
| 1743 | +-------------------+--------------------------------------------------+ |
| 1744 | | ``<2 x i64>`` | Vector of 2 64-bit integer values. | |
| 1745 | +-------------------+--------------------------------------------------+ |
| 1746 | | ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. | |
| 1747 | +-------------------+--------------------------------------------------+ |
| 1748 | |
| 1749 | Constants |
| 1750 | ========= |
| 1751 | |
| 1752 | LLVM has several different basic types of constants. This section |
| 1753 | describes them all and their syntax. |
| 1754 | |
| 1755 | Simple Constants |
| 1756 | ---------------- |
| 1757 | |
| 1758 | **Boolean constants** |
| 1759 | The two strings '``true``' and '``false``' are both valid constants |
| 1760 | of the ``i1`` type. |
| 1761 | **Integer constants** |
| 1762 | Standard integers (such as '4') are constants of the |
| 1763 | :ref:`integer <t_integer>` type. Negative numbers may be used with |
| 1764 | integer types. |
| 1765 | **Floating point constants** |
| 1766 | Floating point constants use standard decimal notation (e.g. |
| 1767 | 123.421), exponential notation (e.g. 1.23421e+2), or a more precise |
| 1768 | hexadecimal notation (see below). The assembler requires the exact |
| 1769 | decimal value of a floating-point constant. For example, the |
| 1770 | assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating |
| 1771 | decimal in binary. Floating point constants must have a :ref:`floating |
| 1772 | point <t_floating>` type. |
| 1773 | **Null pointer constants** |
| 1774 | The identifier '``null``' is recognized as a null pointer constant |
| 1775 | and must be of :ref:`pointer type <t_pointer>`. |
| 1776 | |
| 1777 | The one non-intuitive notation for constants is the hexadecimal form of |
| 1778 | floating point constants. For example, the form |
| 1779 | '``double 0x432ff973cafa8000``' is equivalent to (but harder to read |
| 1780 | than) '``double 4.5e+15``'. The only time hexadecimal floating point |
| 1781 | constants are required (and the only time that they are generated by the |
| 1782 | disassembler) is when a floating point constant must be emitted but it |
| 1783 | cannot be represented as a decimal floating point number in a reasonable |
| 1784 | number of digits. For example, NaN's, infinities, and other special |
| 1785 | values are represented in their IEEE hexadecimal format so that assembly |
| 1786 | and disassembly do not cause any bits to change in the constants. |
| 1787 | |
| 1788 | When using the hexadecimal form, constants of types half, float, and |
| 1789 | double are represented using the 16-digit form shown above (which |
| 1790 | matches the IEEE754 representation for double); half and float values |
Dmitri Gribenko | c3c8d2a | 2013-01-16 23:40:37 +0000 | [diff] [blame] | 1791 | must, however, be exactly representable as IEEE 754 half and single |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 1792 | precision, respectively. Hexadecimal format is always used for long |
| 1793 | double, and there are three forms of long double. The 80-bit format used |
| 1794 | by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The |
| 1795 | 128-bit format used by PowerPC (two adjacent doubles) is represented by |
| 1796 | ``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is |
| 1797 | represented by ``0xL`` followed by 32 hexadecimal digits; no currently |
| 1798 | supported target uses this format. Long doubles will only work if they |
| 1799 | match the long double format on your target. The IEEE 16-bit format |
| 1800 | (half precision) is represented by ``0xH`` followed by 4 hexadecimal |
| 1801 | digits. All hexadecimal formats are big-endian (sign bit at the left). |
| 1802 | |
| 1803 | There are no constants of type x86mmx. |
| 1804 | |
| 1805 | Complex Constants |
| 1806 | ----------------- |
| 1807 | |
| 1808 | Complex constants are a (potentially recursive) combination of simple |
| 1809 | constants and smaller complex constants. |
| 1810 | |
| 1811 | **Structure constants** |
| 1812 | Structure constants are represented with notation similar to |
| 1813 | structure type definitions (a comma separated list of elements, |
| 1814 | surrounded by braces (``{}``)). For example: |
| 1815 | "``{ i32 4, float 17.0, i32* @G }``", where "``@G``" is declared as |
| 1816 | "``@G = external global i32``". Structure constants must have |
| 1817 | :ref:`structure type <t_struct>`, and the number and types of elements |
| 1818 | must match those specified by the type. |
| 1819 | **Array constants** |
| 1820 | Array constants are represented with notation similar to array type |
| 1821 | definitions (a comma separated list of elements, surrounded by |
| 1822 | square brackets (``[]``)). For example: |
| 1823 | "``[ i32 42, i32 11, i32 74 ]``". Array constants must have |
| 1824 | :ref:`array type <t_array>`, and the number and types of elements must |
| 1825 | match those specified by the type. |
| 1826 | **Vector constants** |
| 1827 | Vector constants are represented with notation similar to vector |
| 1828 | type definitions (a comma separated list of elements, surrounded by |
| 1829 | less-than/greater-than's (``<>``)). For example: |
| 1830 | "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants |
| 1831 | must have :ref:`vector type <t_vector>`, and the number and types of |
| 1832 | elements must match those specified by the type. |
| 1833 | **Zero initialization** |
| 1834 | The string '``zeroinitializer``' can be used to zero initialize a |
| 1835 | value to zero of *any* type, including scalar and |
| 1836 | :ref:`aggregate <t_aggregate>` types. This is often used to avoid |
| 1837 | having to print large zero initializers (e.g. for large arrays) and |
| 1838 | is always exactly equivalent to using explicit zero initializers. |
| 1839 | **Metadata node** |
| 1840 | A metadata node is a structure-like constant with :ref:`metadata |
| 1841 | type <t_metadata>`. For example: |
| 1842 | "``metadata !{ i32 0, metadata !"test" }``". Unlike other |
| 1843 | constants that are meant to be interpreted as part of the |
| 1844 | instruction stream, metadata is a place to attach additional |
| 1845 | information such as debug info. |
| 1846 | |
| 1847 | Global Variable and Function Addresses |
| 1848 | -------------------------------------- |
| 1849 | |
| 1850 | The addresses of :ref:`global variables <globalvars>` and |
| 1851 | :ref:`functions <functionstructure>` are always implicitly valid |
| 1852 | (link-time) constants. These constants are explicitly referenced when |
| 1853 | the :ref:`identifier for the global <identifiers>` is used and always have |
| 1854 | :ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM |
| 1855 | file: |
| 1856 | |
| 1857 | .. code-block:: llvm |
| 1858 | |
| 1859 | @X = global i32 17 |
| 1860 | @Y = global i32 42 |
| 1861 | @Z = global [2 x i32*] [ i32* @X, i32* @Y ] |
| 1862 | |
| 1863 | .. _undefvalues: |
| 1864 | |
| 1865 | Undefined Values |
| 1866 | ---------------- |
| 1867 | |
| 1868 | The string '``undef``' can be used anywhere a constant is expected, and |
| 1869 | indicates that the user of the value may receive an unspecified |
| 1870 | bit-pattern. Undefined values may be of any type (other than '``label``' |
| 1871 | or '``void``') and be used anywhere a constant is permitted. |
| 1872 | |
| 1873 | Undefined values are useful because they indicate to the compiler that |
| 1874 | the program is well defined no matter what value is used. This gives the |
| 1875 | compiler more freedom to optimize. Here are some examples of |
| 1876 | (potentially surprising) transformations that are valid (in pseudo IR): |
| 1877 | |
| 1878 | .. code-block:: llvm |
| 1879 | |
| 1880 | %A = add %X, undef |
| 1881 | %B = sub %X, undef |
| 1882 | %C = xor %X, undef |
| 1883 | Safe: |
| 1884 | %A = undef |
| 1885 | %B = undef |
| 1886 | %C = undef |
| 1887 | |
| 1888 | This is safe because all of the output bits are affected by the undef |
| 1889 | bits. Any output bit can have a zero or one depending on the input bits. |
| 1890 | |
| 1891 | .. code-block:: llvm |
| 1892 | |
| 1893 | %A = or %X, undef |
| 1894 | %B = and %X, undef |
| 1895 | Safe: |
| 1896 | %A = -1 |
| 1897 | %B = 0 |
| 1898 | Unsafe: |
| 1899 | %A = undef |
| 1900 | %B = undef |
| 1901 | |
| 1902 | These logical operations have bits that are not always affected by the |
| 1903 | input. For example, if ``%X`` has a zero bit, then the output of the |
| 1904 | '``and``' operation will always be a zero for that bit, no matter what |
| 1905 | the corresponding bit from the '``undef``' is. As such, it is unsafe to |
| 1906 | optimize or assume that the result of the '``and``' is '``undef``'. |
| 1907 | However, it is safe to assume that all bits of the '``undef``' could be |
| 1908 | 0, and optimize the '``and``' to 0. Likewise, it is safe to assume that |
| 1909 | all the bits of the '``undef``' operand to the '``or``' could be set, |
| 1910 | allowing the '``or``' to be folded to -1. |
| 1911 | |
| 1912 | .. code-block:: llvm |
| 1913 | |
| 1914 | %A = select undef, %X, %Y |
| 1915 | %B = select undef, 42, %Y |
| 1916 | %C = select %X, %Y, undef |
| 1917 | Safe: |
| 1918 | %A = %X (or %Y) |
| 1919 | %B = 42 (or %Y) |
| 1920 | %C = %Y |
| 1921 | Unsafe: |
| 1922 | %A = undef |
| 1923 | %B = undef |
| 1924 | %C = undef |
| 1925 | |
| 1926 | This set of examples shows that undefined '``select``' (and conditional |
| 1927 | branch) conditions can go *either way*, but they have to come from one |
| 1928 | of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were |
| 1929 | both known to have a clear low bit, then ``%A`` would have to have a |
| 1930 | cleared low bit. However, in the ``%C`` example, the optimizer is |
| 1931 | allowed to assume that the '``undef``' operand could be the same as |
| 1932 | ``%Y``, allowing the whole '``select``' to be eliminated. |
| 1933 | |
| 1934 | .. code-block:: llvm |
| 1935 | |
| 1936 | %A = xor undef, undef |
| 1937 | |
| 1938 | %B = undef |
| 1939 | %C = xor %B, %B |
| 1940 | |
| 1941 | %D = undef |
| 1942 | %E = icmp lt %D, 4 |
| 1943 | %F = icmp gte %D, 4 |
| 1944 | |
| 1945 | Safe: |
| 1946 | %A = undef |
| 1947 | %B = undef |
| 1948 | %C = undef |
| 1949 | %D = undef |
| 1950 | %E = undef |
| 1951 | %F = undef |
| 1952 | |
| 1953 | This example points out that two '``undef``' operands are not |
| 1954 | necessarily the same. This can be surprising to people (and also matches |
| 1955 | C semantics) where they assume that "``X^X``" is always zero, even if |
| 1956 | ``X`` is undefined. This isn't true for a number of reasons, but the |
| 1957 | short answer is that an '``undef``' "variable" can arbitrarily change |
| 1958 | its value over its "live range". This is true because the variable |
| 1959 | doesn't actually *have a live range*. Instead, the value is logically |
| 1960 | read from arbitrary registers that happen to be around when needed, so |
| 1961 | the value is not necessarily consistent over time. In fact, ``%A`` and |
| 1962 | ``%C`` need to have the same semantics or the core LLVM "replace all |
| 1963 | uses with" concept would not hold. |
| 1964 | |
| 1965 | .. code-block:: llvm |
| 1966 | |
| 1967 | %A = fdiv undef, %X |
| 1968 | %B = fdiv %X, undef |
| 1969 | Safe: |
| 1970 | %A = undef |
| 1971 | b: unreachable |
| 1972 | |
| 1973 | These examples show the crucial difference between an *undefined value* |
| 1974 | and *undefined behavior*. An undefined value (like '``undef``') is |
| 1975 | allowed to have an arbitrary bit-pattern. This means that the ``%A`` |
| 1976 | operation can be constant folded to '``undef``', because the '``undef``' |
| 1977 | could be an SNaN, and ``fdiv`` is not (currently) defined on SNaN's. |
| 1978 | However, in the second example, we can make a more aggressive |
| 1979 | assumption: because the ``undef`` is allowed to be an arbitrary value, |
| 1980 | we are allowed to assume that it could be zero. Since a divide by zero |
| 1981 | has *undefined behavior*, we are allowed to assume that the operation |
| 1982 | does not execute at all. This allows us to delete the divide and all |
| 1983 | code after it. Because the undefined operation "can't happen", the |
| 1984 | optimizer can assume that it occurs in dead code. |
| 1985 | |
| 1986 | .. code-block:: llvm |
| 1987 | |
| 1988 | a: store undef -> %X |
| 1989 | b: store %X -> undef |
| 1990 | Safe: |
| 1991 | a: <deleted> |
| 1992 | b: unreachable |
| 1993 | |
| 1994 | These examples reiterate the ``fdiv`` example: a store *of* an undefined |
| 1995 | value can be assumed to not have any effect; we can assume that the |
| 1996 | value is overwritten with bits that happen to match what was already |
| 1997 | there. However, a store *to* an undefined location could clobber |
| 1998 | arbitrary memory, therefore, it has undefined behavior. |
| 1999 | |
| 2000 | .. _poisonvalues: |
| 2001 | |
| 2002 | Poison Values |
| 2003 | ------------- |
| 2004 | |
| 2005 | Poison values are similar to :ref:`undef values <undefvalues>`, however |
| 2006 | they also represent the fact that an instruction or constant expression |
| 2007 | which cannot evoke side effects has nevertheless detected a condition |
| 2008 | which results in undefined behavior. |
| 2009 | |
| 2010 | There is currently no way of representing a poison value in the IR; they |
| 2011 | only exist when produced by operations such as :ref:`add <i_add>` with |
| 2012 | the ``nsw`` flag. |
| 2013 | |
| 2014 | Poison value behavior is defined in terms of value *dependence*: |
| 2015 | |
| 2016 | - Values other than :ref:`phi <i_phi>` nodes depend on their operands. |
| 2017 | - :ref:`Phi <i_phi>` nodes depend on the operand corresponding to |
| 2018 | their dynamic predecessor basic block. |
| 2019 | - Function arguments depend on the corresponding actual argument values |
| 2020 | in the dynamic callers of their functions. |
| 2021 | - :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>` |
| 2022 | instructions that dynamically transfer control back to them. |
| 2023 | - :ref:`Invoke <i_invoke>` instructions depend on the |
| 2024 | :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing |
| 2025 | call instructions that dynamically transfer control back to them. |
| 2026 | - Non-volatile loads and stores depend on the most recent stores to all |
| 2027 | of the referenced memory addresses, following the order in the IR |
| 2028 | (including loads and stores implied by intrinsics such as |
| 2029 | :ref:`@llvm.memcpy <int_memcpy>`.) |
| 2030 | - An instruction with externally visible side effects depends on the |
| 2031 | most recent preceding instruction with externally visible side |
| 2032 | effects, following the order in the IR. (This includes :ref:`volatile |
| 2033 | operations <volatile>`.) |
| 2034 | - An instruction *control-depends* on a :ref:`terminator |
| 2035 | instruction <terminators>` if the terminator instruction has |
| 2036 | multiple successors and the instruction is always executed when |
| 2037 | control transfers to one of the successors, and may not be executed |
| 2038 | when control is transferred to another. |
| 2039 | - Additionally, an instruction also *control-depends* on a terminator |
| 2040 | instruction if the set of instructions it otherwise depends on would |
| 2041 | be different if the terminator had transferred control to a different |
| 2042 | successor. |
| 2043 | - Dependence is transitive. |
| 2044 | |
| 2045 | Poison Values have the same behavior as :ref:`undef values <undefvalues>`, |
| 2046 | with the additional affect that any instruction which has a *dependence* |
| 2047 | on a poison value has undefined behavior. |
| 2048 | |
| 2049 | Here are some examples: |
| 2050 | |
| 2051 | .. code-block:: llvm |
| 2052 | |
| 2053 | entry: |
| 2054 | %poison = sub nuw i32 0, 1 ; Results in a poison value. |
| 2055 | %still_poison = and i32 %poison, 0 ; 0, but also poison. |
| 2056 | %poison_yet_again = getelementptr i32* @h, i32 %still_poison |
| 2057 | store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned |
| 2058 | |
| 2059 | store i32 %poison, i32* @g ; Poison value stored to memory. |
| 2060 | %poison2 = load i32* @g ; Poison value loaded back from memory. |
| 2061 | |
| 2062 | store volatile i32 %poison, i32* @g ; External observation; undefined behavior. |
| 2063 | |
| 2064 | %narrowaddr = bitcast i32* @g to i16* |
| 2065 | %wideaddr = bitcast i32* @g to i64* |
| 2066 | %poison3 = load i16* %narrowaddr ; Returns a poison value. |
| 2067 | %poison4 = load i64* %wideaddr ; Returns a poison value. |
| 2068 | |
| 2069 | %cmp = icmp slt i32 %poison, 0 ; Returns a poison value. |
| 2070 | br i1 %cmp, label %true, label %end ; Branch to either destination. |
| 2071 | |
| 2072 | true: |
| 2073 | store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so |
| 2074 | ; it has undefined behavior. |
| 2075 | br label %end |
| 2076 | |
| 2077 | end: |
| 2078 | %p = phi i32 [ 0, %entry ], [ 1, %true ] |
| 2079 | ; Both edges into this PHI are |
| 2080 | ; control-dependent on %cmp, so this |
| 2081 | ; always results in a poison value. |
| 2082 | |
| 2083 | store volatile i32 0, i32* @g ; This would depend on the store in %true |
| 2084 | ; if %cmp is true, or the store in %entry |
| 2085 | ; otherwise, so this is undefined behavior. |
| 2086 | |
| 2087 | br i1 %cmp, label %second_true, label %second_end |
| 2088 | ; The same branch again, but this time the |
| 2089 | ; true block doesn't have side effects. |
| 2090 | |
| 2091 | second_true: |
| 2092 | ; No side effects! |
| 2093 | ret void |
| 2094 | |
| 2095 | second_end: |
| 2096 | store volatile i32 0, i32* @g ; This time, the instruction always depends |
| 2097 | ; on the store in %end. Also, it is |
| 2098 | ; control-equivalent to %end, so this is |
| 2099 | ; well-defined (ignoring earlier undefined |
| 2100 | ; behavior in this example). |
| 2101 | |
| 2102 | .. _blockaddress: |
| 2103 | |
| 2104 | Addresses of Basic Blocks |
| 2105 | ------------------------- |
| 2106 | |
| 2107 | ``blockaddress(@function, %block)`` |
| 2108 | |
| 2109 | The '``blockaddress``' constant computes the address of the specified |
| 2110 | basic block in the specified function, and always has an ``i8*`` type. |
| 2111 | Taking the address of the entry block is illegal. |
| 2112 | |
| 2113 | This value only has defined behavior when used as an operand to the |
| 2114 | ':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons |
| 2115 | against null. Pointer equality tests between labels addresses results in |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 2116 | undefined behavior --- though, again, comparison against null is ok, and |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2117 | no label is equal to the null pointer. This may be passed around as an |
| 2118 | opaque pointer sized value as long as the bits are not inspected. This |
| 2119 | allows ``ptrtoint`` and arithmetic to be performed on these values so |
| 2120 | long as the original value is reconstituted before the ``indirectbr`` |
| 2121 | instruction. |
| 2122 | |
| 2123 | Finally, some targets may provide defined semantics when using the value |
| 2124 | as the operand to an inline assembly, but that is target specific. |
| 2125 | |
| 2126 | Constant Expressions |
| 2127 | -------------------- |
| 2128 | |
| 2129 | Constant expressions are used to allow expressions involving other |
| 2130 | constants to be used as constants. Constant expressions may be of any |
| 2131 | :ref:`first class <t_firstclass>` type and may involve any LLVM operation |
| 2132 | that does not have side effects (e.g. load and call are not supported). |
| 2133 | The following is the syntax for constant expressions: |
| 2134 | |
| 2135 | ``trunc (CST to TYPE)`` |
| 2136 | Truncate a constant to another type. The bit size of CST must be |
| 2137 | larger than the bit size of TYPE. Both types must be integers. |
| 2138 | ``zext (CST to TYPE)`` |
| 2139 | Zero extend a constant to another type. The bit size of CST must be |
| 2140 | smaller than the bit size of TYPE. Both types must be integers. |
| 2141 | ``sext (CST to TYPE)`` |
| 2142 | Sign extend a constant to another type. The bit size of CST must be |
| 2143 | smaller than the bit size of TYPE. Both types must be integers. |
| 2144 | ``fptrunc (CST to TYPE)`` |
| 2145 | Truncate a floating point constant to another floating point type. |
| 2146 | The size of CST must be larger than the size of TYPE. Both types |
| 2147 | must be floating point. |
| 2148 | ``fpext (CST to TYPE)`` |
| 2149 | Floating point extend a constant to another type. The size of CST |
| 2150 | must be smaller or equal to the size of TYPE. Both types must be |
| 2151 | floating point. |
| 2152 | ``fptoui (CST to TYPE)`` |
| 2153 | Convert a floating point constant to the corresponding unsigned |
| 2154 | integer constant. TYPE must be a scalar or vector integer type. CST |
| 2155 | must be of scalar or vector floating point type. Both CST and TYPE |
| 2156 | must be scalars, or vectors of the same number of elements. If the |
| 2157 | value won't fit in the integer type, the results are undefined. |
| 2158 | ``fptosi (CST to TYPE)`` |
| 2159 | Convert a floating point constant to the corresponding signed |
| 2160 | integer constant. TYPE must be a scalar or vector integer type. CST |
| 2161 | must be of scalar or vector floating point type. Both CST and TYPE |
| 2162 | must be scalars, or vectors of the same number of elements. If the |
| 2163 | value won't fit in the integer type, the results are undefined. |
| 2164 | ``uitofp (CST to TYPE)`` |
| 2165 | Convert an unsigned integer constant to the corresponding floating |
| 2166 | point constant. TYPE must be a scalar or vector floating point type. |
| 2167 | CST must be of scalar or vector integer type. Both CST and TYPE must |
| 2168 | be scalars, or vectors of the same number of elements. If the value |
| 2169 | won't fit in the floating point type, the results are undefined. |
| 2170 | ``sitofp (CST to TYPE)`` |
| 2171 | Convert a signed integer constant to the corresponding floating |
| 2172 | point constant. TYPE must be a scalar or vector floating point type. |
| 2173 | CST must be of scalar or vector integer type. Both CST and TYPE must |
| 2174 | be scalars, or vectors of the same number of elements. If the value |
| 2175 | won't fit in the floating point type, the results are undefined. |
| 2176 | ``ptrtoint (CST to TYPE)`` |
| 2177 | Convert a pointer typed constant to the corresponding integer |
| 2178 | constant ``TYPE`` must be an integer type. ``CST`` must be of |
| 2179 | pointer type. The ``CST`` value is zero extended, truncated, or |
| 2180 | unchanged to make it fit in ``TYPE``. |
| 2181 | ``inttoptr (CST to TYPE)`` |
| 2182 | Convert an integer constant to a pointer constant. TYPE must be a |
| 2183 | pointer type. CST must be of integer type. The CST value is zero |
| 2184 | extended, truncated, or unchanged to make it fit in a pointer size. |
| 2185 | This one is *really* dangerous! |
| 2186 | ``bitcast (CST to TYPE)`` |
| 2187 | Convert a constant, CST, to another TYPE. The constraints of the |
| 2188 | operands are the same as those for the :ref:`bitcast |
| 2189 | instruction <i_bitcast>`. |
| 2190 | ``getelementptr (CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)`` |
| 2191 | Perform the :ref:`getelementptr operation <i_getelementptr>` on |
| 2192 | constants. As with the :ref:`getelementptr <i_getelementptr>` |
| 2193 | instruction, the index list may have zero or more indexes, which are |
| 2194 | required to make sense for the type of "CSTPTR". |
| 2195 | ``select (COND, VAL1, VAL2)`` |
| 2196 | Perform the :ref:`select operation <i_select>` on constants. |
| 2197 | ``icmp COND (VAL1, VAL2)`` |
| 2198 | Performs the :ref:`icmp operation <i_icmp>` on constants. |
| 2199 | ``fcmp COND (VAL1, VAL2)`` |
| 2200 | Performs the :ref:`fcmp operation <i_fcmp>` on constants. |
| 2201 | ``extractelement (VAL, IDX)`` |
| 2202 | Perform the :ref:`extractelement operation <i_extractelement>` on |
| 2203 | constants. |
| 2204 | ``insertelement (VAL, ELT, IDX)`` |
| 2205 | Perform the :ref:`insertelement operation <i_insertelement>` on |
| 2206 | constants. |
| 2207 | ``shufflevector (VEC1, VEC2, IDXMASK)`` |
| 2208 | Perform the :ref:`shufflevector operation <i_shufflevector>` on |
| 2209 | constants. |
| 2210 | ``extractvalue (VAL, IDX0, IDX1, ...)`` |
| 2211 | Perform the :ref:`extractvalue operation <i_extractvalue>` on |
| 2212 | constants. The index list is interpreted in a similar manner as |
| 2213 | indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At |
| 2214 | least one index value must be specified. |
| 2215 | ``insertvalue (VAL, ELT, IDX0, IDX1, ...)`` |
| 2216 | Perform the :ref:`insertvalue operation <i_insertvalue>` on constants. |
| 2217 | The index list is interpreted in a similar manner as indices in a |
| 2218 | ':ref:`getelementptr <i_getelementptr>`' operation. At least one index |
| 2219 | value must be specified. |
| 2220 | ``OPCODE (LHS, RHS)`` |
| 2221 | Perform the specified operation of the LHS and RHS constants. OPCODE |
| 2222 | may be any of the :ref:`binary <binaryops>` or :ref:`bitwise |
| 2223 | binary <bitwiseops>` operations. The constraints on operands are |
| 2224 | the same as those for the corresponding instruction (e.g. no bitwise |
| 2225 | operations on floating point values are allowed). |
| 2226 | |
| 2227 | Other Values |
| 2228 | ============ |
| 2229 | |
| 2230 | Inline Assembler Expressions |
| 2231 | ---------------------------- |
| 2232 | |
| 2233 | LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level |
| 2234 | Inline Assembly <moduleasm>`) through the use of a special value. This |
| 2235 | value represents the inline assembler as a string (containing the |
| 2236 | instructions to emit), a list of operand constraints (stored as a |
| 2237 | string), a flag that indicates whether or not the inline asm expression |
| 2238 | has side effects, and a flag indicating whether the function containing |
| 2239 | the asm needs to align its stack conservatively. An example inline |
| 2240 | assembler expression is: |
| 2241 | |
| 2242 | .. code-block:: llvm |
| 2243 | |
| 2244 | i32 (i32) asm "bswap $0", "=r,r" |
| 2245 | |
| 2246 | Inline assembler expressions may **only** be used as the callee operand |
| 2247 | of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction. |
| 2248 | Thus, typically we have: |
| 2249 | |
| 2250 | .. code-block:: llvm |
| 2251 | |
| 2252 | %X = call i32 asm "bswap $0", "=r,r"(i32 %Y) |
| 2253 | |
| 2254 | Inline asms with side effects not visible in the constraint list must be |
| 2255 | marked as having side effects. This is done through the use of the |
| 2256 | '``sideeffect``' keyword, like so: |
| 2257 | |
| 2258 | .. code-block:: llvm |
| 2259 | |
| 2260 | call void asm sideeffect "eieio", ""() |
| 2261 | |
| 2262 | In some cases inline asms will contain code that will not work unless |
| 2263 | the stack is aligned in some way, such as calls or SSE instructions on |
| 2264 | x86, yet will not contain code that does that alignment within the asm. |
| 2265 | The compiler should make conservative assumptions about what the asm |
| 2266 | might contain and should generate its usual stack alignment code in the |
| 2267 | prologue if the '``alignstack``' keyword is present: |
| 2268 | |
| 2269 | .. code-block:: llvm |
| 2270 | |
| 2271 | call void asm alignstack "eieio", ""() |
| 2272 | |
| 2273 | Inline asms also support using non-standard assembly dialects. The |
| 2274 | assumed dialect is ATT. When the '``inteldialect``' keyword is present, |
| 2275 | the inline asm is using the Intel dialect. Currently, ATT and Intel are |
| 2276 | the only supported dialects. An example is: |
| 2277 | |
| 2278 | .. code-block:: llvm |
| 2279 | |
| 2280 | call void asm inteldialect "eieio", ""() |
| 2281 | |
| 2282 | If multiple keywords appear the '``sideeffect``' keyword must come |
| 2283 | first, the '``alignstack``' keyword second and the '``inteldialect``' |
| 2284 | keyword last. |
| 2285 | |
| 2286 | Inline Asm Metadata |
| 2287 | ^^^^^^^^^^^^^^^^^^^ |
| 2288 | |
| 2289 | The call instructions that wrap inline asm nodes may have a |
| 2290 | "``!srcloc``" MDNode attached to it that contains a list of constant |
| 2291 | integers. If present, the code generator will use the integer as the |
| 2292 | location cookie value when report errors through the ``LLVMContext`` |
| 2293 | error reporting mechanisms. This allows a front-end to correlate backend |
| 2294 | errors that occur with inline asm back to the source code that produced |
| 2295 | it. For example: |
| 2296 | |
| 2297 | .. code-block:: llvm |
| 2298 | |
| 2299 | call void asm sideeffect "something bad", ""(), !srcloc !42 |
| 2300 | ... |
| 2301 | !42 = !{ i32 1234567 } |
| 2302 | |
| 2303 | It is up to the front-end to make sense of the magic numbers it places |
| 2304 | in the IR. If the MDNode contains multiple constants, the code generator |
| 2305 | will use the one that corresponds to the line of the asm that the error |
| 2306 | occurs on. |
| 2307 | |
| 2308 | .. _metadata: |
| 2309 | |
| 2310 | Metadata Nodes and Metadata Strings |
| 2311 | ----------------------------------- |
| 2312 | |
| 2313 | LLVM IR allows metadata to be attached to instructions in the program |
| 2314 | that can convey extra information about the code to the optimizers and |
| 2315 | code generator. One example application of metadata is source-level |
| 2316 | debug information. There are two metadata primitives: strings and nodes. |
| 2317 | All metadata has the ``metadata`` type and is identified in syntax by a |
| 2318 | preceding exclamation point ('``!``'). |
| 2319 | |
| 2320 | A metadata string is a string surrounded by double quotes. It can |
| 2321 | contain any character by escaping non-printable characters with |
| 2322 | "``\xx``" where "``xx``" is the two digit hex code. For example: |
| 2323 | "``!"test\00"``". |
| 2324 | |
| 2325 | Metadata nodes are represented with notation similar to structure |
| 2326 | constants (a comma separated list of elements, surrounded by braces and |
| 2327 | preceded by an exclamation point). Metadata nodes can have any values as |
| 2328 | their operand. For example: |
| 2329 | |
| 2330 | .. code-block:: llvm |
| 2331 | |
| 2332 | !{ metadata !"test\00", i32 10} |
| 2333 | |
| 2334 | A :ref:`named metadata <namedmetadatastructure>` is a collection of |
| 2335 | metadata nodes, which can be looked up in the module symbol table. For |
| 2336 | example: |
| 2337 | |
| 2338 | .. code-block:: llvm |
| 2339 | |
| 2340 | !foo = metadata !{!4, !3} |
| 2341 | |
| 2342 | Metadata can be used as function arguments. Here ``llvm.dbg.value`` |
| 2343 | function is using two metadata arguments: |
| 2344 | |
| 2345 | .. code-block:: llvm |
| 2346 | |
| 2347 | call void @llvm.dbg.value(metadata !24, i64 0, metadata !25) |
| 2348 | |
| 2349 | Metadata can be attached with an instruction. Here metadata ``!21`` is |
| 2350 | attached to the ``add`` instruction using the ``!dbg`` identifier: |
| 2351 | |
| 2352 | .. code-block:: llvm |
| 2353 | |
| 2354 | %indvar.next = add i64 %indvar, 1, !dbg !21 |
| 2355 | |
| 2356 | More information about specific metadata nodes recognized by the |
| 2357 | optimizers and code generator is found below. |
| 2358 | |
| 2359 | '``tbaa``' Metadata |
| 2360 | ^^^^^^^^^^^^^^^^^^^ |
| 2361 | |
| 2362 | In LLVM IR, memory does not have types, so LLVM's own type system is not |
| 2363 | suitable for doing TBAA. Instead, metadata is added to the IR to |
| 2364 | describe a type system of a higher level language. This can be used to |
| 2365 | implement typical C/C++ TBAA, but it can also be used to implement |
| 2366 | custom alias analysis behavior for other languages. |
| 2367 | |
| 2368 | The current metadata format is very simple. TBAA metadata nodes have up |
| 2369 | to three fields, e.g.: |
| 2370 | |
| 2371 | .. code-block:: llvm |
| 2372 | |
| 2373 | !0 = metadata !{ metadata !"an example type tree" } |
| 2374 | !1 = metadata !{ metadata !"int", metadata !0 } |
| 2375 | !2 = metadata !{ metadata !"float", metadata !0 } |
| 2376 | !3 = metadata !{ metadata !"const float", metadata !2, i64 1 } |
| 2377 | |
| 2378 | The first field is an identity field. It can be any value, usually a |
| 2379 | metadata string, which uniquely identifies the type. The most important |
| 2380 | name in the tree is the name of the root node. Two trees with different |
| 2381 | root node names are entirely disjoint, even if they have leaves with |
| 2382 | common names. |
| 2383 | |
| 2384 | The second field identifies the type's parent node in the tree, or is |
| 2385 | null or omitted for a root node. A type is considered to alias all of |
| 2386 | its descendants and all of its ancestors in the tree. Also, a type is |
| 2387 | considered to alias all types in other trees, so that bitcode produced |
| 2388 | from multiple front-ends is handled conservatively. |
| 2389 | |
| 2390 | If the third field is present, it's an integer which if equal to 1 |
| 2391 | indicates that the type is "constant" (meaning |
| 2392 | ``pointsToConstantMemory`` should return true; see `other useful |
| 2393 | AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_). |
| 2394 | |
| 2395 | '``tbaa.struct``' Metadata |
| 2396 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 2397 | |
| 2398 | The :ref:`llvm.memcpy <int_memcpy>` is often used to implement |
| 2399 | aggregate assignment operations in C and similar languages, however it |
| 2400 | is defined to copy a contiguous region of memory, which is more than |
| 2401 | strictly necessary for aggregate types which contain holes due to |
| 2402 | padding. Also, it doesn't contain any TBAA information about the fields |
| 2403 | of the aggregate. |
| 2404 | |
| 2405 | ``!tbaa.struct`` metadata can describe which memory subregions in a |
| 2406 | memcpy are padding and what the TBAA tags of the struct are. |
| 2407 | |
| 2408 | The current metadata format is very simple. ``!tbaa.struct`` metadata |
| 2409 | nodes are a list of operands which are in conceptual groups of three. |
| 2410 | For each group of three, the first operand gives the byte offset of a |
| 2411 | field in bytes, the second gives its size in bytes, and the third gives |
| 2412 | its tbaa tag. e.g.: |
| 2413 | |
| 2414 | .. code-block:: llvm |
| 2415 | |
| 2416 | !4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 } |
| 2417 | |
| 2418 | This describes a struct with two fields. The first is at offset 0 bytes |
| 2419 | with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes |
| 2420 | and has size 4 bytes and has tbaa tag !2. |
| 2421 | |
| 2422 | Note that the fields need not be contiguous. In this example, there is a |
| 2423 | 4 byte gap between the two fields. This gap represents padding which |
| 2424 | does not carry useful data and need not be preserved. |
| 2425 | |
| 2426 | '``fpmath``' Metadata |
| 2427 | ^^^^^^^^^^^^^^^^^^^^^ |
| 2428 | |
| 2429 | ``fpmath`` metadata may be attached to any instruction of floating point |
| 2430 | type. It can be used to express the maximum acceptable error in the |
| 2431 | result of that instruction, in ULPs, thus potentially allowing the |
| 2432 | compiler to use a more efficient but less accurate method of computing |
| 2433 | it. ULP is defined as follows: |
| 2434 | |
| 2435 | If ``x`` is a real number that lies between two finite consecutive |
| 2436 | floating-point numbers ``a`` and ``b``, without being equal to one |
| 2437 | of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the |
| 2438 | distance between the two non-equal finite floating-point numbers |
| 2439 | nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``. |
| 2440 | |
| 2441 | The metadata node shall consist of a single positive floating point |
| 2442 | number representing the maximum relative error, for example: |
| 2443 | |
| 2444 | .. code-block:: llvm |
| 2445 | |
| 2446 | !0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs |
| 2447 | |
| 2448 | '``range``' Metadata |
| 2449 | ^^^^^^^^^^^^^^^^^^^^ |
| 2450 | |
| 2451 | ``range`` metadata may be attached only to loads of integer types. It |
| 2452 | expresses the possible ranges the loaded value is in. The ranges are |
| 2453 | represented with a flattened list of integers. The loaded value is known |
| 2454 | to be in the union of the ranges defined by each consecutive pair. Each |
| 2455 | pair has the following properties: |
| 2456 | |
| 2457 | - The type must match the type loaded by the instruction. |
| 2458 | - The pair ``a,b`` represents the range ``[a,b)``. |
| 2459 | - Both ``a`` and ``b`` are constants. |
| 2460 | - The range is allowed to wrap. |
| 2461 | - The range should not represent the full or empty set. That is, |
| 2462 | ``a!=b``. |
| 2463 | |
| 2464 | In addition, the pairs must be in signed order of the lower bound and |
| 2465 | they must be non-contiguous. |
| 2466 | |
| 2467 | Examples: |
| 2468 | |
| 2469 | .. code-block:: llvm |
| 2470 | |
| 2471 | %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1 |
| 2472 | %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1 |
| 2473 | %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5 |
| 2474 | %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5 |
| 2475 | ... |
| 2476 | !0 = metadata !{ i8 0, i8 2 } |
| 2477 | !1 = metadata !{ i8 255, i8 2 } |
| 2478 | !2 = metadata !{ i8 0, i8 2, i8 3, i8 6 } |
| 2479 | !3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 } |
| 2480 | |
| 2481 | Module Flags Metadata |
| 2482 | ===================== |
| 2483 | |
| 2484 | Information about the module as a whole is difficult to convey to LLVM's |
| 2485 | subsystems. The LLVM IR isn't sufficient to transmit this information. |
| 2486 | The ``llvm.module.flags`` named metadata exists in order to facilitate |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 2487 | this. These flags are in the form of key / value pairs --- much like a |
| 2488 | dictionary --- making it easy for any subsystem who cares about a flag to |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2489 | look it up. |
| 2490 | |
| 2491 | The ``llvm.module.flags`` metadata contains a list of metadata triplets. |
| 2492 | Each triplet has the following form: |
| 2493 | |
| 2494 | - The first element is a *behavior* flag, which specifies the behavior |
| 2495 | when two (or more) modules are merged together, and it encounters two |
| 2496 | (or more) metadata with the same ID. The supported behaviors are |
| 2497 | described below. |
| 2498 | - The second element is a metadata string that is a unique ID for the |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2499 | metadata. Each module may only have one flag entry for each unique ID (not |
| 2500 | including entries with the **Require** behavior). |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2501 | - The third element is the value of the flag. |
| 2502 | |
| 2503 | When two (or more) modules are merged together, the resulting |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2504 | ``llvm.module.flags`` metadata is the union of the modules' flags. That is, for |
| 2505 | each unique metadata ID string, there will be exactly one entry in the merged |
| 2506 | modules ``llvm.module.flags`` metadata table, and the value for that entry will |
| 2507 | be determined by the merge behavior flag, as described below. The only exception |
| 2508 | is that entries with the *Require* behavior are always preserved. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2509 | |
| 2510 | The following behaviors are supported: |
| 2511 | |
| 2512 | .. list-table:: |
| 2513 | :header-rows: 1 |
| 2514 | :widths: 10 90 |
| 2515 | |
| 2516 | * - Value |
| 2517 | - Behavior |
| 2518 | |
| 2519 | * - 1 |
| 2520 | - **Error** |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2521 | Emits an error if two values disagree, otherwise the resulting value |
| 2522 | is that of the operands. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2523 | |
| 2524 | * - 2 |
| 2525 | - **Warning** |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2526 | Emits a warning if two values disagree. The result value will be the |
| 2527 | operand for the flag from the first module being linked. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2528 | |
| 2529 | * - 3 |
| 2530 | - **Require** |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2531 | Adds a requirement that another module flag be present and have a |
| 2532 | specified value after linking is performed. The value must be a |
| 2533 | metadata pair, where the first element of the pair is the ID of the |
| 2534 | module flag to be restricted, and the second element of the pair is |
| 2535 | the value the module flag should be restricted to. This behavior can |
| 2536 | be used to restrict the allowable results (via triggering of an |
| 2537 | error) of linking IDs with the **Override** behavior. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2538 | |
| 2539 | * - 4 |
| 2540 | - **Override** |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2541 | Uses the specified value, regardless of the behavior or value of the |
| 2542 | other module. If both modules specify **Override**, but the values |
| 2543 | differ, an error will be emitted. |
| 2544 | |
Daniel Dunbar | 5db391c | 2013-01-16 21:38:56 +0000 | [diff] [blame] | 2545 | * - 5 |
| 2546 | - **Append** |
| 2547 | Appends the two values, which are required to be metadata nodes. |
| 2548 | |
| 2549 | * - 6 |
| 2550 | - **AppendUnique** |
| 2551 | Appends the two values, which are required to be metadata |
| 2552 | nodes. However, duplicate entries in the second list are dropped |
| 2553 | during the append operation. |
| 2554 | |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2555 | It is an error for a particular unique flag ID to have multiple behaviors, |
| 2556 | except in the case of **Require** (which adds restrictions on another metadata |
| 2557 | value) or **Override**. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2558 | |
| 2559 | An example of module flags: |
| 2560 | |
| 2561 | .. code-block:: llvm |
| 2562 | |
| 2563 | !0 = metadata !{ i32 1, metadata !"foo", i32 1 } |
| 2564 | !1 = metadata !{ i32 4, metadata !"bar", i32 37 } |
| 2565 | !2 = metadata !{ i32 2, metadata !"qux", i32 42 } |
| 2566 | !3 = metadata !{ i32 3, metadata !"qux", |
| 2567 | metadata !{ |
| 2568 | metadata !"foo", i32 1 |
| 2569 | } |
| 2570 | } |
| 2571 | !llvm.module.flags = !{ !0, !1, !2, !3 } |
| 2572 | |
| 2573 | - Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior |
| 2574 | if two or more ``!"foo"`` flags are seen is to emit an error if their |
| 2575 | values are not equal. |
| 2576 | |
| 2577 | - Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The |
| 2578 | behavior if two or more ``!"bar"`` flags are seen is to use the value |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2579 | '37'. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2580 | |
| 2581 | - Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The |
| 2582 | behavior if two or more ``!"qux"`` flags are seen is to emit a |
| 2583 | warning if their values are not equal. |
| 2584 | |
| 2585 | - Metadata ``!3`` has the ID ``!"qux"`` and the value: |
| 2586 | |
| 2587 | :: |
| 2588 | |
| 2589 | metadata !{ metadata !"foo", i32 1 } |
| 2590 | |
Daniel Dunbar | 8dd938e | 2013-01-15 01:22:53 +0000 | [diff] [blame] | 2591 | The behavior is to emit an error if the ``llvm.module.flags`` does not |
| 2592 | contain a flag with the ID ``!"foo"`` that has the value '1' after linking is |
| 2593 | performed. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2594 | |
| 2595 | Objective-C Garbage Collection Module Flags Metadata |
| 2596 | ---------------------------------------------------- |
| 2597 | |
| 2598 | On the Mach-O platform, Objective-C stores metadata about garbage |
| 2599 | collection in a special section called "image info". The metadata |
| 2600 | consists of a version number and a bitmask specifying what types of |
| 2601 | garbage collection are supported (if any) by the file. If two or more |
| 2602 | modules are linked together their garbage collection metadata needs to |
| 2603 | be merged rather than appended together. |
| 2604 | |
| 2605 | The Objective-C garbage collection module flags metadata consists of the |
| 2606 | following key-value pairs: |
| 2607 | |
| 2608 | .. list-table:: |
| 2609 | :header-rows: 1 |
| 2610 | :widths: 30 70 |
| 2611 | |
| 2612 | * - Key |
| 2613 | - Value |
| 2614 | |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 2615 | * - ``Objective-C Version`` |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 2616 | - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2617 | |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 2618 | * - ``Objective-C Image Info Version`` |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 2619 | - **[Required]** --- The version of the image info section. Currently |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2620 | always 0. |
| 2621 | |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 2622 | * - ``Objective-C Image Info Section`` |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 2623 | - **[Required]** --- The section to place the metadata. Valid values are |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2624 | ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and |
| 2625 | ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for |
| 2626 | Objective-C ABI version 2. |
| 2627 | |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 2628 | * - ``Objective-C Garbage Collection`` |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 2629 | - **[Required]** --- Specifies whether garbage collection is supported or |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2630 | not. Valid values are 0, for no garbage collection, and 2, for garbage |
| 2631 | collection supported. |
| 2632 | |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 2633 | * - ``Objective-C GC Only`` |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 2634 | - **[Optional]** --- Specifies that only garbage collection is supported. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2635 | If present, its value must be 6. This flag requires that the |
| 2636 | ``Objective-C Garbage Collection`` flag have the value 2. |
| 2637 | |
| 2638 | Some important flag interactions: |
| 2639 | |
| 2640 | - If a module with ``Objective-C Garbage Collection`` set to 0 is |
| 2641 | merged with a module with ``Objective-C Garbage Collection`` set to |
| 2642 | 2, then the resulting module has the |
| 2643 | ``Objective-C Garbage Collection`` flag set to 0. |
| 2644 | - A module with ``Objective-C Garbage Collection`` set to 0 cannot be |
| 2645 | merged with a module with ``Objective-C GC Only`` set to 6. |
| 2646 | |
Daniel Dunbar | e06bfe8 | 2013-01-17 00:16:27 +0000 | [diff] [blame] | 2647 | Automatic Linker Flags Module Flags Metadata |
| 2648 | -------------------------------------------- |
| 2649 | |
| 2650 | Some targets support embedding flags to the linker inside individual object |
| 2651 | files. Typically this is used in conjunction with language extensions which |
| 2652 | allow source files to explicitly declare the libraries they depend on, and have |
| 2653 | these automatically be transmitted to the linker via object files. |
| 2654 | |
| 2655 | These flags are encoded in the IR using metadata in the module flags section, |
Daniel Dunbar | 3389dbc | 2013-01-17 18:57:32 +0000 | [diff] [blame] | 2656 | using the ``Linker Options`` key. The merge behavior for this flag is required |
Daniel Dunbar | e06bfe8 | 2013-01-17 00:16:27 +0000 | [diff] [blame] | 2657 | to be ``AppendUnique``, and the value for the key is expected to be a metadata |
| 2658 | node which should be a list of other metadata nodes, each of which should be a |
| 2659 | list of metadata strings defining linker options. |
| 2660 | |
| 2661 | For example, the following metadata section specifies two separate sets of |
| 2662 | linker options, presumably to link against ``libz`` and the ``Cocoa`` |
| 2663 | framework:: |
| 2664 | |
Daniel Dunbar | 6d49b68 | 2013-01-18 19:37:00 +0000 | [diff] [blame] | 2665 | !0 = metadata !{ i32 6, metadata !"Linker Options", |
Daniel Dunbar | e06bfe8 | 2013-01-17 00:16:27 +0000 | [diff] [blame] | 2666 | metadata !{ |
Daniel Dunbar | 6d49b68 | 2013-01-18 19:37:00 +0000 | [diff] [blame] | 2667 | metadata !{ metadata !"-lz" }, |
| 2668 | metadata !{ metadata !"-framework", metadata !"Cocoa" } } } |
Daniel Dunbar | e06bfe8 | 2013-01-17 00:16:27 +0000 | [diff] [blame] | 2669 | !llvm.module.flags = !{ !0 } |
| 2670 | |
| 2671 | The metadata encoding as lists of lists of options, as opposed to a collapsed |
| 2672 | list of options, is chosen so that the IR encoding can use multiple option |
| 2673 | strings to specify e.g., a single library, while still having that specifier be |
| 2674 | preserved as an atomic element that can be recognized by a target specific |
| 2675 | assembly writer or object file emitter. |
| 2676 | |
| 2677 | Each individual option is required to be either a valid option for the target's |
| 2678 | linker, or an option that is reserved by the target specific assembly writer or |
| 2679 | object file emitter. No other aspect of these options is defined by the IR. |
| 2680 | |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 2681 | Intrinsic Global Variables |
| 2682 | ========================== |
| 2683 | |
| 2684 | LLVM has a number of "magic" global variables that contain data that |
| 2685 | affect code generation or other IR semantics. These are documented here. |
| 2686 | All globals of this sort should have a section specified as |
| 2687 | "``llvm.metadata``". This section and all globals that start with |
| 2688 | "``llvm.``" are reserved for use by LLVM. |
| 2689 | |
| 2690 | The '``llvm.used``' Global Variable |
| 2691 | ----------------------------------- |
| 2692 | |
| 2693 | The ``@llvm.used`` global is an array with i8\* element type which has |
| 2694 | :ref:`appending linkage <linkage_appending>`. This array contains a list of |
| 2695 | pointers to global variables and functions which may optionally have a |
| 2696 | pointer cast formed of bitcast or getelementptr. For example, a legal |
| 2697 | use of it is: |
| 2698 | |
| 2699 | .. code-block:: llvm |
| 2700 | |
| 2701 | @X = global i8 4 |
| 2702 | @Y = global i32 123 |
| 2703 | |
| 2704 | @llvm.used = appending global [2 x i8*] [ |
| 2705 | i8* @X, |
| 2706 | i8* bitcast (i32* @Y to i8*) |
| 2707 | ], section "llvm.metadata" |
| 2708 | |
| 2709 | If a global variable appears in the ``@llvm.used`` list, then the |
| 2710 | compiler, assembler, and linker are required to treat the symbol as if |
| 2711 | there is a reference to the global that it cannot see. For example, if a |
| 2712 | variable has internal linkage and no references other than that from the |
| 2713 | ``@llvm.used`` list, it cannot be deleted. This is commonly used to |
| 2714 | represent references from inline asms and other things the compiler |
| 2715 | cannot "see", and corresponds to "``attribute((used))``" in GNU C. |
| 2716 | |
| 2717 | On some targets, the code generator must emit a directive to the |
| 2718 | assembler or object file to prevent the assembler and linker from |
| 2719 | molesting the symbol. |
| 2720 | |
| 2721 | The '``llvm.compiler.used``' Global Variable |
| 2722 | -------------------------------------------- |
| 2723 | |
| 2724 | The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used`` |
| 2725 | directive, except that it only prevents the compiler from touching the |
| 2726 | symbol. On targets that support it, this allows an intelligent linker to |
| 2727 | optimize references to the symbol without being impeded as it would be |
| 2728 | by ``@llvm.used``. |
| 2729 | |
| 2730 | This is a rare construct that should only be used in rare circumstances, |
| 2731 | and should not be exposed to source languages. |
| 2732 | |
| 2733 | The '``llvm.global_ctors``' Global Variable |
| 2734 | ------------------------------------------- |
| 2735 | |
| 2736 | .. code-block:: llvm |
| 2737 | |
| 2738 | %0 = type { i32, void ()* } |
| 2739 | @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }] |
| 2740 | |
| 2741 | The ``@llvm.global_ctors`` array contains a list of constructor |
| 2742 | functions and associated priorities. The functions referenced by this |
| 2743 | array will be called in ascending order of priority (i.e. lowest first) |
| 2744 | when the module is loaded. The order of functions with the same priority |
| 2745 | is not defined. |
| 2746 | |
| 2747 | The '``llvm.global_dtors``' Global Variable |
| 2748 | ------------------------------------------- |
| 2749 | |
| 2750 | .. code-block:: llvm |
| 2751 | |
| 2752 | %0 = type { i32, void ()* } |
| 2753 | @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }] |
| 2754 | |
| 2755 | The ``@llvm.global_dtors`` array contains a list of destructor functions |
| 2756 | and associated priorities. The functions referenced by this array will |
| 2757 | be called in descending order of priority (i.e. highest first) when the |
| 2758 | module is loaded. The order of functions with the same priority is not |
| 2759 | defined. |
| 2760 | |
| 2761 | Instruction Reference |
| 2762 | ===================== |
| 2763 | |
| 2764 | The LLVM instruction set consists of several different classifications |
| 2765 | of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary |
| 2766 | instructions <binaryops>`, :ref:`bitwise binary |
| 2767 | instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and |
| 2768 | :ref:`other instructions <otherops>`. |
| 2769 | |
| 2770 | .. _terminators: |
| 2771 | |
| 2772 | Terminator Instructions |
| 2773 | ----------------------- |
| 2774 | |
| 2775 | As mentioned :ref:`previously <functionstructure>`, every basic block in a |
| 2776 | program ends with a "Terminator" instruction, which indicates which |
| 2777 | block should be executed after the current block is finished. These |
| 2778 | terminator instructions typically yield a '``void``' value: they produce |
| 2779 | control flow, not values (the one exception being the |
| 2780 | ':ref:`invoke <i_invoke>`' instruction). |
| 2781 | |
| 2782 | The terminator instructions are: ':ref:`ret <i_ret>`', |
| 2783 | ':ref:`br <i_br>`', ':ref:`switch <i_switch>`', |
| 2784 | ':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`', |
| 2785 | ':ref:`resume <i_resume>`', and ':ref:`unreachable <i_unreachable>`'. |
| 2786 | |
| 2787 | .. _i_ret: |
| 2788 | |
| 2789 | '``ret``' Instruction |
| 2790 | ^^^^^^^^^^^^^^^^^^^^^ |
| 2791 | |
| 2792 | Syntax: |
| 2793 | """"""" |
| 2794 | |
| 2795 | :: |
| 2796 | |
| 2797 | ret <type> <value> ; Return a value from a non-void function |
| 2798 | ret void ; Return from void function |
| 2799 | |
| 2800 | Overview: |
| 2801 | """"""""" |
| 2802 | |
| 2803 | The '``ret``' instruction is used to return control flow (and optionally |
| 2804 | a value) from a function back to the caller. |
| 2805 | |
| 2806 | There are two forms of the '``ret``' instruction: one that returns a |
| 2807 | value and then causes control flow, and one that just causes control |
| 2808 | flow to occur. |
| 2809 | |
| 2810 | Arguments: |
| 2811 | """""""""" |
| 2812 | |
| 2813 | The '``ret``' instruction optionally accepts a single argument, the |
| 2814 | return value. The type of the return value must be a ':ref:`first |
| 2815 | class <t_firstclass>`' type. |
| 2816 | |
| 2817 | A function is not :ref:`well formed <wellformed>` if it it has a non-void |
| 2818 | return type and contains a '``ret``' instruction with no return value or |
| 2819 | a return value with a type that does not match its type, or if it has a |
| 2820 | void return type and contains a '``ret``' instruction with a return |
| 2821 | value. |
| 2822 | |
| 2823 | Semantics: |
| 2824 | """""""""" |
| 2825 | |
| 2826 | When the '``ret``' instruction is executed, control flow returns back to |
| 2827 | the calling function's context. If the caller is a |
| 2828 | ":ref:`call <i_call>`" instruction, execution continues at the |
| 2829 | instruction after the call. If the caller was an |
| 2830 | ":ref:`invoke <i_invoke>`" instruction, execution continues at the |
| 2831 | beginning of the "normal" destination block. If the instruction returns |
| 2832 | a value, that value shall set the call or invoke instruction's return |
| 2833 | value. |
| 2834 | |
| 2835 | Example: |
| 2836 | """""""" |
| 2837 | |
| 2838 | .. code-block:: llvm |
| 2839 | |
| 2840 | ret i32 5 ; Return an integer value of 5 |
| 2841 | ret void ; Return from a void function |
| 2842 | ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2 |
| 2843 | |
| 2844 | .. _i_br: |
| 2845 | |
| 2846 | '``br``' Instruction |
| 2847 | ^^^^^^^^^^^^^^^^^^^^ |
| 2848 | |
| 2849 | Syntax: |
| 2850 | """"""" |
| 2851 | |
| 2852 | :: |
| 2853 | |
| 2854 | br i1 <cond>, label <iftrue>, label <iffalse> |
| 2855 | br label <dest> ; Unconditional branch |
| 2856 | |
| 2857 | Overview: |
| 2858 | """"""""" |
| 2859 | |
| 2860 | The '``br``' instruction is used to cause control flow to transfer to a |
| 2861 | different basic block in the current function. There are two forms of |
| 2862 | this instruction, corresponding to a conditional branch and an |
| 2863 | unconditional branch. |
| 2864 | |
| 2865 | Arguments: |
| 2866 | """""""""" |
| 2867 | |
| 2868 | The conditional branch form of the '``br``' instruction takes a single |
| 2869 | '``i1``' value and two '``label``' values. The unconditional form of the |
| 2870 | '``br``' instruction takes a single '``label``' value as a target. |
| 2871 | |
| 2872 | Semantics: |
| 2873 | """""""""" |
| 2874 | |
| 2875 | Upon execution of a conditional '``br``' instruction, the '``i1``' |
| 2876 | argument is evaluated. If the value is ``true``, control flows to the |
| 2877 | '``iftrue``' ``label`` argument. If "cond" is ``false``, control flows |
| 2878 | to the '``iffalse``' ``label`` argument. |
| 2879 | |
| 2880 | Example: |
| 2881 | """""""" |
| 2882 | |
| 2883 | .. code-block:: llvm |
| 2884 | |
| 2885 | Test: |
| 2886 | %cond = icmp eq i32 %a, %b |
| 2887 | br i1 %cond, label %IfEqual, label %IfUnequal |
| 2888 | IfEqual: |
| 2889 | ret i32 1 |
| 2890 | IfUnequal: |
| 2891 | ret i32 0 |
| 2892 | |
| 2893 | .. _i_switch: |
| 2894 | |
| 2895 | '``switch``' Instruction |
| 2896 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 2897 | |
| 2898 | Syntax: |
| 2899 | """"""" |
| 2900 | |
| 2901 | :: |
| 2902 | |
| 2903 | switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ] |
| 2904 | |
| 2905 | Overview: |
| 2906 | """"""""" |
| 2907 | |
| 2908 | The '``switch``' instruction is used to transfer control flow to one of |
| 2909 | several different places. It is a generalization of the '``br``' |
| 2910 | instruction, allowing a branch to occur to one of many possible |
| 2911 | destinations. |
| 2912 | |
| 2913 | Arguments: |
| 2914 | """""""""" |
| 2915 | |
| 2916 | The '``switch``' instruction uses three parameters: an integer |
| 2917 | comparison value '``value``', a default '``label``' destination, and an |
| 2918 | array of pairs of comparison value constants and '``label``'s. The table |
| 2919 | is not allowed to contain duplicate constant entries. |
| 2920 | |
| 2921 | Semantics: |
| 2922 | """""""""" |
| 2923 | |
| 2924 | The ``switch`` instruction specifies a table of values and destinations. |
| 2925 | When the '``switch``' instruction is executed, this table is searched |
| 2926 | for the given value. If the value is found, control flow is transferred |
| 2927 | to the corresponding destination; otherwise, control flow is transferred |
| 2928 | to the default destination. |
| 2929 | |
| 2930 | Implementation: |
| 2931 | """"""""""""""" |
| 2932 | |
| 2933 | Depending on properties of the target machine and the particular |
| 2934 | ``switch`` instruction, this instruction may be code generated in |
| 2935 | different ways. For example, it could be generated as a series of |
| 2936 | chained conditional branches or with a lookup table. |
| 2937 | |
| 2938 | Example: |
| 2939 | """""""" |
| 2940 | |
| 2941 | .. code-block:: llvm |
| 2942 | |
| 2943 | ; Emulate a conditional br instruction |
| 2944 | %Val = zext i1 %value to i32 |
| 2945 | switch i32 %Val, label %truedest [ i32 0, label %falsedest ] |
| 2946 | |
| 2947 | ; Emulate an unconditional br instruction |
| 2948 | switch i32 0, label %dest [ ] |
| 2949 | |
| 2950 | ; Implement a jump table: |
| 2951 | switch i32 %val, label %otherwise [ i32 0, label %onzero |
| 2952 | i32 1, label %onone |
| 2953 | i32 2, label %ontwo ] |
| 2954 | |
| 2955 | .. _i_indirectbr: |
| 2956 | |
| 2957 | '``indirectbr``' Instruction |
| 2958 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 2959 | |
| 2960 | Syntax: |
| 2961 | """"""" |
| 2962 | |
| 2963 | :: |
| 2964 | |
| 2965 | indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ] |
| 2966 | |
| 2967 | Overview: |
| 2968 | """"""""" |
| 2969 | |
| 2970 | The '``indirectbr``' instruction implements an indirect branch to a |
| 2971 | label within the current function, whose address is specified by |
| 2972 | "``address``". Address must be derived from a |
| 2973 | :ref:`blockaddress <blockaddress>` constant. |
| 2974 | |
| 2975 | Arguments: |
| 2976 | """""""""" |
| 2977 | |
| 2978 | The '``address``' argument is the address of the label to jump to. The |
| 2979 | rest of the arguments indicate the full set of possible destinations |
| 2980 | that the address may point to. Blocks are allowed to occur multiple |
| 2981 | times in the destination list, though this isn't particularly useful. |
| 2982 | |
| 2983 | This destination list is required so that dataflow analysis has an |
| 2984 | accurate understanding of the CFG. |
| 2985 | |
| 2986 | Semantics: |
| 2987 | """""""""" |
| 2988 | |
| 2989 | Control transfers to the block specified in the address argument. All |
| 2990 | possible destination blocks must be listed in the label list, otherwise |
| 2991 | this instruction has undefined behavior. This implies that jumps to |
| 2992 | labels defined in other functions have undefined behavior as well. |
| 2993 | |
| 2994 | Implementation: |
| 2995 | """"""""""""""" |
| 2996 | |
| 2997 | This is typically implemented with a jump through a register. |
| 2998 | |
| 2999 | Example: |
| 3000 | """""""" |
| 3001 | |
| 3002 | .. code-block:: llvm |
| 3003 | |
| 3004 | indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ] |
| 3005 | |
| 3006 | .. _i_invoke: |
| 3007 | |
| 3008 | '``invoke``' Instruction |
| 3009 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 3010 | |
| 3011 | Syntax: |
| 3012 | """"""" |
| 3013 | |
| 3014 | :: |
| 3015 | |
| 3016 | <result> = invoke [cconv] [ret attrs] <ptr to function ty> <function ptr val>(<function args>) [fn attrs] |
| 3017 | to label <normal label> unwind label <exception label> |
| 3018 | |
| 3019 | Overview: |
| 3020 | """"""""" |
| 3021 | |
| 3022 | The '``invoke``' instruction causes control to transfer to a specified |
| 3023 | function, with the possibility of control flow transfer to either the |
| 3024 | '``normal``' label or the '``exception``' label. If the callee function |
| 3025 | returns with the "``ret``" instruction, control flow will return to the |
| 3026 | "normal" label. If the callee (or any indirect callees) returns via the |
| 3027 | ":ref:`resume <i_resume>`" instruction or other exception handling |
| 3028 | mechanism, control is interrupted and continued at the dynamically |
| 3029 | nearest "exception" label. |
| 3030 | |
| 3031 | The '``exception``' label is a `landing |
| 3032 | pad <ExceptionHandling.html#overview>`_ for the exception. As such, |
| 3033 | '``exception``' label is required to have the |
| 3034 | ":ref:`landingpad <i_landingpad>`" instruction, which contains the |
| 3035 | information about the behavior of the program after unwinding happens, |
| 3036 | as its first non-PHI instruction. The restrictions on the |
| 3037 | "``landingpad``" instruction's tightly couples it to the "``invoke``" |
| 3038 | instruction, so that the important information contained within the |
| 3039 | "``landingpad``" instruction can't be lost through normal code motion. |
| 3040 | |
| 3041 | Arguments: |
| 3042 | """""""""" |
| 3043 | |
| 3044 | This instruction requires several arguments: |
| 3045 | |
| 3046 | #. The optional "cconv" marker indicates which :ref:`calling |
| 3047 | convention <callingconv>` the call should use. If none is |
| 3048 | specified, the call defaults to using C calling conventions. |
| 3049 | #. The optional :ref:`Parameter Attributes <paramattrs>` list for return |
| 3050 | values. Only '``zeroext``', '``signext``', and '``inreg``' attributes |
| 3051 | are valid here. |
| 3052 | #. '``ptr to function ty``': shall be the signature of the pointer to |
| 3053 | function value being invoked. In most cases, this is a direct |
| 3054 | function invocation, but indirect ``invoke``'s are just as possible, |
| 3055 | branching off an arbitrary pointer to function value. |
| 3056 | #. '``function ptr val``': An LLVM value containing a pointer to a |
| 3057 | function to be invoked. |
| 3058 | #. '``function args``': argument list whose types match the function |
| 3059 | signature argument types and parameter attributes. All arguments must |
| 3060 | be of :ref:`first class <t_firstclass>` type. If the function signature |
| 3061 | indicates the function accepts a variable number of arguments, the |
| 3062 | extra arguments can be specified. |
| 3063 | #. '``normal label``': the label reached when the called function |
| 3064 | executes a '``ret``' instruction. |
| 3065 | #. '``exception label``': the label reached when a callee returns via |
| 3066 | the :ref:`resume <i_resume>` instruction or other exception handling |
| 3067 | mechanism. |
| 3068 | #. The optional :ref:`function attributes <fnattrs>` list. Only |
| 3069 | '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``' |
| 3070 | attributes are valid here. |
| 3071 | |
| 3072 | Semantics: |
| 3073 | """""""""" |
| 3074 | |
| 3075 | This instruction is designed to operate as a standard '``call``' |
| 3076 | instruction in most regards. The primary difference is that it |
| 3077 | establishes an association with a label, which is used by the runtime |
| 3078 | library to unwind the stack. |
| 3079 | |
| 3080 | This instruction is used in languages with destructors to ensure that |
| 3081 | proper cleanup is performed in the case of either a ``longjmp`` or a |
| 3082 | thrown exception. Additionally, this is important for implementation of |
| 3083 | '``catch``' clauses in high-level languages that support them. |
| 3084 | |
| 3085 | For the purposes of the SSA form, the definition of the value returned |
| 3086 | by the '``invoke``' instruction is deemed to occur on the edge from the |
| 3087 | current block to the "normal" label. If the callee unwinds then no |
| 3088 | return value is available. |
| 3089 | |
| 3090 | Example: |
| 3091 | """""""" |
| 3092 | |
| 3093 | .. code-block:: llvm |
| 3094 | |
| 3095 | %retval = invoke i32 @Test(i32 15) to label %Continue |
| 3096 | unwind label %TestCleanup ; {i32}:retval set |
| 3097 | %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue |
| 3098 | unwind label %TestCleanup ; {i32}:retval set |
| 3099 | |
| 3100 | .. _i_resume: |
| 3101 | |
| 3102 | '``resume``' Instruction |
| 3103 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 3104 | |
| 3105 | Syntax: |
| 3106 | """"""" |
| 3107 | |
| 3108 | :: |
| 3109 | |
| 3110 | resume <type> <value> |
| 3111 | |
| 3112 | Overview: |
| 3113 | """"""""" |
| 3114 | |
| 3115 | The '``resume``' instruction is a terminator instruction that has no |
| 3116 | successors. |
| 3117 | |
| 3118 | Arguments: |
| 3119 | """""""""" |
| 3120 | |
| 3121 | The '``resume``' instruction requires one argument, which must have the |
| 3122 | same type as the result of any '``landingpad``' instruction in the same |
| 3123 | function. |
| 3124 | |
| 3125 | Semantics: |
| 3126 | """""""""" |
| 3127 | |
| 3128 | The '``resume``' instruction resumes propagation of an existing |
| 3129 | (in-flight) exception whose unwinding was interrupted with a |
| 3130 | :ref:`landingpad <i_landingpad>` instruction. |
| 3131 | |
| 3132 | Example: |
| 3133 | """""""" |
| 3134 | |
| 3135 | .. code-block:: llvm |
| 3136 | |
| 3137 | resume { i8*, i32 } %exn |
| 3138 | |
| 3139 | .. _i_unreachable: |
| 3140 | |
| 3141 | '``unreachable``' Instruction |
| 3142 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 3143 | |
| 3144 | Syntax: |
| 3145 | """"""" |
| 3146 | |
| 3147 | :: |
| 3148 | |
| 3149 | unreachable |
| 3150 | |
| 3151 | Overview: |
| 3152 | """"""""" |
| 3153 | |
| 3154 | The '``unreachable``' instruction has no defined semantics. This |
| 3155 | instruction is used to inform the optimizer that a particular portion of |
| 3156 | the code is not reachable. This can be used to indicate that the code |
| 3157 | after a no-return function cannot be reached, and other facts. |
| 3158 | |
| 3159 | Semantics: |
| 3160 | """""""""" |
| 3161 | |
| 3162 | The '``unreachable``' instruction has no defined semantics. |
| 3163 | |
| 3164 | .. _binaryops: |
| 3165 | |
| 3166 | Binary Operations |
| 3167 | ----------------- |
| 3168 | |
| 3169 | Binary operators are used to do most of the computation in a program. |
| 3170 | They require two operands of the same type, execute an operation on |
| 3171 | them, and produce a single value. The operands might represent multiple |
| 3172 | data, as is the case with the :ref:`vector <t_vector>` data type. The |
| 3173 | result value has the same type as its operands. |
| 3174 | |
| 3175 | There are several different binary operators: |
| 3176 | |
| 3177 | .. _i_add: |
| 3178 | |
| 3179 | '``add``' Instruction |
| 3180 | ^^^^^^^^^^^^^^^^^^^^^ |
| 3181 | |
| 3182 | Syntax: |
| 3183 | """"""" |
| 3184 | |
| 3185 | :: |
| 3186 | |
| 3187 | <result> = add <ty> <op1>, <op2> ; yields {ty}:result |
| 3188 | <result> = add nuw <ty> <op1>, <op2> ; yields {ty}:result |
| 3189 | <result> = add nsw <ty> <op1>, <op2> ; yields {ty}:result |
| 3190 | <result> = add nuw nsw <ty> <op1>, <op2> ; yields {ty}:result |
| 3191 | |
| 3192 | Overview: |
| 3193 | """"""""" |
| 3194 | |
| 3195 | The '``add``' instruction returns the sum of its two operands. |
| 3196 | |
| 3197 | Arguments: |
| 3198 | """""""""" |
| 3199 | |
| 3200 | The two arguments to the '``add``' instruction must be |
| 3201 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3202 | arguments must have identical types. |
| 3203 | |
| 3204 | Semantics: |
| 3205 | """""""""" |
| 3206 | |
| 3207 | The value produced is the integer sum of the two operands. |
| 3208 | |
| 3209 | If the sum has unsigned overflow, the result returned is the |
| 3210 | mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of |
| 3211 | the result. |
| 3212 | |
| 3213 | Because LLVM integers use a two's complement representation, this |
| 3214 | instruction is appropriate for both signed and unsigned integers. |
| 3215 | |
| 3216 | ``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", |
| 3217 | respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the |
| 3218 | result value of the ``add`` is a :ref:`poison value <poisonvalues>` if |
| 3219 | unsigned and/or signed overflow, respectively, occurs. |
| 3220 | |
| 3221 | Example: |
| 3222 | """""""" |
| 3223 | |
| 3224 | .. code-block:: llvm |
| 3225 | |
| 3226 | <result> = add i32 4, %var ; yields {i32}:result = 4 + %var |
| 3227 | |
| 3228 | .. _i_fadd: |
| 3229 | |
| 3230 | '``fadd``' Instruction |
| 3231 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3232 | |
| 3233 | Syntax: |
| 3234 | """"""" |
| 3235 | |
| 3236 | :: |
| 3237 | |
| 3238 | <result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result |
| 3239 | |
| 3240 | Overview: |
| 3241 | """"""""" |
| 3242 | |
| 3243 | The '``fadd``' instruction returns the sum of its two operands. |
| 3244 | |
| 3245 | Arguments: |
| 3246 | """""""""" |
| 3247 | |
| 3248 | The two arguments to the '``fadd``' instruction must be :ref:`floating |
| 3249 | point <t_floating>` or :ref:`vector <t_vector>` of floating point values. |
| 3250 | Both arguments must have identical types. |
| 3251 | |
| 3252 | Semantics: |
| 3253 | """""""""" |
| 3254 | |
| 3255 | The value produced is the floating point sum of the two operands. This |
| 3256 | instruction can also take any number of :ref:`fast-math flags <fastmath>`, |
| 3257 | which are optimization hints to enable otherwise unsafe floating point |
| 3258 | optimizations: |
| 3259 | |
| 3260 | Example: |
| 3261 | """""""" |
| 3262 | |
| 3263 | .. code-block:: llvm |
| 3264 | |
| 3265 | <result> = fadd float 4.0, %var ; yields {float}:result = 4.0 + %var |
| 3266 | |
| 3267 | '``sub``' Instruction |
| 3268 | ^^^^^^^^^^^^^^^^^^^^^ |
| 3269 | |
| 3270 | Syntax: |
| 3271 | """"""" |
| 3272 | |
| 3273 | :: |
| 3274 | |
| 3275 | <result> = sub <ty> <op1>, <op2> ; yields {ty}:result |
| 3276 | <result> = sub nuw <ty> <op1>, <op2> ; yields {ty}:result |
| 3277 | <result> = sub nsw <ty> <op1>, <op2> ; yields {ty}:result |
| 3278 | <result> = sub nuw nsw <ty> <op1>, <op2> ; yields {ty}:result |
| 3279 | |
| 3280 | Overview: |
| 3281 | """"""""" |
| 3282 | |
| 3283 | The '``sub``' instruction returns the difference of its two operands. |
| 3284 | |
| 3285 | Note that the '``sub``' instruction is used to represent the '``neg``' |
| 3286 | instruction present in most other intermediate representations. |
| 3287 | |
| 3288 | Arguments: |
| 3289 | """""""""" |
| 3290 | |
| 3291 | The two arguments to the '``sub``' instruction must be |
| 3292 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3293 | arguments must have identical types. |
| 3294 | |
| 3295 | Semantics: |
| 3296 | """""""""" |
| 3297 | |
| 3298 | The value produced is the integer difference of the two operands. |
| 3299 | |
| 3300 | If the difference has unsigned overflow, the result returned is the |
| 3301 | mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of |
| 3302 | the result. |
| 3303 | |
| 3304 | Because LLVM integers use a two's complement representation, this |
| 3305 | instruction is appropriate for both signed and unsigned integers. |
| 3306 | |
| 3307 | ``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", |
| 3308 | respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the |
| 3309 | result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if |
| 3310 | unsigned and/or signed overflow, respectively, occurs. |
| 3311 | |
| 3312 | Example: |
| 3313 | """""""" |
| 3314 | |
| 3315 | .. code-block:: llvm |
| 3316 | |
| 3317 | <result> = sub i32 4, %var ; yields {i32}:result = 4 - %var |
| 3318 | <result> = sub i32 0, %val ; yields {i32}:result = -%var |
| 3319 | |
| 3320 | .. _i_fsub: |
| 3321 | |
| 3322 | '``fsub``' Instruction |
| 3323 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3324 | |
| 3325 | Syntax: |
| 3326 | """"""" |
| 3327 | |
| 3328 | :: |
| 3329 | |
| 3330 | <result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result |
| 3331 | |
| 3332 | Overview: |
| 3333 | """"""""" |
| 3334 | |
| 3335 | The '``fsub``' instruction returns the difference of its two operands. |
| 3336 | |
| 3337 | Note that the '``fsub``' instruction is used to represent the '``fneg``' |
| 3338 | instruction present in most other intermediate representations. |
| 3339 | |
| 3340 | Arguments: |
| 3341 | """""""""" |
| 3342 | |
| 3343 | The two arguments to the '``fsub``' instruction must be :ref:`floating |
| 3344 | point <t_floating>` or :ref:`vector <t_vector>` of floating point values. |
| 3345 | Both arguments must have identical types. |
| 3346 | |
| 3347 | Semantics: |
| 3348 | """""""""" |
| 3349 | |
| 3350 | The value produced is the floating point difference of the two operands. |
| 3351 | This instruction can also take any number of :ref:`fast-math |
| 3352 | flags <fastmath>`, which are optimization hints to enable otherwise |
| 3353 | unsafe floating point optimizations: |
| 3354 | |
| 3355 | Example: |
| 3356 | """""""" |
| 3357 | |
| 3358 | .. code-block:: llvm |
| 3359 | |
| 3360 | <result> = fsub float 4.0, %var ; yields {float}:result = 4.0 - %var |
| 3361 | <result> = fsub float -0.0, %val ; yields {float}:result = -%var |
| 3362 | |
| 3363 | '``mul``' Instruction |
| 3364 | ^^^^^^^^^^^^^^^^^^^^^ |
| 3365 | |
| 3366 | Syntax: |
| 3367 | """"""" |
| 3368 | |
| 3369 | :: |
| 3370 | |
| 3371 | <result> = mul <ty> <op1>, <op2> ; yields {ty}:result |
| 3372 | <result> = mul nuw <ty> <op1>, <op2> ; yields {ty}:result |
| 3373 | <result> = mul nsw <ty> <op1>, <op2> ; yields {ty}:result |
| 3374 | <result> = mul nuw nsw <ty> <op1>, <op2> ; yields {ty}:result |
| 3375 | |
| 3376 | Overview: |
| 3377 | """"""""" |
| 3378 | |
| 3379 | The '``mul``' instruction returns the product of its two operands. |
| 3380 | |
| 3381 | Arguments: |
| 3382 | """""""""" |
| 3383 | |
| 3384 | The two arguments to the '``mul``' instruction must be |
| 3385 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3386 | arguments must have identical types. |
| 3387 | |
| 3388 | Semantics: |
| 3389 | """""""""" |
| 3390 | |
| 3391 | The value produced is the integer product of the two operands. |
| 3392 | |
| 3393 | If the result of the multiplication has unsigned overflow, the result |
| 3394 | returned is the mathematical result modulo 2\ :sup:`n`\ , where n is the |
| 3395 | bit width of the result. |
| 3396 | |
| 3397 | Because LLVM integers use a two's complement representation, and the |
| 3398 | result is the same width as the operands, this instruction returns the |
| 3399 | correct result for both signed and unsigned integers. If a full product |
| 3400 | (e.g. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be |
| 3401 | sign-extended or zero-extended as appropriate to the width of the full |
| 3402 | product. |
| 3403 | |
| 3404 | ``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap", |
| 3405 | respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the |
| 3406 | result value of the ``mul`` is a :ref:`poison value <poisonvalues>` if |
| 3407 | unsigned and/or signed overflow, respectively, occurs. |
| 3408 | |
| 3409 | Example: |
| 3410 | """""""" |
| 3411 | |
| 3412 | .. code-block:: llvm |
| 3413 | |
| 3414 | <result> = mul i32 4, %var ; yields {i32}:result = 4 * %var |
| 3415 | |
| 3416 | .. _i_fmul: |
| 3417 | |
| 3418 | '``fmul``' Instruction |
| 3419 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3420 | |
| 3421 | Syntax: |
| 3422 | """"""" |
| 3423 | |
| 3424 | :: |
| 3425 | |
| 3426 | <result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result |
| 3427 | |
| 3428 | Overview: |
| 3429 | """"""""" |
| 3430 | |
| 3431 | The '``fmul``' instruction returns the product of its two operands. |
| 3432 | |
| 3433 | Arguments: |
| 3434 | """""""""" |
| 3435 | |
| 3436 | The two arguments to the '``fmul``' instruction must be :ref:`floating |
| 3437 | point <t_floating>` or :ref:`vector <t_vector>` of floating point values. |
| 3438 | Both arguments must have identical types. |
| 3439 | |
| 3440 | Semantics: |
| 3441 | """""""""" |
| 3442 | |
| 3443 | The value produced is the floating point product of the two operands. |
| 3444 | This instruction can also take any number of :ref:`fast-math |
| 3445 | flags <fastmath>`, which are optimization hints to enable otherwise |
| 3446 | unsafe floating point optimizations: |
| 3447 | |
| 3448 | Example: |
| 3449 | """""""" |
| 3450 | |
| 3451 | .. code-block:: llvm |
| 3452 | |
| 3453 | <result> = fmul float 4.0, %var ; yields {float}:result = 4.0 * %var |
| 3454 | |
| 3455 | '``udiv``' Instruction |
| 3456 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3457 | |
| 3458 | Syntax: |
| 3459 | """"""" |
| 3460 | |
| 3461 | :: |
| 3462 | |
| 3463 | <result> = udiv <ty> <op1>, <op2> ; yields {ty}:result |
| 3464 | <result> = udiv exact <ty> <op1>, <op2> ; yields {ty}:result |
| 3465 | |
| 3466 | Overview: |
| 3467 | """"""""" |
| 3468 | |
| 3469 | The '``udiv``' instruction returns the quotient of its two operands. |
| 3470 | |
| 3471 | Arguments: |
| 3472 | """""""""" |
| 3473 | |
| 3474 | The two arguments to the '``udiv``' instruction must be |
| 3475 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3476 | arguments must have identical types. |
| 3477 | |
| 3478 | Semantics: |
| 3479 | """""""""" |
| 3480 | |
| 3481 | The value produced is the unsigned integer quotient of the two operands. |
| 3482 | |
| 3483 | Note that unsigned integer division and signed integer division are |
| 3484 | distinct operations; for signed integer division, use '``sdiv``'. |
| 3485 | |
| 3486 | Division by zero leads to undefined behavior. |
| 3487 | |
| 3488 | If the ``exact`` keyword is present, the result value of the ``udiv`` is |
| 3489 | a :ref:`poison value <poisonvalues>` if %op1 is not a multiple of %op2 (as |
| 3490 | such, "((a udiv exact b) mul b) == a"). |
| 3491 | |
| 3492 | Example: |
| 3493 | """""""" |
| 3494 | |
| 3495 | .. code-block:: llvm |
| 3496 | |
| 3497 | <result> = udiv i32 4, %var ; yields {i32}:result = 4 / %var |
| 3498 | |
| 3499 | '``sdiv``' Instruction |
| 3500 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3501 | |
| 3502 | Syntax: |
| 3503 | """"""" |
| 3504 | |
| 3505 | :: |
| 3506 | |
| 3507 | <result> = sdiv <ty> <op1>, <op2> ; yields {ty}:result |
| 3508 | <result> = sdiv exact <ty> <op1>, <op2> ; yields {ty}:result |
| 3509 | |
| 3510 | Overview: |
| 3511 | """"""""" |
| 3512 | |
| 3513 | The '``sdiv``' instruction returns the quotient of its two operands. |
| 3514 | |
| 3515 | Arguments: |
| 3516 | """""""""" |
| 3517 | |
| 3518 | The two arguments to the '``sdiv``' instruction must be |
| 3519 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3520 | arguments must have identical types. |
| 3521 | |
| 3522 | Semantics: |
| 3523 | """""""""" |
| 3524 | |
| 3525 | The value produced is the signed integer quotient of the two operands |
| 3526 | rounded towards zero. |
| 3527 | |
| 3528 | Note that signed integer division and unsigned integer division are |
| 3529 | distinct operations; for unsigned integer division, use '``udiv``'. |
| 3530 | |
| 3531 | Division by zero leads to undefined behavior. Overflow also leads to |
| 3532 | undefined behavior; this is a rare case, but can occur, for example, by |
| 3533 | doing a 32-bit division of -2147483648 by -1. |
| 3534 | |
| 3535 | If the ``exact`` keyword is present, the result value of the ``sdiv`` is |
| 3536 | a :ref:`poison value <poisonvalues>` if the result would be rounded. |
| 3537 | |
| 3538 | Example: |
| 3539 | """""""" |
| 3540 | |
| 3541 | .. code-block:: llvm |
| 3542 | |
| 3543 | <result> = sdiv i32 4, %var ; yields {i32}:result = 4 / %var |
| 3544 | |
| 3545 | .. _i_fdiv: |
| 3546 | |
| 3547 | '``fdiv``' Instruction |
| 3548 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3549 | |
| 3550 | Syntax: |
| 3551 | """"""" |
| 3552 | |
| 3553 | :: |
| 3554 | |
| 3555 | <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result |
| 3556 | |
| 3557 | Overview: |
| 3558 | """"""""" |
| 3559 | |
| 3560 | The '``fdiv``' instruction returns the quotient of its two operands. |
| 3561 | |
| 3562 | Arguments: |
| 3563 | """""""""" |
| 3564 | |
| 3565 | The two arguments to the '``fdiv``' instruction must be :ref:`floating |
| 3566 | point <t_floating>` or :ref:`vector <t_vector>` of floating point values. |
| 3567 | Both arguments must have identical types. |
| 3568 | |
| 3569 | Semantics: |
| 3570 | """""""""" |
| 3571 | |
| 3572 | The value produced is the floating point quotient of the two operands. |
| 3573 | This instruction can also take any number of :ref:`fast-math |
| 3574 | flags <fastmath>`, which are optimization hints to enable otherwise |
| 3575 | unsafe floating point optimizations: |
| 3576 | |
| 3577 | Example: |
| 3578 | """""""" |
| 3579 | |
| 3580 | .. code-block:: llvm |
| 3581 | |
| 3582 | <result> = fdiv float 4.0, %var ; yields {float}:result = 4.0 / %var |
| 3583 | |
| 3584 | '``urem``' Instruction |
| 3585 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3586 | |
| 3587 | Syntax: |
| 3588 | """"""" |
| 3589 | |
| 3590 | :: |
| 3591 | |
| 3592 | <result> = urem <ty> <op1>, <op2> ; yields {ty}:result |
| 3593 | |
| 3594 | Overview: |
| 3595 | """"""""" |
| 3596 | |
| 3597 | The '``urem``' instruction returns the remainder from the unsigned |
| 3598 | division of its two arguments. |
| 3599 | |
| 3600 | Arguments: |
| 3601 | """""""""" |
| 3602 | |
| 3603 | The two arguments to the '``urem``' instruction must be |
| 3604 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3605 | arguments must have identical types. |
| 3606 | |
| 3607 | Semantics: |
| 3608 | """""""""" |
| 3609 | |
| 3610 | This instruction returns the unsigned integer *remainder* of a division. |
| 3611 | This instruction always performs an unsigned division to get the |
| 3612 | remainder. |
| 3613 | |
| 3614 | Note that unsigned integer remainder and signed integer remainder are |
| 3615 | distinct operations; for signed integer remainder, use '``srem``'. |
| 3616 | |
| 3617 | Taking the remainder of a division by zero leads to undefined behavior. |
| 3618 | |
| 3619 | Example: |
| 3620 | """""""" |
| 3621 | |
| 3622 | .. code-block:: llvm |
| 3623 | |
| 3624 | <result> = urem i32 4, %var ; yields {i32}:result = 4 % %var |
| 3625 | |
| 3626 | '``srem``' Instruction |
| 3627 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3628 | |
| 3629 | Syntax: |
| 3630 | """"""" |
| 3631 | |
| 3632 | :: |
| 3633 | |
| 3634 | <result> = srem <ty> <op1>, <op2> ; yields {ty}:result |
| 3635 | |
| 3636 | Overview: |
| 3637 | """"""""" |
| 3638 | |
| 3639 | The '``srem``' instruction returns the remainder from the signed |
| 3640 | division of its two operands. This instruction can also take |
| 3641 | :ref:`vector <t_vector>` versions of the values in which case the elements |
| 3642 | must be integers. |
| 3643 | |
| 3644 | Arguments: |
| 3645 | """""""""" |
| 3646 | |
| 3647 | The two arguments to the '``srem``' instruction must be |
| 3648 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3649 | arguments must have identical types. |
| 3650 | |
| 3651 | Semantics: |
| 3652 | """""""""" |
| 3653 | |
| 3654 | This instruction returns the *remainder* of a division (where the result |
| 3655 | is either zero or has the same sign as the dividend, ``op1``), not the |
| 3656 | *modulo* operator (where the result is either zero or has the same sign |
| 3657 | as the divisor, ``op2``) of a value. For more information about the |
| 3658 | difference, see `The Math |
| 3659 | Forum <http://mathforum.org/dr.math/problems/anne.4.28.99.html>`_. For a |
| 3660 | table of how this is implemented in various languages, please see |
| 3661 | `Wikipedia: modulo |
| 3662 | operation <http://en.wikipedia.org/wiki/Modulo_operation>`_. |
| 3663 | |
| 3664 | Note that signed integer remainder and unsigned integer remainder are |
| 3665 | distinct operations; for unsigned integer remainder, use '``urem``'. |
| 3666 | |
| 3667 | Taking the remainder of a division by zero leads to undefined behavior. |
| 3668 | Overflow also leads to undefined behavior; this is a rare case, but can |
| 3669 | occur, for example, by taking the remainder of a 32-bit division of |
| 3670 | -2147483648 by -1. (The remainder doesn't actually overflow, but this |
| 3671 | rule lets srem be implemented using instructions that return both the |
| 3672 | result of the division and the remainder.) |
| 3673 | |
| 3674 | Example: |
| 3675 | """""""" |
| 3676 | |
| 3677 | .. code-block:: llvm |
| 3678 | |
| 3679 | <result> = srem i32 4, %var ; yields {i32}:result = 4 % %var |
| 3680 | |
| 3681 | .. _i_frem: |
| 3682 | |
| 3683 | '``frem``' Instruction |
| 3684 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3685 | |
| 3686 | Syntax: |
| 3687 | """"""" |
| 3688 | |
| 3689 | :: |
| 3690 | |
| 3691 | <result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields {ty}:result |
| 3692 | |
| 3693 | Overview: |
| 3694 | """"""""" |
| 3695 | |
| 3696 | The '``frem``' instruction returns the remainder from the division of |
| 3697 | its two operands. |
| 3698 | |
| 3699 | Arguments: |
| 3700 | """""""""" |
| 3701 | |
| 3702 | The two arguments to the '``frem``' instruction must be :ref:`floating |
| 3703 | point <t_floating>` or :ref:`vector <t_vector>` of floating point values. |
| 3704 | Both arguments must have identical types. |
| 3705 | |
| 3706 | Semantics: |
| 3707 | """""""""" |
| 3708 | |
| 3709 | This instruction returns the *remainder* of a division. The remainder |
| 3710 | has the same sign as the dividend. This instruction can also take any |
| 3711 | number of :ref:`fast-math flags <fastmath>`, which are optimization hints |
| 3712 | to enable otherwise unsafe floating point optimizations: |
| 3713 | |
| 3714 | Example: |
| 3715 | """""""" |
| 3716 | |
| 3717 | .. code-block:: llvm |
| 3718 | |
| 3719 | <result> = frem float 4.0, %var ; yields {float}:result = 4.0 % %var |
| 3720 | |
| 3721 | .. _bitwiseops: |
| 3722 | |
| 3723 | Bitwise Binary Operations |
| 3724 | ------------------------- |
| 3725 | |
| 3726 | Bitwise binary operators are used to do various forms of bit-twiddling |
| 3727 | in a program. They are generally very efficient instructions and can |
| 3728 | commonly be strength reduced from other instructions. They require two |
| 3729 | operands of the same type, execute an operation on them, and produce a |
| 3730 | single value. The resulting value is the same type as its operands. |
| 3731 | |
| 3732 | '``shl``' Instruction |
| 3733 | ^^^^^^^^^^^^^^^^^^^^^ |
| 3734 | |
| 3735 | Syntax: |
| 3736 | """"""" |
| 3737 | |
| 3738 | :: |
| 3739 | |
| 3740 | <result> = shl <ty> <op1>, <op2> ; yields {ty}:result |
| 3741 | <result> = shl nuw <ty> <op1>, <op2> ; yields {ty}:result |
| 3742 | <result> = shl nsw <ty> <op1>, <op2> ; yields {ty}:result |
| 3743 | <result> = shl nuw nsw <ty> <op1>, <op2> ; yields {ty}:result |
| 3744 | |
| 3745 | Overview: |
| 3746 | """"""""" |
| 3747 | |
| 3748 | The '``shl``' instruction returns the first operand shifted to the left |
| 3749 | a specified number of bits. |
| 3750 | |
| 3751 | Arguments: |
| 3752 | """""""""" |
| 3753 | |
| 3754 | Both arguments to the '``shl``' instruction must be the same |
| 3755 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. |
| 3756 | '``op2``' is treated as an unsigned value. |
| 3757 | |
| 3758 | Semantics: |
| 3759 | """""""""" |
| 3760 | |
| 3761 | The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`, |
| 3762 | where ``n`` is the width of the result. If ``op2`` is (statically or |
| 3763 | dynamically) negative or equal to or larger than the number of bits in |
| 3764 | ``op1``, the result is undefined. If the arguments are vectors, each |
| 3765 | vector element of ``op1`` is shifted by the corresponding shift amount |
| 3766 | in ``op2``. |
| 3767 | |
| 3768 | If the ``nuw`` keyword is present, then the shift produces a :ref:`poison |
| 3769 | value <poisonvalues>` if it shifts out any non-zero bits. If the |
| 3770 | ``nsw`` keyword is present, then the shift produces a :ref:`poison |
| 3771 | value <poisonvalues>` if it shifts out any bits that disagree with the |
| 3772 | resultant sign bit. As such, NUW/NSW have the same semantics as they |
| 3773 | would if the shift were expressed as a mul instruction with the same |
| 3774 | nsw/nuw bits in (mul %op1, (shl 1, %op2)). |
| 3775 | |
| 3776 | Example: |
| 3777 | """""""" |
| 3778 | |
| 3779 | .. code-block:: llvm |
| 3780 | |
| 3781 | <result> = shl i32 4, %var ; yields {i32}: 4 << %var |
| 3782 | <result> = shl i32 4, 2 ; yields {i32}: 16 |
| 3783 | <result> = shl i32 1, 10 ; yields {i32}: 1024 |
| 3784 | <result> = shl i32 1, 32 ; undefined |
| 3785 | <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 2, i32 4> |
| 3786 | |
| 3787 | '``lshr``' Instruction |
| 3788 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3789 | |
| 3790 | Syntax: |
| 3791 | """"""" |
| 3792 | |
| 3793 | :: |
| 3794 | |
| 3795 | <result> = lshr <ty> <op1>, <op2> ; yields {ty}:result |
| 3796 | <result> = lshr exact <ty> <op1>, <op2> ; yields {ty}:result |
| 3797 | |
| 3798 | Overview: |
| 3799 | """"""""" |
| 3800 | |
| 3801 | The '``lshr``' instruction (logical shift right) returns the first |
| 3802 | operand shifted to the right a specified number of bits with zero fill. |
| 3803 | |
| 3804 | Arguments: |
| 3805 | """""""""" |
| 3806 | |
| 3807 | Both arguments to the '``lshr``' instruction must be the same |
| 3808 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. |
| 3809 | '``op2``' is treated as an unsigned value. |
| 3810 | |
| 3811 | Semantics: |
| 3812 | """""""""" |
| 3813 | |
| 3814 | This instruction always performs a logical shift right operation. The |
| 3815 | most significant bits of the result will be filled with zero bits after |
| 3816 | the shift. If ``op2`` is (statically or dynamically) equal to or larger |
| 3817 | than the number of bits in ``op1``, the result is undefined. If the |
| 3818 | arguments are vectors, each vector element of ``op1`` is shifted by the |
| 3819 | corresponding shift amount in ``op2``. |
| 3820 | |
| 3821 | If the ``exact`` keyword is present, the result value of the ``lshr`` is |
| 3822 | a :ref:`poison value <poisonvalues>` if any of the bits shifted out are |
| 3823 | non-zero. |
| 3824 | |
| 3825 | Example: |
| 3826 | """""""" |
| 3827 | |
| 3828 | .. code-block:: llvm |
| 3829 | |
| 3830 | <result> = lshr i32 4, 1 ; yields {i32}:result = 2 |
| 3831 | <result> = lshr i32 4, 2 ; yields {i32}:result = 1 |
| 3832 | <result> = lshr i8 4, 3 ; yields {i8}:result = 0 |
| 3833 | <result> = lshr i8 -2, 1 ; yields {i8}:result = 0x7FFFFFFF |
| 3834 | <result> = lshr i32 1, 32 ; undefined |
| 3835 | <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1> |
| 3836 | |
| 3837 | '``ashr``' Instruction |
| 3838 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 3839 | |
| 3840 | Syntax: |
| 3841 | """"""" |
| 3842 | |
| 3843 | :: |
| 3844 | |
| 3845 | <result> = ashr <ty> <op1>, <op2> ; yields {ty}:result |
| 3846 | <result> = ashr exact <ty> <op1>, <op2> ; yields {ty}:result |
| 3847 | |
| 3848 | Overview: |
| 3849 | """"""""" |
| 3850 | |
| 3851 | The '``ashr``' instruction (arithmetic shift right) returns the first |
| 3852 | operand shifted to the right a specified number of bits with sign |
| 3853 | extension. |
| 3854 | |
| 3855 | Arguments: |
| 3856 | """""""""" |
| 3857 | |
| 3858 | Both arguments to the '``ashr``' instruction must be the same |
| 3859 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type. |
| 3860 | '``op2``' is treated as an unsigned value. |
| 3861 | |
| 3862 | Semantics: |
| 3863 | """""""""" |
| 3864 | |
| 3865 | This instruction always performs an arithmetic shift right operation, |
| 3866 | The most significant bits of the result will be filled with the sign bit |
| 3867 | of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger |
| 3868 | than the number of bits in ``op1``, the result is undefined. If the |
| 3869 | arguments are vectors, each vector element of ``op1`` is shifted by the |
| 3870 | corresponding shift amount in ``op2``. |
| 3871 | |
| 3872 | If the ``exact`` keyword is present, the result value of the ``ashr`` is |
| 3873 | a :ref:`poison value <poisonvalues>` if any of the bits shifted out are |
| 3874 | non-zero. |
| 3875 | |
| 3876 | Example: |
| 3877 | """""""" |
| 3878 | |
| 3879 | .. code-block:: llvm |
| 3880 | |
| 3881 | <result> = ashr i32 4, 1 ; yields {i32}:result = 2 |
| 3882 | <result> = ashr i32 4, 2 ; yields {i32}:result = 1 |
| 3883 | <result> = ashr i8 4, 3 ; yields {i8}:result = 0 |
| 3884 | <result> = ashr i8 -2, 1 ; yields {i8}:result = -1 |
| 3885 | <result> = ashr i32 1, 32 ; undefined |
| 3886 | <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> ; yields: result=<2 x i32> < i32 -1, i32 0> |
| 3887 | |
| 3888 | '``and``' Instruction |
| 3889 | ^^^^^^^^^^^^^^^^^^^^^ |
| 3890 | |
| 3891 | Syntax: |
| 3892 | """"""" |
| 3893 | |
| 3894 | :: |
| 3895 | |
| 3896 | <result> = and <ty> <op1>, <op2> ; yields {ty}:result |
| 3897 | |
| 3898 | Overview: |
| 3899 | """"""""" |
| 3900 | |
| 3901 | The '``and``' instruction returns the bitwise logical and of its two |
| 3902 | operands. |
| 3903 | |
| 3904 | Arguments: |
| 3905 | """""""""" |
| 3906 | |
| 3907 | The two arguments to the '``and``' instruction must be |
| 3908 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3909 | arguments must have identical types. |
| 3910 | |
| 3911 | Semantics: |
| 3912 | """""""""" |
| 3913 | |
| 3914 | The truth table used for the '``and``' instruction is: |
| 3915 | |
| 3916 | +-----+-----+-----+ |
| 3917 | | In0 | In1 | Out | |
| 3918 | +-----+-----+-----+ |
| 3919 | | 0 | 0 | 0 | |
| 3920 | +-----+-----+-----+ |
| 3921 | | 0 | 1 | 0 | |
| 3922 | +-----+-----+-----+ |
| 3923 | | 1 | 0 | 0 | |
| 3924 | +-----+-----+-----+ |
| 3925 | | 1 | 1 | 1 | |
| 3926 | +-----+-----+-----+ |
| 3927 | |
| 3928 | Example: |
| 3929 | """""""" |
| 3930 | |
| 3931 | .. code-block:: llvm |
| 3932 | |
| 3933 | <result> = and i32 4, %var ; yields {i32}:result = 4 & %var |
| 3934 | <result> = and i32 15, 40 ; yields {i32}:result = 8 |
| 3935 | <result> = and i32 4, 8 ; yields {i32}:result = 0 |
| 3936 | |
| 3937 | '``or``' Instruction |
| 3938 | ^^^^^^^^^^^^^^^^^^^^ |
| 3939 | |
| 3940 | Syntax: |
| 3941 | """"""" |
| 3942 | |
| 3943 | :: |
| 3944 | |
| 3945 | <result> = or <ty> <op1>, <op2> ; yields {ty}:result |
| 3946 | |
| 3947 | Overview: |
| 3948 | """"""""" |
| 3949 | |
| 3950 | The '``or``' instruction returns the bitwise logical inclusive or of its |
| 3951 | two operands. |
| 3952 | |
| 3953 | Arguments: |
| 3954 | """""""""" |
| 3955 | |
| 3956 | The two arguments to the '``or``' instruction must be |
| 3957 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 3958 | arguments must have identical types. |
| 3959 | |
| 3960 | Semantics: |
| 3961 | """""""""" |
| 3962 | |
| 3963 | The truth table used for the '``or``' instruction is: |
| 3964 | |
| 3965 | +-----+-----+-----+ |
| 3966 | | In0 | In1 | Out | |
| 3967 | +-----+-----+-----+ |
| 3968 | | 0 | 0 | 0 | |
| 3969 | +-----+-----+-----+ |
| 3970 | | 0 | 1 | 1 | |
| 3971 | +-----+-----+-----+ |
| 3972 | | 1 | 0 | 1 | |
| 3973 | +-----+-----+-----+ |
| 3974 | | 1 | 1 | 1 | |
| 3975 | +-----+-----+-----+ |
| 3976 | |
| 3977 | Example: |
| 3978 | """""""" |
| 3979 | |
| 3980 | :: |
| 3981 | |
| 3982 | <result> = or i32 4, %var ; yields {i32}:result = 4 | %var |
| 3983 | <result> = or i32 15, 40 ; yields {i32}:result = 47 |
| 3984 | <result> = or i32 4, 8 ; yields {i32}:result = 12 |
| 3985 | |
| 3986 | '``xor``' Instruction |
| 3987 | ^^^^^^^^^^^^^^^^^^^^^ |
| 3988 | |
| 3989 | Syntax: |
| 3990 | """"""" |
| 3991 | |
| 3992 | :: |
| 3993 | |
| 3994 | <result> = xor <ty> <op1>, <op2> ; yields {ty}:result |
| 3995 | |
| 3996 | Overview: |
| 3997 | """"""""" |
| 3998 | |
| 3999 | The '``xor``' instruction returns the bitwise logical exclusive or of |
| 4000 | its two operands. The ``xor`` is used to implement the "one's |
| 4001 | complement" operation, which is the "~" operator in C. |
| 4002 | |
| 4003 | Arguments: |
| 4004 | """""""""" |
| 4005 | |
| 4006 | The two arguments to the '``xor``' instruction must be |
| 4007 | :ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both |
| 4008 | arguments must have identical types. |
| 4009 | |
| 4010 | Semantics: |
| 4011 | """""""""" |
| 4012 | |
| 4013 | The truth table used for the '``xor``' instruction is: |
| 4014 | |
| 4015 | +-----+-----+-----+ |
| 4016 | | In0 | In1 | Out | |
| 4017 | +-----+-----+-----+ |
| 4018 | | 0 | 0 | 0 | |
| 4019 | +-----+-----+-----+ |
| 4020 | | 0 | 1 | 1 | |
| 4021 | +-----+-----+-----+ |
| 4022 | | 1 | 0 | 1 | |
| 4023 | +-----+-----+-----+ |
| 4024 | | 1 | 1 | 0 | |
| 4025 | +-----+-----+-----+ |
| 4026 | |
| 4027 | Example: |
| 4028 | """""""" |
| 4029 | |
| 4030 | .. code-block:: llvm |
| 4031 | |
| 4032 | <result> = xor i32 4, %var ; yields {i32}:result = 4 ^ %var |
| 4033 | <result> = xor i32 15, 40 ; yields {i32}:result = 39 |
| 4034 | <result> = xor i32 4, 8 ; yields {i32}:result = 12 |
| 4035 | <result> = xor i32 %V, -1 ; yields {i32}:result = ~%V |
| 4036 | |
| 4037 | Vector Operations |
| 4038 | ----------------- |
| 4039 | |
| 4040 | LLVM supports several instructions to represent vector operations in a |
| 4041 | target-independent manner. These instructions cover the element-access |
| 4042 | and vector-specific operations needed to process vectors effectively. |
| 4043 | While LLVM does directly support these vector operations, many |
| 4044 | sophisticated algorithms will want to use target-specific intrinsics to |
| 4045 | take full advantage of a specific target. |
| 4046 | |
| 4047 | .. _i_extractelement: |
| 4048 | |
| 4049 | '``extractelement``' Instruction |
| 4050 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4051 | |
| 4052 | Syntax: |
| 4053 | """"""" |
| 4054 | |
| 4055 | :: |
| 4056 | |
| 4057 | <result> = extractelement <n x <ty>> <val>, i32 <idx> ; yields <ty> |
| 4058 | |
| 4059 | Overview: |
| 4060 | """"""""" |
| 4061 | |
| 4062 | The '``extractelement``' instruction extracts a single scalar element |
| 4063 | from a vector at a specified index. |
| 4064 | |
| 4065 | Arguments: |
| 4066 | """""""""" |
| 4067 | |
| 4068 | The first operand of an '``extractelement``' instruction is a value of |
| 4069 | :ref:`vector <t_vector>` type. The second operand is an index indicating |
| 4070 | the position from which to extract the element. The index may be a |
| 4071 | variable. |
| 4072 | |
| 4073 | Semantics: |
| 4074 | """""""""" |
| 4075 | |
| 4076 | The result is a scalar of the same type as the element type of ``val``. |
| 4077 | Its value is the value at position ``idx`` of ``val``. If ``idx`` |
| 4078 | exceeds the length of ``val``, the results are undefined. |
| 4079 | |
| 4080 | Example: |
| 4081 | """""""" |
| 4082 | |
| 4083 | .. code-block:: llvm |
| 4084 | |
| 4085 | <result> = extractelement <4 x i32> %vec, i32 0 ; yields i32 |
| 4086 | |
| 4087 | .. _i_insertelement: |
| 4088 | |
| 4089 | '``insertelement``' Instruction |
| 4090 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4091 | |
| 4092 | Syntax: |
| 4093 | """"""" |
| 4094 | |
| 4095 | :: |
| 4096 | |
| 4097 | <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx> ; yields <n x <ty>> |
| 4098 | |
| 4099 | Overview: |
| 4100 | """"""""" |
| 4101 | |
| 4102 | The '``insertelement``' instruction inserts a scalar element into a |
| 4103 | vector at a specified index. |
| 4104 | |
| 4105 | Arguments: |
| 4106 | """""""""" |
| 4107 | |
| 4108 | The first operand of an '``insertelement``' instruction is a value of |
| 4109 | :ref:`vector <t_vector>` type. The second operand is a scalar value whose |
| 4110 | type must equal the element type of the first operand. The third operand |
| 4111 | is an index indicating the position at which to insert the value. The |
| 4112 | index may be a variable. |
| 4113 | |
| 4114 | Semantics: |
| 4115 | """""""""" |
| 4116 | |
| 4117 | The result is a vector of the same type as ``val``. Its element values |
| 4118 | are those of ``val`` except at position ``idx``, where it gets the value |
| 4119 | ``elt``. If ``idx`` exceeds the length of ``val``, the results are |
| 4120 | undefined. |
| 4121 | |
| 4122 | Example: |
| 4123 | """""""" |
| 4124 | |
| 4125 | .. code-block:: llvm |
| 4126 | |
| 4127 | <result> = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32> |
| 4128 | |
| 4129 | .. _i_shufflevector: |
| 4130 | |
| 4131 | '``shufflevector``' Instruction |
| 4132 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4133 | |
| 4134 | Syntax: |
| 4135 | """"""" |
| 4136 | |
| 4137 | :: |
| 4138 | |
| 4139 | <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> ; yields <m x <ty>> |
| 4140 | |
| 4141 | Overview: |
| 4142 | """"""""" |
| 4143 | |
| 4144 | The '``shufflevector``' instruction constructs a permutation of elements |
| 4145 | from two input vectors, returning a vector with the same element type as |
| 4146 | the input and length that is the same as the shuffle mask. |
| 4147 | |
| 4148 | Arguments: |
| 4149 | """""""""" |
| 4150 | |
| 4151 | The first two operands of a '``shufflevector``' instruction are vectors |
| 4152 | with the same type. The third argument is a shuffle mask whose element |
| 4153 | type is always 'i32'. The result of the instruction is a vector whose |
| 4154 | length is the same as the shuffle mask and whose element type is the |
| 4155 | same as the element type of the first two operands. |
| 4156 | |
| 4157 | The shuffle mask operand is required to be a constant vector with either |
| 4158 | constant integer or undef values. |
| 4159 | |
| 4160 | Semantics: |
| 4161 | """""""""" |
| 4162 | |
| 4163 | The elements of the two input vectors are numbered from left to right |
| 4164 | across both of the vectors. The shuffle mask operand specifies, for each |
| 4165 | element of the result vector, which element of the two input vectors the |
| 4166 | result element gets. The element selector may be undef (meaning "don't |
| 4167 | care") and the second operand may be undef if performing a shuffle from |
| 4168 | only one vector. |
| 4169 | |
| 4170 | Example: |
| 4171 | """""""" |
| 4172 | |
| 4173 | .. code-block:: llvm |
| 4174 | |
| 4175 | <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, |
| 4176 | <4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32> |
| 4177 | <result> = shufflevector <4 x i32> %v1, <4 x i32> undef, |
| 4178 | <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle. |
| 4179 | <result> = shufflevector <8 x i32> %v1, <8 x i32> undef, |
| 4180 | <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> |
| 4181 | <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2, |
| 4182 | <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > ; yields <8 x i32> |
| 4183 | |
| 4184 | Aggregate Operations |
| 4185 | -------------------- |
| 4186 | |
| 4187 | LLVM supports several instructions for working with |
| 4188 | :ref:`aggregate <t_aggregate>` values. |
| 4189 | |
| 4190 | .. _i_extractvalue: |
| 4191 | |
| 4192 | '``extractvalue``' Instruction |
| 4193 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4194 | |
| 4195 | Syntax: |
| 4196 | """"""" |
| 4197 | |
| 4198 | :: |
| 4199 | |
| 4200 | <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}* |
| 4201 | |
| 4202 | Overview: |
| 4203 | """"""""" |
| 4204 | |
| 4205 | The '``extractvalue``' instruction extracts the value of a member field |
| 4206 | from an :ref:`aggregate <t_aggregate>` value. |
| 4207 | |
| 4208 | Arguments: |
| 4209 | """""""""" |
| 4210 | |
| 4211 | The first operand of an '``extractvalue``' instruction is a value of |
| 4212 | :ref:`struct <t_struct>` or :ref:`array <t_array>` type. The operands are |
| 4213 | constant indices to specify which value to extract in a similar manner |
| 4214 | as indices in a '``getelementptr``' instruction. |
| 4215 | |
| 4216 | The major differences to ``getelementptr`` indexing are: |
| 4217 | |
| 4218 | - Since the value being indexed is not a pointer, the first index is |
| 4219 | omitted and assumed to be zero. |
| 4220 | - At least one index must be specified. |
| 4221 | - Not only struct indices but also array indices must be in bounds. |
| 4222 | |
| 4223 | Semantics: |
| 4224 | """""""""" |
| 4225 | |
| 4226 | The result is the value at the position in the aggregate specified by |
| 4227 | the index operands. |
| 4228 | |
| 4229 | Example: |
| 4230 | """""""" |
| 4231 | |
| 4232 | .. code-block:: llvm |
| 4233 | |
| 4234 | <result> = extractvalue {i32, float} %agg, 0 ; yields i32 |
| 4235 | |
| 4236 | .. _i_insertvalue: |
| 4237 | |
| 4238 | '``insertvalue``' Instruction |
| 4239 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4240 | |
| 4241 | Syntax: |
| 4242 | """"""" |
| 4243 | |
| 4244 | :: |
| 4245 | |
| 4246 | <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* ; yields <aggregate type> |
| 4247 | |
| 4248 | Overview: |
| 4249 | """"""""" |
| 4250 | |
| 4251 | The '``insertvalue``' instruction inserts a value into a member field in |
| 4252 | an :ref:`aggregate <t_aggregate>` value. |
| 4253 | |
| 4254 | Arguments: |
| 4255 | """""""""" |
| 4256 | |
| 4257 | The first operand of an '``insertvalue``' instruction is a value of |
| 4258 | :ref:`struct <t_struct>` or :ref:`array <t_array>` type. The second operand is |
| 4259 | a first-class value to insert. The following operands are constant |
| 4260 | indices indicating the position at which to insert the value in a |
| 4261 | similar manner as indices in a '``extractvalue``' instruction. The value |
| 4262 | to insert must have the same type as the value identified by the |
| 4263 | indices. |
| 4264 | |
| 4265 | Semantics: |
| 4266 | """""""""" |
| 4267 | |
| 4268 | The result is an aggregate of the same type as ``val``. Its value is |
| 4269 | that of ``val`` except that the value at the position specified by the |
| 4270 | indices is that of ``elt``. |
| 4271 | |
| 4272 | Example: |
| 4273 | """""""" |
| 4274 | |
| 4275 | .. code-block:: llvm |
| 4276 | |
| 4277 | %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef} |
| 4278 | %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val} |
| 4279 | %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0 ; yields {i32 1, float %val} |
| 4280 | |
| 4281 | .. _memoryops: |
| 4282 | |
| 4283 | Memory Access and Addressing Operations |
| 4284 | --------------------------------------- |
| 4285 | |
| 4286 | A key design point of an SSA-based representation is how it represents |
| 4287 | memory. In LLVM, no memory locations are in SSA form, which makes things |
| 4288 | very simple. This section describes how to read, write, and allocate |
| 4289 | memory in LLVM. |
| 4290 | |
| 4291 | .. _i_alloca: |
| 4292 | |
| 4293 | '``alloca``' Instruction |
| 4294 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4295 | |
| 4296 | Syntax: |
| 4297 | """"""" |
| 4298 | |
| 4299 | :: |
| 4300 | |
| 4301 | <result> = alloca <type>[, <ty> <NumElements>][, align <alignment>] ; yields {type*}:result |
| 4302 | |
| 4303 | Overview: |
| 4304 | """"""""" |
| 4305 | |
| 4306 | The '``alloca``' instruction allocates memory on the stack frame of the |
| 4307 | currently executing function, to be automatically released when this |
| 4308 | function returns to its caller. The object is always allocated in the |
| 4309 | generic address space (address space zero). |
| 4310 | |
| 4311 | Arguments: |
| 4312 | """""""""" |
| 4313 | |
| 4314 | The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements`` |
| 4315 | bytes of memory on the runtime stack, returning a pointer of the |
| 4316 | appropriate type to the program. If "NumElements" is specified, it is |
| 4317 | the number of elements allocated, otherwise "NumElements" is defaulted |
| 4318 | to be one. If a constant alignment is specified, the value result of the |
| 4319 | allocation is guaranteed to be aligned to at least that boundary. If not |
| 4320 | specified, or if zero, the target can choose to align the allocation on |
| 4321 | any convenient boundary compatible with the type. |
| 4322 | |
| 4323 | '``type``' may be any sized type. |
| 4324 | |
| 4325 | Semantics: |
| 4326 | """""""""" |
| 4327 | |
| 4328 | Memory is allocated; a pointer is returned. The operation is undefined |
| 4329 | if there is insufficient stack space for the allocation. '``alloca``'d |
| 4330 | memory is automatically released when the function returns. The |
| 4331 | '``alloca``' instruction is commonly used to represent automatic |
| 4332 | variables that must have an address available. When the function returns |
| 4333 | (either with the ``ret`` or ``resume`` instructions), the memory is |
| 4334 | reclaimed. Allocating zero bytes is legal, but the result is undefined. |
| 4335 | The order in which memory is allocated (ie., which way the stack grows) |
| 4336 | is not specified. |
| 4337 | |
| 4338 | Example: |
| 4339 | """""""" |
| 4340 | |
| 4341 | .. code-block:: llvm |
| 4342 | |
| 4343 | %ptr = alloca i32 ; yields {i32*}:ptr |
| 4344 | %ptr = alloca i32, i32 4 ; yields {i32*}:ptr |
| 4345 | %ptr = alloca i32, i32 4, align 1024 ; yields {i32*}:ptr |
| 4346 | %ptr = alloca i32, align 1024 ; yields {i32*}:ptr |
| 4347 | |
| 4348 | .. _i_load: |
| 4349 | |
| 4350 | '``load``' Instruction |
| 4351 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 4352 | |
| 4353 | Syntax: |
| 4354 | """"""" |
| 4355 | |
| 4356 | :: |
| 4357 | |
| 4358 | <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>] |
| 4359 | <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment> |
| 4360 | !<index> = !{ i32 1 } |
| 4361 | |
| 4362 | Overview: |
| 4363 | """"""""" |
| 4364 | |
| 4365 | The '``load``' instruction is used to read from memory. |
| 4366 | |
| 4367 | Arguments: |
| 4368 | """""""""" |
| 4369 | |
| 4370 | The argument to the '``load``' instruction specifies the memory address |
| 4371 | from which to load. The pointer must point to a :ref:`first |
| 4372 | class <t_firstclass>` type. If the ``load`` is marked as ``volatile``, |
| 4373 | then the optimizer is not allowed to modify the number or order of |
| 4374 | execution of this ``load`` with other :ref:`volatile |
| 4375 | operations <volatile>`. |
| 4376 | |
| 4377 | If the ``load`` is marked as ``atomic``, it takes an extra |
| 4378 | :ref:`ordering <ordering>` and optional ``singlethread`` argument. The |
| 4379 | ``release`` and ``acq_rel`` orderings are not valid on ``load`` |
| 4380 | instructions. Atomic loads produce :ref:`defined <memmodel>` results |
| 4381 | when they may see multiple atomic stores. The type of the pointee must |
| 4382 | be an integer type whose bit width is a power of two greater than or |
| 4383 | equal to eight and less than or equal to a target-specific size limit. |
| 4384 | ``align`` must be explicitly specified on atomic loads, and the load has |
| 4385 | undefined behavior if the alignment is not set to a value which is at |
| 4386 | least the size in bytes of the pointee. ``!nontemporal`` does not have |
| 4387 | any defined semantics for atomic loads. |
| 4388 | |
| 4389 | The optional constant ``align`` argument specifies the alignment of the |
| 4390 | operation (that is, the alignment of the memory address). A value of 0 |
| 4391 | or an omitted ``align`` argument means that the operation has the abi |
| 4392 | alignment for the target. It is the responsibility of the code emitter |
| 4393 | to ensure that the alignment information is correct. Overestimating the |
| 4394 | alignment results in undefined behavior. Underestimating the alignment |
| 4395 | may produce less efficient code. An alignment of 1 is always safe. |
| 4396 | |
| 4397 | The optional ``!nontemporal`` metadata must reference a single |
| 4398 | metatadata name <index> corresponding to a metadata node with one |
| 4399 | ``i32`` entry of value 1. The existence of the ``!nontemporal`` |
| 4400 | metatadata on the instruction tells the optimizer and code generator |
| 4401 | that this load is not expected to be reused in the cache. The code |
| 4402 | generator may select special instructions to save cache bandwidth, such |
| 4403 | as the ``MOVNT`` instruction on x86. |
| 4404 | |
| 4405 | The optional ``!invariant.load`` metadata must reference a single |
| 4406 | metatadata name <index> corresponding to a metadata node with no |
| 4407 | entries. The existence of the ``!invariant.load`` metatadata on the |
| 4408 | instruction tells the optimizer and code generator that this load |
| 4409 | address points to memory which does not change value during program |
| 4410 | execution. The optimizer may then move this load around, for example, by |
| 4411 | hoisting it out of loops using loop invariant code motion. |
| 4412 | |
| 4413 | Semantics: |
| 4414 | """""""""" |
| 4415 | |
| 4416 | The location of memory pointed to is loaded. If the value being loaded |
| 4417 | is of scalar type then the number of bytes read does not exceed the |
| 4418 | minimum number of bytes needed to hold all bits of the type. For |
| 4419 | example, loading an ``i24`` reads at most three bytes. When loading a |
| 4420 | value of a type like ``i20`` with a size that is not an integral number |
| 4421 | of bytes, the result is undefined if the value was not originally |
| 4422 | written using a store of the same type. |
| 4423 | |
| 4424 | Examples: |
| 4425 | """"""""" |
| 4426 | |
| 4427 | .. code-block:: llvm |
| 4428 | |
| 4429 | %ptr = alloca i32 ; yields {i32*}:ptr |
| 4430 | store i32 3, i32* %ptr ; yields {void} |
| 4431 | %val = load i32* %ptr ; yields {i32}:val = i32 3 |
| 4432 | |
| 4433 | .. _i_store: |
| 4434 | |
| 4435 | '``store``' Instruction |
| 4436 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 4437 | |
| 4438 | Syntax: |
| 4439 | """"""" |
| 4440 | |
| 4441 | :: |
| 4442 | |
| 4443 | store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] ; yields {void} |
| 4444 | store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> ; yields {void} |
| 4445 | |
| 4446 | Overview: |
| 4447 | """"""""" |
| 4448 | |
| 4449 | The '``store``' instruction is used to write to memory. |
| 4450 | |
| 4451 | Arguments: |
| 4452 | """""""""" |
| 4453 | |
| 4454 | There are two arguments to the '``store``' instruction: a value to store |
| 4455 | and an address at which to store it. The type of the '``<pointer>``' |
| 4456 | operand must be a pointer to the :ref:`first class <t_firstclass>` type of |
| 4457 | the '``<value>``' operand. If the ``store`` is marked as ``volatile``, |
| 4458 | then the optimizer is not allowed to modify the number or order of |
| 4459 | execution of this ``store`` with other :ref:`volatile |
| 4460 | operations <volatile>`. |
| 4461 | |
| 4462 | If the ``store`` is marked as ``atomic``, it takes an extra |
| 4463 | :ref:`ordering <ordering>` and optional ``singlethread`` argument. The |
| 4464 | ``acquire`` and ``acq_rel`` orderings aren't valid on ``store`` |
| 4465 | instructions. Atomic loads produce :ref:`defined <memmodel>` results |
| 4466 | when they may see multiple atomic stores. The type of the pointee must |
| 4467 | be an integer type whose bit width is a power of two greater than or |
| 4468 | equal to eight and less than or equal to a target-specific size limit. |
| 4469 | ``align`` must be explicitly specified on atomic stores, and the store |
| 4470 | has undefined behavior if the alignment is not set to a value which is |
| 4471 | at least the size in bytes of the pointee. ``!nontemporal`` does not |
| 4472 | have any defined semantics for atomic stores. |
| 4473 | |
| 4474 | The optional constant "align" argument specifies the alignment of the |
| 4475 | operation (that is, the alignment of the memory address). A value of 0 |
| 4476 | or an omitted "align" argument means that the operation has the abi |
| 4477 | alignment for the target. It is the responsibility of the code emitter |
| 4478 | to ensure that the alignment information is correct. Overestimating the |
| 4479 | alignment results in an undefined behavior. Underestimating the |
| 4480 | alignment may produce less efficient code. An alignment of 1 is always |
| 4481 | safe. |
| 4482 | |
| 4483 | The optional !nontemporal metadata must reference a single metatadata |
| 4484 | name <index> corresponding to a metadata node with one i32 entry of |
| 4485 | value 1. The existence of the !nontemporal metatadata on the instruction |
| 4486 | tells the optimizer and code generator that this load is not expected to |
| 4487 | be reused in the cache. The code generator may select special |
| 4488 | instructions to save cache bandwidth, such as the MOVNT instruction on |
| 4489 | x86. |
| 4490 | |
| 4491 | Semantics: |
| 4492 | """""""""" |
| 4493 | |
| 4494 | The contents of memory are updated to contain '``<value>``' at the |
| 4495 | location specified by the '``<pointer>``' operand. If '``<value>``' is |
| 4496 | of scalar type then the number of bytes written does not exceed the |
| 4497 | minimum number of bytes needed to hold all bits of the type. For |
| 4498 | example, storing an ``i24`` writes at most three bytes. When writing a |
| 4499 | value of a type like ``i20`` with a size that is not an integral number |
| 4500 | of bytes, it is unspecified what happens to the extra bits that do not |
| 4501 | belong to the type, but they will typically be overwritten. |
| 4502 | |
| 4503 | Example: |
| 4504 | """""""" |
| 4505 | |
| 4506 | .. code-block:: llvm |
| 4507 | |
| 4508 | %ptr = alloca i32 ; yields {i32*}:ptr |
| 4509 | store i32 3, i32* %ptr ; yields {void} |
| 4510 | %val = load i32* %ptr ; yields {i32}:val = i32 3 |
| 4511 | |
| 4512 | .. _i_fence: |
| 4513 | |
| 4514 | '``fence``' Instruction |
| 4515 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 4516 | |
| 4517 | Syntax: |
| 4518 | """"""" |
| 4519 | |
| 4520 | :: |
| 4521 | |
| 4522 | fence [singlethread] <ordering> ; yields {void} |
| 4523 | |
| 4524 | Overview: |
| 4525 | """"""""" |
| 4526 | |
| 4527 | The '``fence``' instruction is used to introduce happens-before edges |
| 4528 | between operations. |
| 4529 | |
| 4530 | Arguments: |
| 4531 | """""""""" |
| 4532 | |
| 4533 | '``fence``' instructions take an :ref:`ordering <ordering>` argument which |
| 4534 | defines what *synchronizes-with* edges they add. They can only be given |
| 4535 | ``acquire``, ``release``, ``acq_rel``, and ``seq_cst`` orderings. |
| 4536 | |
| 4537 | Semantics: |
| 4538 | """""""""" |
| 4539 | |
| 4540 | A fence A which has (at least) ``release`` ordering semantics |
| 4541 | *synchronizes with* a fence B with (at least) ``acquire`` ordering |
| 4542 | semantics if and only if there exist atomic operations X and Y, both |
| 4543 | operating on some atomic object M, such that A is sequenced before X, X |
| 4544 | modifies M (either directly or through some side effect of a sequence |
| 4545 | headed by X), Y is sequenced before B, and Y observes M. This provides a |
| 4546 | *happens-before* dependency between A and B. Rather than an explicit |
| 4547 | ``fence``, one (but not both) of the atomic operations X or Y might |
| 4548 | provide a ``release`` or ``acquire`` (resp.) ordering constraint and |
| 4549 | still *synchronize-with* the explicit ``fence`` and establish the |
| 4550 | *happens-before* edge. |
| 4551 | |
| 4552 | A ``fence`` which has ``seq_cst`` ordering, in addition to having both |
| 4553 | ``acquire`` and ``release`` semantics specified above, participates in |
| 4554 | the global program order of other ``seq_cst`` operations and/or fences. |
| 4555 | |
| 4556 | The optional ":ref:`singlethread <singlethread>`" argument specifies |
| 4557 | that the fence only synchronizes with other fences in the same thread. |
| 4558 | (This is useful for interacting with signal handlers.) |
| 4559 | |
| 4560 | Example: |
| 4561 | """""""" |
| 4562 | |
| 4563 | .. code-block:: llvm |
| 4564 | |
| 4565 | fence acquire ; yields {void} |
| 4566 | fence singlethread seq_cst ; yields {void} |
| 4567 | |
| 4568 | .. _i_cmpxchg: |
| 4569 | |
| 4570 | '``cmpxchg``' Instruction |
| 4571 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4572 | |
| 4573 | Syntax: |
| 4574 | """"""" |
| 4575 | |
| 4576 | :: |
| 4577 | |
| 4578 | cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering> ; yields {ty} |
| 4579 | |
| 4580 | Overview: |
| 4581 | """"""""" |
| 4582 | |
| 4583 | The '``cmpxchg``' instruction is used to atomically modify memory. It |
| 4584 | loads a value in memory and compares it to a given value. If they are |
| 4585 | equal, it stores a new value into the memory. |
| 4586 | |
| 4587 | Arguments: |
| 4588 | """""""""" |
| 4589 | |
| 4590 | There are three arguments to the '``cmpxchg``' instruction: an address |
| 4591 | to operate on, a value to compare to the value currently be at that |
| 4592 | address, and a new value to place at that address if the compared values |
| 4593 | are equal. The type of '<cmp>' must be an integer type whose bit width |
| 4594 | is a power of two greater than or equal to eight and less than or equal |
| 4595 | to a target-specific size limit. '<cmp>' and '<new>' must have the same |
| 4596 | type, and the type of '<pointer>' must be a pointer to that type. If the |
| 4597 | ``cmpxchg`` is marked as ``volatile``, then the optimizer is not allowed |
| 4598 | to modify the number or order of execution of this ``cmpxchg`` with |
| 4599 | other :ref:`volatile operations <volatile>`. |
| 4600 | |
| 4601 | The :ref:`ordering <ordering>` argument specifies how this ``cmpxchg`` |
| 4602 | synchronizes with other atomic operations. |
| 4603 | |
| 4604 | The optional "``singlethread``" argument declares that the ``cmpxchg`` |
| 4605 | is only atomic with respect to code (usually signal handlers) running in |
| 4606 | the same thread as the ``cmpxchg``. Otherwise the cmpxchg is atomic with |
| 4607 | respect to all other code in the system. |
| 4608 | |
| 4609 | The pointer passed into cmpxchg must have alignment greater than or |
| 4610 | equal to the size in memory of the operand. |
| 4611 | |
| 4612 | Semantics: |
| 4613 | """""""""" |
| 4614 | |
| 4615 | The contents of memory at the location specified by the '``<pointer>``' |
| 4616 | operand is read and compared to '``<cmp>``'; if the read value is the |
| 4617 | equal, '``<new>``' is written. The original value at the location is |
| 4618 | returned. |
| 4619 | |
| 4620 | A successful ``cmpxchg`` is a read-modify-write instruction for the purpose |
| 4621 | of identifying release sequences. A failed ``cmpxchg`` is equivalent to an |
| 4622 | atomic load with an ordering parameter determined by dropping any |
| 4623 | ``release`` part of the ``cmpxchg``'s ordering. |
| 4624 | |
| 4625 | Example: |
| 4626 | """""""" |
| 4627 | |
| 4628 | .. code-block:: llvm |
| 4629 | |
| 4630 | entry: |
| 4631 | %orig = atomic load i32* %ptr unordered ; yields {i32} |
| 4632 | br label %loop |
| 4633 | |
| 4634 | loop: |
| 4635 | %cmp = phi i32 [ %orig, %entry ], [%old, %loop] |
| 4636 | %squared = mul i32 %cmp, %cmp |
| 4637 | %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared ; yields {i32} |
| 4638 | %success = icmp eq i32 %cmp, %old |
| 4639 | br i1 %success, label %done, label %loop |
| 4640 | |
| 4641 | done: |
| 4642 | ... |
| 4643 | |
| 4644 | .. _i_atomicrmw: |
| 4645 | |
| 4646 | '``atomicrmw``' Instruction |
| 4647 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4648 | |
| 4649 | Syntax: |
| 4650 | """"""" |
| 4651 | |
| 4652 | :: |
| 4653 | |
| 4654 | atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> ; yields {ty} |
| 4655 | |
| 4656 | Overview: |
| 4657 | """"""""" |
| 4658 | |
| 4659 | The '``atomicrmw``' instruction is used to atomically modify memory. |
| 4660 | |
| 4661 | Arguments: |
| 4662 | """""""""" |
| 4663 | |
| 4664 | There are three arguments to the '``atomicrmw``' instruction: an |
| 4665 | operation to apply, an address whose value to modify, an argument to the |
| 4666 | operation. The operation must be one of the following keywords: |
| 4667 | |
| 4668 | - xchg |
| 4669 | - add |
| 4670 | - sub |
| 4671 | - and |
| 4672 | - nand |
| 4673 | - or |
| 4674 | - xor |
| 4675 | - max |
| 4676 | - min |
| 4677 | - umax |
| 4678 | - umin |
| 4679 | |
| 4680 | The type of '<value>' must be an integer type whose bit width is a power |
| 4681 | of two greater than or equal to eight and less than or equal to a |
| 4682 | target-specific size limit. The type of the '``<pointer>``' operand must |
| 4683 | be a pointer to that type. If the ``atomicrmw`` is marked as |
| 4684 | ``volatile``, then the optimizer is not allowed to modify the number or |
| 4685 | order of execution of this ``atomicrmw`` with other :ref:`volatile |
| 4686 | operations <volatile>`. |
| 4687 | |
| 4688 | Semantics: |
| 4689 | """""""""" |
| 4690 | |
| 4691 | The contents of memory at the location specified by the '``<pointer>``' |
| 4692 | operand are atomically read, modified, and written back. The original |
| 4693 | value at the location is returned. The modification is specified by the |
| 4694 | operation argument: |
| 4695 | |
| 4696 | - xchg: ``*ptr = val`` |
| 4697 | - add: ``*ptr = *ptr + val`` |
| 4698 | - sub: ``*ptr = *ptr - val`` |
| 4699 | - and: ``*ptr = *ptr & val`` |
| 4700 | - nand: ``*ptr = ~(*ptr & val)`` |
| 4701 | - or: ``*ptr = *ptr | val`` |
| 4702 | - xor: ``*ptr = *ptr ^ val`` |
| 4703 | - max: ``*ptr = *ptr > val ? *ptr : val`` (using a signed comparison) |
| 4704 | - min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison) |
| 4705 | - umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned |
| 4706 | comparison) |
| 4707 | - umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned |
| 4708 | comparison) |
| 4709 | |
| 4710 | Example: |
| 4711 | """""""" |
| 4712 | |
| 4713 | .. code-block:: llvm |
| 4714 | |
| 4715 | %old = atomicrmw add i32* %ptr, i32 1 acquire ; yields {i32} |
| 4716 | |
| 4717 | .. _i_getelementptr: |
| 4718 | |
| 4719 | '``getelementptr``' Instruction |
| 4720 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4721 | |
| 4722 | Syntax: |
| 4723 | """"""" |
| 4724 | |
| 4725 | :: |
| 4726 | |
| 4727 | <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}* |
| 4728 | <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}* |
| 4729 | <result> = getelementptr <ptr vector> ptrval, <vector index type> idx |
| 4730 | |
| 4731 | Overview: |
| 4732 | """"""""" |
| 4733 | |
| 4734 | The '``getelementptr``' instruction is used to get the address of a |
| 4735 | subelement of an :ref:`aggregate <t_aggregate>` data structure. It performs |
| 4736 | address calculation only and does not access memory. |
| 4737 | |
| 4738 | Arguments: |
| 4739 | """""""""" |
| 4740 | |
| 4741 | The first argument is always a pointer or a vector of pointers, and |
| 4742 | forms the basis of the calculation. The remaining arguments are indices |
| 4743 | that indicate which of the elements of the aggregate object are indexed. |
| 4744 | The interpretation of each index is dependent on the type being indexed |
| 4745 | into. The first index always indexes the pointer value given as the |
| 4746 | first argument, the second index indexes a value of the type pointed to |
| 4747 | (not necessarily the value directly pointed to, since the first index |
| 4748 | can be non-zero), etc. The first type indexed into must be a pointer |
| 4749 | value, subsequent types can be arrays, vectors, and structs. Note that |
| 4750 | subsequent types being indexed into can never be pointers, since that |
| 4751 | would require loading the pointer before continuing calculation. |
| 4752 | |
| 4753 | The type of each index argument depends on the type it is indexing into. |
| 4754 | When indexing into a (optionally packed) structure, only ``i32`` integer |
| 4755 | **constants** are allowed (when using a vector of indices they must all |
| 4756 | be the **same** ``i32`` integer constant). When indexing into an array, |
| 4757 | pointer or vector, integers of any width are allowed, and they are not |
| 4758 | required to be constant. These integers are treated as signed values |
| 4759 | where relevant. |
| 4760 | |
| 4761 | For example, let's consider a C code fragment and how it gets compiled |
| 4762 | to LLVM: |
| 4763 | |
| 4764 | .. code-block:: c |
| 4765 | |
| 4766 | struct RT { |
| 4767 | char A; |
| 4768 | int B[10][20]; |
| 4769 | char C; |
| 4770 | }; |
| 4771 | struct ST { |
| 4772 | int X; |
| 4773 | double Y; |
| 4774 | struct RT Z; |
| 4775 | }; |
| 4776 | |
| 4777 | int *foo(struct ST *s) { |
| 4778 | return &s[1].Z.B[5][13]; |
| 4779 | } |
| 4780 | |
| 4781 | The LLVM code generated by Clang is: |
| 4782 | |
| 4783 | .. code-block:: llvm |
| 4784 | |
| 4785 | %struct.RT = type { i8, [10 x [20 x i32]], i8 } |
| 4786 | %struct.ST = type { i32, double, %struct.RT } |
| 4787 | |
| 4788 | define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp { |
| 4789 | entry: |
| 4790 | %arrayidx = getelementptr inbounds %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13 |
| 4791 | ret i32* %arrayidx |
| 4792 | } |
| 4793 | |
| 4794 | Semantics: |
| 4795 | """""""""" |
| 4796 | |
| 4797 | In the example above, the first index is indexing into the |
| 4798 | '``%struct.ST*``' type, which is a pointer, yielding a '``%struct.ST``' |
| 4799 | = '``{ i32, double, %struct.RT }``' type, a structure. The second index |
| 4800 | indexes into the third element of the structure, yielding a |
| 4801 | '``%struct.RT``' = '``{ i8 , [10 x [20 x i32]], i8 }``' type, another |
| 4802 | structure. The third index indexes into the second element of the |
| 4803 | structure, yielding a '``[10 x [20 x i32]]``' type, an array. The two |
| 4804 | dimensions of the array are subscripted into, yielding an '``i32``' |
| 4805 | type. The '``getelementptr``' instruction returns a pointer to this |
| 4806 | element, thus computing a value of '``i32*``' type. |
| 4807 | |
| 4808 | Note that it is perfectly legal to index partially through a structure, |
| 4809 | returning a pointer to an inner element. Because of this, the LLVM code |
| 4810 | for the given testcase is equivalent to: |
| 4811 | |
| 4812 | .. code-block:: llvm |
| 4813 | |
| 4814 | define i32* @foo(%struct.ST* %s) { |
| 4815 | %t1 = getelementptr %struct.ST* %s, i32 1 ; yields %struct.ST*:%t1 |
| 4816 | %t2 = getelementptr %struct.ST* %t1, i32 0, i32 2 ; yields %struct.RT*:%t2 |
| 4817 | %t3 = getelementptr %struct.RT* %t2, i32 0, i32 1 ; yields [10 x [20 x i32]]*:%t3 |
| 4818 | %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 ; yields [20 x i32]*:%t4 |
| 4819 | %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 ; yields i32*:%t5 |
| 4820 | ret i32* %t5 |
| 4821 | } |
| 4822 | |
| 4823 | If the ``inbounds`` keyword is present, the result value of the |
| 4824 | ``getelementptr`` is a :ref:`poison value <poisonvalues>` if the base |
| 4825 | pointer is not an *in bounds* address of an allocated object, or if any |
| 4826 | of the addresses that would be formed by successive addition of the |
| 4827 | offsets implied by the indices to the base address with infinitely |
| 4828 | precise signed arithmetic are not an *in bounds* address of that |
| 4829 | allocated object. The *in bounds* addresses for an allocated object are |
| 4830 | all the addresses that point into the object, plus the address one byte |
| 4831 | past the end. In cases where the base is a vector of pointers the |
| 4832 | ``inbounds`` keyword applies to each of the computations element-wise. |
| 4833 | |
| 4834 | If the ``inbounds`` keyword is not present, the offsets are added to the |
| 4835 | base address with silently-wrapping two's complement arithmetic. If the |
| 4836 | offsets have a different width from the pointer, they are sign-extended |
| 4837 | or truncated to the width of the pointer. The result value of the |
| 4838 | ``getelementptr`` may be outside the object pointed to by the base |
| 4839 | pointer. The result value may not necessarily be used to access memory |
| 4840 | though, even if it happens to point into allocated storage. See the |
| 4841 | :ref:`Pointer Aliasing Rules <pointeraliasing>` section for more |
| 4842 | information. |
| 4843 | |
| 4844 | The getelementptr instruction is often confusing. For some more insight |
| 4845 | into how it works, see :doc:`the getelementptr FAQ <GetElementPtr>`. |
| 4846 | |
| 4847 | Example: |
| 4848 | """""""" |
| 4849 | |
| 4850 | .. code-block:: llvm |
| 4851 | |
| 4852 | ; yields [12 x i8]*:aptr |
| 4853 | %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1 |
| 4854 | ; yields i8*:vptr |
| 4855 | %vptr = getelementptr {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1 |
| 4856 | ; yields i8*:eptr |
| 4857 | %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1 |
| 4858 | ; yields i32*:iptr |
| 4859 | %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0 |
| 4860 | |
| 4861 | In cases where the pointer argument is a vector of pointers, each index |
| 4862 | must be a vector with the same number of elements. For example: |
| 4863 | |
| 4864 | .. code-block:: llvm |
| 4865 | |
| 4866 | %A = getelementptr <4 x i8*> %ptrs, <4 x i64> %offsets, |
| 4867 | |
| 4868 | Conversion Operations |
| 4869 | --------------------- |
| 4870 | |
| 4871 | The instructions in this category are the conversion instructions |
| 4872 | (casting) which all take a single operand and a type. They perform |
| 4873 | various bit conversions on the operand. |
| 4874 | |
| 4875 | '``trunc .. to``' Instruction |
| 4876 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4877 | |
| 4878 | Syntax: |
| 4879 | """"""" |
| 4880 | |
| 4881 | :: |
| 4882 | |
| 4883 | <result> = trunc <ty> <value> to <ty2> ; yields ty2 |
| 4884 | |
| 4885 | Overview: |
| 4886 | """"""""" |
| 4887 | |
| 4888 | The '``trunc``' instruction truncates its operand to the type ``ty2``. |
| 4889 | |
| 4890 | Arguments: |
| 4891 | """""""""" |
| 4892 | |
| 4893 | The '``trunc``' instruction takes a value to trunc, and a type to trunc |
| 4894 | it to. Both types must be of :ref:`integer <t_integer>` types, or vectors |
| 4895 | of the same number of integers. The bit size of the ``value`` must be |
| 4896 | larger than the bit size of the destination type, ``ty2``. Equal sized |
| 4897 | types are not allowed. |
| 4898 | |
| 4899 | Semantics: |
| 4900 | """""""""" |
| 4901 | |
| 4902 | The '``trunc``' instruction truncates the high order bits in ``value`` |
| 4903 | and converts the remaining bits to ``ty2``. Since the source size must |
| 4904 | be larger than the destination size, ``trunc`` cannot be a *no-op cast*. |
| 4905 | It will always truncate bits. |
| 4906 | |
| 4907 | Example: |
| 4908 | """""""" |
| 4909 | |
| 4910 | .. code-block:: llvm |
| 4911 | |
| 4912 | %X = trunc i32 257 to i8 ; yields i8:1 |
| 4913 | %Y = trunc i32 123 to i1 ; yields i1:true |
| 4914 | %Z = trunc i32 122 to i1 ; yields i1:false |
| 4915 | %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7> |
| 4916 | |
| 4917 | '``zext .. to``' Instruction |
| 4918 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4919 | |
| 4920 | Syntax: |
| 4921 | """"""" |
| 4922 | |
| 4923 | :: |
| 4924 | |
| 4925 | <result> = zext <ty> <value> to <ty2> ; yields ty2 |
| 4926 | |
| 4927 | Overview: |
| 4928 | """"""""" |
| 4929 | |
| 4930 | The '``zext``' instruction zero extends its operand to type ``ty2``. |
| 4931 | |
| 4932 | Arguments: |
| 4933 | """""""""" |
| 4934 | |
| 4935 | The '``zext``' instruction takes a value to cast, and a type to cast it |
| 4936 | to. Both types must be of :ref:`integer <t_integer>` types, or vectors of |
| 4937 | the same number of integers. The bit size of the ``value`` must be |
| 4938 | smaller than the bit size of the destination type, ``ty2``. |
| 4939 | |
| 4940 | Semantics: |
| 4941 | """""""""" |
| 4942 | |
| 4943 | The ``zext`` fills the high order bits of the ``value`` with zero bits |
| 4944 | until it reaches the size of the destination type, ``ty2``. |
| 4945 | |
| 4946 | When zero extending from i1, the result will always be either 0 or 1. |
| 4947 | |
| 4948 | Example: |
| 4949 | """""""" |
| 4950 | |
| 4951 | .. code-block:: llvm |
| 4952 | |
| 4953 | %X = zext i32 257 to i64 ; yields i64:257 |
| 4954 | %Y = zext i1 true to i32 ; yields i32:1 |
| 4955 | %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> |
| 4956 | |
| 4957 | '``sext .. to``' Instruction |
| 4958 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 4959 | |
| 4960 | Syntax: |
| 4961 | """"""" |
| 4962 | |
| 4963 | :: |
| 4964 | |
| 4965 | <result> = sext <ty> <value> to <ty2> ; yields ty2 |
| 4966 | |
| 4967 | Overview: |
| 4968 | """"""""" |
| 4969 | |
| 4970 | The '``sext``' sign extends ``value`` to the type ``ty2``. |
| 4971 | |
| 4972 | Arguments: |
| 4973 | """""""""" |
| 4974 | |
| 4975 | The '``sext``' instruction takes a value to cast, and a type to cast it |
| 4976 | to. Both types must be of :ref:`integer <t_integer>` types, or vectors of |
| 4977 | the same number of integers. The bit size of the ``value`` must be |
| 4978 | smaller than the bit size of the destination type, ``ty2``. |
| 4979 | |
| 4980 | Semantics: |
| 4981 | """""""""" |
| 4982 | |
| 4983 | The '``sext``' instruction performs a sign extension by copying the sign |
| 4984 | bit (highest order bit) of the ``value`` until it reaches the bit size |
| 4985 | of the type ``ty2``. |
| 4986 | |
| 4987 | When sign extending from i1, the extension always results in -1 or 0. |
| 4988 | |
| 4989 | Example: |
| 4990 | """""""" |
| 4991 | |
| 4992 | .. code-block:: llvm |
| 4993 | |
| 4994 | %X = sext i8 -1 to i16 ; yields i16 :65535 |
| 4995 | %Y = sext i1 true to i32 ; yields i32:-1 |
| 4996 | %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7> |
| 4997 | |
| 4998 | '``fptrunc .. to``' Instruction |
| 4999 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5000 | |
| 5001 | Syntax: |
| 5002 | """"""" |
| 5003 | |
| 5004 | :: |
| 5005 | |
| 5006 | <result> = fptrunc <ty> <value> to <ty2> ; yields ty2 |
| 5007 | |
| 5008 | Overview: |
| 5009 | """"""""" |
| 5010 | |
| 5011 | The '``fptrunc``' instruction truncates ``value`` to type ``ty2``. |
| 5012 | |
| 5013 | Arguments: |
| 5014 | """""""""" |
| 5015 | |
| 5016 | The '``fptrunc``' instruction takes a :ref:`floating point <t_floating>` |
| 5017 | value to cast and a :ref:`floating point <t_floating>` type to cast it to. |
| 5018 | The size of ``value`` must be larger than the size of ``ty2``. This |
| 5019 | implies that ``fptrunc`` cannot be used to make a *no-op cast*. |
| 5020 | |
| 5021 | Semantics: |
| 5022 | """""""""" |
| 5023 | |
| 5024 | The '``fptrunc``' instruction truncates a ``value`` from a larger |
| 5025 | :ref:`floating point <t_floating>` type to a smaller :ref:`floating |
| 5026 | point <t_floating>` type. If the value cannot fit within the |
| 5027 | destination type, ``ty2``, then the results are undefined. |
| 5028 | |
| 5029 | Example: |
| 5030 | """""""" |
| 5031 | |
| 5032 | .. code-block:: llvm |
| 5033 | |
| 5034 | %X = fptrunc double 123.0 to float ; yields float:123.0 |
| 5035 | %Y = fptrunc double 1.0E+300 to float ; yields undefined |
| 5036 | |
| 5037 | '``fpext .. to``' Instruction |
| 5038 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5039 | |
| 5040 | Syntax: |
| 5041 | """"""" |
| 5042 | |
| 5043 | :: |
| 5044 | |
| 5045 | <result> = fpext <ty> <value> to <ty2> ; yields ty2 |
| 5046 | |
| 5047 | Overview: |
| 5048 | """"""""" |
| 5049 | |
| 5050 | The '``fpext``' extends a floating point ``value`` to a larger floating |
| 5051 | point value. |
| 5052 | |
| 5053 | Arguments: |
| 5054 | """""""""" |
| 5055 | |
| 5056 | The '``fpext``' instruction takes a :ref:`floating point <t_floating>` |
| 5057 | ``value`` to cast, and a :ref:`floating point <t_floating>` type to cast it |
| 5058 | to. The source type must be smaller than the destination type. |
| 5059 | |
| 5060 | Semantics: |
| 5061 | """""""""" |
| 5062 | |
| 5063 | The '``fpext``' instruction extends the ``value`` from a smaller |
| 5064 | :ref:`floating point <t_floating>` type to a larger :ref:`floating |
| 5065 | point <t_floating>` type. The ``fpext`` cannot be used to make a |
| 5066 | *no-op cast* because it always changes bits. Use ``bitcast`` to make a |
| 5067 | *no-op cast* for a floating point cast. |
| 5068 | |
| 5069 | Example: |
| 5070 | """""""" |
| 5071 | |
| 5072 | .. code-block:: llvm |
| 5073 | |
| 5074 | %X = fpext float 3.125 to double ; yields double:3.125000e+00 |
| 5075 | %Y = fpext double %X to fp128 ; yields fp128:0xL00000000000000004000900000000000 |
| 5076 | |
| 5077 | '``fptoui .. to``' Instruction |
| 5078 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5079 | |
| 5080 | Syntax: |
| 5081 | """"""" |
| 5082 | |
| 5083 | :: |
| 5084 | |
| 5085 | <result> = fptoui <ty> <value> to <ty2> ; yields ty2 |
| 5086 | |
| 5087 | Overview: |
| 5088 | """"""""" |
| 5089 | |
| 5090 | The '``fptoui``' converts a floating point ``value`` to its unsigned |
| 5091 | integer equivalent of type ``ty2``. |
| 5092 | |
| 5093 | Arguments: |
| 5094 | """""""""" |
| 5095 | |
| 5096 | The '``fptoui``' instruction takes a value to cast, which must be a |
| 5097 | scalar or vector :ref:`floating point <t_floating>` value, and a type to |
| 5098 | cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If |
| 5099 | ``ty`` is a vector floating point type, ``ty2`` must be a vector integer |
| 5100 | type with the same number of elements as ``ty`` |
| 5101 | |
| 5102 | Semantics: |
| 5103 | """""""""" |
| 5104 | |
| 5105 | The '``fptoui``' instruction converts its :ref:`floating |
| 5106 | point <t_floating>` operand into the nearest (rounding towards zero) |
| 5107 | unsigned integer value. If the value cannot fit in ``ty2``, the results |
| 5108 | are undefined. |
| 5109 | |
| 5110 | Example: |
| 5111 | """""""" |
| 5112 | |
| 5113 | .. code-block:: llvm |
| 5114 | |
| 5115 | %X = fptoui double 123.0 to i32 ; yields i32:123 |
| 5116 | %Y = fptoui float 1.0E+300 to i1 ; yields undefined:1 |
| 5117 | %Z = fptoui float 1.04E+17 to i8 ; yields undefined:1 |
| 5118 | |
| 5119 | '``fptosi .. to``' Instruction |
| 5120 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5121 | |
| 5122 | Syntax: |
| 5123 | """"""" |
| 5124 | |
| 5125 | :: |
| 5126 | |
| 5127 | <result> = fptosi <ty> <value> to <ty2> ; yields ty2 |
| 5128 | |
| 5129 | Overview: |
| 5130 | """"""""" |
| 5131 | |
| 5132 | The '``fptosi``' instruction converts :ref:`floating point <t_floating>` |
| 5133 | ``value`` to type ``ty2``. |
| 5134 | |
| 5135 | Arguments: |
| 5136 | """""""""" |
| 5137 | |
| 5138 | The '``fptosi``' instruction takes a value to cast, which must be a |
| 5139 | scalar or vector :ref:`floating point <t_floating>` value, and a type to |
| 5140 | cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If |
| 5141 | ``ty`` is a vector floating point type, ``ty2`` must be a vector integer |
| 5142 | type with the same number of elements as ``ty`` |
| 5143 | |
| 5144 | Semantics: |
| 5145 | """""""""" |
| 5146 | |
| 5147 | The '``fptosi``' instruction converts its :ref:`floating |
| 5148 | point <t_floating>` operand into the nearest (rounding towards zero) |
| 5149 | signed integer value. If the value cannot fit in ``ty2``, the results |
| 5150 | are undefined. |
| 5151 | |
| 5152 | Example: |
| 5153 | """""""" |
| 5154 | |
| 5155 | .. code-block:: llvm |
| 5156 | |
| 5157 | %X = fptosi double -123.0 to i32 ; yields i32:-123 |
| 5158 | %Y = fptosi float 1.0E-247 to i1 ; yields undefined:1 |
| 5159 | %Z = fptosi float 1.04E+17 to i8 ; yields undefined:1 |
| 5160 | |
| 5161 | '``uitofp .. to``' Instruction |
| 5162 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5163 | |
| 5164 | Syntax: |
| 5165 | """"""" |
| 5166 | |
| 5167 | :: |
| 5168 | |
| 5169 | <result> = uitofp <ty> <value> to <ty2> ; yields ty2 |
| 5170 | |
| 5171 | Overview: |
| 5172 | """"""""" |
| 5173 | |
| 5174 | The '``uitofp``' instruction regards ``value`` as an unsigned integer |
| 5175 | and converts that value to the ``ty2`` type. |
| 5176 | |
| 5177 | Arguments: |
| 5178 | """""""""" |
| 5179 | |
| 5180 | The '``uitofp``' instruction takes a value to cast, which must be a |
| 5181 | scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to |
| 5182 | ``ty2``, which must be an :ref:`floating point <t_floating>` type. If |
| 5183 | ``ty`` is a vector integer type, ``ty2`` must be a vector floating point |
| 5184 | type with the same number of elements as ``ty`` |
| 5185 | |
| 5186 | Semantics: |
| 5187 | """""""""" |
| 5188 | |
| 5189 | The '``uitofp``' instruction interprets its operand as an unsigned |
| 5190 | integer quantity and converts it to the corresponding floating point |
| 5191 | value. If the value cannot fit in the floating point value, the results |
| 5192 | are undefined. |
| 5193 | |
| 5194 | Example: |
| 5195 | """""""" |
| 5196 | |
| 5197 | .. code-block:: llvm |
| 5198 | |
| 5199 | %X = uitofp i32 257 to float ; yields float:257.0 |
| 5200 | %Y = uitofp i8 -1 to double ; yields double:255.0 |
| 5201 | |
| 5202 | '``sitofp .. to``' Instruction |
| 5203 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5204 | |
| 5205 | Syntax: |
| 5206 | """"""" |
| 5207 | |
| 5208 | :: |
| 5209 | |
| 5210 | <result> = sitofp <ty> <value> to <ty2> ; yields ty2 |
| 5211 | |
| 5212 | Overview: |
| 5213 | """"""""" |
| 5214 | |
| 5215 | The '``sitofp``' instruction regards ``value`` as a signed integer and |
| 5216 | converts that value to the ``ty2`` type. |
| 5217 | |
| 5218 | Arguments: |
| 5219 | """""""""" |
| 5220 | |
| 5221 | The '``sitofp``' instruction takes a value to cast, which must be a |
| 5222 | scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to |
| 5223 | ``ty2``, which must be an :ref:`floating point <t_floating>` type. If |
| 5224 | ``ty`` is a vector integer type, ``ty2`` must be a vector floating point |
| 5225 | type with the same number of elements as ``ty`` |
| 5226 | |
| 5227 | Semantics: |
| 5228 | """""""""" |
| 5229 | |
| 5230 | The '``sitofp``' instruction interprets its operand as a signed integer |
| 5231 | quantity and converts it to the corresponding floating point value. If |
| 5232 | the value cannot fit in the floating point value, the results are |
| 5233 | undefined. |
| 5234 | |
| 5235 | Example: |
| 5236 | """""""" |
| 5237 | |
| 5238 | .. code-block:: llvm |
| 5239 | |
| 5240 | %X = sitofp i32 257 to float ; yields float:257.0 |
| 5241 | %Y = sitofp i8 -1 to double ; yields double:-1.0 |
| 5242 | |
| 5243 | .. _i_ptrtoint: |
| 5244 | |
| 5245 | '``ptrtoint .. to``' Instruction |
| 5246 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5247 | |
| 5248 | Syntax: |
| 5249 | """"""" |
| 5250 | |
| 5251 | :: |
| 5252 | |
| 5253 | <result> = ptrtoint <ty> <value> to <ty2> ; yields ty2 |
| 5254 | |
| 5255 | Overview: |
| 5256 | """"""""" |
| 5257 | |
| 5258 | The '``ptrtoint``' instruction converts the pointer or a vector of |
| 5259 | pointers ``value`` to the integer (or vector of integers) type ``ty2``. |
| 5260 | |
| 5261 | Arguments: |
| 5262 | """""""""" |
| 5263 | |
| 5264 | The '``ptrtoint``' instruction takes a ``value`` to cast, which must be |
| 5265 | a a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a |
| 5266 | type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or |
| 5267 | a vector of integers type. |
| 5268 | |
| 5269 | Semantics: |
| 5270 | """""""""" |
| 5271 | |
| 5272 | The '``ptrtoint``' instruction converts ``value`` to integer type |
| 5273 | ``ty2`` by interpreting the pointer value as an integer and either |
| 5274 | truncating or zero extending that value to the size of the integer type. |
| 5275 | If ``value`` is smaller than ``ty2`` then a zero extension is done. If |
| 5276 | ``value`` is larger than ``ty2`` then a truncation is done. If they are |
| 5277 | the same size, then nothing is done (*no-op cast*) other than a type |
| 5278 | change. |
| 5279 | |
| 5280 | Example: |
| 5281 | """""""" |
| 5282 | |
| 5283 | .. code-block:: llvm |
| 5284 | |
| 5285 | %X = ptrtoint i32* %P to i8 ; yields truncation on 32-bit architecture |
| 5286 | %Y = ptrtoint i32* %P to i64 ; yields zero extension on 32-bit architecture |
| 5287 | %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture |
| 5288 | |
| 5289 | .. _i_inttoptr: |
| 5290 | |
| 5291 | '``inttoptr .. to``' Instruction |
| 5292 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5293 | |
| 5294 | Syntax: |
| 5295 | """"""" |
| 5296 | |
| 5297 | :: |
| 5298 | |
| 5299 | <result> = inttoptr <ty> <value> to <ty2> ; yields ty2 |
| 5300 | |
| 5301 | Overview: |
| 5302 | """"""""" |
| 5303 | |
| 5304 | The '``inttoptr``' instruction converts an integer ``value`` to a |
| 5305 | pointer type, ``ty2``. |
| 5306 | |
| 5307 | Arguments: |
| 5308 | """""""""" |
| 5309 | |
| 5310 | The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to |
| 5311 | cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>` |
| 5312 | type. |
| 5313 | |
| 5314 | Semantics: |
| 5315 | """""""""" |
| 5316 | |
| 5317 | The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by |
| 5318 | applying either a zero extension or a truncation depending on the size |
| 5319 | of the integer ``value``. If ``value`` is larger than the size of a |
| 5320 | pointer then a truncation is done. If ``value`` is smaller than the size |
| 5321 | of a pointer then a zero extension is done. If they are the same size, |
| 5322 | nothing is done (*no-op cast*). |
| 5323 | |
| 5324 | Example: |
| 5325 | """""""" |
| 5326 | |
| 5327 | .. code-block:: llvm |
| 5328 | |
| 5329 | %X = inttoptr i32 255 to i32* ; yields zero extension on 64-bit architecture |
| 5330 | %Y = inttoptr i32 255 to i32* ; yields no-op on 32-bit architecture |
| 5331 | %Z = inttoptr i64 0 to i32* ; yields truncation on 32-bit architecture |
| 5332 | %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers |
| 5333 | |
| 5334 | .. _i_bitcast: |
| 5335 | |
| 5336 | '``bitcast .. to``' Instruction |
| 5337 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5338 | |
| 5339 | Syntax: |
| 5340 | """"""" |
| 5341 | |
| 5342 | :: |
| 5343 | |
| 5344 | <result> = bitcast <ty> <value> to <ty2> ; yields ty2 |
| 5345 | |
| 5346 | Overview: |
| 5347 | """"""""" |
| 5348 | |
| 5349 | The '``bitcast``' instruction converts ``value`` to type ``ty2`` without |
| 5350 | changing any bits. |
| 5351 | |
| 5352 | Arguments: |
| 5353 | """""""""" |
| 5354 | |
| 5355 | The '``bitcast``' instruction takes a value to cast, which must be a |
| 5356 | non-aggregate first class value, and a type to cast it to, which must |
| 5357 | also be a non-aggregate :ref:`first class <t_firstclass>` type. The bit |
| 5358 | sizes of ``value`` and the destination type, ``ty2``, must be identical. |
| 5359 | If the source type is a pointer, the destination type must also be a |
| 5360 | pointer. This instruction supports bitwise conversion of vectors to |
| 5361 | integers and to vectors of other types (as long as they have the same |
| 5362 | size). |
| 5363 | |
| 5364 | Semantics: |
| 5365 | """""""""" |
| 5366 | |
| 5367 | The '``bitcast``' instruction converts ``value`` to type ``ty2``. It is |
| 5368 | always a *no-op cast* because no bits change with this conversion. The |
| 5369 | conversion is done as if the ``value`` had been stored to memory and |
| 5370 | read back as type ``ty2``. Pointer (or vector of pointers) types may |
| 5371 | only be converted to other pointer (or vector of pointers) types with |
| 5372 | this instruction. To convert pointers to other types, use the |
| 5373 | :ref:`inttoptr <i_inttoptr>` or :ref:`ptrtoint <i_ptrtoint>` instructions |
| 5374 | first. |
| 5375 | |
| 5376 | Example: |
| 5377 | """""""" |
| 5378 | |
| 5379 | .. code-block:: llvm |
| 5380 | |
| 5381 | %X = bitcast i8 255 to i8 ; yields i8 :-1 |
| 5382 | %Y = bitcast i32* %x to sint* ; yields sint*:%x |
| 5383 | %Z = bitcast <2 x int> %V to i64; ; yields i64: %V |
| 5384 | %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*> |
| 5385 | |
| 5386 | .. _otherops: |
| 5387 | |
| 5388 | Other Operations |
| 5389 | ---------------- |
| 5390 | |
| 5391 | The instructions in this category are the "miscellaneous" instructions, |
| 5392 | which defy better classification. |
| 5393 | |
| 5394 | .. _i_icmp: |
| 5395 | |
| 5396 | '``icmp``' Instruction |
| 5397 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 5398 | |
| 5399 | Syntax: |
| 5400 | """"""" |
| 5401 | |
| 5402 | :: |
| 5403 | |
| 5404 | <result> = icmp <cond> <ty> <op1>, <op2> ; yields {i1} or {<N x i1>}:result |
| 5405 | |
| 5406 | Overview: |
| 5407 | """"""""" |
| 5408 | |
| 5409 | The '``icmp``' instruction returns a boolean value or a vector of |
| 5410 | boolean values based on comparison of its two integer, integer vector, |
| 5411 | pointer, or pointer vector operands. |
| 5412 | |
| 5413 | Arguments: |
| 5414 | """""""""" |
| 5415 | |
| 5416 | The '``icmp``' instruction takes three operands. The first operand is |
| 5417 | the condition code indicating the kind of comparison to perform. It is |
| 5418 | not a value, just a keyword. The possible condition code are: |
| 5419 | |
| 5420 | #. ``eq``: equal |
| 5421 | #. ``ne``: not equal |
| 5422 | #. ``ugt``: unsigned greater than |
| 5423 | #. ``uge``: unsigned greater or equal |
| 5424 | #. ``ult``: unsigned less than |
| 5425 | #. ``ule``: unsigned less or equal |
| 5426 | #. ``sgt``: signed greater than |
| 5427 | #. ``sge``: signed greater or equal |
| 5428 | #. ``slt``: signed less than |
| 5429 | #. ``sle``: signed less or equal |
| 5430 | |
| 5431 | The remaining two arguments must be :ref:`integer <t_integer>` or |
| 5432 | :ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They |
| 5433 | must also be identical types. |
| 5434 | |
| 5435 | Semantics: |
| 5436 | """""""""" |
| 5437 | |
| 5438 | The '``icmp``' compares ``op1`` and ``op2`` according to the condition |
| 5439 | code given as ``cond``. The comparison performed always yields either an |
| 5440 | :ref:`i1 <t_integer>` or vector of ``i1`` result, as follows: |
| 5441 | |
| 5442 | #. ``eq``: yields ``true`` if the operands are equal, ``false`` |
| 5443 | otherwise. No sign interpretation is necessary or performed. |
| 5444 | #. ``ne``: yields ``true`` if the operands are unequal, ``false`` |
| 5445 | otherwise. No sign interpretation is necessary or performed. |
| 5446 | #. ``ugt``: interprets the operands as unsigned values and yields |
| 5447 | ``true`` if ``op1`` is greater than ``op2``. |
| 5448 | #. ``uge``: interprets the operands as unsigned values and yields |
| 5449 | ``true`` if ``op1`` is greater than or equal to ``op2``. |
| 5450 | #. ``ult``: interprets the operands as unsigned values and yields |
| 5451 | ``true`` if ``op1`` is less than ``op2``. |
| 5452 | #. ``ule``: interprets the operands as unsigned values and yields |
| 5453 | ``true`` if ``op1`` is less than or equal to ``op2``. |
| 5454 | #. ``sgt``: interprets the operands as signed values and yields ``true`` |
| 5455 | if ``op1`` is greater than ``op2``. |
| 5456 | #. ``sge``: interprets the operands as signed values and yields ``true`` |
| 5457 | if ``op1`` is greater than or equal to ``op2``. |
| 5458 | #. ``slt``: interprets the operands as signed values and yields ``true`` |
| 5459 | if ``op1`` is less than ``op2``. |
| 5460 | #. ``sle``: interprets the operands as signed values and yields ``true`` |
| 5461 | if ``op1`` is less than or equal to ``op2``. |
| 5462 | |
| 5463 | If the operands are :ref:`pointer <t_pointer>` typed, the pointer values |
| 5464 | are compared as if they were integers. |
| 5465 | |
| 5466 | If the operands are integer vectors, then they are compared element by |
| 5467 | element. The result is an ``i1`` vector with the same number of elements |
| 5468 | as the values being compared. Otherwise, the result is an ``i1``. |
| 5469 | |
| 5470 | Example: |
| 5471 | """""""" |
| 5472 | |
| 5473 | .. code-block:: llvm |
| 5474 | |
| 5475 | <result> = icmp eq i32 4, 5 ; yields: result=false |
| 5476 | <result> = icmp ne float* %X, %X ; yields: result=false |
| 5477 | <result> = icmp ult i16 4, 5 ; yields: result=true |
| 5478 | <result> = icmp sgt i16 4, 5 ; yields: result=false |
| 5479 | <result> = icmp ule i16 -4, 5 ; yields: result=false |
| 5480 | <result> = icmp sge i16 4, 5 ; yields: result=false |
| 5481 | |
| 5482 | Note that the code generator does not yet support vector types with the |
| 5483 | ``icmp`` instruction. |
| 5484 | |
| 5485 | .. _i_fcmp: |
| 5486 | |
| 5487 | '``fcmp``' Instruction |
| 5488 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 5489 | |
| 5490 | Syntax: |
| 5491 | """"""" |
| 5492 | |
| 5493 | :: |
| 5494 | |
| 5495 | <result> = fcmp <cond> <ty> <op1>, <op2> ; yields {i1} or {<N x i1>}:result |
| 5496 | |
| 5497 | Overview: |
| 5498 | """"""""" |
| 5499 | |
| 5500 | The '``fcmp``' instruction returns a boolean value or vector of boolean |
| 5501 | values based on comparison of its operands. |
| 5502 | |
| 5503 | If the operands are floating point scalars, then the result type is a |
| 5504 | boolean (:ref:`i1 <t_integer>`). |
| 5505 | |
| 5506 | If the operands are floating point vectors, then the result type is a |
| 5507 | vector of boolean with the same number of elements as the operands being |
| 5508 | compared. |
| 5509 | |
| 5510 | Arguments: |
| 5511 | """""""""" |
| 5512 | |
| 5513 | The '``fcmp``' instruction takes three operands. The first operand is |
| 5514 | the condition code indicating the kind of comparison to perform. It is |
| 5515 | not a value, just a keyword. The possible condition code are: |
| 5516 | |
| 5517 | #. ``false``: no comparison, always returns false |
| 5518 | #. ``oeq``: ordered and equal |
| 5519 | #. ``ogt``: ordered and greater than |
| 5520 | #. ``oge``: ordered and greater than or equal |
| 5521 | #. ``olt``: ordered and less than |
| 5522 | #. ``ole``: ordered and less than or equal |
| 5523 | #. ``one``: ordered and not equal |
| 5524 | #. ``ord``: ordered (no nans) |
| 5525 | #. ``ueq``: unordered or equal |
| 5526 | #. ``ugt``: unordered or greater than |
| 5527 | #. ``uge``: unordered or greater than or equal |
| 5528 | #. ``ult``: unordered or less than |
| 5529 | #. ``ule``: unordered or less than or equal |
| 5530 | #. ``une``: unordered or not equal |
| 5531 | #. ``uno``: unordered (either nans) |
| 5532 | #. ``true``: no comparison, always returns true |
| 5533 | |
| 5534 | *Ordered* means that neither operand is a QNAN while *unordered* means |
| 5535 | that either operand may be a QNAN. |
| 5536 | |
| 5537 | Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating |
| 5538 | point <t_floating>` type or a :ref:`vector <t_vector>` of floating point |
| 5539 | type. They must have identical types. |
| 5540 | |
| 5541 | Semantics: |
| 5542 | """""""""" |
| 5543 | |
| 5544 | The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the |
| 5545 | condition code given as ``cond``. If the operands are vectors, then the |
| 5546 | vectors are compared element by element. Each comparison performed |
| 5547 | always yields an :ref:`i1 <t_integer>` result, as follows: |
| 5548 | |
| 5549 | #. ``false``: always yields ``false``, regardless of operands. |
| 5550 | #. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1`` |
| 5551 | is equal to ``op2``. |
| 5552 | #. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1`` |
| 5553 | is greater than ``op2``. |
| 5554 | #. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1`` |
| 5555 | is greater than or equal to ``op2``. |
| 5556 | #. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1`` |
| 5557 | is less than ``op2``. |
| 5558 | #. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1`` |
| 5559 | is less than or equal to ``op2``. |
| 5560 | #. ``one``: yields ``true`` if both operands are not a QNAN and ``op1`` |
| 5561 | is not equal to ``op2``. |
| 5562 | #. ``ord``: yields ``true`` if both operands are not a QNAN. |
| 5563 | #. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is |
| 5564 | equal to ``op2``. |
| 5565 | #. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is |
| 5566 | greater than ``op2``. |
| 5567 | #. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is |
| 5568 | greater than or equal to ``op2``. |
| 5569 | #. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is |
| 5570 | less than ``op2``. |
| 5571 | #. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is |
| 5572 | less than or equal to ``op2``. |
| 5573 | #. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is |
| 5574 | not equal to ``op2``. |
| 5575 | #. ``uno``: yields ``true`` if either operand is a QNAN. |
| 5576 | #. ``true``: always yields ``true``, regardless of operands. |
| 5577 | |
| 5578 | Example: |
| 5579 | """""""" |
| 5580 | |
| 5581 | .. code-block:: llvm |
| 5582 | |
| 5583 | <result> = fcmp oeq float 4.0, 5.0 ; yields: result=false |
| 5584 | <result> = fcmp one float 4.0, 5.0 ; yields: result=true |
| 5585 | <result> = fcmp olt float 4.0, 5.0 ; yields: result=true |
| 5586 | <result> = fcmp ueq double 1.0, 2.0 ; yields: result=false |
| 5587 | |
| 5588 | Note that the code generator does not yet support vector types with the |
| 5589 | ``fcmp`` instruction. |
| 5590 | |
| 5591 | .. _i_phi: |
| 5592 | |
| 5593 | '``phi``' Instruction |
| 5594 | ^^^^^^^^^^^^^^^^^^^^^ |
| 5595 | |
| 5596 | Syntax: |
| 5597 | """"""" |
| 5598 | |
| 5599 | :: |
| 5600 | |
| 5601 | <result> = phi <ty> [ <val0>, <label0>], ... |
| 5602 | |
| 5603 | Overview: |
| 5604 | """"""""" |
| 5605 | |
| 5606 | The '``phi``' instruction is used to implement the φ node in the SSA |
| 5607 | graph representing the function. |
| 5608 | |
| 5609 | Arguments: |
| 5610 | """""""""" |
| 5611 | |
| 5612 | The type of the incoming values is specified with the first type field. |
| 5613 | After this, the '``phi``' instruction takes a list of pairs as |
| 5614 | arguments, with one pair for each predecessor basic block of the current |
| 5615 | block. Only values of :ref:`first class <t_firstclass>` type may be used as |
| 5616 | the value arguments to the PHI node. Only labels may be used as the |
| 5617 | label arguments. |
| 5618 | |
| 5619 | There must be no non-phi instructions between the start of a basic block |
| 5620 | and the PHI instructions: i.e. PHI instructions must be first in a basic |
| 5621 | block. |
| 5622 | |
| 5623 | For the purposes of the SSA form, the use of each incoming value is |
| 5624 | deemed to occur on the edge from the corresponding predecessor block to |
| 5625 | the current block (but after any definition of an '``invoke``' |
| 5626 | instruction's return value on the same edge). |
| 5627 | |
| 5628 | Semantics: |
| 5629 | """""""""" |
| 5630 | |
| 5631 | At runtime, the '``phi``' instruction logically takes on the value |
| 5632 | specified by the pair corresponding to the predecessor basic block that |
| 5633 | executed just prior to the current block. |
| 5634 | |
| 5635 | Example: |
| 5636 | """""""" |
| 5637 | |
| 5638 | .. code-block:: llvm |
| 5639 | |
| 5640 | Loop: ; Infinite loop that counts from 0 on up... |
| 5641 | %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ] |
| 5642 | %nextindvar = add i32 %indvar, 1 |
| 5643 | br label %Loop |
| 5644 | |
| 5645 | .. _i_select: |
| 5646 | |
| 5647 | '``select``' Instruction |
| 5648 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5649 | |
| 5650 | Syntax: |
| 5651 | """"""" |
| 5652 | |
| 5653 | :: |
| 5654 | |
| 5655 | <result> = select selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty |
| 5656 | |
| 5657 | selty is either i1 or {<N x i1>} |
| 5658 | |
| 5659 | Overview: |
| 5660 | """"""""" |
| 5661 | |
| 5662 | The '``select``' instruction is used to choose one value based on a |
| 5663 | condition, without branching. |
| 5664 | |
| 5665 | Arguments: |
| 5666 | """""""""" |
| 5667 | |
| 5668 | The '``select``' instruction requires an 'i1' value or a vector of 'i1' |
| 5669 | values indicating the condition, and two values of the same :ref:`first |
| 5670 | class <t_firstclass>` type. If the val1/val2 are vectors and the |
| 5671 | condition is a scalar, then entire vectors are selected, not individual |
| 5672 | elements. |
| 5673 | |
| 5674 | Semantics: |
| 5675 | """""""""" |
| 5676 | |
| 5677 | If the condition is an i1 and it evaluates to 1, the instruction returns |
| 5678 | the first value argument; otherwise, it returns the second value |
| 5679 | argument. |
| 5680 | |
| 5681 | If the condition is a vector of i1, then the value arguments must be |
| 5682 | vectors of the same size, and the selection is done element by element. |
| 5683 | |
| 5684 | Example: |
| 5685 | """""""" |
| 5686 | |
| 5687 | .. code-block:: llvm |
| 5688 | |
| 5689 | %X = select i1 true, i8 17, i8 42 ; yields i8:17 |
| 5690 | |
| 5691 | .. _i_call: |
| 5692 | |
| 5693 | '``call``' Instruction |
| 5694 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 5695 | |
| 5696 | Syntax: |
| 5697 | """"""" |
| 5698 | |
| 5699 | :: |
| 5700 | |
| 5701 | <result> = [tail] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs] |
| 5702 | |
| 5703 | Overview: |
| 5704 | """"""""" |
| 5705 | |
| 5706 | The '``call``' instruction represents a simple function call. |
| 5707 | |
| 5708 | Arguments: |
| 5709 | """""""""" |
| 5710 | |
| 5711 | This instruction requires several arguments: |
| 5712 | |
| 5713 | #. The optional "tail" marker indicates that the callee function does |
| 5714 | not access any allocas or varargs in the caller. Note that calls may |
| 5715 | be marked "tail" even if they do not occur before a |
| 5716 | :ref:`ret <i_ret>` instruction. If the "tail" marker is present, the |
| 5717 | function call is eligible for tail call optimization, but `might not |
| 5718 | in fact be optimized into a jump <CodeGenerator.html#tailcallopt>`_. |
| 5719 | The code generator may optimize calls marked "tail" with either 1) |
| 5720 | automatic `sibling call |
| 5721 | optimization <CodeGenerator.html#sibcallopt>`_ when the caller and |
| 5722 | callee have matching signatures, or 2) forced tail call optimization |
| 5723 | when the following extra requirements are met: |
| 5724 | |
| 5725 | - Caller and callee both have the calling convention ``fastcc``. |
| 5726 | - The call is in tail position (ret immediately follows call and ret |
| 5727 | uses value of call or is void). |
| 5728 | - Option ``-tailcallopt`` is enabled, or |
| 5729 | ``llvm::GuaranteedTailCallOpt`` is ``true``. |
| 5730 | - `Platform specific constraints are |
| 5731 | met. <CodeGenerator.html#tailcallopt>`_ |
| 5732 | |
| 5733 | #. The optional "cconv" marker indicates which :ref:`calling |
| 5734 | convention <callingconv>` the call should use. If none is |
| 5735 | specified, the call defaults to using C calling conventions. The |
| 5736 | calling convention of the call must match the calling convention of |
| 5737 | the target function, or else the behavior is undefined. |
| 5738 | #. The optional :ref:`Parameter Attributes <paramattrs>` list for return |
| 5739 | values. Only '``zeroext``', '``signext``', and '``inreg``' attributes |
| 5740 | are valid here. |
| 5741 | #. '``ty``': the type of the call instruction itself which is also the |
| 5742 | type of the return value. Functions that return no value are marked |
| 5743 | ``void``. |
| 5744 | #. '``fnty``': shall be the signature of the pointer to function value |
| 5745 | being invoked. The argument types must match the types implied by |
| 5746 | this signature. This type can be omitted if the function is not |
| 5747 | varargs and if the function type does not return a pointer to a |
| 5748 | function. |
| 5749 | #. '``fnptrval``': An LLVM value containing a pointer to a function to |
| 5750 | be invoked. In most cases, this is a direct function invocation, but |
| 5751 | indirect ``call``'s are just as possible, calling an arbitrary pointer |
| 5752 | to function value. |
| 5753 | #. '``function args``': argument list whose types match the function |
| 5754 | signature argument types and parameter attributes. All arguments must |
| 5755 | be of :ref:`first class <t_firstclass>` type. If the function signature |
| 5756 | indicates the function accepts a variable number of arguments, the |
| 5757 | extra arguments can be specified. |
| 5758 | #. The optional :ref:`function attributes <fnattrs>` list. Only |
| 5759 | '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``' |
| 5760 | attributes are valid here. |
| 5761 | |
| 5762 | Semantics: |
| 5763 | """""""""" |
| 5764 | |
| 5765 | The '``call``' instruction is used to cause control flow to transfer to |
| 5766 | a specified function, with its incoming arguments bound to the specified |
| 5767 | values. Upon a '``ret``' instruction in the called function, control |
| 5768 | flow continues with the instruction after the function call, and the |
| 5769 | return value of the function is bound to the result argument. |
| 5770 | |
| 5771 | Example: |
| 5772 | """""""" |
| 5773 | |
| 5774 | .. code-block:: llvm |
| 5775 | |
| 5776 | %retval = call i32 @test(i32 %argc) |
| 5777 | call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) ; yields i32 |
| 5778 | %X = tail call i32 @foo() ; yields i32 |
| 5779 | %Y = tail call fastcc i32 @foo() ; yields i32 |
| 5780 | call void %foo(i8 97 signext) |
| 5781 | |
| 5782 | %struct.A = type { i32, i8 } |
| 5783 | %r = call %struct.A @foo() ; yields { 32, i8 } |
| 5784 | %gr = extractvalue %struct.A %r, 0 ; yields i32 |
| 5785 | %gr1 = extractvalue %struct.A %r, 1 ; yields i8 |
| 5786 | %Z = call void @foo() noreturn ; indicates that %foo never returns normally |
| 5787 | %ZZ = call zeroext i32 @bar() ; Return value is %zero extended |
| 5788 | |
| 5789 | llvm treats calls to some functions with names and arguments that match |
| 5790 | the standard C99 library as being the C99 library functions, and may |
| 5791 | perform optimizations or generate code for them under that assumption. |
| 5792 | This is something we'd like to change in the future to provide better |
| 5793 | support for freestanding environments and non-C-based languages. |
| 5794 | |
| 5795 | .. _i_va_arg: |
| 5796 | |
| 5797 | '``va_arg``' Instruction |
| 5798 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5799 | |
| 5800 | Syntax: |
| 5801 | """"""" |
| 5802 | |
| 5803 | :: |
| 5804 | |
| 5805 | <resultval> = va_arg <va_list*> <arglist>, <argty> |
| 5806 | |
| 5807 | Overview: |
| 5808 | """"""""" |
| 5809 | |
| 5810 | The '``va_arg``' instruction is used to access arguments passed through |
| 5811 | the "variable argument" area of a function call. It is used to implement |
| 5812 | the ``va_arg`` macro in C. |
| 5813 | |
| 5814 | Arguments: |
| 5815 | """""""""" |
| 5816 | |
| 5817 | This instruction takes a ``va_list*`` value and the type of the |
| 5818 | argument. It returns a value of the specified argument type and |
| 5819 | increments the ``va_list`` to point to the next argument. The actual |
| 5820 | type of ``va_list`` is target specific. |
| 5821 | |
| 5822 | Semantics: |
| 5823 | """""""""" |
| 5824 | |
| 5825 | The '``va_arg``' instruction loads an argument of the specified type |
| 5826 | from the specified ``va_list`` and causes the ``va_list`` to point to |
| 5827 | the next argument. For more information, see the variable argument |
| 5828 | handling :ref:`Intrinsic Functions <int_varargs>`. |
| 5829 | |
| 5830 | It is legal for this instruction to be called in a function which does |
| 5831 | not take a variable number of arguments, for example, the ``vfprintf`` |
| 5832 | function. |
| 5833 | |
| 5834 | ``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic |
| 5835 | function <intrinsics>` because it takes a type as an argument. |
| 5836 | |
| 5837 | Example: |
| 5838 | """""""" |
| 5839 | |
| 5840 | See the :ref:`variable argument processing <int_varargs>` section. |
| 5841 | |
| 5842 | Note that the code generator does not yet fully support va\_arg on many |
| 5843 | targets. Also, it does not currently support va\_arg with aggregate |
| 5844 | types on any target. |
| 5845 | |
| 5846 | .. _i_landingpad: |
| 5847 | |
| 5848 | '``landingpad``' Instruction |
| 5849 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 5850 | |
| 5851 | Syntax: |
| 5852 | """"""" |
| 5853 | |
| 5854 | :: |
| 5855 | |
| 5856 | <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+ |
| 5857 | <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>* |
| 5858 | |
| 5859 | <clause> := catch <type> <value> |
| 5860 | <clause> := filter <array constant type> <array constant> |
| 5861 | |
| 5862 | Overview: |
| 5863 | """"""""" |
| 5864 | |
| 5865 | The '``landingpad``' instruction is used by `LLVM's exception handling |
| 5866 | system <ExceptionHandling.html#overview>`_ to specify that a basic block |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 5867 | is a landing pad --- one where the exception lands, and corresponds to the |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 5868 | code found in the ``catch`` portion of a ``try``/``catch`` sequence. It |
| 5869 | defines values supplied by the personality function (``pers_fn``) upon |
| 5870 | re-entry to the function. The ``resultval`` has the type ``resultty``. |
| 5871 | |
| 5872 | Arguments: |
| 5873 | """""""""" |
| 5874 | |
| 5875 | This instruction takes a ``pers_fn`` value. This is the personality |
| 5876 | function associated with the unwinding mechanism. The optional |
| 5877 | ``cleanup`` flag indicates that the landing pad block is a cleanup. |
| 5878 | |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 5879 | A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 5880 | contains the global variable representing the "type" that may be caught |
| 5881 | or filtered respectively. Unlike the ``catch`` clause, the ``filter`` |
| 5882 | clause takes an array constant as its argument. Use |
| 5883 | "``[0 x i8**] undef``" for a filter which cannot throw. The |
| 5884 | '``landingpad``' instruction must contain *at least* one ``clause`` or |
| 5885 | the ``cleanup`` flag. |
| 5886 | |
| 5887 | Semantics: |
| 5888 | """""""""" |
| 5889 | |
| 5890 | The '``landingpad``' instruction defines the values which are set by the |
| 5891 | personality function (``pers_fn``) upon re-entry to the function, and |
| 5892 | therefore the "result type" of the ``landingpad`` instruction. As with |
| 5893 | calling conventions, how the personality function results are |
| 5894 | represented in LLVM IR is target specific. |
| 5895 | |
| 5896 | The clauses are applied in order from top to bottom. If two |
| 5897 | ``landingpad`` instructions are merged together through inlining, the |
| 5898 | clauses from the calling function are appended to the list of clauses. |
| 5899 | When the call stack is being unwound due to an exception being thrown, |
| 5900 | the exception is compared against each ``clause`` in turn. If it doesn't |
| 5901 | match any of the clauses, and the ``cleanup`` flag is not set, then |
| 5902 | unwinding continues further up the call stack. |
| 5903 | |
| 5904 | The ``landingpad`` instruction has several restrictions: |
| 5905 | |
| 5906 | - A landing pad block is a basic block which is the unwind destination |
| 5907 | of an '``invoke``' instruction. |
| 5908 | - A landing pad block must have a '``landingpad``' instruction as its |
| 5909 | first non-PHI instruction. |
| 5910 | - There can be only one '``landingpad``' instruction within the landing |
| 5911 | pad block. |
| 5912 | - A basic block that is not a landing pad block may not include a |
| 5913 | '``landingpad``' instruction. |
| 5914 | - All '``landingpad``' instructions in a function must have the same |
| 5915 | personality function. |
| 5916 | |
| 5917 | Example: |
| 5918 | """""""" |
| 5919 | |
| 5920 | .. code-block:: llvm |
| 5921 | |
| 5922 | ;; A landing pad which can catch an integer. |
| 5923 | %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 |
| 5924 | catch i8** @_ZTIi |
| 5925 | ;; A landing pad that is a cleanup. |
| 5926 | %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 |
| 5927 | cleanup |
| 5928 | ;; A landing pad which can catch an integer and can only throw a double. |
| 5929 | %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 |
| 5930 | catch i8** @_ZTIi |
| 5931 | filter [1 x i8**] [@_ZTId] |
| 5932 | |
| 5933 | .. _intrinsics: |
| 5934 | |
| 5935 | Intrinsic Functions |
| 5936 | =================== |
| 5937 | |
| 5938 | LLVM supports the notion of an "intrinsic function". These functions |
| 5939 | have well known names and semantics and are required to follow certain |
| 5940 | restrictions. Overall, these intrinsics represent an extension mechanism |
| 5941 | for the LLVM language that does not require changing all of the |
| 5942 | transformations in LLVM when adding to the language (or the bitcode |
| 5943 | reader/writer, the parser, etc...). |
| 5944 | |
| 5945 | Intrinsic function names must all start with an "``llvm.``" prefix. This |
| 5946 | prefix is reserved in LLVM for intrinsic names; thus, function names may |
| 5947 | not begin with this prefix. Intrinsic functions must always be external |
| 5948 | functions: you cannot define the body of intrinsic functions. Intrinsic |
| 5949 | functions may only be used in call or invoke instructions: it is illegal |
| 5950 | to take the address of an intrinsic function. Additionally, because |
| 5951 | intrinsic functions are part of the LLVM language, it is required if any |
| 5952 | are added that they be documented here. |
| 5953 | |
| 5954 | Some intrinsic functions can be overloaded, i.e., the intrinsic |
| 5955 | represents a family of functions that perform the same operation but on |
| 5956 | different data types. Because LLVM can represent over 8 million |
| 5957 | different integer types, overloading is used commonly to allow an |
| 5958 | intrinsic function to operate on any integer type. One or more of the |
| 5959 | argument types or the result type can be overloaded to accept any |
| 5960 | integer type. Argument types may also be defined as exactly matching a |
| 5961 | previous argument's type or the result type. This allows an intrinsic |
| 5962 | function which accepts multiple arguments, but needs all of them to be |
| 5963 | of the same type, to only be overloaded with respect to a single |
| 5964 | argument or the result. |
| 5965 | |
| 5966 | Overloaded intrinsics will have the names of its overloaded argument |
| 5967 | types encoded into its function name, each preceded by a period. Only |
| 5968 | those types which are overloaded result in a name suffix. Arguments |
| 5969 | whose type is matched against another type do not. For example, the |
| 5970 | ``llvm.ctpop`` function can take an integer of any width and returns an |
| 5971 | integer of exactly the same integer width. This leads to a family of |
| 5972 | functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and |
| 5973 | ``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is |
| 5974 | overloaded, and only one type suffix is required. Because the argument's |
| 5975 | type is matched against the return type, it does not require its own |
| 5976 | name suffix. |
| 5977 | |
| 5978 | To learn how to add an intrinsic function, please see the `Extending |
| 5979 | LLVM Guide <ExtendingLLVM.html>`_. |
| 5980 | |
| 5981 | .. _int_varargs: |
| 5982 | |
| 5983 | Variable Argument Handling Intrinsics |
| 5984 | ------------------------------------- |
| 5985 | |
| 5986 | Variable argument support is defined in LLVM with the |
| 5987 | :ref:`va_arg <i_va_arg>` instruction and these three intrinsic |
| 5988 | functions. These functions are related to the similarly named macros |
| 5989 | defined in the ``<stdarg.h>`` header file. |
| 5990 | |
| 5991 | All of these functions operate on arguments that use a target-specific |
| 5992 | value type "``va_list``". The LLVM assembly language reference manual |
| 5993 | does not define what this type is, so all transformations should be |
| 5994 | prepared to handle these functions regardless of the type used. |
| 5995 | |
| 5996 | This example shows how the :ref:`va_arg <i_va_arg>` instruction and the |
| 5997 | variable argument handling intrinsic functions are used. |
| 5998 | |
| 5999 | .. code-block:: llvm |
| 6000 | |
| 6001 | define i32 @test(i32 %X, ...) { |
| 6002 | ; Initialize variable argument processing |
| 6003 | %ap = alloca i8* |
| 6004 | %ap2 = bitcast i8** %ap to i8* |
| 6005 | call void @llvm.va_start(i8* %ap2) |
| 6006 | |
| 6007 | ; Read a single integer argument |
| 6008 | %tmp = va_arg i8** %ap, i32 |
| 6009 | |
| 6010 | ; Demonstrate usage of llvm.va_copy and llvm.va_end |
| 6011 | %aq = alloca i8* |
| 6012 | %aq2 = bitcast i8** %aq to i8* |
| 6013 | call void @llvm.va_copy(i8* %aq2, i8* %ap2) |
| 6014 | call void @llvm.va_end(i8* %aq2) |
| 6015 | |
| 6016 | ; Stop processing of arguments. |
| 6017 | call void @llvm.va_end(i8* %ap2) |
| 6018 | ret i32 %tmp |
| 6019 | } |
| 6020 | |
| 6021 | declare void @llvm.va_start(i8*) |
| 6022 | declare void @llvm.va_copy(i8*, i8*) |
| 6023 | declare void @llvm.va_end(i8*) |
| 6024 | |
| 6025 | .. _int_va_start: |
| 6026 | |
| 6027 | '``llvm.va_start``' Intrinsic |
| 6028 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6029 | |
| 6030 | Syntax: |
| 6031 | """"""" |
| 6032 | |
| 6033 | :: |
| 6034 | |
| 6035 | declare void %llvm.va_start(i8* <arglist>) |
| 6036 | |
| 6037 | Overview: |
| 6038 | """"""""" |
| 6039 | |
| 6040 | The '``llvm.va_start``' intrinsic initializes ``*<arglist>`` for |
| 6041 | subsequent use by ``va_arg``. |
| 6042 | |
| 6043 | Arguments: |
| 6044 | """""""""" |
| 6045 | |
| 6046 | The argument is a pointer to a ``va_list`` element to initialize. |
| 6047 | |
| 6048 | Semantics: |
| 6049 | """""""""" |
| 6050 | |
| 6051 | The '``llvm.va_start``' intrinsic works just like the ``va_start`` macro |
| 6052 | available in C. In a target-dependent way, it initializes the |
| 6053 | ``va_list`` element to which the argument points, so that the next call |
| 6054 | to ``va_arg`` will produce the first variable argument passed to the |
| 6055 | function. Unlike the C ``va_start`` macro, this intrinsic does not need |
| 6056 | to know the last argument of the function as the compiler can figure |
| 6057 | that out. |
| 6058 | |
| 6059 | '``llvm.va_end``' Intrinsic |
| 6060 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6061 | |
| 6062 | Syntax: |
| 6063 | """"""" |
| 6064 | |
| 6065 | :: |
| 6066 | |
| 6067 | declare void @llvm.va_end(i8* <arglist>) |
| 6068 | |
| 6069 | Overview: |
| 6070 | """"""""" |
| 6071 | |
| 6072 | The '``llvm.va_end``' intrinsic destroys ``*<arglist>``, which has been |
| 6073 | initialized previously with ``llvm.va_start`` or ``llvm.va_copy``. |
| 6074 | |
| 6075 | Arguments: |
| 6076 | """""""""" |
| 6077 | |
| 6078 | The argument is a pointer to a ``va_list`` to destroy. |
| 6079 | |
| 6080 | Semantics: |
| 6081 | """""""""" |
| 6082 | |
| 6083 | The '``llvm.va_end``' intrinsic works just like the ``va_end`` macro |
| 6084 | available in C. In a target-dependent way, it destroys the ``va_list`` |
| 6085 | element to which the argument points. Calls to |
| 6086 | :ref:`llvm.va_start <int_va_start>` and |
| 6087 | :ref:`llvm.va_copy <int_va_copy>` must be matched exactly with calls to |
| 6088 | ``llvm.va_end``. |
| 6089 | |
| 6090 | .. _int_va_copy: |
| 6091 | |
| 6092 | '``llvm.va_copy``' Intrinsic |
| 6093 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6094 | |
| 6095 | Syntax: |
| 6096 | """"""" |
| 6097 | |
| 6098 | :: |
| 6099 | |
| 6100 | declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>) |
| 6101 | |
| 6102 | Overview: |
| 6103 | """"""""" |
| 6104 | |
| 6105 | The '``llvm.va_copy``' intrinsic copies the current argument position |
| 6106 | from the source argument list to the destination argument list. |
| 6107 | |
| 6108 | Arguments: |
| 6109 | """""""""" |
| 6110 | |
| 6111 | The first argument is a pointer to a ``va_list`` element to initialize. |
| 6112 | The second argument is a pointer to a ``va_list`` element to copy from. |
| 6113 | |
| 6114 | Semantics: |
| 6115 | """""""""" |
| 6116 | |
| 6117 | The '``llvm.va_copy``' intrinsic works just like the ``va_copy`` macro |
| 6118 | available in C. In a target-dependent way, it copies the source |
| 6119 | ``va_list`` element into the destination ``va_list`` element. This |
| 6120 | intrinsic is necessary because the `` llvm.va_start`` intrinsic may be |
| 6121 | arbitrarily complex and require, for example, memory allocation. |
| 6122 | |
| 6123 | Accurate Garbage Collection Intrinsics |
| 6124 | -------------------------------------- |
| 6125 | |
| 6126 | LLVM support for `Accurate Garbage Collection <GarbageCollection.html>`_ |
| 6127 | (GC) requires the implementation and generation of these intrinsics. |
| 6128 | These intrinsics allow identification of :ref:`GC roots on the |
| 6129 | stack <int_gcroot>`, as well as garbage collector implementations that |
| 6130 | require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. |
| 6131 | Front-ends for type-safe garbage collected languages should generate |
| 6132 | these intrinsics to make use of the LLVM garbage collectors. For more |
| 6133 | details, see `Accurate Garbage Collection with |
| 6134 | LLVM <GarbageCollection.html>`_. |
| 6135 | |
| 6136 | The garbage collection intrinsics only operate on objects in the generic |
| 6137 | address space (address space zero). |
| 6138 | |
| 6139 | .. _int_gcroot: |
| 6140 | |
| 6141 | '``llvm.gcroot``' Intrinsic |
| 6142 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6143 | |
| 6144 | Syntax: |
| 6145 | """"""" |
| 6146 | |
| 6147 | :: |
| 6148 | |
| 6149 | declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata) |
| 6150 | |
| 6151 | Overview: |
| 6152 | """"""""" |
| 6153 | |
| 6154 | The '``llvm.gcroot``' intrinsic declares the existence of a GC root to |
| 6155 | the code generator, and allows some metadata to be associated with it. |
| 6156 | |
| 6157 | Arguments: |
| 6158 | """""""""" |
| 6159 | |
| 6160 | The first argument specifies the address of a stack object that contains |
| 6161 | the root pointer. The second pointer (which must be either a constant or |
| 6162 | a global value address) contains the meta-data to be associated with the |
| 6163 | root. |
| 6164 | |
| 6165 | Semantics: |
| 6166 | """""""""" |
| 6167 | |
| 6168 | At runtime, a call to this intrinsic stores a null pointer into the |
| 6169 | "ptrloc" location. At compile-time, the code generator generates |
| 6170 | information to allow the runtime to find the pointer at GC safe points. |
| 6171 | The '``llvm.gcroot``' intrinsic may only be used in a function which |
| 6172 | :ref:`specifies a GC algorithm <gc>`. |
| 6173 | |
| 6174 | .. _int_gcread: |
| 6175 | |
| 6176 | '``llvm.gcread``' Intrinsic |
| 6177 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6178 | |
| 6179 | Syntax: |
| 6180 | """"""" |
| 6181 | |
| 6182 | :: |
| 6183 | |
| 6184 | declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr) |
| 6185 | |
| 6186 | Overview: |
| 6187 | """"""""" |
| 6188 | |
| 6189 | The '``llvm.gcread``' intrinsic identifies reads of references from heap |
| 6190 | locations, allowing garbage collector implementations that require read |
| 6191 | barriers. |
| 6192 | |
| 6193 | Arguments: |
| 6194 | """""""""" |
| 6195 | |
| 6196 | The second argument is the address to read from, which should be an |
| 6197 | address allocated from the garbage collector. The first object is a |
| 6198 | pointer to the start of the referenced object, if needed by the language |
| 6199 | runtime (otherwise null). |
| 6200 | |
| 6201 | Semantics: |
| 6202 | """""""""" |
| 6203 | |
| 6204 | The '``llvm.gcread``' intrinsic has the same semantics as a load |
| 6205 | instruction, but may be replaced with substantially more complex code by |
| 6206 | the garbage collector runtime, as needed. The '``llvm.gcread``' |
| 6207 | intrinsic may only be used in a function which :ref:`specifies a GC |
| 6208 | algorithm <gc>`. |
| 6209 | |
| 6210 | .. _int_gcwrite: |
| 6211 | |
| 6212 | '``llvm.gcwrite``' Intrinsic |
| 6213 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6214 | |
| 6215 | Syntax: |
| 6216 | """"""" |
| 6217 | |
| 6218 | :: |
| 6219 | |
| 6220 | declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2) |
| 6221 | |
| 6222 | Overview: |
| 6223 | """"""""" |
| 6224 | |
| 6225 | The '``llvm.gcwrite``' intrinsic identifies writes of references to heap |
| 6226 | locations, allowing garbage collector implementations that require write |
| 6227 | barriers (such as generational or reference counting collectors). |
| 6228 | |
| 6229 | Arguments: |
| 6230 | """""""""" |
| 6231 | |
| 6232 | The first argument is the reference to store, the second is the start of |
| 6233 | the object to store it to, and the third is the address of the field of |
| 6234 | Obj to store to. If the runtime does not require a pointer to the |
| 6235 | object, Obj may be null. |
| 6236 | |
| 6237 | Semantics: |
| 6238 | """""""""" |
| 6239 | |
| 6240 | The '``llvm.gcwrite``' intrinsic has the same semantics as a store |
| 6241 | instruction, but may be replaced with substantially more complex code by |
| 6242 | the garbage collector runtime, as needed. The '``llvm.gcwrite``' |
| 6243 | intrinsic may only be used in a function which :ref:`specifies a GC |
| 6244 | algorithm <gc>`. |
| 6245 | |
| 6246 | Code Generator Intrinsics |
| 6247 | ------------------------- |
| 6248 | |
| 6249 | These intrinsics are provided by LLVM to expose special features that |
| 6250 | may only be implemented with code generator support. |
| 6251 | |
| 6252 | '``llvm.returnaddress``' Intrinsic |
| 6253 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6254 | |
| 6255 | Syntax: |
| 6256 | """"""" |
| 6257 | |
| 6258 | :: |
| 6259 | |
| 6260 | declare i8 *@llvm.returnaddress(i32 <level>) |
| 6261 | |
| 6262 | Overview: |
| 6263 | """"""""" |
| 6264 | |
| 6265 | The '``llvm.returnaddress``' intrinsic attempts to compute a |
| 6266 | target-specific value indicating the return address of the current |
| 6267 | function or one of its callers. |
| 6268 | |
| 6269 | Arguments: |
| 6270 | """""""""" |
| 6271 | |
| 6272 | The argument to this intrinsic indicates which function to return the |
| 6273 | address for. Zero indicates the calling function, one indicates its |
| 6274 | caller, etc. The argument is **required** to be a constant integer |
| 6275 | value. |
| 6276 | |
| 6277 | Semantics: |
| 6278 | """""""""" |
| 6279 | |
| 6280 | The '``llvm.returnaddress``' intrinsic either returns a pointer |
| 6281 | indicating the return address of the specified call frame, or zero if it |
| 6282 | cannot be identified. The value returned by this intrinsic is likely to |
| 6283 | be incorrect or 0 for arguments other than zero, so it should only be |
| 6284 | used for debugging purposes. |
| 6285 | |
| 6286 | Note that calling this intrinsic does not prevent function inlining or |
| 6287 | other aggressive transformations, so the value returned may not be that |
| 6288 | of the obvious source-language caller. |
| 6289 | |
| 6290 | '``llvm.frameaddress``' Intrinsic |
| 6291 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6292 | |
| 6293 | Syntax: |
| 6294 | """"""" |
| 6295 | |
| 6296 | :: |
| 6297 | |
| 6298 | declare i8* @llvm.frameaddress(i32 <level>) |
| 6299 | |
| 6300 | Overview: |
| 6301 | """"""""" |
| 6302 | |
| 6303 | The '``llvm.frameaddress``' intrinsic attempts to return the |
| 6304 | target-specific frame pointer value for the specified stack frame. |
| 6305 | |
| 6306 | Arguments: |
| 6307 | """""""""" |
| 6308 | |
| 6309 | The argument to this intrinsic indicates which function to return the |
| 6310 | frame pointer for. Zero indicates the calling function, one indicates |
| 6311 | its caller, etc. The argument is **required** to be a constant integer |
| 6312 | value. |
| 6313 | |
| 6314 | Semantics: |
| 6315 | """""""""" |
| 6316 | |
| 6317 | The '``llvm.frameaddress``' intrinsic either returns a pointer |
| 6318 | indicating the frame address of the specified call frame, or zero if it |
| 6319 | cannot be identified. The value returned by this intrinsic is likely to |
| 6320 | be incorrect or 0 for arguments other than zero, so it should only be |
| 6321 | used for debugging purposes. |
| 6322 | |
| 6323 | Note that calling this intrinsic does not prevent function inlining or |
| 6324 | other aggressive transformations, so the value returned may not be that |
| 6325 | of the obvious source-language caller. |
| 6326 | |
| 6327 | .. _int_stacksave: |
| 6328 | |
| 6329 | '``llvm.stacksave``' Intrinsic |
| 6330 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6331 | |
| 6332 | Syntax: |
| 6333 | """"""" |
| 6334 | |
| 6335 | :: |
| 6336 | |
| 6337 | declare i8* @llvm.stacksave() |
| 6338 | |
| 6339 | Overview: |
| 6340 | """"""""" |
| 6341 | |
| 6342 | The '``llvm.stacksave``' intrinsic is used to remember the current state |
| 6343 | of the function stack, for use with |
| 6344 | :ref:`llvm.stackrestore <int_stackrestore>`. This is useful for |
| 6345 | implementing language features like scoped automatic variable sized |
| 6346 | arrays in C99. |
| 6347 | |
| 6348 | Semantics: |
| 6349 | """""""""" |
| 6350 | |
| 6351 | This intrinsic returns a opaque pointer value that can be passed to |
| 6352 | :ref:`llvm.stackrestore <int_stackrestore>`. When an |
| 6353 | ``llvm.stackrestore`` intrinsic is executed with a value saved from |
| 6354 | ``llvm.stacksave``, it effectively restores the state of the stack to |
| 6355 | the state it was in when the ``llvm.stacksave`` intrinsic executed. In |
| 6356 | practice, this pops any :ref:`alloca <i_alloca>` blocks from the stack that |
| 6357 | were allocated after the ``llvm.stacksave`` was executed. |
| 6358 | |
| 6359 | .. _int_stackrestore: |
| 6360 | |
| 6361 | '``llvm.stackrestore``' Intrinsic |
| 6362 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6363 | |
| 6364 | Syntax: |
| 6365 | """"""" |
| 6366 | |
| 6367 | :: |
| 6368 | |
| 6369 | declare void @llvm.stackrestore(i8* %ptr) |
| 6370 | |
| 6371 | Overview: |
| 6372 | """"""""" |
| 6373 | |
| 6374 | The '``llvm.stackrestore``' intrinsic is used to restore the state of |
| 6375 | the function stack to the state it was in when the corresponding |
| 6376 | :ref:`llvm.stacksave <int_stacksave>` intrinsic executed. This is |
| 6377 | useful for implementing language features like scoped automatic variable |
| 6378 | sized arrays in C99. |
| 6379 | |
| 6380 | Semantics: |
| 6381 | """""""""" |
| 6382 | |
| 6383 | See the description for :ref:`llvm.stacksave <int_stacksave>`. |
| 6384 | |
| 6385 | '``llvm.prefetch``' Intrinsic |
| 6386 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6387 | |
| 6388 | Syntax: |
| 6389 | """"""" |
| 6390 | |
| 6391 | :: |
| 6392 | |
| 6393 | declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>) |
| 6394 | |
| 6395 | Overview: |
| 6396 | """"""""" |
| 6397 | |
| 6398 | The '``llvm.prefetch``' intrinsic is a hint to the code generator to |
| 6399 | insert a prefetch instruction if supported; otherwise, it is a noop. |
| 6400 | Prefetches have no effect on the behavior of the program but can change |
| 6401 | its performance characteristics. |
| 6402 | |
| 6403 | Arguments: |
| 6404 | """""""""" |
| 6405 | |
| 6406 | ``address`` is the address to be prefetched, ``rw`` is the specifier |
| 6407 | determining if the fetch should be for a read (0) or write (1), and |
| 6408 | ``locality`` is a temporal locality specifier ranging from (0) - no |
| 6409 | locality, to (3) - extremely local keep in cache. The ``cache type`` |
| 6410 | specifies whether the prefetch is performed on the data (1) or |
| 6411 | instruction (0) cache. The ``rw``, ``locality`` and ``cache type`` |
| 6412 | arguments must be constant integers. |
| 6413 | |
| 6414 | Semantics: |
| 6415 | """""""""" |
| 6416 | |
| 6417 | This intrinsic does not modify the behavior of the program. In |
| 6418 | particular, prefetches cannot trap and do not produce a value. On |
| 6419 | targets that support this intrinsic, the prefetch can provide hints to |
| 6420 | the processor cache for better performance. |
| 6421 | |
| 6422 | '``llvm.pcmarker``' Intrinsic |
| 6423 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6424 | |
| 6425 | Syntax: |
| 6426 | """"""" |
| 6427 | |
| 6428 | :: |
| 6429 | |
| 6430 | declare void @llvm.pcmarker(i32 <id>) |
| 6431 | |
| 6432 | Overview: |
| 6433 | """"""""" |
| 6434 | |
| 6435 | The '``llvm.pcmarker``' intrinsic is a method to export a Program |
| 6436 | Counter (PC) in a region of code to simulators and other tools. The |
| 6437 | method is target specific, but it is expected that the marker will use |
| 6438 | exported symbols to transmit the PC of the marker. The marker makes no |
| 6439 | guarantees that it will remain with any specific instruction after |
| 6440 | optimizations. It is possible that the presence of a marker will inhibit |
| 6441 | optimizations. The intended use is to be inserted after optimizations to |
| 6442 | allow correlations of simulation runs. |
| 6443 | |
| 6444 | Arguments: |
| 6445 | """""""""" |
| 6446 | |
| 6447 | ``id`` is a numerical id identifying the marker. |
| 6448 | |
| 6449 | Semantics: |
| 6450 | """""""""" |
| 6451 | |
| 6452 | This intrinsic does not modify the behavior of the program. Backends |
| 6453 | that do not support this intrinsic may ignore it. |
| 6454 | |
| 6455 | '``llvm.readcyclecounter``' Intrinsic |
| 6456 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6457 | |
| 6458 | Syntax: |
| 6459 | """"""" |
| 6460 | |
| 6461 | :: |
| 6462 | |
| 6463 | declare i64 @llvm.readcyclecounter() |
| 6464 | |
| 6465 | Overview: |
| 6466 | """"""""" |
| 6467 | |
| 6468 | The '``llvm.readcyclecounter``' intrinsic provides access to the cycle |
| 6469 | counter register (or similar low latency, high accuracy clocks) on those |
| 6470 | targets that support it. On X86, it should map to RDTSC. On Alpha, it |
| 6471 | should map to RPCC. As the backing counters overflow quickly (on the |
| 6472 | order of 9 seconds on alpha), this should only be used for small |
| 6473 | timings. |
| 6474 | |
| 6475 | Semantics: |
| 6476 | """""""""" |
| 6477 | |
| 6478 | When directly supported, reading the cycle counter should not modify any |
| 6479 | memory. Implementations are allowed to either return a application |
| 6480 | specific value or a system wide value. On backends without support, this |
| 6481 | is lowered to a constant 0. |
| 6482 | |
| 6483 | Standard C Library Intrinsics |
| 6484 | ----------------------------- |
| 6485 | |
| 6486 | LLVM provides intrinsics for a few important standard C library |
| 6487 | functions. These intrinsics allow source-language front-ends to pass |
| 6488 | information about the alignment of the pointer arguments to the code |
| 6489 | generator, providing opportunity for more efficient code generation. |
| 6490 | |
| 6491 | .. _int_memcpy: |
| 6492 | |
| 6493 | '``llvm.memcpy``' Intrinsic |
| 6494 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6495 | |
| 6496 | Syntax: |
| 6497 | """"""" |
| 6498 | |
| 6499 | This is an overloaded intrinsic. You can use ``llvm.memcpy`` on any |
| 6500 | integer bit width and for different address spaces. Not all targets |
| 6501 | support all bit widths however. |
| 6502 | |
| 6503 | :: |
| 6504 | |
| 6505 | declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>, |
| 6506 | i32 <len>, i32 <align>, i1 <isvolatile>) |
| 6507 | declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>, |
| 6508 | i64 <len>, i32 <align>, i1 <isvolatile>) |
| 6509 | |
| 6510 | Overview: |
| 6511 | """"""""" |
| 6512 | |
| 6513 | The '``llvm.memcpy.*``' intrinsics copy a block of memory from the |
| 6514 | source location to the destination location. |
| 6515 | |
| 6516 | Note that, unlike the standard libc function, the ``llvm.memcpy.*`` |
| 6517 | intrinsics do not return a value, takes extra alignment/isvolatile |
| 6518 | arguments and the pointers can be in specified address spaces. |
| 6519 | |
| 6520 | Arguments: |
| 6521 | """""""""" |
| 6522 | |
| 6523 | The first argument is a pointer to the destination, the second is a |
| 6524 | pointer to the source. The third argument is an integer argument |
| 6525 | specifying the number of bytes to copy, the fourth argument is the |
| 6526 | alignment of the source and destination locations, and the fifth is a |
| 6527 | boolean indicating a volatile access. |
| 6528 | |
| 6529 | If the call to this intrinsic has an alignment value that is not 0 or 1, |
| 6530 | then the caller guarantees that both the source and destination pointers |
| 6531 | are aligned to that boundary. |
| 6532 | |
| 6533 | If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy`` call is |
| 6534 | a :ref:`volatile operation <volatile>`. The detailed access behavior is not |
| 6535 | very cleanly specified and it is unwise to depend on it. |
| 6536 | |
| 6537 | Semantics: |
| 6538 | """""""""" |
| 6539 | |
| 6540 | The '``llvm.memcpy.*``' intrinsics copy a block of memory from the |
| 6541 | source location to the destination location, which are not allowed to |
| 6542 | overlap. It copies "len" bytes of memory over. If the argument is known |
| 6543 | to be aligned to some boundary, this can be specified as the fourth |
| 6544 | argument, otherwise it should be set to 0 or 1. |
| 6545 | |
| 6546 | '``llvm.memmove``' Intrinsic |
| 6547 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6548 | |
| 6549 | Syntax: |
| 6550 | """"""" |
| 6551 | |
| 6552 | This is an overloaded intrinsic. You can use llvm.memmove on any integer |
| 6553 | bit width and for different address space. Not all targets support all |
| 6554 | bit widths however. |
| 6555 | |
| 6556 | :: |
| 6557 | |
| 6558 | declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>, |
| 6559 | i32 <len>, i32 <align>, i1 <isvolatile>) |
| 6560 | declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>, |
| 6561 | i64 <len>, i32 <align>, i1 <isvolatile>) |
| 6562 | |
| 6563 | Overview: |
| 6564 | """"""""" |
| 6565 | |
| 6566 | The '``llvm.memmove.*``' intrinsics move a block of memory from the |
| 6567 | source location to the destination location. It is similar to the |
| 6568 | '``llvm.memcpy``' intrinsic but allows the two memory locations to |
| 6569 | overlap. |
| 6570 | |
| 6571 | Note that, unlike the standard libc function, the ``llvm.memmove.*`` |
| 6572 | intrinsics do not return a value, takes extra alignment/isvolatile |
| 6573 | arguments and the pointers can be in specified address spaces. |
| 6574 | |
| 6575 | Arguments: |
| 6576 | """""""""" |
| 6577 | |
| 6578 | The first argument is a pointer to the destination, the second is a |
| 6579 | pointer to the source. The third argument is an integer argument |
| 6580 | specifying the number of bytes to copy, the fourth argument is the |
| 6581 | alignment of the source and destination locations, and the fifth is a |
| 6582 | boolean indicating a volatile access. |
| 6583 | |
| 6584 | If the call to this intrinsic has an alignment value that is not 0 or 1, |
| 6585 | then the caller guarantees that the source and destination pointers are |
| 6586 | aligned to that boundary. |
| 6587 | |
| 6588 | If the ``isvolatile`` parameter is ``true``, the ``llvm.memmove`` call |
| 6589 | is a :ref:`volatile operation <volatile>`. The detailed access behavior is |
| 6590 | not very cleanly specified and it is unwise to depend on it. |
| 6591 | |
| 6592 | Semantics: |
| 6593 | """""""""" |
| 6594 | |
| 6595 | The '``llvm.memmove.*``' intrinsics copy a block of memory from the |
| 6596 | source location to the destination location, which may overlap. It |
| 6597 | copies "len" bytes of memory over. If the argument is known to be |
| 6598 | aligned to some boundary, this can be specified as the fourth argument, |
| 6599 | otherwise it should be set to 0 or 1. |
| 6600 | |
| 6601 | '``llvm.memset.*``' Intrinsics |
| 6602 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6603 | |
| 6604 | Syntax: |
| 6605 | """"""" |
| 6606 | |
| 6607 | This is an overloaded intrinsic. You can use llvm.memset on any integer |
| 6608 | bit width and for different address spaces. However, not all targets |
| 6609 | support all bit widths. |
| 6610 | |
| 6611 | :: |
| 6612 | |
| 6613 | declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>, |
| 6614 | i32 <len>, i32 <align>, i1 <isvolatile>) |
| 6615 | declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>, |
| 6616 | i64 <len>, i32 <align>, i1 <isvolatile>) |
| 6617 | |
| 6618 | Overview: |
| 6619 | """"""""" |
| 6620 | |
| 6621 | The '``llvm.memset.*``' intrinsics fill a block of memory with a |
| 6622 | particular byte value. |
| 6623 | |
| 6624 | Note that, unlike the standard libc function, the ``llvm.memset`` |
| 6625 | intrinsic does not return a value and takes extra alignment/volatile |
| 6626 | arguments. Also, the destination can be in an arbitrary address space. |
| 6627 | |
| 6628 | Arguments: |
| 6629 | """""""""" |
| 6630 | |
| 6631 | The first argument is a pointer to the destination to fill, the second |
| 6632 | is the byte value with which to fill it, the third argument is an |
| 6633 | integer argument specifying the number of bytes to fill, and the fourth |
| 6634 | argument is the known alignment of the destination location. |
| 6635 | |
| 6636 | If the call to this intrinsic has an alignment value that is not 0 or 1, |
| 6637 | then the caller guarantees that the destination pointer is aligned to |
| 6638 | that boundary. |
| 6639 | |
| 6640 | If the ``isvolatile`` parameter is ``true``, the ``llvm.memset`` call is |
| 6641 | a :ref:`volatile operation <volatile>`. The detailed access behavior is not |
| 6642 | very cleanly specified and it is unwise to depend on it. |
| 6643 | |
| 6644 | Semantics: |
| 6645 | """""""""" |
| 6646 | |
| 6647 | The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting |
| 6648 | at the destination location. If the argument is known to be aligned to |
| 6649 | some boundary, this can be specified as the fourth argument, otherwise |
| 6650 | it should be set to 0 or 1. |
| 6651 | |
| 6652 | '``llvm.sqrt.*``' Intrinsic |
| 6653 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6654 | |
| 6655 | Syntax: |
| 6656 | """"""" |
| 6657 | |
| 6658 | This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any |
| 6659 | floating point or vector of floating point type. Not all targets support |
| 6660 | all types however. |
| 6661 | |
| 6662 | :: |
| 6663 | |
| 6664 | declare float @llvm.sqrt.f32(float %Val) |
| 6665 | declare double @llvm.sqrt.f64(double %Val) |
| 6666 | declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val) |
| 6667 | declare fp128 @llvm.sqrt.f128(fp128 %Val) |
| 6668 | declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val) |
| 6669 | |
| 6670 | Overview: |
| 6671 | """"""""" |
| 6672 | |
| 6673 | The '``llvm.sqrt``' intrinsics return the sqrt of the specified operand, |
| 6674 | returning the same value as the libm '``sqrt``' functions would. Unlike |
| 6675 | ``sqrt`` in libm, however, ``llvm.sqrt`` has undefined behavior for |
| 6676 | negative numbers other than -0.0 (which allows for better optimization, |
| 6677 | because there is no need to worry about errno being set). |
| 6678 | ``llvm.sqrt(-0.0)`` is defined to return -0.0 like IEEE sqrt. |
| 6679 | |
| 6680 | Arguments: |
| 6681 | """""""""" |
| 6682 | |
| 6683 | The argument and return value are floating point numbers of the same |
| 6684 | type. |
| 6685 | |
| 6686 | Semantics: |
| 6687 | """""""""" |
| 6688 | |
| 6689 | This function returns the sqrt of the specified operand if it is a |
| 6690 | nonnegative floating point number. |
| 6691 | |
| 6692 | '``llvm.powi.*``' Intrinsic |
| 6693 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6694 | |
| 6695 | Syntax: |
| 6696 | """"""" |
| 6697 | |
| 6698 | This is an overloaded intrinsic. You can use ``llvm.powi`` on any |
| 6699 | floating point or vector of floating point type. Not all targets support |
| 6700 | all types however. |
| 6701 | |
| 6702 | :: |
| 6703 | |
| 6704 | declare float @llvm.powi.f32(float %Val, i32 %power) |
| 6705 | declare double @llvm.powi.f64(double %Val, i32 %power) |
| 6706 | declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power) |
| 6707 | declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power) |
| 6708 | declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power) |
| 6709 | |
| 6710 | Overview: |
| 6711 | """"""""" |
| 6712 | |
| 6713 | The '``llvm.powi.*``' intrinsics return the first operand raised to the |
| 6714 | specified (positive or negative) power. The order of evaluation of |
| 6715 | multiplications is not defined. When a vector of floating point type is |
| 6716 | used, the second argument remains a scalar integer value. |
| 6717 | |
| 6718 | Arguments: |
| 6719 | """""""""" |
| 6720 | |
| 6721 | The second argument is an integer power, and the first is a value to |
| 6722 | raise to that power. |
| 6723 | |
| 6724 | Semantics: |
| 6725 | """""""""" |
| 6726 | |
| 6727 | This function returns the first value raised to the second power with an |
| 6728 | unspecified sequence of rounding operations. |
| 6729 | |
| 6730 | '``llvm.sin.*``' Intrinsic |
| 6731 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6732 | |
| 6733 | Syntax: |
| 6734 | """"""" |
| 6735 | |
| 6736 | This is an overloaded intrinsic. You can use ``llvm.sin`` on any |
| 6737 | floating point or vector of floating point type. Not all targets support |
| 6738 | all types however. |
| 6739 | |
| 6740 | :: |
| 6741 | |
| 6742 | declare float @llvm.sin.f32(float %Val) |
| 6743 | declare double @llvm.sin.f64(double %Val) |
| 6744 | declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val) |
| 6745 | declare fp128 @llvm.sin.f128(fp128 %Val) |
| 6746 | declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val) |
| 6747 | |
| 6748 | Overview: |
| 6749 | """"""""" |
| 6750 | |
| 6751 | The '``llvm.sin.*``' intrinsics return the sine of the operand. |
| 6752 | |
| 6753 | Arguments: |
| 6754 | """""""""" |
| 6755 | |
| 6756 | The argument and return value are floating point numbers of the same |
| 6757 | type. |
| 6758 | |
| 6759 | Semantics: |
| 6760 | """""""""" |
| 6761 | |
| 6762 | This function returns the sine of the specified operand, returning the |
| 6763 | same values as the libm ``sin`` functions would, and handles error |
| 6764 | conditions in the same way. |
| 6765 | |
| 6766 | '``llvm.cos.*``' Intrinsic |
| 6767 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6768 | |
| 6769 | Syntax: |
| 6770 | """"""" |
| 6771 | |
| 6772 | This is an overloaded intrinsic. You can use ``llvm.cos`` on any |
| 6773 | floating point or vector of floating point type. Not all targets support |
| 6774 | all types however. |
| 6775 | |
| 6776 | :: |
| 6777 | |
| 6778 | declare float @llvm.cos.f32(float %Val) |
| 6779 | declare double @llvm.cos.f64(double %Val) |
| 6780 | declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val) |
| 6781 | declare fp128 @llvm.cos.f128(fp128 %Val) |
| 6782 | declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val) |
| 6783 | |
| 6784 | Overview: |
| 6785 | """"""""" |
| 6786 | |
| 6787 | The '``llvm.cos.*``' intrinsics return the cosine of the operand. |
| 6788 | |
| 6789 | Arguments: |
| 6790 | """""""""" |
| 6791 | |
| 6792 | The argument and return value are floating point numbers of the same |
| 6793 | type. |
| 6794 | |
| 6795 | Semantics: |
| 6796 | """""""""" |
| 6797 | |
| 6798 | This function returns the cosine of the specified operand, returning the |
| 6799 | same values as the libm ``cos`` functions would, and handles error |
| 6800 | conditions in the same way. |
| 6801 | |
| 6802 | '``llvm.pow.*``' Intrinsic |
| 6803 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6804 | |
| 6805 | Syntax: |
| 6806 | """"""" |
| 6807 | |
| 6808 | This is an overloaded intrinsic. You can use ``llvm.pow`` on any |
| 6809 | floating point or vector of floating point type. Not all targets support |
| 6810 | all types however. |
| 6811 | |
| 6812 | :: |
| 6813 | |
| 6814 | declare float @llvm.pow.f32(float %Val, float %Power) |
| 6815 | declare double @llvm.pow.f64(double %Val, double %Power) |
| 6816 | declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power) |
| 6817 | declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power) |
| 6818 | declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power) |
| 6819 | |
| 6820 | Overview: |
| 6821 | """"""""" |
| 6822 | |
| 6823 | The '``llvm.pow.*``' intrinsics return the first operand raised to the |
| 6824 | specified (positive or negative) power. |
| 6825 | |
| 6826 | Arguments: |
| 6827 | """""""""" |
| 6828 | |
| 6829 | The second argument is a floating point power, and the first is a value |
| 6830 | to raise to that power. |
| 6831 | |
| 6832 | Semantics: |
| 6833 | """""""""" |
| 6834 | |
| 6835 | This function returns the first value raised to the second power, |
| 6836 | returning the same values as the libm ``pow`` functions would, and |
| 6837 | handles error conditions in the same way. |
| 6838 | |
| 6839 | '``llvm.exp.*``' Intrinsic |
| 6840 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6841 | |
| 6842 | Syntax: |
| 6843 | """"""" |
| 6844 | |
| 6845 | This is an overloaded intrinsic. You can use ``llvm.exp`` on any |
| 6846 | floating point or vector of floating point type. Not all targets support |
| 6847 | all types however. |
| 6848 | |
| 6849 | :: |
| 6850 | |
| 6851 | declare float @llvm.exp.f32(float %Val) |
| 6852 | declare double @llvm.exp.f64(double %Val) |
| 6853 | declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val) |
| 6854 | declare fp128 @llvm.exp.f128(fp128 %Val) |
| 6855 | declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val) |
| 6856 | |
| 6857 | Overview: |
| 6858 | """"""""" |
| 6859 | |
| 6860 | The '``llvm.exp.*``' intrinsics perform the exp function. |
| 6861 | |
| 6862 | Arguments: |
| 6863 | """""""""" |
| 6864 | |
| 6865 | The argument and return value are floating point numbers of the same |
| 6866 | type. |
| 6867 | |
| 6868 | Semantics: |
| 6869 | """""""""" |
| 6870 | |
| 6871 | This function returns the same values as the libm ``exp`` functions |
| 6872 | would, and handles error conditions in the same way. |
| 6873 | |
| 6874 | '``llvm.exp2.*``' Intrinsic |
| 6875 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6876 | |
| 6877 | Syntax: |
| 6878 | """"""" |
| 6879 | |
| 6880 | This is an overloaded intrinsic. You can use ``llvm.exp2`` on any |
| 6881 | floating point or vector of floating point type. Not all targets support |
| 6882 | all types however. |
| 6883 | |
| 6884 | :: |
| 6885 | |
| 6886 | declare float @llvm.exp2.f32(float %Val) |
| 6887 | declare double @llvm.exp2.f64(double %Val) |
| 6888 | declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val) |
| 6889 | declare fp128 @llvm.exp2.f128(fp128 %Val) |
| 6890 | declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val) |
| 6891 | |
| 6892 | Overview: |
| 6893 | """"""""" |
| 6894 | |
| 6895 | The '``llvm.exp2.*``' intrinsics perform the exp2 function. |
| 6896 | |
| 6897 | Arguments: |
| 6898 | """""""""" |
| 6899 | |
| 6900 | The argument and return value are floating point numbers of the same |
| 6901 | type. |
| 6902 | |
| 6903 | Semantics: |
| 6904 | """""""""" |
| 6905 | |
| 6906 | This function returns the same values as the libm ``exp2`` functions |
| 6907 | would, and handles error conditions in the same way. |
| 6908 | |
| 6909 | '``llvm.log.*``' Intrinsic |
| 6910 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6911 | |
| 6912 | Syntax: |
| 6913 | """"""" |
| 6914 | |
| 6915 | This is an overloaded intrinsic. You can use ``llvm.log`` on any |
| 6916 | floating point or vector of floating point type. Not all targets support |
| 6917 | all types however. |
| 6918 | |
| 6919 | :: |
| 6920 | |
| 6921 | declare float @llvm.log.f32(float %Val) |
| 6922 | declare double @llvm.log.f64(double %Val) |
| 6923 | declare x86_fp80 @llvm.log.f80(x86_fp80 %Val) |
| 6924 | declare fp128 @llvm.log.f128(fp128 %Val) |
| 6925 | declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val) |
| 6926 | |
| 6927 | Overview: |
| 6928 | """"""""" |
| 6929 | |
| 6930 | The '``llvm.log.*``' intrinsics perform the log function. |
| 6931 | |
| 6932 | Arguments: |
| 6933 | """""""""" |
| 6934 | |
| 6935 | The argument and return value are floating point numbers of the same |
| 6936 | type. |
| 6937 | |
| 6938 | Semantics: |
| 6939 | """""""""" |
| 6940 | |
| 6941 | This function returns the same values as the libm ``log`` functions |
| 6942 | would, and handles error conditions in the same way. |
| 6943 | |
| 6944 | '``llvm.log10.*``' Intrinsic |
| 6945 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6946 | |
| 6947 | Syntax: |
| 6948 | """"""" |
| 6949 | |
| 6950 | This is an overloaded intrinsic. You can use ``llvm.log10`` on any |
| 6951 | floating point or vector of floating point type. Not all targets support |
| 6952 | all types however. |
| 6953 | |
| 6954 | :: |
| 6955 | |
| 6956 | declare float @llvm.log10.f32(float %Val) |
| 6957 | declare double @llvm.log10.f64(double %Val) |
| 6958 | declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val) |
| 6959 | declare fp128 @llvm.log10.f128(fp128 %Val) |
| 6960 | declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val) |
| 6961 | |
| 6962 | Overview: |
| 6963 | """"""""" |
| 6964 | |
| 6965 | The '``llvm.log10.*``' intrinsics perform the log10 function. |
| 6966 | |
| 6967 | Arguments: |
| 6968 | """""""""" |
| 6969 | |
| 6970 | The argument and return value are floating point numbers of the same |
| 6971 | type. |
| 6972 | |
| 6973 | Semantics: |
| 6974 | """""""""" |
| 6975 | |
| 6976 | This function returns the same values as the libm ``log10`` functions |
| 6977 | would, and handles error conditions in the same way. |
| 6978 | |
| 6979 | '``llvm.log2.*``' Intrinsic |
| 6980 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6981 | |
| 6982 | Syntax: |
| 6983 | """"""" |
| 6984 | |
| 6985 | This is an overloaded intrinsic. You can use ``llvm.log2`` on any |
| 6986 | floating point or vector of floating point type. Not all targets support |
| 6987 | all types however. |
| 6988 | |
| 6989 | :: |
| 6990 | |
| 6991 | declare float @llvm.log2.f32(float %Val) |
| 6992 | declare double @llvm.log2.f64(double %Val) |
| 6993 | declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val) |
| 6994 | declare fp128 @llvm.log2.f128(fp128 %Val) |
| 6995 | declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val) |
| 6996 | |
| 6997 | Overview: |
| 6998 | """"""""" |
| 6999 | |
| 7000 | The '``llvm.log2.*``' intrinsics perform the log2 function. |
| 7001 | |
| 7002 | Arguments: |
| 7003 | """""""""" |
| 7004 | |
| 7005 | The argument and return value are floating point numbers of the same |
| 7006 | type. |
| 7007 | |
| 7008 | Semantics: |
| 7009 | """""""""" |
| 7010 | |
| 7011 | This function returns the same values as the libm ``log2`` functions |
| 7012 | would, and handles error conditions in the same way. |
| 7013 | |
| 7014 | '``llvm.fma.*``' Intrinsic |
| 7015 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7016 | |
| 7017 | Syntax: |
| 7018 | """"""" |
| 7019 | |
| 7020 | This is an overloaded intrinsic. You can use ``llvm.fma`` on any |
| 7021 | floating point or vector of floating point type. Not all targets support |
| 7022 | all types however. |
| 7023 | |
| 7024 | :: |
| 7025 | |
| 7026 | declare float @llvm.fma.f32(float %a, float %b, float %c) |
| 7027 | declare double @llvm.fma.f64(double %a, double %b, double %c) |
| 7028 | declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c) |
| 7029 | declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c) |
| 7030 | declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c) |
| 7031 | |
| 7032 | Overview: |
| 7033 | """"""""" |
| 7034 | |
| 7035 | The '``llvm.fma.*``' intrinsics perform the fused multiply-add |
| 7036 | operation. |
| 7037 | |
| 7038 | Arguments: |
| 7039 | """""""""" |
| 7040 | |
| 7041 | The argument and return value are floating point numbers of the same |
| 7042 | type. |
| 7043 | |
| 7044 | Semantics: |
| 7045 | """""""""" |
| 7046 | |
| 7047 | This function returns the same values as the libm ``fma`` functions |
| 7048 | would. |
| 7049 | |
| 7050 | '``llvm.fabs.*``' Intrinsic |
| 7051 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7052 | |
| 7053 | Syntax: |
| 7054 | """"""" |
| 7055 | |
| 7056 | This is an overloaded intrinsic. You can use ``llvm.fabs`` on any |
| 7057 | floating point or vector of floating point type. Not all targets support |
| 7058 | all types however. |
| 7059 | |
| 7060 | :: |
| 7061 | |
| 7062 | declare float @llvm.fabs.f32(float %Val) |
| 7063 | declare double @llvm.fabs.f64(double %Val) |
| 7064 | declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val) |
| 7065 | declare fp128 @llvm.fabs.f128(fp128 %Val) |
| 7066 | declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val) |
| 7067 | |
| 7068 | Overview: |
| 7069 | """"""""" |
| 7070 | |
| 7071 | The '``llvm.fabs.*``' intrinsics return the absolute value of the |
| 7072 | operand. |
| 7073 | |
| 7074 | Arguments: |
| 7075 | """""""""" |
| 7076 | |
| 7077 | The argument and return value are floating point numbers of the same |
| 7078 | type. |
| 7079 | |
| 7080 | Semantics: |
| 7081 | """""""""" |
| 7082 | |
| 7083 | This function returns the same values as the libm ``fabs`` functions |
| 7084 | would, and handles error conditions in the same way. |
| 7085 | |
| 7086 | '``llvm.floor.*``' Intrinsic |
| 7087 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7088 | |
| 7089 | Syntax: |
| 7090 | """"""" |
| 7091 | |
| 7092 | This is an overloaded intrinsic. You can use ``llvm.floor`` on any |
| 7093 | floating point or vector of floating point type. Not all targets support |
| 7094 | all types however. |
| 7095 | |
| 7096 | :: |
| 7097 | |
| 7098 | declare float @llvm.floor.f32(float %Val) |
| 7099 | declare double @llvm.floor.f64(double %Val) |
| 7100 | declare x86_fp80 @llvm.floor.f80(x86_fp80 %Val) |
| 7101 | declare fp128 @llvm.floor.f128(fp128 %Val) |
| 7102 | declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128 %Val) |
| 7103 | |
| 7104 | Overview: |
| 7105 | """"""""" |
| 7106 | |
| 7107 | The '``llvm.floor.*``' intrinsics return the floor of the operand. |
| 7108 | |
| 7109 | Arguments: |
| 7110 | """""""""" |
| 7111 | |
| 7112 | The argument and return value are floating point numbers of the same |
| 7113 | type. |
| 7114 | |
| 7115 | Semantics: |
| 7116 | """""""""" |
| 7117 | |
| 7118 | This function returns the same values as the libm ``floor`` functions |
| 7119 | would, and handles error conditions in the same way. |
| 7120 | |
| 7121 | '``llvm.ceil.*``' Intrinsic |
| 7122 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7123 | |
| 7124 | Syntax: |
| 7125 | """"""" |
| 7126 | |
| 7127 | This is an overloaded intrinsic. You can use ``llvm.ceil`` on any |
| 7128 | floating point or vector of floating point type. Not all targets support |
| 7129 | all types however. |
| 7130 | |
| 7131 | :: |
| 7132 | |
| 7133 | declare float @llvm.ceil.f32(float %Val) |
| 7134 | declare double @llvm.ceil.f64(double %Val) |
| 7135 | declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val) |
| 7136 | declare fp128 @llvm.ceil.f128(fp128 %Val) |
| 7137 | declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val) |
| 7138 | |
| 7139 | Overview: |
| 7140 | """"""""" |
| 7141 | |
| 7142 | The '``llvm.ceil.*``' intrinsics return the ceiling of the operand. |
| 7143 | |
| 7144 | Arguments: |
| 7145 | """""""""" |
| 7146 | |
| 7147 | The argument and return value are floating point numbers of the same |
| 7148 | type. |
| 7149 | |
| 7150 | Semantics: |
| 7151 | """""""""" |
| 7152 | |
| 7153 | This function returns the same values as the libm ``ceil`` functions |
| 7154 | would, and handles error conditions in the same way. |
| 7155 | |
| 7156 | '``llvm.trunc.*``' Intrinsic |
| 7157 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7158 | |
| 7159 | Syntax: |
| 7160 | """"""" |
| 7161 | |
| 7162 | This is an overloaded intrinsic. You can use ``llvm.trunc`` on any |
| 7163 | floating point or vector of floating point type. Not all targets support |
| 7164 | all types however. |
| 7165 | |
| 7166 | :: |
| 7167 | |
| 7168 | declare float @llvm.trunc.f32(float %Val) |
| 7169 | declare double @llvm.trunc.f64(double %Val) |
| 7170 | declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val) |
| 7171 | declare fp128 @llvm.trunc.f128(fp128 %Val) |
| 7172 | declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val) |
| 7173 | |
| 7174 | Overview: |
| 7175 | """"""""" |
| 7176 | |
| 7177 | The '``llvm.trunc.*``' intrinsics returns the operand rounded to the |
| 7178 | nearest integer not larger in magnitude than the operand. |
| 7179 | |
| 7180 | Arguments: |
| 7181 | """""""""" |
| 7182 | |
| 7183 | The argument and return value are floating point numbers of the same |
| 7184 | type. |
| 7185 | |
| 7186 | Semantics: |
| 7187 | """""""""" |
| 7188 | |
| 7189 | This function returns the same values as the libm ``trunc`` functions |
| 7190 | would, and handles error conditions in the same way. |
| 7191 | |
| 7192 | '``llvm.rint.*``' Intrinsic |
| 7193 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7194 | |
| 7195 | Syntax: |
| 7196 | """"""" |
| 7197 | |
| 7198 | This is an overloaded intrinsic. You can use ``llvm.rint`` on any |
| 7199 | floating point or vector of floating point type. Not all targets support |
| 7200 | all types however. |
| 7201 | |
| 7202 | :: |
| 7203 | |
| 7204 | declare float @llvm.rint.f32(float %Val) |
| 7205 | declare double @llvm.rint.f64(double %Val) |
| 7206 | declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val) |
| 7207 | declare fp128 @llvm.rint.f128(fp128 %Val) |
| 7208 | declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val) |
| 7209 | |
| 7210 | Overview: |
| 7211 | """"""""" |
| 7212 | |
| 7213 | The '``llvm.rint.*``' intrinsics returns the operand rounded to the |
| 7214 | nearest integer. It may raise an inexact floating-point exception if the |
| 7215 | operand isn't an integer. |
| 7216 | |
| 7217 | Arguments: |
| 7218 | """""""""" |
| 7219 | |
| 7220 | The argument and return value are floating point numbers of the same |
| 7221 | type. |
| 7222 | |
| 7223 | Semantics: |
| 7224 | """""""""" |
| 7225 | |
| 7226 | This function returns the same values as the libm ``rint`` functions |
| 7227 | would, and handles error conditions in the same way. |
| 7228 | |
| 7229 | '``llvm.nearbyint.*``' Intrinsic |
| 7230 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7231 | |
| 7232 | Syntax: |
| 7233 | """"""" |
| 7234 | |
| 7235 | This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any |
| 7236 | floating point or vector of floating point type. Not all targets support |
| 7237 | all types however. |
| 7238 | |
| 7239 | :: |
| 7240 | |
| 7241 | declare float @llvm.nearbyint.f32(float %Val) |
| 7242 | declare double @llvm.nearbyint.f64(double %Val) |
| 7243 | declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val) |
| 7244 | declare fp128 @llvm.nearbyint.f128(fp128 %Val) |
| 7245 | declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val) |
| 7246 | |
| 7247 | Overview: |
| 7248 | """"""""" |
| 7249 | |
| 7250 | The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the |
| 7251 | nearest integer. |
| 7252 | |
| 7253 | Arguments: |
| 7254 | """""""""" |
| 7255 | |
| 7256 | The argument and return value are floating point numbers of the same |
| 7257 | type. |
| 7258 | |
| 7259 | Semantics: |
| 7260 | """""""""" |
| 7261 | |
| 7262 | This function returns the same values as the libm ``nearbyint`` |
| 7263 | functions would, and handles error conditions in the same way. |
| 7264 | |
| 7265 | Bit Manipulation Intrinsics |
| 7266 | --------------------------- |
| 7267 | |
| 7268 | LLVM provides intrinsics for a few important bit manipulation |
| 7269 | operations. These allow efficient code generation for some algorithms. |
| 7270 | |
| 7271 | '``llvm.bswap.*``' Intrinsics |
| 7272 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7273 | |
| 7274 | Syntax: |
| 7275 | """"""" |
| 7276 | |
| 7277 | This is an overloaded intrinsic function. You can use bswap on any |
| 7278 | integer type that is an even number of bytes (i.e. BitWidth % 16 == 0). |
| 7279 | |
| 7280 | :: |
| 7281 | |
| 7282 | declare i16 @llvm.bswap.i16(i16 <id>) |
| 7283 | declare i32 @llvm.bswap.i32(i32 <id>) |
| 7284 | declare i64 @llvm.bswap.i64(i64 <id>) |
| 7285 | |
| 7286 | Overview: |
| 7287 | """"""""" |
| 7288 | |
| 7289 | The '``llvm.bswap``' family of intrinsics is used to byte swap integer |
| 7290 | values with an even number of bytes (positive multiple of 16 bits). |
| 7291 | These are useful for performing operations on data that is not in the |
| 7292 | target's native byte order. |
| 7293 | |
| 7294 | Semantics: |
| 7295 | """""""""" |
| 7296 | |
| 7297 | The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high |
| 7298 | and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32`` |
| 7299 | intrinsic returns an i32 value that has the four bytes of the input i32 |
| 7300 | swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the |
| 7301 | returned i32 will have its bytes in 3, 2, 1, 0 order. The |
| 7302 | ``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this |
| 7303 | concept to additional even-byte lengths (6 bytes, 8 bytes and more, |
| 7304 | respectively). |
| 7305 | |
| 7306 | '``llvm.ctpop.*``' Intrinsic |
| 7307 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7308 | |
| 7309 | Syntax: |
| 7310 | """"""" |
| 7311 | |
| 7312 | This is an overloaded intrinsic. You can use llvm.ctpop on any integer |
| 7313 | bit width, or on any vector with integer elements. Not all targets |
| 7314 | support all bit widths or vector types, however. |
| 7315 | |
| 7316 | :: |
| 7317 | |
| 7318 | declare i8 @llvm.ctpop.i8(i8 <src>) |
| 7319 | declare i16 @llvm.ctpop.i16(i16 <src>) |
| 7320 | declare i32 @llvm.ctpop.i32(i32 <src>) |
| 7321 | declare i64 @llvm.ctpop.i64(i64 <src>) |
| 7322 | declare i256 @llvm.ctpop.i256(i256 <src>) |
| 7323 | declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>) |
| 7324 | |
| 7325 | Overview: |
| 7326 | """"""""" |
| 7327 | |
| 7328 | The '``llvm.ctpop``' family of intrinsics counts the number of bits set |
| 7329 | in a value. |
| 7330 | |
| 7331 | Arguments: |
| 7332 | """""""""" |
| 7333 | |
| 7334 | The only argument is the value to be counted. The argument may be of any |
| 7335 | integer type, or a vector with integer elements. The return type must |
| 7336 | match the argument type. |
| 7337 | |
| 7338 | Semantics: |
| 7339 | """""""""" |
| 7340 | |
| 7341 | The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within |
| 7342 | each element of a vector. |
| 7343 | |
| 7344 | '``llvm.ctlz.*``' Intrinsic |
| 7345 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7346 | |
| 7347 | Syntax: |
| 7348 | """"""" |
| 7349 | |
| 7350 | This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any |
| 7351 | integer bit width, or any vector whose elements are integers. Not all |
| 7352 | targets support all bit widths or vector types, however. |
| 7353 | |
| 7354 | :: |
| 7355 | |
| 7356 | declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>) |
| 7357 | declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>) |
| 7358 | declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>) |
| 7359 | declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>) |
| 7360 | declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>) |
| 7361 | declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>) |
| 7362 | |
| 7363 | Overview: |
| 7364 | """"""""" |
| 7365 | |
| 7366 | The '``llvm.ctlz``' family of intrinsic functions counts the number of |
| 7367 | leading zeros in a variable. |
| 7368 | |
| 7369 | Arguments: |
| 7370 | """""""""" |
| 7371 | |
| 7372 | The first argument is the value to be counted. This argument may be of |
| 7373 | any integer type, or a vectory with integer element type. The return |
| 7374 | type must match the first argument type. |
| 7375 | |
| 7376 | The second argument must be a constant and is a flag to indicate whether |
| 7377 | the intrinsic should ensure that a zero as the first argument produces a |
| 7378 | defined result. Historically some architectures did not provide a |
| 7379 | defined result for zero values as efficiently, and many algorithms are |
| 7380 | now predicated on avoiding zero-value inputs. |
| 7381 | |
| 7382 | Semantics: |
| 7383 | """""""""" |
| 7384 | |
| 7385 | The '``llvm.ctlz``' intrinsic counts the leading (most significant) |
| 7386 | zeros in a variable, or within each element of the vector. If |
| 7387 | ``src == 0`` then the result is the size in bits of the type of ``src`` |
| 7388 | if ``is_zero_undef == 0`` and ``undef`` otherwise. For example, |
| 7389 | ``llvm.ctlz(i32 2) = 30``. |
| 7390 | |
| 7391 | '``llvm.cttz.*``' Intrinsic |
| 7392 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7393 | |
| 7394 | Syntax: |
| 7395 | """"""" |
| 7396 | |
| 7397 | This is an overloaded intrinsic. You can use ``llvm.cttz`` on any |
| 7398 | integer bit width, or any vector of integer elements. Not all targets |
| 7399 | support all bit widths or vector types, however. |
| 7400 | |
| 7401 | :: |
| 7402 | |
| 7403 | declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>) |
| 7404 | declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>) |
| 7405 | declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>) |
| 7406 | declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>) |
| 7407 | declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>) |
| 7408 | declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>) |
| 7409 | |
| 7410 | Overview: |
| 7411 | """"""""" |
| 7412 | |
| 7413 | The '``llvm.cttz``' family of intrinsic functions counts the number of |
| 7414 | trailing zeros. |
| 7415 | |
| 7416 | Arguments: |
| 7417 | """""""""" |
| 7418 | |
| 7419 | The first argument is the value to be counted. This argument may be of |
| 7420 | any integer type, or a vectory with integer element type. The return |
| 7421 | type must match the first argument type. |
| 7422 | |
| 7423 | The second argument must be a constant and is a flag to indicate whether |
| 7424 | the intrinsic should ensure that a zero as the first argument produces a |
| 7425 | defined result. Historically some architectures did not provide a |
| 7426 | defined result for zero values as efficiently, and many algorithms are |
| 7427 | now predicated on avoiding zero-value inputs. |
| 7428 | |
| 7429 | Semantics: |
| 7430 | """""""""" |
| 7431 | |
| 7432 | The '``llvm.cttz``' intrinsic counts the trailing (least significant) |
| 7433 | zeros in a variable, or within each element of a vector. If ``src == 0`` |
| 7434 | then the result is the size in bits of the type of ``src`` if |
| 7435 | ``is_zero_undef == 0`` and ``undef`` otherwise. For example, |
| 7436 | ``llvm.cttz(2) = 1``. |
| 7437 | |
| 7438 | Arithmetic with Overflow Intrinsics |
| 7439 | ----------------------------------- |
| 7440 | |
| 7441 | LLVM provides intrinsics for some arithmetic with overflow operations. |
| 7442 | |
| 7443 | '``llvm.sadd.with.overflow.*``' Intrinsics |
| 7444 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7445 | |
| 7446 | Syntax: |
| 7447 | """"""" |
| 7448 | |
| 7449 | This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow`` |
| 7450 | on any integer bit width. |
| 7451 | |
| 7452 | :: |
| 7453 | |
| 7454 | declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b) |
| 7455 | declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) |
| 7456 | declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b) |
| 7457 | |
| 7458 | Overview: |
| 7459 | """"""""" |
| 7460 | |
| 7461 | The '``llvm.sadd.with.overflow``' family of intrinsic functions perform |
| 7462 | a signed addition of the two arguments, and indicate whether an overflow |
| 7463 | occurred during the signed summation. |
| 7464 | |
| 7465 | Arguments: |
| 7466 | """""""""" |
| 7467 | |
| 7468 | The arguments (%a and %b) and the first element of the result structure |
| 7469 | may be of integer types of any bit width, but they must have the same |
| 7470 | bit width. The second element of the result structure must be of type |
| 7471 | ``i1``. ``%a`` and ``%b`` are the two values that will undergo signed |
| 7472 | addition. |
| 7473 | |
| 7474 | Semantics: |
| 7475 | """""""""" |
| 7476 | |
| 7477 | The '``llvm.sadd.with.overflow``' family of intrinsic functions perform |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 7478 | a signed addition of the two variables. They return a structure --- the |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 7479 | first element of which is the signed summation, and the second element |
| 7480 | of which is a bit specifying if the signed summation resulted in an |
| 7481 | overflow. |
| 7482 | |
| 7483 | Examples: |
| 7484 | """"""""" |
| 7485 | |
| 7486 | .. code-block:: llvm |
| 7487 | |
| 7488 | %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b) |
| 7489 | %sum = extractvalue {i32, i1} %res, 0 |
| 7490 | %obit = extractvalue {i32, i1} %res, 1 |
| 7491 | br i1 %obit, label %overflow, label %normal |
| 7492 | |
| 7493 | '``llvm.uadd.with.overflow.*``' Intrinsics |
| 7494 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7495 | |
| 7496 | Syntax: |
| 7497 | """"""" |
| 7498 | |
| 7499 | This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow`` |
| 7500 | on any integer bit width. |
| 7501 | |
| 7502 | :: |
| 7503 | |
| 7504 | declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b) |
| 7505 | declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) |
| 7506 | declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b) |
| 7507 | |
| 7508 | Overview: |
| 7509 | """"""""" |
| 7510 | |
| 7511 | The '``llvm.uadd.with.overflow``' family of intrinsic functions perform |
| 7512 | an unsigned addition of the two arguments, and indicate whether a carry |
| 7513 | occurred during the unsigned summation. |
| 7514 | |
| 7515 | Arguments: |
| 7516 | """""""""" |
| 7517 | |
| 7518 | The arguments (%a and %b) and the first element of the result structure |
| 7519 | may be of integer types of any bit width, but they must have the same |
| 7520 | bit width. The second element of the result structure must be of type |
| 7521 | ``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned |
| 7522 | addition. |
| 7523 | |
| 7524 | Semantics: |
| 7525 | """""""""" |
| 7526 | |
| 7527 | The '``llvm.uadd.with.overflow``' family of intrinsic functions perform |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 7528 | an unsigned addition of the two arguments. They return a structure --- the |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 7529 | first element of which is the sum, and the second element of which is a |
| 7530 | bit specifying if the unsigned summation resulted in a carry. |
| 7531 | |
| 7532 | Examples: |
| 7533 | """"""""" |
| 7534 | |
| 7535 | .. code-block:: llvm |
| 7536 | |
| 7537 | %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b) |
| 7538 | %sum = extractvalue {i32, i1} %res, 0 |
| 7539 | %obit = extractvalue {i32, i1} %res, 1 |
| 7540 | br i1 %obit, label %carry, label %normal |
| 7541 | |
| 7542 | '``llvm.ssub.with.overflow.*``' Intrinsics |
| 7543 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7544 | |
| 7545 | Syntax: |
| 7546 | """"""" |
| 7547 | |
| 7548 | This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow`` |
| 7549 | on any integer bit width. |
| 7550 | |
| 7551 | :: |
| 7552 | |
| 7553 | declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b) |
| 7554 | declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) |
| 7555 | declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b) |
| 7556 | |
| 7557 | Overview: |
| 7558 | """"""""" |
| 7559 | |
| 7560 | The '``llvm.ssub.with.overflow``' family of intrinsic functions perform |
| 7561 | a signed subtraction of the two arguments, and indicate whether an |
| 7562 | overflow occurred during the signed subtraction. |
| 7563 | |
| 7564 | Arguments: |
| 7565 | """""""""" |
| 7566 | |
| 7567 | The arguments (%a and %b) and the first element of the result structure |
| 7568 | may be of integer types of any bit width, but they must have the same |
| 7569 | bit width. The second element of the result structure must be of type |
| 7570 | ``i1``. ``%a`` and ``%b`` are the two values that will undergo signed |
| 7571 | subtraction. |
| 7572 | |
| 7573 | Semantics: |
| 7574 | """""""""" |
| 7575 | |
| 7576 | The '``llvm.ssub.with.overflow``' family of intrinsic functions perform |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 7577 | a signed subtraction of the two arguments. They return a structure --- the |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 7578 | first element of which is the subtraction, and the second element of |
| 7579 | which is a bit specifying if the signed subtraction resulted in an |
| 7580 | overflow. |
| 7581 | |
| 7582 | Examples: |
| 7583 | """"""""" |
| 7584 | |
| 7585 | .. code-block:: llvm |
| 7586 | |
| 7587 | %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b) |
| 7588 | %sum = extractvalue {i32, i1} %res, 0 |
| 7589 | %obit = extractvalue {i32, i1} %res, 1 |
| 7590 | br i1 %obit, label %overflow, label %normal |
| 7591 | |
| 7592 | '``llvm.usub.with.overflow.*``' Intrinsics |
| 7593 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7594 | |
| 7595 | Syntax: |
| 7596 | """"""" |
| 7597 | |
| 7598 | This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow`` |
| 7599 | on any integer bit width. |
| 7600 | |
| 7601 | :: |
| 7602 | |
| 7603 | declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b) |
| 7604 | declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) |
| 7605 | declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b) |
| 7606 | |
| 7607 | Overview: |
| 7608 | """"""""" |
| 7609 | |
| 7610 | The '``llvm.usub.with.overflow``' family of intrinsic functions perform |
| 7611 | an unsigned subtraction of the two arguments, and indicate whether an |
| 7612 | overflow occurred during the unsigned subtraction. |
| 7613 | |
| 7614 | Arguments: |
| 7615 | """""""""" |
| 7616 | |
| 7617 | The arguments (%a and %b) and the first element of the result structure |
| 7618 | may be of integer types of any bit width, but they must have the same |
| 7619 | bit width. The second element of the result structure must be of type |
| 7620 | ``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned |
| 7621 | subtraction. |
| 7622 | |
| 7623 | Semantics: |
| 7624 | """""""""" |
| 7625 | |
| 7626 | The '``llvm.usub.with.overflow``' family of intrinsic functions perform |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 7627 | an unsigned subtraction of the two arguments. They return a structure --- |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 7628 | the first element of which is the subtraction, and the second element of |
| 7629 | which is a bit specifying if the unsigned subtraction resulted in an |
| 7630 | overflow. |
| 7631 | |
| 7632 | Examples: |
| 7633 | """"""""" |
| 7634 | |
| 7635 | .. code-block:: llvm |
| 7636 | |
| 7637 | %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b) |
| 7638 | %sum = extractvalue {i32, i1} %res, 0 |
| 7639 | %obit = extractvalue {i32, i1} %res, 1 |
| 7640 | br i1 %obit, label %overflow, label %normal |
| 7641 | |
| 7642 | '``llvm.smul.with.overflow.*``' Intrinsics |
| 7643 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7644 | |
| 7645 | Syntax: |
| 7646 | """"""" |
| 7647 | |
| 7648 | This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow`` |
| 7649 | on any integer bit width. |
| 7650 | |
| 7651 | :: |
| 7652 | |
| 7653 | declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b) |
| 7654 | declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) |
| 7655 | declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b) |
| 7656 | |
| 7657 | Overview: |
| 7658 | """"""""" |
| 7659 | |
| 7660 | The '``llvm.smul.with.overflow``' family of intrinsic functions perform |
| 7661 | a signed multiplication of the two arguments, and indicate whether an |
| 7662 | overflow occurred during the signed multiplication. |
| 7663 | |
| 7664 | Arguments: |
| 7665 | """""""""" |
| 7666 | |
| 7667 | The arguments (%a and %b) and the first element of the result structure |
| 7668 | may be of integer types of any bit width, but they must have the same |
| 7669 | bit width. The second element of the result structure must be of type |
| 7670 | ``i1``. ``%a`` and ``%b`` are the two values that will undergo signed |
| 7671 | multiplication. |
| 7672 | |
| 7673 | Semantics: |
| 7674 | """""""""" |
| 7675 | |
| 7676 | The '``llvm.smul.with.overflow``' family of intrinsic functions perform |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 7677 | a signed multiplication of the two arguments. They return a structure --- |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 7678 | the first element of which is the multiplication, and the second element |
| 7679 | of which is a bit specifying if the signed multiplication resulted in an |
| 7680 | overflow. |
| 7681 | |
| 7682 | Examples: |
| 7683 | """"""""" |
| 7684 | |
| 7685 | .. code-block:: llvm |
| 7686 | |
| 7687 | %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b) |
| 7688 | %sum = extractvalue {i32, i1} %res, 0 |
| 7689 | %obit = extractvalue {i32, i1} %res, 1 |
| 7690 | br i1 %obit, label %overflow, label %normal |
| 7691 | |
| 7692 | '``llvm.umul.with.overflow.*``' Intrinsics |
| 7693 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7694 | |
| 7695 | Syntax: |
| 7696 | """"""" |
| 7697 | |
| 7698 | This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow`` |
| 7699 | on any integer bit width. |
| 7700 | |
| 7701 | :: |
| 7702 | |
| 7703 | declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b) |
| 7704 | declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) |
| 7705 | declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b) |
| 7706 | |
| 7707 | Overview: |
| 7708 | """"""""" |
| 7709 | |
| 7710 | The '``llvm.umul.with.overflow``' family of intrinsic functions perform |
| 7711 | a unsigned multiplication of the two arguments, and indicate whether an |
| 7712 | overflow occurred during the unsigned multiplication. |
| 7713 | |
| 7714 | Arguments: |
| 7715 | """""""""" |
| 7716 | |
| 7717 | The arguments (%a and %b) and the first element of the result structure |
| 7718 | may be of integer types of any bit width, but they must have the same |
| 7719 | bit width. The second element of the result structure must be of type |
| 7720 | ``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned |
| 7721 | multiplication. |
| 7722 | |
| 7723 | Semantics: |
| 7724 | """""""""" |
| 7725 | |
| 7726 | The '``llvm.umul.with.overflow``' family of intrinsic functions perform |
Dmitri Gribenko | ae4a9ae | 2013-01-19 20:34:20 +0000 | [diff] [blame] | 7727 | an unsigned multiplication of the two arguments. They return a structure --- |
| 7728 | the first element of which is the multiplication, and the second |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 7729 | element of which is a bit specifying if the unsigned multiplication |
| 7730 | resulted in an overflow. |
| 7731 | |
| 7732 | Examples: |
| 7733 | """"""""" |
| 7734 | |
| 7735 | .. code-block:: llvm |
| 7736 | |
| 7737 | %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b) |
| 7738 | %sum = extractvalue {i32, i1} %res, 0 |
| 7739 | %obit = extractvalue {i32, i1} %res, 1 |
| 7740 | br i1 %obit, label %overflow, label %normal |
| 7741 | |
| 7742 | Specialised Arithmetic Intrinsics |
| 7743 | --------------------------------- |
| 7744 | |
| 7745 | '``llvm.fmuladd.*``' Intrinsic |
| 7746 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7747 | |
| 7748 | Syntax: |
| 7749 | """"""" |
| 7750 | |
| 7751 | :: |
| 7752 | |
| 7753 | declare float @llvm.fmuladd.f32(float %a, float %b, float %c) |
| 7754 | declare double @llvm.fmuladd.f64(double %a, double %b, double %c) |
| 7755 | |
| 7756 | Overview: |
| 7757 | """"""""" |
| 7758 | |
| 7759 | The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add |
Lang Hames | b0ec16b | 2013-01-17 00:00:49 +0000 | [diff] [blame] | 7760 | expressions that can be fused if the code generator determines that (a) the |
| 7761 | target instruction set has support for a fused operation, and (b) that the |
| 7762 | fused operation is more efficient than the equivalent, separate pair of mul |
| 7763 | and add instructions. |
Sean Silva | f722b00 | 2012-12-07 10:36:55 +0000 | [diff] [blame] | 7764 | |
| 7765 | Arguments: |
| 7766 | """""""""" |
| 7767 | |
| 7768 | The '``llvm.fmuladd.*``' intrinsics each take three arguments: two |
| 7769 | multiplicands, a and b, and an addend c. |
| 7770 | |
| 7771 | Semantics: |
| 7772 | """""""""" |
| 7773 | |
| 7774 | The expression: |
| 7775 | |
| 7776 | :: |
| 7777 | |
| 7778 | %0 = call float @llvm.fmuladd.f32(%a, %b, %c) |
| 7779 | |
| 7780 | is equivalent to the expression a \* b + c, except that rounding will |
| 7781 | not be performed between the multiplication and addition steps if the |
| 7782 | code generator fuses the operations. Fusion is not guaranteed, even if |
| 7783 | the target platform supports it. If a fused multiply-add is required the |
| 7784 | corresponding llvm.fma.\* intrinsic function should be used instead. |
| 7785 | |
| 7786 | Examples: |
| 7787 | """"""""" |
| 7788 | |
| 7789 | .. code-block:: llvm |
| 7790 | |
| 7791 | %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields {float}:r2 = (a * b) + c |
| 7792 | |
| 7793 | Half Precision Floating Point Intrinsics |
| 7794 | ---------------------------------------- |
| 7795 | |
| 7796 | For most target platforms, half precision floating point is a |
| 7797 | storage-only format. This means that it is a dense encoding (in memory) |
| 7798 | but does not support computation in the format. |
| 7799 | |
| 7800 | This means that code must first load the half-precision floating point |
| 7801 | value as an i16, then convert it to float with |
| 7802 | :ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can |
| 7803 | then be performed on the float value (including extending to double |
| 7804 | etc). To store the value back to memory, it is first converted to float |
| 7805 | if needed, then converted to i16 with |
| 7806 | :ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an |
| 7807 | i16 value. |
| 7808 | |
| 7809 | .. _int_convert_to_fp16: |
| 7810 | |
| 7811 | '``llvm.convert.to.fp16``' Intrinsic |
| 7812 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7813 | |
| 7814 | Syntax: |
| 7815 | """"""" |
| 7816 | |
| 7817 | :: |
| 7818 | |
| 7819 | declare i16 @llvm.convert.to.fp16(f32 %a) |
| 7820 | |
| 7821 | Overview: |
| 7822 | """"""""" |
| 7823 | |
| 7824 | The '``llvm.convert.to.fp16``' intrinsic function performs a conversion |
| 7825 | from single precision floating point format to half precision floating |
| 7826 | point format. |
| 7827 | |
| 7828 | Arguments: |
| 7829 | """""""""" |
| 7830 | |
| 7831 | The intrinsic function contains single argument - the value to be |
| 7832 | converted. |
| 7833 | |
| 7834 | Semantics: |
| 7835 | """""""""" |
| 7836 | |
| 7837 | The '``llvm.convert.to.fp16``' intrinsic function performs a conversion |
| 7838 | from single precision floating point format to half precision floating |
| 7839 | point format. The return value is an ``i16`` which contains the |
| 7840 | converted number. |
| 7841 | |
| 7842 | Examples: |
| 7843 | """"""""" |
| 7844 | |
| 7845 | .. code-block:: llvm |
| 7846 | |
| 7847 | %res = call i16 @llvm.convert.to.fp16(f32 %a) |
| 7848 | store i16 %res, i16* @x, align 2 |
| 7849 | |
| 7850 | .. _int_convert_from_fp16: |
| 7851 | |
| 7852 | '``llvm.convert.from.fp16``' Intrinsic |
| 7853 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7854 | |
| 7855 | Syntax: |
| 7856 | """"""" |
| 7857 | |
| 7858 | :: |
| 7859 | |
| 7860 | declare f32 @llvm.convert.from.fp16(i16 %a) |
| 7861 | |
| 7862 | Overview: |
| 7863 | """"""""" |
| 7864 | |
| 7865 | The '``llvm.convert.from.fp16``' intrinsic function performs a |
| 7866 | conversion from half precision floating point format to single precision |
| 7867 | floating point format. |
| 7868 | |
| 7869 | Arguments: |
| 7870 | """""""""" |
| 7871 | |
| 7872 | The intrinsic function contains single argument - the value to be |
| 7873 | converted. |
| 7874 | |
| 7875 | Semantics: |
| 7876 | """""""""" |
| 7877 | |
| 7878 | The '``llvm.convert.from.fp16``' intrinsic function performs a |
| 7879 | conversion from half single precision floating point format to single |
| 7880 | precision floating point format. The input half-float value is |
| 7881 | represented by an ``i16`` value. |
| 7882 | |
| 7883 | Examples: |
| 7884 | """"""""" |
| 7885 | |
| 7886 | .. code-block:: llvm |
| 7887 | |
| 7888 | %a = load i16* @x, align 2 |
| 7889 | %res = call f32 @llvm.convert.from.fp16(i16 %a) |
| 7890 | |
| 7891 | Debugger Intrinsics |
| 7892 | ------------------- |
| 7893 | |
| 7894 | The LLVM debugger intrinsics (which all start with ``llvm.dbg.`` |
| 7895 | prefix), are described in the `LLVM Source Level |
| 7896 | Debugging <SourceLevelDebugging.html#format_common_intrinsics>`_ |
| 7897 | document. |
| 7898 | |
| 7899 | Exception Handling Intrinsics |
| 7900 | ----------------------------- |
| 7901 | |
| 7902 | The LLVM exception handling intrinsics (which all start with |
| 7903 | ``llvm.eh.`` prefix), are described in the `LLVM Exception |
| 7904 | Handling <ExceptionHandling.html#format_common_intrinsics>`_ document. |
| 7905 | |
| 7906 | .. _int_trampoline: |
| 7907 | |
| 7908 | Trampoline Intrinsics |
| 7909 | --------------------- |
| 7910 | |
| 7911 | These intrinsics make it possible to excise one parameter, marked with |
| 7912 | the :ref:`nest <nest>` attribute, from a function. The result is a |
| 7913 | callable function pointer lacking the nest parameter - the caller does |
| 7914 | not need to provide a value for it. Instead, the value to use is stored |
| 7915 | in advance in a "trampoline", a block of memory usually allocated on the |
| 7916 | stack, which also contains code to splice the nest value into the |
| 7917 | argument list. This is used to implement the GCC nested function address |
| 7918 | extension. |
| 7919 | |
| 7920 | For example, if the function is ``i32 f(i8* nest %c, i32 %x, i32 %y)`` |
| 7921 | then the resulting function pointer has signature ``i32 (i32, i32)*``. |
| 7922 | It can be created as follows: |
| 7923 | |
| 7924 | .. code-block:: llvm |
| 7925 | |
| 7926 | %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86 |
| 7927 | %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0 |
| 7928 | call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval) |
| 7929 | %p = call i8* @llvm.adjust.trampoline(i8* %tramp1) |
| 7930 | %fp = bitcast i8* %p to i32 (i32, i32)* |
| 7931 | |
| 7932 | The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to |
| 7933 | ``%val = call i32 %f(i8* %nval, i32 %x, i32 %y)``. |
| 7934 | |
| 7935 | .. _int_it: |
| 7936 | |
| 7937 | '``llvm.init.trampoline``' Intrinsic |
| 7938 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7939 | |
| 7940 | Syntax: |
| 7941 | """"""" |
| 7942 | |
| 7943 | :: |
| 7944 | |
| 7945 | declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>) |
| 7946 | |
| 7947 | Overview: |
| 7948 | """"""""" |
| 7949 | |
| 7950 | This fills the memory pointed to by ``tramp`` with executable code, |
| 7951 | turning it into a trampoline. |
| 7952 | |
| 7953 | Arguments: |
| 7954 | """""""""" |
| 7955 | |
| 7956 | The ``llvm.init.trampoline`` intrinsic takes three arguments, all |
| 7957 | pointers. The ``tramp`` argument must point to a sufficiently large and |
| 7958 | sufficiently aligned block of memory; this memory is written to by the |
| 7959 | intrinsic. Note that the size and the alignment are target-specific - |
| 7960 | LLVM currently provides no portable way of determining them, so a |
| 7961 | front-end that generates this intrinsic needs to have some |
| 7962 | target-specific knowledge. The ``func`` argument must hold a function |
| 7963 | bitcast to an ``i8*``. |
| 7964 | |
| 7965 | Semantics: |
| 7966 | """""""""" |
| 7967 | |
| 7968 | The block of memory pointed to by ``tramp`` is filled with target |
| 7969 | dependent code, turning it into a function. Then ``tramp`` needs to be |
| 7970 | passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can |
| 7971 | be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new |
| 7972 | function's signature is the same as that of ``func`` with any arguments |
| 7973 | marked with the ``nest`` attribute removed. At most one such ``nest`` |
| 7974 | argument is allowed, and it must be of pointer type. Calling the new |
| 7975 | function is equivalent to calling ``func`` with the same argument list, |
| 7976 | but with ``nval`` used for the missing ``nest`` argument. If, after |
| 7977 | calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is |
| 7978 | modified, then the effect of any later call to the returned function |
| 7979 | pointer is undefined. |
| 7980 | |
| 7981 | .. _int_at: |
| 7982 | |
| 7983 | '``llvm.adjust.trampoline``' Intrinsic |
| 7984 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 7985 | |
| 7986 | Syntax: |
| 7987 | """"""" |
| 7988 | |
| 7989 | :: |
| 7990 | |
| 7991 | declare i8* @llvm.adjust.trampoline(i8* <tramp>) |
| 7992 | |
| 7993 | Overview: |
| 7994 | """"""""" |
| 7995 | |
| 7996 | This performs any required machine-specific adjustment to the address of |
| 7997 | a trampoline (passed as ``tramp``). |
| 7998 | |
| 7999 | Arguments: |
| 8000 | """""""""" |
| 8001 | |
| 8002 | ``tramp`` must point to a block of memory which already has trampoline |
| 8003 | code filled in by a previous call to |
| 8004 | :ref:`llvm.init.trampoline <int_it>`. |
| 8005 | |
| 8006 | Semantics: |
| 8007 | """""""""" |
| 8008 | |
| 8009 | On some architectures the address of the code to be executed needs to be |
| 8010 | different to the address where the trampoline is actually stored. This |
| 8011 | intrinsic returns the executable address corresponding to ``tramp`` |
| 8012 | after performing the required machine specific adjustments. The pointer |
| 8013 | returned can then be :ref:`bitcast and executed <int_trampoline>`. |
| 8014 | |
| 8015 | Memory Use Markers |
| 8016 | ------------------ |
| 8017 | |
| 8018 | This class of intrinsics exists to information about the lifetime of |
| 8019 | memory objects and ranges where variables are immutable. |
| 8020 | |
| 8021 | '``llvm.lifetime.start``' Intrinsic |
| 8022 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8023 | |
| 8024 | Syntax: |
| 8025 | """"""" |
| 8026 | |
| 8027 | :: |
| 8028 | |
| 8029 | declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>) |
| 8030 | |
| 8031 | Overview: |
| 8032 | """"""""" |
| 8033 | |
| 8034 | The '``llvm.lifetime.start``' intrinsic specifies the start of a memory |
| 8035 | object's lifetime. |
| 8036 | |
| 8037 | Arguments: |
| 8038 | """""""""" |
| 8039 | |
| 8040 | The first argument is a constant integer representing the size of the |
| 8041 | object, or -1 if it is variable sized. The second argument is a pointer |
| 8042 | to the object. |
| 8043 | |
| 8044 | Semantics: |
| 8045 | """""""""" |
| 8046 | |
| 8047 | This intrinsic indicates that before this point in the code, the value |
| 8048 | of the memory pointed to by ``ptr`` is dead. This means that it is known |
| 8049 | to never be used and has an undefined value. A load from the pointer |
| 8050 | that precedes this intrinsic can be replaced with ``'undef'``. |
| 8051 | |
| 8052 | '``llvm.lifetime.end``' Intrinsic |
| 8053 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8054 | |
| 8055 | Syntax: |
| 8056 | """"""" |
| 8057 | |
| 8058 | :: |
| 8059 | |
| 8060 | declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>) |
| 8061 | |
| 8062 | Overview: |
| 8063 | """"""""" |
| 8064 | |
| 8065 | The '``llvm.lifetime.end``' intrinsic specifies the end of a memory |
| 8066 | object's lifetime. |
| 8067 | |
| 8068 | Arguments: |
| 8069 | """""""""" |
| 8070 | |
| 8071 | The first argument is a constant integer representing the size of the |
| 8072 | object, or -1 if it is variable sized. The second argument is a pointer |
| 8073 | to the object. |
| 8074 | |
| 8075 | Semantics: |
| 8076 | """""""""" |
| 8077 | |
| 8078 | This intrinsic indicates that after this point in the code, the value of |
| 8079 | the memory pointed to by ``ptr`` is dead. This means that it is known to |
| 8080 | never be used and has an undefined value. Any stores into the memory |
| 8081 | object following this intrinsic may be removed as dead. |
| 8082 | |
| 8083 | '``llvm.invariant.start``' Intrinsic |
| 8084 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8085 | |
| 8086 | Syntax: |
| 8087 | """"""" |
| 8088 | |
| 8089 | :: |
| 8090 | |
| 8091 | declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>) |
| 8092 | |
| 8093 | Overview: |
| 8094 | """"""""" |
| 8095 | |
| 8096 | The '``llvm.invariant.start``' intrinsic specifies that the contents of |
| 8097 | a memory object will not change. |
| 8098 | |
| 8099 | Arguments: |
| 8100 | """""""""" |
| 8101 | |
| 8102 | The first argument is a constant integer representing the size of the |
| 8103 | object, or -1 if it is variable sized. The second argument is a pointer |
| 8104 | to the object. |
| 8105 | |
| 8106 | Semantics: |
| 8107 | """""""""" |
| 8108 | |
| 8109 | This intrinsic indicates that until an ``llvm.invariant.end`` that uses |
| 8110 | the return value, the referenced memory location is constant and |
| 8111 | unchanging. |
| 8112 | |
| 8113 | '``llvm.invariant.end``' Intrinsic |
| 8114 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8115 | |
| 8116 | Syntax: |
| 8117 | """"""" |
| 8118 | |
| 8119 | :: |
| 8120 | |
| 8121 | declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>) |
| 8122 | |
| 8123 | Overview: |
| 8124 | """"""""" |
| 8125 | |
| 8126 | The '``llvm.invariant.end``' intrinsic specifies that the contents of a |
| 8127 | memory object are mutable. |
| 8128 | |
| 8129 | Arguments: |
| 8130 | """""""""" |
| 8131 | |
| 8132 | The first argument is the matching ``llvm.invariant.start`` intrinsic. |
| 8133 | The second argument is a constant integer representing the size of the |
| 8134 | object, or -1 if it is variable sized and the third argument is a |
| 8135 | pointer to the object. |
| 8136 | |
| 8137 | Semantics: |
| 8138 | """""""""" |
| 8139 | |
| 8140 | This intrinsic indicates that the memory is mutable again. |
| 8141 | |
| 8142 | General Intrinsics |
| 8143 | ------------------ |
| 8144 | |
| 8145 | This class of intrinsics is designed to be generic and has no specific |
| 8146 | purpose. |
| 8147 | |
| 8148 | '``llvm.var.annotation``' Intrinsic |
| 8149 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8150 | |
| 8151 | Syntax: |
| 8152 | """"""" |
| 8153 | |
| 8154 | :: |
| 8155 | |
| 8156 | declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>) |
| 8157 | |
| 8158 | Overview: |
| 8159 | """"""""" |
| 8160 | |
| 8161 | The '``llvm.var.annotation``' intrinsic. |
| 8162 | |
| 8163 | Arguments: |
| 8164 | """""""""" |
| 8165 | |
| 8166 | The first argument is a pointer to a value, the second is a pointer to a |
| 8167 | global string, the third is a pointer to a global string which is the |
| 8168 | source file name, and the last argument is the line number. |
| 8169 | |
| 8170 | Semantics: |
| 8171 | """""""""" |
| 8172 | |
| 8173 | This intrinsic allows annotation of local variables with arbitrary |
| 8174 | strings. This can be useful for special purpose optimizations that want |
| 8175 | to look for these annotations. These have no other defined use; they are |
| 8176 | ignored by code generation and optimization. |
| 8177 | |
| 8178 | '``llvm.annotation.*``' Intrinsic |
| 8179 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8180 | |
| 8181 | Syntax: |
| 8182 | """"""" |
| 8183 | |
| 8184 | This is an overloaded intrinsic. You can use '``llvm.annotation``' on |
| 8185 | any integer bit width. |
| 8186 | |
| 8187 | :: |
| 8188 | |
| 8189 | declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>) |
| 8190 | declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>) |
| 8191 | declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>) |
| 8192 | declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>) |
| 8193 | declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>) |
| 8194 | |
| 8195 | Overview: |
| 8196 | """"""""" |
| 8197 | |
| 8198 | The '``llvm.annotation``' intrinsic. |
| 8199 | |
| 8200 | Arguments: |
| 8201 | """""""""" |
| 8202 | |
| 8203 | The first argument is an integer value (result of some expression), the |
| 8204 | second is a pointer to a global string, the third is a pointer to a |
| 8205 | global string which is the source file name, and the last argument is |
| 8206 | the line number. It returns the value of the first argument. |
| 8207 | |
| 8208 | Semantics: |
| 8209 | """""""""" |
| 8210 | |
| 8211 | This intrinsic allows annotations to be put on arbitrary expressions |
| 8212 | with arbitrary strings. This can be useful for special purpose |
| 8213 | optimizations that want to look for these annotations. These have no |
| 8214 | other defined use; they are ignored by code generation and optimization. |
| 8215 | |
| 8216 | '``llvm.trap``' Intrinsic |
| 8217 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8218 | |
| 8219 | Syntax: |
| 8220 | """"""" |
| 8221 | |
| 8222 | :: |
| 8223 | |
| 8224 | declare void @llvm.trap() noreturn nounwind |
| 8225 | |
| 8226 | Overview: |
| 8227 | """"""""" |
| 8228 | |
| 8229 | The '``llvm.trap``' intrinsic. |
| 8230 | |
| 8231 | Arguments: |
| 8232 | """""""""" |
| 8233 | |
| 8234 | None. |
| 8235 | |
| 8236 | Semantics: |
| 8237 | """""""""" |
| 8238 | |
| 8239 | This intrinsic is lowered to the target dependent trap instruction. If |
| 8240 | the target does not have a trap instruction, this intrinsic will be |
| 8241 | lowered to a call of the ``abort()`` function. |
| 8242 | |
| 8243 | '``llvm.debugtrap``' Intrinsic |
| 8244 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8245 | |
| 8246 | Syntax: |
| 8247 | """"""" |
| 8248 | |
| 8249 | :: |
| 8250 | |
| 8251 | declare void @llvm.debugtrap() nounwind |
| 8252 | |
| 8253 | Overview: |
| 8254 | """"""""" |
| 8255 | |
| 8256 | The '``llvm.debugtrap``' intrinsic. |
| 8257 | |
| 8258 | Arguments: |
| 8259 | """""""""" |
| 8260 | |
| 8261 | None. |
| 8262 | |
| 8263 | Semantics: |
| 8264 | """""""""" |
| 8265 | |
| 8266 | This intrinsic is lowered to code which is intended to cause an |
| 8267 | execution trap with the intention of requesting the attention of a |
| 8268 | debugger. |
| 8269 | |
| 8270 | '``llvm.stackprotector``' Intrinsic |
| 8271 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8272 | |
| 8273 | Syntax: |
| 8274 | """"""" |
| 8275 | |
| 8276 | :: |
| 8277 | |
| 8278 | declare void @llvm.stackprotector(i8* <guard>, i8** <slot>) |
| 8279 | |
| 8280 | Overview: |
| 8281 | """"""""" |
| 8282 | |
| 8283 | The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it |
| 8284 | onto the stack at ``slot``. The stack slot is adjusted to ensure that it |
| 8285 | is placed on the stack before local variables. |
| 8286 | |
| 8287 | Arguments: |
| 8288 | """""""""" |
| 8289 | |
| 8290 | The ``llvm.stackprotector`` intrinsic requires two pointer arguments. |
| 8291 | The first argument is the value loaded from the stack guard |
| 8292 | ``@__stack_chk_guard``. The second variable is an ``alloca`` that has |
| 8293 | enough space to hold the value of the guard. |
| 8294 | |
| 8295 | Semantics: |
| 8296 | """""""""" |
| 8297 | |
| 8298 | This intrinsic causes the prologue/epilogue inserter to force the |
| 8299 | position of the ``AllocaInst`` stack slot to be before local variables |
| 8300 | on the stack. This is to ensure that if a local variable on the stack is |
| 8301 | overwritten, it will destroy the value of the guard. When the function |
| 8302 | exits, the guard on the stack is checked against the original guard. If |
| 8303 | they are different, then the program aborts by calling the |
| 8304 | ``__stack_chk_fail()`` function. |
| 8305 | |
| 8306 | '``llvm.objectsize``' Intrinsic |
| 8307 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8308 | |
| 8309 | Syntax: |
| 8310 | """"""" |
| 8311 | |
| 8312 | :: |
| 8313 | |
| 8314 | declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>) |
| 8315 | declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>) |
| 8316 | |
| 8317 | Overview: |
| 8318 | """"""""" |
| 8319 | |
| 8320 | The ``llvm.objectsize`` intrinsic is designed to provide information to |
| 8321 | the optimizers to determine at compile time whether a) an operation |
| 8322 | (like memcpy) will overflow a buffer that corresponds to an object, or |
| 8323 | b) that a runtime check for overflow isn't necessary. An object in this |
| 8324 | context means an allocation of a specific class, structure, array, or |
| 8325 | other object. |
| 8326 | |
| 8327 | Arguments: |
| 8328 | """""""""" |
| 8329 | |
| 8330 | The ``llvm.objectsize`` intrinsic takes two arguments. The first |
| 8331 | argument is a pointer to or into the ``object``. The second argument is |
| 8332 | a boolean and determines whether ``llvm.objectsize`` returns 0 (if true) |
| 8333 | or -1 (if false) when the object size is unknown. The second argument |
| 8334 | only accepts constants. |
| 8335 | |
| 8336 | Semantics: |
| 8337 | """""""""" |
| 8338 | |
| 8339 | The ``llvm.objectsize`` intrinsic is lowered to a constant representing |
| 8340 | the size of the object concerned. If the size cannot be determined at |
| 8341 | compile time, ``llvm.objectsize`` returns ``i32/i64 -1 or 0`` (depending |
| 8342 | on the ``min`` argument). |
| 8343 | |
| 8344 | '``llvm.expect``' Intrinsic |
| 8345 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8346 | |
| 8347 | Syntax: |
| 8348 | """"""" |
| 8349 | |
| 8350 | :: |
| 8351 | |
| 8352 | declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>) |
| 8353 | declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>) |
| 8354 | |
| 8355 | Overview: |
| 8356 | """"""""" |
| 8357 | |
| 8358 | The ``llvm.expect`` intrinsic provides information about expected (the |
| 8359 | most probable) value of ``val``, which can be used by optimizers. |
| 8360 | |
| 8361 | Arguments: |
| 8362 | """""""""" |
| 8363 | |
| 8364 | The ``llvm.expect`` intrinsic takes two arguments. The first argument is |
| 8365 | a value. The second argument is an expected value, this needs to be a |
| 8366 | constant value, variables are not allowed. |
| 8367 | |
| 8368 | Semantics: |
| 8369 | """""""""" |
| 8370 | |
| 8371 | This intrinsic is lowered to the ``val``. |
| 8372 | |
| 8373 | '``llvm.donothing``' Intrinsic |
| 8374 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 8375 | |
| 8376 | Syntax: |
| 8377 | """"""" |
| 8378 | |
| 8379 | :: |
| 8380 | |
| 8381 | declare void @llvm.donothing() nounwind readnone |
| 8382 | |
| 8383 | Overview: |
| 8384 | """"""""" |
| 8385 | |
| 8386 | The ``llvm.donothing`` intrinsic doesn't perform any operation. It's the |
| 8387 | only intrinsic that can be called with an invoke instruction. |
| 8388 | |
| 8389 | Arguments: |
| 8390 | """""""""" |
| 8391 | |
| 8392 | None. |
| 8393 | |
| 8394 | Semantics: |
| 8395 | """""""""" |
| 8396 | |
| 8397 | This intrinsic does nothing, and it's removed by optimizers and ignored |
| 8398 | by codegen. |