X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FLangRef.rst;h=167280f75f7fdeec3f6201e3dd7fa3a32961ed43;hb=abdd9e7330c1a36a31df65c278c7c7b6bace7c2a;hp=24765870dbfbb131cb43673186f7bbb6afcc362c;hpb=d6a9af6fd3de106e509eff11f840aa194236aac1;p=oota-llvm.git diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 24765870dbf..167280f75f7 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -635,8 +635,9 @@ attributes `), optional :ref:`function attributes `, an optional section, an optional alignment, an optional :ref:`comdat `, an optional :ref:`garbage collector name `, an optional :ref:`prefix `, -an optional :ref:`prologue `, an opening -curly brace, a list of basic blocks, and a closing curly brace. +an optional :ref:`prologue `, +an optional :ref:`personality `, +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 `, an optional :ref:`visibility @@ -683,7 +684,8 @@ Syntax:: [cconv] [ret attrs] @ ([argument list]) [unnamed_addr] [fn Attrs] [section "name"] [comdat [($name)]] - [align N] [gc] [prefix Constant] [prologue Constant] { ... } + [align N] [gc] [prefix Constant] [prologue Constant] + [personality Constant] { ... } The argument list is a comma seperated sequence of arguments where each argument is of the following form @@ -821,9 +823,11 @@ with the same name. This is necessary because both globals belong to different COMDAT groups and COMDATs, at the object file level, are represented by sections. -Note that certain IR constructs like global variables and functions may create -COMDATs in the object file in addition to any which are specified using COMDAT -IR. This arises, for example, when a global variable has linkonce_odr linkage. +Note that certain IR constructs like global variables and functions may +create COMDATs in the object file in addition to any which are specified using +COMDAT IR. This arises when the code generator is configured to emit globals +in individual sections (e.g. when `-data-sections` or `-function-sections` +is supplied to `llc`). .. _namedmetadatastructure: @@ -834,6 +838,11 @@ Named metadata is a collection of metadata. :ref:`Metadata nodes ` (but not metadata strings) are the only valid operands for a named metadata. +#. Named metadata are represented as a string of characters with the + metadata prefix. The rules for metadata names are the same as for + identifiers, but quoted names are not allowed. ``"\xx"`` type escapes + are still valid, which allows any character to be part of a name. + Syntax:: ; Some unnamed metadata nodes, which are referenced by the named metadata. @@ -1125,6 +1134,14 @@ A function may have prologue 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. +.. _personalityfn: + +Personality Function +-------------------- + +The ``personality`` attribute permits functions to specify what function +to use for exception handling. + .. _attrgrp: Attribute Groups @@ -1196,6 +1213,13 @@ example: computing edge weights, basic blocks post-dominated by a cold function call are also considered to be cold; and, thus, given low weight. +``convergent`` + This attribute indicates that the callee is dependent on a convergent + thread execution pattern under certain parallel execution models. + Transformations that are execution model agnostic may only move or + tranform this call if the final location is control equivalent to its + original position in the program, where control equivalence is defined as + A dominates B and B post-dominates A, or vice versa. ``inlinehint`` This attribute indicates that the source code contained a hint that inlining this function is desirable (such as the "inline" keyword in @@ -1307,6 +1331,15 @@ example: ``setjmp`` is an example of such a function. The compiler disables some optimizations (like tail calls) in the caller of these functions. +``safestack`` + This attribute indicates that + `SafeStack `_ + protection is enabled for this function. + + If a function that has a ``safestack`` attribute is inlined into a + function that doesn't have a ``safestack`` attribute or which has an + ``ssp``, ``sspstrong`` or ``sspreq`` attribute, then the resulting + function will have a ``safestack`` attribute. ``sanitize_address`` This attribute indicates that AddressSanitizer checks (dynamic address safety analysis) are enabled for this function. @@ -2961,7 +2994,7 @@ DIFile Files are sometimes used in ``scope:`` fields, and are the only valid target for ``file:`` fields. -.. _DILocation: +.. _DIBasicType: DIBasicType """"""""""" @@ -3225,6 +3258,8 @@ discriminate between control flow within a single block in the source language. !1 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 0) !2 = !DILexicalBlockFile(scope: !0, file: !4, discriminator: 1) +.. _DILocation: + DILocation """""""""" @@ -3607,7 +3642,7 @@ will be partially unrolled. '``llvm.loop.unroll.disable``' Metadata ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This metadata either disables loop unrolling. The metadata has a single operand +This metadata disables loop unrolling. The metadata has a single operand which is the string ``llvm.loop.unroll.disable``. For example: .. code-block:: llvm @@ -3617,7 +3652,7 @@ which is the string ``llvm.loop.unroll.disable``. For example: '``llvm.loop.unroll.runtime.disable``' Metadata ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This metadata either disables runtime loop unrolling. The metadata has a single +This metadata disables runtime loop unrolling. The metadata has a single operand which is the string ``llvm.loop.unroll.runtime.disable``. For example: .. code-block:: llvm @@ -3627,8 +3662,8 @@ operand which is the string ``llvm.loop.unroll.runtime.disable``. For example: '``llvm.loop.unroll.full``' Metadata ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This metadata either suggests that the loop should be unrolled fully. The -metadata has a single operand which is the string ``llvm.loop.unroll.disable``. +This metadata suggests that the loop should be unrolled fully. The +metadata has a single operand which is the string ``llvm.loop.unroll.full``. For example: .. code-block:: llvm @@ -5656,7 +5691,7 @@ Syntax: :: - = load [volatile] , * [, align ][, !nontemporal !][, !invariant.load !][, !nonnull !] + = load [volatile] , * [, align ][, !nontemporal !][, !invariant.load !][, !nonnull !][, !dereferenceable !][, !dereferenceable_or_null !] = load atomic [volatile] * [singlethread] , align ! = !{ i32 1 } @@ -5721,6 +5756,25 @@ never be null. This is analogous to the ''nonnull'' attribute on parameters and return values. This metadata can only be applied to loads of a pointer type. +The optional ``!dereferenceable`` metadata must reference a single +metadata name ```` corresponding to a metadata node with one ``i64`` +entry. The existence of the ``!dereferenceable`` metadata on the instruction +tells the optimizer that the value loaded is known to be dereferenceable. +The number of bytes known to be dereferenceable is specified by the integer +value in the metadata node. This is analogous to the ''dereferenceable'' +attribute on parameters and return values. This metadata can only be applied +to loads of a pointer type. + +The optional ``!dereferenceable_or_null`` metadata must reference a single +metadata name ```` corresponding to a metadata node with one ``i64`` +entry. The existence of the ``!dereferenceable_or_null`` metadata on the +instruction tells the optimizer that the value loaded is known to be either +dereferenceable or null. +The number of bytes known to be dereferenceable is specified by the integer +value in the metadata node. This is analogous to the ''dereferenceable_or_null'' +attribute on parameters and return values. This metadata can only be applied +to loads of a pointer type. + Semantics: """""""""" @@ -7241,8 +7295,8 @@ Syntax: :: - = landingpad personality + - = landingpad personality cleanup * + = landingpad + + = landingpad cleanup * := catch := filter @@ -7254,14 +7308,13 @@ The '``landingpad``' instruction is used by `LLVM's exception handling system `_ to specify that a basic block is a landing pad --- one where the exception lands, and corresponds to the code found in the ``catch`` portion of a ``try``/``catch`` sequence. It -defines values supplied by the personality function (``pers_fn``) upon +defines values supplied by the :ref:`personality function ` upon re-entry to the function. The ``resultval`` has the type ``resultty``. Arguments: """""""""" -This instruction takes a ``pers_fn`` value. This is the personality -function associated with the unwinding mechanism. The optional +The optional ``cleanup`` flag indicates that the landing pad block is a cleanup. A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and @@ -7276,7 +7329,7 @@ Semantics: """""""""" The '``landingpad``' instruction defines the values which are set by the -personality function (``pers_fn``) upon re-entry to the function, and +:ref:`personality function ` upon re-entry to the function, and therefore the "result type" of the ``landingpad`` instruction. As with calling conventions, how the personality function results are represented in LLVM IR is target specific. @@ -7299,8 +7352,6 @@ The ``landingpad`` instruction has several restrictions: pad block. - A basic block that is not a landing pad block may not include a '``landingpad``' instruction. -- All '``landingpad``' instructions in a function must have the same - personality function. Example: """""""" @@ -7308,13 +7359,13 @@ Example: .. code-block:: llvm ;; A landing pad which can catch an integer. - %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 + %res = landingpad { i8*, i32 } catch i8** @_ZTIi ;; A landing pad that is a cleanup. - %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 + %res = landingpad { i8*, i32 } cleanup ;; A landing pad which can catch an integer and can only throw a double. - %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0 + %res = landingpad { i8*, i32 } catch i8** @_ZTIi filter [1 x i8**] [@_ZTId]