CbC/CbC_llvm: docs/LangRef.rst comparison

comparison docs/LangRef.rst @ 148:63bd29f05246

merged

author	Shinji KONO <kono@ie.u-ryukyu.ac.jp>
date	Wed, 14 Aug 2019 19:46:37 +0900
parents	c2174574ed3a
children

comparison

equal deleted inserted replaced

-:3fc4d5c3e21e
+:63bd29f05246
 '``[%@][-a-zA-Z$._][-a-zA-Z$._0-9]*``'. Identifiers that require other
 characters in their names can be surrounded with quotes. Special
 characters may be escaped using ``"\xx"`` where ``xx`` is the ASCII
 code for the character in hexadecimal. In this way, any character can
 be used in a name value, even quotes themselves. The ``"\01"`` prefix
-can be used on global variables to suppress mangling.
+can be used on global values to suppress mangling.
 #. Unnamed values are represented as an unsigned numeric value with
 their prefix. For example, ``%12``, ``@2``, ``%44``.
 #. Constants, which are described in the section Constants_ below.
 LLVM requires that values start with a prefix for two reasons: Compilers
 used when implementing functional programming languages. At the
 moment only X86 supports this convention and it has the following
 limitations:
 -  On *X86-32* only supports up to 4 bit type parameters. No
-floating point types are supported.
+floating-point types are supported.
 -  On *X86-64* only supports up to 10 bit type parameters and 6
-floating point parameters.
+floating-point parameters.
 This calling convention supports `tail call
 optimization <CodeGenerator.html#id80>`_ but requires both the
 caller and callee are using it.
 "``cc 11``" - The HiPE calling convention
 a few TLS IR variables, each access will be lowered to a platform-specific
 sequence.
 This calling convention aims to minimize overhead in the caller by
 preserving as many registers as possible (all the registers that are
-perserved on the fast path, composed of the entry and exit blocks).
+preserved on the fast path, composed of the entry and exit blocks).
 This calling convention behaves identical to the `C` calling convention on
 how arguments and return values are passed, but it uses a different set of
 caller/callee-saved registers.
 an optional list of attached :ref:`metadata <metadata>`.
 Variables and aliases can have a
 :ref:`Thread Local Storage Model <tls_model>`.
+:ref:`Scalable vectors <t_vector>` cannot be global variables or members of
+structs or arrays because their size is unknown at compile time.
 Syntax::
 @<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility]
 [DLLStorageClass] [ThreadLocal]
 [(unnamed_addr|local_unnamed_addr)] [AddrSpace]
 an optional :ref:`calling convention <callingconv>`,
 an optional ``unnamed_addr`` attribute, a return type, an optional
 :ref:`parameter attribute <paramattrs>` for the return type, a function
 name, a (possibly empty) argument list (each with optional :ref:`parameter
 attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`,
-an optional section, an optional alignment,
+an optional address space, an optional section, an optional alignment,
 an optional :ref:`comdat <langref_comdats>`,
 an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`,
 an optional :ref:`prologue <prologuedata>`,
 an optional :ref:`personality <personalityfn>`,
 an optional list of attached :ref:`metadata <metadata>`,
 LLVM function declarations consist of the "``declare``" keyword, an
 optional :ref:`linkage type <linkage>`, an optional :ref:`visibility style
 <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`, an
 optional :ref:`calling convention <callingconv>`, an optional ``unnamed_addr``
-or ``local_unnamed_addr`` attribute, a return type, an optional :ref:`parameter
+or ``local_unnamed_addr`` attribute, an optional address space, a return type,
-attribute <paramattrs>` for the return type, a function name, a possibly
+an optional :ref:`parameter attribute <paramattrs>` for the return type, a function name, a possibly
 empty list of arguments, an optional alignment, an optional :ref:`garbage
 collector name <gc>`, an optional :ref:`prefix <prefixdata>`, and an optional
 :ref:`prologue <prologuedata>`.
 A function definition contains a list of basic blocks, forming the CFG (Control
 Flow Graph) for the function. Each basic block may optionally start with a label
 (giving the basic block a symbol table entry), contains a list of instructions,
 and ends with a :ref:`terminator <terminators>` instruction (such as a branch or
-function return). If an explicit label is not provided, a block is assigned an
+function return). If an explicit label name is not provided, a block is assigned
-implicit numbered label, using the next value from the same counter as used for
+an implicit numbered label, using the next value from the same counter as used
-unnamed temporaries (:ref:`see above<identifiers>`). For example, if a function
+for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a
-entry block does not have an explicit label, it will be assigned label "%0",
+function entry block does not have an explicit label, it will be assigned label
-then the first unnamed temporary in that block will be "%1", etc.
+"%0", then the first unnamed temporary in that block will be "%1", etc. If a
+numeric label is explicitly specified, it must match the numeric label that
+would be used implicitly.
 The first basic block in a function is special in two ways: it is
 immediately executed on entrance to the function, and it is not allowed
 to have predecessor basic blocks (i.e. there can not be any branches to
 the entry block of a function). Because the block can have no
 be significant and two identical functions can be merged.
 If the ``local_unnamed_addr`` attribute is given, the address is known to
 not be significant within the module.
+If an explicit address space is not given, it will default to the program
+address space from the :ref:`datalayout string<langref_datalayout>`.
 Syntax::
 define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass]
 [cconv] [ret attrs]
 <ResultType> @<FunctionName> ([argument list])
-[(unnamed_addr|local_unnamed_addr)] [fn Attrs] [section "name"]
+[(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs]
-[comdat [($name)]] [align N] [gc] [prefix Constant]
+[section "name"] [comdat [($name)]] [align N] [gc] [prefix Constant]
 [prologue Constant] [personality Constant] (!name !N)* { ... }
 The argument list is a comma separated sequence of arguments where each
 argument is of the following form:
 in a special target-dependent fashion while emitting code for
 a function call or return (usually, by putting it in a register as
 opposed to memory, though some targets use it to distinguish between
 two different kinds of registers). Use of this attribute is
 target-specific.
-``byval``
+``byval`` or ``byval(<ty>)``
 This indicates that the pointer parameter should really be passed by
 value to the function. The attribute implies that a hidden copy of
 the pointee is made between the caller and the callee, so the callee
 is unable to modify the value in the caller. This attribute is only
 valid on LLVM pointer arguments. It is generally used to pass
 scalars. The copy is considered to belong to the caller not the
 callee (for example, ``readonly`` functions should not write to
 ``byval`` parameters). This is not a valid attribute for return
 values.
+The byval attribute also supports an optional type argument, which must be
+the same as the pointee type of the argument.
 The byval attribute also supports specifying an alignment with the
 align attribute. It indicates the alignment of the stack slot to
 form and the known alignment of the pointer specified to the call
 site. If the alignment is not specified, then the code generator
 makes a target-specific assumption.
 large aggregate return values, which means that frontend authors
 must lower them with ``sret`` pointers.
 When the call site is reached, the argument allocation must have
 been the most recent stack allocation that is still live, or the
-results are undefined. It is possible to allocate additional stack
+behavior is undefined. It is possible to allocate additional stack
 space after an argument allocation and before its call site, but it
 must be cleared off with :ref:`llvm.stackrestore
 <int_stackrestore>`.
 See :doc:`InAlloca` for more information on how to use this
 .. _attr_align:
 ``align <n>``
 This indicates that the pointer value may be assumed by the optimizer to
-have the specified alignment.
+have the specified alignment.  If the pointer value does not have the
+specified alignment, behavior is undefined.
 Note that this attribute has additional semantics when combined with the
-``byval`` attribute.
+``byval`` attribute, which are documented there.
 .. _noalias:
 ``noalias``
 This indicates that objects accessed via pointer values
 return values and can only be applied to one parameter.
 ``nonnull``
 This indicates that the parameter or return pointer is not null. This
 attribute may only be applied to pointer typed parameters. This is not
-checked or enforced by LLVM, the caller must ensure that the pointer
+checked or enforced by LLVM; if the parameter or return pointer is null,
-passed in is non-null, or the callee must ensure that the returned pointer
+the behavior is undefined.
-is non-null.
 ``dereferenceable(<n>)``
 This indicates that the parameter or return pointer is dereferenceable. This
 attribute may only be applied to pointer typed parameters. A pointer that
 is dereferenceable can be loaded from speculatively without a risk of
 on a parameter is not ABI-compatible with one which does not.
 These constraints also allow LLVM to assume that a ``swifterror`` argument
 does not alias any other memory visible within a function and that a
 ``swifterror`` alloca passed as an argument does not escape.
+``immarg``
+This indicates the parameter is required to be an immediate
+value. This must be a trivial immediate integer or floating-point
+constant. Undef or constant expressions are not valid. This is
+only valid on intrinsic declarations and cannot be applied to a
+call site or arbitrary function.
 .. _gc:
 Garbage Collector Strategy Names
 --------------------------------
 Similarly, the optimizer may remove ``convergent`` on calls/invokes when it
 can prove that the call/invoke cannot call a convergent function.
 ``inaccessiblememonly``
 This attribute indicates that the function may only access memory that
 is not accessible by the module being compiled. This is a weaker form
-of ``readnone``.
+of ``readnone``. If the function reads or writes other memory, the
+behavior is undefined.
 ``inaccessiblemem_or_argmemonly``
 This attribute indicates that the function may only access memory that is
 either not accessible by the module being compiled, or is pointed to
-by its pointer arguments. This is a weaker form of  ``argmemonly``
+by its pointer arguments. This is a weaker form of  ``argmemonly``. If the
+function reads or writes other memory, the behavior is undefined.
 ``inlinehint``
 This attribute indicates that the source code contained a hint that
 inlining this function is desirable (such as the "inline" keyword in
 C/C++). It is just a hint; it imposes no requirements on the
 inliner.
 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.
+``nofree``
+This function attribute indicates that the function does not, directly or
+indirectly, call a memory-deallocation function (free, for example). As a
+result, uncaptured pointers that are known to be dereferenceable prior to a
+call to a function with the ``nofree`` attribute are still known to be
+dereferenceable after the call (the capturing condition is necessary in
+environments where the function might communicate the pointer to another thread
+which then deallocates the memory).
 ``noimplicitfloat``
-This attributes disables implicit floating point instructions.
+This attributes disables implicit floating-point instructions.
 ``noinline``
 This attribute indicates that the inliner should never inline this
 function in any situation. This attribute may not be used together
 with the ``alwaysinline`` attribute.
 ``nonlazybind``
 may make calls to the function faster, at the cost of extra program
 startup time if the function is not called during program startup.
 ``noredzone``
 This attribute indicates that the code generator should not use a
 red zone, even if the target-specific ABI normally permits it.
+``indirect-tls-seg-refs``
+This attribute indicates that the code generator should not use
+direct TLS access through segment registers, even if the
+target-specific ABI normally permits it.
 ``noreturn``
 This function attribute indicates that the function never returns
-normally. This produces undefined behavior at runtime if the
+normally, hence through a return instruction. This produces undefined
-function ever does dynamically return.
+behavior at runtime if the function ever does dynamically return. Annotated
+functions may still raise an exception, i.a., ``nounwind`` is not implied.
 ``norecurse``
 This function attribute indicates that the function does not call itself
 either directly or indirectly down any possible call path. This produces
 undefined behavior at runtime if the function ever does recurse.
+``willreturn``
+This function attribute indicates that a call of this function will
+either exhibit undefined behavior or comes back and continues execution
+at a point in the existing call stack that includes the current invocation.
+Annotated functions may still raise an exception, i.a., ``nounwind`` is not implied.
+If an invocation of an annotated function does not return control back
+to a point in the call stack, the behavior is undefined.
+``nosync``
+This function attribute indicates that the function does not communicate
+(synchronize) with another thread through memory or other well-defined means.
+Synchronization is considered possible in the presence of `atomic` accesses
+that enforce an order, thus not "unordered" and "monotonic", `volatile` accesses,
+as well as `convergent` function calls. Note that through `convergent` function calls
+non-memory communication, e.g., cross-lane operations, are possible and are also
+considered synchronization. However `convergent` does not contradict `nosync`.
+If an annotated function does ever synchronize with another thread,
+the behavior is undefined.
 ``nounwind``
 This function attribute indicates that the function never raises an
 exception. If the function does raise an exception, its runtime
 behavior is undefined. However, functions marked nounwind may still
 trap or generate asynchronous exceptions. Exception handling schemes
 that are recognized by LLVM to handle asynchronous exceptions, such
 as SEH, will still provide their implementation defined semantics.
+``"null-pointer-is-valid"``
+If ``"null-pointer-is-valid"`` is set to ``"true"``, then ``null`` address
+in address-space 0 is considered to be a valid address for memory loads and
+stores. Any analysis or optimization should not treat dereferencing a
+pointer to ``null`` as undefined behavior in this function.
+Note: Comparing address of a global variable to ``null`` may still
+evaluate to false because of a limitation in querying this attribute inside
+constant expressions.
+``optforfuzzing``
+This attribute indicates that this function should be optimized
+for maximum fuzzing signal.
 ``optnone``
 This function attribute indicates that most optimization passes will skip
 this function, with the exception of interprocedural optimization passes.
 Code generation defaults to the "fast" instruction selector.
 This attribute cannot be used together with the ``alwaysinline``
 visible memory.
 On an argument, this attribute indicates that the function does not
 dereference that pointer argument, even though it may read or write the
 memory that the pointer points to if accessed through other pointers.
+If a readnone function reads or writes memory visible to the program, or
+has other side-effects, the behavior is undefined. If a function reads from
+or writes to a readnone pointer argument, the behavior is undefined.
 ``readonly``
 On a function, this attribute indicates that the function does not write
 through any pointer arguments (including ``byval`` arguments) or otherwise
 modify any state (e.g. memory, control registers, etc) visible to
 caller functions. It may dereference pointer arguments and read
 exceptions without writing to LLVM visible memory.
 On an argument, this attribute indicates that the function does not write
 through this pointer argument, even though it may write to the memory that
 the pointer points to.
+If a readonly function writes memory visible to the program, or
+has other side-effects, the behavior is undefined. If a function writes to
+a readonly pointer argument, the behavior is undefined.
 ``"stack-probe-size"``
 This attribute controls the behavior of stack probes: either
 the ``"probe-stack"`` attribute, or ABI-required stack probes, if any.
 It defines the size of the guard region. It ensures that if the function
 may use more stack space than the size of the guard region, stack probing
 function has the ``"stack-probe-size"`` attribute that has the lower
 numeric value. If a function that has a ``"stack-probe-size"`` attribute is
 inlined into a function that has no ``"stack-probe-size"`` attribute
 at all, the resulting function has the ``"stack-probe-size"`` attribute
 of the callee.
+``"no-stack-arg-probe"``
+This attribute disables ABI-required stack probes, if any.
 ``writeonly``
 On a function, this attribute indicates that the function may write to but
 does not read from memory.
 On an argument, this attribute indicates that the function may write to but
 does not read through this pointer argument (even though it may read from
 the memory that the pointer points to).
+If a writeonly function reads memory visible to the program, or
+has other side-effects, the behavior is undefined. If a function reads
+from a writeonly pointer argument, the behavior is undefined.
 ``argmemonly``
 This attribute indicates that the only memory accesses inside function are
 loads and stores from objects pointed to by its pointer-typed arguments,
 with arbitrary offsets. Or in other words, all memory operations in the
 function can refer to memory only using pointers based on its function
 arguments.
 Note that ``argmemonly`` can be used together with ``readonly`` attribute
 in order to specify that function reads only from its arguments.
+If an argmemonly function reads or writes memory other than the pointer
+arguments, or has other side-effects, the behavior is undefined.
 ``returns_twice``
 This attribute indicates that this function can return twice. The C
 ``setjmp`` is an example of such a function. The compiler disables
 some optimizations (like tail calls) in the caller of these
 functions.
 (dynamic thread safety analysis) are enabled for this function.
 ``sanitize_hwaddress``
 This attribute indicates that HWAddressSanitizer checks
 (dynamic address safety analysis based on tagged pointers) are enabled for
 this function.
+``sanitize_memtag``
+This attribute indicates that MemTagSanitizer checks
+(dynamic address safety analysis based on Armv8 MTE) are enabled for
+this function.
+``speculative_load_hardening``
+This attribute indicates that
+`Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
+should be enabled for the function body.
+Speculative Load Hardening is a best-effort mitigation against
+information leak attacks that make use of control flow
+miss-speculation - specifically miss-speculation of whether a branch
+is taken or not. Typically vulnerabilities enabling such attacks are
+classified as "Spectre variant #1". Notably, this does not attempt to
+mitigate against miss-speculation of branch target, classified as
+"Spectre variant #2" vulnerabilities.
+When inlining, the attribute is sticky. Inlining a function that carries
+this attribute will cause the caller to gain the attribute. This is intended
+to provide a maximally conservative model where the code in a function
+annotated with this attribute will always (even after inlining) end up
+hardened.
 ``speculatable``
 This function attribute indicates that the function does not have any
 effects besides calculating its result and does not have undefined behavior.
 Note that ``speculatable`` is not enough to conclude that along any
 particular execution path the number of calls to this function will not be
 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.
 ``strictfp``
 This attribute indicates that the function was called from a scope that
-requires strict floating point semantics.  LLVM will not attempt any
+requires strict floating-point semantics.  LLVM will not attempt any
-optimizations that require assumptions about the floating point rounding
+optimizations that require assumptions about the floating-point rounding
-mode or that might alter the state of floating point status flags that
+mode or that might alter the state of floating-point status flags that
 might otherwise be set or cleared by calling this function.
 ``"thunk"``
 This attribute indicates that the function will delegate to some other
 function with a tail call. The prototype of a thunk should not be used for
 optimization purposes. The caller is expected to cast the thunk prototype to
 This attribute indicates that the ABI being targeted requires that
 an unwind table entry be produced for this function even if we can
 show that no exceptions passes by it. This is normally the case for
 the ELF x86-64 abi, but it can be disabled for some compilation
 units.
+``nocf_check``
+This attribute indicates that no control-flow check will be performed on
+the attributed entity. It disables -fcf-protection=<> for a specific
+entity to fine grain the HW control flow protection mechanism. The flag
+is target independent and currently appertains to a function or function
+pointer.
+``shadowcallstack``
+This attribute indicates that the ShadowCallStack checks are enabled for
+the function. The instrumentation checks that the return address for the
+function has not changed between the function prolog and eiplog. It is
+currently x86_64-specific.
 .. _glattrs:
 Global Attributes
 -----------------
 promotion of stack variables is limited to the natural stack
 alignment to avoid dynamic stack realignment. The stack alignment
 must be a multiple of 8-bits. If omitted, the natural stack
 alignment defaults to "unspecified", which does not prevent any
 alignment promotions.
+``P<address space>``
+Specifies the address space that corresponds to program memory.
+Harvard architectures can use this to specify what space LLVM
+should place things such as functions into. If omitted, the
+program memory space defaults to the default address space of 0,
+which corresponds to a Von Neumann architecture that has code
+and data in the same space.
 ``A<address space>``
-Specifies the address space of  objects created by '``alloca``'.
+Specifies the address space of objects created by '``alloca``'.
 Defaults to the default address space of 0.
 ``p[n]:<size>:<abi>:<pref>:<idx>``
 This specifies the *size* of a pointer and its ``<abi>`` and
 ``<pref>``\erred alignments for address space ``n``. The fourth parameter
 ``<idx>`` is a size of index that used for address calculation. If not
 ``<size>``. The value of ``<size>`` must be in the range [1,2^23).
 ``v<size>:<abi>:<pref>``
 This specifies the alignment for a vector type of a given bit
 ``<size>``.
 ``f<size>:<abi>:<pref>``
-This specifies the alignment for a floating point type of a given bit
+This specifies the alignment for a floating-point type of a given bit
 ``<size>``. Only values of ``<size>`` that are supported by the target
 will work. 32 (float) and 64 (double) are supported on all targets; 80
 or 128 (different flavors of long double) are also supported on some
 targets.
 ``a:<abi>:<pref>``
 This specifies the alignment for an object of aggregate type.
+``F<type><abi>``
+This specifies the alignment for function pointers.
+The options for ``<type>`` are:
+* ``i``: The alignment of function pointers is independent of the alignment
+of functions, and is a multiple of ``<abi>``.
+* ``n``: The alignment of function pointers is a multiple of the explicit
+alignment specified on the function, and is a multiple of ``<abi>``.
 ``m:<mangling>``
-If present, specifies that llvm names are mangled in the output. The
+If present, specifies that llvm names are mangled in the output. Symbols
+prefixed with the mangling escape character ``\01`` are passed through
+directly to the assembler without the escape character. The mangling style
 options are
 * ``e``: ELF mangling: Private symbols get a ``.L`` prefix.
 * ``m``: Mips mangling: Private symbols get a ``$`` prefix.
 * ``o``: Mach-O mangling: Private symbols get ``L`` prefix. Other
 symbols get a ``_`` prefix.
-* ``w``: Windows COFF prefix:  Similar to Mach-O, but stdcall and fastcall
+* ``x``: Windows x86 COFF mangling: Private symbols get the usual prefix.
-functions also get a suffix based on the frame size.
+Regular C symbols get a ``_`` prefix. Functions with ``__stdcall``,
-* ``x``: Windows x86 COFF prefix:  Similar to Windows COFF, but use a ``_``
+``__fastcall``, and ``__vectorcall`` have custom mangling that appends
-prefix for ``__cdecl`` functions.
+``@N`` where N is the number of bytes used to pass parameters. C++ symbols
+starting with ``?`` are not mangled in any way.
+* ``w``: Windows COFF mangling: Similar to ``x``, except that normal C
+symbols do not receive a ``_`` prefix.
 ``n<size1>:<size2>:<size3>...``
 This specifies a set of native integer widths for the target CPU in
 bits. For example, it might contain ``n32`` for 32-bit PowerPC,
 ``n32:64`` for PowerPC 64, or ``n8:16:32:64`` for X86-64. Elements of
 this set are considered to support most general arithmetic operations
 of the variable's storage.
 -  The result value of an allocation instruction is associated with the
 address range of the allocated storage.
 -  A null pointer in the default address-space is associated with no
 address.
+-  An :ref:`undef value <undefvalues>` in *any* address-space is
+associated with no address.
 -  An integer constant other than zero or a pointer value returned from
 a function not defined within LLVM may be associated with address
 ranges allocated through mechanisms other than those provided by
 LLVM. Such ranges shall not overlap with any ranges of addresses
 allocated by mechanisms provided by LLVM.
 marked ``volatile``. The optimizers must not change the number of
 volatile operations or change their order of execution relative to other
 volatile operations. The optimizers *may* change the order of volatile
 operations relative to non-volatile operations. This is not Java's
 "volatile" and has no cross-thread synchronization behavior.
+A volatile load or store may have additional target-specific semantics.
+Any volatile operation can have side effects, and any volatile operation
+can read and/or modify state which is not accessible via a regular load
+or store in this module. Volatile operations may use addresses which do
+not point to memory (like MMIO registers). This means the compiler may
+not use a volatile operation to prove a non-volatile access to that
+address has defined behavior.
+The allowed side-effects for volatile accesses are limited.  If a
+non-volatile store to a given address would be legal, a volatile
+operation may modify the memory at that address. A volatile operation
+may not modify any other memory accessible by the module being compiled.
+A volatile operation may not call any code in the current module.
+The compiler may assume execution will continue after a volatile operation,
+so operations which modify memory or may have undefined behavior can be
+hoisted past a volatile operation.
 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.
 Otherwise, an atomic operation that is not marked ``syncscope("singlethread")``
 or ``syncscope("<target-scope>")`` *synchronizes with* and participates in the
 seq\_cst total orderings of other operations that are not marked
 ``syncscope("singlethread")`` or ``syncscope("<target-scope>")``.
+.. _floatenv:
+Floating-Point Environment
+--------------------------
+The default LLVM floating-point environment assumes that floating-point
+instructions do not have side effects. Results assume the round-to-nearest
+rounding mode. No floating-point exception state is maintained in this
+environment. Therefore, there is no attempt to create or preserve invalid
+operation (SNaN) or division-by-zero exceptions.
+The benefit of this exception-free assumption is that floating-point
+operations may be speculated freely without any other fast-math relaxations
+to the floating-point model.
+Code that requires different behavior than this should use the
+:ref:`Constrained Floating-Point Intrinsics <constrainedfp>`.
 .. _fastmath:
 Fast-Math Flags
 ---------------
 may use the following flags to enable otherwise unsafe
 floating-point transformations.
 ``nnan``
 No NaNs - Allow optimizations to assume the arguments and result are not
-NaN. Such optimizations are required to retain defined behavior over
+NaN. If an argument is a nan, or the result would be a nan, it produces
-NaNs, but the value of the result is undefined.
+a :ref:`poison value <poisonvalues>` instead.
 ``ninf``
 No Infs - Allow optimizations to assume the arguments and result are not
-+/-Inf. Such optimizations are required to retain defined behavior over
++/-Inf. If an argument is +/-Inf, or the result would be +/-Inf, it
-+/-Inf, but the value of the result is undefined.
+produces a :ref:`poison value <poisonvalues>` instead.
 ``nsz``
 No Signed Zeros - Allow optimizations to treat the sign of a zero
 argument or result as insignificant.
 functions (sin, log, sqrt, etc). See floating-point intrinsic definitions
 for places where this can apply to LLVM's intrinsic math functions.
 ``reassoc``
 Allow reassociation transformations for floating-point instructions.
-This may dramatically change results in floating point.
+This may dramatically change results in floating-point.
 ``fast``
 This flag implies all of the others.
 .. _uselistorder:
 | ``i1942652``   | a really big integer of over 1 million bits.   |
 +----------------+------------------------------------------------+
 .. _t_floating:
-Floating Point Types
+Floating-Point Types
 """"""""""""""""""""
 .. list-table::
 :header-rows: 1
 * - Type
 - Description
 * - ``half``
-- 16-bit floating point value
+- 16-bit floating-point value
 * - ``float``
-- 32-bit floating point value
+- 32-bit floating-point value
 * - ``double``
-- 64-bit floating point value
+- 64-bit floating-point value
 * - ``fp128``
-- 128-bit floating point value (112-bit mantissa)
+- 128-bit floating-point value (112-bit mantissa)
 * - ``x86_fp80``
--  80-bit floating point value (X87)
+-  80-bit floating-point value (X87)
 * - ``ppc_fp128``
-- 128-bit floating point value (two 64-bits)
+- 128-bit floating-point value (two 64-bits)
+The binary format of half, float, double, and fp128 correspond to the
+IEEE-754-2008 specifications for binary16, binary32, binary64, and binary128
+respectively.
 X86_mmx Type
 """"""""""""
 :Overview:
 :Overview:
 A vector type is a simple derived type that represents a vector of
 elements. Vector types are used when multiple primitive data are
 operated in parallel using a single instruction (SIMD). A vector type
-requires a size (number of elements) and an underlying primitive data
+requires a size (number of elements), an underlying primitive data type,
-type. Vector types are considered :ref:`first class <t_firstclass>`.
+and a scalable property to represent vectors where the exact hardware
+vector length is unknown at compile time. Vector types are considered
+:ref:`first class <t_firstclass>`.
 :Syntax:
 ::
-< <# elements> x <elementtype> >
+< <# elements> x <elementtype> >          ; Fixed-length vector
+< vscale x <# elements> x <elementtype> > ; Scalable vector
 The number of elements is a constant integer value larger than 0;
-elementtype may be any integer, floating point or pointer type. Vectors
+elementtype may be any integer, floating-point or pointer type. Vectors
-of size zero are not allowed.
+of size zero are not allowed. For scalable vectors, the total number of
+elements is a constant multiple (called vscale) of the specified number
+of elements; vscale is a positive integer that is unknown at compile time
+and the same hardware-dependent constant for all scalable vectors at run
+time. The size of a specific scalable vector type is thus constant within
+IR, even if the exact size in bytes cannot be determined until run time.
 :Examples:
-+-------------------+--------------------------------------------------+
++------------------------+----------------------------------------------------+
-| ``<4 x i32>``     | Vector of 4 32-bit integer values.               |
+| ``<4 x i32>``          | Vector of 4 32-bit integer values.                 |
-+-------------------+--------------------------------------------------+
++------------------------+----------------------------------------------------+
-| ``<8 x float>``   | Vector of 8 32-bit floating-point values.        |
+| ``<8 x float>``        | Vector of 8 32-bit floating-point values.          |
-+-------------------+--------------------------------------------------+
++------------------------+----------------------------------------------------+
-| ``<2 x i64>``     | Vector of 2 64-bit integer values.               |
+| ``<2 x i64>``          | Vector of 2 64-bit integer values.                 |
-+-------------------+--------------------------------------------------+
++------------------------+----------------------------------------------------+
-| ``<4 x i64*>``    | Vector of 4 pointers to 64-bit integer values.   |
+| ``<4 x i64*>``         | Vector of 4 pointers to 64-bit integer values.     |
-+-------------------+--------------------------------------------------+
++------------------------+----------------------------------------------------+
+| ``<vscale x 4 x i32>`` | Vector with a multiple of 4 32-bit integer values. |
++------------------------+----------------------------------------------------+
 .. _t_label:
 Label Type
 ^^^^^^^^^^
 Here are some examples of multidimensional arrays:
 +-----------------------------+----------------------------------------------------------+
 | ``[3 x [4 x i32]]``         | 3x4 array of 32-bit integer values.                      |
 +-----------------------------+----------------------------------------------------------+
-| ``[12 x [10 x float]]``     | 12x10 array of single precision floating point values.   |
+| ``[12 x [10 x float]]``     | 12x10 array of single precision floating-point values.   |
 +-----------------------------+----------------------------------------------------------+
 | ``[2 x [3 x [4 x i16]]]``   | 2x3x4 array of 16-bit integer values.                    |
 +-----------------------------+----------------------------------------------------------+
 There is no restriction on indexing beyond the end of the array implied
 of the ``i1`` type.
 **Integer constants**
 Standard integers (such as '4') are constants of the
 :ref:`integer <t_integer>` type. Negative numbers may be used with
 integer types.
-**Floating point constants**
+**Floating-point constants**
-Floating point constants use standard decimal notation (e.g.
+Floating-point constants use standard decimal notation (e.g.
 123.421), exponential notation (e.g. 1.23421e+2), or a more precise
 hexadecimal notation (see below). The assembler requires the exact
 decimal value of a floating-point constant. For example, the
 assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating
-decimal in binary. Floating point constants must have a :ref:`floating
+decimal in binary. Floating-point constants must have a
-point <t_floating>` type.
+:ref:`floating-point <t_floating>` type.
 **Null pointer constants**
 The identifier '``null``' is recognized as a null pointer constant
 and must be of :ref:`pointer type <t_pointer>`.
 **Token constants**
 The identifier '``none``' is recognized as an empty token constant
 and must be of :ref:`token type <t_token>`.
 The one non-intuitive notation for constants is the hexadecimal form of
-floating point constants. For example, the form
+floating-point constants. For example, the form
 '``double    0x432ff973cafa8000``' is equivalent to (but harder to read
-than) '``double 4.5e+15``'. The only time hexadecimal floating point
+than) '``double 4.5e+15``'. The only time hexadecimal floating-point
 constants are required (and the only time that they are generated by the
-disassembler) is when a floating point constant must be emitted but it
+disassembler) is when a floating-point constant must be emitted but it
-cannot be represented as a decimal floating point number in a reasonable
+cannot be represented as a decimal floating-point number in a reasonable
 number of digits. For example, NaN's, infinities, and other special
 values are represented in their IEEE hexadecimal format so that assembly
 and disassembly do not cause any bits to change in the constants.
 When using the hexadecimal form, constants of types half, float, and
 ``%C`` need to have the same semantics or the core LLVM "replace all
 uses with" concept would not hold.
 .. code-block:: llvm
