.. contents::
:local:
- :depth: 3
+ :depth: 4
Abstract
========
#. Unnamed temporaries are created when the result of a computation is
not assigned to a named value.
#. Unnamed temporaries are numbered sequentially (using a per-function
- incrementing counter, starting with 0).
+ incrementing counter, starting with 0). Note that basic blocks are
+ included in this numbering. For example, if the entry basic block is not
+ given a label name, then it will get number 0.
It also shows a convention that we follow in this document. When
demonstrating instructions, we will follow an instruction with a comment
``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the
global will only be merged with equivalent globals. These linkage
types are otherwise the same as their non-``odr`` versions.
-``linkonce_odr_auto_hide``
- Similar to "``linkonce_odr``", but nothing in the translation unit
- takes the address of this definition. For instance, functions that
- had an inline definition, but the compiler decided not to inline it.
- ``linkonce_odr_auto_hide`` may have only ``default`` visibility. The
- symbols are removed by the linker from the final linked image
- (executable or dynamic library).
``external``
If none of the above identifiers are used, the global is externally
visible, meaning that it participates in linkage and can be used to
pointer to a pointer in a DLL, so that it can be referenced with the
``dllimport`` attribute. On Microsoft Windows targets, the pointer
name is formed by combining ``__imp_`` and the function or variable
- name.
-
-For example, since the "``.LC0``" variable is defined to be internal, if
-another module defined a "``.LC0``" variable and was linked with this
-one, one of the two would be renamed, preventing a collision. Since
-"``main``" and "``puts``" are external (i.e., lacking any linkage
-declarations), they are accessible outside of the current module.
+ name. Since this linkage exists for defining a dll interface, the
+ compiler, assembler and linker know it is externally referenced and
+ must refrain from deleting the symbol.
It is illegal for a function *declaration* to have any linkage type
other than ``external``, ``dllimport`` or ``extern_weak``.
-Aliases can have only ``external``, ``internal``, ``weak`` or
-``weak_odr`` linkages.
-
.. _callingconv:
Calling Conventions
support Pascal conventions or any other well-known target-independent
convention.
+.. _visibilitystyles:
+
Visibility Styles
-----------------
defining module will bind to the local symbol. That is, the symbol
cannot be overridden by another module.
+.. _namedtypes:
+
Named Types
-----------
----------------
Global variables define regions of memory allocated at compilation time
-instead of run-time. Global variables may optionally be initialized, may
-have an explicit section to be placed in, and may have an optional
-explicit alignment specified.
+instead of run-time.
+
+Global variables definitions must be initialized, may have an explicit section
+to be placed in, and may have an optional explicit alignment specified.
+
+Global variables in other translation units can also be declared, in which
+case they don't have an initializer.
A variable may be defined as ``thread_local``, which means that it will
not be shared by threads (each thread will have a separated copy of the
initial values before the start of the global initializer. This is
true even for variables potentially accessible from outside the
module, including those with external linkage or appearing in
-``@llvm.used``. This assumption may be suppressed by marking the
-variable with ``externally_initialized``.
+``@llvm.used`` or dllexported variables. This assumption may be suppressed
+by marking the variable with ``externally_initialized``.
An explicit alignment may be specified for a global, which must be a
power of 2. If not present, or if the alignment is set to zero, the
@G = addrspace(5) constant float 1.0, section "foo", align 4
+The following example just declares a global variable
+
+.. code-block:: llvm
+
+ @G = external global i32
+
The following example defines a thread-local global with the
``initialexec`` TLS model:
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 :ref:`garbage
-collector name <gc>`, an opening curly brace, a list of basic blocks,
-and a closing curly brace.
+collector name <gc>`, an optional :ref:`prefix <prefixdata>`, an opening
+curly brace, a list of basic blocks, and a closing curly brace.
LLVM function declarations consist of the "``declare``" keyword, an
optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
style <visibility>`, 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 list of arguments, an optional alignment, and an
-optional :ref:`garbage collector name <gc>`.
-
-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 explicit label is not provided, a block is assigned an
-implicit numbered label, using a next value from the same counter as used
-for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a
-function entry block does not have explicit label, it will be assigned
-label "%0", then first unnamed temporary in that block will be "%1", etc.
+name, a possibly empty list of arguments, an optional alignment, an optional
+:ref:`garbage collector name <gc>` and an optional :ref:`prefix <prefixdata>`.
+
+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
+implicit numbered label, using the next value from the same counter as used for
+unnamed temporaries (:ref:`see above<identifiers>`). For example, if a function
+entry block does not have an explicit label, it will be assigned label "%0",
+then the first unnamed temporary in that block will be "%1", etc.
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
[cconv] [ret attrs]
<ResultType> @<FunctionName> ([argument list])
[fn Attrs] [section "name"] [align N]
- [gc] { ... }
+ [gc] [prefix Constant] { ... }
+
+.. _langref_aliases:
Aliases
-------
@<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
+The linkage must be one of ``private``, ``linker_private``,
+``linker_private_weak``, ``internal``, ``linkonce``, ``weak``,
+``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers
+might not correctly handle dropping a weak symbol that is aliased by a non-weak
+alias.
+
.. _namedmetadatastructure:
Named Metadata
the first parameter. This is not a valid attribute for return
values.
``noalias``
- This indicates that pointer values
`*based* <pointeraliasing>` on
+ This indicates that pointer values
:ref:`based <pointeraliasing>` on
the argument or return value do not alias pointer values which are
not *based* on it, ignoring certain "irrelevant" dependencies. For a
call to the parent function, dependencies between memory references
attribute for return values and can only be applied to one parameter.
``returned``
- This indicates that the value of the function always returns the value
- of the parameter as its return value. This is an optimization hint to
- the code generator when generating the caller, allowing tail call
- optimization and omission of register saves and restores in some cases;
- it is not checked or enforced when generating the callee. The parameter
- and the function return type must be valid operands for the
- :ref:`bitcast instruction <i_bitcast>`. This is not a valid attribute for
- return values and can only be applied to one parameter.
+ This indicates that the function always returns the argument as its return
+ value. This is an optimization hint to the code generator when generating
+ the caller, allowing tail call optimization and omission of register saves
+ and restores in some cases; it is not checked or enforced when generating
+ the callee. The parameter and the function return type must be valid
+ operands for the :ref:`bitcast instruction <i_bitcast>`. This is not a
+ valid attribute for return values and can only be applied to one parameter.
.. _gc:
collector which will cause the compiler to alter its output in order to
support the named garbage collection algorithm.
+.. _prefixdata:
+
+Prefix Data
+-----------
+
+Prefix data is data associated with a function which the code generator
+will emit immediately before the function body. The purpose of this feature
+is to allow frontends to associate language-specific runtime metadata with
+specific functions and make it available through the function pointer while
+still allowing the function pointer to be called. To access the data for a
+given function, a program may bitcast the function pointer to a pointer to
+the constant's type. This implies that the IR symbol points to the start
+of the prefix data.
+
+To maintain the semantics of ordinary function calls, the prefix data must
+have a particular format. Specifically, it must begin with a sequence of
+bytes which decode to a sequence of machine instructions, valid for the
+module's target, which transfer control to the point immediately succeeding
+the prefix data, without performing any other visible action. This allows
+the inliner and other passes to reason about the semantics of the function
+definition without needing to reason about the prefix data. Obviously this
+makes the format of the prefix data highly target dependent.
+
+Prefix data is laid out as if it were an initializer for a global variable
+of the prefix data's type. No padding is automatically placed between the
+prefix data and the function body. If padding is required, it must be part
+of the prefix data.
+
+A trivial example of valid prefix data for the x86 architecture is ``i8 144``,
+which encodes the ``nop`` instruction:
+
+.. code-block:: llvm
+
+ define void @f() prefix i8 144 { ... }
+
+Generally prefix data can be formed by encoding a relative branch instruction
+which skips the metadata, as in this example of valid prefix data for the
+x86_64 architecture, where the first two bytes encode ``jmp .+10``:
+
+.. code-block:: llvm
+
+ %0 = type <{ i8, i8, i8* }>
+
+ define void @f() prefix %0 <{ i8 235, i8 8, i8* @md}> { ... }
+
+A function may have prefix data but no body. This has similar semantics
+to the ``available_externally`` linkage in that the data may be used by the
+optimizers but will not be emitted in the object file.
+
.. _attrgrp:
Attribute Groups
This attribute indicates that the inliner should attempt to inline
this function into callers whenever possible, ignoring any active
inlining size threshold for this caller.
-``nonlazybind``
- This attribute suppresses lazy symbol binding for the function. This
- may make calls to the function faster, at the cost of extra program
- startup time if the function is not called during program startup.
+``builtin``
+ This indicates that the callee function at a call site should be
+ recognized as a built-in function, even though the function's declaration
+ uses the ``nobuiltin`` attribute. This is only valid at call sites for
+ direct calls to functions which are declared with the ``nobuiltin``
+ attribute.
+``cold``
+ This attribute indicates that this function is rarely called. When
+ computing edge weights, basic blocks post-dominated by a cold
+ function call are also considered to be cold; and, thus, given low
+ weight.
``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.
+``minsize``
+ This attribute suggests that optimization passes and code generator
+ passes make choices that keep the code size of this function as small
+ as possible and perform optimizations that may sacrifice runtime
+ performance in order to minimize the size of the generated code.
``naked``
This attribute disables prologue / epilogue emission for the
function. This can have very system-specific consequences.
``nobuiltin``
- This indicates that the callee function at a call site is not
- recognized as a built-in function. LLVM will retain the original call
- and not replace it with equivalent code based on the semantics of the
- built-in function. This is only valid at call sites, not on function
- declarations or definitions.
+ This indicates that the callee function at a call site is not recognized as
+ a built-in function. LLVM will retain the original call and not replace it
+ with equivalent code based on the semantics of the built-in function, unless
+ the call site uses the ``builtin`` attribute. This is valid at call sites
+ and on function declarations and definitions.
``noduplicate``
This attribute indicates that calls to the function cannot be
duplicated. A call to a ``noduplicate`` function may be moved
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``
+ This attribute suppresses lazy symbol binding for the function. This
+ 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.
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.
+``optnone``
+ This function attribute indicates that the function is not optimized
+ by any optimization or code generator passes with the
+ exception of interprocedural optimization passes.
+ This attribute cannot be used together with the ``alwaysinline``
+ attribute; this attribute is also incompatible
+ with the ``minsize`` attribute and the ``optsize`` attribute.
+
+ This attribute requires the ``noinline`` attribute to be specified on
+ the function as well, so the function is never inlined into any caller.
+ Only functions with the ``alwaysinline`` attribute are valid
+ candidates for inlining into the body of this function.
``optsize``
This attribute suggests that optimization passes and code generator
passes make choices that keep the code size of this function low,
- and otherwise do optimizations specifically to reduce code size.
+ and otherwise do optimizations specifically to reduce code size as
+ long as they do not significantly impact runtime performance.
``readnone``
- This attribute indicates that the function computes its result (or
- decides to unwind an exception) based strictly on its arguments,
+ On a function, this attribute indicates that the function computes its
+ result (or decides to unwind an exception) based strictly on its arguments,
without dereferencing any pointer arguments or otherwise accessing
any mutable state (e.g. memory, control registers, etc) visible to
caller functions. It does not write through any pointer arguments
(including ``byval`` arguments) and never changes any state visible
to callers. This means that it cannot unwind exceptions by calling
the ``C++`` exception throwing methods.
+
+ 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.
``readonly``
- This attribute indicates that the function does not write through
- any pointer arguments (including ``byval`` arguments) or otherwise
+ 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
state that may be set in the caller. A readonly function always
called with the same set of arguments and global state. It cannot
unwind an exception by calling the ``C++`` exception throwing
methods.
+
+ 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.
``returns_twice``
This attribute indicates that this function can return twice. The C
``setjmp`` is an example of such a function. The compiler disables
The inline asm code is simply printed to the machine code .s file when
assembly code is generated.
+.. _langref_datalayout:
+
Data Layout
-----------
specifications are given in this list:
- ``E`` - big endian
-- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment
+- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment.
+- ``p[n]:64:64:64`` - Other address spaces are assumed to be the
+ same as the default address space.
- ``S0`` - natural stack alignment is unspecified
- ``i1:8:8`` - i1 is 8-bit (byte) aligned
- ``i8:8:8`` - i8 is 8-bit (byte) aligned
that require precise layout information, but this also prevents those
optimizations from introducing target specificity into the IR.
+.. _langref_triple:
+
+Target Triple
+-------------
+
+A module may specify a target triple string that describes the target
+host. The syntax for the target triple is simply:
+
+.. code-block:: llvm
+
+ target triple = "x86_64-apple-macosx10.7.0"
+
+The *target triple* string consists of a series of identifiers delimited
+by the minus sign character ('-'). The canonical forms are:
+
+::
+
+ ARCHITECTURE-VENDOR-OPERATING_SYSTEM
+ ARCHITECTURE-VENDOR-OPERATING_SYSTEM-ENVIRONMENT
+
+This information is passed along to the backend so that it generates
+code for the proper architecture. It's possible to override this on the
+command line with the ``-mtriple`` command line option.
+
.. _pointeraliasing:
Pointer Aliasing Rules
generated code and enables novel analyses and transformations that are
not feasible to perform on normal three address code representations.
-Type Classifications
---------------------
+.. _t_void:
-The types fall into a few useful classifications:
+Void Type
+---------
+Overview:
+^^^^^^^^^
-.. list-table::
- :header-rows: 1
+The void type does not represent any value and has no size.
- * - Classification
- - Types
+Syntax:
+^^^^^^^
- * - :ref:`integer <t_integer>`
- - ``i1``, ``i2``, ``i3``, ... ``i8``, ... ``i16``, ... ``i32``, ...
- ``i64``, ...
+::
- * - :ref:`floating point <t_floating>`
- - ``half``, ``float``, ``double``, ``x86_fp80``, ``fp128``,
- ``ppc_fp128``
+ void
- * - first class
+.. _t_function:
- .. _t_firstclass:
+Function Type
+-------------
- - :ref:`integer <t_integer>`, :ref:`floating point <t_floating>`,
- :ref:`pointer <t_pointer>`, :ref:`vector <t_vector>`,
- :ref:`structure <t_struct>`, :ref:`array <t_array>`,
- :ref:`label <t_label>`, :ref:`metadata <t_metadata>`.
+Overview:
+^^^^^^^^^
+
+The function type can be thought of as a function signature. It consists of a
+return type and a list of formal parameter types. The return type of a function
+type is a void type or first class type --- except for :ref:`label <t_label>`
+and :ref:`metadata <t_metadata>` types.
- * - :ref:`primitive <t_primitive>`
- - :ref:`label <t_label>`,
- :ref:`void <t_void>`,
- :ref:`integer <t_integer>`,
- :ref:`floating point <t_floating>`,
- :ref:`x86mmx <t_x86mmx>`,
- :ref:`metadata <t_metadata>`.
+Syntax:
+^^^^^^^
- * - :ref:`derived <t_derived>`
- - :ref:`array <t_array>`,
- :ref:`function <t_function>`,
- :ref:`pointer <t_pointer>`,
- :ref:`structure <t_struct>`,
- :ref:`vector <t_vector>`,
- :ref:`opaque <t_opaque>`.
+::
+
+ <returntype> (<parameter list>)
+
+...where '``<parameter list>``' is a comma-separated list of type
+specifiers. Optionally, the parameter list may include a type ``...``, which
+indicates that the function takes a variable number of arguments. Variable
+argument functions can access their arguments with the :ref:`variable argument
+handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type
+except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`.
+
+Examples:
+^^^^^^^^^
+
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _t_firstclass:
+
+First Class Types
+-----------------
The :ref:`first class <t_firstclass>` types are perhaps the most important.
Values of these types are the only ones which can be produced by
instructions.
-.. _t_primitive:
+.. _t_single_value:
-Primitive Types
----------------
+Single Value Types
+^^^^^^^^^^^^^^^^^^
-The primitive types are the fundamental building blocks of the LLVM
-system.
+These are the types that are valid in registers from CodeGen's perspective.
.. _t_integer:
Integer Type
-^^^^^^^^^^^^
+""""""""""""
Overview:
-"""""""""
+*********
The integer type is a very simple type that simply specifies an
arbitrary bit width for the integer type desired. Any bit width from 1
bit to 2\ :sup:`23`\ -1 (about 8 million) can be specified.
Syntax:
-"""""""
+*******
::
value.
Examples:
-"""""""""
+*********
+----------------+------------------------------------------------+
| ``i1`` | a single-bit integer. |
.. _t_floating:
Floating Point Types
-^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""
.. list-table::
:header-rows: 1
.. _t_x86mmx:
X86mmx Type
-^^^^^^^^^^^
+"""""""""""
Overview:
-"""""""""
+*********
The x86mmx type represents a value held in an MMX register on an x86
machine. The operations allowed on it are quite limited: parameters and
of this type.
Syntax:
-"""""""
+*******
::
x86mmx
-.. _t_void:
-Void Type
-^^^^^^^^^
+.. _t_pointer:
+
+Pointer Type
+""""""""""""
Overview:
-"""""""""
+*********
-The void type does not represent any value and has no size.
+The pointer type is used to specify memory locations. Pointers are
+commonly used to reference objects in memory.
+
+Pointer types may have an optional address space attribute defining the
+numbered address space where the pointed-to object resides. The default
+address space is number zero. The semantics of non-zero address spaces
+are target-specific.
+
+Note that LLVM does not permit pointers to void (``void*``) nor does it
+permit pointers to labels (``label*``). Use ``i8*`` instead.
Syntax:
-"""""""
+*******
::
- void
+ <type> *
+
+Examples:
+*********
+
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+
+.. _t_vector:
+
+Vector Type
+"""""""""""
+
+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
+type. Vector types are considered :ref:`first class <t_firstclass>`.
+
+Syntax:
+*******
+
+::
+
+ < <# elements> x <elementtype> >
+
+The number of elements is a constant integer value larger than 0;
+elementtype may be any integer or floating point type, or a pointer to
+these types. Vectors of size zero are not allowed.
+
+Examples:
+*********
+
++-------------------+--------------------------------------------------+
+| ``<4 x i32>`` | Vector of 4 32-bit integer values. |
++-------------------+--------------------------------------------------+
+| ``<8 x float>`` | Vector of 8 32-bit floating-point values. |
++-------------------+--------------------------------------------------+
+| ``<2 x i64>`` | Vector of 2 64-bit integer values. |
++-------------------+--------------------------------------------------+
+| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. |
++-------------------+--------------------------------------------------+
.. _t_label:
metadata
-.. _t_derived:
-
-Derived Types
--------------
-
-The real power in LLVM comes from the derived types in the system. This
-is what allows a programmer to represent arrays, functions, pointers,
-and other useful types. Each of these types contain one or more element
-types which may be a primitive type, or another derived type. For
-example, it is possible to have a two dimensional array, using an array
-as the element type of another array.
-
.. _t_aggregate:
Aggregate Types
.. _t_array:
Array Type
-^^^^^^^^^^
+""""""""""
Overview:
-"""""""""
+*********
The array type is a very simple derived type that arranges elements
sequentially in memory. The array type requires a size (number of
elements) and an underlying data type.
Syntax:
-"""""""
+*******
::
be any type with a size.
Examples:
-"""""""""
+*********
+------------------+--------------------------------------+
| ``[40 x i32]`` | Array of 40 32-bit integer values. |
arrays' in LLVM could use the type "``{ i32, [0 x float]}``", for
example.
-.. _t_function:
-
-Function Type
-^^^^^^^^^^^^^
-
-Overview:
-"""""""""
-
-The function type can be thought of as a function signature. It consists
-of a return type and a list of formal parameter types. The return type
-of a function type is a first class type or a void type.
-
-Syntax:
-"""""""
-
-::
-
- <returntype> (<parameter list>)
-
-...where '``<parameter list>``' is a comma-separated list of type
-specifiers. Optionally, the parameter list may include a type ``...``,
-which indicates that the function takes a variable number of arguments.
-Variable argument functions can access their arguments with the
-:ref:`variable argument handling intrinsic <int_varargs>` functions.
-'``<returntype>``' is any type except :ref:`label <t_label>`.
-
-Examples:
-"""""""""
-
-+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` |
-+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. |
-+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. |
-+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values |
-+---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-
.. _t_struct:
Structure Type
-^^^^^^^^^^^^^^
+""""""""""""""
Overview:
-"""""""""
+*********
The structure type is used to represent a collection of data members
together in memory. The elements of a structure may be any type that has
recursive, can be opaqued, and are never uniqued.
Syntax:
-"""""""
+*******
::
%T2 = type <{ <type list> }> ; Identified packed struct type
Examples:
-"""""""""
+*********
+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values |
.. _t_opaque:
Opaque Structure Types
-^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""
Overview:
-"""""""""
+*********
Opaque structure types are used to represent named structure types that
do not have a body specified. This corresponds (for example) to the C
notion of a forward declared structure.
Syntax:
-"""""""
+*******
::
%52 = type opaque
Examples:
-"""""""""
+*********
+--------------+-------------------+
| ``opaque`` | An opaque type. |
+--------------+-------------------+
-.. _t_pointer:
-
-Pointer Type
-^^^^^^^^^^^^
-
-Overview:
-"""""""""
-
-The pointer type is used to specify memory locations. Pointers are
-commonly used to reference objects in memory.
-
-Pointer types may have an optional address space attribute defining the
-numbered address space where the pointed-to object resides. The default
-address space is number zero. The semantics of non-zero address spaces
-are target-specific.
-
-Note that LLVM does not permit pointers to void (``void*``) nor does it
-permit pointers to labels (``label*``). Use ``i8*`` instead.
-
-Syntax:
-"""""""
-
-::
-
- <type> *
-
-Examples:
-"""""""""
-
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. |
-+-------------------------+--------------------------------------------------------------------------------------------------------------+
-
-.. _t_vector:
-
-Vector Type
-^^^^^^^^^^^
-
-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
-type. Vector types are considered :ref:`first class <t_firstclass>`.
-
-Syntax:
-"""""""
-
-::
-
- < <# elements> x <elementtype> >
-
-The number of elements is a constant integer value larger than 0;
-elementtype may be any integer or floating point type, or a pointer to
-these types. Vectors of size zero are not allowed.
-
-Examples:
-"""""""""
-
-+-------------------+--------------------------------------------------+
-| ``<4 x i32>`` | Vector of 4 32-bit integer values. |
-+-------------------+--------------------------------------------------+
-| ``<8 x float>`` | Vector of 8 32-bit floating-point values. |
-+-------------------+--------------------------------------------------+
-| ``<2 x i64>`` | Vector of 2 64-bit integer values. |
-+-------------------+--------------------------------------------------+
-| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. |
-+-------------------+--------------------------------------------------+
-
Constants
=========
There are no constants of type x86mmx.
+.. _complexconstants:
+
Complex Constants
-----------------
Finally, some targets may provide defined semantics when using the value
as the operand to an inline assembly, but that is target specific.
+.. _constantexprs:
+
Constant Expressions
--------------------
Convert a constant, CST, to another TYPE. The constraints of the
operands are the same as those for the :ref:`bitcast
instruction <i_bitcast>`.
+``addrspacecast (CST to TYPE)``
+ Convert a constant pointer or constant vector of pointer, CST, to another
+ TYPE in a different address space. The constraints of the operands are the
+ same as those for the :ref:`addrspacecast instruction <i_addrspacecast>`.
``getelementptr (CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)``
Perform the :ref:`getelementptr operation <i_getelementptr>` on
constants. As with the :ref:`getelementptr <i_getelementptr>`
Other Values
============
+.. _inlineasmexprs:
+
Inline Assembler Expressions
----------------------------
It is sometimes useful to attach information to loop constructs. Currently,
loop metadata is implemented as metadata attached to the branch instruction
in the loop latch block. This type of metadata refer to a metadata node that is
-guaranteed to be separate for each loop. The loop-level metadata is prefixed
-with ``llvm.loop``.
+guaranteed to be separate for each loop. The loop identifier metadata is
+specified with the name ``llvm.loop``.
The loop identifier metadata is implemented using a metadata that refers to
itself to avoid merging it with any other identifier metadata, e.g.,
!0 = metadata !{ metadata !0 }
!1 = metadata !{ metadata !1 }
+The loop identifier metadata can be used to specify additional per-loop
+metadata. Any operands after the first operand can be treated as user-defined
+metadata. For example the ``llvm.vectorizer.unroll`` metadata is understood
+by the loop vectorizer to indicate how many times to unroll the loop:
-'``llvm.loop.parallel``' Metadata
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: llvm
-This loop metadata can be used to communicate that a loop should be considered
-a parallel loop. The semantics of parallel loops in this case is the one
-with the strongest cross-iteration instruction ordering freedom: the
-iterations in the loop can be considered completely independent of each
-other (also known as embarrassingly parallel loops).
-
-This metadata can originate from a programming language with parallel loop
-constructs. In such a case it is completely the programmer's responsibility
-to ensure the instructions from the different iterations of the loop can be
-executed in an arbitrary order, in parallel, or intertwined. No loop-carried
-dependency checking at all must be expected from the compiler.
-
-In order to fulfill the LLVM requirement for metadata to be safely ignored,
-it is important to ensure that a parallel loop is converted to
-a sequential loop in case an optimization (agnostic of the parallel loop
-semantics) converts the loop back to such. This happens when new memory
-accesses that do not fulfill the requirement of free ordering across iterations
-are added to the loop. Therefore, this metadata is required, but not
-sufficient, to consider the loop at hand a parallel loop. For a loop
-to be parallel, all its memory accessing instructions need to be
-marked with the ``llvm.mem.parallel_loop_access`` metadata that refer
-to the same loop identifier metadata that identify the loop at hand.
+ br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
+ ...
+ !0 = metadata !{ metadata !0, metadata !1 }
+ !1 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 2 }
'``llvm.mem``'
^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For a loop to be parallel, in addition to using
-the ``llvm.loop.parallel`` metadata to mark the loop latch branch instruction,
+the ``llvm.loop`` metadata to mark the loop latch branch instruction,
also all of the memory accessing instructions in the loop body need to be
marked with the ``llvm.mem.parallel_loop_access`` metadata. If there
is at least one memory accessing instruction not marked with the metadata,
-the loop, despite it possibly using the ``llvm.loop.parallel`` metadata,
-must be considered a sequential loop. This causes parallel loops to be
+the loop must be considered a sequential loop. This causes parallel loops to be
converted to sequential loops due to optimization passes that are unaware of
the parallel semantics and that insert new memory instructions to the loop
body.
Example of a loop that is considered parallel due to its correct use of
-both ``llvm.loop.parallel`` and ``llvm.mem.parallel_loop_access``
+both ``llvm.loop`` and ``llvm.mem.parallel_loop_access``
metadata types that refer to the same loop identifier metadata.
.. code-block:: llvm
for.body:
- ...
- %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
- ...
- store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
- ...
- br i1 %exitcond, label %for.end, label %for.body, !llvm.loop.parallel !0
+ ...
+ %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0
for.end:
...
...
inner.for.body:
- ...
- %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
- ...
- store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
- ...
- br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop.parallel !1
+ ...
+ %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1
inner.for.end:
- ...
- %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
- ...
- store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
- ...
- br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop.parallel !2
+ ...
+ %0 = load i32* %arrayidx, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ store i32 %0, i32* %arrayidx4, align 4, !llvm.mem.parallel_loop_access !0
+ ...
+ br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2
outer.for.end: ; preds = %for.body
...
- !0 = metadata !{ metadata !1, metadata !2 } ; a list of parallel loop identifiers
- !1 = metadata !{ metadata !1 } ; an identifier for the inner parallel loop
- !2 = metadata !{ metadata !2 } ; an identifier for the outer parallel loop
+ !0 = metadata !{ metadata !1, metadata !2 } ; a list of loop identifiers
+ !1 = metadata !{ metadata !1 } ; an identifier for the inner loop
+ !2 = metadata !{ metadata !2 } ; an identifier for the outer loop
+
+'``llvm.vectorizer``'
+^^^^^^^^^^^^^^^^^^^^^
+
+Metadata prefixed with ``llvm.vectorizer`` is used to control per-loop
+vectorization parameters such as vectorization factor and unroll factor.
+
+``llvm.vectorizer`` metadata should be used in conjunction with ``llvm.loop``
+loop identification metadata.
+
+'``llvm.vectorizer.unroll``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata instructs the loop vectorizer to unroll the specified
+loop exactly ``N`` times.
+
+The first operand is the string ``llvm.vectorizer.unroll`` and the second
+operand is an integer specifying the unroll factor. For example:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ metadata !"llvm.vectorizer.unroll", i32 4 }
+
+Note that setting ``llvm.vectorizer.unroll`` to 1 disables unrolling of the
+loop.
+
+If ``llvm.vectorizer.unroll`` is set to 0 then the amount of unrolling will be
+determined automatically.
+
+'``llvm.vectorizer.width``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata sets the target width of the vectorizer to ``N``. Without
+this metadata, the vectorizer will choose a width automatically.
+Regardless of this metadata, the vectorizer will only vectorize loops if
+it believes it is valid to do so.
+
+The first operand is the string ``llvm.vectorizer.width`` and the second
+operand is an integer specifying the width. For example:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ metadata !"llvm.vectorizer.width", i32 4 }
+Note that setting ``llvm.vectorizer.width`` to 1 disables vectorization of the
+loop.
+
+If ``llvm.vectorizer.width`` is set to 0 then the width will be determined
+automatically.
Module Flags Metadata
=====================
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.
+.. _intrinsicglobalvariables:
+
Intrinsic Global Variables
==========================
"``llvm.metadata``". This section and all globals that start with
"``llvm.``" are reserved for use by LLVM.
+.. _gv_llvmused:
+
The '``llvm.used``' Global Variable
-----------------------------------
The ``@llvm.used`` global is an array which has
- :ref:`appending linkage <linkage_appending>`. This array contains a list of
-pointers to global variables, functions and aliases which may optionally have a
-pointer cast formed of bitcast or getelementptr. For example, a legal
+:ref:`appending linkage <linkage_appending>`. This array contains a list of
+pointers to named global variables, functions and aliases which may optionally
+have a pointer cast formed of bitcast or getelementptr. For example, a legal
use of it is:
.. code-block:: llvm
If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler,
and linker are required to treat the symbol as if there is a reference to the
-symbol that it cannot see. For example, if a variable has internal linkage and
-no references other than that from the ``@llvm.used`` list, it cannot be
-deleted. This is commonly used to represent references from inline asms and
-other things the compiler cannot "see", and corresponds to
-"``attribute((used))``" in GNU C.
+symbol that it cannot see (which is why they have to be named). For example, if
+a variable has internal linkage and no references other than that from the
+``@llvm.used`` list, it cannot be deleted. This is commonly used to represent
+references from inline asms and other things the compiler cannot "see", and
+corresponds to "``attribute((used))``" in GNU C.
On some targets, the code generator must emit a directive to the
assembler or object file to prevent the assembler and linker from
molesting the symbol.
+.. _gv_llvmcompilerused:
+
The '``llvm.compiler.used``' Global Variable
--------------------------------------------
This is a rare construct that should only be used in rare circumstances,
and should not be exposed to source languages.
+.. _gv_llvmglobalctors:
+
The '``llvm.global_ctors``' Global Variable
-------------------------------------------
when the module is loaded. The order of functions with the same priority
is not defined.
+.. _llvmglobaldtors:
+
The '``llvm.global_dtors``' Global Variable
-------------------------------------------
may produce less efficient code. An alignment of 1 is always safe.
The optional ``!nontemporal`` metadata must reference a single
-metatadata name ``<index>`` corresponding to a metadata node with one
+metadata name ``<index>`` corresponding to a metadata node with one
``i32`` entry of value 1. The existence of the ``!nontemporal``
-metatadata on the instruction tells the optimizer and code generator
+metadata on the instruction tells the optimizer and code generator
that this load is not expected to be reused in the cache. The code
generator may select special instructions to save cache bandwidth, such
as the ``MOVNT`` instruction on x86.
The optional ``!invariant.load`` metadata must reference a single
-metatadata name ``<index>`` corresponding to a metadata node with no
-entries. The existence of the ``!invariant.load`` metatadata on the
+metadata name ``<index>`` corresponding to a metadata node with no
+entries. The existence of the ``!invariant.load`` metadata on the
instruction tells the optimizer and code generator that this load
address points to memory which does not change value during program
execution. The optimizer may then move this load around, for example, by
alignment may produce less efficient code. An alignment of 1 is always
safe.
-The optional ``!nontemporal`` metadata must reference a single metatadata
+The optional ``!nontemporal`` metadata must reference a single metadata
name ``<index>`` corresponding to a metadata node with one ``i32`` entry of
-value 1. The existence of the ``!nontemporal`` metatadata on the instruction
+value 1. The existence of the ``!nontemporal`` metadata on the instruction
tells the optimizer and code generator that this load is not expected to
be reused in the cache. The code generator may select special
instructions to save cache bandwidth, such as the MOVNT instruction on
The '``bitcast``' instruction takes a value to cast, which must be a
non-aggregate first class value, and a type to cast it to, which must
-also be a non-aggregate :ref:`first class <t_firstclass>` type. The bit
-sizes of ``value`` and the destination type, ``ty2``, must be identical.
-If the source type is a pointer, the destination type must also be a
-pointer. This instruction supports bitwise conversion of vectors to
-integers and to vectors of other types (as long as they have the same
-size).
+also be a non-aggregate :ref:`first class <t_firstclass>` type. The
+bit sizes of ``value`` and the destination type, ``ty2``, must be
+identical. If the source type is a pointer, the destination type must
+also be a pointer of the same size. This instruction supports bitwise
+conversion of vectors to integers and to vectors of other types (as
+long as they have the same size).
Semantics:
""""""""""
-The '``bitcast``' instruction converts ``value`` to type ``ty2``. It is
-always a *no-op cast* because no bits change with this conversion. The
-conversion is done as if the ``value`` had been stored to memory and
-read back as type ``ty2``. Pointer (or vector of pointers) types may
-only be converted to other pointer (or vector of pointers) types with
-this instruction. To convert pointers to other types, use the
-:ref:`inttoptr <i_inttoptr>` or :ref:`ptrtoint <i_ptrtoint>` instructions
-first.
+The '``bitcast``' instruction converts ``value`` to type ``ty2``. It
+is always a *no-op cast* because no bits change with this
+conversion. The conversion is done as if the ``value`` had been stored
+to memory and read back as type ``ty2``. Pointer (or vector of
+pointers) types may only be converted to other pointer (or vector of
+pointers) types with the same address space through this instruction.
+To convert pointers to other types, use the :ref:`inttoptr <i_inttoptr>`
+or :ref:`ptrtoint <i_ptrtoint>` instructions first.
Example:
""""""""
%Z = bitcast <2 x int> %V to i64; ; yields i64: %V
%Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
+.. _i_addrspacecast:
+
+'``addrspacecast .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = addrspacecast <pty> <ptrval> to <pty2> ; yields pty2
+
+Overview:
+"""""""""
+
+The '``addrspacecast``' instruction converts ``ptrval`` from ``pty`` in
+address space ``n`` to type ``pty2`` in address space ``m``.
+
+Arguments:
+""""""""""
+
+The '``addrspacecast``' instruction takes a pointer or vector of pointer value
+to cast and a pointer type to cast it to, which must have a different
+address space.
+
+Semantics:
+""""""""""
+
+The '``addrspacecast``' instruction converts the pointer value
+``ptrval`` to type ``pty2``. It can be a *no-op cast* or a complex
+value modification, depending on the target and the address space
+pair. Pointer conversions within the same address space must be
+performed with the ``bitcast`` instruction. Note that if the address space
+conversion is legal then both result and operand refer to the same memory
+location.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = addrspacecast i32* %x to i32 addrspace(1)* ; yields i32 addrspace(1)*:%x
+ %Y = addrspacecast i32 addrspace(1)* %y to i64 addrspace(2)* ; yields i64 addrspace(2)*:%y
+ %Z = addrspacecast <4 x i32*> %z to <4 x float addrspace(3)*> ; yields <4 x float addrspace(3)*>:%z
+
.. _otherops:
Other Operations
::
- declare void
%llvm.va_start(i8* <arglist>)
+ declare void
@llvm.va_start(i8* <arglist>)
Overview:
"""""""""
specific value or a system wide value. On backends without support, this
is lowered to a constant 0.
+Note that runtime support may be conditional on the privilege-level code is
+running at and the host platform.
+
Standard C Library Intrinsics
-----------------------------
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
-argument, otherwise it should be set to 0 or 1.
+argument, otherwise it should be set to 0 or 1 (both meaning no alignment).
'``llvm.memmove``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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,
-otherwise it should be set to 0 or 1.
+otherwise it should be set to 0 or 1 (both meaning no alignment).
'``llvm.memset.*``' Intrinsics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting
at the destination location. If the argument is known to be aligned to
some boundary, this can be specified as the fourth argument, otherwise
-it should be set to 0 or 1.
+it should be set to 0 or 1 (both meaning no alignment).
'``llvm.sqrt.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^
This function returns the same values as the libm ``fabs`` functions
would, and handles error conditions in the same way.
+'``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
+all types however.
+
+::
+
+ declare float @llvm.copysign.f32(float %Mag, float %Sgn)
+ declare double @llvm.copysign.f64(double %Mag, double %Sgn)
+ declare x86_fp80 @llvm.copysign.f80(x86_fp80 %Mag, x86_fp80 %Sgn)
+ declare fp128 @llvm.copysign.f128(fp128 %Mag, fp128 %Sgn)
+ declare ppc_fp128 @llvm.copysign.ppcf128(ppc_fp128 %Mag, ppc_fp128 %Sgn)
+
+Overview:
+"""""""""
+
+The '``llvm.copysign.*``' intrinsics return a value with the magnitude of the
+first operand and the sign of the second operand.
+
+Arguments:
+""""""""""
+
+The arguments and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``copysign``
+functions would, and handles error conditions in the same way.
+
'``llvm.floor.*``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This function returns the same values as the libm ``nearbyint``
functions would, and handles error conditions in the same way.
+'``llvm.round.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+all types however.
+
+::
+
+ declare float @llvm.round.f32(float %Val)
+ declare double @llvm.round.f64(double %Val)
+ declare x86_fp80 @llvm.round.f80(x86_fp80 %Val)
+ declare fp128 @llvm.round.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.round.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.round.*``' intrinsics returns the operand rounded to the
+nearest integer.
+
+Arguments:
+""""""""""
+
+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.
+
Bit Manipulation Intrinsics
---------------------------
Semantics:
""""""""""
-This intrinsic causes the prologue/epilogue inserter to force the
-position of the ``AllocaInst`` stack slot to be before local variables
-on the stack. This is to ensure that if a local variable on the stack is
-overwritten, it will destroy the value of the guard. When the function
-exits, the guard on the stack is checked against the original guard. If
-they are different, then the program aborts by calling the
+This intrinsic causes the prologue/epilogue inserter to force the position of
+the ``AllocaInst`` stack slot to be before local variables on the stack. This is
+to ensure that if a local variable on the stack is overwritten, it will destroy
+the value of the guard. When the function exits, the guard on the stack is
+checked against the original guard by ``llvm.stackprotectorcheck``. If they are
+different, then ``llvm.stackprotectorcheck`` causes the program to abort by
+calling the ``__stack_chk_fail()`` function.
+
+'``llvm.stackprotectorcheck``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.stackprotectorcheck(i8** <guard>)
+
+Overview:
+"""""""""
+
+The ``llvm.stackprotectorcheck`` intrinsic compares ``guard`` against an already
+created stack protector and if they are not equal calls the
``__stack_chk_fail()`` function.
+Arguments:
+""""""""""
+
+The ``llvm.stackprotectorcheck`` intrinsic requires one pointer argument, the
+the variable ``@__stack_chk_guard``.
+
+Semantics:
+""""""""""
+
+This intrinsic is provided to perform the stack protector check by comparing
+``guard`` with the stack slot created by ``llvm.stackprotector`` and if the
+values do not match call the ``__stack_chk_fail()`` function.
+
+The reason to provide this as an IR level intrinsic instead of implementing it
+via other IR operations is that in order to perform this operation at the IR
+level without an intrinsic, one would need to create additional basic blocks to
+handle the success/failure cases. This makes it difficult to stop the stack
+protector check from disrupting sibling tail calls in Codegen. With this
+intrinsic, we are able to generate the stack protector basic blocks late in
+codegen after the tail call decision has occurred.
+
'``llvm.objectsize``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
projects / oota-llvm.git / blobdiff