X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;ds=sidebyside;f=docs%2FLangRef.rst;h=c7ceb73da3782424401ea884ee5c2812e30880dc;hb=e022bf60866ddf5e612958aae651505a8efc3d6e;hp=7be5442cc7ed6f038e65ba1bbc3bdfb51ce95a03;hpb=767c34a919c850c7f96b663aa4c70846398ec565;p=oota-llvm.git diff --git a/docs/LangRef.rst b/docs/LangRef.rst index 7be5442cc7e..c7ceb73da37 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -4421,6 +4421,50 @@ the loop identifier metadata node directly: The ``llvm.bitsets`` global metadata is used to implement :doc:`bitsets `. +'``invariant.group``' Metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``invariant.group`` metadata may be attached to ``load``/``store`` instructions. +The existence of the ``invariant.group`` metadata on the instruction tells +the optimizer that every ``load`` and ``store`` to the same pointer operand +within the same invariant group can be assumed to load or store the same +value (but see the ``llvm.invariant.group.barrier`` intrinsic which affects +when two pointers are considered the same). + +Examples: + +.. code-block:: llvm + + @unknownPtr = external global i8 + ... + %ptr = alloca i8 + store i8 42, i8* %ptr, !invariant.group !0 + call void @foo(i8* %ptr) + + %a = load i8, i8* %ptr, !invariant.group !0 ; Can assume that value under %ptr didn't change + call void @foo(i8* %ptr) + %b = load i8, i8* %ptr, !invariant.group !1 ; Can't assume anything, because group changed + + %newPtr = call i8* @getPointer(i8* %ptr) + %c = load i8, i8* %newPtr, !invariant.group !0 ; Can't assume anything, because we only have information about %ptr + + %unknownValue = load i8, i8* @unknownPtr + store i8 %unknownValue, i8* %ptr, !invariant.group !0 ; Can assume that %unknownValue == 42 + + call void @foo(i8* %ptr) + %newPtr2 = call i8* @llvm.invariant.group.barrier(i8* %ptr) + %d = load i8, i8* %newPtr2, !invariant.group !0 ; Can't step through invariant.group.barrier to get value of %ptr + + ... + declare void @foo(i8*) + declare i8* @getPointer(i8*) + declare i8* @llvm.invariant.group.barrier(i8*) + + !0 = !{!"magic ptr"} + !1 = !{!"other ptr"} + + + Module Flags Metadata ===================== @@ -6768,9 +6812,10 @@ Syntax: :: - = load [volatile] , * [, align ][, !nontemporal !][, !invariant.load !][, !nonnull !][, !dereferenceable !][, !dereferenceable_or_null !] - = load atomic [volatile] * [singlethread] , align + = load [volatile] , * [, align ][, !nontemporal !][, !invariant.load !][, !invariant.group !][, !nonnull !][, !dereferenceable !][, !dereferenceable_or_null !] + = load atomic [volatile] * [singlethread] , align [, !invariant.group !] ! = !{ i32 1 } + ! = !{i64 } Overview: """"""""" @@ -6825,6 +6870,9 @@ Being invariant does not imply that a location is dereferenceable, but it does imply that once the location is known dereferenceable its value is henceforth unchanging. +The optional ``!invariant.group`` metadata must reference a single metadata name + ```` corresponding to a metadata node. See ``invariant.group`` metadata. + The optional ``!nonnull`` metadata must reference a single metadata name ```` corresponding to a metadata node with no entries. The existence of the ``!nonnull`` metadata on the @@ -6833,8 +6881,8 @@ 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`` +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 @@ -6843,8 +6891,8 @@ 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 +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 @@ -6882,8 +6930,8 @@ Syntax: :: - store [volatile] , * [, align ][, !nontemporal !] ; yields void - store atomic [volatile] , * [singlethread] , align ; yields void + store [volatile] , * [, align ][, !nontemporal !][, !invariant.group !] ; yields void + store atomic [volatile] , * [singlethread] , align [, !invariant.group !] ; yields void Overview: """"""""" @@ -6930,6 +6978,9 @@ 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.group`` metadata must reference a +single metadata name ````. See ``invariant.group`` metadata. + Semantics: """""""""" @@ -11465,6 +11516,36 @@ Semantics: This intrinsic indicates that the memory is mutable again. +'``llvm.invariant.group.barrier``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" + +:: + + declare i8* @llvm.invariant.group.barrier(i8* ) + +Overview: +""""""""" + +The '``llvm.invariant.group.barrier``' intrinsic can be used when an invariant +established by invariant.group metadata no longer holds, to obtain a new pointer +value that does not carry the invariant information. + + +Arguments: +"""""""""" + +The ``llvm.invariant.group.barrier`` takes only one argument, which is +the pointer to the memory for which the ``invariant.group`` no longer holds. + +Semantics: +"""""""""" + +Returns another pointer that aliases its argument but which is considered different +for the purposes of ``load``/``store`` ``invariant.group`` metadata. + General Intrinsics ------------------