blob: ef5913b78f3858c56d63e7c7870eb9fc8135ce13 [file] [log] [blame]
Sean Silvab084af42012-12-07 10:36:55 +00001==============================
2LLVM Language Reference Manual
3==============================
4
5.. contents::
6 :local:
Rafael Espindola08013342013-12-07 19:34:20 +00007 :depth: 4
Sean Silvab084af42012-12-07 10:36:55 +00008
Sean Silvab084af42012-12-07 10:36:55 +00009Abstract
10========
11
12This document is a reference manual for the LLVM assembly language. LLVM
13is a Static Single Assignment (SSA) based representation that provides
14type safety, low-level operations, flexibility, and the capability of
15representing 'all' high-level languages cleanly. It is the common code
16representation used throughout all phases of the LLVM compilation
17strategy.
18
19Introduction
20============
21
22The LLVM code representation is designed to be used in three different
23forms: 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
25readable assembly language representation. This allows LLVM to provide a
26powerful intermediate representation for efficient compiler
27transformations and analysis, while providing a natural means to debug
28and visualize the transformations. The three different forms of LLVM are
29all equivalent. This document describes the human readable
30representation and notation.
31
32The LLVM representation aims to be light-weight and low-level while
33being expressive, typed, and extensible at the same time. It aims to be
34a "universal IR" of sorts, by being at a low enough level that
35high-level ideas may be cleanly mapped to it (similar to how
36microprocessors are "universal IR's", allowing many source languages to
37be mapped to them). By providing type information, LLVM can be used as
38the target of optimizations: for example, through pointer analysis, it
39can be proven that a C automatic variable is never accessed outside of
40the current function, allowing it to be promoted to a simple SSA value
41instead of a memory location.
42
43.. _wellformed:
44
45Well-Formedness
46---------------
47
48It is important to note that this document describes 'well formed' LLVM
49assembly language. There is a difference between what the parser accepts
50and what is considered 'well formed'. For example, the following
51instruction is syntactically okay, but not well formed:
52
53.. code-block:: llvm
54
55 %x = add i32 1, %x
56
57because the definition of ``%x`` does not dominate all of its uses. The
58LLVM infrastructure provides a verification pass that may be used to
59verify that an LLVM module is well formed. This pass is automatically
60run by the parser after parsing input assembly and by the optimizer
61before it outputs bitcode. The violations pointed out by the verifier
62pass indicate bugs in transformation passes or input to the parser.
63
64.. _identifiers:
65
66Identifiers
67===========
68
69LLVM identifiers come in two basic types: global and local. Global
70identifiers (functions, global variables) begin with the ``'@'``
71character. Local identifiers (register names, types) begin with the
72``'%'`` character. Additionally, there are three different formats for
73identifiers, 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
Sean Silva9d01a5b2015-01-07 21:35:14 +000078 '``[%@][-a-zA-Z$._][-a-zA-Z$._0-9]*``'. Identifiers that require other
Sean Silvab084af42012-12-07 10:36:55 +000079 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
Hans Wennborg85e06532014-07-30 20:02:08 +000082 be used in a name value, even quotes themselves. The ``"\01"`` prefix
83 can be used on global variables to suppress mangling.
Sean Silvab084af42012-12-07 10:36:55 +000084#. Unnamed values are represented as an unsigned numeric value with
85 their prefix. For example, ``%12``, ``@2``, ``%44``.
Sean Silvaa1190322015-08-06 22:56:48 +000086#. Constants, which are described in the section Constants_ below.
Sean Silvab084af42012-12-07 10:36:55 +000087
88LLVM requires that values start with a prefix for two reasons: Compilers
89don't need to worry about name clashes with reserved words, and the set
90of reserved words may be expanded in the future without penalty.
91Additionally, unnamed identifiers allow a compiler to quickly come up
92with a temporary variable without having to avoid symbol table
93conflicts.
94
95Reserved words in LLVM are very similar to reserved words in other
96languages. There are keywords for different opcodes ('``add``',
97'``bitcast``', '``ret``', etc...), for primitive type names ('``void``',
98'``i32``', etc...), and others. These reserved words cannot conflict
99with variable names, because none of them start with a prefix character
100(``'%'`` or ``'@'``).
101
102Here is an example of LLVM code to multiply the integer variable
103'``%X``' by 8:
104
105The easy way:
106
107.. code-block:: llvm
108
109 %result = mul i32 %X, 8
110
111After strength reduction:
112
113.. code-block:: llvm
114
Dmitri Gribenko675911d2013-01-26 13:30:13 +0000115 %result = shl i32 %X, 3
Sean Silvab084af42012-12-07 10:36:55 +0000116
117And the hard way:
118
119.. code-block:: llvm
120
Tim Northover675a0962014-06-13 14:24:23 +0000121 %0 = add i32 %X, %X ; yields i32:%0
122 %1 = add i32 %0, %0 ; yields i32:%1
Sean Silvab084af42012-12-07 10:36:55 +0000123 %result = add i32 %1, %1
124
125This last way of multiplying ``%X`` by 8 illustrates several important
126lexical features of LLVM:
127
128#. Comments are delimited with a '``;``' and go until the end of line.
129#. Unnamed temporaries are created when the result of a computation is
130 not assigned to a named value.
Sean Silva8ca11782013-05-20 23:31:12 +0000131#. Unnamed temporaries are numbered sequentially (using a per-function
Dan Liew2661dfc2014-08-20 15:06:30 +0000132 incrementing counter, starting with 0). Note that basic blocks and unnamed
133 function parameters are included in this numbering. For example, if the
134 entry basic block is not given a label name and all function parameters are
135 named, then it will get number 0.
Sean Silvab084af42012-12-07 10:36:55 +0000136
137It also shows a convention that we follow in this document. When
138demonstrating instructions, we will follow an instruction with a comment
139that defines the type and name of value produced.
140
141High Level Structure
142====================
143
144Module Structure
145----------------
146
147LLVM programs are composed of ``Module``'s, each of which is a
148translation unit of the input programs. Each module consists of
149functions, global variables, and symbol table entries. Modules may be
150combined together with the LLVM linker, which merges function (and
151global variable) definitions, resolves forward declarations, and merges
152symbol table entries. Here is an example of the "hello world" module:
153
154.. code-block:: llvm
155
Michael Liaoa7699082013-03-06 18:24:34 +0000156 ; Declare the string constant as a global constant.
157 @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
Sean Silvab084af42012-12-07 10:36:55 +0000158
Michael Liaoa7699082013-03-06 18:24:34 +0000159 ; External declaration of the puts function
160 declare i32 @puts(i8* nocapture) nounwind
Sean Silvab084af42012-12-07 10:36:55 +0000161
162 ; Definition of main function
Michael Liaoa7699082013-03-06 18:24:34 +0000163 define i32 @main() { ; i32()*
164 ; Convert [13 x i8]* to i8 *...
David Blaikie16a97eb2015-03-04 22:02:58 +0000165 %cast210 = getelementptr [13 x i8], [13 x i8]* @.str, i64 0, i64 0
Sean Silvab084af42012-12-07 10:36:55 +0000166
Michael Liaoa7699082013-03-06 18:24:34 +0000167 ; Call puts function to write out the string to stdout.
Sean Silvab084af42012-12-07 10:36:55 +0000168 call i32 @puts(i8* %cast210)
Michael Liaoa7699082013-03-06 18:24:34 +0000169 ret i32 0
Sean Silvab084af42012-12-07 10:36:55 +0000170 }
171
172 ; Named metadata
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +0000173 !0 = !{i32 42, null, !"string"}
Nick Lewyckya0de40a2014-08-13 04:54:05 +0000174 !foo = !{!0}
Sean Silvab084af42012-12-07 10:36:55 +0000175
176This example is made up of a :ref:`global variable <globalvars>` named
177"``.str``", an external declaration of the "``puts``" function, a
178:ref:`function definition <functionstructure>` for "``main``" and
179:ref:`named metadata <namedmetadatastructure>` "``foo``".
180
181In general, a module is made up of a list of global values (where both
182functions and global variables are global values). Global values are
183represented by a pointer to a memory location (in this case, a pointer
184to an array of char, and a pointer to a function), and have one of the
185following :ref:`linkage types <linkage>`.
186
187.. _linkage:
188
189Linkage Types
190-------------
191
192All Global Variables and Functions have one of the following types of
193linkage:
194
195``private``
196 Global values with "``private``" linkage are only directly
197 accessible by objects in the current module. In particular, linking
198 code into a module with an private global value may cause the
199 private to be renamed as necessary to avoid collisions. Because the
200 symbol is private to the module, all references can be updated. This
201 doesn't show up in any symbol table in the object file.
Sean Silvab084af42012-12-07 10:36:55 +0000202``internal``
203 Similar to private, but the value shows as a local symbol
204 (``STB_LOCAL`` in the case of ELF) in the object file. This
205 corresponds to the notion of the '``static``' keyword in C.
206``available_externally``
207 Globals with "``available_externally``" linkage are never emitted
208 into the object file corresponding to the LLVM module. They exist to
209 allow inlining and other optimizations to take place given knowledge
210 of the definition of the global, which is known to be somewhere
211 outside the module. Globals with ``available_externally`` linkage
212 are allowed to be discarded at will, and are otherwise the same as
213 ``linkonce_odr``. This linkage type is only allowed on definitions,
214 not declarations.
215``linkonce``
216 Globals with "``linkonce``" linkage are merged with other globals of
217 the same name when linkage occurs. This can be used to implement
218 some forms of inline functions, templates, or other code which must
219 be generated in each translation unit that uses it, but where the
220 body may be overridden with a more definitive definition later.
221 Unreferenced ``linkonce`` globals are allowed to be discarded. Note
222 that ``linkonce`` linkage does not actually allow the optimizer to
223 inline the body of this function into callers because it doesn't
224 know if this definition of the function is the definitive definition
225 within the program or whether it will be overridden by a stronger
226 definition. To enable inlining and other optimizations, use
227 "``linkonce_odr``" linkage.
228``weak``
229 "``weak``" linkage has the same merging semantics as ``linkonce``
230 linkage, except that unreferenced globals with ``weak`` linkage may
231 not be discarded. This is used for globals that are declared "weak"
232 in C source code.
233``common``
234 "``common``" linkage is most similar to "``weak``" linkage, but they
235 are used for tentative definitions in C, such as "``int X;``" at
236 global scope. Symbols with "``common``" linkage are merged in the
237 same way as ``weak symbols``, and they may not be deleted if
238 unreferenced. ``common`` symbols may not have an explicit section,
239 must have a zero initializer, and may not be marked
240 ':ref:`constant <globalvars>`'. Functions and aliases may not have
241 common linkage.
242
243.. _linkage_appending:
244
245``appending``
246 "``appending``" linkage may only be applied to global variables of
247 pointer to array type. When two global variables with appending
248 linkage are linked together, the two global arrays are appended
249 together. This is the LLVM, typesafe, equivalent of having the
250 system linker append together "sections" with identical names when
251 .o files are linked.
252``extern_weak``
253 The semantics of this linkage follow the ELF object file model: the
254 symbol is weak until linked, if not linked, the symbol becomes null
255 instead of being an undefined reference.
256``linkonce_odr``, ``weak_odr``
257 Some languages allow differing globals to be merged, such as two
258 functions with different semantics. Other languages, such as
259 ``C++``, ensure that only equivalent globals are ever merged (the
Sean Silvaa1190322015-08-06 22:56:48 +0000260 "one definition rule" --- "ODR"). Such languages can use the
Sean Silvab084af42012-12-07 10:36:55 +0000261 ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the
262 global will only be merged with equivalent globals. These linkage
263 types are otherwise the same as their non-``odr`` versions.
Sean Silvab084af42012-12-07 10:36:55 +0000264``external``
265 If none of the above identifiers are used, the global is externally
266 visible, meaning that it participates in linkage and can be used to
267 resolve external symbol references.
268
Sean Silvab084af42012-12-07 10:36:55 +0000269It is illegal for a function *declaration* to have any linkage type
Nico Rieck7157bb72014-01-14 15:22:47 +0000270other than ``external`` or ``extern_weak``.
Sean Silvab084af42012-12-07 10:36:55 +0000271
Sean Silvab084af42012-12-07 10:36:55 +0000272.. _callingconv:
273
274Calling Conventions
275-------------------
276
277LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and
278:ref:`invokes <i_invoke>` can all have an optional calling convention
279specified for the call. The calling convention of any pair of dynamic
280caller/callee must match, or the behavior of the program is undefined.
281The following calling conventions are supported by LLVM, and more may be
282added in the future:
283
284"``ccc``" - The C calling convention
285 This calling convention (the default if no other calling convention
286 is specified) matches the target C calling conventions. This calling
287 convention supports varargs function calls and tolerates some
288 mismatch in the declared prototype and implemented declaration of
289 the function (as does normal C).
290"``fastcc``" - The fast calling convention
291 This calling convention attempts to make calls as fast as possible
292 (e.g. by passing things in registers). This calling convention
293 allows the target to use whatever tricks it wants to produce fast
294 code for the target, without having to conform to an externally
295 specified ABI (Application Binary Interface). `Tail calls can only
296 be optimized when this, the GHC or the HiPE convention is
297 used. <CodeGenerator.html#id80>`_ This calling convention does not
298 support varargs and requires the prototype of all callees to exactly
299 match the prototype of the function definition.
300"``coldcc``" - The cold calling convention
301 This calling convention attempts to make code in the caller as
302 efficient as possible under the assumption that the call is not
303 commonly executed. As such, these calls often preserve all registers
304 so that the call does not break any live ranges in the caller side.
305 This calling convention does not support varargs and requires the
306 prototype of all callees to exactly match the prototype of the
Juergen Ributzka5d05ed12014-01-17 22:24:35 +0000307 function definition. Furthermore the inliner doesn't consider such function
308 calls for inlining.
Sean Silvab084af42012-12-07 10:36:55 +0000309"``cc 10``" - GHC convention
310 This calling convention has been implemented specifically for use by
311 the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_.
312 It passes everything in registers, going to extremes to achieve this
313 by disabling callee save registers. This calling convention should
314 not be used lightly but only for specific situations such as an
315 alternative to the *register pinning* performance technique often
316 used when implementing functional programming languages. At the
317 moment only X86 supports this convention and it has the following
318 limitations:
319
320 - On *X86-32* only supports up to 4 bit type parameters. No
321 floating point types are supported.
322 - On *X86-64* only supports up to 10 bit type parameters and 6
323 floating point parameters.
324
325 This calling convention supports `tail call
326 optimization <CodeGenerator.html#id80>`_ but requires both the
327 caller and callee are using it.
328"``cc 11``" - The HiPE calling convention
329 This calling convention has been implemented specifically for use by
330 the `High-Performance Erlang
331 (HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the*
332 native code compiler of the `Ericsson's Open Source Erlang/OTP
333 system <http://www.erlang.org/download.shtml>`_. It uses more
334 registers for argument passing than the ordinary C calling
335 convention and defines no callee-saved registers. The calling
336 convention properly supports `tail call
337 optimization <CodeGenerator.html#id80>`_ but requires that both the
338 caller and the callee use it. It uses a *register pinning*
339 mechanism, similar to GHC's convention, for keeping frequently
340 accessed runtime components pinned to specific hardware registers.
341 At the moment only X86 supports this convention (both 32 and 64
342 bit).
Andrew Trick5e029ce2013-12-24 02:57:25 +0000343"``webkit_jscc``" - WebKit's JavaScript calling convention
344 This calling convention has been implemented for `WebKit FTL JIT
345 <https://trac.webkit.org/wiki/FTLJIT>`_. It passes arguments on the
346 stack right to left (as cdecl does), and returns a value in the
347 platform's customary return register.
348"``anyregcc``" - Dynamic calling convention for code patching
349 This is a special convention that supports patching an arbitrary code
350 sequence in place of a call site. This convention forces the call
Eli Bendersky45324ce2015-04-02 15:20:04 +0000351 arguments into registers but allows them to be dynamically
Andrew Trick5e029ce2013-12-24 02:57:25 +0000352 allocated. This can currently only be used with calls to
353 llvm.experimental.patchpoint because only this intrinsic records
354 the location of its arguments in a side table. See :doc:`StackMaps`.
Juergen Ributzkae6250132014-01-17 19:47:03 +0000355"``preserve_mostcc``" - The `PreserveMost` calling convention
Eli Bendersky45324ce2015-04-02 15:20:04 +0000356 This calling convention attempts to make the code in the caller as
357 unintrusive as possible. This convention behaves identically to the `C`
Juergen Ributzkae6250132014-01-17 19:47:03 +0000358 calling convention on how arguments and return values are passed, but it
359 uses a different set of caller/callee-saved registers. This alleviates the
360 burden of saving and recovering a large register set before and after the
Juergen Ributzka980f2dc2014-01-30 02:39:00 +0000361 call in the caller. If the arguments are passed in callee-saved registers,
362 then they will be preserved by the callee across the call. This doesn't
363 apply for values returned in callee-saved registers.
Juergen Ributzkae6250132014-01-17 19:47:03 +0000364
365 - On X86-64 the callee preserves all general purpose registers, except for
366 R11. R11 can be used as a scratch register. Floating-point registers
367 (XMMs/YMMs) are not preserved and need to be saved by the caller.
368
369 The idea behind this convention is to support calls to runtime functions
370 that have a hot path and a cold path. The hot path is usually a small piece
Eric Christopher1e61ffd2015-02-19 18:46:25 +0000371 of code that doesn't use many registers. The cold path might need to call out to
Juergen Ributzkae6250132014-01-17 19:47:03 +0000372 another function and therefore only needs to preserve the caller-saved
Juergen Ributzka5d05ed12014-01-17 22:24:35 +0000373 registers, which haven't already been saved by the caller. The
374 `PreserveMost` calling convention is very similar to the `cold` calling
375 convention in terms of caller/callee-saved registers, but they are used for
376 different types of function calls. `coldcc` is for function calls that are
377 rarely executed, whereas `preserve_mostcc` function calls are intended to be
378 on the hot path and definitely executed a lot. Furthermore `preserve_mostcc`
379 doesn't prevent the inliner from inlining the function call.
Juergen Ributzkae6250132014-01-17 19:47:03 +0000380
381 This calling convention will be used by a future version of the ObjectiveC
382 runtime and should therefore still be considered experimental at this time.
383 Although this convention was created to optimize certain runtime calls to
384 the ObjectiveC runtime, it is not limited to this runtime and might be used
385 by other runtimes in the future too. The current implementation only
386 supports X86-64, but the intention is to support more architectures in the
387 future.
388"``preserve_allcc``" - The `PreserveAll` calling convention
389 This calling convention attempts to make the code in the caller even less
390 intrusive than the `PreserveMost` calling convention. This calling
391 convention also behaves identical to the `C` calling convention on how
392 arguments and return values are passed, but it uses a different set of
393 caller/callee-saved registers. This removes the burden of saving and
Juergen Ributzka980f2dc2014-01-30 02:39:00 +0000394 recovering a large register set before and after the call in the caller. If
395 the arguments are passed in callee-saved registers, then they will be
396 preserved by the callee across the call. This doesn't apply for values
397 returned in callee-saved registers.
Juergen Ributzkae6250132014-01-17 19:47:03 +0000398
399 - On X86-64 the callee preserves all general purpose registers, except for
400 R11. R11 can be used as a scratch register. Furthermore it also preserves
401 all floating-point registers (XMMs/YMMs).
402
403 The idea behind this convention is to support calls to runtime functions
404 that don't need to call out to any other functions.
405
406 This calling convention, like the `PreserveMost` calling convention, will be
407 used by a future version of the ObjectiveC runtime and should be considered
408 experimental at this time.
Sean Silvab084af42012-12-07 10:36:55 +0000409"``cc <n>``" - Numbered convention
410 Any calling convention may be specified by number, allowing
411 target-specific calling conventions to be used. Target specific
412 calling conventions start at 64.
413
414More calling conventions can be added/defined on an as-needed basis, to
415support Pascal conventions or any other well-known target-independent
416convention.
417
Eli Benderskyfdc529a2013-06-07 19:40:08 +0000418.. _visibilitystyles:
419
Sean Silvab084af42012-12-07 10:36:55 +0000420Visibility Styles
421-----------------
422
423All Global Variables and Functions have one of the following visibility
424styles:
425
426"``default``" - Default style
427 On targets that use the ELF object file format, default visibility
428 means that the declaration is visible to other modules and, in
429 shared libraries, means that the declared entity may be overridden.
430 On Darwin, default visibility means that the declaration is visible
431 to other modules. Default visibility corresponds to "external
432 linkage" in the language.
433"``hidden``" - Hidden style
434 Two declarations of an object with hidden visibility refer to the
435 same object if they are in the same shared object. Usually, hidden
436 visibility indicates that the symbol will not be placed into the
437 dynamic symbol table, so no other module (executable or shared
438 library) can reference it directly.
439"``protected``" - Protected style
440 On ELF, protected visibility indicates that the symbol will be
441 placed in the dynamic symbol table, but that references within the
442 defining module will bind to the local symbol. That is, the symbol
443 cannot be overridden by another module.
444
Duncan P. N. Exon Smithb80de102014-05-07 22:57:20 +0000445A symbol with ``internal`` or ``private`` linkage must have ``default``
446visibility.
447
Rafael Espindola3bc64d52014-05-26 21:30:40 +0000448.. _dllstorageclass:
Eli Benderskyfdc529a2013-06-07 19:40:08 +0000449
Nico Rieck7157bb72014-01-14 15:22:47 +0000450DLL Storage Classes
451-------------------
452
453All Global Variables, Functions and Aliases can have one of the following
454DLL storage class:
455
456``dllimport``
457 "``dllimport``" causes the compiler to reference a function or variable via
458 a global pointer to a pointer that is set up by the DLL exporting the
459 symbol. On Microsoft Windows targets, the pointer name is formed by
460 combining ``__imp_`` and the function or variable name.
461``dllexport``
462 "``dllexport``" causes the compiler to provide a global pointer to a pointer
463 in a DLL, so that it can be referenced with the ``dllimport`` attribute. On
464 Microsoft Windows targets, the pointer name is formed by combining
465 ``__imp_`` and the function or variable name. Since this storage class
466 exists for defining a dll interface, the compiler, assembler and linker know
467 it is externally referenced and must refrain from deleting the symbol.
468
Rafael Espindola59f7eba2014-05-28 18:15:43 +0000469.. _tls_model:
470
471Thread Local Storage Models
472---------------------------
473
474A variable may be defined as ``thread_local``, which means that it will
475not be shared by threads (each thread will have a separated copy of the
476variable). Not all targets support thread-local variables. Optionally, a
477TLS model may be specified:
478
479``localdynamic``
480 For variables that are only used within the current shared library.
481``initialexec``
482 For variables in modules that will not be loaded dynamically.
483``localexec``
484 For variables defined in the executable and only used within it.
485
486If no explicit model is given, the "general dynamic" model is used.
487
488The models correspond to the ELF TLS models; see `ELF Handling For
489Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ for
490more information on under which circumstances the different models may
491be used. The target may choose a different TLS model if the specified
492model is not supported, or if a better choice of model can be made.
493
Sean Silva706fba52015-08-06 22:56:24 +0000494A model can also be specified in an alias, but then it only governs how
Rafael Espindola59f7eba2014-05-28 18:15:43 +0000495the alias is accessed. It will not have any effect in the aliasee.
496
Chih-Hung Hsieh1e859582015-07-28 16:24:05 +0000497For platforms without linker support of ELF TLS model, the -femulated-tls
498flag can be used to generate GCC compatible emulated TLS code.
499
Rafael Espindola3bc64d52014-05-26 21:30:40 +0000500.. _namedtypes:
501
Reid Kleckner7c84d1d2014-03-05 02:21:50 +0000502Structure Types
503---------------
Sean Silvab084af42012-12-07 10:36:55 +0000504
Reid Kleckner7c84d1d2014-03-05 02:21:50 +0000505LLVM IR allows you to specify both "identified" and "literal" :ref:`structure
Sean Silvaa1190322015-08-06 22:56:48 +0000506types <t_struct>`. Literal types are uniqued structurally, but identified types
507are never uniqued. An :ref:`opaque structural type <t_opaque>` can also be used
Richard Smith32dbdf62014-07-31 04:25:36 +0000508to forward declare a type that is not yet available.
Reid Kleckner7c84d1d2014-03-05 02:21:50 +0000509
Sean Silva706fba52015-08-06 22:56:24 +0000510An example of an identified structure specification is:
Sean Silvab084af42012-12-07 10:36:55 +0000511
512.. code-block:: llvm
513
514 %mytype = type { %mytype*, i32 }
515
Sean Silvaa1190322015-08-06 22:56:48 +0000516Prior to the LLVM 3.0 release, identified types were structurally uniqued. Only
Reid Kleckner7c84d1d2014-03-05 02:21:50 +0000517literal types are uniqued in recent versions of LLVM.
Sean Silvab084af42012-12-07 10:36:55 +0000518
519.. _globalvars:
520
521Global Variables
522----------------
523
524Global variables define regions of memory allocated at compilation time
Rafael Espindola5d1b7452013-10-29 13:44:11 +0000525instead of run-time.
526
Eric Christopher1e61ffd2015-02-19 18:46:25 +0000527Global variable definitions must be initialized.
Rafael Espindola5d1b7452013-10-29 13:44:11 +0000528
529Global variables in other translation units can also be declared, in which
530case they don't have an initializer.
Sean Silvab084af42012-12-07 10:36:55 +0000531
Bob Wilson85b24f22014-06-12 20:40:33 +0000532Either global variable definitions or declarations may have an explicit section
533to be placed in and may have an optional explicit alignment specified.
534
Michael Gottesman006039c2013-01-31 05:48:48 +0000535A variable may be defined as a global ``constant``, which indicates that
Sean Silvab084af42012-12-07 10:36:55 +0000536the contents of the variable will **never** be modified (enabling better
537optimization, allowing the global data to be placed in the read-only
538section of an executable, etc). Note that variables that need runtime
Michael Gottesman1cffcf742013-01-31 05:44:04 +0000539initialization cannot be marked ``constant`` as there is a store to the
Sean Silvab084af42012-12-07 10:36:55 +0000540variable.
541
542LLVM explicitly allows *declarations* of global variables to be marked
543constant, even if the final definition of the global is not. This
544capability can be used to enable slightly better optimization of the
545program, but requires the language definition to guarantee that
546optimizations based on the 'constantness' are valid for the translation
547units that do not include the definition.
548
549As SSA values, global variables define pointer values that are in scope
550(i.e. they dominate) all basic blocks in the program. Global variables
551always define a pointer to their "content" type because they describe a
552region of memory, and all memory objects in LLVM are accessed through
553pointers.
554
555Global variables can be marked with ``unnamed_addr`` which indicates
556that the address is not significant, only the content. Constants marked
557like this can be merged with other constants if they have the same
558initializer. Note that a constant with significant address *can* be
559merged with a ``unnamed_addr`` constant, the result being a constant
560whose address is significant.
561
562A global variable may be declared to reside in a target-specific
563numbered address space. For targets that support them, address spaces
564may affect how optimizations are performed and/or what target
565instructions are used to access the variable. The default address space
566is zero. The address space qualifier must precede any other attributes.
567
568LLVM allows an explicit section to be specified for globals. If the
569target supports it, it will emit globals to the section specified.
David Majnemerdad0a642014-06-27 18:19:56 +0000570Additionally, the global can placed in a comdat if the target has the necessary
571support.
Sean Silvab084af42012-12-07 10:36:55 +0000572
Michael Gottesmane743a302013-02-04 03:22:00 +0000573By default, global initializers are optimized by assuming that global
Michael Gottesmanef2bc772013-02-03 09:57:15 +0000574variables defined within the module are not modified from their
Sean Silvaa1190322015-08-06 22:56:48 +0000575initial values before the start of the global initializer. This is
Michael Gottesmanef2bc772013-02-03 09:57:15 +0000576true even for variables potentially accessible from outside the
577module, including those with external linkage or appearing in
Yunzhong Gaof5b769e2013-12-05 18:37:54 +0000578``@llvm.used`` or dllexported variables. This assumption may be suppressed
579by marking the variable with ``externally_initialized``.
Michael Gottesmanef2bc772013-02-03 09:57:15 +0000580
Sean Silvab084af42012-12-07 10:36:55 +0000581An explicit alignment may be specified for a global, which must be a
582power of 2. If not present, or if the alignment is set to zero, the
583alignment of the global is set by the target to whatever it feels
584convenient. If an explicit alignment is specified, the global is forced
585to have exactly that alignment. Targets and optimizers are not allowed
586to over-align the global if the global has an assigned section. In this
587case, the extra alignment could be observable: for example, code could
588assume that the globals are densely packed in their section and try to
589iterate over them as an array, alignment padding would break this
Reid Kleckner15fe7a52014-07-15 01:16:09 +0000590iteration. The maximum alignment is ``1 << 29``.
Sean Silvab084af42012-12-07 10:36:55 +0000591
Nico Rieck7157bb72014-01-14 15:22:47 +0000592Globals can also have a :ref:`DLL storage class <dllstorageclass>`.
593
Peter Collingbourne69ba0162015-02-04 00:42:45 +0000594Variables and aliases can have a
Rafael Espindola59f7eba2014-05-28 18:15:43 +0000595:ref:`Thread Local Storage Model <tls_model>`.
596
Nico Rieck7157bb72014-01-14 15:22:47 +0000597Syntax::
598
599 [@<GlobalVarName> =] [Linkage] [Visibility] [DLLStorageClass] [ThreadLocal]
Rafael Espindola28f3ca62014-06-09 21:21:33 +0000600 [unnamed_addr] [AddrSpace] [ExternallyInitialized]
Bob Wilson85b24f22014-06-12 20:40:33 +0000601 <global | constant> <Type> [<InitializerConstant>]
Rafael Espindola83a362c2015-01-06 22:55:16 +0000602 [, section "name"] [, comdat [($name)]]
603 [, align <Alignment>]
Nico Rieck7157bb72014-01-14 15:22:47 +0000604
Sean Silvab084af42012-12-07 10:36:55 +0000605For example, the following defines a global in a numbered address space
606with an initializer, section, and alignment:
607
608.. code-block:: llvm
609
610 @G = addrspace(5) constant float 1.0, section "foo", align 4
611
Rafael Espindola5d1b7452013-10-29 13:44:11 +0000612The following example just declares a global variable
613
614.. code-block:: llvm
615
616 @G = external global i32
617
Sean Silvab084af42012-12-07 10:36:55 +0000618The following example defines a thread-local global with the
619``initialexec`` TLS model:
620
621.. code-block:: llvm
622
623 @G = thread_local(initialexec) global i32 0, align 4
624
625.. _functionstructure:
626
627Functions
628---------
629
630LLVM function definitions consist of the "``define``" keyword, an
631optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
Nico Rieck7157bb72014-01-14 15:22:47 +0000632style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`,
633an optional :ref:`calling convention <callingconv>`,
Sean Silvab084af42012-12-07 10:36:55 +0000634an optional ``unnamed_addr`` attribute, a return type, an optional
635:ref:`parameter attribute <paramattrs>` for the return type, a function
636name, a (possibly empty) argument list (each with optional :ref:`parameter
637attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`,
David Majnemerdad0a642014-06-27 18:19:56 +0000638an optional section, an optional alignment,
639an optional :ref:`comdat <langref_comdats>`,
Peter Collingbourne51d2de72014-12-03 02:08:38 +0000640an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`,
David Majnemer7fddecc2015-06-17 20:52:32 +0000641an optional :ref:`prologue <prologuedata>`,
642an optional :ref:`personality <personalityfn>`,
643an opening curly brace, a list of basic blocks, and a closing curly brace.
Sean Silvab084af42012-12-07 10:36:55 +0000644
645LLVM function declarations consist of the "``declare``" keyword, an
646optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
Nico Rieck7157bb72014-01-14 15:22:47 +0000647style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`,
648an optional :ref:`calling convention <callingconv>`,
Sean Silvab084af42012-12-07 10:36:55 +0000649an optional ``unnamed_addr`` attribute, a return type, an optional
650:ref:`parameter attribute <paramattrs>` for the return type, a function
Peter Collingbourne3fa50f92013-09-16 01:08:15 +0000651name, a possibly empty list of arguments, an optional alignment, an optional
Peter Collingbourne51d2de72014-12-03 02:08:38 +0000652:ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`,
653and an optional :ref:`prologue <prologuedata>`.
Sean Silvab084af42012-12-07 10:36:55 +0000654
Bill Wendling6822ecb2013-10-27 05:09:12 +0000655A function definition contains a list of basic blocks, forming the CFG (Control
656Flow Graph) for the function. Each basic block may optionally start with a label
657(giving the basic block a symbol table entry), contains a list of instructions,
658and ends with a :ref:`terminator <terminators>` instruction (such as a branch or
659function return). If an explicit label is not provided, a block is assigned an
660implicit numbered label, using the next value from the same counter as used for
661unnamed temporaries (:ref:`see above<identifiers>`). For example, if a function
662entry block does not have an explicit label, it will be assigned label "%0",
663then the first unnamed temporary in that block will be "%1", etc.
Sean Silvab084af42012-12-07 10:36:55 +0000664
665The first basic block in a function is special in two ways: it is
666immediately executed on entrance to the function, and it is not allowed
667to have predecessor basic blocks (i.e. there can not be any branches to
668the entry block of a function). Because the block can have no
669predecessors, it also cannot have any :ref:`PHI nodes <i_phi>`.
670
671LLVM allows an explicit section to be specified for functions. If the
672target supports it, it will emit functions to the section specified.
Eric Christopher1e61ffd2015-02-19 18:46:25 +0000673Additionally, the function can be placed in a COMDAT.
Sean Silvab084af42012-12-07 10:36:55 +0000674
675An explicit alignment may be specified for a function. If not present,
676or if the alignment is set to zero, the alignment of the function is set
677by the target to whatever it feels convenient. If an explicit alignment
678is specified, the function is forced to have at least that much
679alignment. All alignments must be a power of 2.
680
Eric Christopher1e61ffd2015-02-19 18:46:25 +0000681If the ``unnamed_addr`` attribute is given, the address is known to not
Sean Silvab084af42012-12-07 10:36:55 +0000682be significant and two identical functions can be merged.
683
684Syntax::
685
Nico Rieck7157bb72014-01-14 15:22:47 +0000686 define [linkage] [visibility] [DLLStorageClass]
Sean Silvab084af42012-12-07 10:36:55 +0000687 [cconv] [ret attrs]
688 <ResultType> @<FunctionName> ([argument list])
Rafael Espindola83a362c2015-01-06 22:55:16 +0000689 [unnamed_addr] [fn Attrs] [section "name"] [comdat [($name)]]
David Majnemer7fddecc2015-06-17 20:52:32 +0000690 [align N] [gc] [prefix Constant] [prologue Constant]
691 [personality Constant] { ... }
Sean Silvab084af42012-12-07 10:36:55 +0000692
Sean Silva706fba52015-08-06 22:56:24 +0000693The argument list is a comma separated sequence of arguments where each
694argument is of the following form:
Dan Liew2661dfc2014-08-20 15:06:30 +0000695
696Syntax::
697
698 <type> [parameter Attrs] [name]
699
700
Eli Benderskyfdc529a2013-06-07 19:40:08 +0000701.. _langref_aliases:
702
Sean Silvab084af42012-12-07 10:36:55 +0000703Aliases
704-------
705
Rafael Espindola64c1e182014-06-03 02:41:57 +0000706Aliases, unlike function or variables, don't create any new data. They
707are just a new symbol and metadata for an existing position.
708
709Aliases have a name and an aliasee that is either a global value or a
710constant expression.
711
Nico Rieck7157bb72014-01-14 15:22:47 +0000712Aliases may have an optional :ref:`linkage type <linkage>`, an optional
Rafael Espindola64c1e182014-06-03 02:41:57 +0000713:ref:`visibility style <visibility>`, an optional :ref:`DLL storage class
714<dllstorageclass>` and an optional :ref:`tls model <tls_model>`.
Sean Silvab084af42012-12-07 10:36:55 +0000715
716Syntax::
717
Rafael Espindola464fe022014-07-30 22:51:54 +0000718 @<Name> = [Linkage] [Visibility] [DLLStorageClass] [ThreadLocal] [unnamed_addr] alias <AliaseeTy> @<Aliasee>
Sean Silvab084af42012-12-07 10:36:55 +0000719
Rafael Espindola2fb5bc32014-03-13 23:18:37 +0000720The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``,
Rafael Espindola716e7402013-11-01 17:09:14 +0000721``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers
Rafael Espindola64c1e182014-06-03 02:41:57 +0000722might not correctly handle dropping a weak symbol that is aliased.
Rafael Espindola78527052013-10-06 15:10:43 +0000723
Eric Christopher1e61ffd2015-02-19 18:46:25 +0000724Aliases that are not ``unnamed_addr`` are guaranteed to have the same address as
Rafael Espindola42a4c9f2014-06-06 01:20:28 +0000725the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point
726to the same content.
Rafael Espindolaf3336bc2014-03-12 20:15:49 +0000727
Rafael Espindola64c1e182014-06-03 02:41:57 +0000728Since aliases are only a second name, some restrictions apply, of which
729some can only be checked when producing an object file:
Rafael Espindolaf3336bc2014-03-12 20:15:49 +0000730
Rafael Espindola64c1e182014-06-03 02:41:57 +0000731* The expression defining the aliasee must be computable at assembly
732 time. Since it is just a name, no relocations can be used.
733
734* No alias in the expression can be weak as the possibility of the
735 intermediate alias being overridden cannot be represented in an
736 object file.
737
738* No global value in the expression can be a declaration, since that
739 would require a relocation, which is not possible.
Rafael Espindola24a669d2014-03-27 15:26:56 +0000740
David Majnemerdad0a642014-06-27 18:19:56 +0000741.. _langref_comdats:
742
743Comdats
744-------
745
746Comdat IR provides access to COFF and ELF object file COMDAT functionality.
747
Sean Silvaa1190322015-08-06 22:56:48 +0000748Comdats have a name which represents the COMDAT key. All global objects that
David Majnemerdad0a642014-06-27 18:19:56 +0000749specify this key will only end up in the final object file if the linker chooses
Sean Silvaa1190322015-08-06 22:56:48 +0000750that key over some other key. Aliases are placed in the same COMDAT that their
David Majnemerdad0a642014-06-27 18:19:56 +0000751aliasee computes to, if any.
752
753Comdats have a selection kind to provide input on how the linker should
754choose between keys in two different object files.
755
756Syntax::
757
758 $<Name> = comdat SelectionKind
759
760The selection kind must be one of the following:
761
762``any``
763 The linker may choose any COMDAT key, the choice is arbitrary.
764``exactmatch``
765 The linker may choose any COMDAT key but the sections must contain the
766 same data.
767``largest``
768 The linker will choose the section containing the largest COMDAT key.
769``noduplicates``
770 The linker requires that only section with this COMDAT key exist.
771``samesize``
772 The linker may choose any COMDAT key but the sections must contain the
773 same amount of data.
774
775Note that the Mach-O platform doesn't support COMDATs and ELF only supports
776``any`` as a selection kind.
777
778Here is an example of a COMDAT group where a function will only be selected if
779the COMDAT key's section is the largest:
780
781.. code-block:: llvm
782
783 $foo = comdat largest
Rafael Espindola83a362c2015-01-06 22:55:16 +0000784 @foo = global i32 2, comdat($foo)
David Majnemerdad0a642014-06-27 18:19:56 +0000785
Rafael Espindola83a362c2015-01-06 22:55:16 +0000786 define void @bar() comdat($foo) {
David Majnemerdad0a642014-06-27 18:19:56 +0000787 ret void
788 }
789
Rafael Espindola83a362c2015-01-06 22:55:16 +0000790As a syntactic sugar the ``$name`` can be omitted if the name is the same as
791the global name:
792
793.. code-block:: llvm
794
795 $foo = comdat any
796 @foo = global i32 2, comdat
797
798
David Majnemerdad0a642014-06-27 18:19:56 +0000799In a COFF object file, this will create a COMDAT section with selection kind
800``IMAGE_COMDAT_SELECT_LARGEST`` containing the contents of the ``@foo`` symbol
801and another COMDAT section with selection kind
802``IMAGE_COMDAT_SELECT_ASSOCIATIVE`` which is associated with the first COMDAT
Hans Wennborg0def0662014-09-10 17:05:08 +0000803section and contains the contents of the ``@bar`` symbol.
David Majnemerdad0a642014-06-27 18:19:56 +0000804
805There are some restrictions on the properties of the global object.
806It, or an alias to it, must have the same name as the COMDAT group when
807targeting COFF.
808The contents and size of this object may be used during link-time to determine
809which COMDAT groups get selected depending on the selection kind.
810Because the name of the object must match the name of the COMDAT group, the
811linkage of the global object must not be local; local symbols can get renamed
812if a collision occurs in the symbol table.
813
814The combined use of COMDATS and section attributes may yield surprising results.
815For example:
816
817.. code-block:: llvm
818
819 $foo = comdat any
820 $bar = comdat any
Rafael Espindola83a362c2015-01-06 22:55:16 +0000821 @g1 = global i32 42, section "sec", comdat($foo)
822 @g2 = global i32 42, section "sec", comdat($bar)
David Majnemerdad0a642014-06-27 18:19:56 +0000823
824From the object file perspective, this requires the creation of two sections
Sean Silvaa1190322015-08-06 22:56:48 +0000825with the same name. This is necessary because both globals belong to different
David Majnemerdad0a642014-06-27 18:19:56 +0000826COMDAT groups and COMDATs, at the object file level, are represented by
827sections.
828
Peter Collingbourne1feef2e2015-06-30 19:10:31 +0000829Note that certain IR constructs like global variables and functions may
830create COMDATs in the object file in addition to any which are specified using
Sean Silvaa1190322015-08-06 22:56:48 +0000831COMDAT IR. This arises when the code generator is configured to emit globals
Peter Collingbourne1feef2e2015-06-30 19:10:31 +0000832in individual sections (e.g. when `-data-sections` or `-function-sections`
833is supplied to `llc`).
David Majnemerdad0a642014-06-27 18:19:56 +0000834
Sean Silvab084af42012-12-07 10:36:55 +0000835.. _namedmetadatastructure:
836
837Named Metadata
838--------------
839
840Named metadata is a collection of metadata. :ref:`Metadata
841nodes <metadata>` (but not metadata strings) are the only valid
842operands for a named metadata.
843
Filipe Cabecinhas62431b12015-06-02 21:25:08 +0000844#. Named metadata are represented as a string of characters with the
845 metadata prefix. The rules for metadata names are the same as for
846 identifiers, but quoted names are not allowed. ``"\xx"`` type escapes
847 are still valid, which allows any character to be part of a name.
848
Sean Silvab084af42012-12-07 10:36:55 +0000849Syntax::
850
851 ; Some unnamed metadata nodes, which are referenced by the named metadata.
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +0000852 !0 = !{!"zero"}
853 !1 = !{!"one"}
854 !2 = !{!"two"}
Sean Silvab084af42012-12-07 10:36:55 +0000855 ; A named metadata.
856 !name = !{!0, !1, !2}
857
858.. _paramattrs:
859
860Parameter Attributes
861--------------------
862
863The return type and each parameter of a function type may have a set of
864*parameter attributes* associated with them. Parameter attributes are
865used to communicate additional information about the result or
866parameters of a function. Parameter attributes are considered to be part
867of the function, not of the function type, so functions with different
868parameter attributes can have the same function type.
869
870Parameter attributes are simple keywords that follow the type specified.
871If multiple parameter attributes are needed, they are space separated.
872For example:
873
874.. code-block:: llvm
875
876 declare i32 @printf(i8* noalias nocapture, ...)
877 declare i32 @atoi(i8 zeroext)
878 declare signext i8 @returns_signed_char()
879
880Note that any attributes for the function result (``nounwind``,
881``readonly``) come immediately after the argument list.
882
883Currently, only the following parameter attributes are defined:
884
885``zeroext``
886 This indicates to the code generator that the parameter or return
887 value should be zero-extended to the extent required by the target's
888 ABI (which is usually 32-bits, but is 8-bits for a i1 on x86-64) by
889 the caller (for a parameter) or the callee (for a return value).
890``signext``
891 This indicates to the code generator that the parameter or return
892 value should be sign-extended to the extent required by the target's
893 ABI (which is usually 32-bits) by the caller (for a parameter) or
894 the callee (for a return value).
895``inreg``
896 This indicates that this parameter or return value should be treated
Sean Silva706fba52015-08-06 22:56:24 +0000897 in a special target-dependent fashion while emitting code for
Sean Silvab084af42012-12-07 10:36:55 +0000898 a function call or return (usually, by putting it in a register as
899 opposed to memory, though some targets use it to distinguish between
900 two different kinds of registers). Use of this attribute is
901 target-specific.
902``byval``
903 This indicates that the pointer parameter should really be passed by
904 value to the function. The attribute implies that a hidden copy of
905 the pointee is made between the caller and the callee, so the callee
906 is unable to modify the value in the caller. This attribute is only
907 valid on LLVM pointer arguments. It is generally used to pass
908 structs and arrays by value, but is also valid on pointers to
909 scalars. The copy is considered to belong to the caller not the
910 callee (for example, ``readonly`` functions should not write to
911 ``byval`` parameters). This is not a valid attribute for return
912 values.
913
914 The byval attribute also supports specifying an alignment with the
915 align attribute. It indicates the alignment of the stack slot to
916 form and the known alignment of the pointer specified to the call
917 site. If the alignment is not specified, then the code generator
918 makes a target-specific assumption.
919
Reid Klecknera534a382013-12-19 02:14:12 +0000920.. _attr_inalloca:
921
922``inalloca``
923
Reid Kleckner60d3a832014-01-16 22:59:24 +0000924 The ``inalloca`` argument attribute allows the caller to take the
Sean Silvaa1190322015-08-06 22:56:48 +0000925 address of outgoing stack arguments. An ``inalloca`` argument must
Reid Kleckner436c42e2014-01-17 23:58:17 +0000926 be a pointer to stack memory produced by an ``alloca`` instruction.
927 The alloca, or argument allocation, must also be tagged with the
Sean Silvaa1190322015-08-06 22:56:48 +0000928 inalloca keyword. Only the last argument may have the ``inalloca``
Reid Kleckner436c42e2014-01-17 23:58:17 +0000929 attribute, and that argument is guaranteed to be passed in memory.
Reid Klecknera534a382013-12-19 02:14:12 +0000930
Reid Kleckner436c42e2014-01-17 23:58:17 +0000931 An argument allocation may be used by a call at most once because
Sean Silvaa1190322015-08-06 22:56:48 +0000932 the call may deallocate it. The ``inalloca`` attribute cannot be
Reid Kleckner436c42e2014-01-17 23:58:17 +0000933 used in conjunction with other attributes that affect argument
Sean Silvaa1190322015-08-06 22:56:48 +0000934 storage, like ``inreg``, ``nest``, ``sret``, or ``byval``. The
Reid Klecknerf5b76512014-01-31 23:50:57 +0000935 ``inalloca`` attribute also disables LLVM's implicit lowering of
936 large aggregate return values, which means that frontend authors
937 must lower them with ``sret`` pointers.
Reid Klecknera534a382013-12-19 02:14:12 +0000938
Reid Kleckner60d3a832014-01-16 22:59:24 +0000939 When the call site is reached, the argument allocation must have
940 been the most recent stack allocation that is still live, or the
Sean Silvaa1190322015-08-06 22:56:48 +0000941 results are undefined. It is possible to allocate additional stack
Reid Kleckner60d3a832014-01-16 22:59:24 +0000942 space after an argument allocation and before its call site, but it
943 must be cleared off with :ref:`llvm.stackrestore
944 <int_stackrestore>`.
Reid Klecknera534a382013-12-19 02:14:12 +0000945
946 See :doc:`InAlloca` for more information on how to use this
947 attribute.
948
Sean Silvab084af42012-12-07 10:36:55 +0000949``sret``
950 This indicates that the pointer parameter specifies the address of a
951 structure that is the return value of the function in the source
952 program. This pointer must be guaranteed by the caller to be valid:
Eli Bendersky4f2162f2013-01-23 22:05:19 +0000953 loads and stores to the structure may be assumed by the callee
Sean Silvab084af42012-12-07 10:36:55 +0000954 not to trap and to be properly aligned. This may only be applied to
955 the first parameter. This is not a valid attribute for return
956 values.
Sean Silva1703e702014-04-08 21:06:22 +0000957
Hal Finkelccc70902014-07-22 16:58:55 +0000958``align <n>``
959 This indicates that the pointer value may be assumed by the optimizer to
960 have the specified alignment.
961
962 Note that this attribute has additional semantics when combined with the
963 ``byval`` attribute.
964
Sean Silva1703e702014-04-08 21:06:22 +0000965.. _noalias:
966
Sean Silvab084af42012-12-07 10:36:55 +0000967``noalias``
Hal Finkel12d36302014-11-21 02:22:46 +0000968 This indicates that objects accessed via pointer values
969 :ref:`based <pointeraliasing>` on the argument or return value are not also
970 accessed, during the execution of the function, via pointer values not
971 *based* on the argument or return value. The attribute on a return value
972 also has additional semantics described below. The caller shares the
973 responsibility with the callee for ensuring that these requirements are met.
974 For further details, please see the discussion of the NoAlias response in
975 :ref:`alias analysis <Must, May, or No>`.
Sean Silvab084af42012-12-07 10:36:55 +0000976
977 Note that this definition of ``noalias`` is intentionally similar
Hal Finkel12d36302014-11-21 02:22:46 +0000978 to the definition of ``restrict`` in C99 for function arguments.
Sean Silvab084af42012-12-07 10:36:55 +0000979
980 For function return values, C99's ``restrict`` is not meaningful,
Hal Finkel12d36302014-11-21 02:22:46 +0000981 while LLVM's ``noalias`` is. Furthermore, the semantics of the ``noalias``
982 attribute on return values are stronger than the semantics of the attribute
983 when used on function arguments. On function return values, the ``noalias``
984 attribute indicates that the function acts like a system memory allocation
985 function, returning a pointer to allocated storage disjoint from the
986 storage for any other object accessible to the caller.
987
Sean Silvab084af42012-12-07 10:36:55 +0000988``nocapture``
989 This indicates that the callee does not make any copies of the
990 pointer that outlive the callee itself. This is not a valid
991 attribute for return values.
992
993.. _nest:
994
995``nest``
996 This indicates that the pointer parameter can be excised using the
997 :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid
Stephen Linb8bd2322013-04-20 05:14:40 +0000998 attribute for return values and can only be applied to one parameter.
999
1000``returned``
Stephen Linfec5b0b2013-06-20 21:55:10 +00001001 This indicates that the function always returns the argument as its return
1002 value. This is an optimization hint to the code generator when generating
1003 the caller, allowing tail call optimization and omission of register saves
1004 and restores in some cases; it is not checked or enforced when generating
1005 the callee. The parameter and the function return type must be valid
1006 operands for the :ref:`bitcast instruction <i_bitcast>`. This is not a
1007 valid attribute for return values and can only be applied to one parameter.
Sean Silvab084af42012-12-07 10:36:55 +00001008
Nick Lewyckyd52b1522014-05-20 01:23:40 +00001009``nonnull``
1010 This indicates that the parameter or return pointer is not null. This
1011 attribute may only be applied to pointer typed parameters. This is not
1012 checked or enforced by LLVM, the caller must ensure that the pointer
Mehdi Amini4a121fa2015-03-14 22:04:06 +00001013 passed in is non-null, or the callee must ensure that the returned pointer
Nick Lewyckyd52b1522014-05-20 01:23:40 +00001014 is non-null.
1015
Hal Finkelb0407ba2014-07-18 15:51:28 +00001016``dereferenceable(<n>)``
1017 This indicates that the parameter or return pointer is dereferenceable. This
1018 attribute may only be applied to pointer typed parameters. A pointer that
1019 is dereferenceable can be loaded from speculatively without a risk of
1020 trapping. The number of bytes known to be dereferenceable must be provided
1021 in parentheses. It is legal for the number of bytes to be less than the
1022 size of the pointee type. The ``nonnull`` attribute does not imply
1023 dereferenceability (consider a pointer to one element past the end of an
1024 array), however ``dereferenceable(<n>)`` does imply ``nonnull`` in
1025 ``addrspace(0)`` (which is the default address space).
1026
Sanjoy Das31ea6d12015-04-16 20:29:50 +00001027``dereferenceable_or_null(<n>)``
1028 This indicates that the parameter or return value isn't both
1029 non-null and non-dereferenceable (up to ``<n>`` bytes) at the same
Sean Silvaa1190322015-08-06 22:56:48 +00001030 time. All non-null pointers tagged with
Sanjoy Das31ea6d12015-04-16 20:29:50 +00001031 ``dereferenceable_or_null(<n>)`` are ``dereferenceable(<n>)``.
1032 For address space 0 ``dereferenceable_or_null(<n>)`` implies that
1033 a pointer is exactly one of ``dereferenceable(<n>)`` or ``null``,
1034 and in other address spaces ``dereferenceable_or_null(<n>)``
1035 implies that a pointer is at least one of ``dereferenceable(<n>)``
1036 or ``null`` (i.e. it may be both ``null`` and
Sean Silvaa1190322015-08-06 22:56:48 +00001037 ``dereferenceable(<n>)``). This attribute may only be applied to
Sanjoy Das31ea6d12015-04-16 20:29:50 +00001038 pointer typed parameters.
1039
Sean Silvab084af42012-12-07 10:36:55 +00001040.. _gc:
1041
Philip Reamesf80bbff2015-02-25 23:45:20 +00001042Garbage Collector Strategy Names
1043--------------------------------
Sean Silvab084af42012-12-07 10:36:55 +00001044
Philip Reamesf80bbff2015-02-25 23:45:20 +00001045Each function may specify a garbage collector strategy name, which is simply a
Sean Silvab084af42012-12-07 10:36:55 +00001046string:
1047
1048.. code-block:: llvm
1049
1050 define void @f() gc "name" { ... }
1051
Mehdi Amini4a121fa2015-03-14 22:04:06 +00001052The supported values of *name* includes those :ref:`built in to LLVM
Sean Silvaa1190322015-08-06 22:56:48 +00001053<builtin-gc-strategies>` and any provided by loaded plugins. Specifying a GC
Mehdi Amini4a121fa2015-03-14 22:04:06 +00001054strategy will cause the compiler to alter its output in order to support the
Sean Silvaa1190322015-08-06 22:56:48 +00001055named garbage collection algorithm. Note that LLVM itself does not contain a
Philip Reamesf80bbff2015-02-25 23:45:20 +00001056garbage collector, this functionality is restricted to generating machine code
Mehdi Amini4a121fa2015-03-14 22:04:06 +00001057which can interoperate with a collector provided externally.
Sean Silvab084af42012-12-07 10:36:55 +00001058
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001059.. _prefixdata:
1060
1061Prefix Data
1062-----------
1063
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001064Prefix data is data associated with a function which the code
1065generator will emit immediately before the function's entrypoint.
1066The purpose of this feature is to allow frontends to associate
1067language-specific runtime metadata with specific functions and make it
1068available through the function pointer while still allowing the
1069function pointer to be called.
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001070
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001071To access the data for a given function, a program may bitcast the
1072function pointer to a pointer to the constant's type and dereference
Sean Silvaa1190322015-08-06 22:56:48 +00001073index -1. This implies that the IR symbol points just past the end of
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001074the prefix data. For instance, take the example of a function annotated
1075with a single ``i32``,
1076
1077.. code-block:: llvm
1078
1079 define void @f() prefix i32 123 { ... }
1080
1081The prefix data can be referenced as,
1082
1083.. code-block:: llvm
1084
David Blaikie16a97eb2015-03-04 22:02:58 +00001085 %0 = bitcast void* () @f to i32*
1086 %a = getelementptr inbounds i32, i32* %0, i32 -1
David Blaikiec7aabbb2015-03-04 22:06:14 +00001087 %b = load i32, i32* %a
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001088
1089Prefix data is laid out as if it were an initializer for a global variable
Sean Silvaa1190322015-08-06 22:56:48 +00001090of the prefix data's type. The function will be placed such that the
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001091beginning of the prefix data is aligned. This means that if the size
1092of the prefix data is not a multiple of the alignment size, the
1093function's entrypoint will not be aligned. If alignment of the
1094function's entrypoint is desired, padding must be added to the prefix
1095data.
1096
Sean Silvaa1190322015-08-06 22:56:48 +00001097A function may have prefix data but no body. This has similar semantics
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001098to the ``available_externally`` linkage in that the data may be used by the
1099optimizers but will not be emitted in the object file.
1100
1101.. _prologuedata:
1102
1103Prologue Data
1104-------------
1105
1106The ``prologue`` attribute allows arbitrary code (encoded as bytes) to
1107be inserted prior to the function body. This can be used for enabling
1108function hot-patching and instrumentation.
1109
1110To maintain the semantics of ordinary function calls, the prologue data must
Sean Silvaa1190322015-08-06 22:56:48 +00001111have a particular format. Specifically, it must begin with a sequence of
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001112bytes which decode to a sequence of machine instructions, valid for the
1113module's target, which transfer control to the point immediately succeeding
Sean Silvaa1190322015-08-06 22:56:48 +00001114the prologue data, without performing any other visible action. This allows
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001115the inliner and other passes to reason about the semantics of the function
Sean Silvaa1190322015-08-06 22:56:48 +00001116definition without needing to reason about the prologue data. Obviously this
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001117makes the format of the prologue data highly target dependent.
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001118
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001119A trivial example of valid prologue data for the x86 architecture is ``i8 144``,
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001120which encodes the ``nop`` instruction:
1121
1122.. code-block:: llvm
1123
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001124 define void @f() prologue i8 144 { ... }
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001125
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001126Generally prologue data can be formed by encoding a relative branch instruction
1127which skips the metadata, as in this example of valid prologue data for the
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001128x86_64 architecture, where the first two bytes encode ``jmp .+10``:
1129
1130.. code-block:: llvm
1131
1132 %0 = type <{ i8, i8, i8* }>
1133
Peter Collingbourne51d2de72014-12-03 02:08:38 +00001134 define void @f() prologue %0 <{ i8 235, i8 8, i8* @md}> { ... }
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001135
Sean Silvaa1190322015-08-06 22:56:48 +00001136A function may have prologue data but no body. This has similar semantics
Peter Collingbourne3fa50f92013-09-16 01:08:15 +00001137to the ``available_externally`` linkage in that the data may be used by the
1138optimizers but will not be emitted in the object file.
1139
David Majnemer7fddecc2015-06-17 20:52:32 +00001140.. _personalityfn:
1141
1142Personality Function
David Majnemerc5ad8a92015-06-17 21:21:16 +00001143--------------------
David Majnemer7fddecc2015-06-17 20:52:32 +00001144
1145The ``personality`` attribute permits functions to specify what function
1146to use for exception handling.
1147
Bill Wendling63b88192013-02-06 06:52:58 +00001148.. _attrgrp:
1149
1150Attribute Groups
1151----------------
1152
1153Attribute groups are groups of attributes that are referenced by objects within
1154the IR. They are important for keeping ``.ll`` files readable, because a lot of
1155functions will use the same set of attributes. In the degenerative case of a
1156``.ll`` file that corresponds to a single ``.c`` file, the single attribute
1157group will capture the important command line flags used to build that file.
1158
1159An attribute group is a module-level object. To use an attribute group, an
1160object references the attribute group's ID (e.g. ``#37``). An object may refer
1161to more than one attribute group. In that situation, the attributes from the
1162different groups are merged.
1163
1164Here is an example of attribute groups for a function that should always be
1165inlined, has a stack alignment of 4, and which shouldn't use SSE instructions:
1166
1167.. code-block:: llvm
1168
1169 ; Target-independent attributes:
Eli Bendersky97ad9242013-04-18 16:11:44 +00001170 attributes #0 = { alwaysinline alignstack=4 }
Bill Wendling63b88192013-02-06 06:52:58 +00001171
1172 ; Target-dependent attributes:
Eli Bendersky97ad9242013-04-18 16:11:44 +00001173 attributes #1 = { "no-sse" }
Bill Wendling63b88192013-02-06 06:52:58 +00001174
1175 ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse".
1176 define void @f() #0 #1 { ... }
1177
Sean Silvab084af42012-12-07 10:36:55 +00001178.. _fnattrs:
1179
1180Function Attributes
1181-------------------
1182
1183Function attributes are set to communicate additional information about
1184a function. Function attributes are considered to be part of the
1185function, not of the function type, so functions with different function
1186attributes can have the same function type.
1187
1188Function attributes are simple keywords that follow the type specified.
1189If multiple attributes are needed, they are space separated. For
1190example:
1191
1192.. code-block:: llvm
1193
1194 define void @f() noinline { ... }
1195 define void @f() alwaysinline { ... }
1196 define void @f() alwaysinline optsize { ... }
1197 define void @f() optsize { ... }
1198
Sean Silvab084af42012-12-07 10:36:55 +00001199``alignstack(<n>)``
1200 This attribute indicates that, when emitting the prologue and
1201 epilogue, the backend should forcibly align the stack pointer.
1202 Specify the desired alignment, which must be a power of two, in
1203 parentheses.
1204``alwaysinline``
1205 This attribute indicates that the inliner should attempt to inline
1206 this function into callers whenever possible, ignoring any active
1207 inlining size threshold for this caller.
Michael Gottesman41748d72013-06-27 00:25:01 +00001208``builtin``
1209 This indicates that the callee function at a call site should be
1210 recognized as a built-in function, even though the function's declaration
Michael Gottesman3a6a9672013-07-02 21:32:56 +00001211 uses the ``nobuiltin`` attribute. This is only valid at call sites for
Richard Smith32dbdf62014-07-31 04:25:36 +00001212 direct calls to functions that are declared with the ``nobuiltin``
Michael Gottesman41748d72013-06-27 00:25:01 +00001213 attribute.
Michael Gottesman296adb82013-06-27 22:48:08 +00001214``cold``
1215 This attribute indicates that this function is rarely called. When
1216 computing edge weights, basic blocks post-dominated by a cold
1217 function call are also considered to be cold; and, thus, given low
1218 weight.
Owen Anderson85fa7d52015-05-26 23:48:40 +00001219``convergent``
1220 This attribute indicates that the callee is dependent on a convergent
1221 thread execution pattern under certain parallel execution models.
1222 Transformations that are execution model agnostic may only move or
1223 tranform this call if the final location is control equivalent to its
1224 original position in the program, where control equivalence is defined as
1225 A dominates B and B post-dominates A, or vice versa.
Sean Silvab084af42012-12-07 10:36:55 +00001226``inlinehint``
1227 This attribute indicates that the source code contained a hint that
1228 inlining this function is desirable (such as the "inline" keyword in
1229 C/C++). It is just a hint; it imposes no requirements on the
1230 inliner.
Tom Roeder44cb65f2014-06-05 19:29:43 +00001231``jumptable``
1232 This attribute indicates that the function should be added to a
1233 jump-instruction table at code-generation time, and that all address-taken
1234 references to this function should be replaced with a reference to the
1235 appropriate jump-instruction-table function pointer. Note that this creates
1236 a new pointer for the original function, which means that code that depends
1237 on function-pointer identity can break. So, any function annotated with
1238 ``jumptable`` must also be ``unnamed_addr``.
Andrea Di Biagio9b5d23b2013-08-09 18:42:18 +00001239``minsize``
1240 This attribute suggests that optimization passes and code generator
1241 passes make choices that keep the code size of this function as small
Andrew Trickd4d1d9c2013-10-31 17:18:07 +00001242 as possible and perform optimizations that may sacrifice runtime
Andrea Di Biagio9b5d23b2013-08-09 18:42:18 +00001243 performance in order to minimize the size of the generated code.
Sean Silvab084af42012-12-07 10:36:55 +00001244``naked``
1245 This attribute disables prologue / epilogue emission for the
1246 function. This can have very system-specific consequences.
Eli Bendersky97ad9242013-04-18 16:11:44 +00001247``nobuiltin``
Michael Gottesman41748d72013-06-27 00:25:01 +00001248 This indicates that the callee function at a call site is not recognized as
1249 a built-in function. LLVM will retain the original call and not replace it
1250 with equivalent code based on the semantics of the built-in function, unless
1251 the call site uses the ``builtin`` attribute. This is valid at call sites
1252 and on function declarations and definitions.
Bill Wendlingbf902f12013-02-06 06:22:58 +00001253``noduplicate``
1254 This attribute indicates that calls to the function cannot be
1255 duplicated. A call to a ``noduplicate`` function may be moved
1256 within its parent function, but may not be duplicated within
1257 its parent function.
1258
1259 A function containing a ``noduplicate`` call may still
1260 be an inlining candidate, provided that the call is not
1261 duplicated by inlining. That implies that the function has
1262 internal linkage and only has one call site, so the original
1263 call is dead after inlining.
Sean Silvab084af42012-12-07 10:36:55 +00001264``noimplicitfloat``
1265 This attributes disables implicit floating point instructions.
1266``noinline``
1267 This attribute indicates that the inliner should never inline this
1268 function in any situation. This attribute may not be used together
1269 with the ``alwaysinline`` attribute.
Sean Silva1cbbcf12013-08-06 19:34:37 +00001270``nonlazybind``
1271 This attribute suppresses lazy symbol binding for the function. This
1272 may make calls to the function faster, at the cost of extra program
1273 startup time if the function is not called during program startup.
Sean Silvab084af42012-12-07 10:36:55 +00001274``noredzone``
1275 This attribute indicates that the code generator should not use a
1276 red zone, even if the target-specific ABI normally permits it.
1277``noreturn``
1278 This function attribute indicates that the function never returns
1279 normally. This produces undefined behavior at runtime if the
1280 function ever does dynamically return.
1281``nounwind``
Reid Kleckner96d01132015-02-11 01:23:16 +00001282 This function attribute indicates that the function never raises an
1283 exception. If the function does raise an exception, its runtime
1284 behavior is undefined. However, functions marked nounwind may still
1285 trap or generate asynchronous exceptions. Exception handling schemes
1286 that are recognized by LLVM to handle asynchronous exceptions, such
1287 as SEH, will still provide their implementation defined semantics.
Andrea Di Biagio377496b2013-08-23 11:53:55 +00001288``optnone``
1289 This function attribute indicates that the function is not optimized
Andrew Trickd4d1d9c2013-10-31 17:18:07 +00001290 by any optimization or code generator passes with the
Andrea Di Biagio377496b2013-08-23 11:53:55 +00001291 exception of interprocedural optimization passes.
1292 This attribute cannot be used together with the ``alwaysinline``
1293 attribute; this attribute is also incompatible
1294 with the ``minsize`` attribute and the ``optsize`` attribute.
Andrew Trickd4d1d9c2013-10-31 17:18:07 +00001295
Paul Robinsondcbe35b2013-11-18 21:44:03 +00001296 This attribute requires the ``noinline`` attribute to be specified on
1297 the function as well, so the function is never inlined into any caller.
Andrea Di Biagio377496b2013-08-23 11:53:55 +00001298 Only functions with the ``alwaysinline`` attribute are valid
Paul Robinsondcbe35b2013-11-18 21:44:03 +00001299 candidates for inlining into the body of this function.
Sean Silvab084af42012-12-07 10:36:55 +00001300``optsize``
1301 This attribute suggests that optimization passes and code generator
1302 passes make choices that keep the code size of this function low,
Andrea Di Biagio9b5d23b2013-08-09 18:42:18 +00001303 and otherwise do optimizations specifically to reduce code size as
1304 long as they do not significantly impact runtime performance.
Sean Silvab084af42012-12-07 10:36:55 +00001305``readnone``
Nick Lewyckyc2ec0722013-07-06 00:29:58 +00001306 On a function, this attribute indicates that the function computes its
1307 result (or decides to unwind an exception) based strictly on its arguments,
Sean Silvab084af42012-12-07 10:36:55 +00001308 without dereferencing any pointer arguments or otherwise accessing
1309 any mutable state (e.g. memory, control registers, etc) visible to
1310 caller functions. It does not write through any pointer arguments
1311 (including ``byval`` arguments) and never changes any state visible
1312 to callers. This means that it cannot unwind exceptions by calling
1313 the ``C++`` exception throwing methods.
Andrew Trickd4d1d9c2013-10-31 17:18:07 +00001314
Nick Lewyckyc2ec0722013-07-06 00:29:58 +00001315 On an argument, this attribute indicates that the function does not
1316 dereference that pointer argument, even though it may read or write the
Nick Lewyckyefe31f22013-07-06 01:04:47 +00001317 memory that the pointer points to if accessed through other pointers.
Sean Silvab084af42012-12-07 10:36:55 +00001318``readonly``
Nick Lewyckyc2ec0722013-07-06 00:29:58 +00001319 On a function, this attribute indicates that the function does not write
1320 through any pointer arguments (including ``byval`` arguments) or otherwise
Sean Silvab084af42012-12-07 10:36:55 +00001321 modify any state (e.g. memory, control registers, etc) visible to
1322 caller functions. It may dereference pointer arguments and read
1323 state that may be set in the caller. A readonly function always
1324 returns the same value (or unwinds an exception identically) when
1325 called with the same set of arguments and global state. It cannot
1326 unwind an exception by calling the ``C++`` exception throwing
1327 methods.
Andrew Trickd4d1d9c2013-10-31 17:18:07 +00001328
Nick Lewyckyc2ec0722013-07-06 00:29:58 +00001329 On an argument, this attribute indicates that the function does not write
1330 through this pointer argument, even though it may write to the memory that
1331 the pointer points to.
Igor Laevsky39d662f2015-07-11 10:30:36 +00001332``argmemonly``
1333 This attribute indicates that the only memory accesses inside function are
1334 loads and stores from objects pointed to by its pointer-typed arguments,
1335 with arbitrary offsets. Or in other words, all memory operations in the
1336 function can refer to memory only using pointers based on its function
1337 arguments.
1338 Note that ``argmemonly`` can be used together with ``readonly`` attribute
1339 in order to specify that function reads only from its arguments.
Sean Silvab084af42012-12-07 10:36:55 +00001340``returns_twice``
1341 This attribute indicates that this function can return twice. The C
1342 ``setjmp`` is an example of such a function. The compiler disables
1343 some optimizations (like tail calls) in the caller of these
1344 functions.
Peter Collingbourne82437bf2015-06-15 21:07:11 +00001345``safestack``
1346 This attribute indicates that
1347 `SafeStack <http://clang.llvm.org/docs/SafeStack.html>`_
1348 protection is enabled for this function.
1349
1350 If a function that has a ``safestack`` attribute is inlined into a
1351 function that doesn't have a ``safestack`` attribute or which has an
1352 ``ssp``, ``sspstrong`` or ``sspreq`` attribute, then the resulting
1353 function will have a ``safestack`` attribute.
Kostya Serebryanycf880b92013-02-26 06:58:09 +00001354``sanitize_address``
1355 This attribute indicates that AddressSanitizer checks
1356 (dynamic address safety analysis) are enabled for this function.
1357``sanitize_memory``
1358 This attribute indicates that MemorySanitizer checks (dynamic detection
1359 of accesses to uninitialized memory) are enabled for this function.
1360``sanitize_thread``
1361 This attribute indicates that ThreadSanitizer checks
1362 (dynamic thread safety analysis) are enabled for this function.
Sean Silvab084af42012-12-07 10:36:55 +00001363``ssp``
1364 This attribute indicates that the function should emit a stack
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00001365 smashing protector. It is in the form of a "canary" --- a random value
Sean Silvab084af42012-12-07 10:36:55 +00001366 placed on the stack before the local variables that's checked upon
1367 return from the function to see if it has been overwritten. A
1368 heuristic is used to determine if a function needs stack protectors
Bill Wendling7c8f96a2013-01-23 06:43:53 +00001369 or not. The heuristic used will enable protectors for functions with:
Dmitri Gribenko69b56472013-01-29 23:14:41 +00001370
Bill Wendling7c8f96a2013-01-23 06:43:53 +00001371 - Character arrays larger than ``ssp-buffer-size`` (default 8).
1372 - Aggregates containing character arrays larger than ``ssp-buffer-size``.
1373 - Calls to alloca() with variable sizes or constant sizes greater than
1374 ``ssp-buffer-size``.
Sean Silvab084af42012-12-07 10:36:55 +00001375
Josh Magee24c7f062014-02-01 01:36:16 +00001376 Variables that are identified as requiring a protector will be arranged
1377 on the stack such that they are adjacent to the stack protector guard.
1378
Sean Silvab084af42012-12-07 10:36:55 +00001379 If a function that has an ``ssp`` attribute is inlined into a
1380 function that doesn't have an ``ssp`` attribute, then the resulting
1381 function will have an ``ssp`` attribute.
1382``sspreq``
1383 This attribute indicates that the function should *always* emit a
1384 stack smashing protector. This overrides the ``ssp`` function
1385 attribute.
1386
Josh Magee24c7f062014-02-01 01:36:16 +00001387 Variables that are identified as requiring a protector will be arranged
1388 on the stack such that they are adjacent to the stack protector guard.
1389 The specific layout rules are:
1390
1391 #. Large arrays and structures containing large arrays
1392 (``>= ssp-buffer-size``) are closest to the stack protector.
1393 #. Small arrays and structures containing small arrays
1394 (``< ssp-buffer-size``) are 2nd closest to the protector.
1395 #. Variables that have had their address taken are 3rd closest to the
1396 protector.
1397
Sean Silvab084af42012-12-07 10:36:55 +00001398 If a function that has an ``sspreq`` attribute is inlined into a
1399 function that doesn't have an ``sspreq`` attribute or which has an
Bill Wendlingd154e2832013-01-23 06:41:41 +00001400 ``ssp`` or ``sspstrong`` attribute, then the resulting function will have
1401 an ``sspreq`` attribute.
1402``sspstrong``
1403 This attribute indicates that the function should emit a stack smashing
Bill Wendling7c8f96a2013-01-23 06:43:53 +00001404 protector. This attribute causes a strong heuristic to be used when
Sean Silvaa1190322015-08-06 22:56:48 +00001405 determining if a function needs stack protectors. The strong heuristic
Bill Wendling7c8f96a2013-01-23 06:43:53 +00001406 will enable protectors for functions with:
Dmitri Gribenko69b56472013-01-29 23:14:41 +00001407
Bill Wendling7c8f96a2013-01-23 06:43:53 +00001408 - Arrays of any size and type
1409 - Aggregates containing an array of any size and type.
1410 - Calls to alloca().
1411 - Local variables that have had their address taken.
1412
Josh Magee24c7f062014-02-01 01:36:16 +00001413 Variables that are identified as requiring a protector will be arranged
1414 on the stack such that they are adjacent to the stack protector guard.
1415 The specific layout rules are:
1416
1417 #. Large arrays and structures containing large arrays
1418 (``>= ssp-buffer-size``) are closest to the stack protector.
1419 #. Small arrays and structures containing small arrays
1420 (``< ssp-buffer-size``) are 2nd closest to the protector.
1421 #. Variables that have had their address taken are 3rd closest to the
1422 protector.
1423
Bill Wendling7c8f96a2013-01-23 06:43:53 +00001424 This overrides the ``ssp`` function attribute.
Bill Wendlingd154e2832013-01-23 06:41:41 +00001425
1426 If a function that has an ``sspstrong`` attribute is inlined into a
1427 function that doesn't have an ``sspstrong`` attribute, then the
1428 resulting function will have an ``sspstrong`` attribute.
Reid Kleckner5a2ab2b2015-03-04 00:08:56 +00001429``"thunk"``
1430 This attribute indicates that the function will delegate to some other
1431 function with a tail call. The prototype of a thunk should not be used for
1432 optimization purposes. The caller is expected to cast the thunk prototype to
1433 match the thunk target prototype.
Sean Silvab084af42012-12-07 10:36:55 +00001434``uwtable``
1435 This attribute indicates that the ABI being targeted requires that
Sean Silva706fba52015-08-06 22:56:24 +00001436 an unwind table entry be produced for this function even if we can
Sean Silvab084af42012-12-07 10:36:55 +00001437 show that no exceptions passes by it. This is normally the case for
1438 the ELF x86-64 abi, but it can be disabled for some compilation
1439 units.
Sean Silvab084af42012-12-07 10:36:55 +00001440
1441.. _moduleasm:
1442
1443Module-Level Inline Assembly
1444----------------------------
1445
1446Modules may contain "module-level inline asm" blocks, which corresponds
1447to the GCC "file scope inline asm" blocks. These blocks are internally
1448concatenated by LLVM and treated as a single unit, but may be separated
1449in the ``.ll`` file if desired. The syntax is very simple:
1450
1451.. code-block:: llvm
1452
1453 module asm "inline asm code goes here"
1454 module asm "more can go here"
1455
1456The strings can contain any character by escaping non-printable
1457characters. The escape sequence used is simply "\\xx" where "xx" is the
1458two digit hex code for the number.
1459
James Y Knightbc832ed2015-07-08 18:08:36 +00001460Note that the assembly string *must* be parseable by LLVM's integrated assembler
1461(unless it is disabled), even when emitting a ``.s`` file.
Sean Silvab084af42012-12-07 10:36:55 +00001462
Eli Benderskyfdc529a2013-06-07 19:40:08 +00001463.. _langref_datalayout:
1464
Sean Silvab084af42012-12-07 10:36:55 +00001465Data Layout
1466-----------
1467
1468A module may specify a target specific data layout string that specifies
1469how data is to be laid out in memory. The syntax for the data layout is
1470simply:
1471
1472.. code-block:: llvm
1473
1474 target datalayout = "layout specification"
1475
1476The *layout specification* consists of a list of specifications
1477separated by the minus sign character ('-'). Each specification starts
1478with a letter and may include other information after the letter to
1479define some aspect of the data layout. The specifications accepted are
1480as follows:
1481
1482``E``
1483 Specifies that the target lays out data in big-endian form. That is,
1484 the bits with the most significance have the lowest address
1485 location.
1486``e``
1487 Specifies that the target lays out data in little-endian form. That
1488 is, the bits with the least significance have the lowest address
1489 location.
1490``S<size>``
1491 Specifies the natural alignment of the stack in bits. Alignment
1492 promotion of stack variables is limited to the natural stack
1493 alignment to avoid dynamic stack realignment. The stack alignment
1494 must be a multiple of 8-bits. If omitted, the natural stack
1495 alignment defaults to "unspecified", which does not prevent any
1496 alignment promotions.
1497``p[n]:<size>:<abi>:<pref>``
1498 This specifies the *size* of a pointer and its ``<abi>`` and
1499 ``<pref>``\erred alignments for address space ``n``. All sizes are in
Sean Silva706fba52015-08-06 22:56:24 +00001500 bits. The address space, ``n``, is optional, and if not specified,
Sean Silvaa1190322015-08-06 22:56:48 +00001501 denotes the default address space 0. The value of ``n`` must be
Rafael Espindolaabdd7262014-01-06 21:40:24 +00001502 in the range [1,2^23).
Sean Silvab084af42012-12-07 10:36:55 +00001503``i<size>:<abi>:<pref>``
1504 This specifies the alignment for an integer type of a given bit
1505 ``<size>``. The value of ``<size>`` must be in the range [1,2^23).
1506``v<size>:<abi>:<pref>``
1507 This specifies the alignment for a vector type of a given bit
1508 ``<size>``.
1509``f<size>:<abi>:<pref>``
1510 This specifies the alignment for a floating point type of a given bit
1511 ``<size>``. Only values of ``<size>`` that are supported by the target
1512 will work. 32 (float) and 64 (double) are supported on all targets; 80
1513 or 128 (different flavors of long double) are also supported on some
1514 targets.
Rafael Espindolaabdd7262014-01-06 21:40:24 +00001515``a:<abi>:<pref>``
1516 This specifies the alignment for an object of aggregate type.
Rafael Espindola58873562014-01-03 19:21:54 +00001517``m:<mangling>``
Hans Wennborgd4245ac2014-01-15 02:49:17 +00001518 If present, specifies that llvm names are mangled in the output. The
1519 options are
1520
1521 * ``e``: ELF mangling: Private symbols get a ``.L`` prefix.
1522 * ``m``: Mips mangling: Private symbols get a ``$`` prefix.
1523 * ``o``: Mach-O mangling: Private symbols get ``L`` prefix. Other
1524 symbols get a ``_`` prefix.
1525 * ``w``: Windows COFF prefix: Similar to Mach-O, but stdcall and fastcall
1526 functions also get a suffix based on the frame size.
Sean Silvab084af42012-12-07 10:36:55 +00001527``n<size1>:<size2>:<size3>...``
1528 This specifies a set of native integer widths for the target CPU in
1529 bits. For example, it might contain ``n32`` for 32-bit PowerPC,
1530 ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of
1531 this set are considered to support most general arithmetic operations
1532 efficiently.
1533
Rafael Espindolaabdd7262014-01-06 21:40:24 +00001534On every specification that takes a ``<abi>:<pref>``, specifying the
1535``<pref>`` alignment is optional. If omitted, the preceding ``:``
1536should be omitted too and ``<pref>`` will be equal to ``<abi>``.
1537
Sean Silvab084af42012-12-07 10:36:55 +00001538When constructing the data layout for a given target, LLVM starts with a
1539default set of specifications which are then (possibly) overridden by
1540the specifications in the ``datalayout`` keyword. The default
1541specifications are given in this list:
1542
1543- ``E`` - big endian
Matt Arsenault24b49c42013-07-31 17:49:08 +00001544- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment.
1545- ``p[n]:64:64:64`` - Other address spaces are assumed to be the
1546 same as the default address space.
Patrik Hagglunda832ab12013-01-30 09:02:06 +00001547- ``S0`` - natural stack alignment is unspecified
Sean Silvab084af42012-12-07 10:36:55 +00001548- ``i1:8:8`` - i1 is 8-bit (byte) aligned
1549- ``i8:8:8`` - i8 is 8-bit (byte) aligned
1550- ``i16:16:16`` - i16 is 16-bit aligned
1551- ``i32:32:32`` - i32 is 32-bit aligned
1552- ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred
1553 alignment of 64-bits
Patrik Hagglunda832ab12013-01-30 09:02:06 +00001554- ``f16:16:16`` - half is 16-bit aligned
Sean Silvab084af42012-12-07 10:36:55 +00001555- ``f32:32:32`` - float is 32-bit aligned
1556- ``f64:64:64`` - double is 64-bit aligned
Patrik Hagglunda832ab12013-01-30 09:02:06 +00001557- ``f128:128:128`` - quad is 128-bit aligned
Sean Silvab084af42012-12-07 10:36:55 +00001558- ``v64:64:64`` - 64-bit vector is 64-bit aligned
1559- ``v128:128:128`` - 128-bit vector is 128-bit aligned
Rafael Espindolae8f4d582013-12-12 17:21:51 +00001560- ``a:0:64`` - aggregates are 64-bit aligned
Sean Silvab084af42012-12-07 10:36:55 +00001561
1562When LLVM is determining the alignment for a given type, it uses the
1563following rules:
1564
1565#. If the type sought is an exact match for one of the specifications,
1566 that specification is used.
1567#. If no match is found, and the type sought is an integer type, then
1568 the smallest integer type that is larger than the bitwidth of the
1569 sought type is used. If none of the specifications are larger than
1570 the bitwidth then the largest integer type is used. For example,
1571 given the default specifications above, the i7 type will use the
1572 alignment of i8 (next largest) while both i65 and i256 will use the
1573 alignment of i64 (largest specified).
1574#. If no match is found, and the type sought is a vector type, then the
1575 largest vector type that is smaller than the sought vector type will
1576 be used as a fall back. This happens because <128 x double> can be
1577 implemented in terms of 64 <2 x double>, for example.
1578
1579The function of the data layout string may not be what you expect.
1580Notably, this is not a specification from the frontend of what alignment
1581the code generator should use.
1582
1583Instead, if specified, the target data layout is required to match what
1584the ultimate *code generator* expects. This string is used by the
1585mid-level optimizers to improve code, and this only works if it matches
Mehdi Amini4a121fa2015-03-14 22:04:06 +00001586what the ultimate code generator uses. There is no way to generate IR
1587that does not embed this target-specific detail into the IR. If you
1588don't specify the string, the default specifications will be used to
1589generate a Data Layout and the optimization phases will operate
1590accordingly and introduce target specificity into the IR with respect to
1591these default specifications.
Sean Silvab084af42012-12-07 10:36:55 +00001592
Bill Wendling5cc90842013-10-18 23:41:25 +00001593.. _langref_triple:
1594
1595Target Triple
1596-------------
1597
1598A module may specify a target triple string that describes the target
1599host. The syntax for the target triple is simply:
1600
1601.. code-block:: llvm
1602
1603 target triple = "x86_64-apple-macosx10.7.0"
1604
1605The *target triple* string consists of a series of identifiers delimited
1606by the minus sign character ('-'). The canonical forms are:
1607
1608::
1609
1610 ARCHITECTURE-VENDOR-OPERATING_SYSTEM
1611 ARCHITECTURE-VENDOR-OPERATING_SYSTEM-ENVIRONMENT
1612
1613This information is passed along to the backend so that it generates
1614code for the proper architecture. It's possible to override this on the
1615command line with the ``-mtriple`` command line option.
1616
Sean Silvab084af42012-12-07 10:36:55 +00001617.. _pointeraliasing:
1618
1619Pointer Aliasing Rules
1620----------------------
1621
1622Any memory access must be done through a pointer value associated with
1623an address range of the memory access, otherwise the behavior is
1624undefined. Pointer values are associated with address ranges according
1625to the following rules:
1626
1627- A pointer value is associated with the addresses associated with any
1628 value it is *based* on.
1629- An address of a global variable is associated with the address range
1630 of the variable's storage.
1631- The result value of an allocation instruction is associated with the
1632 address range of the allocated storage.
1633- A null pointer in the default address-space is associated with no
1634 address.
1635- An integer constant other than zero or a pointer value returned from
1636 a function not defined within LLVM may be associated with address
1637 ranges allocated through mechanisms other than those provided by
1638 LLVM. Such ranges shall not overlap with any ranges of addresses
1639 allocated by mechanisms provided by LLVM.
1640
1641A pointer value is *based* on another pointer value according to the
1642following rules:
1643
1644- A pointer value formed from a ``getelementptr`` operation is *based*
David Blaikie16a97eb2015-03-04 22:02:58 +00001645 on the first value operand of the ``getelementptr``.
Sean Silvab084af42012-12-07 10:36:55 +00001646- The result value of a ``bitcast`` is *based* on the operand of the
1647 ``bitcast``.
1648- A pointer value formed by an ``inttoptr`` is *based* on all pointer
1649 values that contribute (directly or indirectly) to the computation of
1650 the pointer's value.
1651- The "*based* on" relationship is transitive.
1652
1653Note that this definition of *"based"* is intentionally similar to the
1654definition of *"based"* in C99, though it is slightly weaker.
1655
1656LLVM IR does not associate types with memory. The result type of a
1657``load`` merely indicates the size and alignment of the memory from
1658which to load, as well as the interpretation of the value. The first
1659operand type of a ``store`` similarly only indicates the size and
1660alignment of the store.
1661
1662Consequently, type-based alias analysis, aka TBAA, aka
1663``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR.
1664:ref:`Metadata <metadata>` may be used to encode additional information
1665which specialized optimization passes may use to implement type-based
1666alias analysis.
1667
1668.. _volatile:
1669
1670Volatile Memory Accesses
1671------------------------
1672
1673Certain memory accesses, such as :ref:`load <i_load>`'s,
1674:ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be
1675marked ``volatile``. The optimizers must not change the number of
1676volatile operations or change their order of execution relative to other
1677volatile operations. The optimizers *may* change the order of volatile
1678operations relative to non-volatile operations. This is not Java's
1679"volatile" and has no cross-thread synchronization behavior.
1680
Andrew Trick89fc5a62013-01-30 21:19:35 +00001681IR-level volatile loads and stores cannot safely be optimized into
1682llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are
1683flagged volatile. Likewise, the backend should never split or merge
1684target-legal volatile load/store instructions.
1685
Andrew Trick7e6f9282013-01-31 00:49:39 +00001686.. admonition:: Rationale
1687
1688 Platforms may rely on volatile loads and stores of natively supported
1689 data width to be executed as single instruction. For example, in C
1690 this holds for an l-value of volatile primitive type with native
1691 hardware support, but not necessarily for aggregate types. The
1692 frontend upholds these expectations, which are intentionally
Sean Silva706fba52015-08-06 22:56:24 +00001693 unspecified in the IR. The rules above ensure that IR transformations
Andrew Trick7e6f9282013-01-31 00:49:39 +00001694 do not violate the frontend's contract with the language.
1695
Sean Silvab084af42012-12-07 10:36:55 +00001696.. _memmodel:
1697
1698Memory Model for Concurrent Operations
1699--------------------------------------
1700
1701The LLVM IR does not define any way to start parallel threads of
1702execution or to register signal handlers. Nonetheless, there are
1703platform-specific ways to create them, and we define LLVM IR's behavior
1704in their presence. This model is inspired by the C++0x memory model.
1705
1706For a more informal introduction to this model, see the :doc:`Atomics`.
1707
1708We define a *happens-before* partial order as the least partial order
1709that
1710
1711- Is a superset of single-thread program order, and
1712- When a *synchronizes-with* ``b``, includes an edge from ``a`` to
1713 ``b``. *Synchronizes-with* pairs are introduced by platform-specific
1714 techniques, like pthread locks, thread creation, thread joining,
1715 etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering
1716 Constraints <ordering>`).
1717
1718Note that program order does not introduce *happens-before* edges
1719between a thread and signals executing inside that thread.
1720
1721Every (defined) read operation (load instructions, memcpy, atomic
1722loads/read-modify-writes, etc.) R reads a series of bytes written by
1723(defined) write operations (store instructions, atomic
1724stores/read-modify-writes, memcpy, etc.). For the purposes of this
1725section, initialized globals are considered to have a write of the
1726initializer which is atomic and happens before any other read or write
1727of the memory in question. For each byte of a read R, R\ :sub:`byte`
1728may see any write to the same byte, except:
1729
1730- If write\ :sub:`1` happens before write\ :sub:`2`, and
1731 write\ :sub:`2` happens before R\ :sub:`byte`, then
1732 R\ :sub:`byte` does not see write\ :sub:`1`.
1733- If R\ :sub:`byte` happens before write\ :sub:`3`, then
1734 R\ :sub:`byte` does not see write\ :sub:`3`.
1735
1736Given that definition, R\ :sub:`byte` is defined as follows:
1737
1738- If R is volatile, the result is target-dependent. (Volatile is
1739 supposed to give guarantees which can support ``sig_atomic_t`` in
Richard Smith32dbdf62014-07-31 04:25:36 +00001740 C/C++, and may be used for accesses to addresses that do not behave
Sean Silvab084af42012-12-07 10:36:55 +00001741 like normal memory. It does not generally provide cross-thread
1742 synchronization.)
1743- Otherwise, if there is no write to the same byte that happens before
1744 R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte.
1745- Otherwise, if R\ :sub:`byte` may see exactly one write,
1746 R\ :sub:`byte` returns the value written by that write.
1747- Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may
1748 see are atomic, it chooses one of the values written. See the :ref:`Atomic
1749 Memory Ordering Constraints <ordering>` section for additional
1750 constraints on how the choice is made.
1751- Otherwise R\ :sub:`byte` returns ``undef``.
1752
1753R returns the value composed of the series of bytes it read. This
1754implies that some bytes within the value may be ``undef`` **without**
1755the entire value being ``undef``. Note that this only defines the
1756semantics of the operation; it doesn't mean that targets will emit more
1757than one instruction to read the series of bytes.
1758
1759Note that in cases where none of the atomic intrinsics are used, this
1760model places only one restriction on IR transformations on top of what
1761is required for single-threaded execution: introducing a store to a byte
1762which might not otherwise be stored is not allowed in general.
1763(Specifically, in the case where another thread might write to and read
1764from an address, introducing a store can change a load that may see
1765exactly one write into a load that may see multiple writes.)
1766
1767.. _ordering:
1768
1769Atomic Memory Ordering Constraints
1770----------------------------------
1771
1772Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`,
1773:ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`,
1774:ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take
Tim Northovere94a5182014-03-11 10:48:52 +00001775ordering parameters that determine which other atomic instructions on
Sean Silvab084af42012-12-07 10:36:55 +00001776the same address they *synchronize with*. These semantics are borrowed
1777from Java and C++0x, but are somewhat more colloquial. If these
1778descriptions aren't precise enough, check those specs (see spec
1779references in the :doc:`atomics guide <Atomics>`).
1780:ref:`fence <i_fence>` instructions treat these orderings somewhat
1781differently since they don't take an address. See that instruction's
1782documentation for details.
1783
1784For a simpler introduction to the ordering constraints, see the
1785:doc:`Atomics`.
1786
1787``unordered``
1788 The set of values that can be read is governed by the happens-before
1789 partial order. A value cannot be read unless some operation wrote
1790 it. This is intended to provide a guarantee strong enough to model
1791 Java's non-volatile shared variables. This ordering cannot be
1792 specified for read-modify-write operations; it is not strong enough
1793 to make them atomic in any interesting way.
1794``monotonic``
1795 In addition to the guarantees of ``unordered``, there is a single
1796 total order for modifications by ``monotonic`` operations on each
1797 address. All modification orders must be compatible with the
1798 happens-before order. There is no guarantee that the modification
1799 orders can be combined to a global total order for the whole program
1800 (and this often will not be possible). The read in an atomic
1801 read-modify-write operation (:ref:`cmpxchg <i_cmpxchg>` and
1802 :ref:`atomicrmw <i_atomicrmw>`) reads the value in the modification
1803 order immediately before the value it writes. If one atomic read
1804 happens before another atomic read of the same address, the later
1805 read must see the same value or a later value in the address's
1806 modification order. This disallows reordering of ``monotonic`` (or
1807 stronger) operations on the same address. If an address is written
1808 ``monotonic``-ally by one thread, and other threads ``monotonic``-ally
1809 read that address repeatedly, the other threads must eventually see
1810 the write. This corresponds to the C++0x/C1x
1811 ``memory_order_relaxed``.
1812``acquire``
1813 In addition to the guarantees of ``monotonic``, a
1814 *synchronizes-with* edge may be formed with a ``release`` operation.
1815 This is intended to model C++'s ``memory_order_acquire``.
1816``release``
1817 In addition to the guarantees of ``monotonic``, if this operation
1818 writes a value which is subsequently read by an ``acquire``
1819 operation, it *synchronizes-with* that operation. (This isn't a
1820 complete description; see the C++0x definition of a release
1821 sequence.) This corresponds to the C++0x/C1x
1822 ``memory_order_release``.
1823``acq_rel`` (acquire+release)
1824 Acts as both an ``acquire`` and ``release`` operation on its
1825 address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``.
1826``seq_cst`` (sequentially consistent)
1827 In addition to the guarantees of ``acq_rel`` (``acquire`` for an
Richard Smith32dbdf62014-07-31 04:25:36 +00001828 operation that only reads, ``release`` for an operation that only
Sean Silvab084af42012-12-07 10:36:55 +00001829 writes), there is a global total order on all
1830 sequentially-consistent operations on all addresses, which is
1831 consistent with the *happens-before* partial order and with the
1832 modification orders of all the affected addresses. Each
1833 sequentially-consistent read sees the last preceding write to the
1834 same address in this global order. This corresponds to the C++0x/C1x
1835 ``memory_order_seq_cst`` and Java volatile.
1836
1837.. _singlethread:
1838
1839If an atomic operation is marked ``singlethread``, it only *synchronizes
1840with* or participates in modification and seq\_cst total orderings with
1841other operations running in the same thread (for example, in signal
1842handlers).
1843
1844.. _fastmath:
1845
1846Fast-Math Flags
1847---------------
1848
1849LLVM IR floating-point binary ops (:ref:`fadd <i_fadd>`,
1850:ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`,
James Molloy88eb5352015-07-10 12:52:00 +00001851:ref:`frem <i_frem>`, :ref:`fcmp <i_fcmp>`) have the following flags that can
1852be set to enable otherwise unsafe floating point operations
Sean Silvab084af42012-12-07 10:36:55 +00001853
1854``nnan``
1855 No NaNs - Allow optimizations to assume the arguments and result are not
1856 NaN. Such optimizations are required to retain defined behavior over
1857 NaNs, but the value of the result is undefined.
1858
1859``ninf``
1860 No Infs - Allow optimizations to assume the arguments and result are not
1861 +/-Inf. Such optimizations are required to retain defined behavior over
1862 +/-Inf, but the value of the result is undefined.
1863
1864``nsz``
1865 No Signed Zeros - Allow optimizations to treat the sign of a zero
1866 argument or result as insignificant.
1867
1868``arcp``
1869 Allow Reciprocal - Allow optimizations to use the reciprocal of an
1870 argument rather than perform division.
1871
1872``fast``
1873 Fast - Allow algebraically equivalent transformations that may
1874 dramatically change results in floating point (e.g. reassociate). This
1875 flag implies all the others.
1876
Duncan P. N. Exon Smith0a448fb2014-08-19 21:30:15 +00001877.. _uselistorder:
1878
1879Use-list Order Directives
1880-------------------------
1881
1882Use-list directives encode the in-memory order of each use-list, allowing the
Sean Silvaa1190322015-08-06 22:56:48 +00001883order to be recreated. ``<order-indexes>`` is a comma-separated list of
1884indexes that are assigned to the referenced value's uses. The referenced
Duncan P. N. Exon Smith0a448fb2014-08-19 21:30:15 +00001885value's use-list is immediately sorted by these indexes.
1886
Sean Silvaa1190322015-08-06 22:56:48 +00001887Use-list directives may appear at function scope or global scope. They are not
1888instructions, and have no effect on the semantics of the IR. When they're at
Duncan P. N. Exon Smith0a448fb2014-08-19 21:30:15 +00001889function scope, they must appear after the terminator of the final basic block.
1890
1891If basic blocks have their address taken via ``blockaddress()`` expressions,
1892``uselistorder_bb`` can be used to reorder their use-lists from outside their
1893function's scope.
1894
1895:Syntax:
1896
1897::
1898
1899 uselistorder <ty> <value>, { <order-indexes> }
1900 uselistorder_bb @function, %block { <order-indexes> }
1901
1902:Examples:
1903
1904::
1905
Duncan P. N. Exon Smith23046652014-08-19 21:48:04 +00001906 define void @foo(i32 %arg1, i32 %arg2) {
1907 entry:
1908 ; ... instructions ...
1909 bb:
1910 ; ... instructions ...
1911
1912 ; At function scope.
1913 uselistorder i32 %arg1, { 1, 0, 2 }
1914 uselistorder label %bb, { 1, 0 }
1915 }
Duncan P. N. Exon Smith0a448fb2014-08-19 21:30:15 +00001916
1917 ; At global scope.
1918 uselistorder i32* @global, { 1, 2, 0 }
1919 uselistorder i32 7, { 1, 0 }
1920 uselistorder i32 (i32) @bar, { 1, 0 }
1921 uselistorder_bb @foo, %bb, { 5, 1, 3, 2, 0, 4 }
1922
Sean Silvab084af42012-12-07 10:36:55 +00001923.. _typesystem:
1924
1925Type System
1926===========
1927
1928The LLVM type system is one of the most important features of the
1929intermediate representation. Being typed enables a number of
1930optimizations to be performed on the intermediate representation
1931directly, without having to do extra analyses on the side before the
1932transformation. A strong type system makes it easier to read the
1933generated code and enables novel analyses and transformations that are
1934not feasible to perform on normal three address code representations.
1935
Rafael Espindola08013342013-12-07 19:34:20 +00001936.. _t_void:
Eli Bendersky0220e6b2013-06-07 20:24:43 +00001937
Rafael Espindola08013342013-12-07 19:34:20 +00001938Void Type
1939---------
Sean Silvab084af42012-12-07 10:36:55 +00001940
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00001941:Overview:
1942
Rafael Espindola08013342013-12-07 19:34:20 +00001943
1944The void type does not represent any value and has no size.
1945
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00001946:Syntax:
1947
Rafael Espindola08013342013-12-07 19:34:20 +00001948
1949::
1950
1951 void
Sean Silvab084af42012-12-07 10:36:55 +00001952
1953
Rafael Espindola08013342013-12-07 19:34:20 +00001954.. _t_function:
Sean Silvab084af42012-12-07 10:36:55 +00001955
Rafael Espindola08013342013-12-07 19:34:20 +00001956Function Type
1957-------------
Sean Silvab084af42012-12-07 10:36:55 +00001958
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00001959:Overview:
1960
Sean Silvab084af42012-12-07 10:36:55 +00001961
Rafael Espindola08013342013-12-07 19:34:20 +00001962The function type can be thought of as a function signature. It consists of a
1963return type and a list of formal parameter types. The return type of a function
1964type is a void type or first class type --- except for :ref:`label <t_label>`
1965and :ref:`metadata <t_metadata>` types.
Sean Silvab084af42012-12-07 10:36:55 +00001966
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00001967:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00001968
Rafael Espindola08013342013-12-07 19:34:20 +00001969::
Sean Silvab084af42012-12-07 10:36:55 +00001970
Rafael Espindola08013342013-12-07 19:34:20 +00001971 <returntype> (<parameter list>)
Sean Silvab084af42012-12-07 10:36:55 +00001972
Rafael Espindola08013342013-12-07 19:34:20 +00001973...where '``<parameter list>``' is a comma-separated list of type
1974specifiers. Optionally, the parameter list may include a type ``...``, which
Sean Silvaa1190322015-08-06 22:56:48 +00001975indicates that the function takes a variable number of arguments. Variable
Rafael Espindola08013342013-12-07 19:34:20 +00001976argument functions can access their arguments with the :ref:`variable argument
Sean Silvaa1190322015-08-06 22:56:48 +00001977handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type
Rafael Espindola08013342013-12-07 19:34:20 +00001978except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`.
Sean Silvab084af42012-12-07 10:36:55 +00001979
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00001980:Examples:
Sean Silvab084af42012-12-07 10:36:55 +00001981
Rafael Espindola08013342013-12-07 19:34:20 +00001982+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1983| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` |
1984+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1985| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. |
1986+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1987| ``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. |
1988+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1989| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values |
1990+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
1991
1992.. _t_firstclass:
1993
1994First Class Types
1995-----------------
Sean Silvab084af42012-12-07 10:36:55 +00001996
1997The :ref:`first class <t_firstclass>` types are perhaps the most important.
1998Values of these types are the only ones which can be produced by
1999instructions.
2000
Rafael Espindola08013342013-12-07 19:34:20 +00002001.. _t_single_value:
Sean Silvab084af42012-12-07 10:36:55 +00002002
Rafael Espindola08013342013-12-07 19:34:20 +00002003Single Value Types
2004^^^^^^^^^^^^^^^^^^
Sean Silvab084af42012-12-07 10:36:55 +00002005
Rafael Espindola08013342013-12-07 19:34:20 +00002006These are the types that are valid in registers from CodeGen's perspective.
Sean Silvab084af42012-12-07 10:36:55 +00002007
2008.. _t_integer:
2009
2010Integer Type
Rafael Espindola08013342013-12-07 19:34:20 +00002011""""""""""""
Sean Silvab084af42012-12-07 10:36:55 +00002012
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002013:Overview:
Sean Silvab084af42012-12-07 10:36:55 +00002014
2015The integer type is a very simple type that simply specifies an
2016arbitrary bit width for the integer type desired. Any bit width from 1
2017bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified.
2018
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002019:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00002020
2021::
2022
2023 iN
2024
2025The number of bits the integer will occupy is specified by the ``N``
2026value.
2027
2028Examples:
Rafael Espindola08013342013-12-07 19:34:20 +00002029*********
Sean Silvab084af42012-12-07 10:36:55 +00002030
2031+----------------+------------------------------------------------+
2032| ``i1`` | a single-bit integer. |
2033+----------------+------------------------------------------------+
2034| ``i32`` | a 32-bit integer. |
2035+----------------+------------------------------------------------+
2036| ``i1942652`` | a really big integer of over 1 million bits. |
2037+----------------+------------------------------------------------+
2038
2039.. _t_floating:
2040
2041Floating Point Types
Rafael Espindola08013342013-12-07 19:34:20 +00002042""""""""""""""""""""
Sean Silvab084af42012-12-07 10:36:55 +00002043
2044.. list-table::
2045 :header-rows: 1
2046
2047 * - Type
2048 - Description
2049
2050 * - ``half``
2051 - 16-bit floating point value
2052
2053 * - ``float``
2054 - 32-bit floating point value
2055
2056 * - ``double``
2057 - 64-bit floating point value
2058
2059 * - ``fp128``
2060 - 128-bit floating point value (112-bit mantissa)
2061
2062 * - ``x86_fp80``
2063 - 80-bit floating point value (X87)
2064
2065 * - ``ppc_fp128``
2066 - 128-bit floating point value (two 64-bits)
2067
Reid Kleckner9a16d082014-03-05 02:41:37 +00002068X86_mmx Type
2069""""""""""""
Sean Silvab084af42012-12-07 10:36:55 +00002070
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002071:Overview:
Sean Silvab084af42012-12-07 10:36:55 +00002072
Reid Kleckner9a16d082014-03-05 02:41:37 +00002073The x86_mmx type represents a value held in an MMX register on an x86
Sean Silvab084af42012-12-07 10:36:55 +00002074machine. The operations allowed on it are quite limited: parameters and
2075return values, load and store, and bitcast. User-specified MMX
2076instructions are represented as intrinsic or asm calls with arguments
2077and/or results of this type. There are no arrays, vectors or constants
2078of this type.
2079
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002080:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00002081
2082::
2083
Reid Kleckner9a16d082014-03-05 02:41:37 +00002084 x86_mmx
Sean Silvab084af42012-12-07 10:36:55 +00002085
Sean Silvab084af42012-12-07 10:36:55 +00002086
Rafael Espindola08013342013-12-07 19:34:20 +00002087.. _t_pointer:
2088
2089Pointer Type
2090""""""""""""
Sean Silvab084af42012-12-07 10:36:55 +00002091
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002092:Overview:
Sean Silvab084af42012-12-07 10:36:55 +00002093
Rafael Espindola08013342013-12-07 19:34:20 +00002094The pointer type is used to specify memory locations. Pointers are
2095commonly used to reference objects in memory.
2096
2097Pointer types may have an optional address space attribute defining the
2098numbered address space where the pointed-to object resides. The default
2099address space is number zero. The semantics of non-zero address spaces
2100are target-specific.
2101
2102Note that LLVM does not permit pointers to void (``void*``) nor does it
2103permit pointers to labels (``label*``). Use ``i8*`` instead.
Sean Silvab084af42012-12-07 10:36:55 +00002104
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002105:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00002106
2107::
2108
Rafael Espindola08013342013-12-07 19:34:20 +00002109 <type> *
2110
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002111:Examples:
Rafael Espindola08013342013-12-07 19:34:20 +00002112
2113+-------------------------+--------------------------------------------------------------------------------------------------------------+
2114| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. |
2115+-------------------------+--------------------------------------------------------------------------------------------------------------+
2116| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. |
2117+-------------------------+--------------------------------------------------------------------------------------------------------------+
2118| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. |
2119+-------------------------+--------------------------------------------------------------------------------------------------------------+
2120
2121.. _t_vector:
2122
2123Vector Type
2124"""""""""""
2125
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002126:Overview:
Rafael Espindola08013342013-12-07 19:34:20 +00002127
2128A vector type is a simple derived type that represents a vector of
2129elements. Vector types are used when multiple primitive data are
2130operated in parallel using a single instruction (SIMD). A vector type
2131requires a size (number of elements) and an underlying primitive data
2132type. Vector types are considered :ref:`first class <t_firstclass>`.
2133
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002134:Syntax:
Rafael Espindola08013342013-12-07 19:34:20 +00002135
2136::
2137
2138 < <# elements> x <elementtype> >
2139
2140The number of elements is a constant integer value larger than 0;
Manuel Jacob961f7872014-07-30 12:30:06 +00002141elementtype may be any integer, floating point or pointer type. Vectors
2142of size zero are not allowed.
Rafael Espindola08013342013-12-07 19:34:20 +00002143
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002144:Examples:
Rafael Espindola08013342013-12-07 19:34:20 +00002145
2146+-------------------+--------------------------------------------------+
2147| ``<4 x i32>`` | Vector of 4 32-bit integer values. |
2148+-------------------+--------------------------------------------------+
2149| ``<8 x float>`` | Vector of 8 32-bit floating-point values. |
2150+-------------------+--------------------------------------------------+
2151| ``<2 x i64>`` | Vector of 2 64-bit integer values. |
2152+-------------------+--------------------------------------------------+
2153| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. |
2154+-------------------+--------------------------------------------------+
Sean Silvab084af42012-12-07 10:36:55 +00002155
2156.. _t_label:
2157
2158Label Type
2159^^^^^^^^^^
2160
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002161:Overview:
Sean Silvab084af42012-12-07 10:36:55 +00002162
2163The label type represents code labels.
2164
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002165:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00002166
2167::
2168
2169 label
2170
David Majnemerb611e3f2015-08-14 05:09:07 +00002171.. _t_token:
2172
2173Token Type
2174^^^^^^^^^^
2175
2176:Overview:
2177
2178The token type is used when a value is associated with an instruction
2179but all uses of the value must not attempt to introspect or obscure it.
2180As such, it is not appropriate to have a :ref:`phi <i_phi>` or
2181:ref:`select <i_select>` of type token.
2182
2183:Syntax:
2184
2185::
2186
2187 token
2188
2189
2190
Sean Silvab084af42012-12-07 10:36:55 +00002191.. _t_metadata:
2192
2193Metadata Type
2194^^^^^^^^^^^^^
2195
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002196:Overview:
Sean Silvab084af42012-12-07 10:36:55 +00002197
2198The metadata type represents embedded metadata. No derived types may be
2199created from metadata except for :ref:`function <t_function>` arguments.
2200
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002201:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00002202
2203::
2204
2205 metadata
2206
Sean Silvab084af42012-12-07 10:36:55 +00002207.. _t_aggregate:
2208
2209Aggregate Types
2210^^^^^^^^^^^^^^^
2211
2212Aggregate Types are a subset of derived types that can contain multiple
2213member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are
2214aggregate types. :ref:`Vectors <t_vector>` are not considered to be
2215aggregate types.
2216
2217.. _t_array:
2218
2219Array Type
Rafael Espindola08013342013-12-07 19:34:20 +00002220""""""""""
Sean Silvab084af42012-12-07 10:36:55 +00002221
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002222:Overview:
Sean Silvab084af42012-12-07 10:36:55 +00002223
2224The array type is a very simple derived type that arranges elements
2225sequentially in memory. The array type requires a size (number of
2226elements) and an underlying data type.
2227
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002228:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00002229
2230::
2231
2232 [<# elements> x <elementtype>]
2233
2234The number of elements is a constant integer value; ``elementtype`` may
2235be any type with a size.
2236
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002237:Examples:
Sean Silvab084af42012-12-07 10:36:55 +00002238
2239+------------------+--------------------------------------+
2240| ``[40 x i32]`` | Array of 40 32-bit integer values. |
2241+------------------+--------------------------------------+
2242| ``[41 x i32]`` | Array of 41 32-bit integer values. |
2243+------------------+--------------------------------------+
2244| ``[4 x i8]`` | Array of 4 8-bit integer values. |
2245+------------------+--------------------------------------+
2246
2247Here are some examples of multidimensional arrays:
2248
2249+-----------------------------+----------------------------------------------------------+
2250| ``[3 x [4 x i32]]`` | 3x4 array of 32-bit integer values. |
2251+-----------------------------+----------------------------------------------------------+
2252| ``[12 x [10 x float]]`` | 12x10 array of single precision floating point values. |
2253+-----------------------------+----------------------------------------------------------+
2254| ``[2 x [3 x [4 x i16]]]`` | 2x3x4 array of 16-bit integer values. |
2255+-----------------------------+----------------------------------------------------------+
2256
2257There is no restriction on indexing beyond the end of the array implied
2258by a static type (though there are restrictions on indexing beyond the
2259bounds of an allocated object in some cases). This means that
2260single-dimension 'variable sized array' addressing can be implemented in
2261LLVM with a zero length array type. An implementation of 'pascal style
2262arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for
2263example.
2264
Sean Silvab084af42012-12-07 10:36:55 +00002265.. _t_struct:
2266
2267Structure Type
Rafael Espindola08013342013-12-07 19:34:20 +00002268""""""""""""""
Sean Silvab084af42012-12-07 10:36:55 +00002269
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002270:Overview:
Sean Silvab084af42012-12-07 10:36:55 +00002271
2272The structure type is used to represent a collection of data members
2273together in memory. The elements of a structure may be any type that has
2274a size.
2275
2276Structures in memory are accessed using '``load``' and '``store``' by
2277getting a pointer to a field with the '``getelementptr``' instruction.
2278Structures in registers are accessed using the '``extractvalue``' and
2279'``insertvalue``' instructions.
2280
2281Structures may optionally be "packed" structures, which indicate that
2282the alignment of the struct is one byte, and that there is no padding
2283between the elements. In non-packed structs, padding between field types
2284is inserted as defined by the DataLayout string in the module, which is
2285required to match what the underlying code generator expects.
2286
2287Structures can either be "literal" or "identified". A literal structure
2288is defined inline with other types (e.g. ``{i32, i32}*``) whereas
2289identified types are always defined at the top level with a name.
2290Literal types are uniqued by their contents and can never be recursive
2291or opaque since there is no way to write one. Identified types can be
2292recursive, can be opaqued, and are never uniqued.
2293
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002294:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00002295
2296::
2297
2298 %T1 = type { <type list> } ; Identified normal struct type
2299 %T2 = type <{ <type list> }> ; Identified packed struct type
2300
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002301:Examples:
Sean Silvab084af42012-12-07 10:36:55 +00002302
2303+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2304| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values |
2305+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Daniel Dunbar1dc66ca2013-01-17 18:57:32 +00002306| ``{ 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 Silvab084af42012-12-07 10:36:55 +00002307+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2308| ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. |
2309+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
2310
2311.. _t_opaque:
2312
2313Opaque Structure Types
Rafael Espindola08013342013-12-07 19:34:20 +00002314""""""""""""""""""""""
Sean Silvab084af42012-12-07 10:36:55 +00002315
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002316:Overview:
Sean Silvab084af42012-12-07 10:36:55 +00002317
2318Opaque structure types are used to represent named structure types that
2319do not have a body specified. This corresponds (for example) to the C
2320notion of a forward declared structure.
2321
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002322:Syntax:
Sean Silvab084af42012-12-07 10:36:55 +00002323
2324::
2325
2326 %X = type opaque
2327 %52 = type opaque
2328
Rafael Espindola2f6d7b92013-12-10 14:53:22 +00002329:Examples:
Sean Silvab084af42012-12-07 10:36:55 +00002330
2331+--------------+-------------------+
2332| ``opaque`` | An opaque type. |
2333+--------------+-------------------+
2334
Sean Silva1703e702014-04-08 21:06:22 +00002335.. _constants:
2336
Sean Silvab084af42012-12-07 10:36:55 +00002337Constants
2338=========
2339
2340LLVM has several different basic types of constants. This section
2341describes them all and their syntax.
2342
2343Simple Constants
2344----------------
2345
2346**Boolean constants**
2347 The two strings '``true``' and '``false``' are both valid constants
2348 of the ``i1`` type.
2349**Integer constants**
2350 Standard integers (such as '4') are constants of the
2351 :ref:`integer <t_integer>` type. Negative numbers may be used with
2352 integer types.
2353**Floating point constants**
2354 Floating point constants use standard decimal notation (e.g.
2355 123.421), exponential notation (e.g. 1.23421e+2), or a more precise
2356 hexadecimal notation (see below). The assembler requires the exact
2357 decimal value of a floating-point constant. For example, the
2358 assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating
2359 decimal in binary. Floating point constants must have a :ref:`floating
2360 point <t_floating>` type.
2361**Null pointer constants**
2362 The identifier '``null``' is recognized as a null pointer constant
2363 and must be of :ref:`pointer type <t_pointer>`.
2364
2365The one non-intuitive notation for constants is the hexadecimal form of
2366floating point constants. For example, the form
2367'``double 0x432ff973cafa8000``' is equivalent to (but harder to read
2368than) '``double 4.5e+15``'. The only time hexadecimal floating point
2369constants are required (and the only time that they are generated by the
2370disassembler) is when a floating point constant must be emitted but it
2371cannot be represented as a decimal floating point number in a reasonable
2372number of digits. For example, NaN's, infinities, and other special
2373values are represented in their IEEE hexadecimal format so that assembly
2374and disassembly do not cause any bits to change in the constants.
2375
2376When using the hexadecimal form, constants of types half, float, and
2377double are represented using the 16-digit form shown above (which
2378matches the IEEE754 representation for double); half and float values
Dmitri Gribenko4dc2ba12013-01-16 23:40:37 +00002379must, however, be exactly representable as IEEE 754 half and single
Sean Silvab084af42012-12-07 10:36:55 +00002380precision, respectively. Hexadecimal format is always used for long
2381double, and there are three forms of long double. The 80-bit format used
2382by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The
2383128-bit format used by PowerPC (two adjacent doubles) is represented by
2384``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is
Richard Sandifordae426b42013-05-03 14:32:27 +00002385represented by ``0xL`` followed by 32 hexadecimal digits. Long doubles
2386will only work if they match the long double format on your target.
2387The IEEE 16-bit format (half precision) is represented by ``0xH``
2388followed by 4 hexadecimal digits. All hexadecimal formats are big-endian
2389(sign bit at the left).
Sean Silvab084af42012-12-07 10:36:55 +00002390
Reid Kleckner9a16d082014-03-05 02:41:37 +00002391There are no constants of type x86_mmx.
Sean Silvab084af42012-12-07 10:36:55 +00002392
Eli Bendersky0220e6b2013-06-07 20:24:43 +00002393.. _complexconstants:
2394
Sean Silvab084af42012-12-07 10:36:55 +00002395Complex Constants
2396-----------------
2397
2398Complex constants are a (potentially recursive) combination of simple
2399constants and smaller complex constants.
2400
2401**Structure constants**
2402 Structure constants are represented with notation similar to
2403 structure type definitions (a comma separated list of elements,
2404 surrounded by braces (``{}``)). For example:
2405 "``{ i32 4, float 17.0, i32* @G }``", where "``@G``" is declared as
2406 "``@G = external global i32``". Structure constants must have
2407 :ref:`structure type <t_struct>`, and the number and types of elements
2408 must match those specified by the type.
2409**Array constants**
2410 Array constants are represented with notation similar to array type
2411 definitions (a comma separated list of elements, surrounded by
2412 square brackets (``[]``)). For example:
2413 "``[ i32 42, i32 11, i32 74 ]``". Array constants must have
2414 :ref:`array type <t_array>`, and the number and types of elements must
Daniel Sandersf6051842014-09-11 12:02:59 +00002415 match those specified by the type. As a special case, character array
2416 constants may also be represented as a double-quoted string using the ``c``
2417 prefix. For example: "``c"Hello World\0A\00"``".
Sean Silvab084af42012-12-07 10:36:55 +00002418**Vector constants**
2419 Vector constants are represented with notation similar to vector
2420 type definitions (a comma separated list of elements, surrounded by
2421 less-than/greater-than's (``<>``)). For example:
2422 "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants
2423 must have :ref:`vector type <t_vector>`, and the number and types of
2424 elements must match those specified by the type.
2425**Zero initialization**
2426 The string '``zeroinitializer``' can be used to zero initialize a
2427 value to zero of *any* type, including scalar and
2428 :ref:`aggregate <t_aggregate>` types. This is often used to avoid
2429 having to print large zero initializers (e.g. for large arrays) and
2430 is always exactly equivalent to using explicit zero initializers.
2431**Metadata node**
Sean Silvaa1190322015-08-06 22:56:48 +00002432 A metadata node is a constant tuple without types. For example:
2433 "``!{!0, !{!2, !0}, !"test"}``". Metadata can reference constant values,
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00002434 for example: "``!{!0, i32 0, i8* @global, i64 (i64)* @function, !"str"}``".
2435 Unlike other typed constants that are meant to be interpreted as part of
2436 the instruction stream, metadata is a place to attach additional
Sean Silvab084af42012-12-07 10:36:55 +00002437 information such as debug info.
2438
2439Global Variable and Function Addresses
2440--------------------------------------
2441
2442The addresses of :ref:`global variables <globalvars>` and
2443:ref:`functions <functionstructure>` are always implicitly valid
2444(link-time) constants. These constants are explicitly referenced when
2445the :ref:`identifier for the global <identifiers>` is used and always have
2446:ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM
2447file:
2448
2449.. code-block:: llvm
2450
2451 @X = global i32 17
2452 @Y = global i32 42
2453 @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
2454
2455.. _undefvalues:
2456
2457Undefined Values
2458----------------
2459
2460The string '``undef``' can be used anywhere a constant is expected, and
2461indicates that the user of the value may receive an unspecified
2462bit-pattern. Undefined values may be of any type (other than '``label``'
2463or '``void``') and be used anywhere a constant is permitted.
2464
2465Undefined values are useful because they indicate to the compiler that
2466the program is well defined no matter what value is used. This gives the
2467compiler more freedom to optimize. Here are some examples of
2468(potentially surprising) transformations that are valid (in pseudo IR):
2469
2470.. code-block:: llvm
2471
2472 %A = add %X, undef
2473 %B = sub %X, undef
2474 %C = xor %X, undef
2475 Safe:
2476 %A = undef
2477 %B = undef
2478 %C = undef
2479
2480This is safe because all of the output bits are affected by the undef
2481bits. Any output bit can have a zero or one depending on the input bits.
2482
2483.. code-block:: llvm
2484
2485 %A = or %X, undef
2486 %B = and %X, undef
2487 Safe:
2488 %A = -1
2489 %B = 0
2490 Unsafe:
2491 %A = undef
2492 %B = undef
2493
2494These logical operations have bits that are not always affected by the
2495input. For example, if ``%X`` has a zero bit, then the output of the
2496'``and``' operation will always be a zero for that bit, no matter what
2497the corresponding bit from the '``undef``' is. As such, it is unsafe to
2498optimize or assume that the result of the '``and``' is '``undef``'.
2499However, it is safe to assume that all bits of the '``undef``' could be
25000, and optimize the '``and``' to 0. Likewise, it is safe to assume that
2501all the bits of the '``undef``' operand to the '``or``' could be set,
2502allowing the '``or``' to be folded to -1.
2503
2504.. code-block:: llvm
2505
2506 %A = select undef, %X, %Y
2507 %B = select undef, 42, %Y
2508 %C = select %X, %Y, undef
2509 Safe:
2510 %A = %X (or %Y)
2511 %B = 42 (or %Y)
2512 %C = %Y
2513 Unsafe:
2514 %A = undef
2515 %B = undef
2516 %C = undef
2517
2518This set of examples shows that undefined '``select``' (and conditional
2519branch) conditions can go *either way*, but they have to come from one
2520of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were
2521both known to have a clear low bit, then ``%A`` would have to have a
2522cleared low bit. However, in the ``%C`` example, the optimizer is
2523allowed to assume that the '``undef``' operand could be the same as
2524``%Y``, allowing the whole '``select``' to be eliminated.
2525
2526.. code-block:: llvm
2527
2528 %A = xor undef, undef
2529
2530 %B = undef
2531 %C = xor %B, %B
2532
2533 %D = undef
Jonathan Roelofsec81c0b2014-10-16 19:28:10 +00002534 %E = icmp slt %D, 4
Sean Silvab084af42012-12-07 10:36:55 +00002535 %F = icmp gte %D, 4
2536
2537 Safe:
2538 %A = undef
2539 %B = undef
2540 %C = undef
2541 %D = undef
2542 %E = undef
2543 %F = undef
2544
2545This example points out that two '``undef``' operands are not
2546necessarily the same. This can be surprising to people (and also matches
2547C semantics) where they assume that "``X^X``" is always zero, even if
2548``X`` is undefined. This isn't true for a number of reasons, but the
2549short answer is that an '``undef``' "variable" can arbitrarily change
2550its value over its "live range". This is true because the variable
2551doesn't actually *have a live range*. Instead, the value is logically
2552read from arbitrary registers that happen to be around when needed, so
2553the value is not necessarily consistent over time. In fact, ``%A`` and
2554``%C`` need to have the same semantics or the core LLVM "replace all
2555uses with" concept would not hold.
2556
2557.. code-block:: llvm
2558
2559 %A = fdiv undef, %X
2560 %B = fdiv %X, undef
2561 Safe:
2562 %A = undef
2563 b: unreachable
2564
2565These examples show the crucial difference between an *undefined value*
2566and *undefined behavior*. An undefined value (like '``undef``') is
2567allowed to have an arbitrary bit-pattern. This means that the ``%A``
2568operation can be constant folded to '``undef``', because the '``undef``'
2569could be an SNaN, and ``fdiv`` is not (currently) defined on SNaN's.
2570However, in the second example, we can make a more aggressive
2571assumption: because the ``undef`` is allowed to be an arbitrary value,
2572we are allowed to assume that it could be zero. Since a divide by zero
2573has *undefined behavior*, we are allowed to assume that the operation
2574does not execute at all. This allows us to delete the divide and all
2575code after it. Because the undefined operation "can't happen", the
2576optimizer can assume that it occurs in dead code.
2577
2578.. code-block:: llvm
2579
2580 a: store undef -> %X
2581 b: store %X -> undef
2582 Safe:
2583 a: <deleted>
2584 b: unreachable
2585
2586These examples reiterate the ``fdiv`` example: a store *of* an undefined
2587value can be assumed to not have any effect; we can assume that the
2588value is overwritten with bits that happen to match what was already
2589there. However, a store *to* an undefined location could clobber
2590arbitrary memory, therefore, it has undefined behavior.
2591
2592.. _poisonvalues:
2593
2594Poison Values
2595-------------
2596
2597Poison values are similar to :ref:`undef values <undefvalues>`, however
2598they also represent the fact that an instruction or constant expression
Richard Smith32dbdf62014-07-31 04:25:36 +00002599that cannot evoke side effects has nevertheless detected a condition
2600that results in undefined behavior.
Sean Silvab084af42012-12-07 10:36:55 +00002601
2602There is currently no way of representing a poison value in the IR; they
2603only exist when produced by operations such as :ref:`add <i_add>` with
2604the ``nsw`` flag.
2605
2606Poison value behavior is defined in terms of value *dependence*:
2607
2608- Values other than :ref:`phi <i_phi>` nodes depend on their operands.
2609- :ref:`Phi <i_phi>` nodes depend on the operand corresponding to
2610 their dynamic predecessor basic block.
2611- Function arguments depend on the corresponding actual argument values
2612 in the dynamic callers of their functions.
2613- :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>`
2614 instructions that dynamically transfer control back to them.
2615- :ref:`Invoke <i_invoke>` instructions depend on the
2616 :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing
2617 call instructions that dynamically transfer control back to them.
2618- Non-volatile loads and stores depend on the most recent stores to all
2619 of the referenced memory addresses, following the order in the IR
2620 (including loads and stores implied by intrinsics such as
2621 :ref:`@llvm.memcpy <int_memcpy>`.)
2622- An instruction with externally visible side effects depends on the
2623 most recent preceding instruction with externally visible side
2624 effects, following the order in the IR. (This includes :ref:`volatile
2625 operations <volatile>`.)
2626- An instruction *control-depends* on a :ref:`terminator
2627 instruction <terminators>` if the terminator instruction has
2628 multiple successors and the instruction is always executed when
2629 control transfers to one of the successors, and may not be executed
2630 when control is transferred to another.
2631- Additionally, an instruction also *control-depends* on a terminator
2632 instruction if the set of instructions it otherwise depends on would
2633 be different if the terminator had transferred control to a different
2634 successor.
2635- Dependence is transitive.
2636
Richard Smith32dbdf62014-07-31 04:25:36 +00002637Poison values have the same behavior as :ref:`undef values <undefvalues>`,
2638with the additional effect that any instruction that has a *dependence*
Sean Silvab084af42012-12-07 10:36:55 +00002639on a poison value has undefined behavior.
2640
2641Here are some examples:
2642
2643.. code-block:: llvm
2644
2645 entry:
2646 %poison = sub nuw i32 0, 1 ; Results in a poison value.
2647 %still_poison = and i32 %poison, 0 ; 0, but also poison.
David Blaikie16a97eb2015-03-04 22:02:58 +00002648 %poison_yet_again = getelementptr i32, i32* @h, i32 %still_poison
Sean Silvab084af42012-12-07 10:36:55 +00002649 store i32 0, i32* %poison_yet_again ; memory at @h[0] is poisoned
2650
2651 store i32 %poison, i32* @g ; Poison value stored to memory.
David Blaikiec7aabbb2015-03-04 22:06:14 +00002652 %poison2 = load i32, i32* @g ; Poison value loaded back from memory.
Sean Silvab084af42012-12-07 10:36:55 +00002653
2654 store volatile i32 %poison, i32* @g ; External observation; undefined behavior.
2655
2656 %narrowaddr = bitcast i32* @g to i16*
2657 %wideaddr = bitcast i32* @g to i64*
David Blaikiec7aabbb2015-03-04 22:06:14 +00002658 %poison3 = load i16, i16* %narrowaddr ; Returns a poison value.
2659 %poison4 = load i64, i64* %wideaddr ; Returns a poison value.
Sean Silvab084af42012-12-07 10:36:55 +00002660
2661 %cmp = icmp slt i32 %poison, 0 ; Returns a poison value.
2662 br i1 %cmp, label %true, label %end ; Branch to either destination.
2663
2664 true:
2665 store volatile i32 0, i32* @g ; This is control-dependent on %cmp, so
2666 ; it has undefined behavior.
2667 br label %end
2668
2669 end:
2670 %p = phi i32 [ 0, %entry ], [ 1, %true ]
2671 ; Both edges into this PHI are
2672 ; control-dependent on %cmp, so this
2673 ; always results in a poison value.
2674
2675 store volatile i32 0, i32* @g ; This would depend on the store in %true
2676 ; if %cmp is true, or the store in %entry
2677 ; otherwise, so this is undefined behavior.
2678
2679 br i1 %cmp, label %second_true, label %second_end
2680 ; The same branch again, but this time the
2681 ; true block doesn't have side effects.
2682
2683 second_true:
2684 ; No side effects!
2685 ret void
2686
2687 second_end:
2688 store volatile i32 0, i32* @g ; This time, the instruction always depends
2689 ; on the store in %end. Also, it is
2690 ; control-equivalent to %end, so this is
2691 ; well-defined (ignoring earlier undefined
2692 ; behavior in this example).
2693
2694.. _blockaddress:
2695
2696Addresses of Basic Blocks
2697-------------------------
2698
2699``blockaddress(@function, %block)``
2700
2701The '``blockaddress``' constant computes the address of the specified
2702basic block in the specified function, and always has an ``i8*`` type.
2703Taking the address of the entry block is illegal.
2704
2705This value only has defined behavior when used as an operand to the
2706':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons
2707against null. Pointer equality tests between labels addresses results in
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00002708undefined behavior --- though, again, comparison against null is ok, and
Sean Silvab084af42012-12-07 10:36:55 +00002709no label is equal to the null pointer. This may be passed around as an
2710opaque pointer sized value as long as the bits are not inspected. This
2711allows ``ptrtoint`` and arithmetic to be performed on these values so
2712long as the original value is reconstituted before the ``indirectbr``
2713instruction.
2714
2715Finally, some targets may provide defined semantics when using the value
2716as the operand to an inline assembly, but that is target specific.
2717
Eli Bendersky0220e6b2013-06-07 20:24:43 +00002718.. _constantexprs:
2719
Sean Silvab084af42012-12-07 10:36:55 +00002720Constant Expressions
2721--------------------
2722
2723Constant expressions are used to allow expressions involving other
2724constants to be used as constants. Constant expressions may be of any
2725:ref:`first class <t_firstclass>` type and may involve any LLVM operation
2726that does not have side effects (e.g. load and call are not supported).
2727The following is the syntax for constant expressions:
2728
2729``trunc (CST to TYPE)``
2730 Truncate a constant to another type. The bit size of CST must be
2731 larger than the bit size of TYPE. Both types must be integers.
2732``zext (CST to TYPE)``
2733 Zero extend a constant to another type. The bit size of CST must be
2734 smaller than the bit size of TYPE. Both types must be integers.
2735``sext (CST to TYPE)``
2736 Sign extend a constant to another type. The bit size of CST must be
2737 smaller than the bit size of TYPE. Both types must be integers.
2738``fptrunc (CST to TYPE)``
2739 Truncate a floating point constant to another floating point type.
2740 The size of CST must be larger than the size of TYPE. Both types
2741 must be floating point.
2742``fpext (CST to TYPE)``
2743 Floating point extend a constant to another type. The size of CST
2744 must be smaller or equal to the size of TYPE. Both types must be
2745 floating point.
2746``fptoui (CST to TYPE)``
2747 Convert a floating point constant to the corresponding unsigned
2748 integer constant. TYPE must be a scalar or vector integer type. CST
2749 must be of scalar or vector floating point type. Both CST and TYPE
2750 must be scalars, or vectors of the same number of elements. If the
2751 value won't fit in the integer type, the results are undefined.
2752``fptosi (CST to TYPE)``
2753 Convert a floating point constant to the corresponding signed
2754 integer constant. TYPE must be a scalar or vector integer type. CST
2755 must be of scalar or vector floating point type. Both CST and TYPE
2756 must be scalars, or vectors of the same number of elements. If the
2757 value won't fit in the integer type, the results are undefined.
2758``uitofp (CST to TYPE)``
2759 Convert an unsigned integer constant to the corresponding floating
2760 point constant. TYPE must be a scalar or vector floating point type.
2761 CST must be of scalar or vector integer type. Both CST and TYPE must
2762 be scalars, or vectors of the same number of elements. If the value
2763 won't fit in the floating point type, the results are undefined.
2764``sitofp (CST to TYPE)``
2765 Convert a signed integer constant to the corresponding floating
2766 point constant. TYPE must be a scalar or vector floating point type.
2767 CST must be of scalar or vector integer type. Both CST and TYPE must
2768 be scalars, or vectors of the same number of elements. If the value
2769 won't fit in the floating point type, the results are undefined.
2770``ptrtoint (CST to TYPE)``
2771 Convert a pointer typed constant to the corresponding integer
Eli Bendersky9c0d4932013-03-11 16:51:15 +00002772 constant. ``TYPE`` must be an integer type. ``CST`` must be of
Sean Silvab084af42012-12-07 10:36:55 +00002773 pointer type. The ``CST`` value is zero extended, truncated, or
2774 unchanged to make it fit in ``TYPE``.
2775``inttoptr (CST to TYPE)``
2776 Convert an integer constant to a pointer constant. TYPE must be a
2777 pointer type. CST must be of integer type. The CST value is zero
2778 extended, truncated, or unchanged to make it fit in a pointer size.
2779 This one is *really* dangerous!
2780``bitcast (CST to TYPE)``
2781 Convert a constant, CST, to another TYPE. The constraints of the
2782 operands are the same as those for the :ref:`bitcast
2783 instruction <i_bitcast>`.
Matt Arsenaultb03bd4d2013-11-15 01:34:59 +00002784``addrspacecast (CST to TYPE)``
2785 Convert a constant pointer or constant vector of pointer, CST, to another
2786 TYPE in a different address space. The constraints of the operands are the
2787 same as those for the :ref:`addrspacecast instruction <i_addrspacecast>`.
David Blaikief72d05b2015-03-13 18:20:45 +00002788``getelementptr (TY, CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (TY, CSTPTR, IDX0, IDX1, ...)``
Sean Silvab084af42012-12-07 10:36:55 +00002789 Perform the :ref:`getelementptr operation <i_getelementptr>` on
2790 constants. As with the :ref:`getelementptr <i_getelementptr>`
2791 instruction, the index list may have zero or more indexes, which are
David Blaikief72d05b2015-03-13 18:20:45 +00002792 required to make sense for the type of "pointer to TY".
Sean Silvab084af42012-12-07 10:36:55 +00002793``select (COND, VAL1, VAL2)``
2794 Perform the :ref:`select operation <i_select>` on constants.
2795``icmp COND (VAL1, VAL2)``
2796 Performs the :ref:`icmp operation <i_icmp>` on constants.
2797``fcmp COND (VAL1, VAL2)``
2798 Performs the :ref:`fcmp operation <i_fcmp>` on constants.
2799``extractelement (VAL, IDX)``
2800 Perform the :ref:`extractelement operation <i_extractelement>` on
2801 constants.
2802``insertelement (VAL, ELT, IDX)``
2803 Perform the :ref:`insertelement operation <i_insertelement>` on
2804 constants.
2805``shufflevector (VEC1, VEC2, IDXMASK)``
2806 Perform the :ref:`shufflevector operation <i_shufflevector>` on
2807 constants.
2808``extractvalue (VAL, IDX0, IDX1, ...)``
2809 Perform the :ref:`extractvalue operation <i_extractvalue>` on
2810 constants. The index list is interpreted in a similar manner as
2811 indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At
2812 least one index value must be specified.
2813``insertvalue (VAL, ELT, IDX0, IDX1, ...)``
2814 Perform the :ref:`insertvalue operation <i_insertvalue>` on constants.
2815 The index list is interpreted in a similar manner as indices in a
2816 ':ref:`getelementptr <i_getelementptr>`' operation. At least one index
2817 value must be specified.
2818``OPCODE (LHS, RHS)``
2819 Perform the specified operation of the LHS and RHS constants. OPCODE
2820 may be any of the :ref:`binary <binaryops>` or :ref:`bitwise
2821 binary <bitwiseops>` operations. The constraints on operands are
2822 the same as those for the corresponding instruction (e.g. no bitwise
2823 operations on floating point values are allowed).
2824
2825Other Values
2826============
2827
Eli Bendersky0220e6b2013-06-07 20:24:43 +00002828.. _inlineasmexprs:
2829
Sean Silvab084af42012-12-07 10:36:55 +00002830Inline Assembler Expressions
2831----------------------------
2832
2833LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level
James Y Knightbc832ed2015-07-08 18:08:36 +00002834Inline Assembly <moduleasm>`) through the use of a special value. This value
2835represents the inline assembler as a template string (containing the
2836instructions to emit), a list of operand constraints (stored as a string), a
2837flag that indicates whether or not the inline asm expression has side effects,
2838and a flag indicating whether the function containing the asm needs to align its
2839stack conservatively.
2840
2841The template string supports argument substitution of the operands using "``$``"
2842followed by a number, to indicate substitution of the given register/memory
2843location, as specified by the constraint string. "``${NUM:MODIFIER}``" may also
2844be used, where ``MODIFIER`` is a target-specific annotation for how to print the
2845operand (See :ref:`inline-asm-modifiers`).
2846
2847A literal "``$``" may be included by using "``$$``" in the template. To include
2848other special characters into the output, the usual "``\XX``" escapes may be
2849used, just as in other strings. Note that after template substitution, the
2850resulting assembly string is parsed by LLVM's integrated assembler unless it is
2851disabled -- even when emitting a ``.s`` file -- and thus must contain assembly
2852syntax known to LLVM.
2853
2854LLVM's support for inline asm is modeled closely on the requirements of Clang's
2855GCC-compatible inline-asm support. Thus, the feature-set and the constraint and
2856modifier codes listed here are similar or identical to those in GCC's inline asm
2857support. However, to be clear, the syntax of the template and constraint strings
2858described here is *not* the same as the syntax accepted by GCC and Clang, and,
2859while most constraint letters are passed through as-is by Clang, some get
2860translated to other codes when converting from the C source to the LLVM
2861assembly.
2862
2863An example inline assembler expression is:
Sean Silvab084af42012-12-07 10:36:55 +00002864
2865.. code-block:: llvm
2866
2867 i32 (i32) asm "bswap $0", "=r,r"
2868
2869Inline assembler expressions may **only** be used as the callee operand
2870of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction.
2871Thus, typically we have:
2872
2873.. code-block:: llvm
2874
2875 %X = call i32 asm "bswap $0", "=r,r"(i32 %Y)
2876
2877Inline asms with side effects not visible in the constraint list must be
2878marked as having side effects. This is done through the use of the
2879'``sideeffect``' keyword, like so:
2880
2881.. code-block:: llvm
2882
2883 call void asm sideeffect "eieio", ""()
2884
2885In some cases inline asms will contain code that will not work unless
2886the stack is aligned in some way, such as calls or SSE instructions on
2887x86, yet will not contain code that does that alignment within the asm.
2888The compiler should make conservative assumptions about what the asm
2889might contain and should generate its usual stack alignment code in the
2890prologue if the '``alignstack``' keyword is present:
2891
2892.. code-block:: llvm
2893
2894 call void asm alignstack "eieio", ""()
2895
2896Inline asms also support using non-standard assembly dialects. The
2897assumed dialect is ATT. When the '``inteldialect``' keyword is present,
2898the inline asm is using the Intel dialect. Currently, ATT and Intel are
2899the only supported dialects. An example is:
2900
2901.. code-block:: llvm
2902
2903 call void asm inteldialect "eieio", ""()
2904
2905If multiple keywords appear the '``sideeffect``' keyword must come
2906first, the '``alignstack``' keyword second and the '``inteldialect``'
2907keyword last.
2908
James Y Knightbc832ed2015-07-08 18:08:36 +00002909Inline Asm Constraint String
2910^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2911
2912The constraint list is a comma-separated string, each element containing one or
2913more constraint codes.
2914
2915For each element in the constraint list an appropriate register or memory
2916operand will be chosen, and it will be made available to assembly template
2917string expansion as ``$0`` for the first constraint in the list, ``$1`` for the
2918second, etc.
2919
2920There are three different types of constraints, which are distinguished by a
2921prefix symbol in front of the constraint code: Output, Input, and Clobber. The
2922constraints must always be given in that order: outputs first, then inputs, then
2923clobbers. They cannot be intermingled.
2924
2925There are also three different categories of constraint codes:
2926
2927- Register constraint. This is either a register class, or a fixed physical
2928 register. This kind of constraint will allocate a register, and if necessary,
2929 bitcast the argument or result to the appropriate type.
2930- Memory constraint. This kind of constraint is for use with an instruction
2931 taking a memory operand. Different constraints allow for different addressing
2932 modes used by the target.
2933- Immediate value constraint. This kind of constraint is for an integer or other
2934 immediate value which can be rendered directly into an instruction. The
2935 various target-specific constraints allow the selection of a value in the
2936 proper range for the instruction you wish to use it with.
2937
2938Output constraints
2939""""""""""""""""""
2940
2941Output constraints are specified by an "``=``" prefix (e.g. "``=r``"). This
2942indicates that the assembly will write to this operand, and the operand will
2943then be made available as a return value of the ``asm`` expression. Output
2944constraints do not consume an argument from the call instruction. (Except, see
2945below about indirect outputs).
2946
2947Normally, it is expected that no output locations are written to by the assembly
2948expression until *all* of the inputs have been read. As such, LLVM may assign
2949the same register to an output and an input. If this is not safe (e.g. if the
2950assembly contains two instructions, where the first writes to one output, and
2951the second reads an input and writes to a second output), then the "``&``"
2952modifier must be used (e.g. "``=&r``") to specify that the output is an
2953"early-clobber" output. Marking an ouput as "early-clobber" ensures that LLVM
2954will not use the same register for any inputs (other than an input tied to this
2955output).
2956
2957Input constraints
2958"""""""""""""""""
2959
2960Input constraints do not have a prefix -- just the constraint codes. Each input
2961constraint will consume one argument from the call instruction. It is not
2962permitted for the asm to write to any input register or memory location (unless
2963that input is tied to an output). Note also that multiple inputs may all be
2964assigned to the same register, if LLVM can determine that they necessarily all
2965contain the same value.
2966
2967Instead of providing a Constraint Code, input constraints may also "tie"
2968themselves to an output constraint, by providing an integer as the constraint
2969string. Tied inputs still consume an argument from the call instruction, and
2970take up a position in the asm template numbering as is usual -- they will simply
2971be constrained to always use the same register as the output they've been tied
2972to. For example, a constraint string of "``=r,0``" says to assign a register for
2973output, and use that register as an input as well (it being the 0'th
2974constraint).
2975
2976It is permitted to tie an input to an "early-clobber" output. In that case, no
2977*other* input may share the same register as the input tied to the early-clobber
2978(even when the other input has the same value).
2979
2980You may only tie an input to an output which has a register constraint, not a
2981memory constraint. Only a single input may be tied to an output.
2982
2983There is also an "interesting" feature which deserves a bit of explanation: if a
2984register class constraint allocates a register which is too small for the value
2985type operand provided as input, the input value will be split into multiple
2986registers, and all of them passed to the inline asm.
2987
2988However, this feature is often not as useful as you might think.
2989
2990Firstly, the registers are *not* guaranteed to be consecutive. So, on those
2991architectures that have instructions which operate on multiple consecutive
2992instructions, this is not an appropriate way to support them. (e.g. the 32-bit
2993SparcV8 has a 64-bit load, which instruction takes a single 32-bit register. The
2994hardware then loads into both the named register, and the next register. This
2995feature of inline asm would not be useful to support that.)
2996
2997A few of the targets provide a template string modifier allowing explicit access
2998to the second register of a two-register operand (e.g. MIPS ``L``, ``M``, and
2999``D``). On such an architecture, you can actually access the second allocated
3000register (yet, still, not any subsequent ones). But, in that case, you're still
3001probably better off simply splitting the value into two separate operands, for
3002clarity. (e.g. see the description of the ``A`` constraint on X86, which,
3003despite existing only for use with this feature, is not really a good idea to
3004use)
3005
3006Indirect inputs and outputs
3007"""""""""""""""""""""""""""
3008
3009Indirect output or input constraints can be specified by the "``*``" modifier
3010(which goes after the "``=``" in case of an output). This indicates that the asm
3011will write to or read from the contents of an *address* provided as an input
3012argument. (Note that in this way, indirect outputs act more like an *input* than
3013an output: just like an input, they consume an argument of the call expression,
3014rather than producing a return value. An indirect output constraint is an
3015"output" only in that the asm is expected to write to the contents of the input
3016memory location, instead of just read from it).
3017
3018This is most typically used for memory constraint, e.g. "``=*m``", to pass the
3019address of a variable as a value.
3020
3021It is also possible to use an indirect *register* constraint, but only on output
3022(e.g. "``=*r``"). This will cause LLVM to allocate a register for an output
3023value normally, and then, separately emit a store to the address provided as
3024input, after the provided inline asm. (It's not clear what value this
3025functionality provides, compared to writing the store explicitly after the asm
3026statement, and it can only produce worse code, since it bypasses many
3027optimization passes. I would recommend not using it.)
3028
3029
3030Clobber constraints
3031"""""""""""""""""""
3032
3033A clobber constraint is indicated by a "``~``" prefix. A clobber does not
3034consume an input operand, nor generate an output. Clobbers cannot use any of the
3035general constraint code letters -- they may use only explicit register
3036constraints, e.g. "``~{eax}``". The one exception is that a clobber string of
3037"``~{memory}``" indicates that the assembly writes to arbitrary undeclared
3038memory locations -- not only the memory pointed to by a declared indirect
3039output.
3040
3041
3042Constraint Codes
3043""""""""""""""""
3044After a potential prefix comes constraint code, or codes.
3045
3046A Constraint Code is either a single letter (e.g. "``r``"), a "``^``" character
3047followed by two letters (e.g. "``^wc``"), or "``{``" register-name "``}``"
3048(e.g. "``{eax}``").
3049
3050The one and two letter constraint codes are typically chosen to be the same as
3051GCC's constraint codes.
3052
3053A single constraint may include one or more than constraint code in it, leaving
3054it up to LLVM to choose which one to use. This is included mainly for
3055compatibility with the translation of GCC inline asm coming from clang.
3056
3057There are two ways to specify alternatives, and either or both may be used in an
3058inline asm constraint list:
3059
30601) Append the codes to each other, making a constraint code set. E.g. "``im``"
3061 or "``{eax}m``". This means "choose any of the options in the set". The
3062 choice of constraint is made independently for each constraint in the
3063 constraint list.
3064
30652) Use "``|``" between constraint code sets, creating alternatives. Every
3066 constraint in the constraint list must have the same number of alternative
3067 sets. With this syntax, the same alternative in *all* of the items in the
3068 constraint list will be chosen together.
3069
3070Putting those together, you might have a two operand constraint string like
3071``"rm|r,ri|rm"``. This indicates that if operand 0 is ``r`` or ``m``, then
3072operand 1 may be one of ``r`` or ``i``. If operand 0 is ``r``, then operand 1
3073may be one of ``r`` or ``m``. But, operand 0 and 1 cannot both be of type m.
3074
3075However, the use of either of the alternatives features is *NOT* recommended, as
3076LLVM is not able to make an intelligent choice about which one to use. (At the
3077point it currently needs to choose, not enough information is available to do so
3078in a smart way.) Thus, it simply tries to make a choice that's most likely to
3079compile, not one that will be optimal performance. (e.g., given "``rm``", it'll
3080always choose to use memory, not registers). And, if given multiple registers,
3081or multiple register classes, it will simply choose the first one. (In fact, it
3082doesn't currently even ensure explicitly specified physical registers are
3083unique, so specifying multiple physical registers as alternatives, like
3084``{r11}{r12},{r11}{r12}``, will assign r11 to both operands, not at all what was
3085intended.)
3086
3087Supported Constraint Code List
3088""""""""""""""""""""""""""""""
3089
3090The constraint codes are, in general, expected to behave the same way they do in
3091GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C
3092inline asm code which was supported by GCC. A mismatch in behavior between LLVM
3093and GCC likely indicates a bug in LLVM.
3094
3095Some constraint codes are typically supported by all targets:
3096
3097- ``r``: A register in the target's general purpose register class.
3098- ``m``: A memory address operand. It is target-specific what addressing modes
3099 are supported, typical examples are register, or register + register offset,
3100 or register + immediate offset (of some target-specific size).
3101- ``i``: An integer constant (of target-specific width). Allows either a simple
3102 immediate, or a relocatable value.
3103- ``n``: An integer constant -- *not* including relocatable values.
3104- ``s``: An integer constant, but allowing *only* relocatable values.
3105- ``X``: Allows an operand of any kind, no constraint whatsoever. Typically
3106 useful to pass a label for an asm branch or call.
3107
3108 .. FIXME: but that surely isn't actually okay to jump out of an asm
3109 block without telling llvm about the control transfer???)
3110
3111- ``{register-name}``: Requires exactly the named physical register.
3112
3113Other constraints are target-specific:
3114
3115AArch64:
3116
3117- ``z``: An immediate integer 0. Outputs ``WZR`` or ``XZR``, as appropriate.
3118- ``I``: An immediate integer valid for an ``ADD`` or ``SUB`` instruction,
3119 i.e. 0 to 4095 with optional shift by 12.
3120- ``J``: An immediate integer that, when negated, is valid for an ``ADD`` or
3121 ``SUB`` instruction, i.e. -1 to -4095 with optional left shift by 12.
3122- ``K``: An immediate integer that is valid for the 'bitmask immediate 32' of a
3123 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 32-bit register.
3124- ``L``: An immediate integer that is valid for the 'bitmask immediate 64' of a
3125 logical instruction like ``AND``, ``EOR``, or ``ORR`` with a 64-bit register.
3126- ``M``: An immediate integer for use with the ``MOV`` assembly alias on a
3127 32-bit register. This is a superset of ``K``: in addition to the bitmask
3128 immediate, also allows immediate integers which can be loaded with a single
3129 ``MOVZ`` or ``MOVL`` instruction.
3130- ``N``: An immediate integer for use with the ``MOV`` assembly alias on a
3131 64-bit register. This is a superset of ``L``.
3132- ``Q``: Memory address operand must be in a single register (no
3133 offsets). (However, LLVM currently does this for the ``m`` constraint as
3134 well.)
3135- ``r``: A 32 or 64-bit integer register (W* or X*).
3136- ``w``: A 32, 64, or 128-bit floating-point/SIMD register.
3137- ``x``: A lower 128-bit floating-point/SIMD register (``V0`` to ``V15``).
3138
3139AMDGPU:
3140
3141- ``r``: A 32 or 64-bit integer register.
3142- ``[0-9]v``: The 32-bit VGPR register, number 0-9.
3143- ``[0-9]s``: The 32-bit SGPR register, number 0-9.
3144
3145
3146All ARM modes:
3147
3148- ``Q``, ``Um``, ``Un``, ``Uq``, ``Us``, ``Ut``, ``Uv``, ``Uy``: Memory address
3149 operand. Treated the same as operand ``m``, at the moment.
3150
3151ARM and ARM's Thumb2 mode:
3152
3153- ``j``: An immediate integer between 0 and 65535 (valid for ``MOVW``)
3154- ``I``: An immediate integer valid for a data-processing instruction.
3155- ``J``: An immediate integer between -4095 and 4095.
3156- ``K``: An immediate integer whose bitwise inverse is valid for a
3157 data-processing instruction. (Can be used with template modifier "``B``" to
3158 print the inverted value).
3159- ``L``: An immediate integer whose negation is valid for a data-processing
3160 instruction. (Can be used with template modifier "``n``" to print the negated
3161 value).
3162- ``M``: A power of two or a integer between 0 and 32.
3163- ``N``: Invalid immediate constraint.
3164- ``O``: Invalid immediate constraint.
3165- ``r``: A general-purpose 32-bit integer register (``r0-r15``).
3166- ``l``: In Thumb2 mode, low 32-bit GPR registers (``r0-r7``). In ARM mode, same
3167 as ``r``.
3168- ``h``: In Thumb2 mode, a high 32-bit GPR register (``r8-r15``). In ARM mode,
3169 invalid.
3170- ``w``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s31``,
3171 ``d0-d31``, or ``q0-q15``.
3172- ``x``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s15``,
3173 ``d0-d7``, or ``q0-q3``.
3174- ``t``: A floating-point/SIMD register, only supports 32-bit values:
3175 ``s0-s31``.
3176
3177ARM's Thumb1 mode:
3178
3179- ``I``: An immediate integer between 0 and 255.
3180- ``J``: An immediate integer between -255 and -1.
3181- ``K``: An immediate integer between 0 and 255, with optional left-shift by
3182 some amount.
3183- ``L``: An immediate integer between -7 and 7.
3184- ``M``: An immediate integer which is a multiple of 4 between 0 and 1020.
3185- ``N``: An immediate integer between 0 and 31.
3186- ``O``: An immediate integer which is a multiple of 4 between -508 and 508.
3187- ``r``: A low 32-bit GPR register (``r0-r7``).
3188- ``l``: A low 32-bit GPR register (``r0-r7``).
3189- ``h``: A high GPR register (``r0-r7``).
3190- ``w``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s31``,
3191 ``d0-d31``, or ``q0-q15``.
3192- ``x``: A 32, 64, or 128-bit floating-point/SIMD register: ``s0-s15``,
3193 ``d0-d7``, or ``q0-q3``.
3194- ``t``: A floating-point/SIMD register, only supports 32-bit values:
3195 ``s0-s31``.
3196
3197
3198Hexagon:
3199
3200- ``o``, ``v``: A memory address operand, treated the same as constraint ``m``,
3201 at the moment.
3202- ``r``: A 32 or 64-bit register.
3203
3204MSP430:
3205
3206- ``r``: An 8 or 16-bit register.
3207
3208MIPS:
3209
3210- ``I``: An immediate signed 16-bit integer.
3211- ``J``: An immediate integer zero.
3212- ``K``: An immediate unsigned 16-bit integer.
3213- ``L``: An immediate 32-bit integer, where the lower 16 bits are 0.
3214- ``N``: An immediate integer between -65535 and -1.
3215- ``O``: An immediate signed 15-bit integer.
3216- ``P``: An immediate integer between 1 and 65535.
3217- ``m``: A memory address operand. In MIPS-SE mode, allows a base address
3218 register plus 16-bit immediate offset. In MIPS mode, just a base register.
3219- ``R``: A memory address operand. In MIPS-SE mode, allows a base address
3220 register plus a 9-bit signed offset. In MIPS mode, the same as constraint
3221 ``m``.
3222- ``ZC``: A memory address operand, suitable for use in a ``pref``, ``ll``, or
3223 ``sc`` instruction on the given subtarget (details vary).
3224- ``r``, ``d``, ``y``: A 32 or 64-bit GPR register.
3225- ``f``: A 32 or 64-bit FPU register (``F0-F31``), or a 128-bit MSA register
Daniel Sanders3745e022015-07-13 09:24:21 +00003226 (``W0-W31``). In the case of MSA registers, it is recommended to use the ``w``
3227 argument modifier for compatibility with GCC.
James Y Knightbc832ed2015-07-08 18:08:36 +00003228- ``c``: A 32-bit or 64-bit GPR register suitable for indirect jump (always
3229 ``25``).
3230- ``l``: The ``lo`` register, 32 or 64-bit.
3231- ``x``: Invalid.
3232
3233NVPTX:
3234
3235- ``b``: A 1-bit integer register.
3236- ``c`` or ``h``: A 16-bit integer register.
3237- ``r``: A 32-bit integer register.
3238- ``l`` or ``N``: A 64-bit integer register.
3239- ``f``: A 32-bit float register.
3240- ``d``: A 64-bit float register.
3241
3242
3243PowerPC:
3244
3245- ``I``: An immediate signed 16-bit integer.
3246- ``J``: An immediate unsigned 16-bit integer, shifted left 16 bits.
3247- ``K``: An immediate unsigned 16-bit integer.
3248- ``L``: An immediate signed 16-bit integer, shifted left 16 bits.
3249- ``M``: An immediate integer greater than 31.
3250- ``N``: An immediate integer that is an exact power of 2.
3251- ``O``: The immediate integer constant 0.
3252- ``P``: An immediate integer constant whose negation is a signed 16-bit
3253 constant.
3254- ``es``, ``o``, ``Q``, ``Z``, ``Zy``: A memory address operand, currently
3255 treated the same as ``m``.
3256- ``r``: A 32 or 64-bit integer register.
3257- ``b``: A 32 or 64-bit integer register, excluding ``R0`` (that is:
3258 ``R1-R31``).
3259- ``f``: A 32 or 64-bit float register (``F0-F31``), or when QPX is enabled, a
3260 128 or 256-bit QPX register (``Q0-Q31``; aliases the ``F`` registers).
3261- ``v``: For ``4 x f32`` or ``4 x f64`` types, when QPX is enabled, a
3262 128 or 256-bit QPX register (``Q0-Q31``), otherwise a 128-bit
3263 altivec vector register (``V0-V31``).
3264
3265 .. FIXME: is this a bug that v accepts QPX registers? I think this
3266 is supposed to only use the altivec vector registers?
3267
3268- ``y``: Condition register (``CR0-CR7``).
3269- ``wc``: An individual CR bit in a CR register.
3270- ``wa``, ``wd``, ``wf``: Any 128-bit VSX vector register, from the full VSX
3271 register set (overlapping both the floating-point and vector register files).
3272- ``ws``: A 32 or 64-bit floating point register, from the full VSX register
3273 set.
3274
3275Sparc:
3276
3277- ``I``: An immediate 13-bit signed integer.
3278- ``r``: A 32-bit integer register.
3279
3280SystemZ:
3281
3282- ``I``: An immediate unsigned 8-bit integer.
3283- ``J``: An immediate unsigned 12-bit integer.
3284- ``K``: An immediate signed 16-bit integer.
3285- ``L``: An immediate signed 20-bit integer.
3286- ``M``: An immediate integer 0x7fffffff.
3287- ``Q``, ``R``, ``S``, ``T``: A memory address operand, treated the same as
3288 ``m``, at the moment.
3289- ``r`` or ``d``: A 32, 64, or 128-bit integer register.
3290- ``a``: A 32, 64, or 128-bit integer address register (excludes R0, which in an
3291 address context evaluates as zero).
3292- ``h``: A 32-bit value in the high part of a 64bit data register
3293 (LLVM-specific)
3294- ``f``: A 32, 64, or 128-bit floating point register.
3295
3296X86:
3297
3298- ``I``: An immediate integer between 0 and 31.
3299- ``J``: An immediate integer between 0 and 64.
3300- ``K``: An immediate signed 8-bit integer.
3301- ``L``: An immediate integer, 0xff or 0xffff or (in 64-bit mode only)
3302 0xffffffff.
3303- ``M``: An immediate integer between 0 and 3.
3304- ``N``: An immediate unsigned 8-bit integer.
3305- ``O``: An immediate integer between 0 and 127.
3306- ``e``: An immediate 32-bit signed integer.
3307- ``Z``: An immediate 32-bit unsigned integer.
3308- ``o``, ``v``: Treated the same as ``m``, at the moment.
3309- ``q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit
3310 ``l`` integer register. On X86-32, this is the ``a``, ``b``, ``c``, and ``d``
3311 registers, and on X86-64, it is all of the integer registers.
3312- ``Q``: An 8, 16, 32, or 64-bit register which can be accessed as an 8-bit
3313 ``h`` integer register. This is the ``a``, ``b``, ``c``, and ``d`` registers.
3314- ``r`` or ``l``: An 8, 16, 32, or 64-bit integer register.
3315- ``R``: An 8, 16, 32, or 64-bit "legacy" integer register -- one which has
3316 existed since i386, and can be accessed without the REX prefix.
3317- ``f``: A 32, 64, or 80-bit '387 FPU stack pseudo-register.
3318- ``y``: A 64-bit MMX register, if MMX is enabled.
3319- ``x``: If SSE is enabled: a 32 or 64-bit scalar operand, or 128-bit vector
3320 operand in a SSE register. If AVX is also enabled, can also be a 256-bit
3321 vector operand in an AVX register. If AVX-512 is also enabled, can also be a
3322 512-bit vector operand in an AVX512 register, Otherwise, an error.
3323- ``Y``: The same as ``x``, if *SSE2* is enabled, otherwise an error.
3324- ``A``: Special case: allocates EAX first, then EDX, for a single operand (in
3325 32-bit mode, a 64-bit integer operand will get split into two registers). It
3326 is not recommended to use this constraint, as in 64-bit mode, the 64-bit
3327 operand will get allocated only to RAX -- if two 32-bit operands are needed,
3328 you're better off splitting it yourself, before passing it to the asm
3329 statement.
3330
3331XCore:
3332
3333- ``r``: A 32-bit integer register.
3334
3335
3336.. _inline-asm-modifiers:
3337
3338Asm template argument modifiers
3339^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3340
3341In the asm template string, modifiers can be used on the operand reference, like
3342"``${0:n}``".
3343
3344The modifiers are, in general, expected to behave the same way they do in
3345GCC. LLVM's support is often implemented on an 'as-needed' basis, to support C
3346inline asm code which was supported by GCC. A mismatch in behavior between LLVM
3347and GCC likely indicates a bug in LLVM.
3348
3349Target-independent:
3350
Sean Silvaa1190322015-08-06 22:56:48 +00003351- ``c``: Print an immediate integer constant unadorned, without
James Y Knightbc832ed2015-07-08 18:08:36 +00003352 the target-specific immediate punctuation (e.g. no ``$`` prefix).
3353- ``n``: Negate and print immediate integer constant unadorned, without the
3354 target-specific immediate punctuation (e.g. no ``$`` prefix).
3355- ``l``: Print as an unadorned label, without the target-specific label
3356 punctuation (e.g. no ``$`` prefix).
3357
3358AArch64:
3359
3360- ``w``: Print a GPR register with a ``w*`` name instead of ``x*`` name. E.g.,
3361 instead of ``x30``, print ``w30``.
3362- ``x``: Print a GPR register with a ``x*`` name. (this is the default, anyhow).
3363- ``b``, ``h``, ``s``, ``d``, ``q``: Print a floating-point/SIMD register with a
3364 ``b*``, ``h*``, ``s*``, ``d*``, or ``q*`` name, rather than the default of
3365 ``v*``.
3366
3367AMDGPU:
3368
3369- ``r``: No effect.
3370
3371ARM:
3372
3373- ``a``: Print an operand as an address (with ``[`` and ``]`` surrounding a
3374 register).
3375- ``P``: No effect.
3376- ``q``: No effect.
3377- ``y``: Print a VFP single-precision register as an indexed double (e.g. print
3378 as ``d4[1]`` instead of ``s9``)
3379- ``B``: Bitwise invert and print an immediate integer constant without ``#``
3380 prefix.
3381- ``L``: Print the low 16-bits of an immediate integer constant.
3382- ``M``: Print as a register set suitable for ldm/stm. Also prints *all*
3383 register operands subsequent to the specified one (!), so use carefully.
3384- ``Q``: Print the low-order register of a register-pair, or the low-order
3385 register of a two-register operand.
3386- ``R``: Print the high-order register of a register-pair, or the high-order
3387 register of a two-register operand.
3388- ``H``: Print the second register of a register-pair. (On a big-endian system,
3389 ``H`` is equivalent to ``Q``, and on little-endian system, ``H`` is equivalent
3390 to ``R``.)
3391
3392 .. FIXME: H doesn't currently support printing the second register
3393 of a two-register operand.
3394
3395- ``e``: Print the low doubleword register of a NEON quad register.
3396- ``f``: Print the high doubleword register of a NEON quad register.
3397- ``m``: Print the base register of a memory operand without the ``[`` and ``]``
3398 adornment.
3399
3400Hexagon:
3401
3402- ``L``: Print the second register of a two-register operand. Requires that it
3403 has been allocated consecutively to the first.
3404
3405 .. FIXME: why is it restricted to consecutive ones? And there's
3406 nothing that ensures that happens, is there?
3407
3408- ``I``: Print the letter 'i' if the operand is an integer constant, otherwise
3409 nothing. Used to print 'addi' vs 'add' instructions.
3410
3411MSP430:
3412
3413No additional modifiers.
3414
3415MIPS:
3416
3417- ``X``: Print an immediate integer as hexadecimal
3418- ``x``: Print the low 16 bits of an immediate integer as hexadecimal.
3419- ``d``: Print an immediate integer as decimal.
3420- ``m``: Subtract one and print an immediate integer as decimal.
3421- ``z``: Print $0 if an immediate zero, otherwise print normally.
3422- ``L``: Print the low-order register of a two-register operand, or prints the
3423 address of the low-order word of a double-word memory operand.
3424
3425 .. FIXME: L seems to be missing memory operand support.
3426
3427- ``M``: Print the high-order register of a two-register operand, or prints the
3428 address of the high-order word of a double-word memory operand.
3429
3430 .. FIXME: M seems to be missing memory operand support.
3431
3432- ``D``: Print the second register of a two-register operand, or prints the
3433 second word of a double-word memory operand. (On a big-endian system, ``D`` is
3434 equivalent to ``L``, and on little-endian system, ``D`` is equivalent to
3435 ``M``.)
Daniel Sanders3745e022015-07-13 09:24:21 +00003436- ``w``: No effect. Provided for compatibility with GCC which requires this
3437 modifier in order to print MSA registers (``W0-W31``) with the ``f``
3438 constraint.
James Y Knightbc832ed2015-07-08 18:08:36 +00003439
3440NVPTX:
3441
3442- ``r``: No effect.
3443
3444PowerPC:
3445
3446- ``L``: Print the second register of a two-register operand. Requires that it
3447 has been allocated consecutively to the first.
3448
3449 .. FIXME: why is it restricted to consecutive ones? And there's
3450 nothing that ensures that happens, is there?
3451
3452- ``I``: Print the letter 'i' if the operand is an integer constant, otherwise
3453 nothing. Used to print 'addi' vs 'add' instructions.
3454- ``y``: For a memory operand, prints formatter for a two-register X-form
3455 instruction. (Currently always prints ``r0,OPERAND``).
3456- ``U``: Prints 'u' if the memory operand is an update form, and nothing
3457 otherwise. (NOTE: LLVM does not support update form, so this will currently
3458 always print nothing)
3459- ``X``: Prints 'x' if the memory operand is an indexed form. (NOTE: LLVM does
3460 not support indexed form, so this will currently always print nothing)
3461
3462Sparc:
3463
3464- ``r``: No effect.
3465
3466SystemZ:
3467
3468SystemZ implements only ``n``, and does *not* support any of the other
3469target-independent modifiers.
3470
3471X86:
3472
3473- ``c``: Print an unadorned integer or symbol name. (The latter is
3474 target-specific behavior for this typically target-independent modifier).
3475- ``A``: Print a register name with a '``*``' before it.
3476- ``b``: Print an 8-bit register name (e.g. ``al``); do nothing on a memory
3477 operand.
3478- ``h``: Print the upper 8-bit register name (e.g. ``ah``); do nothing on a
3479 memory operand.
3480- ``w``: Print the 16-bit register name (e.g. ``ax``); do nothing on a memory
3481 operand.
3482- ``k``: Print the 32-bit register name (e.g. ``eax``); do nothing on a memory
3483 operand.
3484- ``q``: Print the 64-bit register name (e.g. ``rax``), if 64-bit registers are
3485 available, otherwise the 32-bit register name; do nothing on a memory operand.
3486- ``n``: Negate and print an unadorned integer, or, for operands other than an
3487 immediate integer (e.g. a relocatable symbol expression), print a '-' before
3488 the operand. (The behavior for relocatable symbol expressions is a
3489 target-specific behavior for this typically target-independent modifier)
3490- ``H``: Print a memory reference with additional offset +8.
3491- ``P``: Print a memory reference or operand for use as the argument of a call
3492 instruction. (E.g. omit ``(rip)``, even though it's PC-relative.)
3493
3494XCore:
3495
3496No additional modifiers.
3497
3498
Sean Silvab084af42012-12-07 10:36:55 +00003499Inline Asm Metadata
3500^^^^^^^^^^^^^^^^^^^
3501
3502The call instructions that wrap inline asm nodes may have a
3503"``!srcloc``" MDNode attached to it that contains a list of constant
3504integers. If present, the code generator will use the integer as the
3505location cookie value when report errors through the ``LLVMContext``
3506error reporting mechanisms. This allows a front-end to correlate backend
3507errors that occur with inline asm back to the source code that produced
3508it. For example:
3509
3510.. code-block:: llvm
3511
3512 call void asm sideeffect "something bad", ""(), !srcloc !42
3513 ...
3514 !42 = !{ i32 1234567 }
3515
3516It is up to the front-end to make sense of the magic numbers it places
3517in the IR. If the MDNode contains multiple constants, the code generator
3518will use the one that corresponds to the line of the asm that the error
3519occurs on.
3520
3521.. _metadata:
3522
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00003523Metadata
3524========
Sean Silvab084af42012-12-07 10:36:55 +00003525
3526LLVM IR allows metadata to be attached to instructions in the program
3527that can convey extra information about the code to the optimizers and
3528code generator. One example application of metadata is source-level
3529debug information. There are two metadata primitives: strings and nodes.
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00003530
Sean Silvaa1190322015-08-06 22:56:48 +00003531Metadata does not have a type, and is not a value. If referenced from a
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00003532``call`` instruction, it uses the ``metadata`` type.
3533
3534All metadata are identified in syntax by a exclamation point ('``!``').
3535
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003536.. _metadata-string:
3537
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00003538Metadata Nodes and Metadata Strings
3539-----------------------------------
Sean Silvab084af42012-12-07 10:36:55 +00003540
3541A metadata string is a string surrounded by double quotes. It can
3542contain any character by escaping non-printable characters with
3543"``\xx``" where "``xx``" is the two digit hex code. For example:
3544"``!"test\00"``".
3545
3546Metadata nodes are represented with notation similar to structure
3547constants (a comma separated list of elements, surrounded by braces and
3548preceded by an exclamation point). Metadata nodes can have any values as
3549their operand. For example:
3550
3551.. code-block:: llvm
3552
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00003553 !{ !"test\00", i32 10}
Sean Silvab084af42012-12-07 10:36:55 +00003554
Duncan P. N. Exon Smith090a19b2015-01-08 22:38:29 +00003555Metadata nodes that aren't uniqued use the ``distinct`` keyword. For example:
3556
3557.. code-block:: llvm
3558
3559 !0 = distinct !{!"test\00", i32 10}
3560
Duncan P. N. Exon Smith99010342015-01-08 23:50:26 +00003561``distinct`` nodes are useful when nodes shouldn't be merged based on their
Sean Silvaa1190322015-08-06 22:56:48 +00003562content. They can also occur when transformations cause uniquing collisions
Duncan P. N. Exon Smith99010342015-01-08 23:50:26 +00003563when metadata operands change.
3564
Sean Silvab084af42012-12-07 10:36:55 +00003565A :ref:`named metadata <namedmetadatastructure>` is a collection of
3566metadata nodes, which can be looked up in the module symbol table. For
3567example:
3568
3569.. code-block:: llvm
3570
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00003571 !foo = !{!4, !3}
Sean Silvab084af42012-12-07 10:36:55 +00003572
3573Metadata can be used as function arguments. Here ``llvm.dbg.value``
3574function is using two metadata arguments:
3575
3576.. code-block:: llvm
3577
3578 call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
3579
3580Metadata can be attached with an instruction. Here metadata ``!21`` is
3581attached to the ``add`` instruction using the ``!dbg`` identifier:
3582
3583.. code-block:: llvm
3584
3585 %indvar.next = add i64 %indvar, 1, !dbg !21
3586
3587More information about specific metadata nodes recognized by the
3588optimizers and code generator is found below.
3589
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003590.. _specialized-metadata:
3591
Duncan P. N. Exon Smith6a484832015-01-13 21:10:44 +00003592Specialized Metadata Nodes
3593^^^^^^^^^^^^^^^^^^^^^^^^^^
3594
3595Specialized metadata nodes are custom data structures in metadata (as opposed
Sean Silvaa1190322015-08-06 22:56:48 +00003596to generic tuples). Their fields are labelled, and can be specified in any
Duncan P. N. Exon Smith6a484832015-01-13 21:10:44 +00003597order.
3598
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003599These aren't inherently debug info centric, but currently all the specialized
3600metadata nodes are related to debug info.
3601
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003602.. _DICompileUnit:
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003603
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003604DICompileUnit
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003605"""""""""""""
3606
Sean Silvaa1190322015-08-06 22:56:48 +00003607``DICompileUnit`` nodes represent a compile unit. The ``enums:``,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003608``retainedTypes:``, ``subprograms:``, ``globals:`` and ``imports:`` fields are
3609tuples containing the debug info to be emitted along with the compile unit,
3610regardless of code optimizations (some nodes are only emitted if there are
3611references to them from instructions).
3612
3613.. code-block:: llvm
3614
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003615 !0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang",
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003616 isOptimized: true, flags: "-O2", runtimeVersion: 2,
3617 splitDebugFilename: "abc.debug", emissionKind: 1,
3618 enums: !2, retainedTypes: !3, subprograms: !4,
3619 globals: !5, imports: !6)
3620
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003621Compile unit descriptors provide the root scope for objects declared in a
Sean Silvaa1190322015-08-06 22:56:48 +00003622specific compilation unit. File descriptors are defined using this scope.
3623These descriptors are collected by a named metadata ``!llvm.dbg.cu``. They
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003624keep track of subprograms, global variables, type information, and imported
3625entities (declarations and namespaces).
3626
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003627.. _DIFile:
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003628
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003629DIFile
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003630""""""
3631
Sean Silvaa1190322015-08-06 22:56:48 +00003632``DIFile`` nodes represent files. The ``filename:`` can include slashes.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003633
3634.. code-block:: llvm
3635
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003636 !0 = !DIFile(filename: "path/to/file", directory: "/path/to/dir")
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003637
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003638Files are sometimes used in ``scope:`` fields, and are the only valid target
3639for ``file:`` fields.
3640
Michael Kuperstein605308a2015-05-14 10:58:59 +00003641.. _DIBasicType:
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003642
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003643DIBasicType
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003644"""""""""""
3645
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003646``DIBasicType`` nodes represent primitive types, such as ``int``, ``bool`` and
Sean Silvaa1190322015-08-06 22:56:48 +00003647``float``. ``tag:`` defaults to ``DW_TAG_base_type``.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003648
3649.. code-block:: llvm
3650
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003651 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003652 encoding: DW_ATE_unsigned_char)
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003653 !1 = !DIBasicType(tag: DW_TAG_unspecified_type, name: "decltype(nullptr)")
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003654
Sean Silvaa1190322015-08-06 22:56:48 +00003655The ``encoding:`` describes the details of the type. Usually it's one of the
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003656following:
3657
3658.. code-block:: llvm
3659
3660 DW_ATE_address = 1
3661 DW_ATE_boolean = 2
3662 DW_ATE_float = 4
3663 DW_ATE_signed = 5
3664 DW_ATE_signed_char = 6
3665 DW_ATE_unsigned = 7
3666 DW_ATE_unsigned_char = 8
3667
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003668.. _DISubroutineType:
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003669
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003670DISubroutineType
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003671""""""""""""""""
3672
Sean Silvaa1190322015-08-06 22:56:48 +00003673``DISubroutineType`` nodes represent subroutine types. Their ``types:`` field
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003674refers to a tuple; the first operand is the return type, while the rest are the
Sean Silvaa1190322015-08-06 22:56:48 +00003675types of the formal arguments in order. If the first operand is ``null``, that
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003676represents a function with no return value (such as ``void foo() {}`` in C++).
3677
3678.. code-block:: llvm
3679
3680 !0 = !BasicType(name: "int", size: 32, align: 32, DW_ATE_signed)
3681 !1 = !BasicType(name: "char", size: 8, align: 8, DW_ATE_signed_char)
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003682 !2 = !DISubroutineType(types: !{null, !0, !1}) ; void (int, char)
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003683
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003684.. _DIDerivedType:
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003685
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003686DIDerivedType
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003687"""""""""""""
3688
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003689``DIDerivedType`` nodes represent types derived from other types, such as
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003690qualified types.
3691
3692.. code-block:: llvm
3693
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003694 !0 = !DIBasicType(name: "unsigned char", size: 8, align: 8,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003695 encoding: DW_ATE_unsigned_char)
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003696 !1 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !0, size: 32,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003697 align: 32)
3698
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003699The following ``tag:`` values are valid:
3700
3701.. code-block:: llvm
3702
3703 DW_TAG_formal_parameter = 5
3704 DW_TAG_member = 13
3705 DW_TAG_pointer_type = 15
3706 DW_TAG_reference_type = 16
3707 DW_TAG_typedef = 22
3708 DW_TAG_ptr_to_member_type = 31
3709 DW_TAG_const_type = 38
3710 DW_TAG_volatile_type = 53
3711 DW_TAG_restrict_type = 55
3712
3713``DW_TAG_member`` is used to define a member of a :ref:`composite type
Sean Silvaa1190322015-08-06 22:56:48 +00003714<DICompositeType>` or :ref:`subprogram <DISubprogram>`. The type of the member
3715is the ``baseType:``. The ``offset:`` is the member's bit offset.
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003716``DW_TAG_formal_parameter`` is used to define a member which is a formal
3717argument of a subprogram.
3718
3719``DW_TAG_typedef`` is used to provide a name for the ``baseType:``.
3720
3721``DW_TAG_pointer_type``, ``DW_TAG_reference_type``, ``DW_TAG_const_type``,
3722``DW_TAG_volatile_type`` and ``DW_TAG_restrict_type`` are used to qualify the
3723``baseType:``.
3724
3725Note that the ``void *`` type is expressed as a type derived from NULL.
3726
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003727.. _DICompositeType:
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003728
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003729DICompositeType
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003730"""""""""""""""
3731
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003732``DICompositeType`` nodes represent types composed of other types, like
Sean Silvaa1190322015-08-06 22:56:48 +00003733structures and unions. ``elements:`` points to a tuple of the composed types.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003734
3735If the source language supports ODR, the ``identifier:`` field gives the unique
Sean Silvaa1190322015-08-06 22:56:48 +00003736identifier used for type merging between modules. When specified, other types
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003737can refer to composite types indirectly via a :ref:`metadata string
3738<metadata-string>` that matches their identifier.
3739
3740.. code-block:: llvm
3741
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003742 !0 = !DIEnumerator(name: "SixKind", value: 7)
3743 !1 = !DIEnumerator(name: "SevenKind", value: 7)
3744 !2 = !DIEnumerator(name: "NegEightKind", value: -8)
3745 !3 = !DICompositeType(tag: DW_TAG_enumeration_type, name: "Enum", file: !12,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003746 line: 2, size: 32, align: 32, identifier: "_M4Enum",
3747 elements: !{!0, !1, !2})
3748
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003749The following ``tag:`` values are valid:
3750
3751.. code-block:: llvm
3752
3753 DW_TAG_array_type = 1
3754 DW_TAG_class_type = 2
3755 DW_TAG_enumeration_type = 4
3756 DW_TAG_structure_type = 19
3757 DW_TAG_union_type = 23
3758 DW_TAG_subroutine_type = 21
3759 DW_TAG_inheritance = 28
3760
3761
3762For ``DW_TAG_array_type``, the ``elements:`` should be :ref:`subrange
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003763descriptors <DISubrange>`, each representing the range of subscripts at that
Sean Silvaa1190322015-08-06 22:56:48 +00003764level of indexing. The ``DIFlagVector`` flag to ``flags:`` indicates that an
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003765array type is a native packed vector.
3766
3767For ``DW_TAG_enumeration_type``, the ``elements:`` should be :ref:`enumerator
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003768descriptors <DIEnumerator>`, each representing the definition of an enumeration
Sean Silvaa1190322015-08-06 22:56:48 +00003769value for the set. All enumeration type descriptors are collected in the
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003770``enums:`` field of the :ref:`compile unit <DICompileUnit>`.
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003771
3772For ``DW_TAG_structure_type``, ``DW_TAG_class_type``, and
3773``DW_TAG_union_type``, the ``elements:`` should be :ref:`derived types
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003774<DIDerivedType>` with ``tag: DW_TAG_member`` or ``tag: DW_TAG_inheritance``.
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003775
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003776.. _DISubrange:
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003777
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003778DISubrange
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003779""""""""""
3780
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003781``DISubrange`` nodes are the elements for ``DW_TAG_array_type`` variants of
Sean Silvaa1190322015-08-06 22:56:48 +00003782:ref:`DICompositeType`. ``count: -1`` indicates an empty array.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003783
3784.. code-block:: llvm
3785
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003786 !0 = !DISubrange(count: 5, lowerBound: 0) ; array counting from 0
3787 !1 = !DISubrange(count: 5, lowerBound: 1) ; array counting from 1
3788 !2 = !DISubrange(count: -1) ; empty array.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003789
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003790.. _DIEnumerator:
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003791
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003792DIEnumerator
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003793""""""""""""
3794
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003795``DIEnumerator`` nodes are the elements for ``DW_TAG_enumeration_type``
3796variants of :ref:`DICompositeType`.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003797
3798.. code-block:: llvm
3799
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003800 !0 = !DIEnumerator(name: "SixKind", value: 7)
3801 !1 = !DIEnumerator(name: "SevenKind", value: 7)
3802 !2 = !DIEnumerator(name: "NegEightKind", value: -8)
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003803
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003804DITemplateTypeParameter
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003805"""""""""""""""""""""""
3806
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003807``DITemplateTypeParameter`` nodes represent type parameters to generic source
Sean Silvaa1190322015-08-06 22:56:48 +00003808language constructs. They are used (optionally) in :ref:`DICompositeType` and
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003809:ref:`DISubprogram` ``templateParams:`` fields.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003810
3811.. code-block:: llvm
3812
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003813 !0 = !DITemplateTypeParameter(name: "Ty", type: !1)
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003814
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003815DITemplateValueParameter
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003816""""""""""""""""""""""""
3817
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003818``DITemplateValueParameter`` nodes represent value parameters to generic source
Sean Silvaa1190322015-08-06 22:56:48 +00003819language constructs. ``tag:`` defaults to ``DW_TAG_template_value_parameter``,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003820but if specified can also be set to ``DW_TAG_GNU_template_template_param`` or
Sean Silvaa1190322015-08-06 22:56:48 +00003821``DW_TAG_GNU_template_param_pack``. They are used (optionally) in
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003822:ref:`DICompositeType` and :ref:`DISubprogram` ``templateParams:`` fields.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003823
3824.. code-block:: llvm
3825
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003826 !0 = !DITemplateValueParameter(name: "Ty", type: !1, value: i32 7)
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003827
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003828DINamespace
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003829"""""""""""
3830
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003831``DINamespace`` nodes represent namespaces in the source language.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003832
3833.. code-block:: llvm
3834
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003835 !0 = !DINamespace(name: "myawesomeproject", scope: !1, file: !2, line: 7)
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003836
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003837DIGlobalVariable
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003838""""""""""""""""
3839
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003840``DIGlobalVariable`` nodes represent global variables in the source language.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003841
3842.. code-block:: llvm
3843
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003844 !0 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !1,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003845 file: !2, line: 7, type: !3, isLocal: true,
3846 isDefinition: false, variable: i32* @foo,
3847 declaration: !4)
3848
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003849All global variables should be referenced by the `globals:` field of a
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003850:ref:`compile unit <DICompileUnit>`.
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003851
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003852.. _DISubprogram:
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003853
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003854DISubprogram
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003855""""""""""""
3856
Sean Silvaa1190322015-08-06 22:56:48 +00003857``DISubprogram`` nodes represent functions from the source language. The
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003858``variables:`` field points at :ref:`variables <DILocalVariable>` that must be
Sean Silvaa1190322015-08-06 22:56:48 +00003859retained, even if their IR counterparts are optimized out of the IR. The
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003860``type:`` field must point at an :ref:`DISubroutineType`.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003861
3862.. code-block:: llvm
3863
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003864 !0 = !DISubprogram(name: "foo", linkageName: "_Zfoov", scope: !1,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003865 file: !2, line: 7, type: !3, isLocal: true,
3866 isDefinition: false, scopeLine: 8, containingType: !4,
3867 virtuality: DW_VIRTUALITY_pure_virtual, virtualIndex: 10,
3868 flags: DIFlagPrototyped, isOptimized: true,
3869 function: void ()* @_Z3foov,
3870 templateParams: !5, declaration: !6, variables: !7)
3871
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003872.. _DILexicalBlock:
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003873
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003874DILexicalBlock
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003875""""""""""""""
3876
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003877``DILexicalBlock`` nodes describe nested blocks within a :ref:`subprogram
Sean Silvaa1190322015-08-06 22:56:48 +00003878<DISubprogram>`. The line number and column numbers are used to dinstinguish
3879two lexical blocks at same depth. They are valid targets for ``scope:``
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003880fields.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003881
3882.. code-block:: llvm
3883
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003884 !0 = distinct !DILexicalBlock(scope: !1, file: !2, line: 7, column: 35)
Duncan P. N. Exon Smithd937cd92015-03-17 23:41:05 +00003885
3886Usually lexical blocks are ``distinct`` to prevent node merging based on
3887operands.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003888
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003889.. _DILexicalBlockFile:
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003890
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003891DILexicalBlockFile
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003892""""""""""""""""""
3893
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003894``DILexicalBlockFile`` nodes are used to discriminate between sections of a
Sean Silvaa1190322015-08-06 22:56:48 +00003895:ref:`lexical block <DILexicalBlock>`. The ``file:`` field can be changed to
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003896indicate textual inclusion, or the ``discriminator:`` field can be used to
3897discriminate between control flow within a single block in the source language.
3898
3899.. code-block:: llvm
3900
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003901 !0 = !DILexicalBlock(scope: !3, file: !4, line: 7, column: 35)
3902 !1 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 0)
3903 !2 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 1)
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003904
Michael Kuperstein605308a2015-05-14 10:58:59 +00003905.. _DILocation:
3906
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003907DILocation
Duncan P. N. Exon Smith6a484832015-01-13 21:10:44 +00003908""""""""""
3909
Sean Silvaa1190322015-08-06 22:56:48 +00003910``DILocation`` nodes represent source debug locations. The ``scope:`` field is
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003911mandatory, and points at an :ref:`DILexicalBlockFile`, an
3912:ref:`DILexicalBlock`, or an :ref:`DISubprogram`.
Duncan P. N. Exon Smith6a484832015-01-13 21:10:44 +00003913
3914.. code-block:: llvm
3915
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003916 !0 = !DILocation(line: 2900, column: 42, scope: !1, inlinedAt: !2)
Duncan P. N. Exon Smith6a484832015-01-13 21:10:44 +00003917
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003918.. _DILocalVariable:
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003919
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003920DILocalVariable
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003921"""""""""""""""
3922
Sean Silvaa1190322015-08-06 22:56:48 +00003923``DILocalVariable`` nodes represent local variables in the source language. If
Duncan P. N. Exon Smithed013cd2015-07-31 18:58:39 +00003924the ``arg:`` field is set to non-zero, then this variable is a subprogram
3925parameter, and it will be included in the ``variables:`` field of its
3926:ref:`DISubprogram`.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003927
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003928.. code-block:: llvm
3929
Duncan P. N. Exon Smithed013cd2015-07-31 18:58:39 +00003930 !0 = !DILocalVariable(name: "this", arg: 1, scope: !3, file: !2, line: 7,
3931 type: !3, flags: DIFlagArtificial)
3932 !1 = !DILocalVariable(name: "x", arg: 2, scope: !4, file: !2, line: 7,
3933 type: !3)
3934 !2 = !DILocalVariable(name: "y", scope: !5, file: !2, line: 7, type: !3)
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003935
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003936DIExpression
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003937""""""""""""
3938
Sean Silvaa1190322015-08-06 22:56:48 +00003939``DIExpression`` nodes represent DWARF expression sequences. They are used in
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003940:ref:`debug intrinsics<dbg_intrinsics>` (such as ``llvm.dbg.declare``) to
3941describe how the referenced LLVM variable relates to the source language
3942variable.
3943
3944The current supported vocabulary is limited:
3945
3946- ``DW_OP_deref`` dereferences the working expression.
3947- ``DW_OP_plus, 93`` adds ``93`` to the working expression.
3948- ``DW_OP_bit_piece, 16, 8`` specifies the offset and size (``16`` and ``8``
3949 here, respectively) of the variable piece from the working expression.
3950
3951.. code-block:: llvm
3952
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003953 !0 = !DIExpression(DW_OP_deref)
3954 !1 = !DIExpression(DW_OP_plus, 3)
3955 !2 = !DIExpression(DW_OP_bit_piece, 3, 7)
3956 !3 = !DIExpression(DW_OP_deref, DW_OP_plus, 3, DW_OP_bit_piece, 3, 7)
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003957
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003958DIObjCProperty
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003959""""""""""""""
3960
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003961``DIObjCProperty`` nodes represent Objective-C property nodes.
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003962
3963.. code-block:: llvm
3964
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003965 !3 = !DIObjCProperty(name: "foo", file: !1, line: 7, setter: "setFoo",
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003966 getter: "getFoo", attributes: 7, type: !2)
3967
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003968DIImportedEntity
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003969""""""""""""""""
3970
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003971``DIImportedEntity`` nodes represent entities (such as modules) imported into a
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003972compile unit.
3973
3974.. code-block:: llvm
3975
Duncan P. N. Exon Smitha9308c42015-04-29 16:38:44 +00003976 !2 = !DIImportedEntity(tag: DW_TAG_imported_module, name: "foo", scope: !0,
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +00003977 entity: !1, line: 7)
3978
Sean Silvab084af42012-12-07 10:36:55 +00003979'``tbaa``' Metadata
3980^^^^^^^^^^^^^^^^^^^
3981
3982In LLVM IR, memory does not have types, so LLVM's own type system is not
3983suitable for doing TBAA. Instead, metadata is added to the IR to
3984describe a type system of a higher level language. This can be used to
3985implement typical C/C++ TBAA, but it can also be used to implement
3986custom alias analysis behavior for other languages.
3987
3988The current metadata format is very simple. TBAA metadata nodes have up
3989to three fields, e.g.:
3990
3991.. code-block:: llvm
3992
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00003993 !0 = !{ !"an example type tree" }
3994 !1 = !{ !"int", !0 }
3995 !2 = !{ !"float", !0 }
3996 !3 = !{ !"const float", !2, i64 1 }
Sean Silvab084af42012-12-07 10:36:55 +00003997
3998The first field is an identity field. It can be any value, usually a
3999metadata string, which uniquely identifies the type. The most important
4000name in the tree is the name of the root node. Two trees with different
4001root node names are entirely disjoint, even if they have leaves with
4002common names.
4003
4004The second field identifies the type's parent node in the tree, or is
4005null or omitted for a root node. A type is considered to alias all of
4006its descendants and all of its ancestors in the tree. Also, a type is
4007considered to alias all types in other trees, so that bitcode produced
4008from multiple front-ends is handled conservatively.
4009
4010If the third field is present, it's an integer which if equal to 1
4011indicates that the type is "constant" (meaning
4012``pointsToConstantMemory`` should return true; see `other useful
4013AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_).
4014
4015'``tbaa.struct``' Metadata
4016^^^^^^^^^^^^^^^^^^^^^^^^^^
4017
4018The :ref:`llvm.memcpy <int_memcpy>` is often used to implement
4019aggregate assignment operations in C and similar languages, however it
4020is defined to copy a contiguous region of memory, which is more than
4021strictly necessary for aggregate types which contain holes due to
4022padding. Also, it doesn't contain any TBAA information about the fields
4023of the aggregate.
4024
4025``!tbaa.struct`` metadata can describe which memory subregions in a
4026memcpy are padding and what the TBAA tags of the struct are.
4027
4028The current metadata format is very simple. ``!tbaa.struct`` metadata
4029nodes are a list of operands which are in conceptual groups of three.
4030For each group of three, the first operand gives the byte offset of a
4031field in bytes, the second gives its size in bytes, and the third gives
4032its tbaa tag. e.g.:
4033
4034.. code-block:: llvm
4035
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004036 !4 = !{ i64 0, i64 4, !1, i64 8, i64 4, !2 }
Sean Silvab084af42012-12-07 10:36:55 +00004037
4038This describes a struct with two fields. The first is at offset 0 bytes
4039with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes
4040and has size 4 bytes and has tbaa tag !2.
4041
4042Note that the fields need not be contiguous. In this example, there is a
40434 byte gap between the two fields. This gap represents padding which
4044does not carry useful data and need not be preserved.
4045
Hal Finkel94146652014-07-24 14:25:39 +00004046'``noalias``' and '``alias.scope``' Metadata
Dan Liewbafdcba2014-07-28 13:33:51 +00004047^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Hal Finkel94146652014-07-24 14:25:39 +00004048
4049``noalias`` and ``alias.scope`` metadata provide the ability to specify generic
4050noalias memory-access sets. This means that some collection of memory access
4051instructions (loads, stores, memory-accessing calls, etc.) that carry
4052``noalias`` metadata can specifically be specified not to alias with some other
4053collection of memory access instructions that carry ``alias.scope`` metadata.
Hal Finkel029cde62014-07-25 15:50:02 +00004054Each type of metadata specifies a list of scopes where each scope has an id and
Ed Maste8ed40ce2015-04-14 20:52:58 +00004055a domain. When evaluating an aliasing query, if for some domain, the set
Hal Finkel029cde62014-07-25 15:50:02 +00004056of scopes with that domain in one instruction's ``alias.scope`` list is a
Arch D. Robison96cf7ab2015-02-24 20:11:49 +00004057subset of (or equal to) the set of scopes for that domain in another
Hal Finkel029cde62014-07-25 15:50:02 +00004058instruction's ``noalias`` list, then the two memory accesses are assumed not to
4059alias.
Hal Finkel94146652014-07-24 14:25:39 +00004060
Hal Finkel029cde62014-07-25 15:50:02 +00004061The metadata identifying each domain is itself a list containing one or two
4062entries. The first entry is the name of the domain. Note that if the name is a
Hal Finkel94146652014-07-24 14:25:39 +00004063string then it can be combined accross functions and translation units. A
Hal Finkel029cde62014-07-25 15:50:02 +00004064self-reference can be used to create globally unique domain names. A
4065descriptive string may optionally be provided as a second list entry.
4066
4067The metadata identifying each scope is also itself a list containing two or
4068three entries. The first entry is the name of the scope. Note that if the name
4069is a string then it can be combined accross functions and translation units. A
4070self-reference can be used to create globally unique scope names. A metadata
4071reference to the scope's domain is the second entry. A descriptive string may
4072optionally be provided as a third list entry.
Hal Finkel94146652014-07-24 14:25:39 +00004073
4074For example,
4075
4076.. code-block:: llvm
4077
Hal Finkel029cde62014-07-25 15:50:02 +00004078 ; Two scope domains:
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004079 !0 = !{!0}
4080 !1 = !{!1}
Hal Finkel94146652014-07-24 14:25:39 +00004081
Hal Finkel029cde62014-07-25 15:50:02 +00004082 ; Some scopes in these domains:
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004083 !2 = !{!2, !0}
4084 !3 = !{!3, !0}
4085 !4 = !{!4, !1}
Hal Finkel94146652014-07-24 14:25:39 +00004086
Hal Finkel029cde62014-07-25 15:50:02 +00004087 ; Some scope lists:
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004088 !5 = !{!4} ; A list containing only scope !4
4089 !6 = !{!4, !3, !2}
4090 !7 = !{!3}
Hal Finkel94146652014-07-24 14:25:39 +00004091
4092 ; These two instructions don't alias:
David Blaikiec7aabbb2015-03-04 22:06:14 +00004093 %0 = load float, float* %c, align 4, !alias.scope !5
Hal Finkel029cde62014-07-25 15:50:02 +00004094 store float %0, float* %arrayidx.i, align 4, !noalias !5
Hal Finkel94146652014-07-24 14:25:39 +00004095
Hal Finkel029cde62014-07-25 15:50:02 +00004096 ; These two instructions also don't alias (for domain !1, the set of scopes
4097 ; in the !alias.scope equals that in the !noalias list):
David Blaikiec7aabbb2015-03-04 22:06:14 +00004098 %2 = load float, float* %c, align 4, !alias.scope !5
Hal Finkel029cde62014-07-25 15:50:02 +00004099 store float %2, float* %arrayidx.i2, align 4, !noalias !6
Hal Finkel94146652014-07-24 14:25:39 +00004100
Adam Nemet0a8416f2015-05-11 08:30:28 +00004101 ; These two instructions may alias (for domain !0, the set of scopes in
Hal Finkel029cde62014-07-25 15:50:02 +00004102 ; the !noalias list is not a superset of, or equal to, the scopes in the
4103 ; !alias.scope list):
David Blaikiec7aabbb2015-03-04 22:06:14 +00004104 %2 = load float, float* %c, align 4, !alias.scope !6
Hal Finkel029cde62014-07-25 15:50:02 +00004105 store float %0, float* %arrayidx.i, align 4, !noalias !7
Hal Finkel94146652014-07-24 14:25:39 +00004106
Sean Silvab084af42012-12-07 10:36:55 +00004107'``fpmath``' Metadata
4108^^^^^^^^^^^^^^^^^^^^^
4109
4110``fpmath`` metadata may be attached to any instruction of floating point
4111type. It can be used to express the maximum acceptable error in the
4112result of that instruction, in ULPs, thus potentially allowing the
4113compiler to use a more efficient but less accurate method of computing
4114it. ULP is defined as follows:
4115
4116 If ``x`` is a real number that lies between two finite consecutive
4117 floating-point numbers ``a`` and ``b``, without being equal to one
4118 of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the
4119 distance between the two non-equal finite floating-point numbers
4120 nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``.
4121
4122The metadata node shall consist of a single positive floating point
4123number representing the maximum relative error, for example:
4124
4125.. code-block:: llvm
4126
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004127 !0 = !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
Sean Silvab084af42012-12-07 10:36:55 +00004128
Philip Reamesf8bf9dd2015-02-27 23:14:50 +00004129.. _range-metadata:
4130
Sean Silvab084af42012-12-07 10:36:55 +00004131'``range``' Metadata
4132^^^^^^^^^^^^^^^^^^^^
4133
Jingyue Wu37fcb592014-06-19 16:50:16 +00004134``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of
4135integer types. It expresses the possible ranges the loaded value or the value
4136returned by the called function at this call site is in. The ranges are
4137represented with a flattened list of integers. The loaded value or the value
4138returned is known to be in the union of the ranges defined by each consecutive
4139pair. Each pair has the following properties:
Sean Silvab084af42012-12-07 10:36:55 +00004140
4141- The type must match the type loaded by the instruction.
4142- The pair ``a,b`` represents the range ``[a,b)``.
4143- Both ``a`` and ``b`` are constants.
4144- The range is allowed to wrap.
4145- The range should not represent the full or empty set. That is,
4146 ``a!=b``.
4147
4148In addition, the pairs must be in signed order of the lower bound and
4149they must be non-contiguous.
4150
4151Examples:
4152
4153.. code-block:: llvm
4154
David Blaikiec7aabbb2015-03-04 22:06:14 +00004155 %a = load i8, i8* %x, align 1, !range !0 ; Can only be 0 or 1
4156 %b = load i8, i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
Jingyue Wu37fcb592014-06-19 16:50:16 +00004157 %c = call i8 @foo(), !range !2 ; Can only be 0, 1, 3, 4 or 5
4158 %d = invoke i8 @bar() to label %cont
4159 unwind label %lpad, !range !3 ; Can only be -2, -1, 3, 4 or 5
Sean Silvab084af42012-12-07 10:36:55 +00004160 ...
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004161 !0 = !{ i8 0, i8 2 }
4162 !1 = !{ i8 255, i8 2 }
4163 !2 = !{ i8 0, i8 2, i8 3, i8 6 }
4164 !3 = !{ i8 -2, i8 0, i8 3, i8 6 }
Sean Silvab084af42012-12-07 10:36:55 +00004165
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004166'``llvm.loop``'
4167^^^^^^^^^^^^^^^
4168
4169It is sometimes useful to attach information to loop constructs. Currently,
4170loop metadata is implemented as metadata attached to the branch instruction
4171in the loop latch block. This type of metadata refer to a metadata node that is
Matt Arsenault24b49c42013-07-31 17:49:08 +00004172guaranteed to be separate for each loop. The loop identifier metadata is
Paul Redmond5fdf8362013-05-28 20:00:34 +00004173specified with the name ``llvm.loop``.
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004174
4175The loop identifier metadata is implemented using a metadata that refers to
Michael Liaoa7699082013-03-06 18:24:34 +00004176itself to avoid merging it with any other identifier metadata, e.g.,
4177during module linkage or function inlining. That is, each loop should refer
4178to their own identification metadata even if they reside in separate functions.
4179The following example contains loop identifier metadata for two separate loop
Pekka Jaaskelainen119a2b62013-02-22 12:03:07 +00004180constructs:
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004181
4182.. code-block:: llvm
Paul Redmondeaaed3b2013-02-21 17:20:45 +00004183
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004184 !0 = !{!0}
4185 !1 = !{!1}
Pekka Jaaskelainen119a2b62013-02-22 12:03:07 +00004186
Mark Heffernan893752a2014-07-18 19:24:51 +00004187The loop identifier metadata can be used to specify additional
4188per-loop metadata. Any operands after the first operand can be treated
4189as user-defined metadata. For example the ``llvm.loop.unroll.count``
4190suggests an unroll factor to the loop unroller:
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004191
Paul Redmond5fdf8362013-05-28 20:00:34 +00004192.. code-block:: llvm
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004193
Paul Redmond5fdf8362013-05-28 20:00:34 +00004194 br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
4195 ...
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004196 !0 = !{!0, !1}
4197 !1 = !{!"llvm.loop.unroll.count", i32 4}
Mark Heffernan893752a2014-07-18 19:24:51 +00004198
Mark Heffernan9d20e422014-07-21 23:11:03 +00004199'``llvm.loop.vectorize``' and '``llvm.loop.interleave``'
4200^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Mark Heffernan893752a2014-07-18 19:24:51 +00004201
Mark Heffernan9d20e422014-07-21 23:11:03 +00004202Metadata prefixed with ``llvm.loop.vectorize`` or ``llvm.loop.interleave`` are
4203used to control per-loop vectorization and interleaving parameters such as
Sean Silvaa1190322015-08-06 22:56:48 +00004204vectorization width and interleave count. These metadata should be used in
4205conjunction with ``llvm.loop`` loop identification metadata. The
Mark Heffernan9d20e422014-07-21 23:11:03 +00004206``llvm.loop.vectorize`` and ``llvm.loop.interleave`` metadata are only
4207optimization hints and the optimizer will only interleave and vectorize loops if
Sean Silvaa1190322015-08-06 22:56:48 +00004208it believes it is safe to do so. The ``llvm.mem.parallel_loop_access`` metadata
Mark Heffernan9d20e422014-07-21 23:11:03 +00004209which contains information about loop-carried memory dependencies can be helpful
4210in determining the safety of these transformations.
Mark Heffernan893752a2014-07-18 19:24:51 +00004211
Mark Heffernan9d20e422014-07-21 23:11:03 +00004212'``llvm.loop.interleave.count``' Metadata
Mark Heffernan893752a2014-07-18 19:24:51 +00004213^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4214
Mark Heffernan9d20e422014-07-21 23:11:03 +00004215This metadata suggests an interleave count to the loop interleaver.
4216The first operand is the string ``llvm.loop.interleave.count`` and the
Mark Heffernan893752a2014-07-18 19:24:51 +00004217second operand is an integer specifying the interleave count. For
4218example:
4219
4220.. code-block:: llvm
4221
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004222 !0 = !{!"llvm.loop.interleave.count", i32 4}
Mark Heffernan893752a2014-07-18 19:24:51 +00004223
Mark Heffernan9d20e422014-07-21 23:11:03 +00004224Note that setting ``llvm.loop.interleave.count`` to 1 disables interleaving
Sean Silvaa1190322015-08-06 22:56:48 +00004225multiple iterations of the loop. If ``llvm.loop.interleave.count`` is set to 0
Mark Heffernan9d20e422014-07-21 23:11:03 +00004226then the interleave count will be determined automatically.
4227
4228'``llvm.loop.vectorize.enable``' Metadata
Dan Liew9a1829d2014-07-22 14:59:38 +00004229^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Mark Heffernan9d20e422014-07-21 23:11:03 +00004230
4231This metadata selectively enables or disables vectorization for the loop. The
4232first operand is the string ``llvm.loop.vectorize.enable`` and the second operand
Sean Silvaa1190322015-08-06 22:56:48 +00004233is a bit. If the bit operand value is 1 vectorization is enabled. A value of
Mark Heffernan9d20e422014-07-21 23:11:03 +000042340 disables vectorization:
4235
4236.. code-block:: llvm
4237
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004238 !0 = !{!"llvm.loop.vectorize.enable", i1 0}
4239 !1 = !{!"llvm.loop.vectorize.enable", i1 1}
Mark Heffernan893752a2014-07-18 19:24:51 +00004240
4241'``llvm.loop.vectorize.width``' Metadata
4242^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4243
4244This metadata sets the target width of the vectorizer. The first
4245operand is the string ``llvm.loop.vectorize.width`` and the second
4246operand is an integer specifying the width. For example:
4247
4248.. code-block:: llvm
4249
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004250 !0 = !{!"llvm.loop.vectorize.width", i32 4}
Mark Heffernan893752a2014-07-18 19:24:51 +00004251
4252Note that setting ``llvm.loop.vectorize.width`` to 1 disables
Sean Silvaa1190322015-08-06 22:56:48 +00004253vectorization of the loop. If ``llvm.loop.vectorize.width`` is set to
Mark Heffernan893752a2014-07-18 19:24:51 +000042540 or if the loop does not have this metadata the width will be
4255determined automatically.
4256
4257'``llvm.loop.unroll``'
4258^^^^^^^^^^^^^^^^^^^^^^
4259
4260Metadata prefixed with ``llvm.loop.unroll`` are loop unrolling
4261optimization hints such as the unroll factor. ``llvm.loop.unroll``
4262metadata should be used in conjunction with ``llvm.loop`` loop
4263identification metadata. The ``llvm.loop.unroll`` metadata are only
4264optimization hints and the unrolling will only be performed if the
4265optimizer believes it is safe to do so.
4266
Mark Heffernan893752a2014-07-18 19:24:51 +00004267'``llvm.loop.unroll.count``' Metadata
4268^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4269
4270This metadata suggests an unroll factor to the loop unroller. The
4271first operand is the string ``llvm.loop.unroll.count`` and the second
4272operand is a positive integer specifying the unroll factor. For
4273example:
4274
4275.. code-block:: llvm
4276
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004277 !0 = !{!"llvm.loop.unroll.count", i32 4}
Mark Heffernan893752a2014-07-18 19:24:51 +00004278
4279If the trip count of the loop is less than the unroll count the loop
4280will be partially unrolled.
4281
Mark Heffernane6b4ba12014-07-23 17:31:37 +00004282'``llvm.loop.unroll.disable``' Metadata
4283^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4284
Mark Heffernan3e32a4e2015-06-30 22:48:51 +00004285This metadata disables loop unrolling. The metadata has a single operand
Sean Silvaa1190322015-08-06 22:56:48 +00004286which is the string ``llvm.loop.unroll.disable``. For example:
Mark Heffernane6b4ba12014-07-23 17:31:37 +00004287
4288.. code-block:: llvm
4289
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004290 !0 = !{!"llvm.loop.unroll.disable"}
Mark Heffernane6b4ba12014-07-23 17:31:37 +00004291
Kevin Qin715b01e2015-03-09 06:14:18 +00004292'``llvm.loop.unroll.runtime.disable``' Metadata
Dan Liew868b0742015-03-11 13:34:49 +00004293^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Kevin Qin715b01e2015-03-09 06:14:18 +00004294
Mark Heffernan3e32a4e2015-06-30 22:48:51 +00004295This metadata disables runtime loop unrolling. The metadata has a single
Sean Silvaa1190322015-08-06 22:56:48 +00004296operand which is the string ``llvm.loop.unroll.runtime.disable``. For example:
Kevin Qin715b01e2015-03-09 06:14:18 +00004297
4298.. code-block:: llvm
4299
4300 !0 = !{!"llvm.loop.unroll.runtime.disable"}
4301
Mark Heffernan89391542015-08-10 17:28:08 +00004302'``llvm.loop.unroll.enable``' Metadata
4303^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4304
4305This metadata suggests that the loop should be fully unrolled if the trip count
4306is known at compile time and partially unrolled if the trip count is not known
4307at compile time. The metadata has a single operand which is the string
4308``llvm.loop.unroll.enable``. For example:
4309
4310.. code-block:: llvm
4311
4312 !0 = !{!"llvm.loop.unroll.enable"}
4313
Mark Heffernane6b4ba12014-07-23 17:31:37 +00004314'``llvm.loop.unroll.full``' Metadata
4315^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4316
Mark Heffernan3e32a4e2015-06-30 22:48:51 +00004317This metadata suggests that the loop should be unrolled fully. The
4318metadata has a single operand which is the string ``llvm.loop.unroll.full``.
Mark Heffernane6b4ba12014-07-23 17:31:37 +00004319For example:
4320
4321.. code-block:: llvm
4322
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004323 !0 = !{!"llvm.loop.unroll.full"}
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004324
4325'``llvm.mem``'
4326^^^^^^^^^^^^^^^
4327
4328Metadata types used to annotate memory accesses with information helpful
4329for optimizations are prefixed with ``llvm.mem``.
4330
4331'``llvm.mem.parallel_loop_access``' Metadata
4332^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4333
Mehdi Amini4a121fa2015-03-14 22:04:06 +00004334The ``llvm.mem.parallel_loop_access`` metadata refers to a loop identifier,
4335or metadata containing a list of loop identifiers for nested loops.
4336The metadata is attached to memory accessing instructions and denotes that
4337no loop carried memory dependence exist between it and other instructions denoted
Pekka Jaaskelainen23b222cc2014-05-23 11:35:46 +00004338with the same loop identifier.
4339
Mehdi Amini4a121fa2015-03-14 22:04:06 +00004340Precisely, given two instructions ``m1`` and ``m2`` that both have the
4341``llvm.mem.parallel_loop_access`` metadata, with ``L1`` and ``L2`` being the
4342set of loops associated with that metadata, respectively, then there is no loop
4343carried dependence between ``m1`` and ``m2`` for loops in both ``L1`` and
Pekka Jaaskelainen23b222cc2014-05-23 11:35:46 +00004344``L2``.
4345
Mehdi Amini4a121fa2015-03-14 22:04:06 +00004346As a special case, if all memory accessing instructions in a loop have
4347``llvm.mem.parallel_loop_access`` metadata that refers to that loop, then the
4348loop has no loop carried memory dependences and is considered to be a parallel
4349loop.
Pekka Jaaskelainen23b222cc2014-05-23 11:35:46 +00004350
Mehdi Amini4a121fa2015-03-14 22:04:06 +00004351Note that if not all memory access instructions have such metadata referring to
4352the loop, then the loop is considered not being trivially parallel. Additional
Sean Silvaa1190322015-08-06 22:56:48 +00004353memory dependence analysis is required to make that determination. As a fail
Mehdi Amini4a121fa2015-03-14 22:04:06 +00004354safe mechanism, this causes loops that were originally parallel to be considered
4355sequential (if optimization passes that are unaware of the parallel semantics
Pekka Jaaskelainen23b222cc2014-05-23 11:35:46 +00004356insert new memory instructions into the loop body).
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004357
4358Example of a loop that is considered parallel due to its correct use of
Paul Redmond5fdf8362013-05-28 20:00:34 +00004359both ``llvm.loop`` and ``llvm.mem.parallel_loop_access``
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004360metadata types that refer to the same loop identifier metadata.
4361
4362.. code-block:: llvm
4363
4364 for.body:
Paul Redmond5fdf8362013-05-28 20:00:34 +00004365 ...
David Blaikiec7aabbb2015-03-04 22:06:14 +00004366 %val0 = load i32, i32* %arrayidx, !llvm.mem.parallel_loop_access !0
Paul Redmond5fdf8362013-05-28 20:00:34 +00004367 ...
Tobias Grosserfbe95dc2014-03-05 13:36:04 +00004368 store i32 %val0, i32* %arrayidx1, !llvm.mem.parallel_loop_access !0
Paul Redmond5fdf8362013-05-28 20:00:34 +00004369 ...
4370 br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004371
4372 for.end:
4373 ...
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004374 !0 = !{!0}
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004375
4376It is also possible to have nested parallel loops. In that case the
4377memory accesses refer to a list of loop identifier metadata nodes instead of
4378the loop identifier metadata node directly:
4379
4380.. code-block:: llvm
4381
4382 outer.for.body:
Tobias Grosserfbe95dc2014-03-05 13:36:04 +00004383 ...
David Blaikiec7aabbb2015-03-04 22:06:14 +00004384 %val1 = load i32, i32* %arrayidx3, !llvm.mem.parallel_loop_access !2
Tobias Grosserfbe95dc2014-03-05 13:36:04 +00004385 ...
4386 br label %inner.for.body
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004387
4388 inner.for.body:
Paul Redmond5fdf8362013-05-28 20:00:34 +00004389 ...
David Blaikiec7aabbb2015-03-04 22:06:14 +00004390 %val0 = load i32, i32* %arrayidx1, !llvm.mem.parallel_loop_access !0
Paul Redmond5fdf8362013-05-28 20:00:34 +00004391 ...
Tobias Grosserfbe95dc2014-03-05 13:36:04 +00004392 store i32 %val0, i32* %arrayidx2, !llvm.mem.parallel_loop_access !0
Paul Redmond5fdf8362013-05-28 20:00:34 +00004393 ...
4394 br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004395
4396 inner.for.end:
Paul Redmond5fdf8362013-05-28 20:00:34 +00004397 ...
Tobias Grosserfbe95dc2014-03-05 13:36:04 +00004398 store i32 %val1, i32* %arrayidx4, !llvm.mem.parallel_loop_access !2
Paul Redmond5fdf8362013-05-28 20:00:34 +00004399 ...
4400 br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004401
4402 outer.for.end: ; preds = %for.body
4403 ...
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004404 !0 = !{!1, !2} ; a list of loop identifiers
4405 !1 = !{!1} ; an identifier for the inner loop
4406 !2 = !{!2} ; an identifier for the outer loop
Pekka Jaaskelainen0d237252013-02-13 18:08:57 +00004407
Peter Collingbournee6909c82015-02-20 20:30:47 +00004408'``llvm.bitsets``'
4409^^^^^^^^^^^^^^^^^^
4410
4411The ``llvm.bitsets`` global metadata is used to implement
4412:doc:`bitsets <BitSets>`.
4413
Sean Silvab084af42012-12-07 10:36:55 +00004414Module Flags Metadata
4415=====================
4416
4417Information about the module as a whole is difficult to convey to LLVM's
4418subsystems. The LLVM IR isn't sufficient to transmit this information.
4419The ``llvm.module.flags`` named metadata exists in order to facilitate
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00004420this. These flags are in the form of key / value pairs --- much like a
4421dictionary --- making it easy for any subsystem who cares about a flag to
Sean Silvab084af42012-12-07 10:36:55 +00004422look it up.
4423
4424The ``llvm.module.flags`` metadata contains a list of metadata triplets.
4425Each triplet has the following form:
4426
4427- The first element is a *behavior* flag, which specifies the behavior
4428 when two (or more) modules are merged together, and it encounters two
4429 (or more) metadata with the same ID. The supported behaviors are
4430 described below.
4431- The second element is a metadata string that is a unique ID for the
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004432 metadata. Each module may only have one flag entry for each unique ID (not
4433 including entries with the **Require** behavior).
Sean Silvab084af42012-12-07 10:36:55 +00004434- The third element is the value of the flag.
4435
4436When two (or more) modules are merged together, the resulting
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004437``llvm.module.flags`` metadata is the union of the modules' flags. That is, for
4438each unique metadata ID string, there will be exactly one entry in the merged
4439modules ``llvm.module.flags`` metadata table, and the value for that entry will
4440be determined by the merge behavior flag, as described below. The only exception
4441is that entries with the *Require* behavior are always preserved.
Sean Silvab084af42012-12-07 10:36:55 +00004442
4443The following behaviors are supported:
4444
4445.. list-table::
4446 :header-rows: 1
4447 :widths: 10 90
4448
4449 * - Value
4450 - Behavior
4451
4452 * - 1
4453 - **Error**
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004454 Emits an error if two values disagree, otherwise the resulting value
4455 is that of the operands.
Sean Silvab084af42012-12-07 10:36:55 +00004456
4457 * - 2
4458 - **Warning**
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004459 Emits a warning if two values disagree. The result value will be the
4460 operand for the flag from the first module being linked.
Sean Silvab084af42012-12-07 10:36:55 +00004461
4462 * - 3
4463 - **Require**
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004464 Adds a requirement that another module flag be present and have a
4465 specified value after linking is performed. The value must be a
4466 metadata pair, where the first element of the pair is the ID of the
4467 module flag to be restricted, and the second element of the pair is
4468 the value the module flag should be restricted to. This behavior can
4469 be used to restrict the allowable results (via triggering of an
4470 error) of linking IDs with the **Override** behavior.
Sean Silvab084af42012-12-07 10:36:55 +00004471
4472 * - 4
4473 - **Override**
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004474 Uses the specified value, regardless of the behavior or value of the
4475 other module. If both modules specify **Override**, but the values
4476 differ, an error will be emitted.
4477
Daniel Dunbard77d9fb2013-01-16 21:38:56 +00004478 * - 5
4479 - **Append**
4480 Appends the two values, which are required to be metadata nodes.
4481
4482 * - 6
4483 - **AppendUnique**
4484 Appends the two values, which are required to be metadata
4485 nodes. However, duplicate entries in the second list are dropped
4486 during the append operation.
4487
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004488It is an error for a particular unique flag ID to have multiple behaviors,
4489except in the case of **Require** (which adds restrictions on another metadata
4490value) or **Override**.
Sean Silvab084af42012-12-07 10:36:55 +00004491
4492An example of module flags:
4493
4494.. code-block:: llvm
4495
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004496 !0 = !{ i32 1, !"foo", i32 1 }
4497 !1 = !{ i32 4, !"bar", i32 37 }
4498 !2 = !{ i32 2, !"qux", i32 42 }
4499 !3 = !{ i32 3, !"qux",
4500 !{
4501 !"foo", i32 1
Sean Silvab084af42012-12-07 10:36:55 +00004502 }
4503 }
4504 !llvm.module.flags = !{ !0, !1, !2, !3 }
4505
4506- Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior
4507 if two or more ``!"foo"`` flags are seen is to emit an error if their
4508 values are not equal.
4509
4510- Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The
4511 behavior if two or more ``!"bar"`` flags are seen is to use the value
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004512 '37'.
Sean Silvab084af42012-12-07 10:36:55 +00004513
4514- Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The
4515 behavior if two or more ``!"qux"`` flags are seen is to emit a
4516 warning if their values are not equal.
4517
4518- Metadata ``!3`` has the ID ``!"qux"`` and the value:
4519
4520 ::
4521
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004522 !{ !"foo", i32 1 }
Sean Silvab084af42012-12-07 10:36:55 +00004523
Daniel Dunbar25c4b572013-01-15 01:22:53 +00004524 The behavior is to emit an error if the ``llvm.module.flags`` does not
4525 contain a flag with the ID ``!"foo"`` that has the value '1' after linking is
4526 performed.
Sean Silvab084af42012-12-07 10:36:55 +00004527
4528Objective-C Garbage Collection Module Flags Metadata
4529----------------------------------------------------
4530
4531On the Mach-O platform, Objective-C stores metadata about garbage
4532collection in a special section called "image info". The metadata
4533consists of a version number and a bitmask specifying what types of
4534garbage collection are supported (if any) by the file. If two or more
4535modules are linked together their garbage collection metadata needs to
4536be merged rather than appended together.
4537
4538The Objective-C garbage collection module flags metadata consists of the
4539following key-value pairs:
4540
4541.. list-table::
4542 :header-rows: 1
4543 :widths: 30 70
4544
4545 * - Key
4546 - Value
4547
Daniel Dunbar1dc66ca2013-01-17 18:57:32 +00004548 * - ``Objective-C Version``
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00004549 - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2.
Sean Silvab084af42012-12-07 10:36:55 +00004550
Daniel Dunbar1dc66ca2013-01-17 18:57:32 +00004551 * - ``Objective-C Image Info Version``
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00004552 - **[Required]** --- The version of the image info section. Currently
Sean Silvab084af42012-12-07 10:36:55 +00004553 always 0.
4554
Daniel Dunbar1dc66ca2013-01-17 18:57:32 +00004555 * - ``Objective-C Image Info Section``
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00004556 - **[Required]** --- The section to place the metadata. Valid values are
Sean Silvab084af42012-12-07 10:36:55 +00004557 ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and
4558 ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for
4559 Objective-C ABI version 2.
4560
Daniel Dunbar1dc66ca2013-01-17 18:57:32 +00004561 * - ``Objective-C Garbage Collection``
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00004562 - **[Required]** --- Specifies whether garbage collection is supported or
Sean Silvab084af42012-12-07 10:36:55 +00004563 not. Valid values are 0, for no garbage collection, and 2, for garbage
4564 collection supported.
4565
Daniel Dunbar1dc66ca2013-01-17 18:57:32 +00004566 * - ``Objective-C GC Only``
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00004567 - **[Optional]** --- Specifies that only garbage collection is supported.
Sean Silvab084af42012-12-07 10:36:55 +00004568 If present, its value must be 6. This flag requires that the
4569 ``Objective-C Garbage Collection`` flag have the value 2.
4570
4571Some important flag interactions:
4572
4573- If a module with ``Objective-C Garbage Collection`` set to 0 is
4574 merged with a module with ``Objective-C Garbage Collection`` set to
4575 2, then the resulting module has the
4576 ``Objective-C Garbage Collection`` flag set to 0.
4577- A module with ``Objective-C Garbage Collection`` set to 0 cannot be
4578 merged with a module with ``Objective-C GC Only`` set to 6.
4579
Daniel Dunbar252bedc2013-01-17 00:16:27 +00004580Automatic Linker Flags Module Flags Metadata
4581--------------------------------------------
4582
4583Some targets support embedding flags to the linker inside individual object
4584files. Typically this is used in conjunction with language extensions which
4585allow source files to explicitly declare the libraries they depend on, and have
4586these automatically be transmitted to the linker via object files.
4587
4588These flags are encoded in the IR using metadata in the module flags section,
Daniel Dunbar1dc66ca2013-01-17 18:57:32 +00004589using the ``Linker Options`` key. The merge behavior for this flag is required
Daniel Dunbar252bedc2013-01-17 00:16:27 +00004590to be ``AppendUnique``, and the value for the key is expected to be a metadata
4591node which should be a list of other metadata nodes, each of which should be a
4592list of metadata strings defining linker options.
4593
4594For example, the following metadata section specifies two separate sets of
4595linker options, presumably to link against ``libz`` and the ``Cocoa``
4596framework::
4597
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004598 !0 = !{ i32 6, !"Linker Options",
4599 !{
4600 !{ !"-lz" },
4601 !{ !"-framework", !"Cocoa" } } }
Daniel Dunbar252bedc2013-01-17 00:16:27 +00004602 !llvm.module.flags = !{ !0 }
4603
4604The metadata encoding as lists of lists of options, as opposed to a collapsed
4605list of options, is chosen so that the IR encoding can use multiple option
4606strings to specify e.g., a single library, while still having that specifier be
4607preserved as an atomic element that can be recognized by a target specific
4608assembly writer or object file emitter.
4609
4610Each individual option is required to be either a valid option for the target's
4611linker, or an option that is reserved by the target specific assembly writer or
4612object file emitter. No other aspect of these options is defined by the IR.
4613
Oliver Stannard5dc29342014-06-20 10:08:11 +00004614C type width Module Flags Metadata
4615----------------------------------
4616
4617The ARM backend emits a section into each generated object file describing the
4618options that it was compiled with (in a compiler-independent way) to prevent
4619linking incompatible objects, and to allow automatic library selection. Some
4620of these options are not visible at the IR level, namely wchar_t width and enum
4621width.
4622
4623To pass this information to the backend, these options are encoded in module
4624flags metadata, using the following key-value pairs:
4625
4626.. list-table::
4627 :header-rows: 1
4628 :widths: 30 70
4629
4630 * - Key
4631 - Value
4632
4633 * - short_wchar
4634 - * 0 --- sizeof(wchar_t) == 4
4635 * 1 --- sizeof(wchar_t) == 2
4636
4637 * - short_enum
4638 - * 0 --- Enums are at least as large as an ``int``.
4639 * 1 --- Enums are stored in the smallest integer type which can
4640 represent all of its values.
4641
4642For example, the following metadata section specifies that the module was
4643compiled with a ``wchar_t`` width of 4 bytes, and the underlying type of an
4644enum is the smallest type which can represent all of its values::
4645
4646 !llvm.module.flags = !{!0, !1}
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00004647 !0 = !{i32 1, !"short_wchar", i32 1}
4648 !1 = !{i32 1, !"short_enum", i32 0}
Oliver Stannard5dc29342014-06-20 10:08:11 +00004649
Eli Bendersky0220e6b2013-06-07 20:24:43 +00004650.. _intrinsicglobalvariables:
4651
Sean Silvab084af42012-12-07 10:36:55 +00004652Intrinsic Global Variables
4653==========================
4654
4655LLVM has a number of "magic" global variables that contain data that
4656affect code generation or other IR semantics. These are documented here.
4657All globals of this sort should have a section specified as
4658"``llvm.metadata``". This section and all globals that start with
4659"``llvm.``" are reserved for use by LLVM.
4660
Eli Bendersky0220e6b2013-06-07 20:24:43 +00004661.. _gv_llvmused:
4662
Sean Silvab084af42012-12-07 10:36:55 +00004663The '``llvm.used``' Global Variable
4664-----------------------------------
4665
Rafael Espindola74f2e462013-04-22 14:58:02 +00004666The ``@llvm.used`` global is an array which has
Paul Redmond219ef812013-05-30 17:24:32 +00004667:ref:`appending linkage <linkage_appending>`. This array contains a list of
Rafael Espindola70a729d2013-06-11 13:18:13 +00004668pointers to named global variables, functions and aliases which may optionally
4669have a pointer cast formed of bitcast or getelementptr. For example, a legal
Sean Silvab084af42012-12-07 10:36:55 +00004670use of it is:
4671
4672.. code-block:: llvm
4673
4674 @X = global i8 4
4675 @Y = global i32 123
4676
4677 @llvm.used = appending global [2 x i8*] [
4678 i8* @X,
4679 i8* bitcast (i32* @Y to i8*)
4680 ], section "llvm.metadata"
4681
Rafael Espindola74f2e462013-04-22 14:58:02 +00004682If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler,
4683and linker are required to treat the symbol as if there is a reference to the
Rafael Espindola70a729d2013-06-11 13:18:13 +00004684symbol that it cannot see (which is why they have to be named). For example, if
4685a variable has internal linkage and no references other than that from the
4686``@llvm.used`` list, it cannot be deleted. This is commonly used to represent
4687references from inline asms and other things the compiler cannot "see", and
4688corresponds to "``attribute((used))``" in GNU C.
Sean Silvab084af42012-12-07 10:36:55 +00004689
4690On some targets, the code generator must emit a directive to the
4691assembler or object file to prevent the assembler and linker from
4692molesting the symbol.
4693
Eli Bendersky0220e6b2013-06-07 20:24:43 +00004694.. _gv_llvmcompilerused:
4695
Sean Silvab084af42012-12-07 10:36:55 +00004696The '``llvm.compiler.used``' Global Variable
4697--------------------------------------------
4698
4699The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used``
4700directive, except that it only prevents the compiler from touching the
4701symbol. On targets that support it, this allows an intelligent linker to
4702optimize references to the symbol without being impeded as it would be
4703by ``@llvm.used``.
4704
4705This is a rare construct that should only be used in rare circumstances,
4706and should not be exposed to source languages.
4707
Eli Bendersky0220e6b2013-06-07 20:24:43 +00004708.. _gv_llvmglobalctors:
4709
Sean Silvab084af42012-12-07 10:36:55 +00004710The '``llvm.global_ctors``' Global Variable
4711-------------------------------------------
4712
4713.. code-block:: llvm
4714
Reid Klecknerfceb76f2014-05-16 20:39:27 +00004715 %0 = type { i32, void ()*, i8* }
4716 @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor, i8* @data }]
Sean Silvab084af42012-12-07 10:36:55 +00004717
4718The ``@llvm.global_ctors`` array contains a list of constructor
Reid Klecknerfceb76f2014-05-16 20:39:27 +00004719functions, priorities, and an optional associated global or function.
4720The functions referenced by this array will be called in ascending order
4721of priority (i.e. lowest first) when the module is loaded. The order of
4722functions with the same priority is not defined.
4723
4724If the third field is present, non-null, and points to a global variable
4725or function, the initializer function will only run if the associated
4726data from the current module is not discarded.
Sean Silvab084af42012-12-07 10:36:55 +00004727
Eli Bendersky0220e6b2013-06-07 20:24:43 +00004728.. _llvmglobaldtors:
4729
Sean Silvab084af42012-12-07 10:36:55 +00004730The '``llvm.global_dtors``' Global Variable
4731-------------------------------------------
4732
4733.. code-block:: llvm
4734
Reid Klecknerfceb76f2014-05-16 20:39:27 +00004735 %0 = type { i32, void ()*, i8* }
4736 @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor, i8* @data }]
Sean Silvab084af42012-12-07 10:36:55 +00004737
Reid Klecknerfceb76f2014-05-16 20:39:27 +00004738The ``@llvm.global_dtors`` array contains a list of destructor
4739functions, priorities, and an optional associated global or function.
4740The functions referenced by this array will be called in descending
Reid Klecknerbffbcc52014-05-27 21:35:17 +00004741order of priority (i.e. highest first) when the module is unloaded. The
Reid Klecknerfceb76f2014-05-16 20:39:27 +00004742order of functions with the same priority is not defined.
4743
4744If the third field is present, non-null, and points to a global variable
4745or function, the destructor function will only run if the associated
4746data from the current module is not discarded.
Sean Silvab084af42012-12-07 10:36:55 +00004747
4748Instruction Reference
4749=====================
4750
4751The LLVM instruction set consists of several different classifications
4752of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
4753instructions <binaryops>`, :ref:`bitwise binary
4754instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and
4755:ref:`other instructions <otherops>`.
4756
4757.. _terminators:
4758
4759Terminator Instructions
4760-----------------------
4761
4762As mentioned :ref:`previously <functionstructure>`, every basic block in a
4763program ends with a "Terminator" instruction, which indicates which
4764block should be executed after the current block is finished. These
4765terminator instructions typically yield a '``void``' value: they produce
4766control flow, not values (the one exception being the
4767':ref:`invoke <i_invoke>`' instruction).
4768
4769The terminator instructions are: ':ref:`ret <i_ret>`',
4770':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
4771':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
David Majnemer654e1302015-07-31 17:58:14 +00004772':ref:`resume <i_resume>`', ':ref:`catchpad <i_catchpad>`',
4773':ref:`catchendpad <i_catchendpad>`',
4774':ref:`catchret <i_catchret>`',
4775':ref:`cleanupret <i_cleanupret>`',
4776':ref:`terminatepad <i_terminatepad>`',
4777and ':ref:`unreachable <i_unreachable>`'.
Sean Silvab084af42012-12-07 10:36:55 +00004778
4779.. _i_ret:
4780
4781'``ret``' Instruction
4782^^^^^^^^^^^^^^^^^^^^^
4783
4784Syntax:
4785"""""""
4786
4787::
4788
4789 ret <type> <value> ; Return a value from a non-void function
4790 ret void ; Return from void function
4791
4792Overview:
4793"""""""""
4794
4795The '``ret``' instruction is used to return control flow (and optionally
4796a value) from a function back to the caller.
4797
4798There are two forms of the '``ret``' instruction: one that returns a
4799value and then causes control flow, and one that just causes control
4800flow to occur.
4801
4802Arguments:
4803""""""""""
4804
4805The '``ret``' instruction optionally accepts a single argument, the
4806return value. The type of the return value must be a ':ref:`first
4807class <t_firstclass>`' type.
4808
4809A function is not :ref:`well formed <wellformed>` if it it has a non-void
4810return type and contains a '``ret``' instruction with no return value or
4811a return value with a type that does not match its type, or if it has a
4812void return type and contains a '``ret``' instruction with a return
4813value.
4814
4815Semantics:
4816""""""""""
4817
4818When the '``ret``' instruction is executed, control flow returns back to
4819the calling function's context. If the caller is a
4820":ref:`call <i_call>`" instruction, execution continues at the
4821instruction after the call. If the caller was an
4822":ref:`invoke <i_invoke>`" instruction, execution continues at the
4823beginning of the "normal" destination block. If the instruction returns
4824a value, that value shall set the call or invoke instruction's return
4825value.
4826
4827Example:
4828""""""""
4829
4830.. code-block:: llvm
4831
4832 ret i32 5 ; Return an integer value of 5
4833 ret void ; Return from a void function
4834 ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2
4835
4836.. _i_br:
4837
4838'``br``' Instruction
4839^^^^^^^^^^^^^^^^^^^^
4840
4841Syntax:
4842"""""""
4843
4844::
4845
4846 br i1 <cond>, label <iftrue>, label <iffalse>
4847 br label <dest> ; Unconditional branch
4848
4849Overview:
4850"""""""""
4851
4852The '``br``' instruction is used to cause control flow to transfer to a
4853different basic block in the current function. There are two forms of
4854this instruction, corresponding to a conditional branch and an
4855unconditional branch.
4856
4857Arguments:
4858""""""""""
4859
4860The conditional branch form of the '``br``' instruction takes a single
4861'``i1``' value and two '``label``' values. The unconditional form of the
4862'``br``' instruction takes a single '``label``' value as a target.
4863
4864Semantics:
4865""""""""""
4866
4867Upon execution of a conditional '``br``' instruction, the '``i1``'
4868argument is evaluated. If the value is ``true``, control flows to the
4869'``iftrue``' ``label`` argument. If "cond" is ``false``, control flows
4870to the '``iffalse``' ``label`` argument.
4871
4872Example:
4873""""""""
4874
4875.. code-block:: llvm
4876
4877 Test:
4878 %cond = icmp eq i32 %a, %b
4879 br i1 %cond, label %IfEqual, label %IfUnequal
4880 IfEqual:
4881 ret i32 1
4882 IfUnequal:
4883 ret i32 0
4884
4885.. _i_switch:
4886
4887'``switch``' Instruction
4888^^^^^^^^^^^^^^^^^^^^^^^^
4889
4890Syntax:
4891"""""""
4892
4893::
4894
4895 switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
4896
4897Overview:
4898"""""""""
4899
4900The '``switch``' instruction is used to transfer control flow to one of
4901several different places. It is a generalization of the '``br``'
4902instruction, allowing a branch to occur to one of many possible
4903destinations.
4904
4905Arguments:
4906""""""""""
4907
4908The '``switch``' instruction uses three parameters: an integer
4909comparison value '``value``', a default '``label``' destination, and an
4910array of pairs of comparison value constants and '``label``'s. The table
4911is not allowed to contain duplicate constant entries.
4912
4913Semantics:
4914""""""""""
4915
4916The ``switch`` instruction specifies a table of values and destinations.
4917When the '``switch``' instruction is executed, this table is searched
4918for the given value. If the value is found, control flow is transferred
4919to the corresponding destination; otherwise, control flow is transferred
4920to the default destination.
4921
4922Implementation:
4923"""""""""""""""
4924
4925Depending on properties of the target machine and the particular
4926``switch`` instruction, this instruction may be code generated in
4927different ways. For example, it could be generated as a series of
4928chained conditional branches or with a lookup table.
4929
4930Example:
4931""""""""
4932
4933.. code-block:: llvm
4934
4935 ; Emulate a conditional br instruction
4936 %Val = zext i1 %value to i32
4937 switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
4938
4939 ; Emulate an unconditional br instruction
4940 switch i32 0, label %dest [ ]
4941
4942 ; Implement a jump table:
4943 switch i32 %val, label %otherwise [ i32 0, label %onzero
4944 i32 1, label %onone
4945 i32 2, label %ontwo ]
4946
4947.. _i_indirectbr:
4948
4949'``indirectbr``' Instruction
4950^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4951
4952Syntax:
4953"""""""
4954
4955::
4956
4957 indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
4958
4959Overview:
4960"""""""""
4961
4962The '``indirectbr``' instruction implements an indirect branch to a
4963label within the current function, whose address is specified by
4964"``address``". Address must be derived from a
4965:ref:`blockaddress <blockaddress>` constant.
4966
4967Arguments:
4968""""""""""
4969
4970The '``address``' argument is the address of the label to jump to. The
4971rest of the arguments indicate the full set of possible destinations
4972that the address may point to. Blocks are allowed to occur multiple
4973times in the destination list, though this isn't particularly useful.
4974
4975This destination list is required so that dataflow analysis has an
4976accurate understanding of the CFG.
4977
4978Semantics:
4979""""""""""
4980
4981Control transfers to the block specified in the address argument. All
4982possible destination blocks must be listed in the label list, otherwise
4983this instruction has undefined behavior. This implies that jumps to
4984labels defined in other functions have undefined behavior as well.
4985
4986Implementation:
4987"""""""""""""""
4988
4989This is typically implemented with a jump through a register.
4990
4991Example:
4992""""""""
4993
4994.. code-block:: llvm
4995
4996 indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
4997
4998.. _i_invoke:
4999
5000'``invoke``' Instruction
5001^^^^^^^^^^^^^^^^^^^^^^^^
5002
5003Syntax:
5004"""""""
5005
5006::
5007
5008 <result> = invoke [cconv] [ret attrs] <ptr to function ty> <function ptr val>(<function args>) [fn attrs]
5009 to label <normal label> unwind label <exception label>
5010
5011Overview:
5012"""""""""
5013
5014The '``invoke``' instruction causes control to transfer to a specified
5015function, with the possibility of control flow transfer to either the
5016'``normal``' label or the '``exception``' label. If the callee function
5017returns with the "``ret``" instruction, control flow will return to the
5018"normal" label. If the callee (or any indirect callees) returns via the
5019":ref:`resume <i_resume>`" instruction or other exception handling
5020mechanism, control is interrupted and continued at the dynamically
5021nearest "exception" label.
5022
5023The '``exception``' label is a `landing
5024pad <ExceptionHandling.html#overview>`_ for the exception. As such,
5025'``exception``' label is required to have the
5026":ref:`landingpad <i_landingpad>`" instruction, which contains the
5027information about the behavior of the program after unwinding happens,
5028as its first non-PHI instruction. The restrictions on the
5029"``landingpad``" instruction's tightly couples it to the "``invoke``"
5030instruction, so that the important information contained within the
5031"``landingpad``" instruction can't be lost through normal code motion.
5032
5033Arguments:
5034""""""""""
5035
5036This instruction requires several arguments:
5037
5038#. The optional "cconv" marker indicates which :ref:`calling
5039 convention <callingconv>` the call should use. If none is
5040 specified, the call defaults to using C calling conventions.
5041#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
5042 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
5043 are valid here.
5044#. '``ptr to function ty``': shall be the signature of the pointer to
5045 function value being invoked. In most cases, this is a direct
5046 function invocation, but indirect ``invoke``'s are just as possible,
5047 branching off an arbitrary pointer to function value.
5048#. '``function ptr val``': An LLVM value containing a pointer to a
5049 function to be invoked.
5050#. '``function args``': argument list whose types match the function
5051 signature argument types and parameter attributes. All arguments must
5052 be of :ref:`first class <t_firstclass>` type. If the function signature
5053 indicates the function accepts a variable number of arguments, the
5054 extra arguments can be specified.
5055#. '``normal label``': the label reached when the called function
5056 executes a '``ret``' instruction.
5057#. '``exception label``': the label reached when a callee returns via
5058 the :ref:`resume <i_resume>` instruction or other exception handling
5059 mechanism.
5060#. The optional :ref:`function attributes <fnattrs>` list. Only
5061 '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
5062 attributes are valid here.
5063
5064Semantics:
5065""""""""""
5066
5067This instruction is designed to operate as a standard '``call``'
5068instruction in most regards. The primary difference is that it
5069establishes an association with a label, which is used by the runtime
5070library to unwind the stack.
5071
5072This instruction is used in languages with destructors to ensure that
5073proper cleanup is performed in the case of either a ``longjmp`` or a
5074thrown exception. Additionally, this is important for implementation of
5075'``catch``' clauses in high-level languages that support them.
5076
5077For the purposes of the SSA form, the definition of the value returned
5078by the '``invoke``' instruction is deemed to occur on the edge from the
5079current block to the "normal" label. If the callee unwinds then no
5080return value is available.
5081
5082Example:
5083""""""""
5084
5085.. code-block:: llvm
5086
5087 %retval = invoke i32 @Test(i32 15) to label %Continue
Tim Northover675a0962014-06-13 14:24:23 +00005088 unwind label %TestCleanup ; i32:retval set
Sean Silvab084af42012-12-07 10:36:55 +00005089 %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
Tim Northover675a0962014-06-13 14:24:23 +00005090 unwind label %TestCleanup ; i32:retval set
Sean Silvab084af42012-12-07 10:36:55 +00005091
5092.. _i_resume:
5093
5094'``resume``' Instruction
5095^^^^^^^^^^^^^^^^^^^^^^^^
5096
5097Syntax:
5098"""""""
5099
5100::
5101
5102 resume <type> <value>
5103
5104Overview:
5105"""""""""
5106
5107The '``resume``' instruction is a terminator instruction that has no
5108successors.
5109
5110Arguments:
5111""""""""""
5112
5113The '``resume``' instruction requires one argument, which must have the
5114same type as the result of any '``landingpad``' instruction in the same
5115function.
5116
5117Semantics:
5118""""""""""
5119
5120The '``resume``' instruction resumes propagation of an existing
5121(in-flight) exception whose unwinding was interrupted with a
5122:ref:`landingpad <i_landingpad>` instruction.
5123
5124Example:
5125""""""""
5126
5127.. code-block:: llvm
5128
5129 resume { i8*, i32 } %exn
5130
David Majnemer654e1302015-07-31 17:58:14 +00005131.. _i_catchpad:
5132
5133'``catchpad``' Instruction
5134^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5135
5136Syntax:
5137"""""""
5138
5139::
5140
5141 <resultval> = catchpad <resultty> [<args>*]
5142 to label <normal label> unwind label <exception label>
5143
5144Overview:
5145"""""""""
5146
5147The '``catchpad``' instruction is used by `LLVM's exception handling
5148system <ExceptionHandling.html#overview>`_ to specify that a basic block
5149is a catch block --- one where a personality routine attempts to transfer
5150control to catch an exception.
5151The ``args`` correspond to whatever information the personality
5152routine requires to know if this is an appropriate place to catch the
Sean Silvaa1190322015-08-06 22:56:48 +00005153exception. Control is tranfered to the ``exception`` label if the
David Majnemer654e1302015-07-31 17:58:14 +00005154``catchpad`` is not an appropriate handler for the in-flight exception.
5155The ``normal`` label should contain the code found in the ``catch``
5156portion of a ``try``/``catch`` sequence. It defines values supplied by
5157the :ref:`personality function <personalityfn>` upon re-entry to the
5158function. The ``resultval`` has the type ``resultty``.
5159
5160Arguments:
5161""""""""""
5162
5163The instruction takes a list of arbitrary values which are interpreted
5164by the :ref:`personality function <personalityfn>`.
5165
5166The ``catchpad`` must be provided a ``normal`` label to transfer control
5167to if the ``catchpad`` matches the exception and an ``exception``
5168label to transfer control to if it doesn't.
5169
5170Semantics:
5171""""""""""
5172
5173The '``catchpad``' instruction defines the values which are set by the
5174:ref:`personality function <personalityfn>` upon re-entry to the function, and
5175therefore the "result type" of the ``catchpad`` instruction. As with
5176calling conventions, how the personality function results are
5177represented in LLVM IR is target specific.
5178
5179When the call stack is being unwound due to an exception being thrown,
5180the exception is compared against the ``args``. If it doesn't match,
5181then control is transfered to the ``exception`` basic block.
5182
5183The ``catchpad`` instruction has several restrictions:
5184
5185- A catch block is a basic block which is the unwind destination of
5186 an exceptional instruction.
5187- A catch block must have a '``catchpad``' instruction as its
5188 first non-PHI instruction.
5189- A catch block's ``exception`` edge must refer to a catch block or a
5190 catch-end block.
5191- There can be only one '``catchpad``' instruction within the
5192 catch block.
5193- A basic block that is not a catch block may not include a
5194 '``catchpad``' instruction.
5195- It is undefined behavior for control to transfer from a ``catchpad`` to a
5196 ``cleanupret`` without first executing a ``catchret`` and a subsequent
5197 ``cleanuppad``.
5198- It is undefined behavior for control to transfer from a ``catchpad`` to a
5199 ``ret`` without first executing a ``catchret``.
5200
5201Example:
5202""""""""
5203
5204.. code-block:: llvm
5205
5206 ;; A catch block which can catch an integer.
5207 %res = catchpad { i8*, i32 } [i8** @_ZTIi]
5208 to label %int.handler unwind label %terminate
5209
5210.. _i_catchendpad:
5211
5212'``catchendpad``' Instruction
5213^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5214
5215Syntax:
5216"""""""
5217
5218::
5219
5220 catchendpad unwind label <nextaction>
5221 catchendpad unwind to caller
5222
5223Overview:
5224"""""""""
5225
5226The '``catchendpad``' instruction is used by `LLVM's exception handling
5227system <ExceptionHandling.html#overview>`_ to communicate to the
5228:ref:`personality function <personalityfn>` which invokes are associated
5229with a chain of :ref:`catchpad <i_catchpad>` instructions.
5230
5231The ``nextaction`` label indicates where control should transfer to if
5232none of the ``catchpad`` instructions are suitable for catching the
5233in-flight exception.
5234
5235If a ``nextaction`` label is not present, the instruction unwinds out of
Sean Silvaa1190322015-08-06 22:56:48 +00005236its parent function. The
David Majnemer654e1302015-07-31 17:58:14 +00005237:ref:`personality function <personalityfn>` will continue processing
5238exception handling actions in the caller.
5239
5240Arguments:
5241""""""""""
5242
5243The instruction optionally takes a label, ``nextaction``, indicating
5244where control should transfer to if none of the preceding
5245``catchpad`` instructions are suitable for the in-flight exception.
5246
5247Semantics:
5248""""""""""
5249
5250When the call stack is being unwound due to an exception being thrown
5251and none of the constituent ``catchpad`` instructions match, then
Sean Silvaa1190322015-08-06 22:56:48 +00005252control is transfered to ``nextaction`` if it is present. If it is not
David Majnemer654e1302015-07-31 17:58:14 +00005253present, control is transfered to the caller.
5254
5255The ``catchendpad`` instruction has several restrictions:
5256
5257- A catch-end block is a basic block which is the unwind destination of
5258 an exceptional instruction.
5259- A catch-end block must have a '``catchendpad``' instruction as its
5260 first non-PHI instruction.
5261- There can be only one '``catchendpad``' instruction within the
5262 catch block.
5263- A basic block that is not a catch-end block may not include a
5264 '``catchendpad``' instruction.
5265- Exactly one catch block may unwind to a ``catchendpad``.
5266- The unwind target of invokes between a ``catchpad`` and a
5267 corresponding ``catchret`` must be its ``catchendpad``.
5268
5269Example:
5270""""""""
5271
5272.. code-block:: llvm
5273
5274 catchendpad unwind label %terminate
5275 catchendpad unwind to caller
5276
5277.. _i_catchret:
5278
5279'``catchret``' Instruction
5280^^^^^^^^^^^^^^^^^^^^^^^^^^
5281
5282Syntax:
5283"""""""
5284
5285::
5286
5287 catchret label <normal>
5288
5289Overview:
5290"""""""""
5291
5292The '``catchret``' instruction is a terminator instruction that has a
5293single successor.
5294
5295
5296Arguments:
5297""""""""""
5298
5299The '``catchret``' instruction requires one argument which specifies
5300where control will transfer to next.
5301
5302Semantics:
5303""""""""""
5304
5305The '``catchret``' instruction ends the existing (in-flight) exception
5306whose unwinding was interrupted with a
5307:ref:`catchpad <i_catchpad>` instruction.
5308The :ref:`personality function <personalityfn>` gets a chance to execute
5309arbitrary code to, for example, run a C++ destructor.
5310Control then transfers to ``normal``.
5311
5312Example:
5313""""""""
5314
5315.. code-block:: llvm
5316
5317 catchret label %continue
5318
5319.. _i_cleanupret:
5320
5321'``cleanupret``' Instruction
5322^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5323
5324Syntax:
5325"""""""
5326
5327::
5328
5329 cleanupret <type> <value> unwind label <continue>
5330 cleanupret <type> <value> unwind to caller
5331
5332Overview:
5333"""""""""
5334
5335The '``cleanupret``' instruction is a terminator instruction that has
5336an optional successor.
5337
5338
5339Arguments:
5340""""""""""
5341
5342The '``cleanupret``' instruction requires one argument, which must have the
5343same type as the result of any '``cleanuppad``' instruction in the same
Sean Silvaa1190322015-08-06 22:56:48 +00005344function. It also has an optional successor, ``continue``.
David Majnemer654e1302015-07-31 17:58:14 +00005345
5346Semantics:
5347""""""""""
5348
5349The '``cleanupret``' instruction indicates to the
5350:ref:`personality function <personalityfn>` that one
5351:ref:`cleanuppad <i_cleanuppad>` it transferred control to has ended.
5352It transfers control to ``continue`` or unwinds out of the function.
5353
5354Example:
5355""""""""
5356
5357.. code-block:: llvm
5358
5359 cleanupret void unwind to caller
5360 cleanupret { i8*, i32 } %exn unwind label %continue
5361
5362.. _i_terminatepad:
5363
5364'``terminatepad``' Instruction
5365^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5366
5367Syntax:
5368"""""""
5369
5370::
5371
5372 terminatepad [<args>*] unwind label <exception label>
5373 terminatepad [<args>*] unwind to caller
5374
5375Overview:
5376"""""""""
5377
5378The '``terminatepad``' instruction is used by `LLVM's exception handling
5379system <ExceptionHandling.html#overview>`_ to specify that a basic block
5380is a terminate block --- one where a personality routine may decide to
5381terminate the program.
5382The ``args`` correspond to whatever information the personality
5383routine requires to know if this is an appropriate place to terminate the
Sean Silvaa1190322015-08-06 22:56:48 +00005384program. Control is transferred to the ``exception`` label if the
David Majnemer654e1302015-07-31 17:58:14 +00005385personality routine decides not to terminate the program for the
5386in-flight exception.
5387
5388Arguments:
5389""""""""""
5390
5391The instruction takes a list of arbitrary values which are interpreted
5392by the :ref:`personality function <personalityfn>`.
5393
5394The ``terminatepad`` may be given an ``exception`` label to
5395transfer control to if the in-flight exception matches the ``args``.
5396
5397Semantics:
5398""""""""""
5399
5400When the call stack is being unwound due to an exception being thrown,
5401the exception is compared against the ``args``. If it matches,
Sean Silvaa1190322015-08-06 22:56:48 +00005402then control is transfered to the ``exception`` basic block. Otherwise,
5403the program is terminated via personality-specific means. Typically,
David Majnemer654e1302015-07-31 17:58:14 +00005404the first argument to ``terminatepad`` specifies what function the
5405personality should defer to in order to terminate the program.
5406
5407The ``terminatepad`` instruction has several restrictions:
5408
5409- A terminate block is a basic block which is the unwind destination of
5410 an exceptional instruction.
5411- A terminate block must have a '``terminatepad``' instruction as its
5412 first non-PHI instruction.
5413- There can be only one '``terminatepad``' instruction within the
5414 terminate block.
5415- A basic block that is not a terminate block may not include a
5416 '``terminatepad``' instruction.
5417
5418Example:
5419""""""""
5420
5421.. code-block:: llvm
5422
5423 ;; A terminate block which only permits integers.
5424 terminatepad [i8** @_ZTIi] unwind label %continue
5425
Sean Silvab084af42012-12-07 10:36:55 +00005426.. _i_unreachable:
5427
5428'``unreachable``' Instruction
5429^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5430
5431Syntax:
5432"""""""
5433
5434::
5435
5436 unreachable
5437
5438Overview:
5439"""""""""
5440
5441The '``unreachable``' instruction has no defined semantics. This
5442instruction is used to inform the optimizer that a particular portion of
5443the code is not reachable. This can be used to indicate that the code
5444after a no-return function cannot be reached, and other facts.
5445
5446Semantics:
5447""""""""""
5448
5449The '``unreachable``' instruction has no defined semantics.
5450
5451.. _binaryops:
5452
5453Binary Operations
5454-----------------
5455
5456Binary operators are used to do most of the computation in a program.
5457They require two operands of the same type, execute an operation on
5458them, and produce a single value. The operands might represent multiple
5459data, as is the case with the :ref:`vector <t_vector>` data type. The
5460result value has the same type as its operands.
5461
5462There are several different binary operators:
5463
5464.. _i_add:
5465
5466'``add``' Instruction
5467^^^^^^^^^^^^^^^^^^^^^
5468
5469Syntax:
5470"""""""
5471
5472::
5473
Tim Northover675a0962014-06-13 14:24:23 +00005474 <result> = add <ty> <op1>, <op2> ; yields ty:result
5475 <result> = add nuw <ty> <op1>, <op2> ; yields ty:result
5476 <result> = add nsw <ty> <op1>, <op2> ; yields ty:result
5477 <result> = add nuw nsw <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005478
5479Overview:
5480"""""""""
5481
5482The '``add``' instruction returns the sum of its two operands.
5483
5484Arguments:
5485""""""""""
5486
5487The two arguments to the '``add``' instruction must be
5488:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
5489arguments must have identical types.
5490
5491Semantics:
5492""""""""""
5493
5494The value produced is the integer sum of the two operands.
5495
5496If the sum has unsigned overflow, the result returned is the
5497mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
5498the result.
5499
5500Because LLVM integers use a two's complement representation, this
5501instruction is appropriate for both signed and unsigned integers.
5502
5503``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
5504respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
5505result value of the ``add`` is a :ref:`poison value <poisonvalues>` if
5506unsigned and/or signed overflow, respectively, occurs.
5507
5508Example:
5509""""""""
5510
5511.. code-block:: llvm
5512
Tim Northover675a0962014-06-13 14:24:23 +00005513 <result> = add i32 4, %var ; yields i32:result = 4 + %var
Sean Silvab084af42012-12-07 10:36:55 +00005514
5515.. _i_fadd:
5516
5517'``fadd``' Instruction
5518^^^^^^^^^^^^^^^^^^^^^^
5519
5520Syntax:
5521"""""""
5522
5523::
5524
Tim Northover675a0962014-06-13 14:24:23 +00005525 <result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005526
5527Overview:
5528"""""""""
5529
5530The '``fadd``' instruction returns the sum of its two operands.
5531
5532Arguments:
5533""""""""""
5534
5535The two arguments to the '``fadd``' instruction must be :ref:`floating
5536point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
5537Both arguments must have identical types.
5538
5539Semantics:
5540""""""""""
5541
5542The value produced is the floating point sum of the two operands. This
5543instruction can also take any number of :ref:`fast-math flags <fastmath>`,
5544which are optimization hints to enable otherwise unsafe floating point
5545optimizations:
5546
5547Example:
5548""""""""
5549
5550.. code-block:: llvm
5551
Tim Northover675a0962014-06-13 14:24:23 +00005552 <result> = fadd float 4.0, %var ; yields float:result = 4.0 + %var
Sean Silvab084af42012-12-07 10:36:55 +00005553
5554'``sub``' Instruction
5555^^^^^^^^^^^^^^^^^^^^^
5556
5557Syntax:
5558"""""""
5559
5560::
5561
Tim Northover675a0962014-06-13 14:24:23 +00005562 <result> = sub <ty> <op1>, <op2> ; yields ty:result
5563 <result> = sub nuw <ty> <op1>, <op2> ; yields ty:result
5564 <result> = sub nsw <ty> <op1>, <op2> ; yields ty:result
5565 <result> = sub nuw nsw <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005566
5567Overview:
5568"""""""""
5569
5570The '``sub``' instruction returns the difference of its two operands.
5571
5572Note that the '``sub``' instruction is used to represent the '``neg``'
5573instruction present in most other intermediate representations.
5574
5575Arguments:
5576""""""""""
5577
5578The two arguments to the '``sub``' instruction must be
5579:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
5580arguments must have identical types.
5581
5582Semantics:
5583""""""""""
5584
5585The value produced is the integer difference of the two operands.
5586
5587If the difference has unsigned overflow, the result returned is the
5588mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
5589the result.
5590
5591Because LLVM integers use a two's complement representation, this
5592instruction is appropriate for both signed and unsigned integers.
5593
5594``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
5595respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
5596result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if
5597unsigned and/or signed overflow, respectively, occurs.
5598
5599Example:
5600""""""""
5601
5602.. code-block:: llvm
5603
Tim Northover675a0962014-06-13 14:24:23 +00005604 <result> = sub i32 4, %var ; yields i32:result = 4 - %var
5605 <result> = sub i32 0, %val ; yields i32:result = -%var
Sean Silvab084af42012-12-07 10:36:55 +00005606
5607.. _i_fsub:
5608
5609'``fsub``' Instruction
5610^^^^^^^^^^^^^^^^^^^^^^
5611
5612Syntax:
5613"""""""
5614
5615::
5616
Tim Northover675a0962014-06-13 14:24:23 +00005617 <result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005618
5619Overview:
5620"""""""""
5621
5622The '``fsub``' instruction returns the difference of its two operands.
5623
5624Note that the '``fsub``' instruction is used to represent the '``fneg``'
5625instruction present in most other intermediate representations.
5626
5627Arguments:
5628""""""""""
5629
5630The two arguments to the '``fsub``' instruction must be :ref:`floating
5631point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
5632Both arguments must have identical types.
5633
5634Semantics:
5635""""""""""
5636
5637The value produced is the floating point difference of the two operands.
5638This instruction can also take any number of :ref:`fast-math
5639flags <fastmath>`, which are optimization hints to enable otherwise
5640unsafe floating point optimizations:
5641
5642Example:
5643""""""""
5644
5645.. code-block:: llvm
5646
Tim Northover675a0962014-06-13 14:24:23 +00005647 <result> = fsub float 4.0, %var ; yields float:result = 4.0 - %var
5648 <result> = fsub float -0.0, %val ; yields float:result = -%var
Sean Silvab084af42012-12-07 10:36:55 +00005649
5650'``mul``' Instruction
5651^^^^^^^^^^^^^^^^^^^^^
5652
5653Syntax:
5654"""""""
5655
5656::
5657
Tim Northover675a0962014-06-13 14:24:23 +00005658 <result> = mul <ty> <op1>, <op2> ; yields ty:result
5659 <result> = mul nuw <ty> <op1>, <op2> ; yields ty:result
5660 <result> = mul nsw <ty> <op1>, <op2> ; yields ty:result
5661 <result> = mul nuw nsw <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005662
5663Overview:
5664"""""""""
5665
5666The '``mul``' instruction returns the product of its two operands.
5667
5668Arguments:
5669""""""""""
5670
5671The two arguments to the '``mul``' instruction must be
5672:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
5673arguments must have identical types.
5674
5675Semantics:
5676""""""""""
5677
5678The value produced is the integer product of the two operands.
5679
5680If the result of the multiplication has unsigned overflow, the result
5681returned is the mathematical result modulo 2\ :sup:`n`\ , where n is the
5682bit width of the result.
5683
5684Because LLVM integers use a two's complement representation, and the
5685result is the same width as the operands, this instruction returns the
5686correct result for both signed and unsigned integers. If a full product
5687(e.g. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be
5688sign-extended or zero-extended as appropriate to the width of the full
5689product.
5690
5691``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
5692respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
5693result value of the ``mul`` is a :ref:`poison value <poisonvalues>` if
5694unsigned and/or signed overflow, respectively, occurs.
5695
5696Example:
5697""""""""
5698
5699.. code-block:: llvm
5700
Tim Northover675a0962014-06-13 14:24:23 +00005701 <result> = mul i32 4, %var ; yields i32:result = 4 * %var
Sean Silvab084af42012-12-07 10:36:55 +00005702
5703.. _i_fmul:
5704
5705'``fmul``' Instruction
5706^^^^^^^^^^^^^^^^^^^^^^
5707
5708Syntax:
5709"""""""
5710
5711::
5712
Tim Northover675a0962014-06-13 14:24:23 +00005713 <result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005714
5715Overview:
5716"""""""""
5717
5718The '``fmul``' instruction returns the product of its two operands.
5719
5720Arguments:
5721""""""""""
5722
5723The two arguments to the '``fmul``' instruction must be :ref:`floating
5724point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
5725Both arguments must have identical types.
5726
5727Semantics:
5728""""""""""
5729
5730The value produced is the floating point product of the two operands.
5731This instruction can also take any number of :ref:`fast-math
5732flags <fastmath>`, which are optimization hints to enable otherwise
5733unsafe floating point optimizations:
5734
5735Example:
5736""""""""
5737
5738.. code-block:: llvm
5739
Tim Northover675a0962014-06-13 14:24:23 +00005740 <result> = fmul float 4.0, %var ; yields float:result = 4.0 * %var
Sean Silvab084af42012-12-07 10:36:55 +00005741
5742'``udiv``' Instruction
5743^^^^^^^^^^^^^^^^^^^^^^
5744
5745Syntax:
5746"""""""
5747
5748::
5749
Tim Northover675a0962014-06-13 14:24:23 +00005750 <result> = udiv <ty> <op1>, <op2> ; yields ty:result
5751 <result> = udiv exact <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005752
5753Overview:
5754"""""""""
5755
5756The '``udiv``' instruction returns the quotient of its two operands.
5757
5758Arguments:
5759""""""""""
5760
5761The two arguments to the '``udiv``' instruction must be
5762:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
5763arguments must have identical types.
5764
5765Semantics:
5766""""""""""
5767
5768The value produced is the unsigned integer quotient of the two operands.
5769
5770Note that unsigned integer division and signed integer division are
5771distinct operations; for signed integer division, use '``sdiv``'.
5772
5773Division by zero leads to undefined behavior.
5774
5775If the ``exact`` keyword is present, the result value of the ``udiv`` is
5776a :ref:`poison value <poisonvalues>` if %op1 is not a multiple of %op2 (as
5777such, "((a udiv exact b) mul b) == a").
5778
5779Example:
5780""""""""
5781
5782.. code-block:: llvm
5783
Tim Northover675a0962014-06-13 14:24:23 +00005784 <result> = udiv i32 4, %var ; yields i32:result = 4 / %var
Sean Silvab084af42012-12-07 10:36:55 +00005785
5786'``sdiv``' Instruction
5787^^^^^^^^^^^^^^^^^^^^^^
5788
5789Syntax:
5790"""""""
5791
5792::
5793
Tim Northover675a0962014-06-13 14:24:23 +00005794 <result> = sdiv <ty> <op1>, <op2> ; yields ty:result
5795 <result> = sdiv exact <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005796
5797Overview:
5798"""""""""
5799
5800The '``sdiv``' instruction returns the quotient of its two operands.
5801
5802Arguments:
5803""""""""""
5804
5805The two arguments to the '``sdiv``' instruction must be
5806:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
5807arguments must have identical types.
5808
5809Semantics:
5810""""""""""
5811
5812The value produced is the signed integer quotient of the two operands
5813rounded towards zero.
5814
5815Note that signed integer division and unsigned integer division are
5816distinct operations; for unsigned integer division, use '``udiv``'.
5817
5818Division by zero leads to undefined behavior. Overflow also leads to
5819undefined behavior; this is a rare case, but can occur, for example, by
5820doing a 32-bit division of -2147483648 by -1.
5821
5822If the ``exact`` keyword is present, the result value of the ``sdiv`` is
5823a :ref:`poison value <poisonvalues>` if the result would be rounded.
5824
5825Example:
5826""""""""
5827
5828.. code-block:: llvm
5829
Tim Northover675a0962014-06-13 14:24:23 +00005830 <result> = sdiv i32 4, %var ; yields i32:result = 4 / %var
Sean Silvab084af42012-12-07 10:36:55 +00005831
5832.. _i_fdiv:
5833
5834'``fdiv``' Instruction
5835^^^^^^^^^^^^^^^^^^^^^^
5836
5837Syntax:
5838"""""""
5839
5840::
5841
Tim Northover675a0962014-06-13 14:24:23 +00005842 <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005843
5844Overview:
5845"""""""""
5846
5847The '``fdiv``' instruction returns the quotient of its two operands.
5848
5849Arguments:
5850""""""""""
5851
5852The two arguments to the '``fdiv``' instruction must be :ref:`floating
5853point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
5854Both arguments must have identical types.
5855
5856Semantics:
5857""""""""""
5858
5859The value produced is the floating point quotient of the two operands.
5860This instruction can also take any number of :ref:`fast-math
5861flags <fastmath>`, which are optimization hints to enable otherwise
5862unsafe floating point optimizations:
5863
5864Example:
5865""""""""
5866
5867.. code-block:: llvm
5868
Tim Northover675a0962014-06-13 14:24:23 +00005869 <result> = fdiv float 4.0, %var ; yields float:result = 4.0 / %var
Sean Silvab084af42012-12-07 10:36:55 +00005870
5871'``urem``' Instruction
5872^^^^^^^^^^^^^^^^^^^^^^
5873
5874Syntax:
5875"""""""
5876
5877::
5878
Tim Northover675a0962014-06-13 14:24:23 +00005879 <result> = urem <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005880
5881Overview:
5882"""""""""
5883
5884The '``urem``' instruction returns the remainder from the unsigned
5885division of its two arguments.
5886
5887Arguments:
5888""""""""""
5889
5890The two arguments to the '``urem``' instruction must be
5891:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
5892arguments must have identical types.
5893
5894Semantics:
5895""""""""""
5896
5897This instruction returns the unsigned integer *remainder* of a division.
5898This instruction always performs an unsigned division to get the
5899remainder.
5900
5901Note that unsigned integer remainder and signed integer remainder are
5902distinct operations; for signed integer remainder, use '``srem``'.
5903
5904Taking the remainder of a division by zero leads to undefined behavior.
5905
5906Example:
5907""""""""
5908
5909.. code-block:: llvm
5910
Tim Northover675a0962014-06-13 14:24:23 +00005911 <result> = urem i32 4, %var ; yields i32:result = 4 % %var
Sean Silvab084af42012-12-07 10:36:55 +00005912
5913'``srem``' Instruction
5914^^^^^^^^^^^^^^^^^^^^^^
5915
5916Syntax:
5917"""""""
5918
5919::
5920
Tim Northover675a0962014-06-13 14:24:23 +00005921 <result> = srem <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005922
5923Overview:
5924"""""""""
5925
5926The '``srem``' instruction returns the remainder from the signed
5927division of its two operands. This instruction can also take
5928:ref:`vector <t_vector>` versions of the values in which case the elements
5929must be integers.
5930
5931Arguments:
5932""""""""""
5933
5934The two arguments to the '``srem``' instruction must be
5935:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
5936arguments must have identical types.
5937
5938Semantics:
5939""""""""""
5940
5941This instruction returns the *remainder* of a division (where the result
5942is either zero or has the same sign as the dividend, ``op1``), not the
5943*modulo* operator (where the result is either zero or has the same sign
5944as the divisor, ``op2``) of a value. For more information about the
5945difference, see `The Math
5946Forum <http://mathforum.org/dr.math/problems/anne.4.28.99.html>`_. For a
5947table of how this is implemented in various languages, please see
5948`Wikipedia: modulo
5949operation <http://en.wikipedia.org/wiki/Modulo_operation>`_.
5950
5951Note that signed integer remainder and unsigned integer remainder are
5952distinct operations; for unsigned integer remainder, use '``urem``'.
5953
5954Taking the remainder of a division by zero leads to undefined behavior.
5955Overflow also leads to undefined behavior; this is a rare case, but can
5956occur, for example, by taking the remainder of a 32-bit division of
5957-2147483648 by -1. (The remainder doesn't actually overflow, but this
5958rule lets srem be implemented using instructions that return both the
5959result of the division and the remainder.)
5960
5961Example:
5962""""""""
5963
5964.. code-block:: llvm
5965
Tim Northover675a0962014-06-13 14:24:23 +00005966 <result> = srem i32 4, %var ; yields i32:result = 4 % %var
Sean Silvab084af42012-12-07 10:36:55 +00005967
5968.. _i_frem:
5969
5970'``frem``' Instruction
5971^^^^^^^^^^^^^^^^^^^^^^
5972
5973Syntax:
5974"""""""
5975
5976::
5977
Tim Northover675a0962014-06-13 14:24:23 +00005978 <result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00005979
5980Overview:
5981"""""""""
5982
5983The '``frem``' instruction returns the remainder from the division of
5984its two operands.
5985
5986Arguments:
5987""""""""""
5988
5989The two arguments to the '``frem``' instruction must be :ref:`floating
5990point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
5991Both arguments must have identical types.
5992
5993Semantics:
5994""""""""""
5995
5996This instruction returns the *remainder* of a division. The remainder
5997has the same sign as the dividend. This instruction can also take any
5998number of :ref:`fast-math flags <fastmath>`, which are optimization hints
5999to enable otherwise unsafe floating point optimizations:
6000
6001Example:
6002""""""""
6003
6004.. code-block:: llvm
6005
Tim Northover675a0962014-06-13 14:24:23 +00006006 <result> = frem float 4.0, %var ; yields float:result = 4.0 % %var
Sean Silvab084af42012-12-07 10:36:55 +00006007
6008.. _bitwiseops:
6009
6010Bitwise Binary Operations
6011-------------------------
6012
6013Bitwise binary operators are used to do various forms of bit-twiddling
6014in a program. They are generally very efficient instructions and can
6015commonly be strength reduced from other instructions. They require two
6016operands of the same type, execute an operation on them, and produce a
6017single value. The resulting value is the same type as its operands.
6018
6019'``shl``' Instruction
6020^^^^^^^^^^^^^^^^^^^^^
6021
6022Syntax:
6023"""""""
6024
6025::
6026
Tim Northover675a0962014-06-13 14:24:23 +00006027 <result> = shl <ty> <op1>, <op2> ; yields ty:result
6028 <result> = shl nuw <ty> <op1>, <op2> ; yields ty:result
6029 <result> = shl nsw <ty> <op1>, <op2> ; yields ty:result
6030 <result> = shl nuw nsw <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00006031
6032Overview:
6033"""""""""
6034
6035The '``shl``' instruction returns the first operand shifted to the left
6036a specified number of bits.
6037
6038Arguments:
6039""""""""""
6040
6041Both arguments to the '``shl``' instruction must be the same
6042:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
6043'``op2``' is treated as an unsigned value.
6044
6045Semantics:
6046""""""""""
6047
6048The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`,
6049where ``n`` is the width of the result. If ``op2`` is (statically or
Sean Silvab8a108c2015-04-17 21:58:55 +00006050dynamically) equal to or larger than the number of bits in
Sean Silvab084af42012-12-07 10:36:55 +00006051``op1``, the result is undefined. If the arguments are vectors, each
6052vector element of ``op1`` is shifted by the corresponding shift amount
6053in ``op2``.
6054
6055If the ``nuw`` keyword is present, then the shift produces a :ref:`poison
6056value <poisonvalues>` if it shifts out any non-zero bits. If the
6057``nsw`` keyword is present, then the shift produces a :ref:`poison
6058value <poisonvalues>` if it shifts out any bits that disagree with the
6059resultant sign bit. As such, NUW/NSW have the same semantics as they
6060would if the shift were expressed as a mul instruction with the same
6061nsw/nuw bits in (mul %op1, (shl 1, %op2)).
6062
6063Example:
6064""""""""
6065
6066.. code-block:: llvm
6067
Tim Northover675a0962014-06-13 14:24:23 +00006068 <result> = shl i32 4, %var ; yields i32: 4 << %var
6069 <result> = shl i32 4, 2 ; yields i32: 16
6070 <result> = shl i32 1, 10 ; yields i32: 1024
Sean Silvab084af42012-12-07 10:36:55 +00006071 <result> = shl i32 1, 32 ; undefined
6072 <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 2, i32 4>
6073
6074'``lshr``' Instruction
6075^^^^^^^^^^^^^^^^^^^^^^
6076
6077Syntax:
6078"""""""
6079
6080::
6081
Tim Northover675a0962014-06-13 14:24:23 +00006082 <result> = lshr <ty> <op1>, <op2> ; yields ty:result
6083 <result> = lshr exact <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00006084
6085Overview:
6086"""""""""
6087
6088The '``lshr``' instruction (logical shift right) returns the first
6089operand shifted to the right a specified number of bits with zero fill.
6090
6091Arguments:
6092""""""""""
6093
6094Both arguments to the '``lshr``' instruction must be the same
6095:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
6096'``op2``' is treated as an unsigned value.
6097
6098Semantics:
6099""""""""""
6100
6101This instruction always performs a logical shift right operation. The
6102most significant bits of the result will be filled with zero bits after
6103the shift. If ``op2`` is (statically or dynamically) equal to or larger
6104than the number of bits in ``op1``, the result is undefined. If the
6105arguments are vectors, each vector element of ``op1`` is shifted by the
6106corresponding shift amount in ``op2``.
6107
6108If the ``exact`` keyword is present, the result value of the ``lshr`` is
6109a :ref:`poison value <poisonvalues>` if any of the bits shifted out are
6110non-zero.
6111
6112Example:
6113""""""""
6114
6115.. code-block:: llvm
6116
Tim Northover675a0962014-06-13 14:24:23 +00006117 <result> = lshr i32 4, 1 ; yields i32:result = 2
6118 <result> = lshr i32 4, 2 ; yields i32:result = 1
6119 <result> = lshr i8 4, 3 ; yields i8:result = 0
6120 <result> = lshr i8 -2, 1 ; yields i8:result = 0x7F
Sean Silvab084af42012-12-07 10:36:55 +00006121 <result> = lshr i32 1, 32 ; undefined
6122 <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1>
6123
6124'``ashr``' Instruction
6125^^^^^^^^^^^^^^^^^^^^^^
6126
6127Syntax:
6128"""""""
6129
6130::
6131
Tim Northover675a0962014-06-13 14:24:23 +00006132 <result> = ashr <ty> <op1>, <op2> ; yields ty:result
6133 <result> = ashr exact <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00006134
6135Overview:
6136"""""""""
6137
6138The '``ashr``' instruction (arithmetic shift right) returns the first
6139operand shifted to the right a specified number of bits with sign
6140extension.
6141
6142Arguments:
6143""""""""""
6144
6145Both arguments to the '``ashr``' instruction must be the same
6146:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
6147'``op2``' is treated as an unsigned value.
6148
6149Semantics:
6150""""""""""
6151
6152This instruction always performs an arithmetic shift right operation,
6153The most significant bits of the result will be filled with the sign bit
6154of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger
6155than the number of bits in ``op1``, the result is undefined. If the
6156arguments are vectors, each vector element of ``op1`` is shifted by the
6157corresponding shift amount in ``op2``.
6158
6159If the ``exact`` keyword is present, the result value of the ``ashr`` is
6160a :ref:`poison value <poisonvalues>` if any of the bits shifted out are
6161non-zero.
6162
6163Example:
6164""""""""
6165
6166.. code-block:: llvm
6167
Tim Northover675a0962014-06-13 14:24:23 +00006168 <result> = ashr i32 4, 1 ; yields i32:result = 2
6169 <result> = ashr i32 4, 2 ; yields i32:result = 1
6170 <result> = ashr i8 4, 3 ; yields i8:result = 0
6171 <result> = ashr i8 -2, 1 ; yields i8:result = -1
Sean Silvab084af42012-12-07 10:36:55 +00006172 <result> = ashr i32 1, 32 ; undefined
6173 <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> ; yields: result=<2 x i32> < i32 -1, i32 0>
6174
6175'``and``' Instruction
6176^^^^^^^^^^^^^^^^^^^^^
6177
6178Syntax:
6179"""""""
6180
6181::
6182
Tim Northover675a0962014-06-13 14:24:23 +00006183 <result> = and <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00006184
6185Overview:
6186"""""""""
6187
6188The '``and``' instruction returns the bitwise logical and of its two
6189operands.
6190
6191Arguments:
6192""""""""""
6193
6194The two arguments to the '``and``' instruction must be
6195:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
6196arguments must have identical types.
6197
6198Semantics:
6199""""""""""
6200
6201The truth table used for the '``and``' instruction is:
6202
6203+-----+-----+-----+
6204| In0 | In1 | Out |
6205+-----+-----+-----+
6206| 0 | 0 | 0 |
6207+-----+-----+-----+
6208| 0 | 1 | 0 |
6209+-----+-----+-----+
6210| 1 | 0 | 0 |
6211+-----+-----+-----+
6212| 1 | 1 | 1 |
6213+-----+-----+-----+
6214
6215Example:
6216""""""""
6217
6218.. code-block:: llvm
6219
Tim Northover675a0962014-06-13 14:24:23 +00006220 <result> = and i32 4, %var ; yields i32:result = 4 & %var
6221 <result> = and i32 15, 40 ; yields i32:result = 8
6222 <result> = and i32 4, 8 ; yields i32:result = 0
Sean Silvab084af42012-12-07 10:36:55 +00006223
6224'``or``' Instruction
6225^^^^^^^^^^^^^^^^^^^^
6226
6227Syntax:
6228"""""""
6229
6230::
6231
Tim Northover675a0962014-06-13 14:24:23 +00006232 <result> = or <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00006233
6234Overview:
6235"""""""""
6236
6237The '``or``' instruction returns the bitwise logical inclusive or of its
6238two operands.
6239
6240Arguments:
6241""""""""""
6242
6243The two arguments to the '``or``' instruction must be
6244:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
6245arguments must have identical types.
6246
6247Semantics:
6248""""""""""
6249
6250The truth table used for the '``or``' instruction is:
6251
6252+-----+-----+-----+
6253| In0 | In1 | Out |
6254+-----+-----+-----+
6255| 0 | 0 | 0 |
6256+-----+-----+-----+
6257| 0 | 1 | 1 |
6258+-----+-----+-----+
6259| 1 | 0 | 1 |
6260+-----+-----+-----+
6261| 1 | 1 | 1 |
6262+-----+-----+-----+
6263
6264Example:
6265""""""""
6266
6267::
6268
Tim Northover675a0962014-06-13 14:24:23 +00006269 <result> = or i32 4, %var ; yields i32:result = 4 | %var
6270 <result> = or i32 15, 40 ; yields i32:result = 47
6271 <result> = or i32 4, 8 ; yields i32:result = 12
Sean Silvab084af42012-12-07 10:36:55 +00006272
6273'``xor``' Instruction
6274^^^^^^^^^^^^^^^^^^^^^
6275
6276Syntax:
6277"""""""
6278
6279::
6280
Tim Northover675a0962014-06-13 14:24:23 +00006281 <result> = xor <ty> <op1>, <op2> ; yields ty:result
Sean Silvab084af42012-12-07 10:36:55 +00006282
6283Overview:
6284"""""""""
6285
6286The '``xor``' instruction returns the bitwise logical exclusive or of
6287its two operands. The ``xor`` is used to implement the "one's
6288complement" operation, which is the "~" operator in C.
6289
6290Arguments:
6291""""""""""
6292
6293The two arguments to the '``xor``' instruction must be
6294:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
6295arguments must have identical types.
6296
6297Semantics:
6298""""""""""
6299
6300The truth table used for the '``xor``' instruction is:
6301
6302+-----+-----+-----+
6303| In0 | In1 | Out |
6304+-----+-----+-----+
6305| 0 | 0 | 0 |
6306+-----+-----+-----+
6307| 0 | 1 | 1 |
6308+-----+-----+-----+
6309| 1 | 0 | 1 |
6310+-----+-----+-----+
6311| 1 | 1 | 0 |
6312+-----+-----+-----+
6313
6314Example:
6315""""""""
6316
6317.. code-block:: llvm
6318
Tim Northover675a0962014-06-13 14:24:23 +00006319 <result> = xor i32 4, %var ; yields i32:result = 4 ^ %var
6320 <result> = xor i32 15, 40 ; yields i32:result = 39
6321 <result> = xor i32 4, 8 ; yields i32:result = 12
6322 <result> = xor i32 %V, -1 ; yields i32:result = ~%V
Sean Silvab084af42012-12-07 10:36:55 +00006323
6324Vector Operations
6325-----------------
6326
6327LLVM supports several instructions to represent vector operations in a
6328target-independent manner. These instructions cover the element-access
6329and vector-specific operations needed to process vectors effectively.
6330While LLVM does directly support these vector operations, many
6331sophisticated algorithms will want to use target-specific intrinsics to
6332take full advantage of a specific target.
6333
6334.. _i_extractelement:
6335
6336'``extractelement``' Instruction
6337^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6338
6339Syntax:
6340"""""""
6341
6342::
6343
Michael J. Spencer1f10c5ea2014-05-01 22:12:39 +00006344 <result> = extractelement <n x <ty>> <val>, <ty2> <idx> ; yields <ty>
Sean Silvab084af42012-12-07 10:36:55 +00006345
6346Overview:
6347"""""""""
6348
6349The '``extractelement``' instruction extracts a single scalar element
6350from a vector at a specified index.
6351
6352Arguments:
6353""""""""""
6354
6355The first operand of an '``extractelement``' instruction is a value of
6356:ref:`vector <t_vector>` type. The second operand is an index indicating
6357the position from which to extract the element. The index may be a
Michael J. Spencer1f10c5ea2014-05-01 22:12:39 +00006358variable of any integer type.
Sean Silvab084af42012-12-07 10:36:55 +00006359
6360Semantics:
6361""""""""""
6362
6363The result is a scalar of the same type as the element type of ``val``.
6364Its value is the value at position ``idx`` of ``val``. If ``idx``
6365exceeds the length of ``val``, the results are undefined.
6366
6367Example:
6368""""""""
6369
6370.. code-block:: llvm
6371
6372 <result> = extractelement <4 x i32> %vec, i32 0 ; yields i32
6373
6374.. _i_insertelement:
6375
6376'``insertelement``' Instruction
6377^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6378
6379Syntax:
6380"""""""
6381
6382::
6383
Michael J. Spencer1f10c5ea2014-05-01 22:12:39 +00006384 <result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <n x <ty>>
Sean Silvab084af42012-12-07 10:36:55 +00006385
6386Overview:
6387"""""""""
6388
6389The '``insertelement``' instruction inserts a scalar element into a
6390vector at a specified index.
6391
6392Arguments:
6393""""""""""
6394
6395The first operand of an '``insertelement``' instruction is a value of
6396:ref:`vector <t_vector>` type. The second operand is a scalar value whose
6397type must equal the element type of the first operand. The third operand
6398is an index indicating the position at which to insert the value. The
Michael J. Spencer1f10c5ea2014-05-01 22:12:39 +00006399index may be a variable of any integer type.
Sean Silvab084af42012-12-07 10:36:55 +00006400
6401Semantics:
6402""""""""""
6403
6404The result is a vector of the same type as ``val``. Its element values
6405are those of ``val`` except at position ``idx``, where it gets the value
6406``elt``. If ``idx`` exceeds the length of ``val``, the results are
6407undefined.
6408
6409Example:
6410""""""""
6411
6412.. code-block:: llvm
6413
6414 <result> = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32>
6415
6416.. _i_shufflevector:
6417
6418'``shufflevector``' Instruction
6419^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6420
6421Syntax:
6422"""""""
6423
6424::
6425
6426 <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> ; yields <m x <ty>>
6427
6428Overview:
6429"""""""""
6430
6431The '``shufflevector``' instruction constructs a permutation of elements
6432from two input vectors, returning a vector with the same element type as
6433the input and length that is the same as the shuffle mask.
6434
6435Arguments:
6436""""""""""
6437
6438The first two operands of a '``shufflevector``' instruction are vectors
6439with the same type. The third argument is a shuffle mask whose element
6440type is always 'i32'. The result of the instruction is a vector whose
6441length is the same as the shuffle mask and whose element type is the
6442same as the element type of the first two operands.
6443
6444The shuffle mask operand is required to be a constant vector with either
6445constant integer or undef values.
6446
6447Semantics:
6448""""""""""
6449
6450The elements of the two input vectors are numbered from left to right
6451across both of the vectors. The shuffle mask operand specifies, for each
6452element of the result vector, which element of the two input vectors the
6453result element gets. The element selector may be undef (meaning "don't
6454care") and the second operand may be undef if performing a shuffle from
6455only one vector.
6456
6457Example:
6458""""""""
6459
6460.. code-block:: llvm
6461
6462 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
6463 <4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32>
6464 <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
6465 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle.
6466 <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
6467 <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32>
6468 <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
6469 <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 > ; yields <8 x i32>
6470
6471Aggregate Operations
6472--------------------
6473
6474LLVM supports several instructions for working with
6475:ref:`aggregate <t_aggregate>` values.
6476
6477.. _i_extractvalue:
6478
6479'``extractvalue``' Instruction
6480^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6481
6482Syntax:
6483"""""""
6484
6485::
6486
6487 <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
6488
6489Overview:
6490"""""""""
6491
6492The '``extractvalue``' instruction extracts the value of a member field
6493from an :ref:`aggregate <t_aggregate>` value.
6494
6495Arguments:
6496""""""""""
6497
6498The first operand of an '``extractvalue``' instruction is a value of
6499:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The operands are
6500constant indices to specify which value to extract in a similar manner
6501as indices in a '``getelementptr``' instruction.
6502
6503The major differences to ``getelementptr`` indexing are:
6504
6505- Since the value being indexed is not a pointer, the first index is
6506 omitted and assumed to be zero.
6507- At least one index must be specified.
6508- Not only struct indices but also array indices must be in bounds.
6509
6510Semantics:
6511""""""""""
6512
6513The result is the value at the position in the aggregate specified by
6514the index operands.
6515
6516Example:
6517""""""""
6518
6519.. code-block:: llvm
6520
6521 <result> = extractvalue {i32, float} %agg, 0 ; yields i32
6522
6523.. _i_insertvalue:
6524
6525'``insertvalue``' Instruction
6526^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6527
6528Syntax:
6529"""""""
6530
6531::
6532
6533 <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* ; yields <aggregate type>
6534
6535Overview:
6536"""""""""
6537
6538The '``insertvalue``' instruction inserts a value into a member field in
6539an :ref:`aggregate <t_aggregate>` value.
6540
6541Arguments:
6542""""""""""
6543
6544The first operand of an '``insertvalue``' instruction is a value of
6545:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The second operand is
6546a first-class value to insert. The following operands are constant
6547indices indicating the position at which to insert the value in a
6548similar manner as indices in a '``extractvalue``' instruction. The value
6549to insert must have the same type as the value identified by the
6550indices.
6551
6552Semantics:
6553""""""""""
6554
6555The result is an aggregate of the same type as ``val``. Its value is
6556that of ``val`` except that the value at the position specified by the
6557indices is that of ``elt``.
6558
6559Example:
6560""""""""
6561
6562.. code-block:: llvm
6563
6564 %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef}
6565 %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val}
Dan Liewffcfe7f2014-09-08 21:19:46 +00006566 %agg3 = insertvalue {i32, {float}} undef, float %val, 1, 0 ; yields {i32 undef, {float %val}}
Sean Silvab084af42012-12-07 10:36:55 +00006567
6568.. _memoryops:
6569
6570Memory Access and Addressing Operations
6571---------------------------------------
6572
6573A key design point of an SSA-based representation is how it represents
6574memory. In LLVM, no memory locations are in SSA form, which makes things
6575very simple. This section describes how to read, write, and allocate
6576memory in LLVM.
6577
6578.. _i_alloca:
6579
6580'``alloca``' Instruction
6581^^^^^^^^^^^^^^^^^^^^^^^^
6582
6583Syntax:
6584"""""""
6585
6586::
6587
Tim Northover675a0962014-06-13 14:24:23 +00006588 <result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] ; yields type*:result
Sean Silvab084af42012-12-07 10:36:55 +00006589
6590Overview:
6591"""""""""
6592
6593The '``alloca``' instruction allocates memory on the stack frame of the
6594currently executing function, to be automatically released when this
6595function returns to its caller. The object is always allocated in the
6596generic address space (address space zero).
6597
6598Arguments:
6599""""""""""
6600
6601The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements``
6602bytes of memory on the runtime stack, returning a pointer of the
6603appropriate type to the program. If "NumElements" is specified, it is
6604the number of elements allocated, otherwise "NumElements" is defaulted
6605to be one. If a constant alignment is specified, the value result of the
Reid Kleckner15fe7a52014-07-15 01:16:09 +00006606allocation is guaranteed to be aligned to at least that boundary. The
6607alignment may not be greater than ``1 << 29``. If not specified, or if
6608zero, the target can choose to align the allocation on any convenient
6609boundary compatible with the type.
Sean Silvab084af42012-12-07 10:36:55 +00006610
6611'``type``' may be any sized type.
6612
6613Semantics:
6614""""""""""
6615
6616Memory is allocated; a pointer is returned. The operation is undefined
6617if there is insufficient stack space for the allocation. '``alloca``'d
6618memory is automatically released when the function returns. The
6619'``alloca``' instruction is commonly used to represent automatic
6620variables that must have an address available. When the function returns
6621(either with the ``ret`` or ``resume`` instructions), the memory is
6622reclaimed. Allocating zero bytes is legal, but the result is undefined.
6623The order in which memory is allocated (ie., which way the stack grows)
6624is not specified.
6625
6626Example:
6627""""""""
6628
6629.. code-block:: llvm
6630
Tim Northover675a0962014-06-13 14:24:23 +00006631 %ptr = alloca i32 ; yields i32*:ptr
6632 %ptr = alloca i32, i32 4 ; yields i32*:ptr
6633 %ptr = alloca i32, i32 4, align 1024 ; yields i32*:ptr
6634 %ptr = alloca i32, align 1024 ; yields i32*:ptr
Sean Silvab084af42012-12-07 10:36:55 +00006635
6636.. _i_load:
6637
6638'``load``' Instruction
6639^^^^^^^^^^^^^^^^^^^^^^
6640
6641Syntax:
6642"""""""
6643
6644::
6645
Sanjoy Dasf9995472015-05-19 20:10:19 +00006646 <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !nonnull !<index>][, !dereferenceable !<index>][, !dereferenceable_or_null !<index>]
Sean Silvab084af42012-12-07 10:36:55 +00006647 <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
6648 !<index> = !{ i32 1 }
6649
6650Overview:
6651"""""""""
6652
6653The '``load``' instruction is used to read from memory.
6654
6655Arguments:
6656""""""""""
6657
Eli Bendersky239a78b2013-04-17 20:17:08 +00006658The argument to the ``load`` instruction specifies the memory address
David Blaikiec7aabbb2015-03-04 22:06:14 +00006659from which to load. The type specified must be a :ref:`first
Sean Silvab084af42012-12-07 10:36:55 +00006660class <t_firstclass>` type. If the ``load`` is marked as ``volatile``,
6661then the optimizer is not allowed to modify the number or order of
6662execution of this ``load`` with other :ref:`volatile
6663operations <volatile>`.
6664
6665If the ``load`` is marked as ``atomic``, it takes an extra
6666:ref:`ordering <ordering>` and optional ``singlethread`` argument. The
6667``release`` and ``acq_rel`` orderings are not valid on ``load``
6668instructions. Atomic loads produce :ref:`defined <memmodel>` results
6669when they may see multiple atomic stores. The type of the pointee must
6670be an integer type whose bit width is a power of two greater than or
6671equal to eight and less than or equal to a target-specific size limit.
6672``align`` must be explicitly specified on atomic loads, and the load has
6673undefined behavior if the alignment is not set to a value which is at
6674least the size in bytes of the pointee. ``!nontemporal`` does not have
6675any defined semantics for atomic loads.
6676
6677The optional constant ``align`` argument specifies the alignment of the
6678operation (that is, the alignment of the memory address). A value of 0
Eli Bendersky239a78b2013-04-17 20:17:08 +00006679or an omitted ``align`` argument means that the operation has the ABI
Sean Silvab084af42012-12-07 10:36:55 +00006680alignment for the target. It is the responsibility of the code emitter
6681to ensure that the alignment information is correct. Overestimating the
6682alignment results in undefined behavior. Underestimating the alignment
Reid Kleckner15fe7a52014-07-15 01:16:09 +00006683may produce less efficient code. An alignment of 1 is always safe. The
6684maximum possible alignment is ``1 << 29``.
Sean Silvab084af42012-12-07 10:36:55 +00006685
6686The optional ``!nontemporal`` metadata must reference a single
Stefanus Du Toit736e2e22013-06-20 14:02:44 +00006687metadata name ``<index>`` corresponding to a metadata node with one
Sean Silvab084af42012-12-07 10:36:55 +00006688``i32`` entry of value 1. The existence of the ``!nontemporal``
Stefanus Du Toit736e2e22013-06-20 14:02:44 +00006689metadata on the instruction tells the optimizer and code generator
Sean Silvab084af42012-12-07 10:36:55 +00006690that this load is not expected to be reused in the cache. The code
6691generator may select special instructions to save cache bandwidth, such
6692as the ``MOVNT`` instruction on x86.
6693
6694The optional ``!invariant.load`` metadata must reference a single
Stefanus Du Toit736e2e22013-06-20 14:02:44 +00006695metadata name ``<index>`` corresponding to a metadata node with no
6696entries. The existence of the ``!invariant.load`` metadata on the
Philip Reamese1526fc2014-11-24 22:32:43 +00006697instruction tells the optimizer and code generator that the address
6698operand to this load points to memory which can be assumed unchanged.
Mehdi Amini4a121fa2015-03-14 22:04:06 +00006699Being invariant does not imply that a location is dereferenceable,
6700but it does imply that once the location is known dereferenceable
6701its value is henceforth unchanging.
Sean Silvab084af42012-12-07 10:36:55 +00006702
Philip Reamescdb72f32014-10-20 22:40:55 +00006703The optional ``!nonnull`` metadata must reference a single
6704metadata name ``<index>`` corresponding to a metadata node with no
6705entries. The existence of the ``!nonnull`` metadata on the
6706instruction tells the optimizer that the value loaded is known to
Sean Silvaa1190322015-08-06 22:56:48 +00006707never be null. This is analogous to the ''nonnull'' attribute
6708on parameters and return values. This metadata can only be applied
Mehdi Amini4a121fa2015-03-14 22:04:06 +00006709to loads of a pointer type.
Philip Reamescdb72f32014-10-20 22:40:55 +00006710
Sanjoy Dasf9995472015-05-19 20:10:19 +00006711The optional ``!dereferenceable`` metadata must reference a single
6712metadata name ``<index>`` corresponding to a metadata node with one ``i64``
Sean Silva706fba52015-08-06 22:56:24 +00006713entry. The existence of the ``!dereferenceable`` metadata on the instruction
Sanjoy Dasf9995472015-05-19 20:10:19 +00006714tells the optimizer that the value loaded is known to be dereferenceable.
Sean Silva706fba52015-08-06 22:56:24 +00006715The number of bytes known to be dereferenceable is specified by the integer
6716value in the metadata node. This is analogous to the ''dereferenceable''
6717attribute on parameters and return values. This metadata can only be applied
Sanjoy Dasf9995472015-05-19 20:10:19 +00006718to loads of a pointer type.
6719
6720The optional ``!dereferenceable_or_null`` metadata must reference a single
6721metadata name ``<index>`` corresponding to a metadata node with one ``i64``
Sean Silva706fba52015-08-06 22:56:24 +00006722entry. The existence of the ``!dereferenceable_or_null`` metadata on the
Sanjoy Dasf9995472015-05-19 20:10:19 +00006723instruction tells the optimizer that the value loaded is known to be either
6724dereferenceable or null.
Sean Silva706fba52015-08-06 22:56:24 +00006725The number of bytes known to be dereferenceable is specified by the integer
6726value in the metadata node. This is analogous to the ''dereferenceable_or_null''
6727attribute on parameters and return values. This metadata can only be applied
Sanjoy Dasf9995472015-05-19 20:10:19 +00006728to loads of a pointer type.
6729
Sean Silvab084af42012-12-07 10:36:55 +00006730Semantics:
6731""""""""""
6732
6733The location of memory pointed to is loaded. If the value being loaded
6734is of scalar type then the number of bytes read does not exceed the
6735minimum number of bytes needed to hold all bits of the type. For
6736example, loading an ``i24`` reads at most three bytes. When loading a
6737value of a type like ``i20`` with a size that is not an integral number
6738of bytes, the result is undefined if the value was not originally
6739written using a store of the same type.
6740
6741Examples:
6742"""""""""
6743
6744.. code-block:: llvm
6745
Tim Northover675a0962014-06-13 14:24:23 +00006746 %ptr = alloca i32 ; yields i32*:ptr
6747 store i32 3, i32* %ptr ; yields void
David Blaikiec7aabbb2015-03-04 22:06:14 +00006748 %val = load i32, i32* %ptr ; yields i32:val = i32 3
Sean Silvab084af42012-12-07 10:36:55 +00006749
6750.. _i_store:
6751
6752'``store``' Instruction
6753^^^^^^^^^^^^^^^^^^^^^^^
6754
6755Syntax:
6756"""""""
6757
6758::
6759
Tim Northover675a0962014-06-13 14:24:23 +00006760 store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] ; yields void
6761 store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> ; yields void
Sean Silvab084af42012-12-07 10:36:55 +00006762
6763Overview:
6764"""""""""
6765
6766The '``store``' instruction is used to write to memory.
6767
6768Arguments:
6769""""""""""
6770
Eli Benderskyca380842013-04-17 17:17:20 +00006771There are two arguments to the ``store`` instruction: a value to store
6772and an address at which to store it. The type of the ``<pointer>``
Sean Silvab084af42012-12-07 10:36:55 +00006773operand must be a pointer to the :ref:`first class <t_firstclass>` type of
Eli Benderskyca380842013-04-17 17:17:20 +00006774the ``<value>`` operand. If the ``store`` is marked as ``volatile``,
Sean Silvab084af42012-12-07 10:36:55 +00006775then the optimizer is not allowed to modify the number or order of
6776execution of this ``store`` with other :ref:`volatile
6777operations <volatile>`.
6778
6779If the ``store`` is marked as ``atomic``, it takes an extra
6780:ref:`ordering <ordering>` and optional ``singlethread`` argument. The
6781``acquire`` and ``acq_rel`` orderings aren't valid on ``store``
6782instructions. Atomic loads produce :ref:`defined <memmodel>` results
6783when they may see multiple atomic stores. The type of the pointee must
6784be an integer type whose bit width is a power of two greater than or
6785equal to eight and less than or equal to a target-specific size limit.
6786``align`` must be explicitly specified on atomic stores, and the store
6787has undefined behavior if the alignment is not set to a value which is
6788at least the size in bytes of the pointee. ``!nontemporal`` does not
6789have any defined semantics for atomic stores.
6790
Eli Benderskyca380842013-04-17 17:17:20 +00006791The optional constant ``align`` argument specifies the alignment of the
Sean Silvab084af42012-12-07 10:36:55 +00006792operation (that is, the alignment of the memory address). A value of 0
Eli Benderskyca380842013-04-17 17:17:20 +00006793or an omitted ``align`` argument means that the operation has the ABI
Sean Silvab084af42012-12-07 10:36:55 +00006794alignment for the target. It is the responsibility of the code emitter
6795to ensure that the alignment information is correct. Overestimating the
Eli Benderskyca380842013-04-17 17:17:20 +00006796alignment results in undefined behavior. Underestimating the
Sean Silvab084af42012-12-07 10:36:55 +00006797alignment may produce less efficient code. An alignment of 1 is always
Reid Kleckner15fe7a52014-07-15 01:16:09 +00006798safe. The maximum possible alignment is ``1 << 29``.
Sean Silvab084af42012-12-07 10:36:55 +00006799
Stefanus Du Toit736e2e22013-06-20 14:02:44 +00006800The optional ``!nontemporal`` metadata must reference a single metadata
Eli Benderskyca380842013-04-17 17:17:20 +00006801name ``<index>`` corresponding to a metadata node with one ``i32`` entry of
Stefanus Du Toit736e2e22013-06-20 14:02:44 +00006802value 1. The existence of the ``!nontemporal`` metadata on the instruction
Sean Silvab084af42012-12-07 10:36:55 +00006803tells the optimizer and code generator that this load is not expected to
6804be reused in the cache. The code generator may select special
6805instructions to save cache bandwidth, such as the MOVNT instruction on
6806x86.
6807
6808Semantics:
6809""""""""""
6810
Eli Benderskyca380842013-04-17 17:17:20 +00006811The contents of memory are updated to contain ``<value>`` at the
6812location specified by the ``<pointer>`` operand. If ``<value>`` is
Sean Silvab084af42012-12-07 10:36:55 +00006813of scalar type then the number of bytes written does not exceed the
6814minimum number of bytes needed to hold all bits of the type. For
6815example, storing an ``i24`` writes at most three bytes. When writing a
6816value of a type like ``i20`` with a size that is not an integral number
6817of bytes, it is unspecified what happens to the extra bits that do not
6818belong to the type, but they will typically be overwritten.
6819
6820Example:
6821""""""""
6822
6823.. code-block:: llvm
6824
Tim Northover675a0962014-06-13 14:24:23 +00006825 %ptr = alloca i32 ; yields i32*:ptr
6826 store i32 3, i32* %ptr ; yields void
Nick Lewycky149d04c2015-08-11 01:05:16 +00006827 %val = load i32, i32* %ptr ; yields i32:val = i32 3
Sean Silvab084af42012-12-07 10:36:55 +00006828
6829.. _i_fence:
6830
6831'``fence``' Instruction
6832^^^^^^^^^^^^^^^^^^^^^^^
6833
6834Syntax:
6835"""""""
6836
6837::
6838
Tim Northover675a0962014-06-13 14:24:23 +00006839 fence [singlethread] <ordering> ; yields void
Sean Silvab084af42012-12-07 10:36:55 +00006840
6841Overview:
6842"""""""""
6843
6844The '``fence``' instruction is used to introduce happens-before edges
6845between operations.
6846
6847Arguments:
6848""""""""""
6849
6850'``fence``' instructions take an :ref:`ordering <ordering>` argument which
6851defines what *synchronizes-with* edges they add. They can only be given
6852``acquire``, ``release``, ``acq_rel``, and ``seq_cst`` orderings.
6853
6854Semantics:
6855""""""""""
6856
6857A fence A which has (at least) ``release`` ordering semantics
6858*synchronizes with* a fence B with (at least) ``acquire`` ordering
6859semantics if and only if there exist atomic operations X and Y, both
6860operating on some atomic object M, such that A is sequenced before X, X
6861modifies M (either directly or through some side effect of a sequence
6862headed by X), Y is sequenced before B, and Y observes M. This provides a
6863*happens-before* dependency between A and B. Rather than an explicit
6864``fence``, one (but not both) of the atomic operations X or Y might
6865provide a ``release`` or ``acquire`` (resp.) ordering constraint and
6866still *synchronize-with* the explicit ``fence`` and establish the
6867*happens-before* edge.
6868
6869A ``fence`` which has ``seq_cst`` ordering, in addition to having both
6870``acquire`` and ``release`` semantics specified above, participates in
6871the global program order of other ``seq_cst`` operations and/or fences.
6872
6873The optional ":ref:`singlethread <singlethread>`" argument specifies
6874that the fence only synchronizes with other fences in the same thread.
6875(This is useful for interacting with signal handlers.)
6876
6877Example:
6878""""""""
6879
6880.. code-block:: llvm
6881
Tim Northover675a0962014-06-13 14:24:23 +00006882 fence acquire ; yields void
6883 fence singlethread seq_cst ; yields void
Sean Silvab084af42012-12-07 10:36:55 +00006884
6885.. _i_cmpxchg:
6886
6887'``cmpxchg``' Instruction
6888^^^^^^^^^^^^^^^^^^^^^^^^^
6889
6890Syntax:
6891"""""""
6892
6893::
6894
Tim Northover675a0962014-06-13 14:24:23 +00006895 cmpxchg [weak] [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <success ordering> <failure ordering> ; yields { ty, i1 }
Sean Silvab084af42012-12-07 10:36:55 +00006896
6897Overview:
6898"""""""""
6899
6900The '``cmpxchg``' instruction is used to atomically modify memory. It
6901loads a value in memory and compares it to a given value. If they are
Tim Northover420a2162014-06-13 14:24:07 +00006902equal, it tries to store a new value into the memory.
Sean Silvab084af42012-12-07 10:36:55 +00006903
6904Arguments:
6905""""""""""
6906
6907There are three arguments to the '``cmpxchg``' instruction: an address
6908to operate on, a value to compare to the value currently be at that
6909address, and a new value to place at that address if the compared values
6910are equal. The type of '<cmp>' must be an integer type whose bit width
6911is a power of two greater than or equal to eight and less than or equal
6912to a target-specific size limit. '<cmp>' and '<new>' must have the same
6913type, and the type of '<pointer>' must be a pointer to that type. If the
6914``cmpxchg`` is marked as ``volatile``, then the optimizer is not allowed
6915to modify the number or order of execution of this ``cmpxchg`` with
6916other :ref:`volatile operations <volatile>`.
6917
Tim Northovere94a5182014-03-11 10:48:52 +00006918The success and failure :ref:`ordering <ordering>` arguments specify how this
Tim Northover1dcc9f92014-06-13 14:24:16 +00006919``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters
6920must be at least ``monotonic``, the ordering constraint on failure must be no
6921stronger than that on success, and the failure ordering cannot be either
6922``release`` or ``acq_rel``.
Sean Silvab084af42012-12-07 10:36:55 +00006923
6924The optional "``singlethread``" argument declares that the ``cmpxchg``
6925is only atomic with respect to code (usually signal handlers) running in
6926the same thread as the ``cmpxchg``. Otherwise the cmpxchg is atomic with
6927respect to all other code in the system.
6928
6929The pointer passed into cmpxchg must have alignment greater than or
6930equal to the size in memory of the operand.
6931
6932Semantics:
6933""""""""""
6934
Tim Northover420a2162014-06-13 14:24:07 +00006935The contents of memory at the location specified by the '``<pointer>``' operand
6936is read and compared to '``<cmp>``'; if the read value is the equal, the
6937'``<new>``' is written. The original value at the location is returned, together
6938with a flag indicating success (true) or failure (false).
6939
6940If the cmpxchg operation is marked as ``weak`` then a spurious failure is
6941permitted: the operation may not write ``<new>`` even if the comparison
6942matched.
6943
6944If the cmpxchg operation is strong (the default), the i1 value is 1 if and only
6945if the value loaded equals ``cmp``.
Sean Silvab084af42012-12-07 10:36:55 +00006946
Tim Northovere94a5182014-03-11 10:48:52 +00006947A successful ``cmpxchg`` is a read-modify-write instruction for the purpose of
6948identifying release sequences. A failed ``cmpxchg`` is equivalent to an atomic
6949load with an ordering parameter determined the second ordering parameter.
Sean Silvab084af42012-12-07 10:36:55 +00006950
6951Example:
6952""""""""
6953
6954.. code-block:: llvm
6955
6956 entry:
David Blaikiec7aabbb2015-03-04 22:06:14 +00006957 %orig = atomic load i32, i32* %ptr unordered ; yields i32
Sean Silvab084af42012-12-07 10:36:55 +00006958 br label %loop
6959
6960 loop:
6961 %cmp = phi i32 [ %orig, %entry ], [%old, %loop]
6962 %squared = mul i32 %cmp, %cmp
Tim Northover675a0962014-06-13 14:24:23 +00006963 %val_success = cmpxchg i32* %ptr, i32 %cmp, i32 %squared acq_rel monotonic ; yields { i32, i1 }
Tim Northover420a2162014-06-13 14:24:07 +00006964 %value_loaded = extractvalue { i32, i1 } %val_success, 0
6965 %success = extractvalue { i32, i1 } %val_success, 1
Sean Silvab084af42012-12-07 10:36:55 +00006966 br i1 %success, label %done, label %loop
6967
6968 done:
6969 ...
6970
6971.. _i_atomicrmw:
6972
6973'``atomicrmw``' Instruction
6974^^^^^^^^^^^^^^^^^^^^^^^^^^^
6975
6976Syntax:
6977"""""""
6978
6979::
6980
Tim Northover675a0962014-06-13 14:24:23 +00006981 atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> ; yields ty
Sean Silvab084af42012-12-07 10:36:55 +00006982
6983Overview:
6984"""""""""
6985
6986The '``atomicrmw``' instruction is used to atomically modify memory.
6987
6988Arguments:
6989""""""""""
6990
6991There are three arguments to the '``atomicrmw``' instruction: an
6992operation to apply, an address whose value to modify, an argument to the
6993operation. The operation must be one of the following keywords:
6994
6995- xchg
6996- add
6997- sub
6998- and
6999- nand
7000- or
7001- xor
7002- max
7003- min
7004- umax
7005- umin
7006
7007The type of '<value>' must be an integer type whose bit width is a power
7008of two greater than or equal to eight and less than or equal to a
7009target-specific size limit. The type of the '``<pointer>``' operand must
7010be a pointer to that type. If the ``atomicrmw`` is marked as
7011``volatile``, then the optimizer is not allowed to modify the number or
7012order of execution of this ``atomicrmw`` with other :ref:`volatile
7013operations <volatile>`.
7014
7015Semantics:
7016""""""""""
7017
7018The contents of memory at the location specified by the '``<pointer>``'
7019operand are atomically read, modified, and written back. The original
7020value at the location is returned. The modification is specified by the
7021operation argument:
7022
7023- xchg: ``*ptr = val``
7024- add: ``*ptr = *ptr + val``
7025- sub: ``*ptr = *ptr - val``
7026- and: ``*ptr = *ptr & val``
7027- nand: ``*ptr = ~(*ptr & val)``
7028- or: ``*ptr = *ptr | val``
7029- xor: ``*ptr = *ptr ^ val``
7030- max: ``*ptr = *ptr > val ? *ptr : val`` (using a signed comparison)
7031- min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison)
7032- umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned
7033 comparison)
7034- umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned
7035 comparison)
7036
7037Example:
7038""""""""
7039
7040.. code-block:: llvm
7041
Tim Northover675a0962014-06-13 14:24:23 +00007042 %old = atomicrmw add i32* %ptr, i32 1 acquire ; yields i32
Sean Silvab084af42012-12-07 10:36:55 +00007043
7044.. _i_getelementptr:
7045
7046'``getelementptr``' Instruction
7047^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7048
7049Syntax:
7050"""""""
7051
7052::
7053
David Blaikie16a97eb2015-03-04 22:02:58 +00007054 <result> = getelementptr <ty>, <ty>* <ptrval>{, <ty> <idx>}*
7055 <result> = getelementptr inbounds <ty>, <ty>* <ptrval>{, <ty> <idx>}*
7056 <result> = getelementptr <ty>, <ptr vector> <ptrval>, <vector index type> <idx>
Sean Silvab084af42012-12-07 10:36:55 +00007057
7058Overview:
7059"""""""""
7060
7061The '``getelementptr``' instruction is used to get the address of a
7062subelement of an :ref:`aggregate <t_aggregate>` data structure. It performs
Elena Demikhovsky37a4da82015-07-09 07:42:48 +00007063address calculation only and does not access memory. The instruction can also
7064be used to calculate a vector of such addresses.
Sean Silvab084af42012-12-07 10:36:55 +00007065
7066Arguments:
7067""""""""""
7068
David Blaikie16a97eb2015-03-04 22:02:58 +00007069The first argument is always a type used as the basis for the calculations.
7070The second argument is always a pointer or a vector of pointers, and is the
7071base address to start from. The remaining arguments are indices
Sean Silvab084af42012-12-07 10:36:55 +00007072that indicate which of the elements of the aggregate object are indexed.
7073The interpretation of each index is dependent on the type being indexed
7074into. The first index always indexes the pointer value given as the
7075first argument, the second index indexes a value of the type pointed to
7076(not necessarily the value directly pointed to, since the first index
7077can be non-zero), etc. The first type indexed into must be a pointer
7078value, subsequent types can be arrays, vectors, and structs. Note that
7079subsequent types being indexed into can never be pointers, since that
7080would require loading the pointer before continuing calculation.
7081
7082The type of each index argument depends on the type it is indexing into.
7083When indexing into a (optionally packed) structure, only ``i32`` integer
7084**constants** are allowed (when using a vector of indices they must all
7085be the **same** ``i32`` integer constant). When indexing into an array,
7086pointer or vector, integers of any width are allowed, and they are not
7087required to be constant. These integers are treated as signed values
7088where relevant.
7089
7090For example, let's consider a C code fragment and how it gets compiled
7091to LLVM:
7092
7093.. code-block:: c
7094
7095 struct RT {
7096 char A;
7097 int B[10][20];
7098 char C;
7099 };
7100 struct ST {
7101 int X;
7102 double Y;
7103 struct RT Z;
7104 };
7105
7106 int *foo(struct ST *s) {
7107 return &s[1].Z.B[5][13];
7108 }
7109
7110The LLVM code generated by Clang is:
7111
7112.. code-block:: llvm
7113
7114 %struct.RT = type { i8, [10 x [20 x i32]], i8 }
7115 %struct.ST = type { i32, double, %struct.RT }
7116
7117 define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp {
7118 entry:
David Blaikie16a97eb2015-03-04 22:02:58 +00007119 %arrayidx = getelementptr inbounds %struct.ST, %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13
Sean Silvab084af42012-12-07 10:36:55 +00007120 ret i32* %arrayidx
7121 }
7122
7123Semantics:
7124""""""""""
7125
7126In the example above, the first index is indexing into the
7127'``%struct.ST*``' type, which is a pointer, yielding a '``%struct.ST``'
7128= '``{ i32, double, %struct.RT }``' type, a structure. The second index
7129indexes into the third element of the structure, yielding a
7130'``%struct.RT``' = '``{ i8 , [10 x [20 x i32]], i8 }``' type, another
7131structure. The third index indexes into the second element of the
7132structure, yielding a '``[10 x [20 x i32]]``' type, an array. The two
7133dimensions of the array are subscripted into, yielding an '``i32``'
7134type. The '``getelementptr``' instruction returns a pointer to this
7135element, thus computing a value of '``i32*``' type.
7136
7137Note that it is perfectly legal to index partially through a structure,
7138returning a pointer to an inner element. Because of this, the LLVM code
7139for the given testcase is equivalent to:
7140
7141.. code-block:: llvm
7142
7143 define i32* @foo(%struct.ST* %s) {
David Blaikie16a97eb2015-03-04 22:02:58 +00007144 %t1 = getelementptr %struct.ST, %struct.ST* %s, i32 1 ; yields %struct.ST*:%t1
7145 %t2 = getelementptr %struct.ST, %struct.ST* %t1, i32 0, i32 2 ; yields %struct.RT*:%t2
7146 %t3 = getelementptr %struct.RT, %struct.RT* %t2, i32 0, i32 1 ; yields [10 x [20 x i32]]*:%t3
7147 %t4 = getelementptr [10 x [20 x i32]], [10 x [20 x i32]]* %t3, i32 0, i32 5 ; yields [20 x i32]*:%t4
7148 %t5 = getelementptr [20 x i32], [20 x i32]* %t4, i32 0, i32 13 ; yields i32*:%t5
Sean Silvab084af42012-12-07 10:36:55 +00007149 ret i32* %t5
7150 }
7151
7152If the ``inbounds`` keyword is present, the result value of the
7153``getelementptr`` is a :ref:`poison value <poisonvalues>` if the base
7154pointer is not an *in bounds* address of an allocated object, or if any
7155of the addresses that would be formed by successive addition of the
7156offsets implied by the indices to the base address with infinitely
7157precise signed arithmetic are not an *in bounds* address of that
7158allocated object. The *in bounds* addresses for an allocated object are
7159all the addresses that point into the object, plus the address one byte
7160past the end. In cases where the base is a vector of pointers the
7161``inbounds`` keyword applies to each of the computations element-wise.
7162
7163If the ``inbounds`` keyword is not present, the offsets are added to the
7164base address with silently-wrapping two's complement arithmetic. If the
7165offsets have a different width from the pointer, they are sign-extended
7166or truncated to the width of the pointer. The result value of the
7167``getelementptr`` may be outside the object pointed to by the base
7168pointer. The result value may not necessarily be used to access memory
7169though, even if it happens to point into allocated storage. See the
7170:ref:`Pointer Aliasing Rules <pointeraliasing>` section for more
7171information.
7172
7173The getelementptr instruction is often confusing. For some more insight
7174into how it works, see :doc:`the getelementptr FAQ <GetElementPtr>`.
7175
7176Example:
7177""""""""
7178
7179.. code-block:: llvm
7180
7181 ; yields [12 x i8]*:aptr
David Blaikie16a97eb2015-03-04 22:02:58 +00007182 %aptr = getelementptr {i32, [12 x i8]}, {i32, [12 x i8]}* %saptr, i64 0, i32 1
Sean Silvab084af42012-12-07 10:36:55 +00007183 ; yields i8*:vptr
David Blaikie16a97eb2015-03-04 22:02:58 +00007184 %vptr = getelementptr {i32, <2 x i8>}, {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1
Sean Silvab084af42012-12-07 10:36:55 +00007185 ; yields i8*:eptr
David Blaikie16a97eb2015-03-04 22:02:58 +00007186 %eptr = getelementptr [12 x i8], [12 x i8]* %aptr, i64 0, i32 1
Sean Silvab084af42012-12-07 10:36:55 +00007187 ; yields i32*:iptr
David Blaikie16a97eb2015-03-04 22:02:58 +00007188 %iptr = getelementptr [10 x i32], [10 x i32]* @arr, i16 0, i16 0
Sean Silvab084af42012-12-07 10:36:55 +00007189
Elena Demikhovsky37a4da82015-07-09 07:42:48 +00007190Vector of pointers:
7191"""""""""""""""""""
7192
7193The ``getelementptr`` returns a vector of pointers, instead of a single address,
7194when one or more of its arguments is a vector. In such cases, all vector
7195arguments should have the same number of elements, and every scalar argument
7196will be effectively broadcast into a vector during address calculation.
Sean Silvab084af42012-12-07 10:36:55 +00007197
7198.. code-block:: llvm
7199
Elena Demikhovsky37a4da82015-07-09 07:42:48 +00007200 ; All arguments are vectors:
7201 ; A[i] = ptrs[i] + offsets[i]*sizeof(i8)
7202 %A = getelementptr i8, <4 x i8*> %ptrs, <4 x i64> %offsets
Sean Silva706fba52015-08-06 22:56:24 +00007203
Elena Demikhovsky37a4da82015-07-09 07:42:48 +00007204 ; Add the same scalar offset to each pointer of a vector:
7205 ; A[i] = ptrs[i] + offset*sizeof(i8)
7206 %A = getelementptr i8, <4 x i8*> %ptrs, i64 %offset
Sean Silva706fba52015-08-06 22:56:24 +00007207
Elena Demikhovsky37a4da82015-07-09 07:42:48 +00007208 ; Add distinct offsets to the same pointer:
7209 ; A[i] = ptr + offsets[i]*sizeof(i8)
7210 %A = getelementptr i8, i8* %ptr, <4 x i64> %offsets
Sean Silva706fba52015-08-06 22:56:24 +00007211
Elena Demikhovsky37a4da82015-07-09 07:42:48 +00007212 ; In all cases described above the type of the result is <4 x i8*>
7213
7214The two following instructions are equivalent:
7215
7216.. code-block:: llvm
7217
7218 getelementptr %struct.ST, <4 x %struct.ST*> %s, <4 x i64> %ind1,
7219 <4 x i32> <i32 2, i32 2, i32 2, i32 2>,
7220 <4 x i32> <i32 1, i32 1, i32 1, i32 1>,
7221 <4 x i32> %ind4,
7222 <4 x i64> <i64 13, i64 13, i64 13, i64 13>
Sean Silva706fba52015-08-06 22:56:24 +00007223
Elena Demikhovsky37a4da82015-07-09 07:42:48 +00007224 getelementptr %struct.ST, <4 x %struct.ST*> %s, <4 x i64> %ind1,
7225 i32 2, i32 1, <4 x i32> %ind4, i64 13
7226
7227Let's look at the C code, where the vector version of ``getelementptr``
7228makes sense:
7229
7230.. code-block:: c
7231
7232 // Let's assume that we vectorize the following loop:
7233 double *A, B; int *C;
7234 for (int i = 0; i < size; ++i) {
7235 A[i] = B[C[i]];
7236 }
7237
7238.. code-block:: llvm
7239
7240 ; get pointers for 8 elements from array B
7241 %ptrs = getelementptr double, double* %B, <8 x i32> %C
7242 ; load 8 elements from array B into A
7243 %A = call <8 x double> @llvm.masked.gather.v8f64(<8 x double*> %ptrs,
7244 i32 8, <8 x i1> %mask, <8 x double> %passthru)
Sean Silvab084af42012-12-07 10:36:55 +00007245
7246Conversion Operations
7247---------------------
7248
7249The instructions in this category are the conversion instructions
7250(casting) which all take a single operand and a type. They perform
7251various bit conversions on the operand.
7252
7253'``trunc .. to``' Instruction
7254^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7255
7256Syntax:
7257"""""""
7258
7259::
7260
7261 <result> = trunc <ty> <value> to <ty2> ; yields ty2
7262
7263Overview:
7264"""""""""
7265
7266The '``trunc``' instruction truncates its operand to the type ``ty2``.
7267
7268Arguments:
7269""""""""""
7270
7271The '``trunc``' instruction takes a value to trunc, and a type to trunc
7272it to. Both types must be of :ref:`integer <t_integer>` types, or vectors
7273of the same number of integers. The bit size of the ``value`` must be
7274larger than the bit size of the destination type, ``ty2``. Equal sized
7275types are not allowed.
7276
7277Semantics:
7278""""""""""
7279
7280The '``trunc``' instruction truncates the high order bits in ``value``
7281and converts the remaining bits to ``ty2``. Since the source size must
7282be larger than the destination size, ``trunc`` cannot be a *no-op cast*.
7283It will always truncate bits.
7284
7285Example:
7286""""""""
7287
7288.. code-block:: llvm
7289
7290 %X = trunc i32 257 to i8 ; yields i8:1
7291 %Y = trunc i32 123 to i1 ; yields i1:true
7292 %Z = trunc i32 122 to i1 ; yields i1:false
7293 %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7>
7294
7295'``zext .. to``' Instruction
7296^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7297
7298Syntax:
7299"""""""
7300
7301::
7302
7303 <result> = zext <ty> <value> to <ty2> ; yields ty2
7304
7305Overview:
7306"""""""""
7307
7308The '``zext``' instruction zero extends its operand to type ``ty2``.
7309
7310Arguments:
7311""""""""""
7312
7313The '``zext``' instruction takes a value to cast, and a type to cast it
7314to. Both types must be of :ref:`integer <t_integer>` types, or vectors of
7315the same number of integers. The bit size of the ``value`` must be
7316smaller than the bit size of the destination type, ``ty2``.
7317
7318Semantics:
7319""""""""""
7320
7321The ``zext`` fills the high order bits of the ``value`` with zero bits
7322until it reaches the size of the destination type, ``ty2``.
7323
7324When zero extending from i1, the result will always be either 0 or 1.
7325
7326Example:
7327""""""""
7328
7329.. code-block:: llvm
7330
7331 %X = zext i32 257 to i64 ; yields i64:257
7332 %Y = zext i1 true to i32 ; yields i32:1
7333 %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
7334
7335'``sext .. to``' Instruction
7336^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7337
7338Syntax:
7339"""""""
7340
7341::
7342
7343 <result> = sext <ty> <value> to <ty2> ; yields ty2
7344
7345Overview:
7346"""""""""
7347
7348The '``sext``' sign extends ``value`` to the type ``ty2``.
7349
7350Arguments:
7351""""""""""
7352
7353The '``sext``' instruction takes a value to cast, and a type to cast it
7354to. Both types must be of :ref:`integer <t_integer>` types, or vectors of
7355the same number of integers. The bit size of the ``value`` must be
7356smaller than the bit size of the destination type, ``ty2``.
7357
7358Semantics:
7359""""""""""
7360
7361The '``sext``' instruction performs a sign extension by copying the sign
7362bit (highest order bit) of the ``value`` until it reaches the bit size
7363of the type ``ty2``.
7364
7365When sign extending from i1, the extension always results in -1 or 0.
7366
7367Example:
7368""""""""
7369
7370.. code-block:: llvm
7371
7372 %X = sext i8 -1 to i16 ; yields i16 :65535
7373 %Y = sext i1 true to i32 ; yields i32:-1
7374 %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
7375
7376'``fptrunc .. to``' Instruction
7377^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7378
7379Syntax:
7380"""""""
7381
7382::
7383
7384 <result> = fptrunc <ty> <value> to <ty2> ; yields ty2
7385
7386Overview:
7387"""""""""
7388
7389The '``fptrunc``' instruction truncates ``value`` to type ``ty2``.
7390
7391Arguments:
7392""""""""""
7393
7394The '``fptrunc``' instruction takes a :ref:`floating point <t_floating>`
7395value to cast and a :ref:`floating point <t_floating>` type to cast it to.
7396The size of ``value`` must be larger than the size of ``ty2``. This
7397implies that ``fptrunc`` cannot be used to make a *no-op cast*.
7398
7399Semantics:
7400""""""""""
7401
7402The '``fptrunc``' instruction truncates a ``value`` from a larger
7403:ref:`floating point <t_floating>` type to a smaller :ref:`floating
7404point <t_floating>` type. If the value cannot fit within the
7405destination type, ``ty2``, then the results are undefined.
7406
7407Example:
7408""""""""
7409
7410.. code-block:: llvm
7411
7412 %X = fptrunc double 123.0 to float ; yields float:123.0
7413 %Y = fptrunc double 1.0E+300 to float ; yields undefined
7414
7415'``fpext .. to``' Instruction
7416^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7417
7418Syntax:
7419"""""""
7420
7421::
7422
7423 <result> = fpext <ty> <value> to <ty2> ; yields ty2
7424
7425Overview:
7426"""""""""
7427
7428The '``fpext``' extends a floating point ``value`` to a larger floating
7429point value.
7430
7431Arguments:
7432""""""""""
7433
7434The '``fpext``' instruction takes a :ref:`floating point <t_floating>`
7435``value`` to cast, and a :ref:`floating point <t_floating>` type to cast it
7436to. The source type must be smaller than the destination type.
7437
7438Semantics:
7439""""""""""
7440
7441The '``fpext``' instruction extends the ``value`` from a smaller
7442:ref:`floating point <t_floating>` type to a larger :ref:`floating
7443point <t_floating>` type. The ``fpext`` cannot be used to make a
7444*no-op cast* because it always changes bits. Use ``bitcast`` to make a
7445*no-op cast* for a floating point cast.
7446
7447Example:
7448""""""""
7449
7450.. code-block:: llvm
7451
7452 %X = fpext float 3.125 to double ; yields double:3.125000e+00
7453 %Y = fpext double %X to fp128 ; yields fp128:0xL00000000000000004000900000000000
7454
7455'``fptoui .. to``' Instruction
7456^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7457
7458Syntax:
7459"""""""
7460
7461::
7462
7463 <result> = fptoui <ty> <value> to <ty2> ; yields ty2
7464
7465Overview:
7466"""""""""
7467
7468The '``fptoui``' converts a floating point ``value`` to its unsigned
7469integer equivalent of type ``ty2``.
7470
7471Arguments:
7472""""""""""
7473
7474The '``fptoui``' instruction takes a value to cast, which must be a
7475scalar or vector :ref:`floating point <t_floating>` value, and a type to
7476cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
7477``ty`` is a vector floating point type, ``ty2`` must be a vector integer
7478type with the same number of elements as ``ty``
7479
7480Semantics:
7481""""""""""
7482
7483The '``fptoui``' instruction converts its :ref:`floating
7484point <t_floating>` operand into the nearest (rounding towards zero)
7485unsigned integer value. If the value cannot fit in ``ty2``, the results
7486are undefined.
7487
7488Example:
7489""""""""
7490
7491.. code-block:: llvm
7492
7493 %X = fptoui double 123.0 to i32 ; yields i32:123
7494 %Y = fptoui float 1.0E+300 to i1 ; yields undefined:1
7495 %Z = fptoui float 1.04E+17 to i8 ; yields undefined:1
7496
7497'``fptosi .. to``' Instruction
7498^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7499
7500Syntax:
7501"""""""
7502
7503::
7504
7505 <result> = fptosi <ty> <value> to <ty2> ; yields ty2
7506
7507Overview:
7508"""""""""
7509
7510The '``fptosi``' instruction converts :ref:`floating point <t_floating>`
7511``value`` to type ``ty2``.
7512
7513Arguments:
7514""""""""""
7515
7516The '``fptosi``' instruction takes a value to cast, which must be a
7517scalar or vector :ref:`floating point <t_floating>` value, and a type to
7518cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
7519``ty`` is a vector floating point type, ``ty2`` must be a vector integer
7520type with the same number of elements as ``ty``
7521
7522Semantics:
7523""""""""""
7524
7525The '``fptosi``' instruction converts its :ref:`floating
7526point <t_floating>` operand into the nearest (rounding towards zero)
7527signed integer value. If the value cannot fit in ``ty2``, the results
7528are undefined.
7529
7530Example:
7531""""""""
7532
7533.. code-block:: llvm
7534
7535 %X = fptosi double -123.0 to i32 ; yields i32:-123
7536 %Y = fptosi float 1.0E-247 to i1 ; yields undefined:1
7537 %Z = fptosi float 1.04E+17 to i8 ; yields undefined:1
7538
7539'``uitofp .. to``' Instruction
7540^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7541
7542Syntax:
7543"""""""
7544
7545::
7546
7547 <result> = uitofp <ty> <value> to <ty2> ; yields ty2
7548
7549Overview:
7550"""""""""
7551
7552The '``uitofp``' instruction regards ``value`` as an unsigned integer
7553and converts that value to the ``ty2`` type.
7554
7555Arguments:
7556""""""""""
7557
7558The '``uitofp``' instruction takes a value to cast, which must be a
7559scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
7560``ty2``, which must be an :ref:`floating point <t_floating>` type. If
7561``ty`` is a vector integer type, ``ty2`` must be a vector floating point
7562type with the same number of elements as ``ty``
7563
7564Semantics:
7565""""""""""
7566
7567The '``uitofp``' instruction interprets its operand as an unsigned
7568integer quantity and converts it to the corresponding floating point
7569value. If the value cannot fit in the floating point value, the results
7570are undefined.
7571
7572Example:
7573""""""""
7574
7575.. code-block:: llvm
7576
7577 %X = uitofp i32 257 to float ; yields float:257.0
7578 %Y = uitofp i8 -1 to double ; yields double:255.0
7579
7580'``sitofp .. to``' Instruction
7581^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7582
7583Syntax:
7584"""""""
7585
7586::
7587
7588 <result> = sitofp <ty> <value> to <ty2> ; yields ty2
7589
7590Overview:
7591"""""""""
7592
7593The '``sitofp``' instruction regards ``value`` as a signed integer and
7594converts that value to the ``ty2`` type.
7595
7596Arguments:
7597""""""""""
7598
7599The '``sitofp``' instruction takes a value to cast, which must be a
7600scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
7601``ty2``, which must be an :ref:`floating point <t_floating>` type. If
7602``ty`` is a vector integer type, ``ty2`` must be a vector floating point
7603type with the same number of elements as ``ty``
7604
7605Semantics:
7606""""""""""
7607
7608The '``sitofp``' instruction interprets its operand as a signed integer
7609quantity and converts it to the corresponding floating point value. If
7610the value cannot fit in the floating point value, the results are
7611undefined.
7612
7613Example:
7614""""""""
7615
7616.. code-block:: llvm
7617
7618 %X = sitofp i32 257 to float ; yields float:257.0
7619 %Y = sitofp i8 -1 to double ; yields double:-1.0
7620
7621.. _i_ptrtoint:
7622
7623'``ptrtoint .. to``' Instruction
7624^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7625
7626Syntax:
7627"""""""
7628
7629::
7630
7631 <result> = ptrtoint <ty> <value> to <ty2> ; yields ty2
7632
7633Overview:
7634"""""""""
7635
7636The '``ptrtoint``' instruction converts the pointer or a vector of
7637pointers ``value`` to the integer (or vector of integers) type ``ty2``.
7638
7639Arguments:
7640""""""""""
7641
7642The '``ptrtoint``' instruction takes a ``value`` to cast, which must be
Ed Maste8ed40ce2015-04-14 20:52:58 +00007643a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a
Sean Silvab084af42012-12-07 10:36:55 +00007644type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or
7645a vector of integers type.
7646
7647Semantics:
7648""""""""""
7649
7650The '``ptrtoint``' instruction converts ``value`` to integer type
7651``ty2`` by interpreting the pointer value as an integer and either
7652truncating or zero extending that value to the size of the integer type.
7653If ``value`` is smaller than ``ty2`` then a zero extension is done. If
7654``value`` is larger than ``ty2`` then a truncation is done. If they are
7655the same size, then nothing is done (*no-op cast*) other than a type
7656change.
7657
7658Example:
7659""""""""
7660
7661.. code-block:: llvm
7662
7663 %X = ptrtoint i32* %P to i8 ; yields truncation on 32-bit architecture
7664 %Y = ptrtoint i32* %P to i64 ; yields zero extension on 32-bit architecture
7665 %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture
7666
7667.. _i_inttoptr:
7668
7669'``inttoptr .. to``' Instruction
7670^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7671
7672Syntax:
7673"""""""
7674
7675::
7676
7677 <result> = inttoptr <ty> <value> to <ty2> ; yields ty2
7678
7679Overview:
7680"""""""""
7681
7682The '``inttoptr``' instruction converts an integer ``value`` to a
7683pointer type, ``ty2``.
7684
7685Arguments:
7686""""""""""
7687
7688The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to
7689cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>`
7690type.
7691
7692Semantics:
7693""""""""""
7694
7695The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by
7696applying either a zero extension or a truncation depending on the size
7697of the integer ``value``. If ``value`` is larger than the size of a
7698pointer then a truncation is done. If ``value`` is smaller than the size
7699of a pointer then a zero extension is done. If they are the same size,
7700nothing is done (*no-op cast*).
7701
7702Example:
7703""""""""
7704
7705.. code-block:: llvm
7706
7707 %X = inttoptr i32 255 to i32* ; yields zero extension on 64-bit architecture
7708 %Y = inttoptr i32 255 to i32* ; yields no-op on 32-bit architecture
7709 %Z = inttoptr i64 0 to i32* ; yields truncation on 32-bit architecture
7710 %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers
7711
7712.. _i_bitcast:
7713
7714'``bitcast .. to``' Instruction
7715^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7716
7717Syntax:
7718"""""""
7719
7720::
7721
7722 <result> = bitcast <ty> <value> to <ty2> ; yields ty2
7723
7724Overview:
7725"""""""""
7726
7727The '``bitcast``' instruction converts ``value`` to type ``ty2`` without
7728changing any bits.
7729
7730Arguments:
7731""""""""""
7732
7733The '``bitcast``' instruction takes a value to cast, which must be a
7734non-aggregate first class value, and a type to cast it to, which must
Matt Arsenault24b49c42013-07-31 17:49:08 +00007735also be a non-aggregate :ref:`first class <t_firstclass>` type. The
7736bit sizes of ``value`` and the destination type, ``ty2``, must be
Sean Silvaa1190322015-08-06 22:56:48 +00007737identical. If the source type is a pointer, the destination type must
Matt Arsenault24b49c42013-07-31 17:49:08 +00007738also be a pointer of the same size. This instruction supports bitwise
7739conversion of vectors to integers and to vectors of other types (as
7740long as they have the same size).
Sean Silvab084af42012-12-07 10:36:55 +00007741
7742Semantics:
7743""""""""""
7744
Matt Arsenault24b49c42013-07-31 17:49:08 +00007745The '``bitcast``' instruction converts ``value`` to type ``ty2``. It
7746is always a *no-op cast* because no bits change with this
7747conversion. The conversion is done as if the ``value`` had been stored
7748to memory and read back as type ``ty2``. Pointer (or vector of
7749pointers) types may only be converted to other pointer (or vector of
Matt Arsenaultb03bd4d2013-11-15 01:34:59 +00007750pointers) types with the same address space through this instruction.
7751To convert pointers to other types, use the :ref:`inttoptr <i_inttoptr>`
7752or :ref:`ptrtoint <i_ptrtoint>` instructions first.
Sean Silvab084af42012-12-07 10:36:55 +00007753
7754Example:
7755""""""""
7756
7757.. code-block:: llvm
7758
7759 %X = bitcast i8 255 to i8 ; yields i8 :-1
7760 %Y = bitcast i32* %x to sint* ; yields sint*:%x
7761 %Z = bitcast <2 x int> %V to i64; ; yields i64: %V
7762 %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
7763
Matt Arsenaultb03bd4d2013-11-15 01:34:59 +00007764.. _i_addrspacecast:
7765
7766'``addrspacecast .. to``' Instruction
7767^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7768
7769Syntax:
7770"""""""
7771
7772::
7773
7774 <result> = addrspacecast <pty> <ptrval> to <pty2> ; yields pty2
7775
7776Overview:
7777"""""""""
7778
7779The '``addrspacecast``' instruction converts ``ptrval`` from ``pty`` in
7780address space ``n`` to type ``pty2`` in address space ``m``.
7781
7782Arguments:
7783""""""""""
7784
7785The '``addrspacecast``' instruction takes a pointer or vector of pointer value
7786to cast and a pointer type to cast it to, which must have a different
7787address space.
7788
7789Semantics:
7790""""""""""
7791
7792The '``addrspacecast``' instruction converts the pointer value
7793``ptrval`` to type ``pty2``. It can be a *no-op cast* or a complex
Matt Arsenault54a2a172013-11-15 05:44:56 +00007794value modification, depending on the target and the address space
7795pair. Pointer conversions within the same address space must be
7796performed with the ``bitcast`` instruction. Note that if the address space
Matt Arsenaultb03bd4d2013-11-15 01:34:59 +00007797conversion is legal then both result and operand refer to the same memory
7798location.
7799
7800Example:
7801""""""""
7802
7803.. code-block:: llvm
7804
Matt Arsenault9c13dd02013-11-15 22:43:50 +00007805 %X = addrspacecast i32* %x to i32 addrspace(1)* ; yields i32 addrspace(1)*:%x
7806 %Y = addrspacecast i32 addrspace(1)* %y to i64 addrspace(2)* ; yields i64 addrspace(2)*:%y
7807 %Z = addrspacecast <4 x i32*> %z to <4 x float addrspace(3)*> ; yields <4 x float addrspace(3)*>:%z
Matt Arsenaultb03bd4d2013-11-15 01:34:59 +00007808
Sean Silvab084af42012-12-07 10:36:55 +00007809.. _otherops:
7810
7811Other Operations
7812----------------
7813
7814The instructions in this category are the "miscellaneous" instructions,
7815which defy better classification.
7816
7817.. _i_icmp:
7818
7819'``icmp``' Instruction
7820^^^^^^^^^^^^^^^^^^^^^^
7821
7822Syntax:
7823"""""""
7824
7825::
7826
Tim Northover675a0962014-06-13 14:24:23 +00007827 <result> = icmp <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result
Sean Silvab084af42012-12-07 10:36:55 +00007828
7829Overview:
7830"""""""""
7831
7832The '``icmp``' instruction returns a boolean value or a vector of
7833boolean values based on comparison of its two integer, integer vector,
7834pointer, or pointer vector operands.
7835
7836Arguments:
7837""""""""""
7838
7839The '``icmp``' instruction takes three operands. The first operand is
7840the condition code indicating the kind of comparison to perform. It is
7841not a value, just a keyword. The possible condition code are:
7842
7843#. ``eq``: equal
7844#. ``ne``: not equal
7845#. ``ugt``: unsigned greater than
7846#. ``uge``: unsigned greater or equal
7847#. ``ult``: unsigned less than
7848#. ``ule``: unsigned less or equal
7849#. ``sgt``: signed greater than
7850#. ``sge``: signed greater or equal
7851#. ``slt``: signed less than
7852#. ``sle``: signed less or equal
7853
7854The remaining two arguments must be :ref:`integer <t_integer>` or
7855:ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They
7856must also be identical types.
7857
7858Semantics:
7859""""""""""
7860
7861The '``icmp``' compares ``op1`` and ``op2`` according to the condition
7862code given as ``cond``. The comparison performed always yields either an
7863:ref:`i1 <t_integer>` or vector of ``i1`` result, as follows:
7864
7865#. ``eq``: yields ``true`` if the operands are equal, ``false``
7866 otherwise. No sign interpretation is necessary or performed.
7867#. ``ne``: yields ``true`` if the operands are unequal, ``false``
7868 otherwise. No sign interpretation is necessary or performed.
7869#. ``ugt``: interprets the operands as unsigned values and yields
7870 ``true`` if ``op1`` is greater than ``op2``.
7871#. ``uge``: interprets the operands as unsigned values and yields
7872 ``true`` if ``op1`` is greater than or equal to ``op2``.
7873#. ``ult``: interprets the operands as unsigned values and yields
7874 ``true`` if ``op1`` is less than ``op2``.
7875#. ``ule``: interprets the operands as unsigned values and yields
7876 ``true`` if ``op1`` is less than or equal to ``op2``.
7877#. ``sgt``: interprets the operands as signed values and yields ``true``
7878 if ``op1`` is greater than ``op2``.
7879#. ``sge``: interprets the operands as signed values and yields ``true``
7880 if ``op1`` is greater than or equal to ``op2``.
7881#. ``slt``: interprets the operands as signed values and yields ``true``
7882 if ``op1`` is less than ``op2``.
7883#. ``sle``: interprets the operands as signed values and yields ``true``
7884 if ``op1`` is less than or equal to ``op2``.
7885
7886If the operands are :ref:`pointer <t_pointer>` typed, the pointer values
7887are compared as if they were integers.
7888
7889If the operands are integer vectors, then they are compared element by
7890element. The result is an ``i1`` vector with the same number of elements
7891as the values being compared. Otherwise, the result is an ``i1``.
7892
7893Example:
7894""""""""
7895
7896.. code-block:: llvm
7897
7898 <result> = icmp eq i32 4, 5 ; yields: result=false
7899 <result> = icmp ne float* %X, %X ; yields: result=false
7900 <result> = icmp ult i16 4, 5 ; yields: result=true
7901 <result> = icmp sgt i16 4, 5 ; yields: result=false
7902 <result> = icmp ule i16 -4, 5 ; yields: result=false
7903 <result> = icmp sge i16 4, 5 ; yields: result=false
7904
7905Note that the code generator does not yet support vector types with the
7906``icmp`` instruction.
7907
7908.. _i_fcmp:
7909
7910'``fcmp``' Instruction
7911^^^^^^^^^^^^^^^^^^^^^^
7912
7913Syntax:
7914"""""""
7915
7916::
7917
James Molloy88eb5352015-07-10 12:52:00 +00007918 <result> = fcmp [fast-math flags]* <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result
Sean Silvab084af42012-12-07 10:36:55 +00007919
7920Overview:
7921"""""""""
7922
7923The '``fcmp``' instruction returns a boolean value or vector of boolean
7924values based on comparison of its operands.
7925
7926If the operands are floating point scalars, then the result type is a
7927boolean (:ref:`i1 <t_integer>`).
7928
7929If the operands are floating point vectors, then the result type is a
7930vector of boolean with the same number of elements as the operands being
7931compared.
7932
7933Arguments:
7934""""""""""
7935
7936The '``fcmp``' instruction takes three operands. The first operand is
7937the condition code indicating the kind of comparison to perform. It is
7938not a value, just a keyword. The possible condition code are:
7939
7940#. ``false``: no comparison, always returns false
7941#. ``oeq``: ordered and equal
7942#. ``ogt``: ordered and greater than
7943#. ``oge``: ordered and greater than or equal
7944#. ``olt``: ordered and less than
7945#. ``ole``: ordered and less than or equal
7946#. ``one``: ordered and not equal
7947#. ``ord``: ordered (no nans)
7948#. ``ueq``: unordered or equal
7949#. ``ugt``: unordered or greater than
7950#. ``uge``: unordered or greater than or equal
7951#. ``ult``: unordered or less than
7952#. ``ule``: unordered or less than or equal
7953#. ``une``: unordered or not equal
7954#. ``uno``: unordered (either nans)
7955#. ``true``: no comparison, always returns true
7956
7957*Ordered* means that neither operand is a QNAN while *unordered* means
7958that either operand may be a QNAN.
7959
7960Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating
7961point <t_floating>` type or a :ref:`vector <t_vector>` of floating point
7962type. They must have identical types.
7963
7964Semantics:
7965""""""""""
7966
7967The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the
7968condition code given as ``cond``. If the operands are vectors, then the
7969vectors are compared element by element. Each comparison performed
7970always yields an :ref:`i1 <t_integer>` result, as follows:
7971
7972#. ``false``: always yields ``false``, regardless of operands.
7973#. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1``
7974 is equal to ``op2``.
7975#. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1``
7976 is greater than ``op2``.
7977#. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1``
7978 is greater than or equal to ``op2``.
7979#. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1``
7980 is less than ``op2``.
7981#. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1``
7982 is less than or equal to ``op2``.
7983#. ``one``: yields ``true`` if both operands are not a QNAN and ``op1``
7984 is not equal to ``op2``.
7985#. ``ord``: yields ``true`` if both operands are not a QNAN.
7986#. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is
7987 equal to ``op2``.
7988#. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is
7989 greater than ``op2``.
7990#. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is
7991 greater than or equal to ``op2``.
7992#. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is
7993 less than ``op2``.
7994#. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is
7995 less than or equal to ``op2``.
7996#. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is
7997 not equal to ``op2``.
7998#. ``uno``: yields ``true`` if either operand is a QNAN.
7999#. ``true``: always yields ``true``, regardless of operands.
8000
James Molloy88eb5352015-07-10 12:52:00 +00008001The ``fcmp`` instruction can also optionally take any number of
8002:ref:`fast-math flags <fastmath>`, which are optimization hints to enable
8003otherwise unsafe floating point optimizations.
8004
8005Any set of fast-math flags are legal on an ``fcmp`` instruction, but the
8006only flags that have any effect on its semantics are those that allow
8007assumptions to be made about the values of input arguments; namely
8008``nnan``, ``ninf``, and ``nsz``. See :ref:`fastmath` for more information.
8009
Sean Silvab084af42012-12-07 10:36:55 +00008010Example:
8011""""""""
8012
8013.. code-block:: llvm
8014
8015 <result> = fcmp oeq float 4.0, 5.0 ; yields: result=false
8016 <result> = fcmp one float 4.0, 5.0 ; yields: result=true
8017 <result> = fcmp olt float 4.0, 5.0 ; yields: result=true
8018 <result> = fcmp ueq double 1.0, 2.0 ; yields: result=false
8019
8020Note that the code generator does not yet support vector types with the
8021``fcmp`` instruction.
8022
8023.. _i_phi:
8024
8025'``phi``' Instruction
8026^^^^^^^^^^^^^^^^^^^^^
8027
8028Syntax:
8029"""""""
8030
8031::
8032
8033 <result> = phi <ty> [ <val0>, <label0>], ...
8034
8035Overview:
8036"""""""""
8037
8038The '``phi``' instruction is used to implement the φ node in the SSA
8039graph representing the function.
8040
8041Arguments:
8042""""""""""
8043
8044The type of the incoming values is specified with the first type field.
8045After this, the '``phi``' instruction takes a list of pairs as
8046arguments, with one pair for each predecessor basic block of the current
8047block. Only values of :ref:`first class <t_firstclass>` type may be used as
8048the value arguments to the PHI node. Only labels may be used as the
8049label arguments.
8050
8051There must be no non-phi instructions between the start of a basic block
8052and the PHI instructions: i.e. PHI instructions must be first in a basic
8053block.
8054
8055For the purposes of the SSA form, the use of each incoming value is
8056deemed to occur on the edge from the corresponding predecessor block to
8057the current block (but after any definition of an '``invoke``'
8058instruction's return value on the same edge).
8059
8060Semantics:
8061""""""""""
8062
8063At runtime, the '``phi``' instruction logically takes on the value
8064specified by the pair corresponding to the predecessor basic block that
8065executed just prior to the current block.
8066
8067Example:
8068""""""""
8069
8070.. code-block:: llvm
8071
8072 Loop: ; Infinite loop that counts from 0 on up...
8073 %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
8074 %nextindvar = add i32 %indvar, 1
8075 br label %Loop
8076
8077.. _i_select:
8078
8079'``select``' Instruction
8080^^^^^^^^^^^^^^^^^^^^^^^^
8081
8082Syntax:
8083"""""""
8084
8085::
8086
8087 <result> = select selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty
8088
8089 selty is either i1 or {<N x i1>}
8090
8091Overview:
8092"""""""""
8093
8094The '``select``' instruction is used to choose one value based on a
Joerg Sonnenberger94321ec2014-03-26 15:30:21 +00008095condition, without IR-level branching.
Sean Silvab084af42012-12-07 10:36:55 +00008096
8097Arguments:
8098""""""""""
8099
8100The '``select``' instruction requires an 'i1' value or a vector of 'i1'
8101values indicating the condition, and two values of the same :ref:`first
David Majnemer40a0b592015-03-03 22:45:47 +00008102class <t_firstclass>` type.
Sean Silvab084af42012-12-07 10:36:55 +00008103
8104Semantics:
8105""""""""""
8106
8107If the condition is an i1 and it evaluates to 1, the instruction returns
8108the first value argument; otherwise, it returns the second value
8109argument.
8110
8111If the condition is a vector of i1, then the value arguments must be
8112vectors of the same size, and the selection is done element by element.
8113
David Majnemer40a0b592015-03-03 22:45:47 +00008114If the condition is an i1 and the value arguments are vectors of the
8115same size, then an entire vector is selected.
8116
Sean Silvab084af42012-12-07 10:36:55 +00008117Example:
8118""""""""
8119
8120.. code-block:: llvm
8121
8122 %X = select i1 true, i8 17, i8 42 ; yields i8:17
8123
8124.. _i_call:
8125
8126'``call``' Instruction
8127^^^^^^^^^^^^^^^^^^^^^^
8128
8129Syntax:
8130"""""""
8131
8132::
8133
Reid Kleckner5772b772014-04-24 20:14:34 +00008134 <result> = [tail | musttail] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
Sean Silvab084af42012-12-07 10:36:55 +00008135
8136Overview:
8137"""""""""
8138
8139The '``call``' instruction represents a simple function call.
8140
8141Arguments:
8142""""""""""
8143
8144This instruction requires several arguments:
8145
Reid Kleckner5772b772014-04-24 20:14:34 +00008146#. The optional ``tail`` and ``musttail`` markers indicate that the optimizers
Sean Silvaa1190322015-08-06 22:56:48 +00008147 should perform tail call optimization. The ``tail`` marker is a hint that
8148 `can be ignored <CodeGenerator.html#sibcallopt>`_. The ``musttail`` marker
Reid Kleckner5772b772014-04-24 20:14:34 +00008149 means that the call must be tail call optimized in order for the program to
Sean Silvaa1190322015-08-06 22:56:48 +00008150 be correct. The ``musttail`` marker provides these guarantees:
Reid Kleckner5772b772014-04-24 20:14:34 +00008151
8152 #. The call will not cause unbounded stack growth if it is part of a
8153 recursive cycle in the call graph.
8154 #. Arguments with the :ref:`inalloca <attr_inalloca>` attribute are
8155 forwarded in place.
8156
8157 Both markers imply that the callee does not access allocas or varargs from
Sean Silvaa1190322015-08-06 22:56:48 +00008158 the caller. Calls marked ``musttail`` must obey the following additional
Reid Kleckner5772b772014-04-24 20:14:34 +00008159 rules:
8160
8161 - The call must immediately precede a :ref:`ret <i_ret>` instruction,
8162 or a pointer bitcast followed by a ret instruction.
8163 - The ret instruction must return the (possibly bitcasted) value
8164 produced by the call or void.
Sean Silvaa1190322015-08-06 22:56:48 +00008165 - The caller and callee prototypes must match. Pointer types of
Reid Kleckner5772b772014-04-24 20:14:34 +00008166 parameters or return types may differ in pointee type, but not
8167 in address space.
8168 - The calling conventions of the caller and callee must match.
8169 - All ABI-impacting function attributes, such as sret, byval, inreg,
8170 returned, and inalloca, must match.
Reid Kleckner83498642014-08-26 00:33:28 +00008171 - The callee must be varargs iff the caller is varargs. Bitcasting a
8172 non-varargs function to the appropriate varargs type is legal so
8173 long as the non-varargs prefixes obey the other rules.
Reid Kleckner5772b772014-04-24 20:14:34 +00008174
8175 Tail call optimization for calls marked ``tail`` is guaranteed to occur if
8176 the following conditions are met:
Sean Silvab084af42012-12-07 10:36:55 +00008177
8178 - Caller and callee both have the calling convention ``fastcc``.
8179 - The call is in tail position (ret immediately follows call and ret
8180 uses value of call or is void).
8181 - Option ``-tailcallopt`` is enabled, or
8182 ``llvm::GuaranteedTailCallOpt`` is ``true``.
Alp Tokercf218752014-06-30 18:57:16 +00008183 - `Platform-specific constraints are
Sean Silvab084af42012-12-07 10:36:55 +00008184 met. <CodeGenerator.html#tailcallopt>`_
8185
8186#. The optional "cconv" marker indicates which :ref:`calling
8187 convention <callingconv>` the call should use. If none is
8188 specified, the call defaults to using C calling conventions. The
8189 calling convention of the call must match the calling convention of
8190 the target function, or else the behavior is undefined.
8191#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
8192 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
8193 are valid here.
8194#. '``ty``': the type of the call instruction itself which is also the
8195 type of the return value. Functions that return no value are marked
8196 ``void``.
8197#. '``fnty``': shall be the signature of the pointer to function value
8198 being invoked. The argument types must match the types implied by
8199 this signature. This type can be omitted if the function is not
8200 varargs and if the function type does not return a pointer to a
8201 function.
8202#. '``fnptrval``': An LLVM value containing a pointer to a function to
8203 be invoked. In most cases, this is a direct function invocation, but
8204 indirect ``call``'s are just as possible, calling an arbitrary pointer
8205 to function value.
8206#. '``function args``': argument list whose types match the function
8207 signature argument types and parameter attributes. All arguments must
8208 be of :ref:`first class <t_firstclass>` type. If the function signature
8209 indicates the function accepts a variable number of arguments, the
8210 extra arguments can be specified.
8211#. The optional :ref:`function attributes <fnattrs>` list. Only
8212 '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
8213 attributes are valid here.
8214
8215Semantics:
8216""""""""""
8217
8218The '``call``' instruction is used to cause control flow to transfer to
8219a specified function, with its incoming arguments bound to the specified
8220values. Upon a '``ret``' instruction in the called function, control
8221flow continues with the instruction after the function call, and the
8222return value of the function is bound to the result argument.
8223
8224Example:
8225""""""""
8226
8227.. code-block:: llvm
8228
8229 %retval = call i32 @test(i32 %argc)
8230 call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) ; yields i32
8231 %X = tail call i32 @foo() ; yields i32
8232 %Y = tail call fastcc i32 @foo() ; yields i32
8233 call void %foo(i8 97 signext)
8234
8235 %struct.A = type { i32, i8 }
Tim Northover675a0962014-06-13 14:24:23 +00008236 %r = call %struct.A @foo() ; yields { i32, i8 }
Sean Silvab084af42012-12-07 10:36:55 +00008237 %gr = extractvalue %struct.A %r, 0 ; yields i32
8238 %gr1 = extractvalue %struct.A %r, 1 ; yields i8
8239 %Z = call void @foo() noreturn ; indicates that %foo never returns normally
8240 %ZZ = call zeroext i32 @bar() ; Return value is %zero extended
8241
8242llvm treats calls to some functions with names and arguments that match
8243the standard C99 library as being the C99 library functions, and may
8244perform optimizations or generate code for them under that assumption.
8245This is something we'd like to change in the future to provide better
8246support for freestanding environments and non-C-based languages.
8247
8248.. _i_va_arg:
8249
8250'``va_arg``' Instruction
8251^^^^^^^^^^^^^^^^^^^^^^^^
8252
8253Syntax:
8254"""""""
8255
8256::
8257
8258 <resultval> = va_arg <va_list*> <arglist>, <argty>
8259
8260Overview:
8261"""""""""
8262
8263The '``va_arg``' instruction is used to access arguments passed through
8264the "variable argument" area of a function call. It is used to implement
8265the ``va_arg`` macro in C.
8266
8267Arguments:
8268""""""""""
8269
8270This instruction takes a ``va_list*`` value and the type of the
8271argument. It returns a value of the specified argument type and
8272increments the ``va_list`` to point to the next argument. The actual
8273type of ``va_list`` is target specific.
8274
8275Semantics:
8276""""""""""
8277
8278The '``va_arg``' instruction loads an argument of the specified type
8279from the specified ``va_list`` and causes the ``va_list`` to point to
8280the next argument. For more information, see the variable argument
8281handling :ref:`Intrinsic Functions <int_varargs>`.
8282
8283It is legal for this instruction to be called in a function which does
8284not take a variable number of arguments, for example, the ``vfprintf``
8285function.
8286
8287``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic
8288function <intrinsics>` because it takes a type as an argument.
8289
8290Example:
8291""""""""
8292
8293See the :ref:`variable argument processing <int_varargs>` section.
8294
8295Note that the code generator does not yet fully support va\_arg on many
8296targets. Also, it does not currently support va\_arg with aggregate
8297types on any target.
8298
8299.. _i_landingpad:
8300
8301'``landingpad``' Instruction
8302^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8303
8304Syntax:
8305"""""""
8306
8307::
8308
David Majnemer7fddecc2015-06-17 20:52:32 +00008309 <resultval> = landingpad <resultty> <clause>+
8310 <resultval> = landingpad <resultty> cleanup <clause>*
Sean Silvab084af42012-12-07 10:36:55 +00008311
8312 <clause> := catch <type> <value>
8313 <clause> := filter <array constant type> <array constant>
8314
8315Overview:
8316"""""""""
8317
8318The '``landingpad``' instruction is used by `LLVM's exception handling
8319system <ExceptionHandling.html#overview>`_ to specify that a basic block
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00008320is a landing pad --- one where the exception lands, and corresponds to the
Sean Silvab084af42012-12-07 10:36:55 +00008321code found in the ``catch`` portion of a ``try``/``catch`` sequence. It
David Majnemer7fddecc2015-06-17 20:52:32 +00008322defines values supplied by the :ref:`personality function <personalityfn>` upon
Sean Silvab084af42012-12-07 10:36:55 +00008323re-entry to the function. The ``resultval`` has the type ``resultty``.
8324
8325Arguments:
8326""""""""""
8327
David Majnemer7fddecc2015-06-17 20:52:32 +00008328The optional
Sean Silvab084af42012-12-07 10:36:55 +00008329``cleanup`` flag indicates that the landing pad block is a cleanup.
8330
Dmitri Gribenkoe8131122013-01-19 20:34:20 +00008331A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and
Sean Silvab084af42012-12-07 10:36:55 +00008332contains the global variable representing the "type" that may be caught
8333or filtered respectively. Unlike the ``catch`` clause, the ``filter``
8334clause takes an array constant as its argument. Use
8335"``[0 x i8**] undef``" for a filter which cannot throw. The
8336'``landingpad``' instruction must contain *at least* one ``clause`` or
8337the ``cleanup`` flag.
8338
8339Semantics:
8340""""""""""
8341
8342The '``landingpad``' instruction defines the values which are set by the
David Majnemer7fddecc2015-06-17 20:52:32 +00008343:ref:`personality function <personalityfn>` upon re-entry to the function, and
Sean Silvab084af42012-12-07 10:36:55 +00008344therefore the "result type" of the ``landingpad`` instruction. As with
8345calling conventions, how the personality function results are
8346represented in LLVM IR is target specific.
8347
8348The clauses are applied in order from top to bottom. If two
8349``landingpad`` instructions are merged together through inlining, the
8350clauses from the calling function are appended to the list of clauses.
8351When the call stack is being unwound due to an exception being thrown,
8352the exception is compared against each ``clause`` in turn. If it doesn't
8353match any of the clauses, and the ``cleanup`` flag is not set, then
8354unwinding continues further up the call stack.
8355
8356The ``landingpad`` instruction has several restrictions:
8357
8358- A landing pad block is a basic block which is the unwind destination
8359 of an '``invoke``' instruction.
8360- A landing pad block must have a '``landingpad``' instruction as its
8361 first non-PHI instruction.
8362- There can be only one '``landingpad``' instruction within the landing
8363 pad block.
8364- A basic block that is not a landing pad block may not include a
8365 '``landingpad``' instruction.
Sean Silvab084af42012-12-07 10:36:55 +00008366
8367Example:
8368""""""""
8369
8370.. code-block:: llvm
8371
8372 ;; A landing pad which can catch an integer.
David Majnemer7fddecc2015-06-17 20:52:32 +00008373 %res = landingpad { i8*, i32 }
Sean Silvab084af42012-12-07 10:36:55 +00008374 catch i8** @_ZTIi
8375 ;; A landing pad that is a cleanup.
David Majnemer7fddecc2015-06-17 20:52:32 +00008376 %res = landingpad { i8*, i32 }
Sean Silvab084af42012-12-07 10:36:55 +00008377 cleanup
8378 ;; A landing pad which can catch an integer and can only throw a double.
David Majnemer7fddecc2015-06-17 20:52:32 +00008379 %res = landingpad { i8*, i32 }
Sean Silvab084af42012-12-07 10:36:55 +00008380 catch i8** @_ZTIi
8381 filter [1 x i8**] [@_ZTId]
8382
David Majnemer654e1302015-07-31 17:58:14 +00008383.. _i_cleanuppad:
8384
8385'``cleanuppad``' Instruction
8386^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8387
8388Syntax:
8389"""""""
8390
8391::
8392
8393 <resultval> = cleanuppad <resultty> [<args>*]
8394
8395Overview:
8396"""""""""
8397
8398The '``cleanuppad``' instruction is used by `LLVM's exception handling
8399system <ExceptionHandling.html#overview>`_ to specify that a basic block
8400is a cleanup block --- one where a personality routine attempts to
8401transfer control to run cleanup actions.
8402The ``args`` correspond to whatever additional
8403information the :ref:`personality function <personalityfn>` requires to
8404execute the cleanup.
8405The ``resultval`` has the type ``resultty``.
8406
8407Arguments:
8408""""""""""
8409
8410The instruction takes a list of arbitrary values which are interpreted
8411by the :ref:`personality function <personalityfn>`.
8412
8413Semantics:
8414""""""""""
8415
8416The '``cleanuppad``' instruction defines the values which are set by the
8417:ref:`personality function <personalityfn>` upon re-entry to the function, and
8418therefore the "result type" of the ``cleanuppad`` instruction. As with
8419calling conventions, how the personality function results are
8420represented in LLVM IR is target specific.
8421
8422When the call stack is being unwound due to an exception being thrown,
8423the :ref:`personality function <personalityfn>` transfers control to the
8424``cleanuppad`` with the aid of the personality-specific arguments.
8425
8426The ``cleanuppad`` instruction has several restrictions:
8427
8428- A cleanup block is a basic block which is the unwind destination of
8429 an exceptional instruction.
8430- A cleanup block must have a '``cleanuppad``' instruction as its
8431 first non-PHI instruction.
8432- There can be only one '``cleanuppad``' instruction within the
8433 cleanup block.
8434- A basic block that is not a cleanup block may not include a
8435 '``cleanuppad``' instruction.
8436- It is undefined behavior for control to transfer from a ``cleanuppad`` to a
8437 ``catchret`` without first executing a ``cleanupret`` and a subsequent
8438 ``catchpad``.
8439- It is undefined behavior for control to transfer from a ``cleanuppad`` to a
8440 ``ret`` without first executing a ``cleanupret``.
8441
8442Example:
8443""""""""
8444
8445.. code-block:: llvm
8446
8447 %res = cleanuppad { i8*, i32 } [label %nextaction]
8448
Sean Silvab084af42012-12-07 10:36:55 +00008449.. _intrinsics:
8450
8451Intrinsic Functions
8452===================
8453
8454LLVM supports the notion of an "intrinsic function". These functions
8455have well known names and semantics and are required to follow certain
8456restrictions. Overall, these intrinsics represent an extension mechanism
8457for the LLVM language that does not require changing all of the
8458transformations in LLVM when adding to the language (or the bitcode
8459reader/writer, the parser, etc...).
8460
8461Intrinsic function names must all start with an "``llvm.``" prefix. This
8462prefix is reserved in LLVM for intrinsic names; thus, function names may
8463not begin with this prefix. Intrinsic functions must always be external
8464functions: you cannot define the body of intrinsic functions. Intrinsic
8465functions may only be used in call or invoke instructions: it is illegal
8466to take the address of an intrinsic function. Additionally, because
8467intrinsic functions are part of the LLVM language, it is required if any
8468are added that they be documented here.
8469
8470Some intrinsic functions can be overloaded, i.e., the intrinsic
8471represents a family of functions that perform the same operation but on
8472different data types. Because LLVM can represent over 8 million
8473different integer types, overloading is used commonly to allow an
8474intrinsic function to operate on any integer type. One or more of the
8475argument types or the result type can be overloaded to accept any
8476integer type. Argument types may also be defined as exactly matching a
8477previous argument's type or the result type. This allows an intrinsic
8478function which accepts multiple arguments, but needs all of them to be
8479of the same type, to only be overloaded with respect to a single
8480argument or the result.
8481
8482Overloaded intrinsics will have the names of its overloaded argument
8483types encoded into its function name, each preceded by a period. Only
8484those types which are overloaded result in a name suffix. Arguments
8485whose type is matched against another type do not. For example, the
8486``llvm.ctpop`` function can take an integer of any width and returns an
8487integer of exactly the same integer width. This leads to a family of
8488functions such as ``i8 @llvm.ctpop.i8(i8 %val)`` and
8489``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is
8490overloaded, and only one type suffix is required. Because the argument's
8491type is matched against the return type, it does not require its own
8492name suffix.
8493
8494To learn how to add an intrinsic function, please see the `Extending
8495LLVM Guide <ExtendingLLVM.html>`_.
8496
8497.. _int_varargs:
8498
8499Variable Argument Handling Intrinsics
8500-------------------------------------
8501
8502Variable argument support is defined in LLVM with the
8503:ref:`va_arg <i_va_arg>` instruction and these three intrinsic
8504functions. These functions are related to the similarly named macros
8505defined in the ``<stdarg.h>`` header file.
8506
8507All of these functions operate on arguments that use a target-specific
8508value type "``va_list``". The LLVM assembly language reference manual
8509does not define what this type is, so all transformations should be
8510prepared to handle these functions regardless of the type used.
8511
8512This example shows how the :ref:`va_arg <i_va_arg>` instruction and the
8513variable argument handling intrinsic functions are used.
8514
8515.. code-block:: llvm
8516
Tim Northoverab60bb92014-11-02 01:21:51 +00008517 ; This struct is different for every platform. For most platforms,
8518 ; it is merely an i8*.
8519 %struct.va_list = type { i8* }
8520
8521 ; For Unix x86_64 platforms, va_list is the following struct:
8522 ; %struct.va_list = type { i32, i32, i8*, i8* }
8523
Sean Silvab084af42012-12-07 10:36:55 +00008524 define i32 @test(i32 %X, ...) {
8525 ; Initialize variable argument processing
Tim Northoverab60bb92014-11-02 01:21:51 +00008526 %ap = alloca %struct.va_list
8527 %ap2 = bitcast %struct.va_list* %ap to i8*
Sean Silvab084af42012-12-07 10:36:55 +00008528 call void @llvm.va_start(i8* %ap2)
8529
8530 ; Read a single integer argument
Tim Northoverab60bb92014-11-02 01:21:51 +00008531 %tmp = va_arg i8* %ap2, i32
Sean Silvab084af42012-12-07 10:36:55 +00008532
8533 ; Demonstrate usage of llvm.va_copy and llvm.va_end
8534 %aq = alloca i8*
8535 %aq2 = bitcast i8** %aq to i8*
8536 call void @llvm.va_copy(i8* %aq2, i8* %ap2)
8537 call void @llvm.va_end(i8* %aq2)
8538
8539 ; Stop processing of arguments.
8540 call void @llvm.va_end(i8* %ap2)
8541 ret i32 %tmp
8542 }
8543
8544 declare void @llvm.va_start(i8*)
8545 declare void @llvm.va_copy(i8*, i8*)
8546 declare void @llvm.va_end(i8*)
8547
8548.. _int_va_start:
8549
8550'``llvm.va_start``' Intrinsic
8551^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8552
8553Syntax:
8554"""""""
8555
8556::
8557
Nick Lewycky04f6de02013-09-11 22:04:52 +00008558 declare void @llvm.va_start(i8* <arglist>)
Sean Silvab084af42012-12-07 10:36:55 +00008559
8560Overview:
8561"""""""""
8562
8563The '``llvm.va_start``' intrinsic initializes ``*<arglist>`` for
8564subsequent use by ``va_arg``.
8565
8566Arguments:
8567""""""""""
8568
8569The argument is a pointer to a ``va_list`` element to initialize.
8570
8571Semantics:
8572""""""""""
8573
8574The '``llvm.va_start``' intrinsic works just like the ``va_start`` macro
8575available in C. In a target-dependent way, it initializes the
8576``va_list`` element to which the argument points, so that the next call
8577to ``va_arg`` will produce the first variable argument passed to the
8578function. Unlike the C ``va_start`` macro, this intrinsic does not need
8579to know the last argument of the function as the compiler can figure
8580that out.
8581
8582'``llvm.va_end``' Intrinsic
8583^^^^^^^^^^^^^^^^^^^^^^^^^^^
8584
8585Syntax:
8586"""""""
8587
8588::
8589
8590 declare void @llvm.va_end(i8* <arglist>)
8591
8592Overview:
8593"""""""""
8594
8595The '``llvm.va_end``' intrinsic destroys ``*<arglist>``, which has been
8596initialized previously with ``llvm.va_start`` or ``llvm.va_copy``.
8597
8598Arguments:
8599""""""""""
8600
8601The argument is a pointer to a ``va_list`` to destroy.
8602
8603Semantics:
8604""""""""""
8605
8606The '``llvm.va_end``' intrinsic works just like the ``va_end`` macro
8607available in C. In a target-dependent way, it destroys the ``va_list``
8608element to which the argument points. Calls to
8609:ref:`llvm.va_start <int_va_start>` and
8610:ref:`llvm.va_copy <int_va_copy>` must be matched exactly with calls to
8611``llvm.va_end``.
8612
8613.. _int_va_copy:
8614
8615'``llvm.va_copy``' Intrinsic
8616^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8617
8618Syntax:
8619"""""""
8620
8621::
8622
8623 declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
8624
8625Overview:
8626"""""""""
8627
8628The '``llvm.va_copy``' intrinsic copies the current argument position
8629from the source argument list to the destination argument list.
8630
8631Arguments:
8632""""""""""
8633
8634The first argument is a pointer to a ``va_list`` element to initialize.
8635The second argument is a pointer to a ``va_list`` element to copy from.
8636
8637Semantics:
8638""""""""""
8639
8640The '``llvm.va_copy``' intrinsic works just like the ``va_copy`` macro
8641available in C. In a target-dependent way, it copies the source
8642``va_list`` element into the destination ``va_list`` element. This
8643intrinsic is necessary because the `` llvm.va_start`` intrinsic may be
8644arbitrarily complex and require, for example, memory allocation.
8645
8646Accurate Garbage Collection Intrinsics
8647--------------------------------------
8648
Philip Reamesc5b0f562015-02-25 23:52:06 +00008649LLVM's support for `Accurate Garbage Collection <GarbageCollection.html>`_
Mehdi Amini4a121fa2015-03-14 22:04:06 +00008650(GC) requires the frontend to generate code containing appropriate intrinsic
8651calls and select an appropriate GC strategy which knows how to lower these
Philip Reamesc5b0f562015-02-25 23:52:06 +00008652intrinsics in a manner which is appropriate for the target collector.
8653
Sean Silvab084af42012-12-07 10:36:55 +00008654These intrinsics allow identification of :ref:`GC roots on the
8655stack <int_gcroot>`, as well as garbage collector implementations that
8656require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers.
Philip Reamesc5b0f562015-02-25 23:52:06 +00008657Frontends for type-safe garbage collected languages should generate
Sean Silvab084af42012-12-07 10:36:55 +00008658these intrinsics to make use of the LLVM garbage collectors. For more
Philip Reamesf80bbff2015-02-25 23:45:20 +00008659details, see `Garbage Collection with LLVM <GarbageCollection.html>`_.
Sean Silvab084af42012-12-07 10:36:55 +00008660
Philip Reamesf80bbff2015-02-25 23:45:20 +00008661Experimental Statepoint Intrinsics
8662^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8663
8664LLVM provides an second experimental set of intrinsics for describing garbage
Sean Silvaa1190322015-08-06 22:56:48 +00008665collection safepoints in compiled code. These intrinsics are an alternative
Mehdi Amini4a121fa2015-03-14 22:04:06 +00008666to the ``llvm.gcroot`` intrinsics, but are compatible with the ones for
Sean Silvaa1190322015-08-06 22:56:48 +00008667:ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. The
Mehdi Amini4a121fa2015-03-14 22:04:06 +00008668differences in approach are covered in the `Garbage Collection with LLVM
Sean Silvaa1190322015-08-06 22:56:48 +00008669<GarbageCollection.html>`_ documentation. The intrinsics themselves are
Philip Reamesf80bbff2015-02-25 23:45:20 +00008670described in :doc:`Statepoints`.
Sean Silvab084af42012-12-07 10:36:55 +00008671
8672.. _int_gcroot:
8673
8674'``llvm.gcroot``' Intrinsic
8675^^^^^^^^^^^^^^^^^^^^^^^^^^^
8676
8677Syntax:
8678"""""""
8679
8680::
8681
8682 declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
8683
8684Overview:
8685"""""""""
8686
8687The '``llvm.gcroot``' intrinsic declares the existence of a GC root to
8688the code generator, and allows some metadata to be associated with it.
8689
8690Arguments:
8691""""""""""
8692
8693The first argument specifies the address of a stack object that contains
8694the root pointer. The second pointer (which must be either a constant or
8695a global value address) contains the meta-data to be associated with the
8696root.
8697
8698Semantics:
8699""""""""""
8700
8701At runtime, a call to this intrinsic stores a null pointer into the
8702"ptrloc" location. At compile-time, the code generator generates
8703information to allow the runtime to find the pointer at GC safe points.
8704The '``llvm.gcroot``' intrinsic may only be used in a function which
8705:ref:`specifies a GC algorithm <gc>`.
8706
8707.. _int_gcread:
8708
8709'``llvm.gcread``' Intrinsic
8710^^^^^^^^^^^^^^^^^^^^^^^^^^^
8711
8712Syntax:
8713"""""""
8714
8715::
8716
8717 declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
8718
8719Overview:
8720"""""""""
8721
8722The '``llvm.gcread``' intrinsic identifies reads of references from heap
8723locations, allowing garbage collector implementations that require read
8724barriers.
8725
8726Arguments:
8727""""""""""
8728
8729The second argument is the address to read from, which should be an
8730address allocated from the garbage collector. The first object is a
8731pointer to the start of the referenced object, if needed by the language
8732runtime (otherwise null).
8733
8734Semantics:
8735""""""""""
8736
8737The '``llvm.gcread``' intrinsic has the same semantics as a load
8738instruction, but may be replaced with substantially more complex code by
8739the garbage collector runtime, as needed. The '``llvm.gcread``'
8740intrinsic may only be used in a function which :ref:`specifies a GC
8741algorithm <gc>`.
8742
8743.. _int_gcwrite:
8744
8745'``llvm.gcwrite``' Intrinsic
8746^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8747
8748Syntax:
8749"""""""
8750
8751::
8752
8753 declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
8754
8755Overview:
8756"""""""""
8757
8758The '``llvm.gcwrite``' intrinsic identifies writes of references to heap
8759locations, allowing garbage collector implementations that require write
8760barriers (such as generational or reference counting collectors).
8761
8762Arguments:
8763""""""""""
8764
8765The first argument is the reference to store, the second is the start of
8766the object to store it to, and the third is the address of the field of
8767Obj to store to. If the runtime does not require a pointer to the
8768object, Obj may be null.
8769
8770Semantics:
8771""""""""""
8772
8773The '``llvm.gcwrite``' intrinsic has the same semantics as a store
8774instruction, but may be replaced with substantially more complex code by
8775the garbage collector runtime, as needed. The '``llvm.gcwrite``'
8776intrinsic may only be used in a function which :ref:`specifies a GC
8777algorithm <gc>`.
8778
8779Code Generator Intrinsics
8780-------------------------
8781
8782These intrinsics are provided by LLVM to expose special features that
8783may only be implemented with code generator support.
8784
8785'``llvm.returnaddress``' Intrinsic
8786^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8787
8788Syntax:
8789"""""""
8790
8791::
8792
8793 declare i8 *@llvm.returnaddress(i32 <level>)
8794
8795Overview:
8796"""""""""
8797
8798The '``llvm.returnaddress``' intrinsic attempts to compute a
8799target-specific value indicating the return address of the current
8800function or one of its callers.
8801
8802Arguments:
8803""""""""""
8804
8805The argument to this intrinsic indicates which function to return the
8806address for. Zero indicates the calling function, one indicates its
8807caller, etc. The argument is **required** to be a constant integer
8808value.
8809
8810Semantics:
8811""""""""""
8812
8813The '``llvm.returnaddress``' intrinsic either returns a pointer
8814indicating the return address of the specified call frame, or zero if it
8815cannot be identified. The value returned by this intrinsic is likely to
8816be incorrect or 0 for arguments other than zero, so it should only be
8817used for debugging purposes.
8818
8819Note that calling this intrinsic does not prevent function inlining or
8820other aggressive transformations, so the value returned may not be that
8821of the obvious source-language caller.
8822
8823'``llvm.frameaddress``' Intrinsic
8824^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8825
8826Syntax:
8827"""""""
8828
8829::
8830
8831 declare i8* @llvm.frameaddress(i32 <level>)
8832
8833Overview:
8834"""""""""
8835
8836The '``llvm.frameaddress``' intrinsic attempts to return the
8837target-specific frame pointer value for the specified stack frame.
8838
8839Arguments:
8840""""""""""
8841
8842The argument to this intrinsic indicates which function to return the
8843frame pointer for. Zero indicates the calling function, one indicates
8844its caller, etc. The argument is **required** to be a constant integer
8845value.
8846
8847Semantics:
8848""""""""""
8849
8850The '``llvm.frameaddress``' intrinsic either returns a pointer
8851indicating the frame address of the specified call frame, or zero if it
8852cannot be identified. The value returned by this intrinsic is likely to
8853be incorrect or 0 for arguments other than zero, so it should only be
8854used for debugging purposes.
8855
8856Note that calling this intrinsic does not prevent function inlining or
8857other aggressive transformations, so the value returned may not be that
8858of the obvious source-language caller.
8859
Reid Kleckner60381792015-07-07 22:25:32 +00008860'``llvm.localescape``' and '``llvm.localrecover``' Intrinsics
Reid Klecknere9b89312015-01-13 00:48:10 +00008861^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8862
8863Syntax:
8864"""""""
8865
8866::
8867
Reid Kleckner60381792015-07-07 22:25:32 +00008868 declare void @llvm.localescape(...)
8869 declare i8* @llvm.localrecover(i8* %func, i8* %fp, i32 %idx)
Reid Klecknere9b89312015-01-13 00:48:10 +00008870
8871Overview:
8872"""""""""
8873
Reid Kleckner60381792015-07-07 22:25:32 +00008874The '``llvm.localescape``' intrinsic escapes offsets of a collection of static
8875allocas, and the '``llvm.localrecover``' intrinsic applies those offsets to a
Reid Klecknercfb9ce52015-03-05 18:26:34 +00008876live frame pointer to recover the address of the allocation. The offset is
Reid Kleckner60381792015-07-07 22:25:32 +00008877computed during frame layout of the caller of ``llvm.localescape``.
Reid Klecknere9b89312015-01-13 00:48:10 +00008878
8879Arguments:
8880""""""""""
8881
Reid Kleckner60381792015-07-07 22:25:32 +00008882All arguments to '``llvm.localescape``' must be pointers to static allocas or
8883casts of static allocas. Each function can only call '``llvm.localescape``'
Reid Klecknercfb9ce52015-03-05 18:26:34 +00008884once, and it can only do so from the entry block.
Reid Klecknere9b89312015-01-13 00:48:10 +00008885
Reid Kleckner60381792015-07-07 22:25:32 +00008886The ``func`` argument to '``llvm.localrecover``' must be a constant
Reid Klecknere9b89312015-01-13 00:48:10 +00008887bitcasted pointer to a function defined in the current module. The code
8888generator cannot determine the frame allocation offset of functions defined in
8889other modules.
8890
Reid Klecknerd5afc62f2015-07-07 23:23:03 +00008891The ``fp`` argument to '``llvm.localrecover``' must be a frame pointer of a
8892call frame that is currently live. The return value of '``llvm.localaddress``'
8893is one way to produce such a value, but various runtimes also expose a suitable
8894pointer in platform-specific ways.
Reid Klecknere9b89312015-01-13 00:48:10 +00008895
Reid Kleckner60381792015-07-07 22:25:32 +00008896The ``idx`` argument to '``llvm.localrecover``' indicates which alloca passed to
8897'``llvm.localescape``' to recover. It is zero-indexed.
Reid Klecknercfb9ce52015-03-05 18:26:34 +00008898
Reid Klecknere9b89312015-01-13 00:48:10 +00008899Semantics:
8900""""""""""
8901
Reid Kleckner60381792015-07-07 22:25:32 +00008902These intrinsics allow a group of functions to share access to a set of local
8903stack allocations of a one parent function. The parent function may call the
8904'``llvm.localescape``' intrinsic once from the function entry block, and the
8905child functions can use '``llvm.localrecover``' to access the escaped allocas.
8906The '``llvm.localescape``' intrinsic blocks inlining, as inlining changes where
8907the escaped allocas are allocated, which would break attempts to use
8908'``llvm.localrecover``'.
Reid Klecknere9b89312015-01-13 00:48:10 +00008909
Renato Golinc7aea402014-05-06 16:51:25 +00008910.. _int_read_register:
8911.. _int_write_register:
8912
8913'``llvm.read_register``' and '``llvm.write_register``' Intrinsics
8914^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8915
8916Syntax:
8917"""""""
8918
8919::
8920
8921 declare i32 @llvm.read_register.i32(metadata)
8922 declare i64 @llvm.read_register.i64(metadata)
8923 declare void @llvm.write_register.i32(metadata, i32 @value)
8924 declare void @llvm.write_register.i64(metadata, i64 @value)
Duncan P. N. Exon Smithbe7ea192014-12-15 19:07:53 +00008925 !0 = !{!"sp\00"}
Renato Golinc7aea402014-05-06 16:51:25 +00008926
8927Overview:
8928"""""""""
8929
8930The '``llvm.read_register``' and '``llvm.write_register``' intrinsics
8931provides access to the named register. The register must be valid on
8932the architecture being compiled to. The type needs to be compatible
8933with the register being read.
8934
8935Semantics:
8936""""""""""
8937
8938The '``llvm.read_register``' intrinsic returns the current value of the
8939register, where possible. The '``llvm.write_register``' intrinsic sets
8940the current value of the register, where possible.
8941
8942This is useful to implement named register global variables that need
8943to always be mapped to a specific register, as is common practice on
8944bare-metal programs including OS kernels.
8945
8946The compiler doesn't check for register availability or use of the used
8947register in surrounding code, including inline assembly. Because of that,
8948allocatable registers are not supported.
8949
8950Warning: So far it only works with the stack pointer on selected
Tim Northover3b0846e2014-05-24 12:50:23 +00008951architectures (ARM, AArch64, PowerPC and x86_64). Significant amount of
Renato Golinc7aea402014-05-06 16:51:25 +00008952work is needed to support other registers and even more so, allocatable
8953registers.
8954
Sean Silvab084af42012-12-07 10:36:55 +00008955.. _int_stacksave:
8956
8957'``llvm.stacksave``' Intrinsic
8958^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8959
8960Syntax:
8961"""""""
8962
8963::
8964
8965 declare i8* @llvm.stacksave()
8966
8967Overview:
8968"""""""""
8969
8970The '``llvm.stacksave``' intrinsic is used to remember the current state
8971of the function stack, for use with
8972:ref:`llvm.stackrestore <int_stackrestore>`. This is useful for
8973implementing language features like scoped automatic variable sized
8974arrays in C99.
8975
8976Semantics:
8977""""""""""
8978
8979This intrinsic returns a opaque pointer value that can be passed to
8980:ref:`llvm.stackrestore <int_stackrestore>`. When an
8981``llvm.stackrestore`` intrinsic is executed with a value saved from
8982``llvm.stacksave``, it effectively restores the state of the stack to
8983the state it was in when the ``llvm.stacksave`` intrinsic executed. In
8984practice, this pops any :ref:`alloca <i_alloca>` blocks from the stack that
8985were allocated after the ``llvm.stacksave`` was executed.
8986
8987.. _int_stackrestore:
8988
8989'``llvm.stackrestore``' Intrinsic
8990^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8991
8992Syntax:
8993"""""""
8994
8995::
8996
8997 declare void @llvm.stackrestore(i8* %ptr)
8998
8999Overview:
9000"""""""""
9001
9002The '``llvm.stackrestore``' intrinsic is used to restore the state of
9003the function stack to the state it was in when the corresponding
9004:ref:`llvm.stacksave <int_stacksave>` intrinsic executed. This is
9005useful for implementing language features like scoped automatic variable
9006sized arrays in C99.
9007
9008Semantics:
9009""""""""""
9010
9011See the description for :ref:`llvm.stacksave <int_stacksave>`.
9012
9013'``llvm.prefetch``' Intrinsic
9014^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9015
9016Syntax:
9017"""""""
9018
9019::
9020
9021 declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>)
9022
9023Overview:
9024"""""""""
9025
9026The '``llvm.prefetch``' intrinsic is a hint to the code generator to
9027insert a prefetch instruction if supported; otherwise, it is a noop.
9028Prefetches have no effect on the behavior of the program but can change
9029its performance characteristics.
9030
9031Arguments:
9032""""""""""
9033
9034``address`` is the address to be prefetched, ``rw`` is the specifier
9035determining if the fetch should be for a read (0) or write (1), and
9036``locality`` is a temporal locality specifier ranging from (0) - no
9037locality, to (3) - extremely local keep in cache. The ``cache type``
9038specifies whether the prefetch is performed on the data (1) or
9039instruction (0) cache. The ``rw``, ``locality`` and ``cache type``
9040arguments must be constant integers.
9041
9042Semantics:
9043""""""""""
9044
9045This intrinsic does not modify the behavior of the program. In
9046particular, prefetches cannot trap and do not produce a value. On
9047targets that support this intrinsic, the prefetch can provide hints to
9048the processor cache for better performance.
9049
9050'``llvm.pcmarker``' Intrinsic
9051^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9052
9053Syntax:
9054"""""""
9055
9056::
9057
9058 declare void @llvm.pcmarker(i32 <id>)
9059
9060Overview:
9061"""""""""
9062
9063The '``llvm.pcmarker``' intrinsic is a method to export a Program
9064Counter (PC) in a region of code to simulators and other tools. The
9065method is target specific, but it is expected that the marker will use
9066exported symbols to transmit the PC of the marker. The marker makes no
9067guarantees that it will remain with any specific instruction after
9068optimizations. It is possible that the presence of a marker will inhibit
9069optimizations. The intended use is to be inserted after optimizations to
9070allow correlations of simulation runs.
9071
9072Arguments:
9073""""""""""
9074
9075``id`` is a numerical id identifying the marker.
9076
9077Semantics:
9078""""""""""
9079
9080This intrinsic does not modify the behavior of the program. Backends
9081that do not support this intrinsic may ignore it.
9082
9083'``llvm.readcyclecounter``' Intrinsic
9084^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9085
9086Syntax:
9087"""""""
9088
9089::
9090
9091 declare i64 @llvm.readcyclecounter()
9092
9093Overview:
9094"""""""""
9095
9096The '``llvm.readcyclecounter``' intrinsic provides access to the cycle
9097counter register (or similar low latency, high accuracy clocks) on those
9098targets that support it. On X86, it should map to RDTSC. On Alpha, it
9099should map to RPCC. As the backing counters overflow quickly (on the
9100order of 9 seconds on alpha), this should only be used for small
9101timings.
9102
9103Semantics:
9104""""""""""
9105
9106When directly supported, reading the cycle counter should not modify any
9107memory. Implementations are allowed to either return a application
9108specific value or a system wide value. On backends without support, this
9109is lowered to a constant 0.
9110
Tim Northoverbc933082013-05-23 19:11:20 +00009111Note that runtime support may be conditional on the privilege-level code is
9112running at and the host platform.
9113
Renato Golinc0a3c1d2014-03-26 12:52:28 +00009114'``llvm.clear_cache``' Intrinsic
9115^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9116
9117Syntax:
9118"""""""
9119
9120::
9121
9122 declare void @llvm.clear_cache(i8*, i8*)
9123
9124Overview:
9125"""""""""
9126
Joerg Sonnenberger03014d62014-03-26 14:35:21 +00009127The '``llvm.clear_cache``' intrinsic ensures visibility of modifications
9128in the specified range to the execution unit of the processor. On
9129targets with non-unified instruction and data cache, the implementation
9130flushes the instruction cache.
Renato Golinc0a3c1d2014-03-26 12:52:28 +00009131
9132Semantics:
9133""""""""""
9134
Joerg Sonnenberger03014d62014-03-26 14:35:21 +00009135On platforms with coherent instruction and data caches (e.g. x86), this
9136intrinsic is a nop. On platforms with non-coherent instruction and data
Alp Toker16f98b22014-04-09 14:47:27 +00009137cache (e.g. ARM, MIPS), the intrinsic is lowered either to appropriate
Joerg Sonnenberger03014d62014-03-26 14:35:21 +00009138instructions or a system call, if cache flushing requires special
9139privileges.
Renato Golinc0a3c1d2014-03-26 12:52:28 +00009140
Sean Silvad02bf3e2014-04-07 22:29:53 +00009141The default behavior is to emit a call to ``__clear_cache`` from the run
Joerg Sonnenberger03014d62014-03-26 14:35:21 +00009142time library.
Renato Golin93010e62014-03-26 14:01:32 +00009143
Joerg Sonnenberger03014d62014-03-26 14:35:21 +00009144This instrinsic does *not* empty the instruction pipeline. Modifications
9145of the current function are outside the scope of the intrinsic.
Renato Golinc0a3c1d2014-03-26 12:52:28 +00009146
Justin Bogner61ba2e32014-12-08 18:02:35 +00009147'``llvm.instrprof_increment``' Intrinsic
9148^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9149
9150Syntax:
9151"""""""
9152
9153::
9154
9155 declare void @llvm.instrprof_increment(i8* <name>, i64 <hash>,
9156 i32 <num-counters>, i32 <index>)
9157
9158Overview:
9159"""""""""
9160
9161The '``llvm.instrprof_increment``' intrinsic can be emitted by a
9162frontend for use with instrumentation based profiling. These will be
9163lowered by the ``-instrprof`` pass to generate execution counts of a
9164program at runtime.
9165
9166Arguments:
9167""""""""""
9168
9169The first argument is a pointer to a global variable containing the
9170name of the entity being instrumented. This should generally be the
9171(mangled) function name for a set of counters.
9172
9173The second argument is a hash value that can be used by the consumer
9174of the profile data to detect changes to the instrumented source, and
9175the third is the number of counters associated with ``name``. It is an
9176error if ``hash`` or ``num-counters`` differ between two instances of
9177``instrprof_increment`` that refer to the same name.
9178
9179The last argument refers to which of the counters for ``name`` should
9180be incremented. It should be a value between 0 and ``num-counters``.
9181
9182Semantics:
9183""""""""""
9184
9185This intrinsic represents an increment of a profiling counter. It will
9186cause the ``-instrprof`` pass to generate the appropriate data
9187structures and the code to increment the appropriate value, in a
9188format that can be written out by a compiler runtime and consumed via
9189the ``llvm-profdata`` tool.
9190
Sean Silvab084af42012-12-07 10:36:55 +00009191Standard C Library Intrinsics
9192-----------------------------
9193
9194LLVM provides intrinsics for a few important standard C library
9195functions. These intrinsics allow source-language front-ends to pass
9196information about the alignment of the pointer arguments to the code
9197generator, providing opportunity for more efficient code generation.
9198
9199.. _int_memcpy:
9200
9201'``llvm.memcpy``' Intrinsic
9202^^^^^^^^^^^^^^^^^^^^^^^^^^^
9203
9204Syntax:
9205"""""""
9206
9207This is an overloaded intrinsic. You can use ``llvm.memcpy`` on any
9208integer bit width and for different address spaces. Not all targets
9209support all bit widths however.
9210
9211::
9212
9213 declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
9214 i32 <len>, i32 <align>, i1 <isvolatile>)
9215 declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
9216 i64 <len>, i32 <align>, i1 <isvolatile>)
9217
9218Overview:
9219"""""""""
9220
9221The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
9222source location to the destination location.
9223
9224Note that, unlike the standard libc function, the ``llvm.memcpy.*``
9225intrinsics do not return a value, takes extra alignment/isvolatile
9226arguments and the pointers can be in specified address spaces.
9227
9228Arguments:
9229""""""""""
9230
9231The first argument is a pointer to the destination, the second is a
9232pointer to the source. The third argument is an integer argument
9233specifying the number of bytes to copy, the fourth argument is the
9234alignment of the source and destination locations, and the fifth is a
9235boolean indicating a volatile access.
9236
9237If the call to this intrinsic has an alignment value that is not 0 or 1,
9238then the caller guarantees that both the source and destination pointers
9239are aligned to that boundary.
9240
9241If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy`` call is
9242a :ref:`volatile operation <volatile>`. The detailed access behavior is not
9243very cleanly specified and it is unwise to depend on it.
9244
9245Semantics:
9246""""""""""
9247
9248The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
9249source location to the destination location, which are not allowed to
9250overlap. It copies "len" bytes of memory over. If the argument is known
9251to be aligned to some boundary, this can be specified as the fourth
Bill Wendling61163152013-10-18 23:26:55 +00009252argument, otherwise it should be set to 0 or 1 (both meaning no alignment).
Sean Silvab084af42012-12-07 10:36:55 +00009253
9254'``llvm.memmove``' Intrinsic
9255^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9256
9257Syntax:
9258"""""""
9259
9260This is an overloaded intrinsic. You can use llvm.memmove on any integer
9261bit width and for different address space. Not all targets support all
9262bit widths however.
9263
9264::
9265
9266 declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
9267 i32 <len>, i32 <align>, i1 <isvolatile>)
9268 declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
9269 i64 <len>, i32 <align>, i1 <isvolatile>)
9270
9271Overview:
9272"""""""""
9273
9274The '``llvm.memmove.*``' intrinsics move a block of memory from the
9275source location to the destination location. It is similar to the
9276'``llvm.memcpy``' intrinsic but allows the two memory locations to
9277overlap.
9278
9279Note that, unlike the standard libc function, the ``llvm.memmove.*``
9280intrinsics do not return a value, takes extra alignment/isvolatile
9281arguments and the pointers can be in specified address spaces.
9282
9283Arguments:
9284""""""""""
9285
9286The first argument is a pointer to the destination, the second is a
9287pointer to the source. The third argument is an integer argument
9288specifying the number of bytes to copy, the fourth argument is the
9289alignment of the source and destination locations, and the fifth is a
9290boolean indicating a volatile access.
9291
9292If the call to this intrinsic has an alignment value that is not 0 or 1,
9293then the caller guarantees that the source and destination pointers are
9294aligned to that boundary.
9295
9296If the ``isvolatile`` parameter is ``true``, the ``llvm.memmove`` call
9297is a :ref:`volatile operation <volatile>`. The detailed access behavior is
9298not very cleanly specified and it is unwise to depend on it.
9299
9300Semantics:
9301""""""""""
9302
9303The '``llvm.memmove.*``' intrinsics copy a block of memory from the
9304source location to the destination location, which may overlap. It
9305copies "len" bytes of memory over. If the argument is known to be
9306aligned to some boundary, this can be specified as the fourth argument,
Bill Wendling61163152013-10-18 23:26:55 +00009307otherwise it should be set to 0 or 1 (both meaning no alignment).
Sean Silvab084af42012-12-07 10:36:55 +00009308
9309'``llvm.memset.*``' Intrinsics
9310^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9311
9312Syntax:
9313"""""""
9314
9315This is an overloaded intrinsic. You can use llvm.memset on any integer
9316bit width and for different address spaces. However, not all targets
9317support all bit widths.
9318
9319::
9320
9321 declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>,
9322 i32 <len>, i32 <align>, i1 <isvolatile>)
9323 declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>,
9324 i64 <len>, i32 <align>, i1 <isvolatile>)
9325
9326Overview:
9327"""""""""
9328
9329The '``llvm.memset.*``' intrinsics fill a block of memory with a
9330particular byte value.
9331
9332Note that, unlike the standard libc function, the ``llvm.memset``
9333intrinsic does not return a value and takes extra alignment/volatile
9334arguments. Also, the destination can be in an arbitrary address space.
9335
9336Arguments:
9337""""""""""
9338
9339The first argument is a pointer to the destination to fill, the second
9340is the byte value with which to fill it, the third argument is an
9341integer argument specifying the number of bytes to fill, and the fourth
9342argument is the known alignment of the destination location.
9343
9344If the call to this intrinsic has an alignment value that is not 0 or 1,
9345then the caller guarantees that the destination pointer is aligned to
9346that boundary.
9347
9348If the ``isvolatile`` parameter is ``true``, the ``llvm.memset`` call is
9349a :ref:`volatile operation <volatile>`. The detailed access behavior is not
9350very cleanly specified and it is unwise to depend on it.
9351
9352Semantics:
9353""""""""""
9354
9355The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting
9356at the destination location. If the argument is known to be aligned to
9357some boundary, this can be specified as the fourth argument, otherwise
Bill Wendling61163152013-10-18 23:26:55 +00009358it should be set to 0 or 1 (both meaning no alignment).
Sean Silvab084af42012-12-07 10:36:55 +00009359
9360'``llvm.sqrt.*``' Intrinsic
9361^^^^^^^^^^^^^^^^^^^^^^^^^^^
9362
9363Syntax:
9364"""""""
9365
9366This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any
9367floating point or vector of floating point type. Not all targets support
9368all types however.
9369
9370::
9371
9372 declare float @llvm.sqrt.f32(float %Val)
9373 declare double @llvm.sqrt.f64(double %Val)
9374 declare x86_fp80 @llvm.sqrt.f80(x86_fp80 %Val)
9375 declare fp128 @llvm.sqrt.f128(fp128 %Val)
9376 declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
9377
9378Overview:
9379"""""""""
9380
9381The '``llvm.sqrt``' intrinsics return the sqrt of the specified operand,
9382returning the same value as the libm '``sqrt``' functions would. Unlike
9383``sqrt`` in libm, however, ``llvm.sqrt`` has undefined behavior for
9384negative numbers other than -0.0 (which allows for better optimization,
9385because there is no need to worry about errno being set).
9386``llvm.sqrt(-0.0)`` is defined to return -0.0 like IEEE sqrt.
9387
9388Arguments:
9389""""""""""
9390
9391The argument and return value are floating point numbers of the same
9392type.
9393
9394Semantics:
9395""""""""""
9396
9397This function returns the sqrt of the specified operand if it is a
9398nonnegative floating point number.
9399
9400'``llvm.powi.*``' Intrinsic
9401^^^^^^^^^^^^^^^^^^^^^^^^^^^
9402
9403Syntax:
9404"""""""
9405
9406This is an overloaded intrinsic. You can use ``llvm.powi`` on any
9407floating point or vector of floating point type. Not all targets support
9408all types however.
9409
9410::
9411
9412 declare float @llvm.powi.f32(float %Val, i32 %power)
9413 declare double @llvm.powi.f64(double %Val, i32 %power)
9414 declare x86_fp80 @llvm.powi.f80(x86_fp80 %Val, i32 %power)
9415 declare fp128 @llvm.powi.f128(fp128 %Val, i32 %power)
9416 declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128 %Val, i32 %power)
9417
9418Overview:
9419"""""""""
9420
9421The '``llvm.powi.*``' intrinsics return the first operand raised to the
9422specified (positive or negative) power. The order of evaluation of
9423multiplications is not defined. When a vector of floating point type is
9424used, the second argument remains a scalar integer value.
9425
9426Arguments:
9427""""""""""
9428
9429The second argument is an integer power, and the first is a value to
9430raise to that power.
9431
9432Semantics:
9433""""""""""
9434
9435This function returns the first value raised to the second power with an
9436unspecified sequence of rounding operations.
9437
9438'``llvm.sin.*``' Intrinsic
9439^^^^^^^^^^^^^^^^^^^^^^^^^^
9440
9441Syntax:
9442"""""""
9443
9444This is an overloaded intrinsic. You can use ``llvm.sin`` on any
9445floating point or vector of floating point type. Not all targets support
9446all types however.
9447
9448::
9449
9450 declare float @llvm.sin.f32(float %Val)
9451 declare double @llvm.sin.f64(double %Val)
9452 declare x86_fp80 @llvm.sin.f80(x86_fp80 %Val)
9453 declare fp128 @llvm.sin.f128(fp128 %Val)
9454 declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128 %Val)
9455
9456Overview:
9457"""""""""
9458
9459The '``llvm.sin.*``' intrinsics return the sine of the operand.
9460
9461Arguments:
9462""""""""""
9463
9464The argument and return value are floating point numbers of the same
9465type.
9466
9467Semantics:
9468""""""""""
9469
9470This function returns the sine of the specified operand, returning the
9471same values as the libm ``sin`` functions would, and handles error
9472conditions in the same way.
9473
9474'``llvm.cos.*``' Intrinsic
9475^^^^^^^^^^^^^^^^^^^^^^^^^^
9476
9477Syntax:
9478"""""""
9479
9480This is an overloaded intrinsic. You can use ``llvm.cos`` on any
9481floating point or vector of floating point type. Not all targets support
9482all types however.
9483
9484::
9485
9486 declare float @llvm.cos.f32(float %Val)
9487 declare double @llvm.cos.f64(double %Val)
9488 declare x86_fp80 @llvm.cos.f80(x86_fp80 %Val)
9489 declare fp128 @llvm.cos.f128(fp128 %Val)
9490 declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128 %Val)
9491
9492Overview:
9493"""""""""
9494
9495The '``llvm.cos.*``' intrinsics return the cosine of the operand.
9496
9497Arguments:
9498""""""""""
9499
9500The argument and return value are floating point numbers of the same
9501type.
9502
9503Semantics:
9504""""""""""
9505
9506This function returns the cosine of the specified operand, returning the
9507same values as the libm ``cos`` functions would, and handles error
9508conditions in the same way.
9509
9510'``llvm.pow.*``' Intrinsic
9511^^^^^^^^^^^^^^^^^^^^^^^^^^
9512
9513Syntax:
9514"""""""
9515
9516This is an overloaded intrinsic. You can use ``llvm.pow`` on any
9517floating point or vector of floating point type. Not all targets support
9518all types however.
9519
9520::
9521
9522 declare float @llvm.pow.f32(float %Val, float %Power)
9523 declare double @llvm.pow.f64(double %Val, double %Power)
9524 declare x86_fp80 @llvm.pow.f80(x86_fp80 %Val, x86_fp80 %Power)
9525 declare fp128 @llvm.pow.f128(fp128 %Val, fp128 %Power)
9526 declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128 %Val, ppc_fp128 Power)
9527
9528Overview:
9529"""""""""
9530
9531The '``llvm.pow.*``' intrinsics return the first operand raised to the
9532specified (positive or negative) power.
9533
9534Arguments:
9535""""""""""
9536
9537The second argument is a floating point power, and the first is a value
9538to raise to that power.
9539
9540Semantics:
9541""""""""""
9542
9543This function returns the first value raised to the second power,
9544returning the same values as the libm ``pow`` functions would, and
9545handles error conditions in the same way.
9546
9547'``llvm.exp.*``' Intrinsic
9548^^^^^^^^^^^^^^^^^^^^^^^^^^
9549
9550Syntax:
9551"""""""
9552
9553This is an overloaded intrinsic. You can use ``llvm.exp`` on any
9554floating point or vector of floating point type. Not all targets support
9555all types however.
9556
9557::
9558
9559 declare float @llvm.exp.f32(float %Val)
9560 declare double @llvm.exp.f64(double %Val)
9561 declare x86_fp80 @llvm.exp.f80(x86_fp80 %Val)
9562 declare fp128 @llvm.exp.f128(fp128 %Val)
9563 declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128 %Val)
9564
9565Overview:
9566"""""""""
9567
9568The '``llvm.exp.*``' intrinsics perform the exp function.
9569
9570Arguments:
9571""""""""""
9572
9573The argument and return value are floating point numbers of the same
9574type.
9575
9576Semantics:
9577""""""""""
9578
9579This function returns the same values as the libm ``exp`` functions
9580would, and handles error conditions in the same way.
9581
9582'``llvm.exp2.*``' Intrinsic
9583^^^^^^^^^^^^^^^^^^^^^^^^^^^
9584
9585Syntax:
9586"""""""
9587
9588This is an overloaded intrinsic. You can use ``llvm.exp2`` on any
9589floating point or vector of floating point type. Not all targets support
9590all types however.
9591
9592::
9593
9594 declare float @llvm.exp2.f32(float %Val)
9595 declare double @llvm.exp2.f64(double %Val)
9596 declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val)
9597 declare fp128 @llvm.exp2.f128(fp128 %Val)
9598 declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val)
9599
9600Overview:
9601"""""""""
9602
9603The '``llvm.exp2.*``' intrinsics perform the exp2 function.
9604
9605Arguments:
9606""""""""""
9607
9608The argument and return value are floating point numbers of the same
9609type.
9610
9611Semantics:
9612""""""""""
9613
9614This function returns the same values as the libm ``exp2`` functions
9615would, and handles error conditions in the same way.
9616
9617'``llvm.log.*``' Intrinsic
9618^^^^^^^^^^^^^^^^^^^^^^^^^^
9619
9620Syntax:
9621"""""""
9622
9623This is an overloaded intrinsic. You can use ``llvm.log`` on any
9624floating point or vector of floating point type. Not all targets support
9625all types however.
9626
9627::
9628
9629 declare float @llvm.log.f32(float %Val)
9630 declare double @llvm.log.f64(double %Val)
9631 declare x86_fp80 @llvm.log.f80(x86_fp80 %Val)
9632 declare fp128 @llvm.log.f128(fp128 %Val)
9633 declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128 %Val)
9634
9635Overview:
9636"""""""""
9637
9638The '``llvm.log.*``' intrinsics perform the log function.
9639
9640Arguments:
9641""""""""""
9642
9643The argument and return value are floating point numbers of the same
9644type.
9645
9646Semantics:
9647""""""""""
9648
9649This function returns the same values as the libm ``log`` functions
9650would, and handles error conditions in the same way.
9651
9652'``llvm.log10.*``' Intrinsic
9653^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9654
9655Syntax:
9656"""""""
9657
9658This is an overloaded intrinsic. You can use ``llvm.log10`` on any
9659floating point or vector of floating point type. Not all targets support
9660all types however.
9661
9662::
9663
9664 declare float @llvm.log10.f32(float %Val)
9665 declare double @llvm.log10.f64(double %Val)
9666 declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val)
9667 declare fp128 @llvm.log10.f128(fp128 %Val)
9668 declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val)
9669
9670Overview:
9671"""""""""
9672
9673The '``llvm.log10.*``' intrinsics perform the log10 function.
9674
9675Arguments:
9676""""""""""
9677
9678The argument and return value are floating point numbers of the same
9679type.
9680
9681Semantics:
9682""""""""""
9683
9684This function returns the same values as the libm ``log10`` functions
9685would, and handles error conditions in the same way.
9686
9687'``llvm.log2.*``' Intrinsic
9688^^^^^^^^^^^^^^^^^^^^^^^^^^^
9689
9690Syntax:
9691"""""""
9692
9693This is an overloaded intrinsic. You can use ``llvm.log2`` on any
9694floating point or vector of floating point type. Not all targets support
9695all types however.
9696
9697::
9698
9699 declare float @llvm.log2.f32(float %Val)
9700 declare double @llvm.log2.f64(double %Val)
9701 declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val)
9702 declare fp128 @llvm.log2.f128(fp128 %Val)
9703 declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val)
9704
9705Overview:
9706"""""""""
9707
9708The '``llvm.log2.*``' intrinsics perform the log2 function.
9709
9710Arguments:
9711""""""""""
9712
9713The argument and return value are floating point numbers of the same
9714type.
9715
9716Semantics:
9717""""""""""
9718
9719This function returns the same values as the libm ``log2`` functions
9720would, and handles error conditions in the same way.
9721
9722'``llvm.fma.*``' Intrinsic
9723^^^^^^^^^^^^^^^^^^^^^^^^^^
9724
9725Syntax:
9726"""""""
9727
9728This is an overloaded intrinsic. You can use ``llvm.fma`` on any
9729floating point or vector of floating point type. Not all targets support
9730all types however.
9731
9732::
9733
9734 declare float @llvm.fma.f32(float %a, float %b, float %c)
9735 declare double @llvm.fma.f64(double %a, double %b, double %c)
9736 declare x86_fp80 @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c)
9737 declare fp128 @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c)
9738 declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c)
9739
9740Overview:
9741"""""""""
9742
9743The '``llvm.fma.*``' intrinsics perform the fused multiply-add
9744operation.
9745
9746Arguments:
9747""""""""""
9748
9749The argument and return value are floating point numbers of the same
9750type.
9751
9752Semantics:
9753""""""""""
9754
9755This function returns the same values as the libm ``fma`` functions
Matt Arsenaultee364ee2014-01-31 00:09:00 +00009756would, and does not set errno.
Sean Silvab084af42012-12-07 10:36:55 +00009757
9758'``llvm.fabs.*``' Intrinsic
9759^^^^^^^^^^^^^^^^^^^^^^^^^^^
9760
9761Syntax:
9762"""""""
9763
9764This is an overloaded intrinsic. You can use ``llvm.fabs`` on any
9765floating point or vector of floating point type. Not all targets support
9766all types however.
9767
9768::
9769
9770 declare float @llvm.fabs.f32(float %Val)
9771 declare double @llvm.fabs.f64(double %Val)
Matt Arsenaultd6511b42014-10-21 23:00:20 +00009772 declare x86_fp80 @llvm.fabs.f80(x86_fp80 %Val)
Sean Silvab084af42012-12-07 10:36:55 +00009773 declare fp128 @llvm.fabs.f128(fp128 %Val)
Matt Arsenaultd6511b42014-10-21 23:00:20 +00009774 declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128 %Val)
Sean Silvab084af42012-12-07 10:36:55 +00009775
9776Overview:
9777"""""""""
9778
9779The '``llvm.fabs.*``' intrinsics return the absolute value of the
9780operand.
9781
9782Arguments:
9783""""""""""
9784
9785The argument and return value are floating point numbers of the same
9786type.
9787
9788Semantics:
9789""""""""""
9790
9791This function returns the same values as the libm ``fabs`` functions
9792would, and handles error conditions in the same way.
9793
Matt Arsenaultd6511b42014-10-21 23:00:20 +00009794'``llvm.minnum.*``' Intrinsic
Matt Arsenault9886b0d2014-10-22 00:15:53 +00009795^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Matt Arsenaultd6511b42014-10-21 23:00:20 +00009796
9797Syntax:
9798"""""""
9799
9800This is an overloaded intrinsic. You can use ``llvm.minnum`` on any
9801floating point or vector of floating point type. Not all targets support
9802all types however.
9803
9804::
9805
Matt Arsenault64313c92014-10-22 18:25:02 +00009806 declare float @llvm.minnum.f32(float %Val0, float %Val1)
9807 declare double @llvm.minnum.f64(double %Val0, double %Val1)
9808 declare x86_fp80 @llvm.minnum.f80(x86_fp80 %Val0, x86_fp80 %Val1)
9809 declare fp128 @llvm.minnum.f128(fp128 %Val0, fp128 %Val1)
9810 declare ppc_fp128 @llvm.minnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1)
Matt Arsenaultd6511b42014-10-21 23:00:20 +00009811
9812Overview:
9813"""""""""
9814
9815The '``llvm.minnum.*``' intrinsics return the minimum of the two
9816arguments.
9817
9818
9819Arguments:
9820""""""""""
9821
9822The arguments and return value are floating point numbers of the same
9823type.
9824
9825Semantics:
9826""""""""""
9827
9828Follows the IEEE-754 semantics for minNum, which also match for libm's
9829fmin.
9830
9831If either operand is a NaN, returns the other non-NaN operand. Returns
9832NaN only if both operands are NaN. If the operands compare equal,
9833returns a value that compares equal to both operands. This means that
9834fmin(+/-0.0, +/-0.0) could return either -0.0 or 0.0.
9835
9836'``llvm.maxnum.*``' Intrinsic
Matt Arsenault9886b0d2014-10-22 00:15:53 +00009837^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Matt Arsenaultd6511b42014-10-21 23:00:20 +00009838
9839Syntax:
9840"""""""
9841
9842This is an overloaded intrinsic. You can use ``llvm.maxnum`` on any
9843floating point or vector of floating point type. Not all targets support
9844all types however.
9845
9846::
9847
Matt Arsenault64313c92014-10-22 18:25:02 +00009848 declare float @llvm.maxnum.f32(float %Val0, float %Val1l)
9849 declare double @llvm.maxnum.f64(double %Val0, double %Val1)
9850 declare x86_fp80 @llvm.maxnum.f80(x86_fp80 %Val0, x86_fp80 %Val1)
9851 declare fp128 @llvm.maxnum.f128(fp128 %Val0, fp128 %Val1)
9852 declare ppc_fp128 @llvm.maxnum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1)
Matt Arsenaultd6511b42014-10-21 23:00:20 +00009853
9854Overview:
9855"""""""""
9856
9857The '``llvm.maxnum.*``' intrinsics return the maximum of the two
9858arguments.
9859
9860
9861Arguments:
9862""""""""""
9863
9864The arguments and return value are floating point numbers of the same
9865type.
9866
9867Semantics:
9868""""""""""
9869Follows the IEEE-754 semantics for maxNum, which also match for libm's
9870fmax.
9871
9872If either operand is a NaN, returns the other non-NaN operand. Returns
9873NaN only if both operands are NaN. If the operands compare equal,
9874returns a value that compares equal to both operands. This means that
9875fmax(+/-0.0, +/-0.0) could return either -0.0 or 0.0.
9876
Hal Finkel0c5c01aa2013-08-19 23:35:46 +00009877'``llvm.copysign.*``' Intrinsic
9878^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9879
9880Syntax:
9881"""""""
9882
9883This is an overloaded intrinsic. You can use ``llvm.copysign`` on any
9884floating point or vector of floating point type. Not all targets support
9885all types however.
9886
9887::
9888
9889 declare float @llvm.copysign.f32(float %Mag, float %Sgn)
9890 declare double @llvm.copysign.f64(double %Mag, double %Sgn)
9891 declare x86_fp80 @llvm.copysign.f80(x86_fp80 %Mag, x86_fp80 %Sgn)
9892 declare fp128 @llvm.copysign.f128(fp128 %Mag, fp128 %Sgn)
9893 declare ppc_fp128 @llvm.copysign.ppcf128(ppc_fp128 %Mag, ppc_fp128 %Sgn)
9894
9895Overview:
9896"""""""""
9897
9898The '``llvm.copysign.*``' intrinsics return a value with the magnitude of the
9899first operand and the sign of the second operand.
9900
9901Arguments:
9902""""""""""
9903
9904The arguments and return value are floating point numbers of the same
9905type.
9906
9907Semantics:
9908""""""""""
9909
9910This function returns the same values as the libm ``copysign``
9911functions would, and handles error conditions in the same way.
9912
Sean Silvab084af42012-12-07 10:36:55 +00009913'``llvm.floor.*``' Intrinsic
9914^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9915
9916Syntax:
9917"""""""
9918
9919This is an overloaded intrinsic. You can use ``llvm.floor`` on any
9920floating point or vector of floating point type. Not all targets support
9921all types however.
9922
9923::
9924
9925 declare float @llvm.floor.f32(float %Val)
9926 declare double @llvm.floor.f64(double %Val)
9927 declare x86_fp80 @llvm.floor.f80(x86_fp80 %Val)
9928 declare fp128 @llvm.floor.f128(fp128 %Val)
9929 declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128 %Val)
9930
9931Overview:
9932"""""""""
9933
9934The '``llvm.floor.*``' intrinsics return the floor of the operand.
9935
9936Arguments:
9937""""""""""
9938
9939The argument and return value are floating point numbers of the same
9940type.
9941
9942Semantics:
9943""""""""""
9944
9945This function returns the same values as the libm ``floor`` functions
9946would, and handles error conditions in the same way.
9947
9948'``llvm.ceil.*``' Intrinsic
9949^^^^^^^^^^^^^^^^^^^^^^^^^^^
9950
9951Syntax:
9952"""""""
9953
9954This is an overloaded intrinsic. You can use ``llvm.ceil`` on any
9955floating point or vector of floating point type. Not all targets support
9956all types however.
9957
9958::
9959
9960 declare float @llvm.ceil.f32(float %Val)
9961 declare double @llvm.ceil.f64(double %Val)
9962 declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val)
9963 declare fp128 @llvm.ceil.f128(fp128 %Val)
9964 declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val)
9965
9966Overview:
9967"""""""""
9968
9969The '``llvm.ceil.*``' intrinsics return the ceiling of the operand.
9970
9971Arguments:
9972""""""""""
9973
9974The argument and return value are floating point numbers of the same
9975type.
9976
9977Semantics:
9978""""""""""
9979
9980This function returns the same values as the libm ``ceil`` functions
9981would, and handles error conditions in the same way.
9982
9983'``llvm.trunc.*``' Intrinsic
9984^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9985
9986Syntax:
9987"""""""
9988
9989This is an overloaded intrinsic. You can use ``llvm.trunc`` on any
9990floating point or vector of floating point type. Not all targets support
9991all types however.
9992
9993::
9994
9995 declare float @llvm.trunc.f32(float %Val)
9996 declare double @llvm.trunc.f64(double %Val)
9997 declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val)
9998 declare fp128 @llvm.trunc.f128(fp128 %Val)
9999 declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val)
10000
10001Overview:
10002"""""""""
10003
10004The '``llvm.trunc.*``' intrinsics returns the operand rounded to the
10005nearest integer not larger in magnitude than the operand.
10006
10007Arguments:
10008""""""""""
10009
10010The argument and return value are floating point numbers of the same
10011type.
10012
10013Semantics:
10014""""""""""
10015
10016This function returns the same values as the libm ``trunc`` functions
10017would, and handles error conditions in the same way.
10018
10019'``llvm.rint.*``' Intrinsic
10020^^^^^^^^^^^^^^^^^^^^^^^^^^^
10021
10022Syntax:
10023"""""""
10024
10025This is an overloaded intrinsic. You can use ``llvm.rint`` on any
10026floating point or vector of floating point type. Not all targets support
10027all types however.
10028
10029::
10030
10031 declare float @llvm.rint.f32(float %Val)
10032 declare double @llvm.rint.f64(double %Val)
10033 declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val)
10034 declare fp128 @llvm.rint.f128(fp128 %Val)
10035 declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val)
10036
10037Overview:
10038"""""""""
10039
10040The '``llvm.rint.*``' intrinsics returns the operand rounded to the
10041nearest integer. It may raise an inexact floating-point exception if the
10042operand isn't an integer.
10043
10044Arguments:
10045""""""""""
10046
10047The argument and return value are floating point numbers of the same
10048type.
10049
10050Semantics:
10051""""""""""
10052
10053This function returns the same values as the libm ``rint`` functions
10054would, and handles error conditions in the same way.
10055
10056'``llvm.nearbyint.*``' Intrinsic
10057^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10058
10059Syntax:
10060"""""""
10061
10062This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any
10063floating point or vector of floating point type. Not all targets support
10064all types however.
10065
10066::
10067
10068 declare float @llvm.nearbyint.f32(float %Val)
10069 declare double @llvm.nearbyint.f64(double %Val)
10070 declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val)
10071 declare fp128 @llvm.nearbyint.f128(fp128 %Val)
10072 declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val)
10073
10074Overview:
10075"""""""""
10076
10077The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the
10078nearest integer.
10079
10080Arguments:
10081""""""""""
10082
10083The argument and return value are floating point numbers of the same
10084type.
10085
10086Semantics:
10087""""""""""
10088
10089This function returns the same values as the libm ``nearbyint``
10090functions would, and handles error conditions in the same way.
10091
Hal Finkel171817e2013-08-07 22:49:12 +000010092'``llvm.round.*``' Intrinsic
10093^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10094
10095Syntax:
10096"""""""
10097
10098This is an overloaded intrinsic. You can use ``llvm.round`` on any
10099floating point or vector of floating point type. Not all targets support
10100all types however.
10101
10102::
10103
10104 declare float @llvm.round.f32(float %Val)
10105 declare double @llvm.round.f64(double %Val)
10106 declare x86_fp80 @llvm.round.f80(x86_fp80 %Val)
10107 declare fp128 @llvm.round.f128(fp128 %Val)
10108 declare ppc_fp128 @llvm.round.ppcf128(ppc_fp128 %Val)
10109
10110Overview:
10111"""""""""
10112
10113The '``llvm.round.*``' intrinsics returns the operand rounded to the
10114nearest integer.
10115
10116Arguments:
10117""""""""""
10118
10119The argument and return value are floating point numbers of the same
10120type.
10121
10122Semantics:
10123""""""""""
10124
10125This function returns the same values as the libm ``round``
10126functions would, and handles error conditions in the same way.
10127
Sean Silvab084af42012-12-07 10:36:55 +000010128Bit Manipulation Intrinsics
10129---------------------------
10130
10131LLVM provides intrinsics for a few important bit manipulation
10132operations. These allow efficient code generation for some algorithms.
10133
10134'``llvm.bswap.*``' Intrinsics
10135^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10136
10137Syntax:
10138"""""""
10139
10140This is an overloaded intrinsic function. You can use bswap on any
10141integer type that is an even number of bytes (i.e. BitWidth % 16 == 0).
10142
10143::
10144
10145 declare i16 @llvm.bswap.i16(i16 <id>)
10146 declare i32 @llvm.bswap.i32(i32 <id>)
10147 declare i64 @llvm.bswap.i64(i64 <id>)
10148
10149Overview:
10150"""""""""
10151
10152The '``llvm.bswap``' family of intrinsics is used to byte swap integer
10153values with an even number of bytes (positive multiple of 16 bits).
10154These are useful for performing operations on data that is not in the
10155target's native byte order.
10156
10157Semantics:
10158""""""""""
10159
10160The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high
10161and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32``
10162intrinsic returns an i32 value that has the four bytes of the input i32
10163swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the
10164returned i32 will have its bytes in 3, 2, 1, 0 order. The
10165``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this
10166concept to additional even-byte lengths (6 bytes, 8 bytes and more,
10167respectively).
10168
10169'``llvm.ctpop.*``' Intrinsic
10170^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10171
10172Syntax:
10173"""""""
10174
10175This is an overloaded intrinsic. You can use llvm.ctpop on any integer
10176bit width, or on any vector with integer elements. Not all targets
10177support all bit widths or vector types, however.
10178
10179::
10180
10181 declare i8 @llvm.ctpop.i8(i8 <src>)
10182 declare i16 @llvm.ctpop.i16(i16 <src>)
10183 declare i32 @llvm.ctpop.i32(i32 <src>)
10184 declare i64 @llvm.ctpop.i64(i64 <src>)
10185 declare i256 @llvm.ctpop.i256(i256 <src>)
10186 declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>)
10187
10188Overview:
10189"""""""""
10190
10191The '``llvm.ctpop``' family of intrinsics counts the number of bits set
10192in a value.
10193
10194Arguments:
10195""""""""""
10196
10197The only argument is the value to be counted. The argument may be of any
10198integer type, or a vector with integer elements. The return type must
10199match the argument type.
10200
10201Semantics:
10202""""""""""
10203
10204The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within
10205each element of a vector.
10206
10207'``llvm.ctlz.*``' Intrinsic
10208^^^^^^^^^^^^^^^^^^^^^^^^^^^
10209
10210Syntax:
10211"""""""
10212
10213This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any
10214integer bit width, or any vector whose elements are integers. Not all
10215targets support all bit widths or vector types, however.
10216
10217::
10218
10219 declare i8 @llvm.ctlz.i8 (i8 <src>, i1 <is_zero_undef>)
10220 declare i16 @llvm.ctlz.i16 (i16 <src>, i1 <is_zero_undef>)
10221 declare i32 @llvm.ctlz.i32 (i32 <src>, i1 <is_zero_undef>)
10222 declare i64 @llvm.ctlz.i64 (i64 <src>, i1 <is_zero_undef>)
10223 declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>)
10224 declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
10225
10226Overview:
10227"""""""""
10228
10229The '``llvm.ctlz``' family of intrinsic functions counts the number of
10230leading zeros in a variable.
10231
10232Arguments:
10233""""""""""
10234
10235The first argument is the value to be counted. This argument may be of
Hal Finkel5dd82782015-01-05 04:05:21 +000010236any integer type, or a vector with integer element type. The return
Sean Silvab084af42012-12-07 10:36:55 +000010237type must match the first argument type.
10238
10239The second argument must be a constant and is a flag to indicate whether
10240the intrinsic should ensure that a zero as the first argument produces a
10241defined result. Historically some architectures did not provide a
10242defined result for zero values as efficiently, and many algorithms are
10243now predicated on avoiding zero-value inputs.
10244
10245Semantics:
10246""""""""""
10247
10248The '``llvm.ctlz``' intrinsic counts the leading (most significant)
10249zeros in a variable, or within each element of the vector. If
10250``src == 0`` then the result is the size in bits of the type of ``src``
10251if ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
10252``llvm.ctlz(i32 2) = 30``.
10253
10254'``llvm.cttz.*``' Intrinsic
10255^^^^^^^^^^^^^^^^^^^^^^^^^^^
10256
10257Syntax:
10258"""""""
10259
10260This is an overloaded intrinsic. You can use ``llvm.cttz`` on any
10261integer bit width, or any vector of integer elements. Not all targets
10262support all bit widths or vector types, however.
10263
10264::
10265
10266 declare i8 @llvm.cttz.i8 (i8 <src>, i1 <is_zero_undef>)
10267 declare i16 @llvm.cttz.i16 (i16 <src>, i1 <is_zero_undef>)
10268 declare i32 @llvm.cttz.i32 (i32 <src>, i1 <is_zero_undef>)
10269 declare i64 @llvm.cttz.i64 (i64 <src>, i1 <is_zero_undef>)
10270 declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>)
10271 declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
10272
10273Overview:
10274"""""""""
10275
10276The '``llvm.cttz``' family of intrinsic functions counts the number of
10277trailing zeros.
10278
10279Arguments:
10280""""""""""
10281
10282The first argument is the value to be counted. This argument may be of
Hal Finkel5dd82782015-01-05 04:05:21 +000010283any integer type, or a vector with integer element type. The return
Sean Silvab084af42012-12-07 10:36:55 +000010284type must match the first argument type.
10285
10286The second argument must be a constant and is a flag to indicate whether
10287the intrinsic should ensure that a zero as the first argument produces a
10288defined result. Historically some architectures did not provide a
10289defined result for zero values as efficiently, and many algorithms are
10290now predicated on avoiding zero-value inputs.
10291
10292Semantics:
10293""""""""""
10294
10295The '``llvm.cttz``' intrinsic counts the trailing (least significant)
10296zeros in a variable, or within each element of a vector. If ``src == 0``
10297then the result is the size in bits of the type of ``src`` if
10298``is_zero_undef == 0`` and ``undef`` otherwise. For example,
10299``llvm.cttz(2) = 1``.
10300
Philip Reames34843ae2015-03-05 05:55:55 +000010301.. _int_overflow:
10302
Sean Silvab084af42012-12-07 10:36:55 +000010303Arithmetic with Overflow Intrinsics
10304-----------------------------------
10305
10306LLVM provides intrinsics for some arithmetic with overflow operations.
10307
10308'``llvm.sadd.with.overflow.*``' Intrinsics
10309^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10310
10311Syntax:
10312"""""""
10313
10314This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow``
10315on any integer bit width.
10316
10317::
10318
10319 declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
10320 declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
10321 declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
10322
10323Overview:
10324"""""""""
10325
10326The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
10327a signed addition of the two arguments, and indicate whether an overflow
10328occurred during the signed summation.
10329
10330Arguments:
10331""""""""""
10332
10333The arguments (%a and %b) and the first element of the result structure
10334may be of integer types of any bit width, but they must have the same
10335bit width. The second element of the result structure must be of type
10336``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
10337addition.
10338
10339Semantics:
10340""""""""""
10341
10342The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
Dmitri Gribenkoe8131122013-01-19 20:34:20 +000010343a signed addition of the two variables. They return a structure --- the
Sean Silvab084af42012-12-07 10:36:55 +000010344first element of which is the signed summation, and the second element
10345of which is a bit specifying if the signed summation resulted in an
10346overflow.
10347
10348Examples:
10349"""""""""
10350
10351.. code-block:: llvm
10352
10353 %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
10354 %sum = extractvalue {i32, i1} %res, 0
10355 %obit = extractvalue {i32, i1} %res, 1
10356 br i1 %obit, label %overflow, label %normal
10357
10358'``llvm.uadd.with.overflow.*``' Intrinsics
10359^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10360
10361Syntax:
10362"""""""
10363
10364This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow``
10365on any integer bit width.
10366
10367::
10368
10369 declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
10370 declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
10371 declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
10372
10373Overview:
10374"""""""""
10375
10376The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
10377an unsigned addition of the two arguments, and indicate whether a carry
10378occurred during the unsigned summation.
10379
10380Arguments:
10381""""""""""
10382
10383The arguments (%a and %b) and the first element of the result structure
10384may be of integer types of any bit width, but they must have the same
10385bit width. The second element of the result structure must be of type
10386``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
10387addition.
10388
10389Semantics:
10390""""""""""
10391
10392The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
Dmitri Gribenkoe8131122013-01-19 20:34:20 +000010393an unsigned addition of the two arguments. They return a structure --- the
Sean Silvab084af42012-12-07 10:36:55 +000010394first element of which is the sum, and the second element of which is a
10395bit specifying if the unsigned summation resulted in a carry.
10396
10397Examples:
10398"""""""""
10399
10400.. code-block:: llvm
10401
10402 %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
10403 %sum = extractvalue {i32, i1} %res, 0
10404 %obit = extractvalue {i32, i1} %res, 1
10405 br i1 %obit, label %carry, label %normal
10406
10407'``llvm.ssub.with.overflow.*``' Intrinsics
10408^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10409
10410Syntax:
10411"""""""
10412
10413This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow``
10414on any integer bit width.
10415
10416::
10417
10418 declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
10419 declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
10420 declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
10421
10422Overview:
10423"""""""""
10424
10425The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
10426a signed subtraction of the two arguments, and indicate whether an
10427overflow occurred during the signed subtraction.
10428
10429Arguments:
10430""""""""""
10431
10432The arguments (%a and %b) and the first element of the result structure
10433may be of integer types of any bit width, but they must have the same
10434bit width. The second element of the result structure must be of type
10435``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
10436subtraction.
10437
10438Semantics:
10439""""""""""
10440
10441The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
Dmitri Gribenkoe8131122013-01-19 20:34:20 +000010442a signed subtraction of the two arguments. They return a structure --- the
Sean Silvab084af42012-12-07 10:36:55 +000010443first element of which is the subtraction, and the second element of
10444which is a bit specifying if the signed subtraction resulted in an
10445overflow.
10446
10447Examples:
10448"""""""""
10449
10450.. code-block:: llvm
10451
10452 %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
10453 %sum = extractvalue {i32, i1} %res, 0
10454 %obit = extractvalue {i32, i1} %res, 1
10455 br i1 %obit, label %overflow, label %normal
10456
10457'``llvm.usub.with.overflow.*``' Intrinsics
10458^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10459
10460Syntax:
10461"""""""
10462
10463This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow``
10464on any integer bit width.
10465
10466::
10467
10468 declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
10469 declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
10470 declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
10471
10472Overview:
10473"""""""""
10474
10475The '``llvm.usub.with.overflow``' family of intrinsic functions perform
10476an unsigned subtraction of the two arguments, and indicate whether an
10477overflow occurred during the unsigned subtraction.
10478
10479Arguments:
10480""""""""""
10481
10482The arguments (%a and %b) and the first element of the result structure
10483may be of integer types of any bit width, but they must have the same
10484bit width. The second element of the result structure must be of type
10485``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
10486subtraction.
10487
10488Semantics:
10489""""""""""
10490
10491The '``llvm.usub.with.overflow``' family of intrinsic functions perform
Dmitri Gribenkoe8131122013-01-19 20:34:20 +000010492an unsigned subtraction of the two arguments. They return a structure ---
Sean Silvab084af42012-12-07 10:36:55 +000010493the first element of which is the subtraction, and the second element of
10494which is a bit specifying if the unsigned subtraction resulted in an
10495overflow.
10496
10497Examples:
10498"""""""""
10499
10500.. code-block:: llvm
10501
10502 %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
10503 %sum = extractvalue {i32, i1} %res, 0
10504 %obit = extractvalue {i32, i1} %res, 1
10505 br i1 %obit, label %overflow, label %normal
10506
10507'``llvm.smul.with.overflow.*``' Intrinsics
10508^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10509
10510Syntax:
10511"""""""
10512
10513This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow``
10514on any integer bit width.
10515
10516::
10517
10518 declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
10519 declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
10520 declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
10521
10522Overview:
10523"""""""""
10524
10525The '``llvm.smul.with.overflow``' family of intrinsic functions perform
10526a signed multiplication of the two arguments, and indicate whether an
10527overflow occurred during the signed multiplication.
10528
10529Arguments:
10530""""""""""
10531
10532The arguments (%a and %b) and the first element of the result structure
10533may be of integer types of any bit width, but they must have the same
10534bit width. The second element of the result structure must be of type
10535``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
10536multiplication.
10537
10538Semantics:
10539""""""""""
10540
10541The '``llvm.smul.with.overflow``' family of intrinsic functions perform
Dmitri Gribenkoe8131122013-01-19 20:34:20 +000010542a signed multiplication of the two arguments. They return a structure ---
Sean Silvab084af42012-12-07 10:36:55 +000010543the first element of which is the multiplication, and the second element
10544of which is a bit specifying if the signed multiplication resulted in an
10545overflow.
10546
10547Examples:
10548"""""""""
10549
10550.. code-block:: llvm
10551
10552 %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
10553 %sum = extractvalue {i32, i1} %res, 0
10554 %obit = extractvalue {i32, i1} %res, 1
10555 br i1 %obit, label %overflow, label %normal
10556
10557'``llvm.umul.with.overflow.*``' Intrinsics
10558^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10559
10560Syntax:
10561"""""""
10562
10563This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow``
10564on any integer bit width.
10565
10566::
10567
10568 declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
10569 declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
10570 declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
10571
10572Overview:
10573"""""""""
10574
10575The '``llvm.umul.with.overflow``' family of intrinsic functions perform
10576a unsigned multiplication of the two arguments, and indicate whether an
10577overflow occurred during the unsigned multiplication.
10578
10579Arguments:
10580""""""""""
10581
10582The arguments (%a and %b) and the first element of the result structure
10583may be of integer types of any bit width, but they must have the same
10584bit width. The second element of the result structure must be of type
10585``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
10586multiplication.
10587
10588Semantics:
10589""""""""""
10590
10591The '``llvm.umul.with.overflow``' family of intrinsic functions perform
Dmitri Gribenkoe8131122013-01-19 20:34:20 +000010592an unsigned multiplication of the two arguments. They return a structure ---
10593the first element of which is the multiplication, and the second
Sean Silvab084af42012-12-07 10:36:55 +000010594element of which is a bit specifying if the unsigned multiplication
10595resulted in an overflow.
10596
10597Examples:
10598"""""""""
10599
10600.. code-block:: llvm
10601
10602 %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
10603 %sum = extractvalue {i32, i1} %res, 0
10604 %obit = extractvalue {i32, i1} %res, 1
10605 br i1 %obit, label %overflow, label %normal
10606
10607Specialised Arithmetic Intrinsics
10608---------------------------------
10609
Owen Anderson1056a922015-07-11 07:01:27 +000010610'``llvm.canonicalize.*``' Intrinsic
10611^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10612
10613Syntax:
10614"""""""
10615
10616::
10617
10618 declare float @llvm.canonicalize.f32(float %a)
10619 declare double @llvm.canonicalize.f64(double %b)
10620
10621Overview:
10622"""""""""
10623
10624The '``llvm.canonicalize.*``' intrinsic returns the platform specific canonical
Sean Silvaa1190322015-08-06 22:56:48 +000010625encoding of a floating point number. This canonicalization is useful for
Owen Anderson1056a922015-07-11 07:01:27 +000010626implementing certain numeric primitives such as frexp. The canonical encoding is
10627defined by IEEE-754-2008 to be:
10628
10629::
10630
10631 2.1.8 canonical encoding: The preferred encoding of a floating-point
Sean Silvaa1190322015-08-06 22:56:48 +000010632 representation in a format. Applied to declets, significands of finite
Owen Anderson1056a922015-07-11 07:01:27 +000010633 numbers, infinities, and NaNs, especially in decimal formats.
10634
10635This operation can also be considered equivalent to the IEEE-754-2008
Sean Silvaa1190322015-08-06 22:56:48 +000010636conversion of a floating-point value to the same format. NaNs are handled
Owen Anderson1056a922015-07-11 07:01:27 +000010637according to section 6.2.
10638
10639Examples of non-canonical encodings:
10640
Sean Silvaa1190322015-08-06 22:56:48 +000010641- x87 pseudo denormals, pseudo NaNs, pseudo Infinity, Unnormals. These are
Owen Anderson1056a922015-07-11 07:01:27 +000010642 converted to a canonical representation per hardware-specific protocol.
10643- Many normal decimal floating point numbers have non-canonical alternative
10644 encodings.
10645- Some machines, like GPUs or ARMv7 NEON, do not support subnormal values.
10646 These are treated as non-canonical encodings of zero and with be flushed to
10647 a zero of the same sign by this operation.
10648
10649Note that per IEEE-754-2008 6.2, systems that support signaling NaNs with
10650default exception handling must signal an invalid exception, and produce a
10651quiet NaN result.
10652
10653This function should always be implementable as multiplication by 1.0, provided
Sean Silvaa1190322015-08-06 22:56:48 +000010654that the compiler does not constant fold the operation. Likewise, division by
106551.0 and ``llvm.minnum(x, x)`` are possible implementations. Addition with
Owen Anderson1056a922015-07-11 07:01:27 +000010656-0.0 is also sufficient provided that the rounding mode is not -Infinity.
10657
Sean Silvaa1190322015-08-06 22:56:48 +000010658``@llvm.canonicalize`` must preserve the equality relation. That is:
Owen Anderson1056a922015-07-11 07:01:27 +000010659
10660- ``(@llvm.canonicalize(x) == x)`` is equivalent to ``(x == x)``
10661- ``(@llvm.canonicalize(x) == @llvm.canonicalize(y))`` is equivalent to
10662 to ``(x == y)``
10663
10664Additionally, the sign of zero must be conserved:
10665``@llvm.canonicalize(-0.0) = -0.0`` and ``@llvm.canonicalize(+0.0) = +0.0``
10666
10667The payload bits of a NaN must be conserved, with two exceptions.
10668First, environments which use only a single canonical representation of NaN
Sean Silvaa1190322015-08-06 22:56:48 +000010669must perform said canonicalization. Second, SNaNs must be quieted per the
Owen Anderson1056a922015-07-11 07:01:27 +000010670usual methods.
10671
10672The canonicalization operation may be optimized away if:
10673
Sean Silvaa1190322015-08-06 22:56:48 +000010674- The input is known to be canonical. For example, it was produced by a
Owen Anderson1056a922015-07-11 07:01:27 +000010675 floating-point operation that is required by the standard to be canonical.
10676- The result is consumed only by (or fused with) other floating-point
Sean Silvaa1190322015-08-06 22:56:48 +000010677 operations. That is, the bits of the floating point value are not examined.
Owen Anderson1056a922015-07-11 07:01:27 +000010678
Sean Silvab084af42012-12-07 10:36:55 +000010679'``llvm.fmuladd.*``' Intrinsic
10680^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10681
10682Syntax:
10683"""""""
10684
10685::
10686
10687 declare float @llvm.fmuladd.f32(float %a, float %b, float %c)
10688 declare double @llvm.fmuladd.f64(double %a, double %b, double %c)
10689
10690Overview:
10691"""""""""
10692
10693The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add
Lang Hames045f4392013-01-17 00:00:49 +000010694expressions that can be fused if the code generator determines that (a) the
10695target instruction set has support for a fused operation, and (b) that the
10696fused operation is more efficient than the equivalent, separate pair of mul
10697and add instructions.
Sean Silvab084af42012-12-07 10:36:55 +000010698
10699Arguments:
10700""""""""""
10701
10702The '``llvm.fmuladd.*``' intrinsics each take three arguments: two
10703multiplicands, a and b, and an addend c.
10704
10705Semantics:
10706""""""""""
10707
10708The expression:
10709
10710::
10711
10712 %0 = call float @llvm.fmuladd.f32(%a, %b, %c)
10713
10714is equivalent to the expression a \* b + c, except that rounding will
10715not be performed between the multiplication and addition steps if the
10716code generator fuses the operations. Fusion is not guaranteed, even if
10717the target platform supports it. If a fused multiply-add is required the
Matt Arsenaultee364ee2014-01-31 00:09:00 +000010718corresponding llvm.fma.\* intrinsic function should be used
10719instead. This never sets errno, just as '``llvm.fma.*``'.
Sean Silvab084af42012-12-07 10:36:55 +000010720
10721Examples:
10722"""""""""
10723
10724.. code-block:: llvm
10725
Tim Northover675a0962014-06-13 14:24:23 +000010726 %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields float:r2 = (a * b) + c
Sean Silvab084af42012-12-07 10:36:55 +000010727
James Molloy7395a812015-07-16 15:22:46 +000010728
10729'``llvm.uabsdiff.*``' and '``llvm.sabsdiff.*``' Intrinsics
10730^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10731
10732Syntax:
10733"""""""
10734This is an overloaded intrinsic. The loaded data is a vector of any integer bit width.
10735
10736.. code-block:: llvm
10737
10738 declare <4 x integer> @llvm.uabsdiff.v4i32(<4 x integer> %a, <4 x integer> %b)
10739
10740
10741Overview:
10742"""""""""
10743
10744The ``llvm.uabsdiff`` intrinsic returns a vector result of the absolute difference of the two operands,
10745treating them both as unsigned integers.
10746
Sean Silvaa1190322015-08-06 22:56:48 +000010747The ``llvm.sabsdiff`` intrinsic returns a vector result of the absolute difference of the two operands,
James Molloy7395a812015-07-16 15:22:46 +000010748treating them both as signed integers.
10749
10750.. note::
10751
10752 These intrinsics are primarily used during the code generation stage of compilation.
10753 They are generated by compiler passes such as the Loop and SLP vectorizers.it is not
10754 recommended for users to create them manually.
10755
10756Arguments:
10757""""""""""
10758
10759Both intrinsics take two integer of the same bitwidth.
10760
10761Semantics:
10762""""""""""
10763
10764The expression::
10765
10766 call <4 x i32> @llvm.uabsdiff.v4i32(<4 x i32> %a, <4 x i32> %b)
10767
10768is equivalent to::
10769
10770 %sub = sub <4 x i32> %a, %b
10771 %ispos = icmp ugt <4 x i32> %sub, <i32 -1, i32 -1, i32 -1, i32 -1>
10772 %neg = sub <4 x i32> zeroinitializer, %sub
10773 %1 = select <4 x i1> %ispos, <4 x i32> %sub, <4 x i32> %neg
10774
10775Similarly the expression::
10776
10777 call <4 x i32> @llvm.sabsdiff.v4i32(<4 x i32> %a, <4 x i32> %b)
10778
10779is equivalent to::
10780
10781 %sub = sub nsw <4 x i32> %a, %b
10782 %ispos = icmp sgt <4 x i32> %sub, <i32 -1, i32 -1, i32 -1, i32 -1>
10783 %neg = sub nsw <4 x i32> zeroinitializer, %sub
10784 %1 = select <4 x i1> %ispos, <4 x i32> %sub, <4 x i32> %neg
10785
10786
Sean Silvab084af42012-12-07 10:36:55 +000010787Half Precision Floating Point Intrinsics
10788----------------------------------------
10789
10790For most target platforms, half precision floating point is a
10791storage-only format. This means that it is a dense encoding (in memory)
10792but does not support computation in the format.
10793
10794This means that code must first load the half-precision floating point
10795value as an i16, then convert it to float with
10796:ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can
10797then be performed on the float value (including extending to double
10798etc). To store the value back to memory, it is first converted to float
10799if needed, then converted to i16 with
10800:ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an
10801i16 value.
10802
10803.. _int_convert_to_fp16:
10804
10805'``llvm.convert.to.fp16``' Intrinsic
10806^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10807
10808Syntax:
10809"""""""
10810
10811::
10812
Tim Northoverfd7e4242014-07-17 10:51:23 +000010813 declare i16 @llvm.convert.to.fp16.f32(float %a)
10814 declare i16 @llvm.convert.to.fp16.f64(double %a)
Sean Silvab084af42012-12-07 10:36:55 +000010815
10816Overview:
10817"""""""""
10818
Tim Northoverfd7e4242014-07-17 10:51:23 +000010819The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a
10820conventional floating point type to half precision floating point format.
Sean Silvab084af42012-12-07 10:36:55 +000010821
10822Arguments:
10823""""""""""
10824
10825The intrinsic function contains single argument - the value to be
10826converted.
10827
10828Semantics:
10829""""""""""
10830
Tim Northoverfd7e4242014-07-17 10:51:23 +000010831The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a
10832conventional floating point format to half precision floating point format. The
10833return value is an ``i16`` which contains the converted number.
Sean Silvab084af42012-12-07 10:36:55 +000010834
10835Examples:
10836"""""""""
10837
10838.. code-block:: llvm
10839
Tim Northoverfd7e4242014-07-17 10:51:23 +000010840 %res = call i16 @llvm.convert.to.fp16.f32(float %a)
Sean Silvab084af42012-12-07 10:36:55 +000010841 store i16 %res, i16* @x, align 2
10842
10843.. _int_convert_from_fp16:
10844
10845'``llvm.convert.from.fp16``' Intrinsic
10846^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10847
10848Syntax:
10849"""""""
10850
10851::
10852
Tim Northoverfd7e4242014-07-17 10:51:23 +000010853 declare float @llvm.convert.from.fp16.f32(i16 %a)
10854 declare double @llvm.convert.from.fp16.f64(i16 %a)
Sean Silvab084af42012-12-07 10:36:55 +000010855
10856Overview:
10857"""""""""
10858
10859The '``llvm.convert.from.fp16``' intrinsic function performs a
10860conversion from half precision floating point format to single precision
10861floating point format.
10862
10863Arguments:
10864""""""""""
10865
10866The intrinsic function contains single argument - the value to be
10867converted.
10868
10869Semantics:
10870""""""""""
10871
10872The '``llvm.convert.from.fp16``' intrinsic function performs a
10873conversion from half single precision floating point format to single
10874precision floating point format. The input half-float value is
10875represented by an ``i16`` value.
10876
10877Examples:
10878"""""""""
10879
10880.. code-block:: llvm
10881
David Blaikiec7aabbb2015-03-04 22:06:14 +000010882 %a = load i16, i16* @x, align 2
Matt Arsenault3e3ddda2014-07-10 03:22:16 +000010883 %res = call float @llvm.convert.from.fp16(i16 %a)
Sean Silvab084af42012-12-07 10:36:55 +000010884
Duncan P. N. Exon Smithe2741802015-03-03 17:24:31 +000010885.. _dbg_intrinsics:
10886
Sean Silvab084af42012-12-07 10:36:55 +000010887Debugger Intrinsics
10888-------------------
10889
10890The LLVM debugger intrinsics (which all start with ``llvm.dbg.``
10891prefix), are described in the `LLVM Source Level
10892Debugging <SourceLevelDebugging.html#format_common_intrinsics>`_
10893document.
10894
10895Exception Handling Intrinsics
10896-----------------------------
10897
10898The LLVM exception handling intrinsics (which all start with
10899``llvm.eh.`` prefix), are described in the `LLVM Exception
10900Handling <ExceptionHandling.html#format_common_intrinsics>`_ document.
10901
10902.. _int_trampoline:
10903
10904Trampoline Intrinsics
10905---------------------
10906
10907These intrinsics make it possible to excise one parameter, marked with
10908the :ref:`nest <nest>` attribute, from a function. The result is a
10909callable function pointer lacking the nest parameter - the caller does
10910not need to provide a value for it. Instead, the value to use is stored
10911in advance in a "trampoline", a block of memory usually allocated on the
10912stack, which also contains code to splice the nest value into the
10913argument list. This is used to implement the GCC nested function address
10914extension.
10915
10916For example, if the function is ``i32 f(i8* nest %c, i32 %x, i32 %y)``
10917then the resulting function pointer has signature ``i32 (i32, i32)*``.
10918It can be created as follows:
10919
10920.. code-block:: llvm
10921
10922 %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
David Blaikie16a97eb2015-03-04 22:02:58 +000010923 %tramp1 = getelementptr [10 x i8], [10 x i8]* %tramp, i32 0, i32 0
Sean Silvab084af42012-12-07 10:36:55 +000010924 call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
10925 %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
10926 %fp = bitcast i8* %p to i32 (i32, i32)*
10927
10928The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to
10929``%val = call i32 %f(i8* %nval, i32 %x, i32 %y)``.
10930
10931.. _int_it:
10932
10933'``llvm.init.trampoline``' Intrinsic
10934^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10935
10936Syntax:
10937"""""""
10938
10939::
10940
10941 declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
10942
10943Overview:
10944"""""""""
10945
10946This fills the memory pointed to by ``tramp`` with executable code,
10947turning it into a trampoline.
10948
10949Arguments:
10950""""""""""
10951
10952The ``llvm.init.trampoline`` intrinsic takes three arguments, all
10953pointers. The ``tramp`` argument must point to a sufficiently large and
10954sufficiently aligned block of memory; this memory is written to by the
10955intrinsic. Note that the size and the alignment are target-specific -
10956LLVM currently provides no portable way of determining them, so a
10957front-end that generates this intrinsic needs to have some
10958target-specific knowledge. The ``func`` argument must hold a function
10959bitcast to an ``i8*``.
10960
10961Semantics:
10962""""""""""
10963
10964The block of memory pointed to by ``tramp`` is filled with target
10965dependent code, turning it into a function. Then ``tramp`` needs to be
10966passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can
10967be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new
10968function's signature is the same as that of ``func`` with any arguments
10969marked with the ``nest`` attribute removed. At most one such ``nest``
10970argument is allowed, and it must be of pointer type. Calling the new
10971function is equivalent to calling ``func`` with the same argument list,
10972but with ``nval`` used for the missing ``nest`` argument. If, after
10973calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is
10974modified, then the effect of any later call to the returned function
10975pointer is undefined.
10976
10977.. _int_at:
10978
10979'``llvm.adjust.trampoline``' Intrinsic
10980^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10981
10982Syntax:
10983"""""""
10984
10985::
10986
10987 declare i8* @llvm.adjust.trampoline(i8* <tramp>)
10988
10989Overview:
10990"""""""""
10991
10992This performs any required machine-specific adjustment to the address of
10993a trampoline (passed as ``tramp``).
10994
10995Arguments:
10996""""""""""
10997
10998``tramp`` must point to a block of memory which already has trampoline
10999code filled in by a previous call to
11000:ref:`llvm.init.trampoline <int_it>`.
11001
11002Semantics:
11003""""""""""
11004
11005On some architectures the address of the code to be executed needs to be
Sanjay Patel69bf48e2014-07-04 19:40:43 +000011006different than the address where the trampoline is actually stored. This
Sean Silvab084af42012-12-07 10:36:55 +000011007intrinsic returns the executable address corresponding to ``tramp``
11008after performing the required machine specific adjustments. The pointer
11009returned can then be :ref:`bitcast and executed <int_trampoline>`.
11010
Elena Demikhovsky82cdd652015-05-07 12:25:11 +000011011.. _int_mload_mstore:
11012
Elena Demikhovsky3d13f1c2014-12-25 09:29:13 +000011013Masked Vector Load and Store Intrinsics
11014---------------------------------------
11015
11016LLVM provides intrinsics for predicated vector load and store operations. The predicate is specified by a mask operand, which holds one bit per vector element, switching the associated vector lane on or off. The memory addresses corresponding to the "off" lanes are not accessed. When all bits of the mask are on, the intrinsic is identical to a regular vector load or store. When all bits are off, no memory is accessed.
11017
11018.. _int_mload:
11019
11020'``llvm.masked.load.*``' Intrinsics
11021^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11022
11023Syntax:
11024"""""""
11025This is an overloaded intrinsic. The loaded data is a vector of any integer or floating point data type.
11026
11027::
11028
11029 declare <16 x float> @llvm.masked.load.v16f32 (<16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>)
11030 declare <2 x double> @llvm.masked.load.v2f64 (<2 x double>* <ptr>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>)
11031
11032Overview:
11033"""""""""
11034
Elena Demikhovsky82cdd652015-05-07 12:25:11 +000011035Reads a vector from memory according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. The masked-off lanes in the result vector are taken from the corresponding lanes of the '``passthru``' operand.
Elena Demikhovsky3d13f1c2014-12-25 09:29:13 +000011036
11037
11038Arguments:
11039""""""""""
11040
Elena Demikhovsky82cdd652015-05-07 12:25:11 +000011041The first operand is the base pointer for the load. The second operand is the alignment of the source location. It must be a constant integer value. The third operand, mask, is a vector of boolean values with the same number of elements as the return type. The fourth is a pass-through value that is used to fill the masked-off lanes of the result. The return type, underlying type of the base pointer and the type of the '``passthru``' operand are the same vector types.
Elena Demikhovsky3d13f1c2014-12-25 09:29:13 +000011042
11043
11044Semantics:
11045""""""""""
11046
11047The '``llvm.masked.load``' intrinsic is designed for conditional reading of selected vector elements in a single IR operation. It is useful for targets that support vector masked loads and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar load operations.
11048The result of this operation is equivalent to a regular vector load instruction followed by a 'select' between the loaded and the passthru values, predicated on the same mask. However, using this intrinsic prevents exceptions on memory access to masked-off lanes.
11049
11050
11051::
11052
11053 %res = call <16 x float> @llvm.masked.load.v16f32 (<16 x float>* %ptr, i32 4, <16 x i1>%mask, <16 x float> %passthru)
Mehdi Amini4a121fa2015-03-14 22:04:06 +000011054
Elena Demikhovsky3d13f1c2014-12-25 09:29:13 +000011055 ;; The result of the two following instructions is identical aside from potential memory access exception
David Blaikiec7aabbb2015-03-04 22:06:14 +000011056 %loadlal = load <16 x float>, <16 x float>* %ptr, align 4
Elena Demikhovskye86c8c82014-12-29 09:47:51 +000011057 %res = select <16 x i1> %mask, <16 x float> %loadlal, <16 x float> %passthru
Elena Demikhovsky3d13f1c2014-12-25 09:29:13 +000011058
11059.. _int_mstore:
11060
11061'``llvm.masked.store.*``' Intrinsics
11062^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11063
11064Syntax:
11065"""""""
11066This is an overloaded intrinsic. The data stored in memory is a vector of any integer or floating point data type.
11067
11068::
11069
11070 declare void @llvm.masked.store.v8i32 (<8 x i32> <value>, <8 x i32> * <ptr>, i32 <alignment>, <8 x i1> <mask>)
11071 declare void @llvm.masked.store.v16f32(<16 x i32> <value>, <16 x i32>* <ptr>, i32 <alignment>, <16 x i1> <mask>)
11072
11073Overview:
11074"""""""""
11075
11076Writes a vector to memory according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes.
11077
11078Arguments:
11079""""""""""
11080
11081The first operand is the vector value to be written to memory. The second operand is the base pointer for the store, it has the same underlying type as the value operand. The third operand is the alignment of the destination location. The fourth operand, mask, is a vector of boolean values. The types of the mask and the value operand must have the same number of vector elements.
11082
11083
11084Semantics:
11085""""""""""
11086
11087The '``llvm.masked.store``' intrinsics is designed for conditional writing of selected vector elements in a single IR operation. It is useful for targets that support vector masked store and allows vectorizing predicated basic blocks on these targets. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations.
11088The result of this operation is equivalent to a load-modify-store sequence. However, using this intrinsic prevents exceptions and data races on memory access to masked-off lanes.
11089
11090::
11091
11092 call void @llvm.masked.store.v16f32(<16 x float> %value, <16 x float>* %ptr, i32 4, <16 x i1> %mask)
Mehdi Amini4a121fa2015-03-14 22:04:06 +000011093
Elena Demikhovskye86c8c82014-12-29 09:47:51 +000011094 ;; The result of the following instructions is identical aside from potential data races and memory access exceptions
David Blaikiec7aabbb2015-03-04 22:06:14 +000011095 %oldval = load <16 x float>, <16 x float>* %ptr, align 4
Elena Demikhovsky3d13f1c2014-12-25 09:29:13 +000011096 %res = select <16 x i1> %mask, <16 x float> %value, <16 x float> %oldval
11097 store <16 x float> %res, <16 x float>* %ptr, align 4
11098
11099
Elena Demikhovsky82cdd652015-05-07 12:25:11 +000011100Masked Vector Gather and Scatter Intrinsics
11101-------------------------------------------
11102
11103LLVM provides intrinsics for vector gather and scatter operations. They are similar to :ref:`Masked Vector Load and Store <int_mload_mstore>`, except they are designed for arbitrary memory accesses, rather than sequential memory accesses. Gather and scatter also employ a mask operand, which holds one bit per vector element, switching the associated vector lane on or off. The memory addresses corresponding to the "off" lanes are not accessed. When all bits are off, no memory is accessed.
11104
11105.. _int_mgather:
11106
11107'``llvm.masked.gather.*``' Intrinsics
11108^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11109
11110Syntax:
11111"""""""
11112This is an overloaded intrinsic. The loaded data are multiple scalar values of any integer or floating point data type gathered together into one vector.
11113
11114::
11115
11116 declare <16 x float> @llvm.masked.gather.v16f32 (<16 x float*> <ptrs>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>)
11117 declare <2 x double> @llvm.masked.gather.v2f64 (<2 x double*> <ptrs>, i32 <alignment>, <2 x i1> <mask>, <2 x double> <passthru>)
11118
11119Overview:
11120"""""""""
11121
11122Reads scalar values from arbitrary memory locations and gathers them into one vector. The memory locations are provided in the vector of pointers '``ptrs``'. The memory is accessed according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes. The masked-off lanes in the result vector are taken from the corresponding lanes of the '``passthru``' operand.
11123
11124
11125Arguments:
11126""""""""""
11127
11128The first operand is a vector of pointers which holds all memory addresses to read. The second operand is an alignment of the source addresses. It must be a constant integer value. The third operand, mask, is a vector of boolean values with the same number of elements as the return type. The fourth is a pass-through value that is used to fill the masked-off lanes of the result. The return type, underlying type of the vector of pointers and the type of the '``passthru``' operand are the same vector types.
11129
11130
11131Semantics:
11132""""""""""
11133
11134The '``llvm.masked.gather``' intrinsic is designed for conditional reading of multiple scalar values from arbitrary memory locations in a single IR operation. It is useful for targets that support vector masked gathers and allows vectorizing basic blocks with data and control divergence. Other targets may support this intrinsic differently, for example by lowering it into a sequence of scalar load operations.
11135The semantics of this operation are equivalent to a sequence of conditional scalar loads with subsequent gathering all loaded values into a single vector. The mask restricts memory access to certain lanes and facilitates vectorization of predicated basic blocks.
11136
11137
11138::
11139
11140 %res = call <4 x double> @llvm.masked.gather.v4f64 (<4 x double*> %ptrs, i32 8, <4 x i1>%mask, <4 x double> <true, true, true, true>)
11141
11142 ;; The gather with all-true mask is equivalent to the following instruction sequence
11143 %ptr0 = extractelement <4 x double*> %ptrs, i32 0
11144 %ptr1 = extractelement <4 x double*> %ptrs, i32 1
11145 %ptr2 = extractelement <4 x double*> %ptrs, i32 2
11146 %ptr3 = extractelement <4 x double*> %ptrs, i32 3
11147
11148 %val0 = load double, double* %ptr0, align 8
11149 %val1 = load double, double* %ptr1, align 8
11150 %val2 = load double, double* %ptr2, align 8
11151 %val3 = load double, double* %ptr3, align 8
11152
11153 %vec0 = insertelement <4 x double>undef, %val0, 0
11154 %vec01 = insertelement <4 x double>%vec0, %val1, 1
11155 %vec012 = insertelement <4 x double>%vec01, %val2, 2
11156 %vec0123 = insertelement <4 x double>%vec012, %val3, 3
11157
11158.. _int_mscatter:
11159
11160'``llvm.masked.scatter.*``' Intrinsics
11161^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11162
11163Syntax:
11164"""""""
11165This is an overloaded intrinsic. The data stored in memory is a vector of any integer or floating point data type. Each vector element is stored in an arbitrary memory addresses. Scatter with overlapping addresses is guaranteed to be ordered from least-significant to most-significant element.
11166
11167::
11168
11169 declare void @llvm.masked.scatter.v8i32 (<8 x i32> <value>, <8 x i32*> <ptrs>, i32 <alignment>, <8 x i1> <mask>)
11170 declare void @llvm.masked.scatter.v16f32(<16 x i32> <value>, <16 x i32*> <ptrs>, i32 <alignment>, <16 x i1> <mask>)
11171
11172Overview:
11173"""""""""
11174
11175Writes each element from the value vector to the corresponding memory address. The memory addresses are represented as a vector of pointers. Writing is done according to the provided mask. The mask holds a bit for each vector lane, and is used to prevent memory accesses to the masked-off lanes.
11176
11177Arguments:
11178""""""""""
11179
11180The first operand is a vector value to be written to memory. The second operand is a vector of pointers, pointing to where the value elements should be stored. It has the same underlying type as the value operand. The third operand is an alignment of the destination addresses. The fourth operand, mask, is a vector of boolean values. The types of the mask and the value operand must have the same number of vector elements.
11181
11182
11183Semantics:
11184""""""""""
11185
11186The '``llvm.masked.scatter``' intrinsics is designed for writing selected vector elements to arbitrary memory addresses in a single IR operation. The operation may be conditional, when not all bits in the mask are switched on. It is useful for targets that support vector masked scatter and allows vectorizing basic blocks with data and control divergency. Other targets may support this intrinsic differently, for example by lowering it into a sequence of branches that guard scalar store operations.
11187
11188::
11189
11190 ;; This instruction unconditionaly stores data vector in multiple addresses
11191 call @llvm.masked.scatter.v8i32 (<8 x i32> %value, <8 x i32*> %ptrs, i32 4, <8 x i1> <true, true, .. true>)
11192
11193 ;; It is equivalent to a list of scalar stores
11194 %val0 = extractelement <8 x i32> %value, i32 0
11195 %val1 = extractelement <8 x i32> %value, i32 1
11196 ..
11197 %val7 = extractelement <8 x i32> %value, i32 7
11198 %ptr0 = extractelement <8 x i32*> %ptrs, i32 0
11199 %ptr1 = extractelement <8 x i32*> %ptrs, i32 1
11200 ..
11201 %ptr7 = extractelement <8 x i32*> %ptrs, i32 7
11202 ;; Note: the order of the following stores is important when they overlap:
11203 store i32 %val0, i32* %ptr0, align 4
11204 store i32 %val1, i32* %ptr1, align 4
11205 ..
11206 store i32 %val7, i32* %ptr7, align 4
11207
11208
Sean Silvab084af42012-12-07 10:36:55 +000011209Memory Use Markers
11210------------------
11211
Sanjay Patel69bf48e2014-07-04 19:40:43 +000011212This class of intrinsics provides information about the lifetime of
Sean Silvab084af42012-12-07 10:36:55 +000011213memory objects and ranges where variables are immutable.
11214
Reid Klecknera534a382013-12-19 02:14:12 +000011215.. _int_lifestart:
11216
Sean Silvab084af42012-12-07 10:36:55 +000011217'``llvm.lifetime.start``' Intrinsic
11218^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11219
11220Syntax:
11221"""""""
11222
11223::
11224
11225 declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)
11226
11227Overview:
11228"""""""""
11229
11230The '``llvm.lifetime.start``' intrinsic specifies the start of a memory
11231object's lifetime.
11232
11233Arguments:
11234""""""""""
11235
11236The first argument is a constant integer representing the size of the
11237object, or -1 if it is variable sized. The second argument is a pointer
11238to the object.
11239
11240Semantics:
11241""""""""""
11242
11243This intrinsic indicates that before this point in the code, the value
11244of the memory pointed to by ``ptr`` is dead. This means that it is known
11245to never be used and has an undefined value. A load from the pointer
11246that precedes this intrinsic can be replaced with ``'undef'``.
11247
Reid Klecknera534a382013-12-19 02:14:12 +000011248.. _int_lifeend:
11249
Sean Silvab084af42012-12-07 10:36:55 +000011250'``llvm.lifetime.end``' Intrinsic
11251^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11252
11253Syntax:
11254"""""""
11255
11256::
11257
11258 declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
11259
11260Overview:
11261"""""""""
11262
11263The '``llvm.lifetime.end``' intrinsic specifies the end of a memory
11264object's lifetime.
11265
11266Arguments:
11267""""""""""
11268
11269The first argument is a constant integer representing the size of the
11270object, or -1 if it is variable sized. The second argument is a pointer
11271to the object.
11272
11273Semantics:
11274""""""""""
11275
11276This intrinsic indicates that after this point in the code, the value of
11277the memory pointed to by ``ptr`` is dead. This means that it is known to
11278never be used and has an undefined value. Any stores into the memory
11279object following this intrinsic may be removed as dead.
11280
11281'``llvm.invariant.start``' Intrinsic
11282^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11283
11284Syntax:
11285"""""""
11286
11287::
11288
11289 declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
11290
11291Overview:
11292"""""""""
11293
11294The '``llvm.invariant.start``' intrinsic specifies that the contents of
11295a memory object will not change.
11296
11297Arguments:
11298""""""""""
11299
11300The first argument is a constant integer representing the size of the
11301object, or -1 if it is variable sized. The second argument is a pointer
11302to the object.
11303
11304Semantics:
11305""""""""""
11306
11307This intrinsic indicates that until an ``llvm.invariant.end`` that uses
11308the return value, the referenced memory location is constant and
11309unchanging.
11310
11311'``llvm.invariant.end``' Intrinsic
11312^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11313
11314Syntax:
11315"""""""
11316
11317::
11318
11319 declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>)
11320
11321Overview:
11322"""""""""
11323
11324The '``llvm.invariant.end``' intrinsic specifies that the contents of a
11325memory object are mutable.
11326
11327Arguments:
11328""""""""""
11329
11330The first argument is the matching ``llvm.invariant.start`` intrinsic.
11331The second argument is a constant integer representing the size of the
11332object, or -1 if it is variable sized and the third argument is a
11333pointer to the object.
11334
11335Semantics:
11336""""""""""
11337
11338This intrinsic indicates that the memory is mutable again.
11339
11340General Intrinsics
11341------------------
11342
11343This class of intrinsics is designed to be generic and has no specific
11344purpose.
11345
11346'``llvm.var.annotation``' Intrinsic
11347^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11348
11349Syntax:
11350"""""""
11351
11352::
11353
11354 declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
11355
11356Overview:
11357"""""""""
11358
11359The '``llvm.var.annotation``' intrinsic.
11360
11361Arguments:
11362""""""""""
11363
11364The first argument is a pointer to a value, the second is a pointer to a
11365global string, the third is a pointer to a global string which is the
11366source file name, and the last argument is the line number.
11367
11368Semantics:
11369""""""""""
11370
11371This intrinsic allows annotation of local variables with arbitrary
11372strings. This can be useful for special purpose optimizations that want
11373to look for these annotations. These have no other defined use; they are
11374ignored by code generation and optimization.
11375
Michael Gottesman88d18832013-03-26 00:34:27 +000011376'``llvm.ptr.annotation.*``' Intrinsic
11377^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11378
11379Syntax:
11380"""""""
11381
11382This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a
11383pointer to an integer of any width. *NOTE* you must specify an address space for
11384the pointer. The identifier for the default address space is the integer
11385'``0``'.
11386
11387::
11388
11389 declare i8* @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
11390 declare i16* @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32 <int>)
11391 declare i32* @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32 <int>)
11392 declare i64* @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32 <int>)
11393 declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32 <int>)
11394
11395Overview:
11396"""""""""
11397
11398The '``llvm.ptr.annotation``' intrinsic.
11399
11400Arguments:
11401""""""""""
11402
11403The first argument is a pointer to an integer value of arbitrary bitwidth
11404(result of some expression), the second is a pointer to a global string, the
11405third is a pointer to a global string which is the source file name, and the
11406last argument is the line number. It returns the value of the first argument.
11407
11408Semantics:
11409""""""""""
11410
11411This intrinsic allows annotation of a pointer to an integer with arbitrary
11412strings. This can be useful for special purpose optimizations that want to look
11413for these annotations. These have no other defined use; they are ignored by code
11414generation and optimization.
11415
Sean Silvab084af42012-12-07 10:36:55 +000011416'``llvm.annotation.*``' Intrinsic
11417^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11418
11419Syntax:
11420"""""""
11421
11422This is an overloaded intrinsic. You can use '``llvm.annotation``' on
11423any integer bit width.
11424
11425::
11426
11427 declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32 <int>)
11428 declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32 <int>)
11429 declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32 <int>)
11430 declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32 <int>)
11431 declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32 <int>)
11432
11433Overview:
11434"""""""""
11435
11436The '``llvm.annotation``' intrinsic.
11437
11438Arguments:
11439""""""""""
11440
11441The first argument is an integer value (result of some expression), the
11442second is a pointer to a global string, the third is a pointer to a
11443global string which is the source file name, and the last argument is
11444the line number. It returns the value of the first argument.
11445
11446Semantics:
11447""""""""""
11448
11449This intrinsic allows annotations to be put on arbitrary expressions
11450with arbitrary strings. This can be useful for special purpose
11451optimizations that want to look for these annotations. These have no
11452other defined use; they are ignored by code generation and optimization.
11453
11454'``llvm.trap``' Intrinsic
11455^^^^^^^^^^^^^^^^^^^^^^^^^
11456
11457Syntax:
11458"""""""
11459
11460::
11461
11462 declare void @llvm.trap() noreturn nounwind
11463
11464Overview:
11465"""""""""
11466
11467The '``llvm.trap``' intrinsic.
11468
11469Arguments:
11470""""""""""
11471
11472None.
11473
11474Semantics:
11475""""""""""
11476
11477This intrinsic is lowered to the target dependent trap instruction. If
11478the target does not have a trap instruction, this intrinsic will be
11479lowered to a call of the ``abort()`` function.
11480
11481'``llvm.debugtrap``' Intrinsic
11482^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11483
11484Syntax:
11485"""""""
11486
11487::
11488
11489 declare void @llvm.debugtrap() nounwind
11490
11491Overview:
11492"""""""""
11493
11494The '``llvm.debugtrap``' intrinsic.
11495
11496Arguments:
11497""""""""""
11498
11499None.
11500
11501Semantics:
11502""""""""""
11503
11504This intrinsic is lowered to code which is intended to cause an
11505execution trap with the intention of requesting the attention of a
11506debugger.
11507
11508'``llvm.stackprotector``' Intrinsic
11509^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11510
11511Syntax:
11512"""""""
11513
11514::
11515
11516 declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)
11517
11518Overview:
11519"""""""""
11520
11521The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it
11522onto the stack at ``slot``. The stack slot is adjusted to ensure that it
11523is placed on the stack before local variables.
11524
11525Arguments:
11526""""""""""
11527
11528The ``llvm.stackprotector`` intrinsic requires two pointer arguments.
11529The first argument is the value loaded from the stack guard
11530``@__stack_chk_guard``. The second variable is an ``alloca`` that has
11531enough space to hold the value of the guard.
11532
11533Semantics:
11534""""""""""
11535
Michael Gottesmandafc7d92013-08-12 18:35:32 +000011536This intrinsic causes the prologue/epilogue inserter to force the position of
11537the ``AllocaInst`` stack slot to be before local variables on the stack. This is
11538to ensure that if a local variable on the stack is overwritten, it will destroy
11539the value of the guard. When the function exits, the guard on the stack is
11540checked against the original guard by ``llvm.stackprotectorcheck``. If they are
11541different, then ``llvm.stackprotectorcheck`` causes the program to abort by
11542calling the ``__stack_chk_fail()`` function.
11543
11544'``llvm.stackprotectorcheck``' Intrinsic
Sean Silva9d1e1a32013-09-09 19:13:28 +000011545^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Michael Gottesmandafc7d92013-08-12 18:35:32 +000011546
11547Syntax:
11548"""""""
11549
11550::
11551
11552 declare void @llvm.stackprotectorcheck(i8** <guard>)
11553
11554Overview:
11555"""""""""
11556
11557The ``llvm.stackprotectorcheck`` intrinsic compares ``guard`` against an already
Michael Gottesman98850bd2013-08-12 19:44:09 +000011558created stack protector and if they are not equal calls the
Sean Silvab084af42012-12-07 10:36:55 +000011559``__stack_chk_fail()`` function.
11560
Michael Gottesmandafc7d92013-08-12 18:35:32 +000011561Arguments:
11562""""""""""
11563
11564The ``llvm.stackprotectorcheck`` intrinsic requires one pointer argument, the
11565the variable ``@__stack_chk_guard``.
11566
11567Semantics:
11568""""""""""
11569
11570This intrinsic is provided to perform the stack protector check by comparing
11571``guard`` with the stack slot created by ``llvm.stackprotector`` and if the
11572values do not match call the ``__stack_chk_fail()`` function.
11573
11574The reason to provide this as an IR level intrinsic instead of implementing it
11575via other IR operations is that in order to perform this operation at the IR
11576level without an intrinsic, one would need to create additional basic blocks to
11577handle the success/failure cases. This makes it difficult to stop the stack
11578protector check from disrupting sibling tail calls in Codegen. With this
11579intrinsic, we are able to generate the stack protector basic blocks late in
Benjamin Kramer3b32b2f2013-10-29 17:53:27 +000011580codegen after the tail call decision has occurred.
Michael Gottesmandafc7d92013-08-12 18:35:32 +000011581
Sean Silvab084af42012-12-07 10:36:55 +000011582'``llvm.objectsize``' Intrinsic
11583^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11584
11585Syntax:
11586"""""""
11587
11588::
11589
11590 declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>)
11591 declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>)
11592
11593Overview:
11594"""""""""
11595
11596The ``llvm.objectsize`` intrinsic is designed to provide information to
11597the optimizers to determine at compile time whether a) an operation
11598(like memcpy) will overflow a buffer that corresponds to an object, or
11599b) that a runtime check for overflow isn't necessary. An object in this
11600context means an allocation of a specific class, structure, array, or
11601other object.
11602
11603Arguments:
11604""""""""""
11605
11606The ``llvm.objectsize`` intrinsic takes two arguments. The first
11607argument is a pointer to or into the ``object``. The second argument is
11608a boolean and determines whether ``llvm.objectsize`` returns 0 (if true)
11609or -1 (if false) when the object size is unknown. The second argument
11610only accepts constants.
11611
11612Semantics:
11613""""""""""
11614
11615The ``llvm.objectsize`` intrinsic is lowered to a constant representing
11616the size of the object concerned. If the size cannot be determined at
11617compile time, ``llvm.objectsize`` returns ``i32/i64 -1 or 0`` (depending
11618on the ``min`` argument).
11619
11620'``llvm.expect``' Intrinsic
11621^^^^^^^^^^^^^^^^^^^^^^^^^^^
11622
11623Syntax:
11624"""""""
11625
Duncan P. N. Exon Smith1ff08e32014-02-02 22:43:55 +000011626This is an overloaded intrinsic. You can use ``llvm.expect`` on any
11627integer bit width.
11628
Sean Silvab084af42012-12-07 10:36:55 +000011629::
11630
Duncan P. N. Exon Smith1ff08e32014-02-02 22:43:55 +000011631 declare i1 @llvm.expect.i1(i1 <val>, i1 <expected_val>)
Sean Silvab084af42012-12-07 10:36:55 +000011632 declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>)
11633 declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>)
11634
11635Overview:
11636"""""""""
11637
11638The ``llvm.expect`` intrinsic provides information about expected (the
11639most probable) value of ``val``, which can be used by optimizers.
11640
11641Arguments:
11642""""""""""
11643
11644The ``llvm.expect`` intrinsic takes two arguments. The first argument is
11645a value. The second argument is an expected value, this needs to be a
11646constant value, variables are not allowed.
11647
11648Semantics:
11649""""""""""
11650
11651This intrinsic is lowered to the ``val``.
11652
Philip Reamese0e90832015-04-26 22:23:12 +000011653.. _int_assume:
11654
Hal Finkel93046912014-07-25 21:13:35 +000011655'``llvm.assume``' Intrinsic
11656^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11657
11658Syntax:
11659"""""""
11660
11661::
11662
11663 declare void @llvm.assume(i1 %cond)
11664
11665Overview:
11666"""""""""
11667
11668The ``llvm.assume`` allows the optimizer to assume that the provided
11669condition is true. This information can then be used in simplifying other parts
11670of the code.
11671
11672Arguments:
11673""""""""""
11674
11675The condition which the optimizer may assume is always true.
11676
11677Semantics:
11678""""""""""
11679
11680The intrinsic allows the optimizer to assume that the provided condition is
11681always true whenever the control flow reaches the intrinsic call. No code is
11682generated for this intrinsic, and instructions that contribute only to the
11683provided condition are not used for code generation. If the condition is
11684violated during execution, the behavior is undefined.
11685
Sanjay Patel1ed2bb52015-01-14 16:03:58 +000011686Note that the optimizer might limit the transformations performed on values
Hal Finkel93046912014-07-25 21:13:35 +000011687used by the ``llvm.assume`` intrinsic in order to preserve the instructions
11688only used to form the intrinsic's input argument. This might prove undesirable
Sanjay Patel1ed2bb52015-01-14 16:03:58 +000011689if the extra information provided by the ``llvm.assume`` intrinsic does not cause
Hal Finkel93046912014-07-25 21:13:35 +000011690sufficient overall improvement in code quality. For this reason,
11691``llvm.assume`` should not be used to document basic mathematical invariants
11692that the optimizer can otherwise deduce or facts that are of little use to the
11693optimizer.
11694
Peter Collingbournee6909c82015-02-20 20:30:47 +000011695.. _bitset.test:
11696
11697'``llvm.bitset.test``' Intrinsic
11698^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11699
11700Syntax:
11701"""""""
11702
11703::
11704
11705 declare i1 @llvm.bitset.test(i8* %ptr, metadata %bitset) nounwind readnone
11706
11707
11708Arguments:
11709""""""""""
11710
11711The first argument is a pointer to be tested. The second argument is a
11712metadata string containing the name of a :doc:`bitset <BitSets>`.
11713
11714Overview:
11715"""""""""
11716
11717The ``llvm.bitset.test`` intrinsic tests whether the given pointer is a
11718member of the given bitset.
11719
Sean Silvab084af42012-12-07 10:36:55 +000011720'``llvm.donothing``' Intrinsic
11721^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11722
11723Syntax:
11724"""""""
11725
11726::
11727
11728 declare void @llvm.donothing() nounwind readnone
11729
11730Overview:
11731"""""""""
11732
Juergen Ributzkac9161192014-10-23 22:36:13 +000011733The ``llvm.donothing`` intrinsic doesn't perform any operation. It's one of only
11734two intrinsics (besides ``llvm.experimental.patchpoint``) that can be called
11735with an invoke instruction.
Sean Silvab084af42012-12-07 10:36:55 +000011736
11737Arguments:
11738""""""""""
11739
11740None.
11741
11742Semantics:
11743""""""""""
11744
11745This intrinsic does nothing, and it's removed by optimizers and ignored
11746by codegen.
Andrew Trick5e029ce2013-12-24 02:57:25 +000011747
11748Stack Map Intrinsics
11749--------------------
11750
11751LLVM provides experimental intrinsics to support runtime patching
11752mechanisms commonly desired in dynamic language JITs. These intrinsics
11753are described in :doc:`StackMaps`.