:local:
:depth: 3
-Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Vikram
-Adve <mailto:vadve@cs.uiuc.edu>`_
-
Abstract
========
.. code-block:: llvm
- %result = shl i32 %X, i8 3
+ %result = shl i32 %X, 3
And the hard way:
.. code-block:: llvm
- ; Declare the string constant as a global constant.
- @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
+ ; Declare the string constant as a global constant.
+ @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
- ; External declaration of the puts function
- declare i32 @puts(i8* nocapture) nounwind
+ ; External declaration of the puts function
+ declare i32 @puts(i8* nocapture) nounwind
; Definition of main function
- define i32 @main() { ; i32()*
- ; Convert [13 x i8]* to i8 *...
+ define i32 @main() { ; i32()*
+ ; Convert [13 x i8]* to i8 *...
%cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0
- ; Call puts function to write out the string to stdout.
+ ; Call puts function to write out the string to stdout.
call i32 @puts(i8* %cast210)
- ret i32 0
+ ret i32 0
}
; Named metadata
Some languages allow differing globals to be merged, such as two
functions with different semantics. Other languages, such as
``C++``, ensure that only equivalent globals are ever merged (the
- "one definition rule" — "ODR"). Such languages can use the
+ "one definition rule" --- "ODR"). Such languages can use the
``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the
global will only be merged with equivalent globals. These linkage
types are otherwise the same as their non-``odr`` versions.
be used. The target may choose a different TLS model if the specified
model is not supported, or if a better choice of model can be made.
-A variable may be defined as a global "constant," which indicates that
+A variable may be defined as a global ``constant``, which indicates that
the contents of the variable will **never** be modified (enabling better
optimization, allowing the global data to be placed in the read-only
section of an executable, etc). Note that variables that need runtime
-initialization cannot be marked "constant" as there is a store to the
+initialization cannot be marked ``constant`` as there is a store to the
variable.
LLVM explicitly allows *declarations* of global variables to be marked
LLVM allows an explicit section to be specified for globals. If the
target supports it, it will emit globals to the section specified.
+By default, global initializers are optimized by assuming that global
+variables defined within the module are not modified from their
+initial values before the start of the global initializer. This is
+true even for variables potentially accessible from outside the
+module, including those with external linkage or appearing in
+``@llvm.used``. This assumption may be suppressed by marking the
+variable with ``externally_initialized``.
+
An explicit alignment may be specified for a global, which must be a
power of 2. If not present, or if the alignment is set to zero, the
alignment of the global is set by the target to whatever it feels
This indicates that the pointer parameter specifies the address of a
structure that is the return value of the function in the source
program. This pointer must be guaranteed by the caller to be valid:
- loads and stores to the structure may be assumed by the callee to
+ loads and stores to the structure may be assumed by the callee
not to trap and to be properly aligned. This may only be applied to
the first parameter. This is not a valid attribute for return
values.
This indicates that the pointer parameter can be excised using the
:ref:`trampoline intrinsics <int_trampoline>`. This is not a valid
attribute for return values.
+``nobuiltin``
+ This indicates that the callee function at a call site is not
+ recognized as a built-in function. LLVM will retain the original call
+ and not replace it with equivalent code based on the semantics of the
+ built-in function.
.. _gc:
collector which will cause the compiler to alter its output in order to
support the named garbage collection algorithm.
+.. _attrgrp:
+
+Attribute Groups
+----------------
+
+Attribute groups are groups of attributes that are referenced by objects within
+the IR. They are important for keeping ``.ll`` files readable, because a lot of
+functions will use the same set of attributes. In the degenerative case of a
+``.ll`` file that corresponds to a single ``.c`` file, the single attribute
+group will capture the important command line flags used to build that file.
+
+An attribute group is a module-level object. To use an attribute group, an
+object references the attribute group's ID (e.g. ``#37``). An object may refer
+to more than one attribute group. In that situation, the attributes from the
+different groups are merged.
+
+Here is an example of attribute groups for a function that should always be
+inlined, has a stack alignment of 4, and which shouldn't use SSE instructions:
+
+.. code-block:: llvm
+
+ ; Target-independent attributes:
+ #0 = attributes { alwaysinline alignstack=4 }
+
+ ; Target-dependent attributes:
+ #1 = attributes { "no-sse" }
+
+ ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse".
+ define void @f() #0 #1 { ... }
+
.. _fnattrs:
Function Attributes
define void @f() alwaysinline optsize { ... }
define void @f() optsize { ... }
-``address_safety``
- This attribute indicates that the address safety analysis is enabled
- for this function.
``alignstack(<n>)``
This attribute indicates that, when emitting the prologue and
epilogue, the backend should forcibly align the stack pointer.
``naked``
This attribute disables prologue / epilogue emission for the
function. This can have very system-specific consequences.
+``noduplicate``
+ This attribute indicates that calls to the function cannot be
+ duplicated. A call to a ``noduplicate`` function may be moved
+ within its parent function, but may not be duplicated within
+ its parent function.
+
+ A function containing a ``noduplicate`` call may still
+ be an inlining candidate, provided that the call is not
+ duplicated by inlining. That implies that the function has
+ internal linkage and only has one call site, so the original
+ call is dead after inlining.
``noimplicitfloat``
This attributes disables implicit floating point instructions.
``noinline``
``setjmp`` is an example of such a function. The compiler disables
some optimizations (like tail calls) in the caller of these
functions.
+``sanitize_address``
+ This attribute indicates that AddressSanitizer checks
+ (dynamic address safety analysis) are enabled for this function.
+``sanitize_memory``
+ This attribute indicates that MemorySanitizer checks (dynamic detection
+ of accesses to uninitialized memory) are enabled for this function.
+``sanitize_thread``
+ This attribute indicates that ThreadSanitizer checks
+ (dynamic thread safety analysis) are enabled for this function.
``ssp``
This attribute indicates that the function should emit a stack
- smashing protector. It is in the form of a "canary"—a random value
+ smashing protector. It is in the form of a "canary" --- a random value
placed on the stack before the local variables that's checked upon
return from the function to see if it has been overwritten. A
heuristic is used to determine if a function needs stack protectors
- or not.
+ or not. The heuristic used will enable protectors for functions with:
+
+ - Character arrays larger than ``ssp-buffer-size`` (default 8).
+ - Aggregates containing character arrays larger than ``ssp-buffer-size``.
+ - Calls to alloca() with variable sizes or constant sizes greater than
+ ``ssp-buffer-size``.
If a function that has an ``ssp`` attribute is inlined into a
function that doesn't have an ``ssp`` attribute, then the resulting
If a function that has an ``sspreq`` attribute is inlined into a
function that doesn't have an ``sspreq`` attribute or which has an
- ``ssp`` attribute, then the resulting function will have an
- ``sspreq`` attribute.
+ ``ssp`` or ``sspstrong`` attribute, then the resulting function will have
+ an ``sspreq`` attribute.
+``sspstrong``
+ This attribute indicates that the function should emit a stack smashing
+ protector. This attribute causes a strong heuristic to be used when
+ determining if a function needs stack protectors. The strong heuristic
+ will enable protectors for functions with:
+
+ - Arrays of any size and type
+ - Aggregates containing an array of any size and type.
+ - Calls to alloca().
+ - Local variables that have had their address taken.
+
+ This overrides the ``ssp`` function attribute.
+
+ If a function that has an ``sspstrong`` attribute is inlined into a
+ function that doesn't have an ``sspstrong`` attribute, then the
+ resulting function will have an ``sspstrong`` attribute.
``uwtable``
This attribute indicates that the ABI being targeted requires that
an unwind table entry be produce for this function even if we can
- ``E`` - big endian
- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment
-- ``p1:32:32:32`` - 32-bit pointers with 32-bit alignment for address
- space 1
-- ``p2:16:32:32`` - 16-bit pointers with 32-bit alignment for address
- space 2
+- ``S0`` - natural stack alignment is unspecified
- ``i1:8:8`` - i1 is 8-bit (byte) aligned
- ``i8:8:8`` - i8 is 8-bit (byte) aligned
- ``i16:16:16`` - i16 is 16-bit aligned
- ``i32:32:32`` - i32 is 32-bit aligned
- ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred
alignment of 64-bits
+- ``f16:16:16`` - half is 16-bit aligned
- ``f32:32:32`` - float is 32-bit aligned
- ``f64:64:64`` - double is 64-bit aligned
+- ``f128:128:128`` - quad is 128-bit aligned
- ``v64:64:64`` - 64-bit vector is 64-bit aligned
- ``v128:128:128`` - 128-bit vector is 128-bit aligned
-- ``a0:0:1`` - aggregates are 8-bit aligned
-- ``s0:64:64`` - stack objects are 64-bit aligned
+- ``a0:0:64`` - aggregates are 64-bit aligned
When LLVM is determining the alignment for a given type, it uses the
following rules:
operations relative to non-volatile operations. This is not Java's
"volatile" and has no cross-thread synchronization behavior.
+IR-level volatile loads and stores cannot safely be optimized into
+llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are
+flagged volatile. Likewise, the backend should never split or merge
+target-legal volatile load/store instructions.
+
+.. admonition:: Rationale
+
+ Platforms may rely on volatile loads and stores of natively supported
+ data width to be executed as single instruction. For example, in C
+ this holds for an l-value of volatile primitive type with native
+ hardware support, but not necessarily for aggregate types. The
+ frontend upholds these expectations, which are intentionally
+ unspecified in the IR. The rules above ensure that IR transformation
+ do not violate the frontend's contract with the language.
+
.. _memmodel:
Memory Model for Concurrent Operations
+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` |
+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. |
+| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. |
+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``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. |
+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values |
+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``{ 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``. |
+| ``{ 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``. |
+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. |
+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
When using the hexadecimal form, constants of types half, float, and
double are represented using the 16-digit form shown above (which
matches the IEEE754 representation for double); half and float values
-must, however, be exactly representable as IEE754 half and single
+must, however, be exactly representable as IEEE 754 half and single
precision, respectively. Hexadecimal format is always used for long
double, and there are three forms of long double. The 80-bit format used
by x86 is represented as ``0xK`` followed by 20 hexadecimal digits. The
This value only has defined behavior when used as an operand to the
':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons
against null. Pointer equality tests between labels addresses results in
-undefined behavior — though, again, comparison against null is ok, and
+undefined behavior --- though, again, comparison against null is ok, and
no label is equal to the null pointer. This may be passed around as an
opaque pointer sized value as long as the bits are not inspected. This
allows ``ptrtoint`` and arithmetic to be performed on these values so
!2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
!3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }
+'``llvm.loop``'
+^^^^^^^^^^^^^^^
+
+It is sometimes useful to attach information to loop constructs. Currently,
+loop metadata is implemented as metadata attached to the branch instruction
+in the loop latch block. This type of metadata refer to a metadata node that is
+guaranteed to be separate for each loop. The loop-level metadata is prefixed
+with ``llvm.loop``.
+
+The loop identifier metadata is implemented using a metadata that refers to
+itself to avoid merging it with any other identifier metadata, e.g.,
+during module linkage or function inlining. That is, each loop should refer
+to their own identification metadata even if they reside in separate functions.
+The following example contains loop identifier metadata for two separate loop
+constructs:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ metadata !0 }
+ !1 = metadata !{ metadata !1 }
+
+
+'``llvm.loop.parallel``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This loop metadata can be used to communicate that a loop should be considered
+a parallel loop. The semantics of parallel loops in this case is the one
+with the strongest cross-iteration instruction ordering freedom: the
+iterations in the loop can be considered completely independent of each
+other (also known as embarrassingly parallel loops).
+
+This metadata can originate from a programming language with parallel loop
+constructs. In such a case it is completely the programmer's responsibility
+to ensure the instructions from the different iterations of the loop can be
+executed in an arbitrary order, in parallel, or intertwined. No loop-carried
+dependency checking at all must be expected from the compiler.
+
+In order to fulfill the LLVM requirement for metadata to be safely ignored,
+it is important to ensure that a parallel loop is converted to
+a sequential loop in case an optimization (agnostic of the parallel loop
+semantics) converts the loop back to such. This happens when new memory
+accesses that do not fulfill the requirement of free ordering across iterations
+are added to the loop. Therefore, this metadata is required, but not
+sufficient, to consider the loop at hand a parallel loop. For a loop
+to be parallel, all its memory accessing instructions need to be
+marked with the ``llvm.mem.parallel_loop_access`` metadata that refer
+to the same loop identifier metadata that identify the loop at hand.
+
+'``llvm.mem``'
+^^^^^^^^^^^^^^^
+
+Metadata types used to annotate memory accesses with information helpful
+for optimizations are prefixed with ``llvm.mem``.
+
+'``llvm.mem.parallel_loop_access``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For a loop to be parallel, in addition to using
+the ``llvm.loop.parallel`` metadata to mark the loop latch branch instruction,
+also all of the memory accessing instructions in the loop body need to be
+marked with the ``llvm.mem.parallel_loop_access`` metadata. If there
+is at least one memory accessing instruction not marked with the metadata,
+the loop, despite it possibly using the ``llvm.loop.parallel`` metadata,
+must be considered a sequential loop. This causes parallel loops to be
+converted to sequential loops due to optimization passes that are unaware of
+the parallel semantics and that insert new memory instructions to the loop
+body.
+
+Example of a loop that is considered parallel due to its correct use of
+both ``llvm.loop.parallel`` and ``llvm.mem.parallel_loop_access``
+metadata types that refer to the same loop identifier metadata.
+
+.. code-block:: llvm
+
+ for.body:
+ ...
+ %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ br i1 %exitcond, label %for.end, label %for.body, !llvm.loop.parallel !0
+
+ for.end:
+ ...
+ !0 = metadata !{ metadata !0 }
+
+It is also possible to have nested parallel loops. In that case the
+memory accesses refer to a list of loop identifier metadata nodes instead of
+the loop identifier metadata node directly:
+
+.. code-block:: llvm
+
+ outer.for.body:
+ ...
+
+ inner.for.body:
+ ...
+ %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop.parallel !1
+
+ inner.for.end:
+ ...
+ %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop.parallel !2
+
+ outer.for.end: ; preds = %for.body
+ ...
+ !0 = metadata !{ metadata !1, metadata !2 } ; a list of parallel loop identifiers
+ !1 = metadata !{ metadata !1 } ; an identifier for the inner parallel loop
+ !2 = metadata !{ metadata !2 } ; an identifier for the outer parallel loop
+
+
Module Flags Metadata
=====================
Information about the module as a whole is difficult to convey to LLVM's
subsystems. The LLVM IR isn't sufficient to transmit this information.
The ``llvm.module.flags`` named metadata exists in order to facilitate
-this. These flags are in the form of key / value pairs — much like a
-dictionary — making it easy for any subsystem who cares about a flag to
+this. These flags are in the form of key / value pairs --- much like a
+dictionary --- making it easy for any subsystem who cares about a flag to
look it up.
The ``llvm.module.flags`` metadata contains a list of metadata triplets.
(or more) metadata with the same ID. The supported behaviors are
described below.
- The second element is a metadata string that is a unique ID for the
- metadata. How each ID is interpreted is documented below.
+ metadata. Each module may only have one flag entry for each unique ID (not
+ including entries with the **Require** behavior).
- The third element is the value of the flag.
When two (or more) modules are merged together, the resulting
-``llvm.module.flags`` metadata is the union of the modules'
-``llvm.module.flags`` metadata. The only exception being a flag with the
-*Override* behavior, which may override another flag's value (see
-below).
+``llvm.module.flags`` metadata is the union of the modules' flags. That is, for
+each unique metadata ID string, there will be exactly one entry in the merged
+modules ``llvm.module.flags`` metadata table, and the value for that entry will
+be determined by the merge behavior flag, as described below. The only exception
+is that entries with the *Require* behavior are always preserved.
The following behaviors are supported:
* - 1
- **Error**
- Emits an error if two values disagree. It is an error to have an
- ID with both an Error and a Warning behavior.
+ Emits an error if two values disagree, otherwise the resulting value
+ is that of the operands.
* - 2
- **Warning**
- Emits a warning if two values disagree.
+ Emits a warning if two values disagree. The result value will be the
+ operand for the flag from the first module being linked.
* - 3
- **Require**
- Emits an error when the specified value is not present or doesn't
- have the specified value. It is an error for two (or more)
- ``llvm.module.flags`` with the same ID to have the Require behavior
- but different values. There may be multiple Require flags per ID.
+ Adds a requirement that another module flag be present and have a
+ specified value after linking is performed. The value must be a
+ metadata pair, where the first element of the pair is the ID of the
+ module flag to be restricted, and the second element of the pair is
+ the value the module flag should be restricted to. This behavior can
+ be used to restrict the allowable results (via triggering of an
+ error) of linking IDs with the **Override** behavior.
* - 4
- **Override**
- Uses the specified value if the two values disagree. It is an
- error for two (or more) ``llvm.module.flags`` with the same ID
- to have the Override behavior but different values.
+ Uses the specified value, regardless of the behavior or value of the
+ other module. If both modules specify **Override**, but the values
+ differ, an error will be emitted.
+
+ * - 5
+ - **Append**
+ Appends the two values, which are required to be metadata nodes.
+
+ * - 6
+ - **AppendUnique**
+ Appends the two values, which are required to be metadata
+ nodes. However, duplicate entries in the second list are dropped
+ during the append operation.
+
+It is an error for a particular unique flag ID to have multiple behaviors,
+except in the case of **Require** (which adds restrictions on another metadata
+value) or **Override**.
An example of module flags:
- Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The
behavior if two or more ``!"bar"`` flags are seen is to use the value
- '37' if their values are not equal.
+ '37'.
- Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The
behavior if two or more ``!"qux"`` flags are seen is to emit a
metadata !{ metadata !"foo", i32 1 }
- The behavior is to emit an error if the ``llvm.module.flags`` does
- not contain a flag with the ID ``!"foo"`` that has the value '1'. If
- two or more ``!"qux"`` flags exist, then they must have the same
- value or an error will be issued.
+ The behavior is to emit an error if the ``llvm.module.flags`` does not
+ contain a flag with the ID ``!"foo"`` that has the value '1' after linking is
+ performed.
Objective-C Garbage Collection Module Flags Metadata
----------------------------------------------------
* - Key
- Value
- * - ``Objective-C Version``
- - **[Required]** — The Objective-C ABI version. Valid values are 1 and 2.
+ * - ``Objective-C Version``
+ - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2.
- * - ``Objective-C Image Info Version``
- - **[Required]** — The version of the image info section. Currently
+ * - ``Objective-C Image Info Version``
+ - **[Required]** --- The version of the image info section. Currently
always 0.
- * - ``Objective-C Image Info Section``
- - **[Required]** — The section to place the metadata. Valid values are
+ * - ``Objective-C Image Info Section``
+ - **[Required]** --- The section to place the metadata. Valid values are
``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and
``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for
Objective-C ABI version 2.
- * - ``Objective-C Garbage Collection``
- - **[Required]** — Specifies whether garbage collection is supported or
+ * - ``Objective-C Garbage Collection``
+ - **[Required]** --- Specifies whether garbage collection is supported or
not. Valid values are 0, for no garbage collection, and 2, for garbage
collection supported.
- * - ``Objective-C GC Only``
- - **[Optional]** — Specifies that only garbage collection is supported.
+ * - ``Objective-C GC Only``
+ - **[Optional]** --- Specifies that only garbage collection is supported.
If present, its value must be 6. This flag requires that the
``Objective-C Garbage Collection`` flag have the value 2.
- A module with ``Objective-C Garbage Collection`` set to 0 cannot be
merged with a module with ``Objective-C GC Only`` set to 6.
+Automatic Linker Flags Module Flags Metadata
+--------------------------------------------
+
+Some targets support embedding flags to the linker inside individual object
+files. Typically this is used in conjunction with language extensions which
+allow source files to explicitly declare the libraries they depend on, and have
+these automatically be transmitted to the linker via object files.
+
+These flags are encoded in the IR using metadata in the module flags section,
+using the ``Linker Options`` key. The merge behavior for this flag is required
+to be ``AppendUnique``, and the value for the key is expected to be a metadata
+node which should be a list of other metadata nodes, each of which should be a
+list of metadata strings defining linker options.
+
+For example, the following metadata section specifies two separate sets of
+linker options, presumably to link against ``libz`` and the ``Cocoa``
+framework::
+
+ !0 = metadata !{ i32 6, metadata !"Linker Options",
+ metadata !{
+ metadata !{ metadata !"-lz" },
+ metadata !{ metadata !"-framework", metadata !"Cocoa" } } }
+ !llvm.module.flags = !{ !0 }
+
+The metadata encoding as lists of lists of options, as opposed to a collapsed
+list of options, is chosen so that the IR encoding can use multiple option
+strings to specify e.g., a single library, while still having that specifier be
+preserved as an atomic element that can be recognized by a target specific
+assembly writer or object file emitter.
+
+Each individual option is required to be either a valid option for the target's
+linker, or an option that is reserved by the target specific assembly writer or
+object file emitter. No other aspect of these options is defined by the IR.
+
Intrinsic Global Variables
==========================
The '``landingpad``' instruction is used by `LLVM's exception handling
system <ExceptionHandling.html#overview>`_ to specify that a basic block
-is a landing pad — one where the exception lands, and corresponds to the
+is a landing pad --- one where the exception lands, and corresponds to the
code found in the ``catch`` portion of a ``try``/``catch`` sequence. It
defines values supplied by the personality function (``pers_fn``) upon
re-entry to the function. The ``resultval`` has the type ``resultty``.
function associated with the unwinding mechanism. The optional
``cleanup`` flag indicates that the landing pad block is a cleanup.
-A ``clause`` begins with the clause type — ``catch`` or ``filter`` — and
+A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and
contains the global variable representing the "type" that may be caught
or filtered respectively. Unlike the ``catch`` clause, the ``filter``
clause takes an array constant as its argument. Use
""""""""""
The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
-a signed addition of the two variables. They return a structure — the
+a signed addition of the two variables. They return a structure --- the
first element of which is the signed summation, and the second element
of which is a bit specifying if the signed summation resulted in an
overflow.
""""""""""
The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
-an unsigned addition of the two arguments. They return a structure — the
+an unsigned addition of the two arguments. They return a structure --- the
first element of which is the sum, and the second element of which is a
bit specifying if the unsigned summation resulted in a carry.
""""""""""
The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
-a signed subtraction of the two arguments. They return a structure — the
+a signed subtraction of the two arguments. They return a structure --- the
first element of which is the subtraction, and the second element of
which is a bit specifying if the signed subtraction resulted in an
overflow.
""""""""""
The '``llvm.usub.with.overflow``' family of intrinsic functions perform
-an unsigned subtraction of the two arguments. They return a structure —
+an unsigned subtraction of the two arguments. They return a structure ---
the first element of which is the subtraction, and the second element of
which is a bit specifying if the unsigned subtraction resulted in an
overflow.
""""""""""
The '``llvm.smul.with.overflow``' family of intrinsic functions perform
-a signed multiplication of the two arguments. They return a structure —
+a signed multiplication of the two arguments. They return a structure ---
the first element of which is the multiplication, and the second element
of which is a bit specifying if the signed multiplication resulted in an
overflow.
""""""""""
The '``llvm.umul.with.overflow``' family of intrinsic functions perform
-an unsigned multiplication of the two arguments. They return a structure
-— the first element of which is the multiplication, and the second
+an unsigned multiplication of the two arguments. They return a structure ---
+the first element of which is the multiplication, and the second
element of which is a bit specifying if the unsigned multiplication
resulted in an overflow.
"""""""""
The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add
-expressions that can be fused if the code generator determines that the
-fused expression would be legal and efficient.
+expressions that can be fused if the code generator determines that (a) the
+target instruction set has support for a fused operation, and (b) that the
+fused operation is more efficient than the equivalent, separate pair of mul
+and add instructions.
Arguments:
""""""""""
projects / oota-llvm.git / blobdiff