.. 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``.
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
The linkage must be one of ``private``, ``linker_private``,
``linker_private_weak``, ``internal``, ``linkonce``, ``weak``,
-``linkonce_odr``, ``weak_odr``, ``linkonce_odr_auto_hide``, ``external``. Note
-that some system linkers might not correctly handle dropping a weak symbol that
-is aliased by a non weak alias.
+``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:
site. If the alignment is not specified, then the code generator
makes a target-specific assumption.
+.. _attr_inalloca:
+
+``inalloca``
+
+.. Warning:: This feature is unstable and not fully implemented.
+
+ The ``inalloca`` argument attribute allows the caller to get the
+ address of an outgoing argument to a ``call`` or ``invoke`` before
+ it executes. It is similar to ``byval`` in that it is used to pass
+ arguments by value, but it guarantees that the argument will not be
+ copied.
+
+ To be :ref:`well formed <wellformed>`, the caller must pass in an
+ alloca value into an ``inalloca`` parameter, and an alloca may be
+ used as an ``inalloca`` argument at most once. The attribute can
+ only be applied to parameters that would be passed in memory and not
+ registers. The ``inalloca`` attribute cannot be used in conjunction
+ with other attributes that affect argument storage, like ``inreg``,
+ ``nest``, ``sret``, or ``byval``. The ``inalloca`` stack space is
+ considered to be clobbered by any call that uses it, so any
+ ``inalloca`` parameters cannot be marked ``readonly``.
+
+ Allocas passed with ``inalloca`` to a call must be in the opposite
+ order of the parameter list, meaning that the rightmost argument
+ must be allocated first. If a call has inalloca arguments, no other
+ allocas can occur between the first alloca used by the call and the
+ call site, unless they are are cleared by calls to
+ :ref:`llvm.stackrestore <int_stackrestore>`. Violating these rules
+ results in undefined behavior at runtime.
+
+ See :doc:`InAlloca` for more information on how to use this
+ attribute.
+
``sret``
This indicates that the pointer parameter specifies the address of a
structure that is the return value of the function in the source
attribute; this attribute is also incompatible
with the ``minsize`` attribute and the ``optsize`` attribute.
- The inliner should never inline this function in any situation.
+ 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 inside the body of this function.
+ 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,
- ``f128:128:128`` - quad is 128-bit aligned
- ``v64:64:64`` - 64-bit vector is 64-bit aligned
- ``v128:128:128`` - 128-bit vector is 128-bit aligned
-- ``a0:0:64`` - aggregates are 64-bit aligned
+- ``a:0:64`` - aggregates are 64-bit aligned
When LLVM is determining the alignment for a given type, it uses the
following rules:
generated code and enables novel analyses and transformations that are
not feasible to perform on normal three address code representations.
-.. _typeclassifications:
+.. _t_void:
-Type Classifications
---------------------
+Void Type
+---------
-The types fall into a few useful classifications:
+: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:
+
+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 void type or first class type --- except for :ref:`label <t_label>`
+and :ref:`metadata <t_metadata>` types.
+
+: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>` and :ref:`metadata <t_metadata>`.
- .. _t_firstclass:
+:Examples:
- - :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>`.
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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 |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- * - :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>`.
+.. _t_firstclass:
- * - :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>`.
+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:
-"""""""""
+: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:
-"""""""
+:Syntax:
::
value.
Examples:
-"""""""""
+*********
+----------------+------------------------------------------------+
| ``i1`` | a single-bit integer. |
.. _t_floating:
Floating Point Types
-^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""
.. list-table::
:header-rows: 1
.. _t_x86mmx:
X86mmx Type
-^^^^^^^^^^^
+"""""""""""
-Overview:
-"""""""""
+: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
and/or results of this type. There are no arrays, vectors or constants
of this type.
-Syntax:
-"""""""
+:Syntax:
::
x86mmx
-.. _t_void:
-Void Type
-^^^^^^^^^
+.. _t_pointer:
-Overview:
-"""""""""
+Pointer Type
+""""""""""""
-The void type does not represent any value and has no size.
+:Overview:
-Syntax:
-"""""""
+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:
Label Type
^^^^^^^^^^
-Overview:
-"""""""""
+:Overview:
The label type represents code labels.
-Syntax:
-"""""""
+:Syntax:
::
Metadata Type
^^^^^^^^^^^^^
-Overview:
-"""""""""
+:Overview:
The metadata type represents embedded metadata. No derived types may be
created from metadata except for :ref:`function <t_function>` arguments.
-Syntax:
-"""""""
+:Syntax:
::
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:
-"""""""""
+: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:
-"""""""
+:Syntax:
::
The number of elements is a constant integer value; ``elementtype`` may
be any type with a size.
-Examples:
-"""""""""
+: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 void type or first class type --- except for :ref:`label <t_label>`
-and :ref:`metadata <t_metadata>` types.
-
-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>` 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_struct:
Structure Type
-^^^^^^^^^^^^^^
+""""""""""""""
-Overview:
-"""""""""
+: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
or opaque since there is no way to write one. Identified types can be
recursive, can be opaqued, and are never uniqued.
-Syntax:
-"""""""
+:Syntax:
::
%T1 = type { <type list> } ; Identified normal struct type
%T2 = type <{ <type list> }> ; Identified packed struct type
-Examples:
-"""""""""
+:Examples:
+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values |
.. _t_opaque:
Opaque Structure Types
-^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""
-Overview:
-"""""""""
+: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:
-"""""""
+:Syntax:
::
%X = type opaque
%52 = type opaque
-Examples:
-"""""""""
+: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
=========
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>`
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 if the pointer sizes are
-equal. To convert pointers to other types, use the :ref:`inttoptr
-<i_inttoptr>` or :ref:`ptrtoint <i_ptrtoint>` instructions first.
+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
This class of intrinsics exists to information about the lifetime of
memory objects and ranges where variables are immutable.
+.. _int_lifestart:
+
'``llvm.lifetime.start``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
to never be used and has an undefined value. A load from the pointer
that precedes this intrinsic can be replaced with ``'undef'``.
+.. _int_lifeend:
+
'``llvm.lifetime.end``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
projects / oota-llvm.git / blobdiff