-%A = fdiv undef, %X
+%A = sdiv undef, %X
-%B = fdiv %X, undef
+%B = sdiv %X, undef
 Safe:
-%A = undef
+%A = 0
 b: unreachable
 These examples show the crucial difference between an *undefined value*
 and *undefined behavior*. An undefined value (like '``undef``') is
 allowed to have an arbitrary bit-pattern. This means that the ``%A``
-operation can be constant folded to '``undef``', because the '``undef``'
+operation can be constant folded to '``0``', because the '``undef``'
-could be an SNaN, and ``fdiv`` is not (currently) defined on SNaN's.
+could be zero, and zero divided by any value is zero.
 However, in the second example, we can make a more aggressive
 assumption: because the ``undef`` is allowed to be an arbitrary value,
 we are allowed to assume that it could be zero. Since a divide by zero
 has *undefined behavior*, we are allowed to assume that the operation
 does not execute at all. This allows us to delete the divide and all
 b:  store %X -> undef
 Safe:
 a: <deleted>
 b: unreachable
-These examples reiterate the ``fdiv`` example: a store *of* an undefined
+A store *of* an undefined value can be assumed to not have any effect;
-value can be assumed to not have any effect; we can assume that the
+we can assume that the value is overwritten with bits that happen to
-value is overwritten with bits that happen to match what was already
+match what was already there. However, a store *to* an undefined
-there. However, a store *to* an undefined location could clobber
+location could clobber arbitrary memory, therefore, it has undefined
-arbitrary memory, therefore, it has undefined behavior.
+behavior.
 .. _poisonvalues:
 Poison Values
 -------------
-Poison values are similar to :ref:`undef values <undefvalues>`, however
+In order to facilitate speculative execution, many instructions do not
-they also represent the fact that an instruction or constant expression
+invoke immediate undefined behavior when provided with illegal operands,
-that cannot evoke side effects has nevertheless detected a condition
+and return a poison value instead.
-that results in undefined behavior.
 There is currently no way of representing a poison value in the IR; they
 only exist when produced by operations such as :ref:`add <i_add>` with
 the ``nsw`` flag.
 instruction if the set of instructions it otherwise depends on would
 be different if the terminator had transferred control to a different
 successor.
 -  Dependence is transitive.
-Poison values have the same behavior as :ref:`undef values <undefvalues>`,
+An instruction that *depends* on a poison value, produces a poison value
-with the additional effect that any instruction that has a *dependence*
+itself. A poison value may be relaxed into an
-on a poison value has undefined behavior.
+:ref:`undef value <undefvalues>`, which takes an arbitrary bit-pattern.
+This means that immediate undefined behavior occurs if a poison value is
+used as an instruction operand that has any values that trigger undefined
+behavior. Notably this includes (but is not limited to):
+-  The pointer operand of a :ref:`load <i_load>`, :ref:`store <i_store>` or
+any other pointer dereferencing instruction (independent of address
+space).
+-  The divisor operand of a ``udiv``, ``sdiv``, ``urem`` or ``srem``
+instruction.
+Additionally, undefined behavior occurs if a side effect *depends* on poison.
+This includes side effects that are control dependent on a poisoned branch.
 Here are some examples:
 .. code-block:: llvm
 entry:
 %poison = sub nuw i32 0, 1           ; Results in a poison value.
 %still_poison = and i32 %poison, 0   ; 0, but also poison.
 %poison_yet_again = getelementptr i32, i32* @h, i32 %still_poison
-store i32 0, i32* %poison_yet_again  ; memory at @h[0] is poisoned
+store i32 0, i32* %poison_yet_again  ; Undefined behavior due to
+; store to poison.
 store i32 %poison, i32* @g           ; Poison value stored to memory.
 %poison2 = load i32, i32* @g         ; Poison value loaded back from memory.
-store volatile i32 %poison, i32* @g  ; External observation; undefined behavior.
 %narrowaddr = bitcast i32* @g to i16*
 %wideaddr = bitcast i32* @g to i64*
 %poison3 = load i16, i16* %narrowaddr ; Returns a poison value.
 %poison4 = load i64, i64* %wideaddr  ; Returns a poison value.
 The '``blockaddress``' constant computes the address of the specified
 basic block in the specified function, and always has an ``i8*`` type.
 Taking the address of the entry block is illegal.
 This value only has defined behavior when used as an operand to the
-':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons
+':ref:`indirectbr <i_indirectbr>`' or ':ref:`callbr <i_callbr>`'instruction, or
-against null. Pointer equality tests between labels addresses results in
+for comparisons against null. Pointer equality tests between labels addresses
-undefined behavior --- though, again, comparison against null is ok, and
+results in undefined behavior --- though, again, comparison against null is ok,
-no label is equal to the null pointer. This may be passed around as an
+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
-long as the original value is reconstituted before the ``indirectbr``
+long as the original value is reconstituted before the ``indirectbr`` or
-instruction.
+``callbr`` instruction.
 Finally, some targets may provide defined semantics when using the value
 as the operand to an inline assembly, but that is target specific.
 .. _constantexprs:
 ``zext (CST to TYPE)``
 Perform the :ref:`zext operation <i_zext>` on constants.
 ``sext (CST to TYPE)``
 Perform the :ref:`sext operation <i_sext>` on constants.
 ``fptrunc (CST to TYPE)``
-Truncate a floating point constant to another floating point type.
+Truncate a floating-point constant to another floating-point type.
 The size of CST must be larger than the size of TYPE. Both types
-must be floating point.
+must be floating-point.
 ``fpext (CST to TYPE)``
-Floating point extend a constant to another type. The size of CST
+Floating-point extend a constant to another type. The size of CST
 must be smaller or equal to the size of TYPE. Both types must be
-floating point.
+floating-point.
 ``fptoui (CST to TYPE)``
-Convert a floating point constant to the corresponding unsigned
+Convert a floating-point constant to the corresponding unsigned
 integer constant. TYPE must be a scalar or vector integer type. CST
-must be of scalar or vector floating point type. Both CST and TYPE
+must be of scalar or vector floating-point type. Both CST and TYPE
 must be scalars, or vectors of the same number of elements. If the
-value won't fit in the integer type, the results are undefined.
+value won't fit in the integer type, the result is a
+:ref:`poison value <poisonvalues>`.
 ``fptosi (CST to TYPE)``
-Convert a floating point constant to the corresponding signed
+Convert a floating-point constant to the corresponding signed
 integer constant. TYPE must be a scalar or vector integer type. CST
-must be of scalar or vector floating point type. Both CST and TYPE
+must be of scalar or vector floating-point type. Both CST and TYPE
 must be scalars, or vectors of the same number of elements. If the
-value won't fit in the integer type, the results are undefined.
+value won't fit in the integer type, the result is a
+:ref:`poison value <poisonvalues>`.
 ``uitofp (CST to TYPE)``
-Convert an unsigned integer constant to the corresponding floating
+Convert an unsigned integer constant to the corresponding
-point constant. TYPE must be a scalar or vector floating point type.
+floating-point constant. TYPE must be a scalar or vector floating-point
+type.  CST must be of scalar or vector integer type. Both CST and TYPE must
+be scalars, or vectors of the same number of elements.
+``sitofp (CST to TYPE)``
+Convert a signed integer constant to the corresponding floating-point
+constant. TYPE must be a scalar or vector floating-point type.
 CST must be of scalar or vector integer type. Both CST and TYPE must
-be scalars, or vectors of the same number of elements. If the value
+be scalars, or vectors of the same number of elements.
-won't fit in the floating point type, the results are undefined.
-``sitofp (CST to TYPE)``
-Convert a signed integer constant to the corresponding floating
-point constant. TYPE must be a scalar or vector floating point type.
-CST must be of scalar or vector integer type. Both CST and TYPE must
-be scalars, or vectors of the same number of elements. If the value
-won't fit in the floating point type, the results are undefined.
 ``ptrtoint (CST to TYPE)``
 Perform the :ref:`ptrtoint operation <i_ptrtoint>` on constants.
 ``inttoptr (CST to TYPE)``
 Perform the :ref:`inttoptr operation <i_inttoptr>` on constants.
 This one is *really* dangerous!
 ``OPCODE (LHS, RHS)``
 Perform the specified operation of the LHS and RHS constants. OPCODE
 may be any of the :ref:`binary <binaryops>` or :ref:`bitwise
 binary <bitwiseops>` operations. The constraints on operands are
 the same as those for the corresponding instruction (e.g. no bitwise
-operations on floating point values are allowed).
+operations on floating-point values are allowed).
 Other Values
 ============
 .. _inlineasmexprs:
 All ARM modes:
 - ``Q``, ``Um``, ``Un``, ``Uq``, ``Us``, ``Ut``, ``Uv``, ``Uy``: Memory address
 operand. Treated the same as operand ``m``, at the moment.
+- ``Te``: An even general-purpose 32-bit integer register: ``r0,r2,...,r12,r14``
+- ``To``: An odd general-purpose 32-bit integer register: ``r1,r3,...,r11``
 ARM and ARM's Thumb2 mode:
 - ``j``: An immediate integer between 0 and 65535 (valid for ``MOVW``)
 - ``I``: An immediate integer valid for a data-processing instruction.
 - ``y``: Condition register (``CR0-CR7``).
 - ``wc``: An individual CR bit in a CR register.
 - ``wa``, ``wd``, ``wf``: Any 128-bit VSX vector register, from the full VSX
 register set (overlapping both the floating-point and vector register files).
-- ``ws``: A 32 or 64-bit floating point register, from the full VSX register
+- ``ws``: A 32 or 64-bit floating-point register, from the full VSX register
 set.
+RISC-V:
+- ``A``: An address operand (using a general-purpose register, without an
+offset).
+- ``I``: A 12-bit signed integer immediate operand.
+- ``J``: A zero integer immediate operand.
+- ``K``: A 5-bit unsigned integer immediate operand.
+- ``f``: A 32- or 64-bit floating-point register (requires F or D extension).
+- ``r``: A 32- or 64-bit general-purpose register (depending on the platform
+``XLEN``).
 Sparc:
 - ``I``: An immediate 13-bit signed integer.
 - ``r``: A 32-bit integer register.
-- ``f``: Any floating-point register on SparcV8, or a floating point
+- ``f``: Any floating-point register on SparcV8, or a floating-point
 register in the "low" half of the registers on SparcV9.
-- ``e``: Any floating point register. (Same as ``f`` on SparcV8.)
+- ``e``: Any floating-point register. (Same as ``f`` on SparcV8.)
 SystemZ:
 - ``I``: An immediate unsigned 8-bit integer.
 - ``J``: An immediate unsigned 12-bit integer.
 - ``r`` or ``d``: A 32, 64, or 128-bit integer register.
 - ``a``: A 32, 64, or 128-bit integer address register (excludes R0, which in an
 address context evaluates as zero).
 - ``h``: A 32-bit value in the high part of a 64bit data register
 (LLVM-specific)
-- ``f``: A 32, 64, or 128-bit floating point register.
+- ``f``: A 32, 64, or 128-bit floating-point register.
 X86:
 - ``I``: An immediate integer between 0 and 31.
 - ``J``: An immediate integer between 0 and 64.
 - ``count: -1`` indicates an empty array.
 - ``count: !9`` describes the count with a :ref:`DILocalVariable`.
 - ``count: !11`` describes the count with a :ref:`DIGlobalVariable`.
-.. code-block:: llvm
+.. code-block:: text
 !0 = !DISubrange(count: 5, lowerBound: 0) ; array counting from 0
 !1 = !DISubrange(count: 5, lowerBound: 1) ; array counting from 1
 !2 = !DISubrange(count: -1) ; empty array.
 ; Scopes used in rest of example
 !6 = !DIFile(filename: "vla.c", directory: "/path/to/file")
-!7 = distinct !DICompileUnit(language: DW_LANG_C99, ...
+!7 = distinct !DICompileUnit(language: DW_LANG_C99, file: !6)
-!8 = distinct !DISubprogram(name: "foo", scope: !7, file: !6, line: 5, ...
+!8 = distinct !DISubprogram(name: "foo", scope: !7, file: !6, line: 5)
 ; Use of local variable as count value
 !9 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed)
 !10 = !DILocalVariable(name: "count", scope: !8, file: !6, line: 42, type: !9)
-!11 = !DISubrange(count !10, lowerBound: 0)
+!11 = !DISubrange(count: !10, lowerBound: 0)
 ; Use of global variable as count value
 !12 = !DIGlobalVariable(name: "count", scope: !8, file: !6, line: 22, type: !9)
-!13 = !DISubrange(count !12, lowerBound: 0)
+!13 = !DISubrange(count: !12, lowerBound: 0)
 .. _DIEnumerator:
 DIEnumerator
 """"""""""""
 ``DIEnumerator`` nodes are the elements for ``DW_TAG_enumeration_type``
 variants of :ref:`DICompositeType`.
-.. code-block:: llvm
+.. code-block:: text
 !0 = !DIEnumerator(name: "SixKind", value: 7)
 !1 = !DIEnumerator(name: "SevenKind", value: 7)
 !2 = !DIEnumerator(name: "NegEightKind", value: -8)
 ``DITemplateTypeParameter`` nodes represent type parameters to generic source
 language constructs. They are used (optionally) in :ref:`DICompositeType` and
 :ref:`DISubprogram` ``templateParams:`` fields.
-.. code-block:: llvm
+.. code-block:: text
 !0 = !DITemplateTypeParameter(name: "Ty", type: !1)
 DITemplateValueParameter
 """"""""""""""""""""""""
 language constructs. ``tag:`` defaults to ``DW_TAG_template_value_parameter``,
 but if specified can also be set to ``DW_TAG_GNU_template_template_param`` or
 ``DW_TAG_GNU_template_param_pack``. They are used (optionally) in
 :ref:`DICompositeType` and :ref:`DISubprogram` ``templateParams:`` fields.
-.. code-block:: llvm
+.. code-block:: text
 !0 = !DITemplateValueParameter(name: "Ty", type: !1, value: i32 7)
 DINamespace
 """""""""""
 ``DINamespace`` nodes represent namespaces in the source language.
-.. code-block:: llvm
+.. code-block:: text
 !0 = !DINamespace(name: "myawesomeproject", scope: !1, file: !2, line: 7)
 .. _DIGlobalVariable:
 DIGlobalVariable
 """"""""""""""""
 ``DIGlobalVariable`` nodes represent global variables in the source language.
-.. code-block:: llvm
+.. code-block:: text
-!0 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !1,
+@foo = global i32, !dbg !0
-file: !2, line: 7, type: !3, isLocal: true,
+!0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression())
-isDefinition: false, variable: i32* @foo,
+!1 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !2,
-declaration: !4)
+file: !3, line: 7, type: !4, isLocal: true,
+isDefinition: false, declaration: !5)
-All global variables should be referenced by the `globals:` field of a
-:ref:`compile unit <DICompileUnit>`.
+DIGlobalVariableExpression
+""""""""""""""""""""""""""
+``DIGlobalVariableExpression`` nodes tie a :ref:`DIGlobalVariable` together
+with a :ref:`DIExpression`.
+.. code-block:: text
+@lower = global i32, !dbg !0
+@upper = global i32, !dbg !1
+!0 = !DIGlobalVariableExpression(
+var: !2,
+expr: !DIExpression(DW_OP_LLVM_fragment, 0, 32)
+)
+!1 = !DIGlobalVariableExpression(
+var: !2,
+expr: !DIExpression(DW_OP_LLVM_fragment, 32, 32)
+)
+!2 = !DIGlobalVariable(name: "split64", linkageName: "split64", scope: !3,
+file: !4, line: 8, type: !5, declaration: !6)
+All global variable expressions should be referenced by the `globals:` field of
+a :ref:`compile unit <DICompileUnit>`.
 .. _DISubprogram:
 DISubprogram
 """"""""""""
 ``DISubprogram`` nodes represent functions from the source language. A
-``DISubprogram`` may be attached to a function definition using ``!dbg``
+distinct ``DISubprogram`` may be attached to a function definition using
-metadata. The ``variables:`` field points at :ref:`variables <DILocalVariable>`
+``!dbg`` metadata. A unique ``DISubprogram`` may be attached to a function
-that must be retained, even if their IR counterparts are optimized out of
+declaration used for call site debug info. The ``variables:`` field points at
-the IR. The ``type:`` field must point at an :ref:`DISubroutineType`.
+:ref:`variables <DILocalVariable>` that must be retained, even if their IR
+counterparts are optimized out of the IR. The ``type:`` field must point at an
+:ref:`DISubroutineType`.
 .. _DISubprogramDeclaration:
 When ``isDefinition: false``, subprograms describe a declaration in the type
 tree as opposed to a definition of a function.  If the scope is a composite
 ``DILexicalBlockFile`` nodes are used to discriminate between sections of a
 :ref:`lexical block <DILexicalBlock>`. The ``file:`` field can be changed to
 indicate textual inclusion, or the ``discriminator:`` field can be used to
 discriminate between control flow within a single block in the source language.
-.. code-block:: llvm
+.. code-block:: text
 !0 = !DILexicalBlock(scope: !3, file: !4, line: 7, column: 35)
 !1 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 0)
 !2 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 1)
 ``DILocation`` nodes represent source debug locations. The ``scope:`` field is
 mandatory, and points at an :ref:`DILexicalBlockFile`, an
 :ref:`DILexicalBlock`, or an :ref:`DISubprogram`.
-.. code-block:: llvm
+.. code-block:: text
 !0 = !DILocation(line: 2900, column: 42, scope: !1, inlinedAt: !2)
 .. _DILocalVariable:
 type: !3, flags: DIFlagArtificial)
 !1 = !DILocalVariable(name: "x", arg: 2, scope: !4, file: !2, line: 7,
 type: !3)
 !2 = !DILocalVariable(name: "y", scope: !5, file: !2, line: 7, type: !3)
+.. _DIExpression:
 DIExpression
 """"""""""""
 ``DIExpression`` nodes represent expressions that are inspired by the DWARF
 expression language. They are used in :ref:`debug intrinsics<dbg_intrinsics>`
 (such as ``llvm.dbg.declare`` and ``llvm.dbg.value``) to describe how the
-referenced LLVM variable relates to the source language variable.
+referenced LLVM variable relates to the source language variable. Debug
+intrinsics are interpreted left-to-right: start by pushing the value/address
-The current supported vocabulary is limited:
+operand of the intrinsic onto a stack, then repeatedly push and evaluate
+opcodes from the DIExpression until the final variable description is produced.
+The current supported opcode vocabulary is limited:
 - ``DW_OP_deref`` dereferences the top of the expression stack.
 - ``DW_OP_plus`` pops the last two entries from the expression stack, adds
 them together and appends the result to the expression stack.
 - ``DW_OP_minus`` pops the last two entries from the expression stack, subtracts
 - ``DW_OP_plus_uconst, 93`` adds ``93`` to the working expression.
 - ``DW_OP_LLVM_fragment, 16, 8`` specifies the offset and size (``16`` and ``8``
 here, respectively) of the variable fragment from the working expression. Note
 that contrary to DW_OP_bit_piece, the offset is describing the location
 within the described source variable.
+- ``DW_OP_LLVM_convert, 16, DW_ATE_signed`` specifies a bit size and encoding
+(``16`` and ``DW_ATE_signed`` here, respectively) to which the top of the
+expression stack is to be converted. Maps into a ``DW_OP_convert`` operation
+that references a base type constructed from the supplied values.
+- ``DW_OP_LLVM_tag_offset, tag_offset`` specifies that a memory tag should be
+optionally applied to the pointer. The memory tag is derived from the
+given tag offset in an implementation-defined manner.
 - ``DW_OP_swap`` swaps top two stack entries.
 - ``DW_OP_xderef`` provides extended dereference mechanism. The entry at the top
 of the stack is treated as an address. The second stack entry is treated as an
 address space identifier.
 - ``DW_OP_stack_value`` marks a constant value.
+- If an expression is marked with ``DW_OP_entry_value`` all register and
+memory read operations refer to the respective value at the function entry.
+The first operand of ``DW_OP_entry_value`` is the size of following
+DWARF expression.
+``DW_OP_entry_value`` may appear after the ``LiveDebugValues`` pass.
+LLVM only supports entry values for function parameters
+that are unmodified throughout a function and that are described as
+simple register location descriptions.
+``DW_OP_entry_value`` may also appear after the ``AsmPrinter`` pass when
+a call site parameter value (``DW_AT_call_site_parameter_value``)
+is represented as entry value of the parameter.
+- ``DW_OP_breg`` (or ``DW_OP_bregx``) represents a content on the provided
+signed offset of the specified register. The opcode is only generated by the
+``AsmPrinter`` pass to describe call site parameter value which requires an
+expression over two registers.
 DWARF specifies three kinds of simple location descriptions: Register, memory,
