.. 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``.
----------------
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 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 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.
+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
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:
``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
+ 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
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
+ 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.
-
- 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,
(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.
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.
generated code and enables novel analyses and transformations that are
not feasible to perform on normal three address code representations.
-.. _typeclassifications:
+.. _t_void:
+
+Void Type
+---------
-Type Classifications
---------------------
+Overview:
+^^^^^^^^^
-The types fall into a few useful classifications:
+The void type does not represent any value and has no size.
+Syntax:
+^^^^^^^
-.. list-table::
- :header-rows: 1
+::
+
+ void
+
+
+.. _t_function:
+
+Function Type
+-------------
+
+Overview:
+^^^^^^^^^
- * - Classification
- - Types
+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:`integer <t_integer>`
- - ``i1``, ``i2``, ``i3``, ... ``i8``, ... ``i16``, ... ``i32``, ...
- ``i64``, ...
+Syntax:
+^^^^^^^
- * - :ref:`floating point <t_floating>`
- - ``half``, ``float``, ``double``, ``x86_fp80``, ``fp128``,
- ``ppc_fp128``
+::
+ <returntype> (<parameter list>)
- * - first class
+...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:
-"""""""""
+*********
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
=========
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
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 occured.
+codegen after the tail call decision has occurred.
'``llvm.objectsize``' Intrinsic
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
projects / oota-llvm.git / blobdiff