The idea behind this convention is to support calls to runtime functions
that have a hot path and a cold path. The hot path is usually a small piece
- of code that doesn't many registers. The cold path might need to call out to
+ of code that doesn't use many registers. The cold path might need to call out to
another function and therefore only needs to preserve the caller-saved
registers, which haven't already been saved by the caller. The
`PreserveMost` calling convention is very similar to the `cold` calling
Global variables define regions of memory allocated at compilation time
instead of run-time.
-Global variables definitions must be initialized.
+Global variable definitions must be initialized.
Global variables in other translation units can also be declared, in which
case they don't have an initializer.
Globals can also have a :ref:`DLL storage class <dllstorageclass>`.
-Variables and aliasaes can have a
+Variables and aliases can have a
:ref:`Thread Local Storage Model <tls_model>`.
Syntax::
LLVM allows an explicit section to be specified for functions. If the
target supports it, it will emit functions to the section specified.
-Additionally, the function can placed in a COMDAT.
+Additionally, the function can be placed in a COMDAT.
An explicit alignment may be specified for a function. If not present,
or if the alignment is set to zero, the alignment of the function is set
is specified, the function is forced to have at least that much
alignment. All alignments must be a power of 2.
-If the ``unnamed_addr`` attribute is given, the address is know to not
+If the ``unnamed_addr`` attribute is given, the address is known to not
be significant and two identical functions can be merged.
Syntax::
``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers
might not correctly handle dropping a weak symbol that is aliased.
-Alias that are not ``unnamed_addr`` are guaranteed to have the same address as
+Aliases that are not ``unnamed_addr`` are guaranteed to have the same address as
the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point
to the same content.
.. _gc:
-Garbage Collector Names
------------------------
+Garbage Collector Strategy Names
+--------------------------------
-Each function may specify a garbage collector name, which is simply a
+Each function may specify a garbage collector strategy name, which is simply a
string:
.. code-block:: llvm
define void @f() gc "name" { ... }
-The compiler declares the supported values of *name*. Specifying a
-collector will cause the compiler to alter its output in order to
-support the named garbage collection algorithm.
+The supported values of *name* includes those :ref:`built in to LLVM
+<builtin-gc-strategies>` and any provided by loaded plugins. Specifying a GC
+strategy will cause the compiler to alter its output in order to support the
+named garbage collection algorithm. Note that LLVM itself does not contain a
+garbage collector, this functionality is restricted to generating machine code
+which can interoperate with a collector provided externally.
.. _prefixdata:
normally. This produces undefined behavior at runtime if the
function ever does dynamically return.
``nounwind``
- This function attribute indicates that the function never returns
- with an unwind or exceptional control flow. If the function does
- unwind, its runtime behavior is undefined.
+ 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.
``optnone``
This function attribute indicates that the function is not optimized
by any optimization or code generator passes with the
LLVM IR floating-point binary ops (:ref:`fadd <i_fadd>`,
:ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`,
-:ref:`frem <i_frem>`) have the following flags that can set to enable
+:ref:`frem <i_frem>`) have the following flags that can be set to enable
otherwise unsafe floating point operations
``nnan``
!{ !"test\00", i32 10}
+Metadata nodes that aren't uniqued use the ``distinct`` keyword. For example:
+
+.. code-block:: llvm
+
+ !0 = distinct !{!"test\00", i32 10}
+
+``distinct`` nodes are useful when nodes shouldn't be merged based on their
+content. They can also occur when transformations cause uniquing collisions
+when metadata operands change.
+
A :ref:`named metadata <namedmetadatastructure>` is a collection of
metadata nodes, which can be looked up in the module symbol table. For
example:
More information about specific metadata nodes recognized by the
optimizers and code generator is found below.
+Specialized Metadata Nodes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Specialized metadata nodes are custom data structures in metadata (as opposed
+to generic tuples). Their fields are labelled, and can be specified in any
+order.
+
+MDLocation
+""""""""""
+
+``MDLocation`` nodes represent source debug locations. The ``scope:`` field is
+mandatory.
+
+.. code-block:: llvm
+
+ !0 = !MDLocation(line: 2900, column: 42, scope: !1, inlinedAt: !2)
+
'``tbaa``' Metadata
^^^^^^^^^^^^^^^^^^^
Each type of metadata specifies a list of scopes where each scope has an id and
a domain. When evaluating an aliasing query, if for some some domain, the set
of scopes with that domain in one instruction's ``alias.scope`` list is a
-subset of (or qual to) the set of scopes for that domain in another
+subset of (or equal to) the set of scopes for that domain in another
instruction's ``noalias`` list, then the two memory accesses are assumed not to
alias.
!1 = !{!1} ; an identifier for the inner loop
!2 = !{!2} ; an identifier for the outer loop
+'``llvm.bitsets``'
+^^^^^^^^^^^^^^^^^^
+
+The ``llvm.bitsets`` global metadata is used to implement
+:doc:`bitsets <BitSets>`.
+
Module Flags Metadata
=====================
Accurate Garbage Collection Intrinsics
--------------------------------------
-LLVM support for `Accurate Garbage Collection <GarbageCollection.html>`_
-(GC) requires the implementation and generation of these intrinsics.
+LLVM's support for `Accurate Garbage Collection <GarbageCollection.html>`_
+(GC) requires the frontend to generate code containing appropriate intrinsic
+calls and select an appropriate GC strategy which knows how to lower these
+intrinsics in a manner which is appropriate for the target collector.
+
These intrinsics allow identification of :ref:`GC roots on the
stack <int_gcroot>`, as well as garbage collector implementations that
require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers.
-Front-ends for type-safe garbage collected languages should generate
+Frontends for type-safe garbage collected languages should generate
these intrinsics to make use of the LLVM garbage collectors. For more
-details, see `Accurate Garbage Collection with
-LLVM <GarbageCollection.html>`_.
+details, see `Garbage Collection with LLVM <GarbageCollection.html>`_.
-The garbage collection intrinsics only operate on objects in the generic
-address space (address space zero).
+Experimental Statepoint Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+LLVM provides an second experimental set of intrinsics for describing garbage
+collection safepoints in compiled code. These intrinsics are an alternative
+to the ``llvm.gcroot`` intrinsics, but are compatible with the ones for
+:ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` barriers. The
+differences in approach are covered in the `Garbage Collection with LLVM
+<GarbageCollection.html>`_ documentation. The intrinsics themselves are
+described in :doc:`Statepoints`.
.. _int_gcroot:
other aggressive transformations, so the value returned may not be that
of the obvious source-language caller.
+'``llvm.frameallocate``' and '``llvm.framerecover``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.frameallocate(i32 %size)
+ declare i8* @llvm.framerecover(i8* %func, i8* %fp)
+
+Overview:
+"""""""""
+
+The '``llvm.frameallocate``' intrinsic allocates stack memory at some fixed
+offset from the frame pointer, and the '``llvm.framerecover``'
+intrinsic applies that offset to a live frame pointer to recover the address of
+the allocation. The offset is computed during frame layout of the caller of
+``llvm.frameallocate``.
+
+Arguments:
+""""""""""
+
+The ``size`` argument to '``llvm.frameallocate``' must be a constant integer
+indicating the amount of stack memory to allocate. As with allocas, allocating
+zero bytes is legal, but the result is undefined.
+
+The ``func`` argument to '``llvm.framerecover``' must be a constant
+bitcasted pointer to a function defined in the current module. The code
+generator cannot determine the frame allocation offset of functions defined in
+other modules.
+
+The ``fp`` argument to '``llvm.framerecover``' must be a frame
+pointer of a call frame that is currently live. The return value of
+'``llvm.frameaddress``' is one way to produce such a value, but most platforms
+also expose the frame pointer through stack unwinding mechanisms.
+
+Semantics:
+""""""""""
+
+These intrinsics allow a group of functions to access one stack memory
+allocation in an ancestor stack frame. The memory returned from
+'``llvm.frameallocate``' may be allocated prior to stack realignment, so the
+memory is only aligned to the ABI-required stack alignment. Each function may
+only call '``llvm.frameallocate``' one or zero times from the function entry
+block. The frame allocation intrinsic inhibits inlining, as any frame
+allocations in the inlined function frame are likely to be at a different
+offset from the one used by '``llvm.framerecover``' called with the
+uninlined function.
+
.. _int_read_register:
.. _int_write_register:
provided condition are not used for code generation. If the condition is
violated during execution, the behavior is undefined.
-Please note that optimizer might limit the transformations performed on values
+Note that the optimizer might limit the transformations performed on values
used by the ``llvm.assume`` intrinsic in order to preserve the instructions
only used to form the intrinsic's input argument. This might prove undesirable
-if the extra information provided by the ``llvm.assume`` intrinsic does cause
+if the extra information provided by the ``llvm.assume`` intrinsic does not cause
sufficient overall improvement in code quality. For this reason,
``llvm.assume`` should not be used to document basic mathematical invariants
that the optimizer can otherwise deduce or facts that are of little use to the
optimizer.
+.. _bitset.test:
+
+'``llvm.bitset.test``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i1 @llvm.bitset.test(i8* %ptr, metadata %bitset) nounwind readnone
+
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to be tested. The second argument is a
+metadata string containing the name of a :doc:`bitset <BitSets>`.
+
+Overview:
+"""""""""
+
+The ``llvm.bitset.test`` intrinsic tests whether the given pointer is a
+member of the given bitset.
+
'``llvm.donothing``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
projects / oota-llvm.git / blobdiff