-and implicit location descriptions. Register and memory location descriptions
+and implicit location descriptions.  Note that a location description is
-describe the *location* of a source variable (in the sense that a debugger might
+defined over certain ranges of a program, i.e the location of a variable may
-modify its value), whereas implicit locations describe merely the *value* of a
+change over the course of the program. Register and memory location
-source variable. DIExpressions also follow this model: A DIExpression that
+descriptions describe the *concrete location* of a source variable (in the
-doesn't have a trailing ``DW_OP_stack_value`` will describe an *address* when
+sense that a debugger might modify its value), whereas *implicit locations*
-combined with a concrete location.
+describe merely the actual *value* of a source variable which might not exist
+in registers or in memory (see ``DW_OP_stack_value``).
+A ``llvm.dbg.addr`` or ``llvm.dbg.declare`` intrinsic describes an indirect
+value (the address) of a source variable. The first operand of the intrinsic
+must be an address of some kind. A DIExpression attached to the intrinsic
+refines this address to produce a concrete location for the source variable.
+A ``llvm.dbg.value`` intrinsic describes the direct value of a source variable.
+The first operand of the intrinsic may be a direct or indirect value. A
+DIExpresion attached to the intrinsic refines the first operand to produce a
+direct value. For example, if the first operand is an indirect value, it may be
+necessary to insert ``DW_OP_deref`` into the DIExpresion in order to produce a
+valid debug intrinsic.
+.. note::
+A DIExpression is interpreted in the same way regardless of which kind of
+debug intrinsic it's attached to.
 .. code-block:: text
 !0 = !DIExpression(DW_OP_deref)
 !1 = !DIExpression(DW_OP_plus_uconst, 3)
 !2 = !DIExpression(DW_OP_bit_piece, 3, 7)
 !3 = !DIExpression(DW_OP_deref, DW_OP_constu, 3, DW_OP_plus, DW_OP_LLVM_fragment, 3, 7)
 !4 = !DIExpression(DW_OP_constu, 2, DW_OP_swap, DW_OP_xderef)
 !5 = !DIExpression(DW_OP_constu, 42, DW_OP_stack_value)
+DIFlags
+"""""""""""""""
+These flags encode various properties of DINodes.
+The `ArgumentNotModified` flag marks a function argument whose value
+is not modified throughout of a function. This flag is used to decide
+whether a DW_OP_entry_value can be used in a location description
+after the function prologue. The language frontend is expected to compute
+this property for each DILocalVariable. The flag should be used
+only in optimized code.
 DIObjCProperty
 """"""""""""""
 ``DIObjCProperty`` nodes represent Objective-C property nodes.
-.. code-block:: llvm
+.. code-block:: text
 !3 = !DIObjCProperty(name: "foo", file: !1, line: 7, setter: "setFoo",
 getter: "getFoo", attributes: 7, type: !2)
 DIImportedEntity
 };
 void f(struct Outer* outer, struct Inner* inner, float* f, int* i, char* c) {
 outer->f = 0;            // tag0: (OuterStructTy, FloatScalarTy, 0)
 outer->inner_a.i = 0;    // tag1: (OuterStructTy, IntScalarTy, 12)
-outer->inner_a.f = 0.0;  // tag2: (OuterStructTy, IntScalarTy, 16)
+outer->inner_a.f = 0.0;  // tag2: (OuterStructTy, FloatScalarTy, 16)
 *f = 0.0;                // tag3: (FloatScalarTy, FloatScalarTy, 0)
 }
 is (note that in C and C++, ``char`` can be used to access any arbitrary
 type):
 store float %0, float* %arrayidx.i, align 4, !noalias !7
 '``fpmath``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^
-``fpmath`` metadata may be attached to any instruction of floating point
+``fpmath`` metadata may be attached to any instruction of floating-point
 type. It can be used to express the maximum acceptable error in the
 result of that instruction, in ULPs, thus potentially allowing the
 compiler to use a more efficient but less accurate method of computing
 it. ULP is defined as follows:
 '``range``' Metadata
 ^^^^^^^^^^^^^^^^^^^^
 ``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of
 integer types. It expresses the possible ranges the loaded value or the value
-returned by the called function at this call site is in. The ranges are
+returned by the called function at this call site is in. If the loaded or
-represented with a flattened list of integers. The loaded value or the value
+returned value is not in the specified range, the behavior is undefined. The
-returned is known to be in the union of the ranges defined by each consecutive
+ranges are represented with a flattened list of integers. The loaded value or
-pair. Each pair has the following properties:
+the value returned is known to be in the union of the ranges defined by each
+consecutive pair. Each pair has the following properties:
 -  The type must match the type loaded by the instruction.
 -  The pair ``a,b`` represents the range ``[a,b)``.
 -  Both ``a`` and ``b`` are constants.
 -  The range is allowed to wrap.
 %result = call i64 %binop(i64 %x, i64 %y), !callees !0
 ...
 !0 = !{i64 (i64, i64)* @add, i64 (i64, i64)* @sub}
+'``callback``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^
+``callback`` metadata may be attached to a function declaration, or definition.
+(Call sites are excluded only due to the lack of a use case.) For ease of
+exposition, we'll refer to the function annotated w/ metadata as a broker
+function. The metadata describes how the arguments of a call to the broker are
+in turn passed to the callback function specified by the metadata. Thus, the
+``callback`` metadata provides a partial description of a call site inside the
+broker function with regards to the arguments of a call to the broker. The only
+semantic restriction on the broker function itself is that it is not allowed to
+inspect or modify arguments referenced in the ``callback`` metadata as
+pass-through to the callback function.
+The broker is not required to actually invoke the callback function at runtime.
+However, the assumptions about not inspecting or modifying arguments that would
+be passed to the specified callback function still hold, even if the callback
+function is not dynamically invoked. The broker is allowed to invoke the
+callback function more than once per invocation of the broker. The broker is
+also allowed to invoke (directly or indirectly) the function passed as a
+callback through another use. Finally, the broker is also allowed to relay the
+callback callee invocation to a different thread.
+The metadata is structured as follows: At the outer level, ``callback``
+metadata is a list of ``callback`` encodings. Each encoding starts with a
+constant ``i64`` which describes the argument position of the callback function
+in the call to the broker. The following elements, except the last, describe
+what arguments are passed to the callback function. Each element is again an
+``i64`` constant identifying the argument of the broker that is passed through,
+or ``i64 -1`` to indicate an unknown or inspected argument. The order in which
+they are listed has to be the same in which they are passed to the callback
+callee. The last element of the encoding is a boolean which specifies how
+variadic arguments of the broker are handled. If it is true, all variadic
+arguments of the broker are passed through to the callback function *after* the
+arguments encoded explicitly before.
+In the code below, the ``pthread_create`` function is marked as a broker
+through the ``!callback !1`` metadata. In the example, there is only one
+callback encoding, namely ``!2``, associated with the broker. This encoding
+identifies the callback function as the second argument of the broker (``i64
+2``) and the sole argument of the callback function as the third one of the
+broker function (``i64 3``).
+.. FIXME why does the llvm-sphinx-docs builder give a highlighting
+error if the below is set to highlight as 'llvm', despite that we
+have misc.highlighting_failure set?
+.. code-block:: text
+declare !callback !1 dso_local i32 @pthread_create(i64*, %union.pthread_attr_t*, i8* (i8*)*, i8*)
+...
+!2 = !{i64 2, i64 3, i1 false}
+!1 = !{!2}
+Another example is shown below. The callback callee is the second argument of
+the ``__kmpc_fork_call`` function (``i64 2``). The callee is given two unknown
+values (each identified by a ``i64 -1``) and afterwards all
+variadic arguments that are passed to the ``__kmpc_fork_call`` call (due to the
+final ``i1 true``).
+.. FIXME why does the llvm-sphinx-docs builder give a highlighting
+error if the below is set to highlight as 'llvm', despite that we
+have misc.highlighting_failure set?
+.. code-block:: text
+declare !callback !0 dso_local void @__kmpc_fork_call(%struct.ident_t*, i32, void (i32*, i32*, ...)*, ...)
+...
+!1 = !{i64 2, i64 -1, i64 -1, i1 true}
+!0 = !{!1}
 '``unpredictable``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 ``unpredictable`` metadata may be attached to any branch or switch
 instruction. It can be used to express the unpredictability of control
 flow. Similar to the llvm.expect intrinsic, it may be used to alter
 optimizations related to compare and branch instructions. The metadata
 is treated as a boolean value; if it exists, it signals that the branch
 or switch that it is attached to is completely unpredictable.
+.. _md_dereferenceable:
+'``dereferenceable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The existence of the ``!dereferenceable`` metadata on the instruction
+tells the optimizer that the value loaded is known to be dereferenceable.
+The number of bytes known to be dereferenceable is specified by the integer
+value in the metadata node. This is analogous to the ''dereferenceable''
+attribute on parameters and return values.
+.. _md_dereferenceable_or_null:
+'``dereferenceable_or_null``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The existence of the ``!dereferenceable_or_null`` metadata on the
+instruction tells the optimizer that the value loaded is known to be either
+dereferenceable or null.
+The number of bytes known to be dereferenceable is specified by the integer
+value in the metadata node. This is analogous to the ''dereferenceable_or_null''
+attribute on parameters and return values.
+.. _llvm.loop:
 '``llvm.loop``'
 ^^^^^^^^^^^^^^^
 It is sometimes useful to attach information to loop constructs. Currently,
 loop metadata is implemented as metadata attached to the branch instruction
 br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
 ...
 !0 = !{!0, !1}
 !1 = !{!"llvm.loop.unroll.count", i32 4}
+'``llvm.loop.disable_nonforced``'
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata disables all optional loop transformations unless
+explicitly instructed using other transformation metadata such as
+``llvm.loop.unroll.enable``. That is, no heuristic will try to determine
+whether a transformation is profitable. The purpose is to avoid that the
+loop is transformed to a different loop before an explicitly requested
+(forced) transformation is applied. For instance, loop fusion can make
+other transformations impossible. Mandatory loop canonicalizations such
+as loop rotation are still applied.
+It is recommended to use this metadata in addition to any llvm.loop.*
+transformation directive. Also, any loop should have at most one
+directive applied to it (and a sequence of transformations built using
+followup-attributes). Otherwise, which transformation will be applied
+depends on implementation details such as the pass pipeline order.
+See :ref:`transformation-metadata` for details.
 '``llvm.loop.vectorize``' and '``llvm.loop.interleave``'
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Metadata prefixed with ``llvm.loop.vectorize`` or ``llvm.loop.interleave`` are
 used to control per-loop vectorization and interleaving parameters such as
 vectorization width and interleave count. These metadata should be used in
 conjunction with ``llvm.loop`` loop identification metadata. The
 ``llvm.loop.vectorize`` and ``llvm.loop.interleave`` metadata are only
 optimization hints and the optimizer will only interleave and vectorize loops if
-it believes it is safe to do so. The ``llvm.mem.parallel_loop_access`` metadata
+it believes it is safe to do so. The ``llvm.loop.parallel_accesses`` metadata
 which contains information about loop-carried memory dependencies can be helpful
 in determining the safety of these transformations.
 '``llvm.loop.interleave.count``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. code-block:: llvm
 !0 = !{!"llvm.loop.vectorize.enable", i1 0}
 !1 = !{!"llvm.loop.vectorize.enable", i1 1}
+'``llvm.loop.vectorize.predicate.enable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata selectively enables or disables creating predicated instructions
+for the loop, which can enable folding of the scalar epilogue loop into the
+main loop. The first operand is the string
+``llvm.loop.vectorize.predicate.enable`` and the second operand is a bit. If
+the bit operand value is 1 vectorization is enabled. A value of 0 disables
+vectorization:
+.. code-block:: llvm
+!0 = !{!"llvm.loop.vectorize.predicate.enable", i1 0}
+!1 = !{!"llvm.loop.vectorize.predicate.enable", i1 1}
 '``llvm.loop.vectorize.width``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This metadata sets the target width of the vectorizer. The first
 operand is the string ``llvm.loop.vectorize.width`` and the second
 Note that setting ``llvm.loop.vectorize.width`` to 1 disables
 vectorization of the loop. If ``llvm.loop.vectorize.width`` is set to
 0 or if the loop does not have this metadata the width will be
 determined automatically.
+'``llvm.loop.vectorize.followup_vectorized``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata defines which loop attributes the vectorized loop will
+have. See :ref:`transformation-metadata` for details.
+'``llvm.loop.vectorize.followup_epilogue``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata defines which loop attributes the epilogue will have. The
+epilogue is not vectorized and is executed when either the vectorized
+loop is not known to preserve semantics (because e.g., it processes two
+arrays that are found to alias by a runtime check) or for the last
+iterations that do not fill a complete set of vector lanes. See
+:ref:`Transformation Metadata <transformation-metadata>` for details.
+'``llvm.loop.vectorize.followup_all``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Attributes in the metadata will be added to both the vectorized and
+epilogue loop.
+See :ref:`Transformation Metadata <transformation-metadata>` for details.
 '``llvm.loop.unroll``'
 ^^^^^^^^^^^^^^^^^^^^^^
 Metadata prefixed with ``llvm.loop.unroll`` are loop unrolling
 .. code-block:: llvm
 !0 = !{!"llvm.loop.unroll.full"}
+'``llvm.loop.unroll.followup``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata defines which loop attributes the unrolled loop will have.
+See :ref:`Transformation Metadata <transformation-metadata>` for details.
+'``llvm.loop.unroll.followup_remainder``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata defines which loop attributes the remainder loop after
+partial/runtime unrolling will have. See
+:ref:`Transformation Metadata <transformation-metadata>` for details.
+'``llvm.loop.unroll_and_jam``'
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata is treated very similarly to the ``llvm.loop.unroll`` metadata
+above, but affect the unroll and jam pass. In addition any loop with
+``llvm.loop.unroll`` metadata but no ``llvm.loop.unroll_and_jam`` metadata will
+disable unroll and jam (so ``llvm.loop.unroll`` metadata will be left to the
+unroller, plus ``llvm.loop.unroll.disable`` metadata will disable unroll and jam
+too.)
+The metadata for unroll and jam otherwise is the same as for ``unroll``.
+``llvm.loop.unroll_and_jam.enable``, ``llvm.loop.unroll_and_jam.disable`` and
+``llvm.loop.unroll_and_jam.count`` do the same as for unroll.
+``llvm.loop.unroll_and_jam.full`` is not supported. Again these are only hints
+and the normal safety checks will still be performed.
+'``llvm.loop.unroll_and_jam.count``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata suggests an unroll and jam factor to use, similarly to
+``llvm.loop.unroll.count``. The first operand is the string
+``llvm.loop.unroll_and_jam.count`` and the second operand is a positive integer
+specifying the unroll factor. For example:
+.. code-block:: llvm
+!0 = !{!"llvm.loop.unroll_and_jam.count", i32 4}
+If the trip count of the loop is less than the unroll count the loop
+will be partially unroll and jammed.
+'``llvm.loop.unroll_and_jam.disable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata disables loop unroll and jamming. The metadata has a single
+operand which is the string ``llvm.loop.unroll_and_jam.disable``. For example:
+.. code-block:: llvm
+!0 = !{!"llvm.loop.unroll_and_jam.disable"}
+'``llvm.loop.unroll_and_jam.enable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata suggests that the loop should be fully unroll and jammed if the
+trip count is known at compile time and partially unrolled if the trip count is
+not known at compile time. The metadata has a single operand which is the
+string ``llvm.loop.unroll_and_jam.enable``.  For example:
+.. code-block:: llvm
+!0 = !{!"llvm.loop.unroll_and_jam.enable"}
+'``llvm.loop.unroll_and_jam.followup_outer``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata defines which loop attributes the outer unrolled loop will
+have. See :ref:`Transformation Metadata <transformation-metadata>` for
+details.
+'``llvm.loop.unroll_and_jam.followup_inner``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata defines which loop attributes the inner jammed loop will
+have. See :ref:`Transformation Metadata <transformation-metadata>` for
+details.
+'``llvm.loop.unroll_and_jam.followup_remainder_outer``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata defines which attributes the epilogue of the outer loop
+will have. This loop is usually unrolled, meaning there is no such
+loop. This attribute will be ignored in this case. See
+:ref:`Transformation Metadata <transformation-metadata>` for details.
+'``llvm.loop.unroll_and_jam.followup_remainder_inner``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata defines which attributes the inner loop of the epilogue
+will have. The outer epilogue will usually be unrolled, meaning there
+can be multiple inner remainder loops. See
+:ref:`Transformation Metadata <transformation-metadata>` for details.
+'``llvm.loop.unroll_and_jam.followup_all``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Attributes specified in the metadata is added to all
+``llvm.loop.unroll_and_jam.*`` loops. See
+:ref:`Transformation Metadata <transformation-metadata>` for details.
 '``llvm.loop.licm_versioning.disable``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This metadata indicates that the loop should not be versioned for the purpose
 of enabling loop-invariant code motion (LICM). The metadata has a single operand
 !1 = !{!"llvm.loop.distribute.enable", i1 1}
 This metadata should be used in conjunction with ``llvm.loop`` loop
 identification metadata.
-'``llvm.mem``'
+'``llvm.loop.distribute.followup_coincident``' Metadata
-^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Metadata types used to annotate memory accesses with information helpful
+This metadata defines which attributes extracted loops with no cyclic
-for optimizations are prefixed with ``llvm.mem``.
+dependencies will have (i.e. can be vectorized). See
+:ref:`Transformation Metadata <transformation-metadata>` for details.
-'``llvm.mem.parallel_loop_access``' Metadata
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+'``llvm.loop.distribute.followup_sequential``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ``llvm.mem.parallel_loop_access`` metadata refers to a loop identifier,
-or metadata containing a list of loop identifiers for nested loops.
+This metadata defines which attributes the isolated loops with unsafe
-The metadata is attached to memory accessing instructions and denotes that
+memory dependencies will have. See
-no loop carried memory dependence exist between it and other instructions denoted
+:ref:`Transformation Metadata <transformation-metadata>` for details.
-with the same loop identifier. The metadata on memory reads also implies that
-if conversion (i.e. speculative execution within a loop iteration) is safe.
+'``llvm.loop.distribute.followup_fallback``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Precisely, given two instructions ``m1`` and ``m2`` that both have the
-``llvm.mem.parallel_loop_access`` metadata, with ``L1`` and ``L2`` being the
+If loop versioning is necessary, this metadata defined the attributes
-set of loops associated with that metadata, respectively, then there is no loop
+the non-distributed fallback version will have. See
-carried dependence between ``m1`` and ``m2`` for loops in both ``L1`` and
+:ref:`Transformation Metadata <transformation-metadata>` for details.
-``L2``.
+'``llvm.loop.distribute.followup_all``' Metadata
-As a special case, if all memory accessing instructions in a loop have
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-``llvm.mem.parallel_loop_access`` metadata that refers to that loop, then the
-loop has no loop carried memory dependences and is considered to be a parallel
+The attributes in this metadata is added to all followup loops of the
-loop.
+loop distribution pass. See
+:ref:`Transformation Metadata <transformation-metadata>` for details.
-Note that if not all memory access instructions have such metadata referring to
-the loop, then the loop is considered not being trivially parallel. Additional
+'``llvm.licm.disable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This metadata indicates that loop-invariant code motion (LICM) should not be
+performed on this loop. The metadata has a single operand which is the string
+``llvm.licm.disable``. For example:
+.. code-block:: llvm
+!0 = !{!"llvm.licm.disable"}
+Note that although it operates per loop it isn't given the llvm.loop prefix
+as it is not affected by the ``llvm.loop.disable_nonforced`` metadata.
+'``llvm.access.group``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``llvm.access.group`` metadata can be attached to any instruction that
+potentially accesses memory. It can point to a single distinct metadata
+node, which we call access group. This node represents all memory access
+instructions referring to it via ``llvm.access.group``. When an
+instruction belongs to multiple access groups, it can also point to a
+list of accesses groups, illustrated by the following example.
+.. code-block:: llvm
+%val = load i32, i32* %arrayidx, !llvm.access.group !0
+...
+!0 = !{!1, !2}
+!1 = distinct !{}
+!2 = distinct !{}
+It is illegal for the list node to be empty since it might be confused
+with an access group.
+The access group metadata node must be 'distinct' to avoid collapsing
+multiple access groups by content. A access group metadata node must
+always be empty which can be used to distinguish an access group
+metadata node from a list of access groups. Being empty avoids the
+situation that the content must be updated which, because metadata is
+immutable by design, would required finding and updating all references
+to the access group node.
+The access group can be used to refer to a memory access instruction
+without pointing to it directly (which is not possible in global
+metadata). Currently, the only metadata making use of it is
+``llvm.loop.parallel_accesses``.
+'``llvm.loop.parallel_accesses``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The ``llvm.loop.parallel_accesses`` metadata refers to one or more
+access group metadata nodes (see ``llvm.access.group``). It denotes that
+no loop-carried memory dependence exist between it and other instructions
+in the loop with this metadata.
+Let ``m1`` and ``m2`` be two instructions that both have the
+``llvm.access.group`` metadata to the access group ``g1``, respectively
+``g2`` (which might be identical). If a loop contains both access groups
+in its ``llvm.loop.parallel_accesses`` metadata, then the compiler can
+assume that there is no dependency between ``m1`` and ``m2`` carried by
+this loop. Instructions that belong to multiple access groups are
+considered having this property if at least one of the access groups
+matches the ``llvm.loop.parallel_accesses`` list.
+If all memory-accessing instructions in a loop have
+``llvm.loop.parallel_accesses`` metadata that refers to that loop, then the
+loop has no loop carried memory dependences and is considered to be a
+parallel loop.
+Note that if not all memory access instructions belong to an access
+group referred to by ``llvm.loop.parallel_accesses``, then the loop must
+not be considered trivially parallel. Additional
 memory dependence analysis is required to make that determination. As a fail
 safe mechanism, this causes loops that were originally parallel to be considered
 sequential (if optimization passes that are unaware of the parallel semantics
 insert new memory instructions into the loop body).
 Example of a loop that is considered parallel due to its correct use of
-both ``llvm.loop`` and ``llvm.mem.parallel_loop_access``
+both ``llvm.access.group`` and ``llvm.loop.parallel_accesses``
-metadata types that refer to the same loop identifier metadata.
+metadata types.
 .. code-block:: llvm
 for.body:
 ...
-%val0 = load i32, i32* %arrayidx, !llvm.mem.parallel_loop_access !0
+%val0 = load i32, i32* %arrayidx, !llvm.access.group !1
 ...
-store i32 %val0, i32* %arrayidx1, !llvm.mem.parallel_loop_access !0
+store i32 %val0, i32* %arrayidx1, !llvm.access.group !1
 ...
 br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0
 for.end:
 ...
-!0 = !{!0}
+!0 = distinct !{!0, !{!"llvm.loop.parallel_accesses", !1}}
+!1 = distinct !{}
-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
+It is also possible to have nested parallel loops:
-the loop identifier metadata node directly:
 .. code-block:: llvm
 outer.for.body:
 ...
-%val1 = load i32, i32* %arrayidx3, !llvm.mem.parallel_loop_access !2
+%val1 = load i32, i32* %arrayidx3, !llvm.access.group !4
 ...
 br label %inner.for.body
 inner.for.body:
 ...
-%val0 = load i32, i32* %arrayidx1, !llvm.mem.parallel_loop_access !0
+%val0 = load i32, i32* %arrayidx1, !llvm.access.group !3
 ...
-store i32 %val0, i32* %arrayidx2, !llvm.mem.parallel_loop_access !0
+store i32 %val0, i32* %arrayidx2, !llvm.access.group !3
 ...
 br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1
 inner.for.end:
 ...
-store i32 %val1, i32* %arrayidx4, !llvm.mem.parallel_loop_access !2
+store i32 %val1, i32* %arrayidx4, !llvm.access.group !4
 ...
 br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2
 outer.for.end:                                          ; preds = %for.body
 ...
-!0 = !{!1, !2} ; a list of loop identifiers
+!1 = distinct !{!1, !{!"llvm.loop.parallel_accesses", !3}}     ; metadata for the inner loop
-!1 = !{!1} ; an identifier for the inner loop
+!2 = distinct !{!2, !{!"llvm.loop.parallel_accesses", !3, !4}} ; metadata for the outer loop
-!2 = !{!2} ; an identifier for the outer loop
+!3 = distinct !{} ; access group for instructions in the inner loop (which are implicitly contained in outer loop as well)
+!4 = distinct !{} ; access group for instructions in the outer, but not the inner loop
 '``irr_loop``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^
 ``irr_loop`` metadata may be attached to the terminator instruction of a basic
 ...
 !0 = !{"loop_header_weight", i64 100}
 Irreducible loop header weights are typically based on profile data.
+.. _md_invariant.group:
 '``invariant.group``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ``invariant.group`` metadata may be attached to ``load``/``store`` instructions.
+The experimental ``invariant.group`` metadata may be attached to
+``load``/``store`` instructions referencing a single metadata with no entries.
 The existence of the ``invariant.group`` metadata on the instruction tells
 the optimizer that every ``load`` and ``store`` to the same pointer operand
-within the same invariant group can be assumed to load or store the same
+can be assumed to load or store the same
-value (but see the ``llvm.invariant.group.barrier`` intrinsic which affects
+value (but see the ``llvm.launder.invariant.group`` intrinsic which affects
 when two pointers are considered the same). Pointers returned by bitcast or
 getelementptr with only zero indices are considered the same.
 Examples:
 store i8 42, i8* %ptr, !invariant.group !0
 call void @foo(i8* %ptr)
 %a = load i8, i8* %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change
 call void @foo(i8* %ptr)
-%b = load i8, i8* %ptr, !invariant.group !1 ; Can't assume anything, because group changed
 %newPtr = call i8* @getPointer(i8* %ptr)
 %c = load i8, i8* %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr
 %unknownValue = load i8, i8* @unknownPtr
 store i8 %unknownValue, i8* %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42
 call void @foo(i8* %ptr)
-%newPtr2 = call i8* @llvm.invariant.group.barrier(i8* %ptr)
+%newPtr2 = call i8* @llvm.launder.invariant.group(i8* %ptr)
-%d = load i8, i8* %newPtr2, !invariant.group !0  ; Can't step through invariant.group.barrier to get value of %ptr
+%d = load i8, i8* %newPtr2, !invariant.group !0  ; Can't step through launder.invariant.group to get value of %ptr
 ...
 declare void @foo(i8*)
 declare i8* @getPointer(i8*)
-declare i8* @llvm.invariant.group.barrier(i8*)
+declare i8* @llvm.launder.invariant.group(i8*)
-!0 = !{!"magic ptr"}
+!0 = !{}
-!1 = !{!"other ptr"}
 The invariant.group metadata must be dropped when replacing one pointer by
 another based on aliasing information. This is because invariant.group is tied
 to the SSA value of the pointer operand.
 %v = load i8, i8* %x, !invariant.group !0
 ; if %x mustalias %y then we can replace the above instruction with
 %v = load i8, i8* %y
+Note that this is an experimental feature, which means that its semantics might
+change in the future.
 '``type``' Metadata
 ^^^^^^^^^^^^^^^^^^^
 See :doc:`TypeMetadata`.
 !1 = !{i32 1, !"short_enum", i32 0}
 Automatic Linker Flags Named Metadata
 =====================================
-Some targets support embedding flags to the linker inside individual object
+Some targets support embedding of 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
+allow source files to contain linker command line options, and have these
-these automatically be transmitted to the linker via object files.
+automatically be transmitted to the linker via object files.
 These flags are encoded in the IR using named metadata with the name
 ``!llvm.linker.options``. Each operand 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 = !{ !"-lz" },
+!0 = !{ !"-lz" }
-!1 = !{ !"-framework", !"Cocoa" } } }
+!1 = !{ !"-framework", !"Cocoa" }
 !llvm.linker.options = !{ !0, !1 }
 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
 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.
+Dependent Libs Named Metadata
+=============================
+Some targets support embedding of strings into object files to indicate
+a set of libraries to add to the link. 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.
+The list is encoded in the IR using named metadata with the name
+``!llvm.dependent-libraries``. Each operand is expected to be a metadata node
+which should contain a single string operand.
+For example, the following metadata section contains two library specfiers::
+!0 = !{!"a library specifier"}
+!1 = !{!"another library specifier"}
+!llvm.dependent-libraries = !{ !0, !1 }
+Each library specifier will be handled independently by the consuming linker.
+The effect of the library specifiers are defined by the consuming linker.
+.. _summary:
+ThinLTO Summary
+===============
+Compiling with `ThinLTO <https://clang.llvm.org/docs/ThinLTO.html>`_
+causes the building of a compact summary of the module that is emitted into
+the bitcode. The summary is emitted into the LLVM assembly and identified
+in syntax by a caret ('``^``').
+The summary is parsed into a bitcode output, along with the Module
+IR, via the "``llvm-as``" tool. Tools that parse the Module IR for the purposes
+of optimization (e.g. "``clang -x ir``" and "``opt``"), will ignore the
+summary entries (just as they currently ignore summary entries in a bitcode
+input file).
+Eventually, the summary will be parsed into a ModuleSummaryIndex object under
+the same conditions where summary index is currently built from bitcode.
+Specifically, tools that test the Thin Link portion of a ThinLTO compile
+(i.e. llvm-lto and llvm-lto2), or when parsing a combined index
+for a distributed ThinLTO backend via clang's "``-fthinlto-index=<>``" flag
+(this part is not yet implemented, use llvm-as to create a bitcode object
+before feeding into thin link tools for now).
+There are currently 3 types of summary entries in the LLVM assembly:
+:ref:`module paths<module_path_summary>`,
+:ref:`global values<gv_summary>`, and
+:ref:`type identifiers<typeid_summary>`.
+.. _module_path_summary:
+Module Path Summary Entry
+-------------------------
+Each module path summary entry lists a module containing global values included
+in the summary. For a single IR module there will be one such entry, but
+in a combined summary index produced during the thin link, there will be
+one module path entry per linked module with summary.
+Example:
+.. code-block:: text
+^0 = module: (path: "/path/to/file.o", hash: (2468601609, 1329373163, 1565878005, 638838075, 3148790418))
+The ``path`` field is a string path to the bitcode file, and the ``hash``
+field is the 160-bit SHA-1 hash of the IR bitcode contents, used for
+incremental builds and caching.
+.. _gv_summary:
+Global Value Summary Entry
+--------------------------
+Each global value summary entry corresponds to a global value defined or
+referenced by a summarized module.
+Example:
+.. code-block:: text
+^4 = gv: (name: "f"[, summaries: (Summary)[, (Summary)]*]?) ; guid = 14740650423002898831
+For declarations, there will not be a summary list. For definitions, a
+global value will contain a list of summaries, one per module containing
+a definition. There can be multiple entries in a combined summary index
+for symbols with weak linkage.
+Each ``Summary`` format will depend on whether the global value is a
+:ref:`function<function_summary>`, :ref:`variable<variable_summary>`, or
+:ref:`alias<alias_summary>`.
+.. _function_summary:
+Function Summary
+^^^^^^^^^^^^^^^^
+If the global value is a function, the ``Summary`` entry will look like:
+.. code-block:: text
+function: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), insts: 2[, FuncFlags]?[, Calls]?[, TypeIdInfo]?[, Refs]?
+The ``module`` field includes the summary entry id for the module containing
+this definition, and the ``flags`` field contains information such as
+the linkage type, a flag indicating whether it is legal to import the
+definition, whether it is globally live and whether the linker resolved it
+to a local definition (the latter two are populated during the thin link).
+The ``insts`` field contains the number of IR instructions in the function.
+Finally, there are several optional fields: :ref:`FuncFlags<funcflags_summary>`,
+:ref:`Calls<calls_summary>`, :ref:`TypeIdInfo<typeidinfo_summary>`,
+:ref:`Refs<refs_summary>`.
+.. _variable_summary:
+Global Variable Summary
+^^^^^^^^^^^^^^^^^^^^^^^
+If the global value is a variable, the ``Summary`` entry will look like:
+.. code-block:: text
+variable: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0)[, Refs]?
+The variable entry contains a subset of the fields in a
+:ref:`function summary <function_summary>`, see the descriptions there.
+.. _alias_summary:
+Alias Summary
+^^^^^^^^^^^^^
+If the global value is an alias, the ``Summary`` entry will look like:
+.. code-block:: text
+alias: (module: ^0, flags: (linkage: external, notEligibleToImport: 0, live: 0, dsoLocal: 0), aliasee: ^2)
+The ``module`` and ``flags`` fields are as described for a
+:ref:`function summary <function_summary>`. The ``aliasee`` field
+contains a reference to the global value summary entry of the aliasee.
+.. _funcflags_summary:
+Function Flags
+^^^^^^^^^^^^^^
+The optional ``FuncFlags`` field looks like:
+.. code-block:: text
+funcFlags: (readNone: 0, readOnly: 0, noRecurse: 0, returnDoesNotAlias: 0)
+If unspecified, flags are assumed to hold the conservative ``false`` value of
+``0``.
+.. _calls_summary:
+Calls
+^^^^^
+The optional ``Calls`` field looks like:
+.. code-block:: text
+calls: ((Callee)[, (Callee)]*)
+where each ``Callee`` looks like:
+.. code-block:: text
+callee: ^1[, hotness: None]?[, relbf: 0]?
+The ``callee`` refers to the summary entry id of the callee. At most one
+of ``hotness`` (which can take the values ``Unknown``, ``Cold``, ``None``,
+``Hot``, and ``Critical``), and ``relbf`` (which holds the integer
+branch frequency relative to the entry frequency, scaled down by 2^8)
+may be specified. The defaults are ``Unknown`` and ``0``, respectively.
+.. _refs_summary:
+Refs
+^^^^
+The optional ``Refs`` field looks like:
+.. code-block:: text
+refs: ((Ref)[, (Ref)]*)
+where each ``Ref`` contains a reference to the summary id of the referenced
+value (e.g. ``^1``).
+.. _typeidinfo_summary:
+TypeIdInfo
+^^^^^^^^^^
+The optional ``TypeIdInfo`` field, used for
+`Control Flow Integrity <http://clang.llvm.org/docs/ControlFlowIntegrity.html>`_,
+looks like:
+.. code-block:: text
+typeIdInfo: [(TypeTests)]?[, (TypeTestAssumeVCalls)]?[, (TypeCheckedLoadVCalls)]?[, (TypeTestAssumeConstVCalls)]?[, (TypeCheckedLoadConstVCalls)]?
+These optional fields have the following forms:
+TypeTests
+"""""""""
+.. code-block:: text
+typeTests: (TypeIdRef[, TypeIdRef]*)
+Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>`
+by summary id or ``GUID``.
+TypeTestAssumeVCalls
+""""""""""""""""""""
+.. code-block:: text
+typeTestAssumeVCalls: (VFuncId[, VFuncId]*)
+Where each VFuncId has the format:
+.. code-block:: text
+vFuncId: (TypeIdRef, offset: 16)
+Where each ``TypeIdRef`` refers to a :ref:`type id<typeid_summary>`
+by summary id or ``GUID`` preceeded by a ``guid:`` tag.
+TypeCheckedLoadVCalls
+"""""""""""""""""""""
+.. code-block:: text
+typeCheckedLoadVCalls: (VFuncId[, VFuncId]*)
+Where each VFuncId has the format described for ``TypeTestAssumeVCalls``.
+TypeTestAssumeConstVCalls
+"""""""""""""""""""""""""
+.. code-block:: text
+typeTestAssumeConstVCalls: (ConstVCall[, ConstVCall]*)
+Where each ConstVCall has the format:
+.. code-block:: text
+(VFuncId, args: (Arg[, Arg]*))
+and where each VFuncId has the format described for ``TypeTestAssumeVCalls``,
+and each Arg is an integer argument number.
+TypeCheckedLoadConstVCalls
+""""""""""""""""""""""""""
+.. code-block:: text
+typeCheckedLoadConstVCalls: (ConstVCall[, ConstVCall]*)
+Where each ConstVCall has the format described for
+``TypeTestAssumeConstVCalls``.
+.. _typeid_summary:
+Type ID Summary Entry
+---------------------
+Each type id summary entry corresponds to a type identifier resolution
+which is generated during the LTO link portion of the compile when building
+with `Control Flow Integrity <http://clang.llvm.org/docs/ControlFlowIntegrity.html>`_,
+so these are only present in a combined summary index.
+Example:
+.. code-block:: text
+^4 = typeid: (name: "_ZTS1A", summary: (typeTestRes: (kind: allOnes, sizeM1BitWidth: 7[, alignLog2: 0]?[, sizeM1: 0]?[, bitMask: 0]?[, inlineBits: 0]?)[, WpdResolutions]?)) ; guid = 7004155349499253778
+The ``typeTestRes`` gives the type test resolution ``kind`` (which may
+be ``unsat``, ``byteArray``, ``inline``, ``single``, or ``allOnes``), and
+the ``size-1`` bit width. It is followed by optional flags, which default to 0,
+and an optional WpdResolutions (whole program devirtualization resolution)
+field that looks like:
+.. code-block:: text
+wpdResolutions: ((offset: 0, WpdRes)[, (offset: 1, WpdRes)]*
+where each entry is a mapping from the given byte offset to the whole-program
+devirtualization resolution WpdRes, that has one of the following formats:
+.. code-block:: text
+wpdRes: (kind: branchFunnel)
+wpdRes: (kind: singleImpl, singleImplName: "_ZN1A1nEi")
+wpdRes: (kind: indir)
+Additionally, each wpdRes has an optional ``resByArg`` field, which
+describes the resolutions for calls with all constant integer arguments:
+.. code-block:: text
+resByArg: (ResByArg[, ResByArg]*)
+where ResByArg is:
+.. code-block:: text
+args: (Arg[, Arg]*), byArg: (kind: UniformRetVal[, info: 0][, byte: 0][, bit: 0])
+Where the ``kind`` can be ``Indir``, ``UniformRetVal``, ``UniqueRetVal``
+or ``VirtualConstProp``. The ``info`` field is only used if the kind
+is ``UniformRetVal`` (indicates the uniform return value), or
+``UniqueRetVal`` (holds the return value associated with the unique vtable
+(0 or 1)). The ``byte`` and ``bit`` fields are only used if the target does
+not support the use of absolute symbols to store constants.
 .. _intrinsicglobalvariables:
 Intrinsic Global Variables
 ==========================
 %0 = type { i32, void ()*, i8* }
 @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor, i8* @data }]
 The ``@llvm.global_ctors`` array contains a list of constructor
