diff options
Diffstat (limited to 'docs/LangRef.rst')
| -rw-r--r-- | docs/LangRef.rst | 366 |
1 files changed, 312 insertions, 54 deletions
diff --git a/docs/LangRef.rst b/docs/LangRef.rst index b69e2a3..810455c 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -128,7 +128,9 @@ lexical features of LLVM: #. 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 @@ -267,13 +269,6 @@ linkage: ``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 @@ -305,9 +300,6 @@ declarations), they are accessible outside of the current module. 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 @@ -448,9 +440,13 @@ Global Variables ---------------- 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 @@ -532,6 +528,12 @@ with an initializer, section, and alignment: @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: @@ -552,27 +554,26 @@ an optional ``unnamed_addr`` attribute, a return type, an optional 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 @@ -598,7 +599,7 @@ Syntax:: [cconv] [ret attrs] <ResultType> @<FunctionName> ([argument list]) [fn Attrs] [section "name"] [align N] - [gc] { ... } + [gc] [prefix Constant] { ... } .. _langref_aliases: @@ -614,6 +615,12 @@ Syntax:: @<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 @@ -757,6 +764,55 @@ The compiler declares the supported values of *name*. Specifying a 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 @@ -833,6 +889,11 @@ example: 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. @@ -874,10 +935,23 @@ example: 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`` On a function, this attribute indicates that the function computes its result (or decides to unwind an exception) based strictly on its arguments, @@ -887,7 +961,7 @@ example: (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. @@ -901,7 +975,7 @@ example: 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. @@ -1109,6 +1183,30 @@ don't have to specify the string. This will disable some optimizations 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 @@ -1659,9 +1757,10 @@ 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. +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: """"""" @@ -1671,11 +1770,11 @@ 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>`. +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: """"""""" @@ -2286,6 +2385,10 @@ The following is the syntax for 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>` @@ -5630,9 +5733,9 @@ 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 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: """""""" @@ -5644,6 +5747,51 @@ 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 @@ -6293,7 +6441,7 @@ Syntax: :: - declare void %llvm.va_start(i8* <arglist>) + declare void @llvm.va_start(i8* <arglist>) Overview: """"""""" @@ -6805,7 +6953,7 @@ The '``llvm.memcpy.*``' intrinsics copy a block of memory from the source location to the destination location, which are not allowed to overlap. It copies "len" bytes of memory over. If the argument is known to be aligned to some boundary, this can be specified as the fourth -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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -6860,7 +7008,7 @@ The '``llvm.memmove.*``' intrinsics copy a block of memory from the source location to the destination location, which may overlap. It copies "len" bytes of memory over. If the argument is known to be aligned to some boundary, this can be specified as the fourth argument, -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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -6911,7 +7059,7 @@ Semantics: 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -7347,6 +7495,42 @@ Semantics: 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -7526,6 +7710,42 @@ Semantics: 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 --------------------------- @@ -8599,14 +8819,52 @@ enough space to hold the value of the guard. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |