Index: docs/LangRef.rst =================================================================== --- docs/LangRef.rst +++ docs/LangRef.rst @@ -4421,6 +4421,50 @@ The ``llvm.bitsets`` global metadata is used to implement :doc:`bitsets `. +'``invariant.group``' Metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``invariant.group`` metadata may be attached to ``load``/``store`` instruction. +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,8 +6812,8 @@ :: - = 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 } Overview: @@ -6825,6 +6869,9 @@ 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 @@ -6882,8 +6929,8 @@ :: - 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 +6977,9 @@ 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 +11515,36 @@ 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 ------------------