-functions, priorities, and an optional associated global or function.
+functions, priorities, and an associated global or function.
 The functions referenced by this array will be called in ascending order
 of priority (i.e. lowest first) when the module is loaded. The order of
 functions with the same priority is not defined.
-If the third field is present, non-null, and points to a global variable
+If the third field is non-null, and points to a global variable
 or function, the initializer function will only run if the associated
 data from the current module is not discarded.
 .. _llvmglobaldtors:
 %0 = type { i32, void ()*, i8* }
 @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor, i8* @data }]
 The ``@llvm.global_dtors`` array contains a list of destructor
-functions, priorities, and an optional associated global or function.
+functions, priorities, and an associated global or function.
 The functions referenced by this array will be called in descending
 order of priority (i.e. highest first) when the module is unloaded. The
 order of functions with the same priority is not defined.
-If the third field is present, non-null, and points to a global variable
+If the third field is non-null, and points to a global variable
 or function, the destructor function will only run if the associated
 data from the current module is not discarded.
 Instruction Reference
 =====================
 ':ref:`invoke <i_invoke>`' instruction).
 The terminator instructions are: ':ref:`ret <i_ret>`',
 ':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
 ':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
+':ref:`callbr <i_callbr>`'
 ':ref:`resume <i_resume>`', ':ref:`catchswitch <i_catchswitch>`',
 ':ref:`catchret <i_catchret>`',
 ':ref:`cleanupret <i_cleanupret>`',
 and ':ref:`unreachable <i_unreachable>`'.
 The '``ret``' instruction optionally accepts a single argument, the
 return value. The type of the return value must be a ':ref:`first
 class <t_firstclass>`' type.
-A function is not :ref:`well formed <wellformed>` if it it has a non-void
+A function is not :ref:`well formed <wellformed>` if it has a non-void
 return type and contains a '``ret``' instruction with no return value or
 a return value with a type that does not match its type, or if it has a
 void return type and contains a '``ret``' instruction with a return
 value.
 Syntax:
 """""""
 ::
-<result> = invoke [cconv] [ret attrs] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
+<result> = invoke [cconv] [ret attrs] [addrspace(<num>)] [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
 [operand bundles] to label <normal label> unwind label <exception label>
 Overview:
 """""""""
 convention <callingconv>` the call should use. If none is
 specified, the call defaults to using C calling conventions.
 #. The optional :ref:`Parameter Attributes <paramattrs>` list for return
 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
 are valid here.
+#. The optional addrspace attribute can be used to indicate the address space
+of the called function. If it is not specified, the program address space
+from the :ref:`datalayout string<langref_datalayout>` will be used.
 #. '``ty``': the type of the call instruction itself which is also the
 type of the return value. Functions that return no value are marked
 ``void``.
 #. '``fnty``': shall be the signature of the function being invoked. The
 argument types must match the types implied by this signature. This
 %retval = invoke i32 @Test(i32 15) to label %Continue
 unwind label %TestCleanup              ; i32:retval set
 %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
 unwind label %TestCleanup              ; i32:retval set
+.. _i_callbr:
+'``callbr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+<result> = callbr [cconv] [ret attrs] [addrspace(<num>)] [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
+[operand bundles] to label <normal label> or jump [other labels]
+Overview:
+"""""""""
+The '``callbr``' instruction causes control to transfer to a specified
+function, with the possibility of control flow transfer to either the
+'``normal``' label or one of the '``other``' labels.
+This instruction should only be used to implement the "goto" feature of gcc
+style inline assembly. Any other usage is an error in the IR verifier.
+Arguments:
+""""""""""
+This instruction requires several arguments:
+#. The optional "cconv" marker indicates which :ref:`calling
+convention <callingconv>` the call should use. If none is
+specified, the call defaults to using C calling conventions.
+#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
+values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
+are valid here.
+#. The optional addrspace attribute can be used to indicate the address space
+of the called function. If it is not specified, the program address space
+from the :ref:`datalayout string<langref_datalayout>` will be used.
+#. '``ty``': the type of the call instruction itself which is also the
+type of the return value. Functions that return no value are marked
+``void``.
+#. '``fnty``': shall be the signature of the function being called. The
+argument types must match the types implied by this signature. This
+type can be omitted if the function is not varargs.
+#. '``fnptrval``': An LLVM value containing a pointer to a function to
+be called. In most cases, this is a direct function call, but
+indirect ``callbr``'s are just as possible, calling an arbitrary pointer
+to function value.
+#. '``function args``': argument list whose types match the function
+signature argument types and parameter attributes. All arguments must
+be of :ref:`first class <t_firstclass>` type. If the function signature
+indicates the function accepts a variable number of arguments, the
+extra arguments can be specified.
+#. '``normal label``': the label reached when the called function
+executes a '``ret``' instruction.
+#. '``other labels``': the labels reached when a callee transfers control
+to a location other than the normal '``normal label``'
+#. The optional :ref:`function attributes <fnattrs>` list.
+#. The optional :ref:`operand bundles <opbundles>` list.
+Semantics:
+""""""""""
+This instruction is designed to operate as a standard '``call``'
+instruction in most regards. The primary difference is that it
+establishes an association with additional labels to define where control
+flow goes after the call.
+The only use of this today is to implement the "goto" feature of gcc inline
+assembly where additional labels can be provided as locations for the inline
+assembly to jump to.
+Example:
+""""""""
+.. code-block:: text
+callbr void asm "", "r,x"(i32 %x, i8 *blockaddress(@foo, %fail))
+to label %normal or jump [label %fail]
 .. _i_resume:
 '``resume``' Instruction
 ^^^^^^^^^^^^^^^^^^^^^^^^
 Semantics:
 """"""""""
 The '``unreachable``' instruction has no defined semantics.
+.. _unaryops:
+Unary Operations
+-----------------
+Unary operators require a single operand, execute an operation on
+it, and produce a single value. The operand might represent multiple
+data, as is the case with the :ref:`vector <t_vector>` data type. The
+result value has the same type as its operand.
+.. _i_fneg:
+'``fneg``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+<result> = fneg [fast-math flags]* <ty> <op1>   ; yields ty:result
+Overview:
+"""""""""
+The '``fneg``' instruction returns the negation of its operand.
+Arguments:
+""""""""""
+The argument to the '``fneg``' instruction must be a
+:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
+floating-point values.
+Semantics:
+""""""""""
+The value produced is a copy of the operand with its sign bit flipped.
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating-point optimizations:
+Example:
+""""""""
+.. code-block:: text
+<result> = fneg float %val          ; yields float:result = -%var
 .. _binaryops:
 Binary Operations
 -----------------
 The '``fadd``' instruction returns the sum of its two operands.
 Arguments:
 """"""""""
-The two arguments to the '``fadd``' instruction must be :ref:`floating
+The two arguments to the '``fadd``' instruction must be
-point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
-Both arguments must have identical types.
+floating-point values. Both arguments must have identical types.
 Semantics:
 """"""""""
-The value produced is the floating point sum of the two operands. This
+The value produced is the floating-point sum of the two operands.
-instruction can also take any number of :ref:`fast-math flags <fastmath>`,
+This instruction is assumed to execute in the default :ref:`floating-point
-which are optimization hints to enable otherwise unsafe floating point
+environment <floatenv>`.
-optimizations:
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating-point optimizations:
 Example:
 """"""""
 .. code-block:: text
 Overview:
 """""""""
 The '``fsub``' instruction returns the difference of its two operands.
-Note that the '``fsub``' instruction is used to represent the '``fneg``'
+Arguments:
-instruction present in most other intermediate representations.
+""""""""""
-Arguments:
+The two arguments to the '``fsub``' instruction must be
-""""""""""
+:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
+floating-point values. Both arguments must have identical types.
-The two arguments to the '``fsub``' instruction must be :ref:`floating
-point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Semantics:
-Both arguments must have identical types.
+""""""""""
-Semantics:
+The value produced is the floating-point difference of the two operands.
-""""""""""
+This instruction is assumed to execute in the default :ref:`floating-point
+environment <floatenv>`.
-The value produced is the floating point difference of the two operands.
 This instruction can also take any number of :ref:`fast-math
 flags <fastmath>`, which are optimization hints to enable otherwise
-unsafe floating point optimizations:
+unsafe floating-point optimizations:
 Example:
 """"""""
 .. code-block:: text
 The '``fmul``' instruction returns the product of its two operands.
 Arguments:
 """"""""""
-The two arguments to the '``fmul``' instruction must be :ref:`floating
+The two arguments to the '``fmul``' instruction must be
-point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
-Both arguments must have identical types.
+floating-point values. Both arguments must have identical types.
 Semantics:
 """"""""""
-The value produced is the floating point product of the two operands.
+The value produced is the floating-point product of the two operands.
+This instruction is assumed to execute in the default :ref:`floating-point
+environment <floatenv>`.
 This instruction can also take any number of :ref:`fast-math
 flags <fastmath>`, which are optimization hints to enable otherwise
-unsafe floating point optimizations:
+unsafe floating-point optimizations:
 Example:
 """"""""
 .. code-block:: text
 The '``fdiv``' instruction returns the quotient of its two operands.
 Arguments:
 """"""""""
-The two arguments to the '``fdiv``' instruction must be :ref:`floating
+The two arguments to the '``fdiv``' instruction must be
-point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
-Both arguments must have identical types.
+floating-point values. Both arguments must have identical types.
 Semantics:
 """"""""""
-The value produced is the floating point quotient of the two operands.
+The value produced is the floating-point quotient of the two operands.
+This instruction is assumed to execute in the default :ref:`floating-point
+environment <floatenv>`.
 This instruction can also take any number of :ref:`fast-math
 flags <fastmath>`, which are optimization hints to enable otherwise
-unsafe floating point optimizations:
+unsafe floating-point optimizations:
 Example:
 """"""""
 .. code-block:: text
 its two operands.
 Arguments:
 """"""""""
-The two arguments to the '``frem``' instruction must be :ref:`floating
+The two arguments to the '``frem``' instruction must be
-point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+:ref:`floating-point <t_floating>` or :ref:`vector <t_vector>` of
-Both arguments must have identical types.
+floating-point values. Both arguments must have identical types.
 Semantics:
 """"""""""
-Return the same value as a libm '``fmod``' function but without trapping or
+The value produced is the floating-point remainder of the two operands.
-setting ``errno``.
+This is the same output as a libm '``fmod``' function, but without any
+possibility of setting ``errno``. The remainder has the same sign as the
-The remainder has the same sign as the dividend. This instruction can also
+dividend.
-take any number of :ref:`fast-math flags <fastmath>`, which are optimization
+This instruction is assumed to execute in the default :ref:`floating-point
-hints to enable otherwise unsafe floating-point optimizations:
+environment <floatenv>`.
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating-point optimizations:
 Example:
 """"""""
 .. code-block:: text
 by the corresponding shift amount in ``op2``.
 If the ``nuw`` keyword is present, then the shift produces a poison
 value if it shifts out any non-zero bits.
 If the ``nsw`` keyword is present, then the shift produces a poison
-value it shifts out any bits that disagree with the resultant sign bit.
+value if it shifts out any bits that disagree with the resultant sign bit.
 Example:
 """"""""
 .. code-block:: text
 """""""
 ::
 <result> = extractelement <n x <ty>> <val>, <ty2> <idx>  ; yields <ty>
+<result> = extractelement <vscale x n x <ty>> <val>, <ty2> <idx> ; yields <ty>
 Overview:
 """""""""
 The '``extractelement``' instruction extracts a single scalar element
 Semantics:
 """"""""""
 The result is a scalar of the same type as the element type of ``val``.
 Its value is the value at position ``idx`` of ``val``. If ``idx``
-exceeds the length of ``val``, the results are undefined.
+exceeds the length of ``val`` for a fixed-length vector, the result is a
+:ref:`poison value <poisonvalues>`. For a scalable vector, if the value
+of ``idx`` exceeds the runtime length of the vector, the result is a
+:ref:`poison value <poisonvalues>`.
 Example:
 """"""""
 .. code-block:: text
 """""""
 ::
 <result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx>    ; yields <n x <ty>>
+<result> = insertelement <vscale x n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <vscale x n x <ty>>
 Overview:
 """""""""
 The '``insertelement``' instruction inserts a scalar element into a
 Semantics:
 """"""""""
 The result is a vector of the same type as ``val``. Its element values
 are those of ``val`` except at position ``idx``, where it gets the value
-``elt``. If ``idx`` exceeds the length of ``val``, the results are
+``elt``. If ``idx`` exceeds the length of ``val`` for a fixed-length vector,
-undefined.
+the result is a :ref:`poison value <poisonvalues>`. For a scalable vector,
+if the value of ``idx`` exceeds the runtime length of the vector, the result
+is a :ref:`poison value <poisonvalues>`.
 Example:
 """"""""
 .. code-block:: text
 """""""
 ::
 <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask>    ; yields <m x <ty>>
+<result> = shufflevector <vscale x n x <ty>> <v1>, <vscale x n x <ty>> v2, <vscale x m x i32> <mask>  ; yields <vscale x m x <ty>>
 Overview:
 """""""""
 The '``shufflevector``' instruction constructs a permutation of elements
 element of the result vector, which element of the two input vectors the
 result element gets. If the shuffle mask is undef, the result vector is
 undef. If any element of the mask operand is undef, that element of the
 result is undef. If the shuffle mask selects an undef element from one
 of the input vectors, the resulting element is undef.
+For scalable vectors, the only valid mask values at present are
+``zeroinitializer`` and ``undef``, since we cannot write all indices as
+literals for a vector with a length unknown at compile time.
 Example:
 """"""""
 .. code-block:: text
 '``type``' may be any sized type.
 Semantics:
 """"""""""
-Memory is allocated; a pointer is returned. The operation is undefined
+Memory is allocated; a pointer is returned. The allocated memory is
-if there is insufficient stack space for the allocation. '``alloca``'d
+uninitialized, and loading from uninitialized memory produces an undefined
-memory is automatically released when the function returns. The
+value. The operation itself is undefined if there is insufficient stack
-'``alloca``' instruction is commonly used to represent automatic
+space for the allocation.'``alloca``'d memory is automatically released
-variables that must have an address available. When the function returns
+when the function returns. The '``alloca``' instruction is commonly used
-(either with the ``ret`` or ``resume`` instructions), the memory is
+to represent automatic variables that must have an address available. When
-reclaimed. Allocating zero bytes is legal, but the result is undefined.
+the function returns (either with the ``ret`` or ``resume`` instructions),
-The order in which memory is allocated (ie., which way the stack grows)
+the memory is reclaimed. Allocating zero bytes is legal, but the returned
-is not specified.
+pointer may not be unique. The order in which memory is allocated (ie.,
+which way the stack grows) is not specified.
 Example:
 """"""""
 .. code-block:: llvm
 The optional ``!invariant.load`` metadata must reference a single
 metadata name ``<index>`` corresponding to a metadata node with no
 entries. If a load instruction tagged with the ``!invariant.load``
 metadata is executed, the optimizer may assume the memory location
 referenced by the load contains the same value at all points in the
-program where the memory location is known to be dereferenceable.
+program where the memory location is known to be dereferenceable;
+otherwise, the behavior is undefined.
 The optional ``!invariant.group`` metadata must reference a single metadata name
-``<index>`` corresponding to a metadata node. See ``invariant.group`` metadata.
+``<index>`` corresponding to a metadata node with no entries.
+See ``invariant.group`` metadata :ref:`invariant.group <md_invariant.group>`
 The optional ``!nonnull`` metadata must reference a single
 metadata name ``<index>`` corresponding to a metadata node with no
 entries. The existence of the ``!nonnull`` metadata on the
 instruction tells the optimizer that the value loaded is known to
-never be null. This is analogous to the ``nonnull`` attribute
+never be null. If the value is null at runtime, the behavior is undefined.
-on parameters and return values. This metadata can only be applied
+This is analogous to the ``nonnull`` attribute on parameters and return
-to loads of a pointer type.
+values. This metadata can only be applied to loads of a pointer type.
 The optional ``!dereferenceable`` metadata must reference a single metadata
 name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64``
-entry. The existence of the ``!dereferenceable`` metadata on the instruction
+entry.
-tells the optimizer that the value loaded is known to be dereferenceable.
+See ``dereferenceable`` metadata :ref:`dereferenceable <md_dereferenceable>`
-The number of bytes known to be dereferenceable is specified by the integer
-value in the metadata node. This is analogous to the ''dereferenceable''
-attribute on parameters and return values. This metadata can only be applied
-to loads of a pointer type.
 The optional ``!dereferenceable_or_null`` metadata must reference a single
 metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one
-``i64`` entry. The existence of the ``!dereferenceable_or_null`` metadata on the
+``i64`` entry.
-instruction tells the optimizer that the value loaded is known to be either
+See ``dereferenceable_or_null`` metadata :ref:`dereferenceable_or_null
-dereferenceable or null.
+<md_dereferenceable_or_null>`
-The number of bytes known to be dereferenceable is specified by the integer
-value in the metadata node. This is analogous to the ''dereferenceable_or_null''
-attribute on parameters and return values. This metadata can only be applied
-to loads of a pointer type.
 The optional ``!align`` metadata must reference a single metadata name
 ``<align_node>`` corresponding to a metadata node with one ``i64`` entry.
 The existence of the ``!align`` metadata on the instruction tells the
 optimizer that the value loaded is known to be aligned to a boundary specified
 by the integer value in the metadata node. The alignment must be a power of 2.
 This is analogous to the ''align'' attribute on parameters and return values.
-This metadata can only be applied to loads of a pointer type.
+This metadata can only be applied to loads of a pointer type. If the returned
+value is not appropriately aligned at runtime, the behavior is undefined.
 Semantics:
 """"""""""
 The location of memory pointed to is loaded. If the value being loaded
 -  xor
 -  max
 -  min
 -  umax
 -  umin
+-  fadd
-The type of '<value>' must be an integer type whose bit width is a power
+-  fsub
-of two greater than or equal to eight and less than or equal to a
-target-specific size limit. The type of the '``<pointer>``' operand must
+For most of these operations, the type of '<value>' must be an integer
-be a pointer to that type. If the ``atomicrmw`` is marked as
+type whose bit width is a power of two greater than or equal to eight
-``volatile``, then the optimizer is not allowed to modify the number or
+and less than or equal to a target-specific size limit. For xchg, this
-order of execution of this ``atomicrmw`` with other :ref:`volatile
+may also be a floating point type with the same size constraints as
-operations <volatile>`.
+integers.  For fadd/fsub, this must be a floating point type.  The
+type of the '``<pointer>``' operand must be a pointer to that type. If
+the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not
+allowed to modify the number or order of execution of this
+``atomicrmw`` with other :ref:`volatile operations <volatile>`.
 A ``atomicrmw`` instruction can also take an optional
 ":ref:`syncscope <syncscope>`" argument.
 Semantics:
 -  min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison)
 -  umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned
 comparison)
 -  umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned
 comparison)
+- fadd: ``*ptr = *ptr + val`` (using floating point arithmetic)
+- fsub: ``*ptr = *ptr - val`` (using floating point arithmetic)
 Example:
 """"""""
 .. code-block:: llvm
 The '``fptrunc``' instruction truncates ``value`` to type ``ty2``.
 Arguments:
 """"""""""
-The '``fptrunc``' instruction takes a :ref:`floating point <t_floating>`
+The '``fptrunc``' instruction takes a :ref:`floating-point <t_floating>`
-value to cast and a :ref:`floating point <t_floating>` type to cast it to.
+value to cast and a :ref:`floating-point <t_floating>` type to cast it to.
 The size of ``value`` must be larger than the size of ``ty2``. This
 implies that ``fptrunc`` cannot be used to make a *no-op cast*.
 Semantics:
 """"""""""
 The '``fptrunc``' instruction casts a ``value`` from a larger
-:ref:`floating point <t_floating>` type to a smaller :ref:`floating
+:ref:`floating-point <t_floating>` type to a smaller :ref:`floating-point
-point <t_floating>` type. If the value cannot fit (i.e. overflows) within the
+<t_floating>` type.
-destination type, ``ty2``, then the results are undefined. If the cast produces
+This instruction is assumed to execute in the default :ref:`floating-point
-an inexact result, how rounding is performed (e.g. truncation, also known as
+environment <floatenv>`.
-round to zero) is undefined.
 Example:
 """"""""
 .. code-block:: llvm
-%X = fptrunc double 123.0 to float         ; yields float:123.0
+%X = fptrunc double 16777217.0 to float    ; yields float:16777216.0
-%Y = fptrunc double 1.0E+300 to float      ; yields undefined
+%Y = fptrunc double 1.0E+300 to half       ; yields half:+infinity
 '``fpext .. to``' Instruction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 <result> = fpext <ty> <value> to <ty2>             ; yields ty2
 Overview:
 """""""""
-The '``fpext``' extends a floating point ``value`` to a larger floating
+The '``fpext``' extends a floating-point ``value`` to a larger floating-point
-point value.
+value.
 Arguments:
 """"""""""
-The '``fpext``' instruction takes a :ref:`floating point <t_floating>`
+The '``fpext``' instruction takes a :ref:`floating-point <t_floating>`
-``value`` to cast, and a :ref:`floating point <t_floating>` type to cast it
+``value`` to cast, and a :ref:`floating-point <t_floating>` type to cast it
 to. The source type must be smaller than the destination type.
 Semantics:
 """"""""""
 The '``fpext``' instruction extends the ``value`` from a smaller
-:ref:`floating point <t_floating>` type to a larger :ref:`floating
+:ref:`floating-point <t_floating>` type to a larger :ref:`floating-point
-point <t_floating>` type. The ``fpext`` cannot be used to make a
+<t_floating>` type. The ``fpext`` cannot be used to make a
 *no-op cast* because it always changes bits. Use ``bitcast`` to make a
-*no-op cast* for a floating point cast.
+*no-op cast* for a floating-point cast.
 Example:
 """"""""
 .. code-block:: llvm
 <result> = fptoui <ty> <value> to <ty2>             ; yields ty2
 Overview:
 """""""""
-The '``fptoui``' converts a floating point ``value`` to its unsigned
+The '``fptoui``' converts a floating-point ``value`` to its unsigned
 integer equivalent of type ``ty2``.
 Arguments:
 """"""""""
 The '``fptoui``' instruction takes a value to cast, which must be a
-scalar or vector :ref:`floating point <t_floating>` value, and a type to
+scalar or vector :ref:`floating-point <t_floating>` value, and a type to
 cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
-``ty`` is a vector floating point type, ``ty2`` must be a vector integer
+``ty`` is a vector floating-point type, ``ty2`` must be a vector integer
 type with the same number of elements as ``ty``
 Semantics:
 """"""""""
-The '``fptoui``' instruction converts its :ref:`floating
+The '``fptoui``' instruction converts its :ref:`floating-point
-point <t_floating>` operand into the nearest (rounding towards zero)
+<t_floating>` operand into the nearest (rounding towards zero)
-unsigned integer value. If the value cannot fit in ``ty2``, the results
+unsigned integer value. If the value cannot fit in ``ty2``, the result
-are undefined.
+is a :ref:`poison value <poisonvalues>`.
 Example:
 """"""""
 .. code-block:: llvm
 <result> = fptosi <ty> <value> to <ty2>             ; yields ty2
 Overview:
 """""""""
-The '``fptosi``' instruction converts :ref:`floating point <t_floating>`
+The '``fptosi``' instruction converts :ref:`floating-point <t_floating>`
 ``value`` to type ``ty2``.
 Arguments:
 """"""""""
 The '``fptosi``' instruction takes a value to cast, which must be a
-scalar or vector :ref:`floating point <t_floating>` value, and a type to
+scalar or vector :ref:`floating-point <t_floating>` value, and a type to
 cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
-``ty`` is a vector floating point type, ``ty2`` must be a vector integer
+``ty`` is a vector floating-point type, ``ty2`` must be a vector integer
 type with the same number of elements as ``ty``
 Semantics:
 """"""""""
-The '``fptosi``' instruction converts its :ref:`floating
+The '``fptosi``' instruction converts its :ref:`floating-point
-point <t_floating>` operand into the nearest (rounding towards zero)
+<t_floating>` operand into the nearest (rounding towards zero)
-signed integer value. If the value cannot fit in ``ty2``, the results
+signed integer value. If the value cannot fit in ``ty2``, the result
-are undefined.
+is a :ref:`poison value <poisonvalues>`.
 Example:
 """"""""
 .. code-block:: llvm
 Arguments:
 """"""""""
 The '``uitofp``' instruction takes a value to cast, which must be a
 scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
-``ty2``, which must be an :ref:`floating point <t_floating>` type. If
+``ty2``, which must be an :ref:`floating-point <t_floating>` type. If
-``ty`` is a vector integer type, ``ty2`` must be a vector floating point
+``ty`` is a vector integer type, ``ty2`` must be a vector floating-point
 type with the same number of elements as ``ty``
 Semantics:
 """"""""""
 The '``uitofp``' instruction interprets its operand as an unsigned
-integer quantity and converts it to the corresponding floating point
+integer quantity and converts it to the corresponding floating-point
-value. If the value cannot fit in the floating point value, the results
+value. If the value cannot be exactly represented, it is rounded using
-are undefined.
+the default rounding mode.
 Example:
 """"""""
 .. code-block:: llvm
 Arguments:
 """"""""""
 The '``sitofp``' instruction takes a value to cast, which must be a
 scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
-``ty2``, which must be an :ref:`floating point <t_floating>` type. If
+``ty2``, which must be an :ref:`floating-point <t_floating>` type. If
-``ty`` is a vector integer type, ``ty2`` must be a vector floating point
+``ty`` is a vector integer type, ``ty2`` must be a vector floating-point
 type with the same number of elements as ``ty``
 Semantics:
 """"""""""
 The '``sitofp``' instruction interprets its operand as a signed integer
-quantity and converts it to the corresponding floating point value. If
+quantity and converts it to the corresponding floating-point value. If the
-the value cannot fit in the floating point value, the results are
+value cannot be exactly represented, it is rounded using the default rounding
-undefined.
+mode.
 Example:
 """"""""
 .. code-block:: llvm
 Syntax:
 """""""
 ::
-<result> = inttoptr <ty> <value> to <ty2>             ; yields ty2
+<result> = inttoptr <ty> <value> to <ty2>[, !dereferenceable !<deref_bytes_node>][, !dereferenceable_or_null !<deref_bytes_node]             ; yields ty2
 Overview:
 """""""""
 The '``inttoptr``' instruction converts an integer ``value`` to a
 """"""""""
 The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to
 cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>`
 type.
+The optional ``!dereferenceable`` metadata must reference a single metadata
+name ``<deref_bytes_node>`` corresponding to a metadata node with one ``i64``
+entry.
+See ``dereferenceable`` metadata.
+The optional ``!dereferenceable_or_null`` metadata must reference a single
+metadata name ``<deref_bytes_node>`` corresponding to a metadata node with one
+``i64`` entry.
+See ``dereferenceable_or_null`` metadata.
 Semantics:
 """"""""""
 The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by
 """""""""
 The '``fcmp``' instruction returns a boolean value or vector of boolean
 values based on comparison of its operands.
-If the operands are floating point scalars, then the result type is a
+If the operands are floating-point scalars, then the result type is a
 boolean (:ref:`i1 <t_integer>`).
-If the operands are floating point vectors, then the result type is a
+If the operands are floating-point vectors, then the result type is a
 vector of boolean with the same number of elements as the operands being
 compared.
 Arguments:
 """"""""""
 #. ``true``: no comparison, always returns true
 *Ordered* means that neither operand is a QNAN while *unordered* means
 that either operand may be a QNAN.
-Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating
+Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating-point
-point <t_floating>` type or a :ref:`vector <t_vector>` of floating point
+<t_floating>` type or a :ref:`vector <t_vector>` of floating-point type.
-type. They must have identical types.
+They must have identical types.
 Semantics:
 """"""""""
 The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the
 #. ``uno``: yields ``true`` if either operand is a QNAN.
 #. ``true``: always yields ``true``, regardless of operands.
 The ``fcmp`` instruction can also optionally take any number of
 :ref:`fast-math flags <fastmath>`, which are optimization hints to enable
-otherwise unsafe floating point optimizations.
+otherwise unsafe floating-point optimizations.
 Any set of fast-math flags are legal on an ``fcmp`` instruction, but the
 only flags that have any effect on its semantics are those that allow
 assumptions to be made about the values of input arguments; namely
-``nnan``, ``ninf``, and ``nsz``. See :ref:`fastmath` for more information.
+``nnan``, ``ninf``, and ``reassoc``. See :ref:`fastmath` for more information.
 Example:
 """"""""
 .. code-block:: text
 Syntax:
 """""""
 ::
-<result> = select selty <cond>, <ty> <val1>, <ty> <val2>             ; yields ty
+<result> = select [fast-math flags] selty <cond>, <ty> <val1>, <ty> <val2>             ; yields ty
 selty is either i1 or {<N x i1>}
 Overview:
 """""""""
 The '``select``' instruction requires an 'i1' value or a vector of 'i1'
 values indicating the condition, and two values of the same :ref:`first
 class <t_firstclass>` type.
+#. The optional ``fast-math flags`` marker indicates that the select has one or more
+:ref:`fast-math flags <fastmath>`. These are optimization hints to enable
+otherwise unsafe floating-point optimizations. Fast-math flags are only valid
+for selects that return a floating-point scalar or vector type.
 Semantics:
 """"""""""
 If the condition is an i1 and it evaluates to 1, the instruction returns
 the first value argument; otherwise, it returns the second value
 Syntax:
 """""""
 ::
-<result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] <ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
+<result> = [tail | musttail | notail ] call [fast-math flags] [cconv] [ret attrs] [addrspace(<num>)]
-[ operand bundles ]
+[<ty>|<fnty> <fnptrval>(<function args>) [fn attrs] [ operand bundles ]
 Overview:
 """""""""
 The '``call``' instruction represents a simple function call.
 #. The call will not cause unbounded stack growth if it is part of a
 recursive cycle in the call graph.
 #. Arguments with the :ref:`inalloca <attr_inalloca>` attribute are
 forwarded in place.
+#. If the musttail call appears in a function with the ``"thunk"`` attribute
+and the caller and callee both have varargs, than any unprototyped
+arguments in register or memory are forwarded to the callee. Similarly,
+the return value of the callee is returned the the caller's caller, even
+if a void return type is in use.
 Both markers imply that the callee does not access allocas from the caller.
 The ``tail`` marker additionally implies that the callee does not access
-varargs from the caller, while ``musttail`` implies that varargs from the
+varargs from the caller. Calls marked ``musttail`` must obey the following
-caller are passed to the callee. Calls marked ``musttail`` must obey the
+additional  rules:
-following additional  rules:
 - The call must immediately precede a :ref:`ret <i_ret>` instruction,
 or a pointer bitcast followed by a ret instruction.
 - The ret instruction must return the (possibly bitcasted) value
 produced by the call or void.
 calling convention of the call must match the calling convention of
 the target function, or else the behavior is undefined.
 #. The optional :ref:`Parameter Attributes <paramattrs>` list for return
 values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
 are valid here.
+#. The optional addrspace attribute can be used to indicate the address space
+of the called function. If it is not specified, the program address space
+from the :ref:`datalayout string<langref_datalayout>` will be used.
 #. '``ty``': the type of the call instruction itself which is also the
 type of the return value. Functions that return no value are marked
 ``void``.
 #. '``fnty``': shall be the signature of the function being called. The
 argument types must match the types implied by this signature. This
 ``i29 @llvm.ctpop.i29(i29 %val)``. Only one type, the return type, is
 overloaded, and only one type suffix is required. Because the argument's
 type is matched against the return type, it does not require its own
 name suffix.
+For target developers who are defining intrinsics for back-end code
+generation, any intrinsic overloads based solely the distinction between
+integer or floating point types should not be relied upon for correct
+code generation. In such cases, the recommended approach for target
+maintainers when defining intrinsics is to create separate integer and
+FP intrinsics rather than rely on overloading. For example, if different
+codegen is required for ``llvm.target.foo(<4 x i32>)`` and
+``llvm.target.foo(<4 x float>)`` then these should be split into
+different intrinsics.
 To learn how to add an intrinsic function, please see the `Extending
 LLVM Guide <ExtendingLLVM.html>`_.
 .. _int_varargs:
 Note that calling this intrinsic does not prevent function inlining or
 other aggressive transformations, so the value returned may not be that
 of the obvious source-language caller.
-This intrinsic is only implemented for x86.
+This intrinsic is only implemented for x86 and aarch64.
+'``llvm.sponentry``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.sponentry()
+Overview:
+"""""""""
+The '``llvm.sponentry``' intrinsic returns the stack pointer value at
+the entry of the current function calling this intrinsic.
+Semantics:
+""""""""""
+Note this intrinsic is only verified on AArch64.
 '``llvm.frameaddress``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """"""""""
 The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
 source location to the destination location, which are not allowed to
 overlap. It copies "len" bytes of memory over. If the argument is known
-to be aligned to some boundary, this can be specified as the fourth
+to be aligned to some boundary, this can be specified as an attribute on
-argument, otherwise it should be set to 0 or 1 (both meaning no alignment).
+the argument.
+If "len" is 0, the pointers may be NULL or dangling. However, they must still
+be appropriately aligned.
 .. _int_memmove:
 '``llvm.memmove``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 """"""""""
 The '``llvm.memmove.*``' intrinsics copy a block of memory from the
 source location to the destination location, which may overlap. It
 copies "len" bytes of memory over. If the argument is known to be
-aligned to some boundary, this can be specified as the fourth argument,
+aligned to some boundary, this can be specified as an attribute on
-otherwise it should be set to 0 or 1 (both meaning no alignment).
+the argument.
+If "len" is 0, the pointers may be NULL or dangling. However, they must still
+be appropriately aligned.
 .. _int_memset:
 '``llvm.memset.*``' Intrinsics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Semantics:
 """"""""""
 The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting
-at the destination location.
+at the destination location. If the argument is known to be
+aligned to some boundary, this can be specified as an attribute on
+the argument.
+If "len" is 0, the pointers may be NULL or dangling. However, they must still
+be appropriately aligned.
 '``llvm.sqrt.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.powi`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.powi.f32(float  %Val, i32 %power)
 Overview:
 """""""""
 The '``llvm.powi.*``' intrinsics return the first operand raised to the
 specified (positive or negative) power. The order of evaluation of
-multiplications is not defined. When a vector of floating point type is
+multiplications is not defined. When a vector of floating-point type is
 used, the second argument remains a scalar integer value.
 Arguments:
 """"""""""
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.fabs`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.fabs.f32(float  %Val)
 operand.
 Arguments:
 """"""""""
-The argument and return value are floating point numbers of the same
+The argument and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.minnum`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.minnum.f32(float %Val0, float %Val1)
 Arguments:
 """"""""""
-The arguments and return value are floating point numbers of the same
+The arguments and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
-Follows the IEEE-754 semantics for minNum, which also match for libm's
+Follows the IEEE-754 semantics for minNum, except for handling of
-fmin.
+signaling NaNs. This match's the behavior of libm's fmin.
 If either operand is a NaN, returns the other non-NaN operand. Returns
-NaN only if both operands are NaN. If the operands compare equal,
+NaN only if both operands are NaN. The returned NaN is always
-returns a value that compares equal to both operands. This means that
+quiet. If the operands compare equal, returns a value that compares
-fmin(+/-0.0, +/-0.0) could return either -0.0 or 0.0.
+equal to both operands. This means that fmin(+/-0.0, +/-0.0) could
+return either -0.0 or 0.0.
+Unlike the IEEE-754 2008 behavior, this does not distinguish between
+signaling and quiet NaN inputs. If a target's implementation follows
+the standard and returns a quiet NaN if either input is a signaling
+NaN, the intrinsic lowering is responsible for quieting the inputs to
+correctly return the non-NaN input (e.g. by using the equivalent of
+``llvm.canonicalize``).
 '``llvm.maxnum.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.maxnum`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.maxnum.f32(float  %Val0, float  %Val1l)
 Arguments:
 """"""""""
-The arguments and return value are floating point numbers of the same
+The arguments and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
-Follows the IEEE-754 semantics for maxNum, which also match for libm's
+Follows the IEEE-754 semantics for maxNum except for the handling of
-fmax.
+signaling NaNs. This matches the behavior of libm's fmax.
 If either operand is a NaN, returns the other non-NaN operand. Returns
-NaN only if both operands are NaN. If the operands compare equal,
+NaN only if both operands are NaN. The returned NaN is always
-returns a value that compares equal to both operands. This means that
+quiet. If the operands compare equal, returns a value that compares
-fmax(+/-0.0, +/-0.0) could return either -0.0 or 0.0.
+equal to both operands. This means that fmax(+/-0.0, +/-0.0) could
+return either -0.0 or 0.0.
+Unlike the IEEE-754 2008 behavior, this does not distinguish between
+signaling and quiet NaN inputs. If a target's implementation follows
+the standard and returns a quiet NaN if either input is a signaling
+NaN, the intrinsic lowering is responsible for quieting the inputs to
+correctly return the non-NaN input (e.g. by using the equivalent of
+``llvm.canonicalize``).
+'``llvm.minimum.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.minimum`` on any
+floating-point or vector of floating-point type. Not all targets support
+all types however.
+::
+declare float     @llvm.minimum.f32(float %Val0, float %Val1)
+declare double    @llvm.minimum.f64(double %Val0, double %Val1)
+declare x86_fp80  @llvm.minimum.f80(x86_fp80 %Val0, x86_fp80 %Val1)
+declare fp128     @llvm.minimum.f128(fp128 %Val0, fp128 %Val1)
+declare ppc_fp128 @llvm.minimum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1)
+Overview:
+"""""""""
+The '``llvm.minimum.*``' intrinsics return the minimum of the two
+arguments, propagating NaNs and treating -0.0 as less than +0.0.
+Arguments:
+""""""""""
+The arguments and return value are floating-point numbers of the same
+type.
+Semantics:
+""""""""""
+If either operand is a NaN, returns NaN. Otherwise returns the lesser
+of the two arguments. -0.0 is considered to be less than +0.0 for this
+intrinsic. Note that these are the semantics specified in the draft of
+IEEE 754-2018.
+'``llvm.maximum.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.maximum`` on any
+floating-point or vector of floating-point type. Not all targets support
+all types however.
+::
+declare float     @llvm.maximum.f32(float %Val0, float %Val1)
+declare double    @llvm.maximum.f64(double %Val0, double %Val1)
+declare x86_fp80  @llvm.maximum.f80(x86_fp80 %Val0, x86_fp80 %Val1)
+declare fp128     @llvm.maximum.f128(fp128 %Val0, fp128 %Val1)
+declare ppc_fp128 @llvm.maximum.ppcf128(ppc_fp128 %Val0, ppc_fp128 %Val1)
+Overview:
+"""""""""
+The '``llvm.maximum.*``' intrinsics return the maximum of the two
+arguments, propagating NaNs and treating -0.0 as less than +0.0.
+Arguments:
+""""""""""
+The arguments and return value are floating-point numbers of the same
+type.
+Semantics:
+""""""""""
+If either operand is a NaN, returns NaN. Otherwise returns the greater
+of the two arguments. -0.0 is considered to be less than +0.0 for this
+intrinsic. Note that these are the semantics specified in the draft of
+IEEE 754-2018.
 '``llvm.copysign.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.copysign`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.copysign.f32(float  %Mag, float  %Sgn)
 first operand and the sign of the second operand.
 Arguments:
 """"""""""
-The arguments and return value are floating point numbers of the same
+The arguments and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.floor`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.floor.f32(float  %Val)
 The '``llvm.floor.*``' intrinsics return the floor of the operand.
 Arguments:
 """"""""""
-The argument and return value are floating point numbers of the same
+The argument and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.ceil`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.ceil.f32(float  %Val)
 The '``llvm.ceil.*``' intrinsics return the ceiling of the operand.
 Arguments:
 """"""""""
-The argument and return value are floating point numbers of the same
+The argument and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.trunc`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.trunc.f32(float  %Val)
 nearest integer not larger in magnitude than the operand.
 Arguments:
 """"""""""
-The argument and return value are floating point numbers of the same
+The argument and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.rint`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.rint.f32(float  %Val)
 operand isn't an integer.
 Arguments:
 """"""""""
-The argument and return value are floating point numbers of the same
+The argument and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.nearbyint.f32(float  %Val)
 nearest integer.
 Arguments:
 """"""""""
-The argument and return value are floating point numbers of the same
+The argument and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.round`` on any
-floating point or vector of floating point type. Not all targets support
+floating-point or vector of floating-point type. Not all targets support
 all types however.
 ::
 declare float     @llvm.round.f32(float  %Val)
 nearest integer.
 Arguments:
 """"""""""
-The argument and return value are floating point numbers of the same
+The argument and return value are floating-point numbers of the same
 type.
 Semantics:
 """"""""""
 This function returns the same values as the libm ``round``
 functions would, and handles error conditions in the same way.
+'``llvm.lround.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.lround`` on any
+floating-point type. Not all targets support all types however.
+::
+declare i32 @llvm.lround.i32.f32(float %Val)
+declare i32 @llvm.lround.i32.f64(double %Val)
+declare i32 @llvm.lround.i32.f80(float %Val)
+declare i32 @llvm.lround.i32.f128(double %Val)
+declare i32 @llvm.lround.i32.ppcf128(double %Val)
+declare i64 @llvm.lround.i64.f32(float %Val)
+declare i64 @llvm.lround.i64.f64(double %Val)
+declare i64 @llvm.lround.i64.f80(float %Val)
+declare i64 @llvm.lround.i64.f128(double %Val)
+declare i64 @llvm.lround.i64.ppcf128(double %Val)
+Overview:
+"""""""""
+The '``llvm.lround.*``' intrinsics returns the operand rounded to the
+nearest integer.
+Arguments:
+""""""""""
+The argument is a floating-point number and return is an integer type.
+Semantics:
+""""""""""
+This function returns the same values as the libm ``lround``
+functions would, but without setting errno.
+'``llvm.llround.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.llround`` on any
+floating-point type. Not all targets support all types however.
+::
+declare i64 @llvm.lround.i64.f32(float %Val)
+declare i64 @llvm.lround.i64.f64(double %Val)
+declare i64 @llvm.lround.i64.f80(float %Val)
+declare i64 @llvm.lround.i64.f128(double %Val)
+declare i64 @llvm.lround.i64.ppcf128(double %Val)
+Overview:
+"""""""""
+The '``llvm.llround.*``' intrinsics returns the operand rounded to the
+nearest integer.
+Arguments:
+""""""""""
+The argument is a floating-point number and return is an integer type.
+Semantics:
+""""""""""
+This function returns the same values as the libm ``llround``
+functions would, but without setting errno.
+'``llvm.lrint.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.lrint`` on any
+floating-point type. Not all targets support all types however.
+::
+declare i32 @llvm.lrint.i32.f32(float %Val)
+declare i32 @llvm.lrint.i32.f64(double %Val)
+declare i32 @llvm.lrint.i32.f80(float %Val)
+declare i32 @llvm.lrint.i32.f128(double %Val)
+declare i32 @llvm.lrint.i32.ppcf128(double %Val)
+declare i64 @llvm.lrint.i64.f32(float %Val)
+declare i64 @llvm.lrint.i64.f64(double %Val)
+declare i64 @llvm.lrint.i64.f80(float %Val)
+declare i64 @llvm.lrint.i64.f128(double %Val)
+declare i64 @llvm.lrint.i64.ppcf128(double %Val)
+Overview:
+"""""""""
+The '``llvm.lrint.*``' intrinsics returns the operand rounded to the
+nearest integer.
+Arguments:
+""""""""""
+The argument is a floating-point number and return is an integer type.
+Semantics:
+""""""""""
+This function returns the same values as the libm ``lrint``
+functions would, but without setting errno.
+'``llvm.llrint.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.llrint`` on any
+floating-point type. Not all targets support all types however.
+::
+declare i64 @llvm.llrint.i64.f32(float %Val)
+declare i64 @llvm.llrint.i64.f64(double %Val)
+declare i64 @llvm.llrint.i64.f80(float %Val)
+declare i64 @llvm.llrint.i64.f128(double %Val)
+declare i64 @llvm.llrint.i64.ppcf128(double %Val)
+Overview:
+"""""""""
+The '``llvm.llrint.*``' intrinsics returns the operand rounded to the
+nearest integer.
+Arguments:
+""""""""""
+The argument is a floating-point number and return is an integer type.
+Semantics:
+""""""""""
+This function returns the same values as the libm ``llrint``
+functions would, but without setting errno.
 Bit Manipulation Intrinsics
 ---------------------------
 LLVM provides intrinsics for a few important bit manipulation
 ::
 declare i16 @llvm.bitreverse.i16(i16 <id>)
 declare i32 @llvm.bitreverse.i32(i32 <id>)
 declare i64 @llvm.bitreverse.i64(i64 <id>)
+declare <4 x i32> @llvm.bitreverse.v4i32(<4 x i32> <id>)
 Overview:
 """""""""
 The '``llvm.bitreverse``' family of intrinsics is used to reverse the
-bitpattern of an integer value; for example ``0b10110110`` becomes
+bitpattern of an integer value or vector of integer values; for example
-``0b01101101``.
+``0b10110110`` becomes ``0b01101101``.
 Semantics:
 """"""""""
 The ``llvm.bitreverse.iN`` intrinsic returns an iN value that has bit
-``M`` in the input moved to bit ``N-M`` in the output.
+``M`` in the input moved to bit ``N-M`` in the output. The vector
+intrinsics, such as ``llvm.bitreverse.v4i32``, operate on a per-element
+basis and the element order is not affected.
 '``llvm.bswap.*``' Intrinsics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 ::
 declare i16 @llvm.bswap.i16(i16 <id>)
 declare i32 @llvm.bswap.i32(i32 <id>)
 declare i64 @llvm.bswap.i64(i64 <id>)
+declare <4 x i32> @llvm.bswap.v4i32(<4 x i32> <id>)
-Overview:
-"""""""""
+Overview:
+"""""""""
-The '``llvm.bswap``' family of intrinsics is used to byte swap integer
-values with an even number of bytes (positive multiple of 16 bits).
+The '``llvm.bswap``' family of intrinsics is used to byte swap an integer
-These are useful for performing operations on data that is not in the
+value or vector of integer values with an even number of bytes (positive
-target's native byte order.
+multiple of 16 bits).
 Semantics:
 """"""""""
 The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high
 intrinsic returns an i32 value that has the four bytes of the input i32
 swapped, so that if the input bytes are numbered 0, 1, 2, 3 then the
 returned i32 will have its bytes in 3, 2, 1, 0 order. The
 ``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this
 concept to additional even-byte lengths (6 bytes, 8 bytes and more,
-respectively).
+respectively). The vector intrinsics, such as ``llvm.bswap.v4i32``,
+operate on a per-element basis and the element order is not affected.
 '``llvm.ctpop.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 then the result is the size in bits of the type of ``src`` if
 ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
 ``llvm.cttz(2) = 1``.
 .. _int_overflow:
+'``llvm.fshl.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.fshl`` on any
+integer bit width or any vector of integer elements. Not all targets
+support all bit widths or vector types, however.
+::
+declare i8  @llvm.fshl.i8 (i8 %a, i8 %b, i8 %c)
+declare i67 @llvm.fshl.i67(i67 %a, i67 %b, i67 %c)
+declare <2 x i32> @llvm.fshl.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c)
+Overview:
+"""""""""
+The '``llvm.fshl``' family of intrinsic functions performs a funnel shift left:
+the first two values are concatenated as { %a : %b } (%a is the most significant
+bits of the wide value), the combined value is shifted left, and the most
+significant bits are extracted to produce a result that is the same size as the
+original arguments. If the first 2 arguments are identical, this is equivalent
+to a rotate left operation. For vector types, the operation occurs for each
+element of the vector. The shift argument is treated as an unsigned amount
+modulo the element size of the arguments.
+Arguments:
+""""""""""
+The first two arguments are the values to be concatenated. The third
+argument is the shift amount. The arguments may be any integer type or a
+vector with integer element type. All arguments and the return value must
+have the same type.
+Example:
+""""""""
+.. code-block:: text
+%r = call i8 @llvm.fshl.i8(i8 %x, i8 %y, i8 %z)  ; %r = i8: msb_extract((concat(x, y) << (z % 8)), 8)
+%r = call i8 @llvm.fshl.i8(i8 255, i8 0, i8 15)  ; %r = i8: 128 (0b10000000)
+%r = call i8 @llvm.fshl.i8(i8 15, i8 15, i8 11)  ; %r = i8: 120 (0b01111000)
+%r = call i8 @llvm.fshl.i8(i8 0, i8 255, i8 8)   ; %r = i8: 0   (0b00000000)
+'``llvm.fshr.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.fshr`` on any
+integer bit width or any vector of integer elements. Not all targets
+support all bit widths or vector types, however.
+::
+declare i8  @llvm.fshr.i8 (i8 %a, i8 %b, i8 %c)
+declare i67 @llvm.fshr.i67(i67 %a, i67 %b, i67 %c)
+declare <2 x i32> @llvm.fshr.v2i32(<2 x i32> %a, <2 x i32> %b, <2 x i32> %c)
+Overview:
+"""""""""
+The '``llvm.fshr``' family of intrinsic functions performs a funnel shift right:
+the first two values are concatenated as { %a : %b } (%a is the most significant
+bits of the wide value), the combined value is shifted right, and the least
+significant bits are extracted to produce a result that is the same size as the
+original arguments. If the first 2 arguments are identical, this is equivalent
+to a rotate right operation. For vector types, the operation occurs for each
+element of the vector. The shift argument is treated as an unsigned amount
+modulo the element size of the arguments.
+Arguments:
+""""""""""
+The first two arguments are the values to be concatenated. The third
+argument is the shift amount. The arguments may be any integer type or a
+vector with integer element type. All arguments and the return value must
+have the same type.
+Example:
+""""""""
+.. code-block:: text
+%r = call i8 @llvm.fshr.i8(i8 %x, i8 %y, i8 %z)  ; %r = i8: lsb_extract((concat(x, y) >> (z % 8)), 8)
+%r = call i8 @llvm.fshr.i8(i8 255, i8 0, i8 15)  ; %r = i8: 254 (0b11111110)
+%r = call i8 @llvm.fshr.i8(i8 15, i8 15, i8 11)  ; %r = i8: 225 (0b11100001)
+%r = call i8 @llvm.fshr.i8(i8 0, i8 255, i8 8)   ; %r = i8: 255 (0b11111111)
 Arithmetic with Overflow Intrinsics
 -----------------------------------
 LLVM provides intrinsics for fast arithmetic overflow checking.
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 ::
 declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
 declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
 declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
+declare {<4 x i32>, <4 x i1>} @llvm.sadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 Overview:
 """""""""
 The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 ::
 declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
 declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
 declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
+declare {<4 x i32>, <4 x i1>} @llvm.uadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 Overview:
 """""""""
 The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 ::
 declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
 declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
 declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
+declare {<4 x i32>, <4 x i1>} @llvm.ssub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 Overview:
 """""""""
 The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 ::
 declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
 declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
 declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
+declare {<4 x i32>, <4 x i1>} @llvm.usub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 Overview:
 """""""""
 The '``llvm.usub.with.overflow``' family of intrinsic functions perform
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 ::
 declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
 declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
 declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
+declare {<4 x i32>, <4 x i1>} @llvm.smul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 Overview:
 """""""""
 The '``llvm.smul.with.overflow``' family of intrinsic functions perform
 Syntax:
 """""""
 This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 ::
 declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
 declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
 declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
+declare {<4 x i32>, <4 x i1>} @llvm.umul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 Overview:
 """""""""
 The '``llvm.umul.with.overflow``' family of intrinsic functions perform
 %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
 %sum = extractvalue {i32, i1} %res, 0
 %obit = extractvalue {i32, i1} %res, 1
 br i1 %obit, label %overflow, label %normal
+Saturation Arithmetic Intrinsics
+---------------------------------
+Saturation arithmetic is a version of arithmetic in which operations are
+limited to a fixed range between a minimum and maximum value. If the result of
+an operation is greater than the maximum value, the result is set (or
+"clamped") to this maximum. If it is below the minimum, it is clamped to this
+minimum.
+'``llvm.sadd.sat.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.sadd.sat``
+on any integer bit width or vectors of integers.
+::
+declare i16 @llvm.sadd.sat.i16(i16 %a, i16 %b)
+declare i32 @llvm.sadd.sat.i32(i32 %a, i32 %b)
+declare i64 @llvm.sadd.sat.i64(i64 %a, i64 %b)
+declare <4 x i32> @llvm.sadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b)
+Overview
+"""""""""
+The '``llvm.sadd.sat``' family of intrinsic functions perform signed
+saturation addition on the 2 arguments.
+Arguments
+""""""""""
+The arguments (%a and %b) and the result may be of integer types of any bit
+width, but they must have the same bit width. ``%a`` and ``%b`` are the two
+values that will undergo signed addition.
+Semantics:
+""""""""""
+The maximum value this operation can clamp to is the largest signed value
+representable by the bit width of the arguments. The minimum value is the
+smallest signed value representable by this bit width.
+Examples
+"""""""""
+.. code-block:: llvm
+%res = call i4 @llvm.sadd.sat.i4(i4 1, i4 2)  ; %res = 3
+%res = call i4 @llvm.sadd.sat.i4(i4 5, i4 6)  ; %res = 7
+%res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 2)  ; %res = -2
+%res = call i4 @llvm.sadd.sat.i4(i4 -4, i4 -5)  ; %res = -8
+'``llvm.uadd.sat.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.uadd.sat``
+on any integer bit width or vectors of integers.
+::
+declare i16 @llvm.uadd.sat.i16(i16 %a, i16 %b)
+declare i32 @llvm.uadd.sat.i32(i32 %a, i32 %b)
+declare i64 @llvm.uadd.sat.i64(i64 %a, i64 %b)
+declare <4 x i32> @llvm.uadd.sat.v4i32(<4 x i32> %a, <4 x i32> %b)
+Overview
+"""""""""
+The '``llvm.uadd.sat``' family of intrinsic functions perform unsigned
+saturation addition on the 2 arguments.
+Arguments
+""""""""""
+The arguments (%a and %b) and the result may be of integer types of any bit
+width, but they must have the same bit width. ``%a`` and ``%b`` are the two
+values that will undergo unsigned addition.
+Semantics:
+""""""""""
+The maximum value this operation can clamp to is the largest unsigned value
+representable by the bit width of the arguments. Because this is an unsigned
+operation, the result will never saturate towards zero.
+Examples
+"""""""""
+.. code-block:: llvm
+%res = call i4 @llvm.uadd.sat.i4(i4 1, i4 2)  ; %res = 3
+%res = call i4 @llvm.uadd.sat.i4(i4 5, i4 6)  ; %res = 11
+%res = call i4 @llvm.uadd.sat.i4(i4 8, i4 8)  ; %res = 15
+'``llvm.ssub.sat.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.ssub.sat``
+on any integer bit width or vectors of integers.
+::
+declare i16 @llvm.ssub.sat.i16(i16 %a, i16 %b)
+declare i32 @llvm.ssub.sat.i32(i32 %a, i32 %b)
+declare i64 @llvm.ssub.sat.i64(i64 %a, i64 %b)
+declare <4 x i32> @llvm.ssub.sat.v4i32(<4 x i32> %a, <4 x i32> %b)
+Overview
+"""""""""
+The '``llvm.ssub.sat``' family of intrinsic functions perform signed
+saturation subtraction on the 2 arguments.
+Arguments
+""""""""""
+The arguments (%a and %b) and the result may be of integer types of any bit
+width, but they must have the same bit width. ``%a`` and ``%b`` are the two
+values that will undergo signed subtraction.
+Semantics:
+""""""""""
+The maximum value this operation can clamp to is the largest signed value
+representable by the bit width of the arguments. The minimum value is the
+smallest signed value representable by this bit width.
+Examples
+"""""""""
+.. code-block:: llvm
+%res = call i4 @llvm.ssub.sat.i4(i4 2, i4 1)  ; %res = 1
+%res = call i4 @llvm.ssub.sat.i4(i4 2, i4 6)  ; %res = -4
+%res = call i4 @llvm.ssub.sat.i4(i4 -4, i4 5)  ; %res = -8
+%res = call i4 @llvm.ssub.sat.i4(i4 4, i4 -5)  ; %res = 7
+'``llvm.usub.sat.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.usub.sat``
+on any integer bit width or vectors of integers.
+::
+declare i16 @llvm.usub.sat.i16(i16 %a, i16 %b)
+declare i32 @llvm.usub.sat.i32(i32 %a, i32 %b)
+declare i64 @llvm.usub.sat.i64(i64 %a, i64 %b)
+declare <4 x i32> @llvm.usub.sat.v4i32(<4 x i32> %a, <4 x i32> %b)
+Overview
+"""""""""
+The '``llvm.usub.sat``' family of intrinsic functions perform unsigned
+saturation subtraction on the 2 arguments.
+Arguments
+""""""""""
+The arguments (%a and %b) and the result may be of integer types of any bit
+width, but they must have the same bit width. ``%a`` and ``%b`` are the two
+values that will undergo unsigned subtraction.
+Semantics:
+""""""""""
+The minimum value this operation can clamp to is 0, which is the smallest
+unsigned value representable by the bit width of the unsigned arguments.
+Because this is an unsigned operation, the result will never saturate towards
+the largest possible value representable by this bit width.
+Examples
+"""""""""
+.. code-block:: llvm
+%res = call i4 @llvm.usub.sat.i4(i4 2, i4 1)  ; %res = 1
+%res = call i4 @llvm.usub.sat.i4(i4 2, i4 6)  ; %res = 0
+Fixed Point Arithmetic Intrinsics
+---------------------------------
+A fixed point number represents a real data type for a number that has a fixed
+number of digits after a radix point (equivalent to the decimal point '.').
+The number of digits after the radix point is referred as the ``scale``. These
+are useful for representing fractional values to a specific precision. The
+following intrinsics perform fixed point arithmetic operations on 2 operands
+of the same scale, specified as the third argument.
+The `llvm.*mul.fix` family of intrinsic functions represents a multiplication
+of fixed point numbers through scaled integers. Therefore, fixed point
+multplication can be represented as
+::
+%result = call i4 @llvm.smul.fix.i4(i4 %a, i4 %b, i32 %scale)
+; Expands to
+%a2 = sext i4 %a to i8
+%b2 = sext i4 %b to i8
+%mul = mul nsw nuw i8 %a, %b
+%scale2 = trunc i32 %scale to i8
+%r = ashr i8 %mul, i8 %scale2  ; this is for a target rounding down towards negative infinity
+%result = trunc i8 %r to i4
+For each of these functions, if the result cannot be represented exactly with
+the provided scale, the result is rounded. Rounding is unspecified since
+preferred rounding may vary for different targets. Rounding is specified
+through a target hook. Different pipelines should legalize or optimize this
+using the rounding specified by this hook if it is provided. Operations like
+constant folding, instruction combining, KnownBits, and ValueTracking should
+also use this hook, if provided, and not assume the direction of rounding. A
+rounded result must always be within one unit of precision from the true
+result. That is, the error between the returned result and the true result must
+be less than 1/2^(scale).
+'``llvm.smul.fix.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.smul.fix``
+on any integer bit width or vectors of integers.
+::
+declare i16 @llvm.smul.fix.i16(i16 %a, i16 %b, i32 %scale)
+declare i32 @llvm.smul.fix.i32(i32 %a, i32 %b, i32 %scale)
+declare i64 @llvm.smul.fix.i64(i64 %a, i64 %b, i32 %scale)
+declare <4 x i32> @llvm.smul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale)
+Overview
+"""""""""
+The '``llvm.smul.fix``' family of intrinsic functions perform signed
+fixed point multiplication on 2 arguments of the same scale.
+Arguments
+""""""""""
+The arguments (%a and %b) and the result may be of integer types of any bit
+width, but they must have the same bit width. The arguments may also work with
+int vectors of the same length and int size. ``%a`` and ``%b`` are the two
+values that will undergo signed fixed point multiplication. The argument
+``%scale`` represents the scale of both operands, and must be a constant
+integer.
+Semantics:
+""""""""""
+This operation performs fixed point multiplication on the 2 arguments of a
+specified scale. The result will also be returned in the same scale specified
+in the third argument.
+If the result value cannot be precisely represented in the given scale, the
+value is rounded up or down to the closest representable value. The rounding
+direction is unspecified.
+It is undefined behavior if the result value does not fit within the range of
+the fixed point type.
+Examples
+"""""""""
+.. code-block:: llvm
+%res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 0)  ; %res = 6 (2 x 3 = 6)
+%res = call i4 @llvm.smul.fix.i4(i4 3, i4 2, i32 1)  ; %res = 3 (1.5 x 1 = 1.5)
+%res = call i4 @llvm.smul.fix.i4(i4 3, i4 -2, i32 1)  ; %res = -3 (1.5 x -1 = -1.5)
+; The result in the following could be rounded up to -2 or down to -2.5
+%res = call i4 @llvm.smul.fix.i4(i4 3, i4 -3, i32 1)  ; %res = -5 (or -4) (1.5 x -1.5 = -2.25)
+'``llvm.umul.fix.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.umul.fix``
+on any integer bit width or vectors of integers.
+::
+declare i16 @llvm.umul.fix.i16(i16 %a, i16 %b, i32 %scale)
+declare i32 @llvm.umul.fix.i32(i32 %a, i32 %b, i32 %scale)
+declare i64 @llvm.umul.fix.i64(i64 %a, i64 %b, i32 %scale)
+declare <4 x i32> @llvm.umul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale)
+Overview
+"""""""""
+The '``llvm.umul.fix``' family of intrinsic functions perform unsigned
+fixed point multiplication on 2 arguments of the same scale.
+Arguments
+""""""""""
+The arguments (%a and %b) and the result may be of integer types of any bit
+width, but they must have the same bit width. The arguments may also work with
+int vectors of the same length and int size. ``%a`` and ``%b`` are the two
+values that will undergo unsigned fixed point multiplication. The argument
+``%scale`` represents the scale of both operands, and must be a constant
+integer.
+Semantics:
+""""""""""
+This operation performs unsigned fixed point multiplication on the 2 arguments of a
+specified scale. The result will also be returned in the same scale specified
+in the third argument.
+If the result value cannot be precisely represented in the given scale, the
+value is rounded up or down to the closest representable value. The rounding
+direction is unspecified.
+It is undefined behavior if the result value does not fit within the range of
+the fixed point type.
+Examples
+"""""""""
+.. code-block:: llvm
+%res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 0)  ; %res = 6 (2 x 3 = 6)
+%res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 1)  ; %res = 3 (1.5 x 1 = 1.5)
+; The result in the following could be rounded down to 3.5 or up to 4
+%res = call i4 @llvm.umul.fix.i4(i4 15, i4 1, i32 1)  ; %res = 7 (or 8) (7.5 x 0.5 = 3.75)
+'``llvm.smul.fix.sat.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax
+"""""""
+This is an overloaded intrinsic. You can use ``llvm.smul.fix.sat``
+on any integer bit width or vectors of integers.
+::
+declare i16 @llvm.smul.fix.sat.i16(i16 %a, i16 %b, i32 %scale)
+declare i32 @llvm.smul.fix.sat.i32(i32 %a, i32 %b, i32 %scale)
+declare i64 @llvm.smul.fix.sat.i64(i64 %a, i64 %b, i32 %scale)
+declare <4 x i32> @llvm.smul.fix.sat.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale)
+Overview
+"""""""""
+The '``llvm.smul.fix.sat``' family of intrinsic functions perform signed
+fixed point saturation multiplication on 2 arguments of the same scale.
+Arguments
+""""""""""
+The arguments (%a and %b) and the result may be of integer types of any bit
+width, but they must have the same bit width. ``%a`` and ``%b`` are the two
+values that will undergo signed fixed point multiplication. The argument
+``%scale`` represents the scale of both operands, and must be a constant
+integer.
+Semantics:
+""""""""""
+This operation performs fixed point multiplication on the 2 arguments of a
+specified scale. The result will also be returned in the same scale specified
+in the third argument.
+If the result value cannot be precisely represented in the given scale, the
+value is rounded up or down to the closest representable value. The rounding
+direction is unspecified.
+The maximum value this operation can clamp to is the largest signed value
+representable by the bit width of the first 2 arguments. The minimum value is the
+smallest signed value representable by this bit width.
+Examples
+"""""""""
+.. code-block:: llvm
+%res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 2, i32 0)  ; %res = 6 (2 x 3 = 6)
+%res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 2, i32 1)  ; %res = 3 (1.5 x 1 = 1.5)
+%res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 -2, i32 1)  ; %res = -3 (1.5 x -1 = -1.5)
+; The result in the following could be rounded up to -2 or down to -2.5
+%res = call i4 @llvm.smul.fix.sat.i4(i4 3, i4 -3, i32 1)  ; %res = -5 (or -4) (1.5 x -1.5 = -2.25)
+; Saturation
+%res = call i4 @llvm.smul.fix.sat.i4(i4 7, i4 2, i32 0)  ; %res = 7
+%res = call i4 @llvm.smul.fix.sat.i4(i4 7, i4 2, i32 2)  ; %res = 7
+%res = call i4 @llvm.smul.fix.sat.i4(i4 -8, i4 2, i32 2)  ; %res = -8
+%res = call i4 @llvm.smul.fix.sat.i4(i4 -8, i4 -2, i32 2)  ; %res = 7
+; Scale can affect the saturation result
+%res = call i4 @llvm.smul.fix.sat.i4(i4 2, i4 4, i32 0)  ; %res = 7 (2 x 4 -> clamped to 7)
+%res = call i4 @llvm.smul.fix.sat.i4(i4 2, i4 4, i32 1)  ; %res = 4 (1 x 2 = 2)
 Specialised Arithmetic Intrinsics
 ---------------------------------
 '``llvm.canonicalize.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Overview:
 """""""""
 The '``llvm.canonicalize.*``' intrinsic returns the platform specific canonical
-encoding of a floating point number. This canonicalization is useful for
+encoding of a floating-point number. This canonicalization is useful for
 implementing certain numeric primitives such as frexp. The canonical encoding is
 defined by IEEE-754-2008 to be:
 ::
 Examples of non-canonical encodings:
 - x87 pseudo denormals, pseudo NaNs, pseudo Infinity, Unnormals. These are
 converted to a canonical representation per hardware-specific protocol.
-- Many normal decimal floating point numbers have non-canonical alternative
+- Many normal decimal floating-point numbers have non-canonical alternative
 encodings.
 - Some machines, like GPUs or ARMv7 NEON, do not support subnormal values.
 These are treated as non-canonical encodings of zero and will be flushed to
 a zero of the same sign by this operation.
 The canonicalization operation may be optimized away if:
 - The input is known to be canonical. For example, it was produced by a
 floating-point operation that is required by the standard to be canonical.
 - The result is consumed only by (or fused with) other floating-point
-operations. That is, the bits of the floating point value are not examined.
+operations. That is, the bits of the floating-point value are not examined.
 '``llvm.fmuladd.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.add.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.add.v4i32(<4 x i32> %a)
-declare i64 @llvm.experimental.vector.reduce.add.i64.v2i64(<2 x i64> %a)
+declare i64 @llvm.experimental.vector.reduce.add.v2i64(<2 x i64> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.add.*``' intrinsics do an integer ``ADD``
 Arguments:
 """"""""""
 The argument to this intrinsic must be a vector of integer values.
-'``llvm.experimental.vector.reduce.fadd.*``' Intrinsic
+'``llvm.experimental.vector.reduce.v2.fadd.*``' Intrinsic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 ::
-declare float @llvm.experimental.vector.reduce.fadd.f32.v4f32(float %acc, <4 x float> %a)
+declare float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float %start_value, <4 x float> %a)
-declare double @llvm.experimental.vector.reduce.fadd.f64.v2f64(double %acc, <2 x double> %a)
+declare double @llvm.experimental.vector.reduce.v2.fadd.f64.v2f64(double %start_value, <2 x double> %a)
 Overview:
 """""""""
-The '``llvm.experimental.vector.reduce.fadd.*``' intrinsics do a floating point
+The '``llvm.experimental.vector.reduce.v2.fadd.*``' intrinsics do a floating-point
 ``ADD`` reduction of a vector, returning the result as a scalar. The return type
 matches the element-type of the vector input.
-If the intrinsic call has fast-math flags, then the reduction will not preserve
+If the intrinsic call has the 'reassoc' or 'fast' flags set, then the
-the associativity of an equivalent scalarized counterpart. If it does not have
+reduction will not preserve the associativity of an equivalent scalarized
-fast-math flags, then the reduction will be *ordered*, implying that the
+counterpart. Otherwise the reduction will be *ordered*, thus implying that
-operation respects the associativity of a scalarized reduction.
+the operation respects the associativity of a scalarized reduction.
 Arguments:
 """"""""""
-The first argument to this intrinsic is a scalar accumulator value, which is
+The first argument to this intrinsic is a scalar start value for the reduction.
-only used when there are no fast-math flags attached. This argument may be undef
+The type of the start value matches the element-type of the vector input.
-when fast-math flags are used.
+The second argument must be a vector of floating-point values.
-The second argument must be a vector of floating point values.
 Examples:
 """""""""
-.. code-block:: llvm
+::
-%fast = call fast float @llvm.experimental.vector.reduce.fadd.f32.v4f32(float undef, <4 x float> %input) ; fast reduction
+%unord = call reassoc float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float 0.0, <4 x float> %input) ; unordered reduction
-%ord = call float @llvm.experimental.vector.reduce.fadd.f32.v4f32(float %acc, <4 x float> %input) ; ordered reduction
+%ord = call float @llvm.experimental.vector.reduce.v2.fadd.f32.v4f32(float %start_value, <4 x float> %input) ; ordered reduction
 '``llvm.experimental.vector.reduce.mul.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.mul.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.mul.v4i32(<4 x i32> %a)
-declare i64 @llvm.experimental.vector.reduce.mul.i64.v2i64(<2 x i64> %a)
+declare i64 @llvm.experimental.vector.reduce.mul.v2i64(<2 x i64> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.mul.*``' intrinsics do an integer ``MUL``
 Arguments:
 """"""""""
 The argument to this intrinsic must be a vector of integer values.
-'``llvm.experimental.vector.reduce.fmul.*``' Intrinsic
+'``llvm.experimental.vector.reduce.v2.fmul.*``' Intrinsic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 ::
-declare float @llvm.experimental.vector.reduce.fmul.f32.v4f32(float %acc, <4 x float> %a)
+declare float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float %start_value, <4 x float> %a)
-declare double @llvm.experimental.vector.reduce.fmul.f64.v2f64(double %acc, <2 x double> %a)
+declare double @llvm.experimental.vector.reduce.v2.fmul.f64.v2f64(double %start_value, <2 x double> %a)
 Overview:
 """""""""
-The '``llvm.experimental.vector.reduce.fmul.*``' intrinsics do a floating point
+The '``llvm.experimental.vector.reduce.v2.fmul.*``' intrinsics do a floating-point
 ``MUL`` reduction of a vector, returning the result as a scalar. The return type
 matches the element-type of the vector input.
-If the intrinsic call has fast-math flags, then the reduction will not preserve
+If the intrinsic call has the 'reassoc' or 'fast' flags set, then the
-the associativity of an equivalent scalarized counterpart. If it does not have
+reduction will not preserve the associativity of an equivalent scalarized
-fast-math flags, then the reduction will be *ordered*, implying that the
+counterpart. Otherwise the reduction will be *ordered*, thus implying that
-operation respects the associativity of a scalarized reduction.
+the operation respects the associativity of a scalarized reduction.
 Arguments:
 """"""""""
-The first argument to this intrinsic is a scalar accumulator value, which is
+The first argument to this intrinsic is a scalar start value for the reduction.
-only used when there are no fast-math flags attached. This argument may be undef
+The type of the start value matches the element-type of the vector input.
-when fast-math flags are used.
+The second argument must be a vector of floating-point values.
-The second argument must be a vector of floating point values.
 Examples:
 """""""""
-.. code-block:: llvm
+::
-%fast = call fast float @llvm.experimental.vector.reduce.fmul.f32.v4f32(float undef, <4 x float> %input) ; fast reduction
+%unord = call reassoc float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float 1.0, <4 x float> %input) ; unordered reduction
-%ord = call float @llvm.experimental.vector.reduce.fmul.f32.v4f32(float %acc, <4 x float> %input) ; ordered reduction
+%ord = call float @llvm.experimental.vector.reduce.v2.fmul.f32.v4f32(float %start_value, <4 x float> %input) ; ordered reduction
 '``llvm.experimental.vector.reduce.and.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.and.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.and.v4i32(<4 x i32> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.and.*``' intrinsics do a bitwise ``AND``
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.or.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.or.v4i32(<4 x i32> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.or.*``' intrinsics do a bitwise ``OR`` reduction
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.xor.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.xor.v4i32(<4 x i32> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.xor.*``' intrinsics do a bitwise ``XOR``
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.smax.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.smax.v4i32(<4 x i32> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.smax.*``' intrinsics do a signed integer
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.smin.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.smin.v4i32(<4 x i32> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.smin.*``' intrinsics do a signed integer
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.umax.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.umax.v4i32(<4 x i32> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.umax.*``' intrinsics do an unsigned
 Syntax:
 """""""
 ::
-declare i32 @llvm.experimental.vector.reduce.umin.i32.v4i32(<4 x i32> %a)
+declare i32 @llvm.experimental.vector.reduce.umin.v4i32(<4 x i32> %a)
 Overview:
 """""""""
 The '``llvm.experimental.vector.reduce.umin.*``' intrinsics do an unsigned
 Syntax:
 """""""
 ::
-declare float @llvm.experimental.vector.reduce.fmax.f32.v4f32(<4 x float> %a)
+declare float @llvm.experimental.vector.reduce.fmax.v4f32(<4 x float> %a)
-declare double @llvm.experimental.vector.reduce.fmax.f64.v2f64(<2 x double> %a)
+declare double @llvm.experimental.vector.reduce.fmax.v2f64(<2 x double> %a)
 Overview:
 """""""""
-The '``llvm.experimental.vector.reduce.fmax.*``' intrinsics do a floating point
+The '``llvm.experimental.vector.reduce.fmax.*``' intrinsics do a floating-point
 ``MAX`` reduction of a vector, returning the result as a scalar. The return type
 matches the element-type of the vector input.
 If the intrinsic call has the ``nnan`` fast-math flag then the operation can
 assume that NaNs are not present in the input vector.
 Arguments:
 """"""""""
-The argument to this intrinsic must be a vector of floating point values.
+The argument to this intrinsic must be a vector of floating-point values.
 '``llvm.experimental.vector.reduce.fmin.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 ::
-declare float @llvm.experimental.vector.reduce.fmin.f32.v4f32(<4 x float> %a)
+declare float @llvm.experimental.vector.reduce.fmin.v4f32(<4 x float> %a)
-declare double @llvm.experimental.vector.reduce.fmin.f64.v2f64(<2 x double> %a)
+declare double @llvm.experimental.vector.reduce.fmin.v2f64(<2 x double> %a)
 Overview:
 """""""""
-The '``llvm.experimental.vector.reduce.fmin.*``' intrinsics do a floating point
+The '``llvm.experimental.vector.reduce.fmin.*``' intrinsics do a floating-point
 ``MIN`` reduction of a vector, returning the result as a scalar. The return type
 matches the element-type of the vector input.
 If the intrinsic call has the ``nnan`` fast-math flag then the operation can
 assume that NaNs are not present in the input vector.
 Arguments:
 """"""""""
-The argument to this intrinsic must be a vector of floating point values.
+The argument to this intrinsic must be a vector of floating-point values.
-Half Precision Floating Point Intrinsics
+Half Precision Floating-Point Intrinsics
 ----------------------------------------
-For most target platforms, half precision floating point is a
+For most target platforms, half precision floating-point is a
 storage-only format. This means that it is a dense encoding (in memory)
 but does not support computation in the format.
-This means that code must first load the half-precision floating point
+This means that code must first load the half-precision floating-point
 value as an i16, then convert it to float with
 :ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. Computation can
 then be performed on the float value (including extending to double
 etc). To store the value back to memory, it is first converted to float
 if needed, then converted to i16 with
 Overview:
 """""""""
 The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a
-conventional floating point type to half precision floating point format.
+conventional floating-point type to half precision floating-point format.
 Arguments:
 """"""""""
 The intrinsic function contains single argument - the value to be
 Semantics:
 """"""""""
 The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a
-conventional floating point format to half precision floating point format. The
+conventional floating-point format to half precision floating-point format. The
 return value is an ``i16`` which contains the converted number.
 Examples:
 """""""""
 Overview:
 """""""""
 The '``llvm.convert.from.fp16``' intrinsic function performs a
-conversion from half precision floating point format to single precision
+conversion from half precision floating-point format to single precision
-floating point format.
+floating-point format.
 Arguments:
 """"""""""
 The intrinsic function contains single argument - the value to be
 Semantics:
 """"""""""
 The '``llvm.convert.from.fp16``' intrinsic function performs a
-conversion from half single precision floating point format to single
+conversion from half single precision floating-point format to single
-precision floating point format. The input half-float value is
+precision floating-point format. The input half-float value is
 represented by an ``i16`` value.
 Examples:
 """""""""
 '``llvm.masked.load.*``' Intrinsics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
-This is an overloaded intrinsic. The loaded data is a vector of any integer, floating point or pointer data type.
+This is an overloaded intrinsic. The loaded data is a vector of any integer, floating-point or pointer data type.
 ::
 declare <16 x float>  @llvm.masked.load.v16f32.p0v16f32 (<16 x float>* <ptr>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>)
 declare <2 x double>  @llvm.masked.load.v2f64.p0v2f64  (<2 x double>* <ptr>, i32 <alignment>, <2 x i1>  <mask>, <2 x double> <passthru>)
 '``llvm.masked.store.*``' Intrinsics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
-This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating point or pointer data type.
+This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating-point or pointer data type.
 ::
 declare void @llvm.masked.store.v8i32.p0v8i32  (<8  x i32>   <value>, <8  x i32>*   <ptr>, i32 <alignment>,  <8  x i1> <mask>)
 declare void @llvm.masked.store.v16f32.p0v16f32 (<16 x float> <value>, <16 x float>* <ptr>, i32 <alignment>,  <16 x i1> <mask>)
 '``llvm.masked.gather.*``' Intrinsics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
-This is an overloaded intrinsic. The loaded data are multiple scalar values of any integer, floating point or pointer data type gathered together into one vector.
+This is an overloaded intrinsic. The loaded data are multiple scalar values of any integer, floating-point or pointer data type gathered together into one vector.
 ::
 declare <16 x float> @llvm.masked.gather.v16f32.v16p0f32   (<16 x float*> <ptrs>, i32 <alignment>, <16 x i1> <mask>, <16 x float> <passthru>)
 declare <2 x double> @llvm.masked.gather.v2f64.v2p1f64     (<2 x double addrspace(1)*> <ptrs>, i32 <alignment>, <2 x i1>  <mask>, <2 x double> <passthru>)
 '``llvm.masked.scatter.*``' Intrinsics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
-This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating point or pointer data type. Each vector element is stored in an arbitrary memory address. Scatter with overlapping addresses is guaranteed to be ordered from least-significant to most-significant element.
+This is an overloaded intrinsic. The data stored in memory is a vector of any integer, floating-point or pointer data type. Each vector element is stored in an arbitrary memory address. Scatter with overlapping addresses is guaranteed to be ordered from least-significant to most-significant element.
 ::
 declare void @llvm.masked.scatter.v8i32.v8p0i32     (<8 x i32>     <value>, <8 x i32*>     <ptrs>, i32 <alignment>, <8 x i1>  <mask>)
 declare void @llvm.masked.scatter.v16f32.v16p1f32   (<16 x float>  <value>, <16 x float addrspace(1)*>  <ptrs>, i32 <alignment>, <16 x i1> <mask>)
 store i32 %val1, i32* %ptr1, align 4
 ..
 store i32 %val7, i32* %ptr7, align 4
+Masked Vector Expanding Load and Compressing Store Intrinsics
+-------------------------------------------------------------
+LLVM provides intrinsics for expanding load and compressing store operations. Data selected from a vector according to a mask is stored in consecutive memory addresses (compressed store), and vice-versa (expanding load). These operations effective map to "if (cond.i) a[j++] = v.i" and "if (cond.i) v.i = a[j++]" patterns, respectively. Note that when the mask starts with '1' bits followed by '0' bits, these operations are identical to :ref:`llvm.masked.store <int_mstore>` and :ref:`llvm.masked.load <int_mload>`.
+.. _int_expandload:
+'``llvm.masked.expandload.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. Several values of integer, floating point or pointer data type are loaded from consecutive memory addresses and stored into the elements of a vector according to the mask.
+::
+declare <16 x float>  @llvm.masked.expandload.v16f32 (float* <ptr>, <16 x i1> <mask>, <16 x float> <passthru>)
+declare <2 x i64>     @llvm.masked.expandload.v2i64 (i64* <ptr>, <2 x i1>  <mask>, <2 x i64> <passthru>)
+Overview:
+"""""""""
+Reads a number of scalar values sequentially from memory location provided in '``ptr``' and spreads them in a vector. The '``mask``' holds a bit for each vector lane. The number of elements read from memory is equal to the number of '1' bits in the mask. The loaded elements are positioned in the destination vector according to the sequence of '1' and '0' bits in the mask. E.g., if the mask vector is '10010001', "explandload" reads 3 values from memory addresses ptr, ptr+1, ptr+2 and places them in lanes 0, 3 and 7 accordingly. The masked-off lanes are filled by elements from the corresponding lanes of the '``passthru``' operand.
+Arguments:
+""""""""""
+The first operand is the base pointer for the load. It has the same underlying type as the element of the returned vector. The second operand, mask, is a vector of boolean values with the same number of elements as the return type. The third is a pass-through value that is used to fill the masked-off lanes of the result. The return type and the type of the '``passthru``' operand have the same vector type.
+Semantics:
+""""""""""
+The '``llvm.masked.expandload``' intrinsic is designed for reading multiple scalar values from adjacent memory addresses into possibly non-adjacent vector lanes. It is useful for targets that support vector expanding loads and allows vectorizing loop with cross-iteration dependency like in the following example:
+.. code-block:: c
+// In this loop we load from B and spread the elements into array A.
+double *A, B; int *C;
+for (int i = 0; i < size; ++i) {
+if (C[i] != 0)
+A[i] = B[j++];
+}
+.. code-block:: llvm
+; Load several elements from array B and expand them in a vector.
+; The number of loaded elements is equal to the number of '1' elements in the Mask.
+%Tmp = call <8 x double> @llvm.masked.expandload.v8f64(double* %Bptr, <8 x i1> %Mask, <8 x double> undef)
+; Store the result in A
+call void @llvm.masked.store.v8f64.p0v8f64(<8 x double> %Tmp, <8 x double>* %Aptr, i32 8, <8 x i1> %Mask)
+; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask.
+%MaskI = bitcast <8 x i1> %Mask to i8
+%MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI)
+%MaskI64 = zext i8 %MaskIPopcnt to i64
+%BNextInd = add i64 %BInd, %MaskI64
+Other targets may support this intrinsic differently, for example, by lowering it into a sequence of conditional scalar load operations and shuffles.
+If all mask elements are '1', the intrinsic behavior is equivalent to the regular unmasked vector load.
+.. _int_compressstore:
+'``llvm.masked.compressstore.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. A number of scalar values of integer, floating point or pointer data type are collected from an input vector and stored into adjacent memory addresses. A mask defines which elements to collect from the vector.
+::
+declare void @llvm.masked.compressstore.v8i32  (<8  x i32>   <value>, i32*   <ptr>, <8  x i1> <mask>)
+declare void @llvm.masked.compressstore.v16f32 (<16 x float> <value>, float* <ptr>, <16 x i1> <mask>)
+Overview:
+"""""""""
+Selects elements from input vector '``value``' according to the '``mask``'. All selected elements are written into adjacent memory addresses starting at address '`ptr`', from lower to higher. The mask holds a bit for each vector lane, and is used to select elements to be stored. The number of elements to be stored is equal to the number of active bits in the mask.
+Arguments:
+""""""""""
+The first operand is the input vector, from which elements are collected and written to memory. The second operand is the base pointer for the store, it has the same underlying type as the element of the input vector operand. The third operand is the mask, a vector of boolean values. The mask and the input vector must have the same number of vector elements.
+Semantics:
+""""""""""
+The '``llvm.masked.compressstore``' intrinsic is designed for compressing data in memory. It allows to collect elements from possibly non-adjacent lanes of a vector and store them contiguously in memory in one IR operation. It is useful for targets that support compressing store operations and allows vectorizing loops with cross-iteration dependences like in the following example:
+.. code-block:: c
+// In this loop we load elements from A and store them consecutively in B
+double *A, B; int *C;
+for (int i = 0; i < size; ++i) {
+if (C[i] != 0)
+B[j++] = A[i]
+}
+.. code-block:: llvm
+; Load elements from A.
+%Tmp = call <8 x double> @llvm.masked.load.v8f64.p0v8f64(<8 x double>* %Aptr, i32 8, <8 x i1> %Mask, <8 x double> undef)
+; Store all selected elements consecutively in array B
+call <void> @llvm.masked.compressstore.v8f64(<8 x double> %Tmp, double* %Bptr, <8 x i1> %Mask)
+; %Bptr should be increased on each iteration according to the number of '1' elements in the Mask.
+%MaskI = bitcast <8 x i1> %Mask to i8
+%MaskIPopcnt = call i8 @llvm.ctpop.i8(i8 %MaskI)
+%MaskI64 = zext i8 %MaskIPopcnt to i64
+%BNextInd = add i64 %BInd, %MaskI64
+Other targets may support this intrinsic differently, for example, by lowering it into a sequence of branches that guard scalar store operations.
 Memory Use Markers
 ------------------
 This class of intrinsics provides information about the lifetime of
 memory objects and ranges where variables are immutable.
 Semantics:
 """"""""""
 This intrinsic indicates that the memory is mutable again.
-'``llvm.invariant.group.barrier``' Intrinsic
+'``llvm.launder.invariant.group``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 This is an overloaded intrinsic. The memory object can belong to any address
 space. The returned pointer must belong to the same address space as the
 argument.
 ::
-declare i8* @llvm.invariant.group.barrier.p0i8(i8* <ptr>)
+declare i8* @llvm.launder.invariant.group.p0i8(i8* <ptr>)
 Overview:
 """""""""
-The '``llvm.invariant.group.barrier``' intrinsic can be used when an invariant
+The '``llvm.launder.invariant.group``' intrinsic can be used when an invariant
-established by invariant.group metadata no longer holds, to obtain a new pointer
+established by ``invariant.group`` metadata no longer holds, to obtain a new
-value that does not carry the invariant information.
+pointer value that carries fresh invariant group information. It is an
+experimental intrinsic, which means that its semantics might change in the
+future.
-Arguments:
-""""""""""
+Arguments:
-The ``llvm.invariant.group.barrier`` takes only one argument, which is
+""""""""""
-the pointer to the memory for which the ``invariant.group`` no longer holds.
+The ``llvm.launder.invariant.group`` takes only one argument, which is a pointer
+to the memory.
 Semantics:
 """"""""""
 Returns another pointer that aliases its argument but which is considered different
 for the purposes of ``load``/``store`` ``invariant.group`` metadata.
+It does not read any accessible memory and the execution can be speculated.
-Constrained Floating Point Intrinsics
+'``llvm.strip.invariant.group``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. The memory object can belong to any address
+space. The returned pointer must belong to the same address space as the
+argument.
+::
+declare i8* @llvm.strip.invariant.group.p0i8(i8* <ptr>)
+Overview:
+"""""""""
+The '``llvm.strip.invariant.group``' intrinsic can be used when an invariant
+established by ``invariant.group`` metadata no longer holds, to obtain a new pointer
+value that does not carry the invariant information. It is an experimental
+intrinsic, which means that its semantics might change in the future.
+Arguments:
+""""""""""
+The ``llvm.strip.invariant.group`` takes only one argument, which is a pointer
+to the memory.
+Semantics:
+""""""""""
+Returns another pointer that aliases its argument but which has no associated
+``invariant.group`` metadata.
+It does not read any memory and can be speculated.
+.. _constrainedfp:
+Constrained Floating-Point Intrinsics
 -------------------------------------
-These intrinsics are used to provide special handling of floating point
+These intrinsics are used to provide special handling of floating-point
-operations when specific rounding mode or floating point exception behavior is
+operations when specific rounding mode or floating-point exception behavior is
 required.  By default, LLVM optimization passes assume that the rounding mode is
-round-to-nearest and that floating point exceptions will not be monitored.
+round-to-nearest and that floating-point exceptions will not be monitored.
 Constrained FP intrinsics are used to support non-default rounding modes and
 accurately preserve exception behavior without compromising LLVM's ability to
 optimize FP code when the default behavior is used.
-Each of these intrinsics corresponds to a normal floating point operation.  The
+Each of these intrinsics corresponds to a normal floating-point operation.  The
 first two arguments and the return value are the same as the corresponding FP
 operation.
 The third argument is a metadata argument specifying the rounding mode to be
 assumed. This argument must be one of the following strings:
 actual runtime rounding mode (as defined in a target-specific manner) matches
 the specified rounding mode, but this is not guaranteed.  Using a specific
 non-dynamic rounding mode which does not match the actual rounding mode at
 runtime results in undefined behavior.
-The fourth argument to the constrained floating point intrinsics specifies the
+The fourth argument to the constrained floating-point intrinsics specifies the
 required exception behavior.  This argument must be one of the following
 strings:
 ::
 "fpexcept.ignore"
 "fpexcept.maytrap"
 "fpexcept.strict"
 If this argument is "fpexcept.ignore" optimization passes may assume that the
-exception status flags will not be read and that floating point exceptions will
+exception status flags will not be read and that floating-point exceptions will
 be masked.  This allows transformations to be performed that may change the
 exception semantics of the original code.  For example, FP operations may be
 speculatively executed in this case whereas they must not be for either of the
 other possible values of this argument.
 passes are not required to preserve all exceptions that are implied by the
 original code.  For example, exceptions may be potentially hidden by constant
 folding.
 If the exception behavior argument is "fpexcept.strict" all transformations must
-strictly preserve the floating point exception semantics of the original code.
+strictly preserve the floating-point exception semantics of the original code.
 Any FP exception that would have been raised by the original code must be raised
 by the transformed code, and the transformed code must not raise any FP
 exceptions that would not have been raised by the original code.  This is the
 exception behavior argument that will be used if the code being compiled reads
 the FP exception status flags, but this mode can also be used with code that
 unmasks FP exceptions.
-The number and order of floating point exceptions is NOT guaranteed.  For
+The number and order of floating-point exceptions is NOT guaranteed.  For
 example, a series of FP operations that each may raise exceptions may be
 vectorized into a single instruction that raises each unique exception a single
 time.
 Arguments:
 """"""""""
 The first two arguments to the '``llvm.experimental.constrained.fadd``'
-intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>`
+intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
-of floating point values. Both arguments must have identical types.
+of floating-point values. Both arguments must have identical types.
 The third and fourth arguments specify the rounding mode and exception
 behavior as described above.
 Semantics:
 """"""""""
-The value produced is the floating point sum of the two value operands and has
+The value produced is the floating-point sum of the two value operands and has
 the same type as the operands.
 '``llvm.experimental.constrained.fsub``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Arguments:
 """"""""""
 The first two arguments to the '``llvm.experimental.constrained.fsub``'
-intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>`
+intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
-of floating point values. Both arguments must have identical types.
+of floating-point values. Both arguments must have identical types.
 The third and fourth arguments specify the rounding mode and exception
 behavior as described above.
 Semantics:
 """"""""""
-The value produced is the floating point difference of the two value operands
+The value produced is the floating-point difference of the two value operands
 and has the same type as the operands.
 '``llvm.experimental.constrained.fmul``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Arguments:
 """"""""""
 The first two arguments to the '``llvm.experimental.constrained.fmul``'
-intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>`
+intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
-of floating point values. Both arguments must have identical types.
+of floating-point values. Both arguments must have identical types.
 The third and fourth arguments specify the rounding mode and exception
 behavior as described above.
 Semantics:
 """"""""""
-The value produced is the floating point product of the two value operands and
+The value produced is the floating-point product of the two value operands and
 has the same type as the operands.
 '``llvm.experimental.constrained.fdiv``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Arguments:
 """"""""""
 The first two arguments to the '``llvm.experimental.constrained.fdiv``'
-intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>`
+intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
-of floating point values. Both arguments must have identical types.
+of floating-point values. Both arguments must have identical types.
 The third and fourth arguments specify the rounding mode and exception
 behavior as described above.
 Semantics:
 """"""""""
-The value produced is the floating point quotient of the two value operands and
+The value produced is the floating-point quotient of the two value operands and
 has the same type as the operands.
 '``llvm.experimental.constrained.frem``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Arguments:
 """"""""""
 The first two arguments to the '``llvm.experimental.constrained.frem``'
-intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector <t_vector>`
+intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector <t_vector>`
-of floating point values. Both arguments must have identical types.
+of floating-point values. Both arguments must have identical types.
 The third and fourth arguments specify the rounding mode and exception
 behavior as described above.  The rounding mode argument has no effect, since
 the result of frem is never rounded, but the argument is included for
-consistency with the other constrained floating point intrinsics.
+consistency with the other constrained floating-point intrinsics.
 Semantics:
 """"""""""
-The value produced is the floating point remainder from the division of the two
+The value produced is the floating-point remainder from the division of the two
 value operands and has the same type as the operands.  The remainder has the
 same sign as the dividend.
 '``llvm.experimental.constrained.fma``' Intrinsic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 ::
 Arguments:
 """"""""""
 The first three arguments to the '``llvm.experimental.constrained.fma``'
-intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector
+intrinsic must be :ref:`floating-point <t_floating>` or :ref:`vector
-<t_vector>` of floating point values. All arguments must have identical types.
+<t_vector>` of floating-point values. All arguments must have identical types.
 The fourth and fifth arguments specify the rounding mode and exception behavior
 as described above.
 Semantics:
 The result produced is the product of the first two operands added to the third
 operand computed with infinite precision, and then rounded to the target
 precision.
+'``llvm.experimental.constrained.fptrunc``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <ty2>
+@llvm.experimental.constrained.fptrunc(<type> <value>,
+metadata <rounding mode>,
+metadata <exception behavior>)
+Overview:
+"""""""""
+The '``llvm.experimental.constrained.fptrunc``' intrinsic truncates ``value``
+to type ``ty2``.
+Arguments:
+""""""""""
+The first argument to the '``llvm.experimental.constrained.fptrunc``'
+intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector
+<t_vector>` of floating point values. This argument must be larger in size
+than the result.
+The second and third arguments specify the rounding mode and exception
+behavior as described above.
+Semantics:
+""""""""""
+The result produced is a floating point value truncated to be smaller in size
+than the operand.
+'``llvm.experimental.constrained.fpext``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <ty2>
+@llvm.experimental.constrained.fpext(<type> <value>,
+metadata <exception behavior>)
+Overview:
+"""""""""
+The '``llvm.experimental.constrained.fpext``' intrinsic extends a
+floating-point ``value`` to a larger floating-point value.
+Arguments:
+""""""""""
+The first argument to the '``llvm.experimental.constrained.fpext``'
+intrinsic must be :ref:`floating point <t_floating>` or :ref:`vector
+<t_vector>` of floating point values. This argument must be smaller in size
+than the result.
+The second argument specifies the exception behavior as described above.
+Semantics:
+""""""""""
+The result produced is a floating point value extended to be larger in size
+than the operand. All restrictions that apply to the fpext instruction also
+apply to this intrinsic.
 Constrained libm-equivalent Intrinsics
 --------------------------------------
-In addition to the basic floating point operations for which constrained
+In addition to the basic floating-point operations for which constrained
 intrinsics are described above, there are constrained versions of various
 operations which provide equivalent behavior to a corresponding libm function.
 These intrinsics allow the precise behavior of these operations with respect to
 rounding mode and exception behavior to be controlled.
-As with the basic constrained floating point intrinsics, the rounding mode
+As with the basic constrained floating-point intrinsics, the rounding mode
 and exception behavior arguments only control the behavior of the optimizer.
-They do not change the runtime floating point environment.
+They do not change the runtime floating-point environment.
 '``llvm.experimental.constrained.sqrt``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 functions would, but without setting ``errno``.
 Arguments:
 """"""""""
-The first argument and the return type are floating point numbers of the same
+The first argument and the return type are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 Semantics:
 """"""""""
 This function returns the nonnegative square root of the specified value.
-If the value is less than negative zero, a floating point exception occurs
+If the value is less than negative zero, a floating-point exception occurs
 and the return value is architecture specific.
 '``llvm.experimental.constrained.pow``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 raised to the (positive or negative) power specified by the second operand.
 Arguments:
 """"""""""
-The first two arguments and the return value are floating point numbers of the
+The first two arguments and the return value are floating-point numbers of the
 same type.  The second argument specifies the power to which the first argument
 should be raised.
 The third and fourth arguments specify the rounding mode and exception
 behavior as described above.
 Overview:
 """""""""
 The '``llvm.experimental.constrained.powi``' intrinsic returns the first operand
 raised to the (positive or negative) power specified by the second operand. The
-order of evaluation of multiplications is not defined. When a vector of floating
+order of evaluation of multiplications is not defined. When a vector of
-point type is used, the second argument remains a scalar integer value.
+floating-point type is used, the second argument remains a scalar integer value.
 Arguments:
 """"""""""
-The first argument and the return value are floating point numbers of the same
+The first argument and the return value are floating-point numbers of the same
 type.  The second argument is a 32-bit signed integer specifying the power to
 which the first argument should be raised.
 The third and fourth arguments specify the rounding mode and exception
 behavior as described above.
 first operand.
 Arguments:
 """"""""""
-The first argument and the return type are floating point numbers of the same
+The first argument and the return type are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 first operand.
 Arguments:
 """"""""""
-The first argument and the return type are floating point numbers of the same
+The first argument and the return type are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 exponential of the specified value.
 Arguments:
 """"""""""
-The first argument and the return value are floating point numbers of the same
+The first argument and the return value are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 Arguments:
 """"""""""
-The first argument and the return value are floating point numbers of the same
+The first argument and the return value are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 logarithm of the specified value.
 Arguments:
 """"""""""
-The first argument and the return value are floating point numbers of the same
+The first argument and the return value are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 logarithm of the specified value.
 Arguments:
 """"""""""
-The first argument and the return value are floating point numbers of the same
+The first argument and the return value are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 logarithm of the specified value.
 Arguments:
 """"""""""
-The first argument and the return value are floating point numbers of the same
+The first argument and the return value are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 Overview:
 """""""""
 The '``llvm.experimental.constrained.rint``' intrinsic returns the first
-operand rounded to the nearest integer. It may raise an inexact floating point
+operand rounded to the nearest integer. It may raise an inexact floating-point
 exception if the operand is not an integer.
 Arguments:
 """"""""""
-The first argument and the return value are floating point numbers of the same
+The first argument and the return value are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 """"""""""
 This function returns the same values as the libm ``rint`` functions
 would, and handles error conditions in the same way.  The rounding mode is
 described, not determined, by the rounding mode argument.  The actual rounding
-mode is determined by the runtime floating point environment.  The rounding
+mode is determined by the runtime floating-point environment.  The rounding
 mode argument is only intended as information to the compiler.
 '``llvm.experimental.constrained.nearbyint``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Overview:
 """""""""
 The '``llvm.experimental.constrained.nearbyint``' intrinsic returns the first
-operand rounded to the nearest integer. It will not raise an inexact floating
+operand rounded to the nearest integer. It will not raise an inexact
-point exception if the operand is not an integer.
+floating-point exception if the operand is not an integer.
 Arguments:
 """"""""""
-The first argument and the return value are floating point numbers of the same
+The first argument and the return value are floating-point numbers of the same
 type.
 The second and third arguments specify the rounding mode and exception
 behavior as described above.
 """"""""""
 This function returns the same values as the libm ``nearbyint`` functions
 would, and handles error conditions in the same way.  The rounding mode is
 described, not determined, by the rounding mode argument.  The actual rounding
-mode is determined by the runtime floating point environment.  The rounding
+mode is determined by the runtime floating-point environment.  The rounding
 mode argument is only intended as information to the compiler.
+'``llvm.experimental.constrained.maxnum``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <type>
+@llvm.experimental.constrained.maxnum(<type> <op1>, <type> <op2>
+metadata <rounding mode>,
+metadata <exception behavior>)
+Overview:
+"""""""""
+The '``llvm.experimental.constrained.maxnum``' intrinsic returns the maximum
+of the two arguments.
+Arguments:
+""""""""""
+The first two arguments and the return value are floating-point numbers
+of the same type.
+The third and forth arguments specify the rounding mode and exception
+behavior as described above.
+Semantics:
+""""""""""
+This function follows the IEEE-754 semantics for maxNum. The rounding mode is
+described, not determined, by the rounding mode argument. The actual rounding
+mode is determined by the runtime floating-point environment. The rounding
+mode argument is only intended as information to the compiler.
+'``llvm.experimental.constrained.minnum``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <type>
+@llvm.experimental.constrained.minnum(<type> <op1>, <type> <op2>
+metadata <rounding mode>,
+metadata <exception behavior>)
+Overview:
+"""""""""
+The '``llvm.experimental.constrained.minnum``' intrinsic returns the minimum
+of the two arguments.
+Arguments:
+""""""""""
+The first two arguments and the return value are floating-point numbers
+of the same type.
+The third and forth arguments specify the rounding mode and exception
+behavior as described above.
+Semantics:
+""""""""""
+This function follows the IEEE-754 semantics for minNum. The rounding mode is
+described, not determined, by the rounding mode argument. The actual rounding
+mode is determined by the runtime floating-point environment. The rounding
+mode argument is only intended as information to the compiler.
+'``llvm.experimental.constrained.ceil``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <type>
+@llvm.experimental.constrained.ceil(<type> <op1>,
+metadata <rounding mode>,
+metadata <exception behavior>)
+Overview:
+"""""""""
+The '``llvm.experimental.constrained.ceil``' intrinsic returns the ceiling of the
+first operand.
+Arguments:
+""""""""""
+The first argument and the return value are floating-point numbers of the same
+type.
+The second and third arguments specify the rounding mode and exception
+behavior as described above. The rounding mode is currently unused for this
+intrinsic.
+Semantics:
+""""""""""
+This function returns the same values as the libm ``ceil`` functions
+would and handles error conditions in the same way.
+'``llvm.experimental.constrained.floor``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <type>
+@llvm.experimental.constrained.floor(<type> <op1>,
+metadata <rounding mode>,
+metadata <exception behavior>)
+Overview:
+"""""""""
+The '``llvm.experimental.constrained.floor``' intrinsic returns the floor of the
+first operand.
+Arguments:
+""""""""""
+The first argument and the return value are floating-point numbers of the same
+type.
+The second and third arguments specify the rounding mode and exception
+behavior as described above. The rounding mode is currently unused for this
+intrinsic.
+Semantics:
+""""""""""
+This function returns the same values as the libm ``floor`` functions
+would and handles error conditions in the same way.
+'``llvm.experimental.constrained.round``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <type>
+@llvm.experimental.constrained.round(<type> <op1>,
+metadata <rounding mode>,
+metadata <exception behavior>)
+Overview:
+"""""""""
+The '``llvm.experimental.constrained.round``' intrinsic returns the first
+operand rounded to the nearest integer.
+Arguments:
+""""""""""
+The first argument and the return value are floating-point numbers of the same
+type.
+The second and third arguments specify the rounding mode and exception
+behavior as described above. The rounding mode is currently unused for this
+intrinsic.
+Semantics:
+""""""""""
+This function returns the same values as the libm ``round`` functions
+would and handles error conditions in the same way.
+'``llvm.experimental.constrained.trunc``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <type>
+@llvm.experimental.constrained.trunc(<type> <op1>,
+metadata <truncing mode>,
+metadata <exception behavior>)
+Overview:
+"""""""""
+The '``llvm.experimental.constrained.trunc``' intrinsic returns the first
+operand rounded to the nearest integer not larger in magnitude than the
+operand.
+Arguments:
+""""""""""
+The first argument and the return value are floating-point numbers of the same
+type.
+The second and third arguments specify the truncing mode and exception
+behavior as described above. The truncing mode is currently unused for this
+intrinsic.
+Semantics:
+""""""""""
+This function returns the same values as the libm ``trunc`` functions
+would and handles error conditions in the same way.
 General Intrinsics
 ------------------
 Syntax:
 """""""
 ::
-declare void @llvm.trap() noreturn nounwind
+declare void @llvm.trap() cold noreturn nounwind
 Overview:
 """""""""
 The '``llvm.trap``' intrinsic.
 Syntax:
 """""""
 ::
-declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>, i1 <nullunknown>)
+declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>)
-declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>, i1 <nullunknown>)
+declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>)
 Overview:
 """""""""
-The ``llvm.objectsize`` intrinsic is designed to provide information to
+The ``llvm.objectsize`` intrinsic is designed to provide information to the
-the optimizers to determine at compile time whether a) an operation
+optimizer to determine whether a) an operation (like memcpy) will overflow a
-(like memcpy) will overflow a buffer that corresponds to an object, or
+buffer that corresponds to an object, or b) that a runtime check for overflow
-b) that a runtime check for overflow isn't necessary. An object in this
+isn't necessary. An object in this context means an allocation of a specific
-context means an allocation of a specific class, structure, array, or
+class, structure, array, or other object.
-other object.
+Arguments:
-Arguments:
+""""""""""
-""""""""""
+The ``llvm.objectsize`` intrinsic takes four arguments. The first argument is a
-The ``llvm.objectsize`` intrinsic takes three arguments. The first argument is
+pointer to or into the ``object``. The second argument determines whether
-a pointer to or into the ``object``. The second argument determines whether
+``llvm.objectsize`` returns 0 (if true) or -1 (if false) when the object size is
-``llvm.objectsize`` returns 0 (if true) or -1 (if false) when the object size
+unknown. The third argument controls how ``llvm.objectsize`` acts when ``null``
-is unknown. The third argument controls how ``llvm.objectsize`` acts when
+in address space 0 is used as its pointer argument. If it's ``false``,
-``null`` is used as its pointer argument. If it's true and the pointer is in
+``llvm.objectsize`` reports 0 bytes available when given ``null``. Otherwise, if
-address space 0, ``null`` is treated as an opaque value with an unknown number
+the ``null`` is in a non-zero address space or if ``true`` is given for the
-of bytes. Otherwise, ``llvm.objectsize`` reports 0 bytes available when given
+third argument of ``llvm.objectsize``, we assume its size is unknown. The fourth
-``null``.
+argument to ``llvm.objectsize`` determines if the value should be evaluated at
+runtime.
-The second and third arguments only accept constants.
+The second, third, and fourth arguments only accept constants.
-Semantics:
-""""""""""
+Semantics:
+""""""""""
-The ``llvm.objectsize`` intrinsic is lowered to a constant representing
-the size of the object concerned. If the size cannot be determined at
+The ``llvm.objectsize`` intrinsic is lowered to a value representing the size of
-compile time, ``llvm.objectsize`` returns ``i32/i64 -1 or 0`` (depending
+the object concerned. If the size cannot be determined, ``llvm.objectsize``
-on the ``min`` argument).
+returns ``i32/i64 -1 or 0`` (depending on the ``min`` argument).
 '``llvm.expect``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 Arguments:
 """"""""""
 The ``llvm.expect`` intrinsic takes two arguments. The first argument is
-a value. The second argument is an expected value, this needs to be a
+a value. The second argument is an expected value.
-constant value, variables are not allowed.
 Semantics:
 """"""""""
 This intrinsic is lowered to the ``val``.
 if"); and this allows for "check widening" type optimizations.
 ``@llvm.experimental.guard`` cannot be invoked.
+'``llvm.experimental.widenable.condition``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i1 @llvm.experimental.widenable.condition()
+Overview:
+"""""""""
+This intrinsic represents a "widenable condition" which is
+boolean expressions with the following property: whether this
+expression is `true` or `false`, the program is correct and
+well-defined.
+Together with :ref:`deoptimization operand bundles <deopt_opbundles>`,
+``@llvm.experimental.widenable.condition`` allows frontends to
+express guards or checks on optimistic assumptions made during
+compilation and represent them as branch instructions on special
+conditions.
+While this may appear similar in semantics to `undef`, it is very
+different in that an invocation produces a particular, singular
+value. It is also intended to be lowered late, and remain available
+for specific optimizations and transforms that can benefit from its
+special properties.
+Arguments:
+""""""""""
+None.
+Semantics:
+""""""""""
+The intrinsic ``@llvm.experimental.widenable.condition()``
+returns either `true` or `false`. For each evaluation of a call
+to this intrinsic, the program must be valid and correct both if
+it returns `true` and if it returns `false`. This allows
+transformation passes to replace evaluations of this intrinsic
+with either value whenever one is beneficial.
+When used in a branch condition, it allows us to choose between
+two alternative correct solutions for the same problem, like
+in example below:
+.. code-block:: text
+%cond = call i1 @llvm.experimental.widenable.condition()
+br i1 %cond, label %solution_1, label %solution_2
+label %fast_path:
+; Apply memory-consuming but fast solution for a task.
+label %slow_path:
+; Cheap in memory but slow solution.
+Whether the result of intrinsic's call is `true` or `false`,
+it should be correct to pick either solution. We can switch
+between them by replacing the result of
+``@llvm.experimental.widenable.condition`` with different
+`i1` expressions.
+This is how it can be used to represent guards as widenable branches:
+.. code-block:: text
+block:
+; Unguarded instructions
+call void @llvm.experimental.guard(i1 %cond, <args...>) ["deopt"(<deopt_args...>)]
+; Guarded instructions
+Can be expressed in an alternative equivalent form of explicit branch using
+``@llvm.experimental.widenable.condition``:
+.. code-block:: text
+block:
+; Unguarded instructions
+%widenable_condition = call i1 @llvm.experimental.widenable.condition()
+%guard_condition = and i1 %cond, %widenable_condition
+br i1 %guard_condition, label %guarded, label %deopt
+guarded:
+; Guarded instructions
+deopt:
+call type @llvm.experimental.deoptimize(<args...>) [ "deopt"(<deopt_args...>) ]
+So the block `guarded` is only reachable when `%cond` is `true`,
+and it should be valid to go to the block `deopt` whenever `%cond`
+is `true` or `false`.
+``@llvm.experimental.widenable.condition`` will never throw, thus
+it cannot be invoked.
+Guard widening:
+"""""""""""""""
+When ``@llvm.experimental.widenable.condition()`` is used in
+condition of a guard represented as explicit branch, it is
+legal to widen the guard's condition with any additional
+conditions.
+Guard widening looks like replacement of
+.. code-block:: text
+%widenable_cond = call i1 @llvm.experimental.widenable.condition()
+%guard_cond = and i1 %cond, %widenable_cond
+br i1 %guard_cond, label %guarded, label %deopt
+with
+.. code-block:: text
+%widenable_cond = call i1 @llvm.experimental.widenable.condition()
+%new_cond = and i1 %any_other_cond, %widenable_cond
+%new_guard_cond = and i1 %cond, %new_cond
+br i1 %new_guard_cond, label %guarded, label %deopt
+for this branch. Here `%any_other_cond` is an arbitrarily chosen
+well-defined `i1` value. By making guard widening, we may
+impose stricter conditions on `guarded` block and bail to the
+deopt when the new condition is not met.
+Lowering:
+"""""""""
+Default lowering strategy is replacing the result of
+call of ``@llvm.experimental.widenable.condition``  with
+constant `true`. However it is always correct to replace
+it with any other `i1` value. Any pass can
+freely do it if it can benefit from non-default lowering.
 '``llvm.load.relative``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
 """""""
 Semantics:
 """"""""""
 This intrinsic actually does nothing, but optimizers must assume that it
 has externally observable side effects.
+'``llvm.is.constant.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+This is an overloaded intrinsic. You can use llvm.is.constant with any argument type.
+::
+declare i1 @llvm.is.constant.i32(i32 %operand) nounwind readnone
+declare i1 @llvm.is.constant.f32(float %operand) nounwind readnone
+declare i1 @llvm.is.constant.TYPENAME(TYPE %operand) nounwind readnone
+Overview:
+"""""""""
+The '``llvm.is.constant``' intrinsic will return true if the argument
+is known to be a manifest compile-time constant. It is guaranteed to
+fold to either true or false before generating machine code.
+Semantics:
+""""""""""
+This intrinsic generates no code. If its argument is known to be a
+manifest compile-time constant value, then the intrinsic will be
+converted to a constant true value. Otherwise, it will be converted to
+a constant false value.
+In particular, note that if the argument is a constant expression
+which refers to a global (the address of which _is_ a constant, but
+not manifest during the compile), then the intrinsic evaluates to
+false.
+The result also intentionally depends on the result of optimization
+passes -- e.g., the result can change depending on whether a
+function gets inlined or not. A function's parameters are
+obviously not constant. However, a call like
+``llvm.is.constant.i32(i32 %param)`` *can* return true after the
+function is inlined, if the value passed to the function parameter was
+a constant.
+On the other hand, if constant folding is not run, it will never
+evaluate to true, even in simple cases.
 Stack Map Intrinsics
 --------------------
 LLVM provides experimental intrinsics to support runtime patching
 In the most general case call to the '``llvm.memset.element.unordered.atomic.*``' is
 lowered to a call to the symbol ``__llvm_memset_element_unordered_atomic_*``. Where '*'
 is replaced with an actual element size.
 The optimizer is allowed to inline the memory assignment when it's profitable to do so.
+Objective-C ARC Runtime Intrinsics
+----------------------------------
+LLVM provides intrinsics that lower to Objective-C ARC runtime entry points.
+LLVM is aware of the semantics of these functions, and optimizes based on that
+knowledge. You can read more about the details of Objective-C ARC `here
+<https://clang.llvm.org/docs/AutomaticReferenceCounting.html>`_.
+'``llvm.objc.autorelease``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.autorelease(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_autorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autorelease>`_.
+'``llvm.objc.autoreleasePoolPop``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare void @llvm.objc.autoreleasePoolPop(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_autoreleasePoolPop <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpop-void-pool>`_.
+'``llvm.objc.autoreleasePoolPush``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.autoreleasePoolPush()
+Lowering:
+"""""""""
+Lowers to a call to `objc_autoreleasePoolPush <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-autoreleasepoolpush-void>`_.
+'``llvm.objc.autoreleaseReturnValue``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.autoreleaseReturnValue(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_autoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autoreleasereturnvalue>`_.
+'``llvm.objc.copyWeak``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare void @llvm.objc.copyWeak(i8**, i8**)
+Lowering:
+"""""""""
+Lowers to a call to `objc_copyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-copyweak-id-dest-id-src>`_.
+'``llvm.objc.destroyWeak``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare void @llvm.objc.destroyWeak(i8**)
+Lowering:
+"""""""""
+Lowers to a call to `objc_destroyWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-destroyweak-id-object>`_.
+'``llvm.objc.initWeak``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.initWeak(i8**, i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_initWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-initweak>`_.
+'``llvm.objc.loadWeak``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.loadWeak(i8**)
+Lowering:
+"""""""""
+Lowers to a call to `objc_loadWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweak>`_.
+'``llvm.objc.loadWeakRetained``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.loadWeakRetained(i8**)
+Lowering:
+"""""""""
+Lowers to a call to `objc_loadWeakRetained <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-loadweakretained>`_.
+'``llvm.objc.moveWeak``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare void @llvm.objc.moveWeak(i8**, i8**)
+Lowering:
+"""""""""
+Lowers to a call to `objc_moveWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-moveweak-id-dest-id-src>`_.
+'``llvm.objc.release``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare void @llvm.objc.release(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_release <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-release-id-value>`_.
+'``llvm.objc.retain``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.retain(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_retain <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retain>`_.
+'``llvm.objc.retainAutorelease``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.retainAutorelease(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_retainAutorelease <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautorelease>`_.
+'``llvm.objc.retainAutoreleaseReturnValue``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.retainAutoreleaseReturnValue(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_retainAutoreleaseReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasereturnvalue>`_.
+'``llvm.objc.retainAutoreleasedReturnValue``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.retainAutoreleasedReturnValue(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_retainAutoreleasedReturnValue <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainautoreleasedreturnvalue>`_.
+'``llvm.objc.retainBlock``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.retainBlock(i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_retainBlock <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-retainblock>`_.
+'``llvm.objc.storeStrong``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare void @llvm.objc.storeStrong(i8**, i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_storeStrong <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#void-objc-storestrong-id-object-id-value>`_.
+'``llvm.objc.storeWeak``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare i8* @llvm.objc.storeWeak(i8**, i8*)
+Lowering:
+"""""""""
+Lowers to a call to `objc_storeWeak <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-storeweak>`_.
+Preserving Debug Information Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+These intrinsics are used to carry certain debuginfo together with
+IR-level operations. For example, it may be desirable to
+know the structure/union name and the original user-level field
+indices. Such information got lost in IR GetElementPtr instruction
+since the IR types are different from debugInfo types and unions
+are converted to structs in IR.
+'``llvm.preserve.array.access.index``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <ret_type>
+@llvm.preserve.array.access.index.p0s_union.anons.p0a10s_union.anons(<type> base,
+i32 dim,
+i32 index)
+Overview:
+"""""""""
+The '``llvm.preserve.array.access.index``' intrinsic returns the getelementptr address
+based on array base ``base``, array dimension ``dim`` and the last access index ``index``
+into the array. The return type ``ret_type`` is a pointer type to the array element.
+The array ``dim`` and ``index`` are preserved which is more robust than
+getelementptr instruction which may be subject to compiler transformation.
+The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction
+to provide array or pointer debuginfo type.
+The metadata is a ``DICompositeType`` or ``DIDerivedType`` representing the
+debuginfo version of ``type``.
+Arguments:
+""""""""""
+The ``base`` is the array base address.  The ``dim`` is the array dimension.
+The ``base`` is a pointer if ``dim`` equals 0.
+The ``index`` is the last access index into the array or pointer.
+Semantics:
+""""""""""
+The '``llvm.preserve.array.access.index``' intrinsic produces the same result
+as a getelementptr with base ``base`` and access operands ``{dim's 0's, index}``.
+'``llvm.preserve.union.access.index``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <type>
+@llvm.preserve.union.access.index.p0s_union.anons.p0s_union.anons(<type> base,
+i32 di_index)
+Overview:
+"""""""""
+The '``llvm.preserve.union.access.index``' intrinsic carries the debuginfo field index
+``di_index`` and returns the ``base`` address.
+The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction
+to provide union debuginfo type.
+The metadata is a ``DICompositeType`` representing the debuginfo version of ``type``.
+The return type ``type`` is the same as the ``base`` type.
+Arguments:
+""""""""""
+The ``base`` is the union base address. The ``di_index`` is the field index in debuginfo.
+Semantics:
+""""""""""
+The '``llvm.preserve.union.access.index``' intrinsic returns the ``base`` address.
+'``llvm.preserve.struct.access.index``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Syntax:
+"""""""
+::
+declare <ret_type>
+@llvm.preserve.struct.access.index.p0i8.p0s_struct.anon.0s(<type> base,
+i32 gep_index,
+i32 di_index)
+Overview:
+"""""""""
+The '``llvm.preserve.struct.access.index``' intrinsic returns the getelementptr address
+based on struct base ``base`` and IR struct member index ``gep_index``.
+The ``llvm.preserve.access.index`` type of metadata is attached to this call instruction
+to provide struct debuginfo type.
+The metadata is a ``DICompositeType`` representing the debuginfo version of ``type``.
+The return type ``ret_type`` is a pointer type to the structure member.
+Arguments:
+""""""""""
+The ``base`` is the structure base address. The ``gep_index`` is the struct member index
+based on IR structures. The ``di_index`` is the struct member index based on debuginfo.
+Semantics:
+""""""""""
+The '``llvm.preserve.struct.access.index``' intrinsic produces the same result
+as a getelementptr with base ``base`` and access operands ``{0, gep_index}``.

Mercurial > hg > CbC > CbC_llvm

comparison docs/LangRef.rst @ 148:63bd29f05246