invariant.group and invariant.group.barrier docs

[nlewycky]

docs/LangRef.rst

6872

Typo "referenece"

6876

Typo "loados"

6877

Consider:
(but see the @llvm.invariant.barrier() intrinsic which affects when two pointers are considered the same).

6980

Typo "referenece"

6984

Typo "loados"

6985

Consider:
(but see the @llvm.invariant.barrier() intrinsic which affects when two pointers are considered the same).

11567–11568

I'd remove "specifies that given a pointer," and switch "the first" with "its argument" and "produces" with "returns":

The '``llvm.invariant.group.barrier``' intrinsic returns another pointer that aliases its argument but which is considered different for the purposes of load/store !invariant.group metadata.

11580–11581

Consider:
This intrinsic produces a copy of its argument, except that it is a distinct pointer for the purposes of the !invariant.group metadata.

[rsmith]

docs/LangRef.rst

6874

existance -> existence

6876

have the same -> has the same
loados -> loads

6877

This suggests that any such call could affect the loads. I think the right model is that the @llvm.invariant.group.barrier returns a different pointer value. That makes this parenthetical redundant, since "same pointer value" is already a side-condition.

6932–6934

invariant.group.barrier -> invariant.group

6980–6985

Same comments as above.

6982

existance -> existence

6984

that have -> that has
loados -> loads

11575

might changed -> might have changed

... but I don't think that's quite what we want to say. Something like:

the pointer to the memory for which the invariant no longer holds

maybe?

11580–11581

I don't think it's accurate to say this affects the "next" load/store. The text in the "Overview" section seems like a good fit for a semantic description of the intrinsic. Maybe in the overview you could put something more general like "The <...> 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."

11583–11587

Delete this, we already have this heading on line 10151.

[reames]

docs/LangRef.rst

6875

The fact that it's the llvm::Value of a pointer that matters and not it's runtime value (aka the actual address) is non-obvious from this description.

6876

The comma in "value, that" seems misplaced. I think you intend something like the following:
"every load and store to the same pointer operand within the same invariant group (i.e. index), can be assume to load or store the same bit value..."

6878–6879

Stray change, please submit separately.

6980

Given the repetition here, I'd suggest adding a new subsection defining the notion of an invariant group and then reference that from the per instruction description.

[Prazek]

Getting ready to push it to master with invariant.group.barrier implementation

[Prazek]

@reames ping. I want to push it with http://reviews.llvm.org/D12310

[nlewycky]

docs/LangRef.rst

4427

"atached" --> "attached"

4430

"can be assume" --> "can be assumed"

4430

What does it mean to be assumed to store the same bit value? In the case of loads I think it means that the load must return the same value. Is the store stating that the store must be storing the same value, that is the value operand of the two stores is bit equivalent?

4582–4583

This should either be removed or committed independently.

11545

"it's" --> "its"

11554

Either revert this newline or commit it independently if correct.

[Prazek]

docs/LangRef.rst

4430

I don't understand what you are saying. It means that 2 stores with the same invariant.group and same operand must store the same value

[rsmith]

docs/LangRef.rst

4430

Remove the word "bit" here, just "load or store the same value".

4444–4445

You should insert a call between these two, since otherwise we can assume they load the same value because the value cannot have changed between the two loads.

4454

Again, insert a call before this load, since otherwise we can prove that this loads 42 because we just saw a store of 42 to the same region of memory.

[rsmith]

LGTM, I think you've addressed everyone's feedback.

docs/LangRef.rst

4427

instruction -> instructions

4430

Remove the comma here.

docs/LangRef.rst

.. code-block:: llvm
    !2 = !{!2} ; an identifier for the outer loop
 
 '``llvm.bitsets``'
 ^^^^^^^^^^^^^^^^^^
 
 The ``llvm.bitsets`` global metadata is used to implement
 :doc:`bitsets <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
 =====================
 
 Information about the module as a whole is difficult to convey to LLVM's
 subsystems. The LLVM IR isn't sufficient to transmit this information.
 The ``llvm.module.flags`` named metadata exists in order to facilitate
 this. These flags are in the form of key / value pairs --- much like a
 dictionary --- making it easy for any subsystem who cares about a flag to
-  Metadata ``!3`` has the ID ``!"qux"`` and the value:
    ::
 
        !{ !"foo", i32 1 }
 
    The behavior is to emit an error if the ``llvm.module.flags`` does not
    contain a flag with the ID ``!"foo"`` that has the value '1' after linking is
    performed.
 
 Objective-C Garbage Collection Module Flags Metadata
 ----------------------------------------------------
 
 On the Mach-O platform, Objective-C stores metadata about garbage
 collection in a special section called "image info". The metadata
 consists of a version number and a bitmask specifying what types of
 garbage collection are supported (if any) by the file. If two or more
 modules are linked together their garbage collection metadata needs to
 be merged rather than appended together.
 

 '``load``' Instruction
 ^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
-      <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !nonnull !<index>][, !dereferenceable !<index>][, !dereferenceable_or_null !<index>]
-      <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
+      <result> = load [volatile] <ty>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>][, !invariant.group !<index>][, !nonnull !<index>][, !dereferenceable !<index>][, !dereferenceable_or_null !<index>]
+      <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment> [, !invariant.group !<index>]
       !<index> = !{ i32 1 }
 
 Overview:
 """""""""
 
 The '``load``' instruction is used to read from memory.
 
 Arguments:

 metadata name ``<index>`` corresponding to a metadata node with no
 entries. The existence of the ``!invariant.load`` metadata on the
 instruction tells the optimizer and code generator that the address
 operand to this load points to memory which can be assumed unchanged.
 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
+ ``<index>`` corresponding to a metadata node. See ``invariant.group`` metadata.
+
 The optional ``!nonnull`` metadata must reference a single
 metadata name ``<index>`` corresponding to a metadata node with no
 entries. The existence of the ``!nonnull`` metadata on the
 instruction tells the optimizer that the value loaded is known to
 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 ``<index>`` 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

 '``store``' Instruction
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
-      store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]        ; yields void
-      store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment>  ; yields void
+      store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.group !<index>]        ; yields void
+      store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> [, !invariant.group !<index>] ; yields void
 
 Overview:
 """""""""
 
 The '``store``' instruction is used to write to memory.
 
 Arguments:
 """"""""""
 

 The optional ``!nontemporal`` metadata must reference a single metadata
 name ``<index>`` corresponding to a metadata node with one ``i32`` entry of
 value 1. The existence of the ``!nontemporal`` metadata on the instruction
 tells the optimizer and code generator that this load is not expected to
 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 ``<index>``. See ``invariant.group`` metadata.
+
 Semantics:
 """"""""""
 
 The contents of memory are updated to contain ``<value>`` at the
 location specified by the ``<pointer>`` operand. If ``<value>`` is
 of scalar type then the number of bytes written does not exceed the
 minimum number of bytes needed to hold all bits of the type. For
 example, storing an ``i24`` writes at most three bytes. When writing a
 value of a type like ``i20`` with a size that is not an integral number
 of bytes, it is unspecified what happens to the extra bits that do not
 belong to the type, but they will typically be overwritten.

 object, or -1 if it is variable sized and the third argument is a
 pointer to the object.
 
 Semantics:
 """"""""""
 
 This intrinsic indicates that the memory is mutable again.
 
+'``llvm.invariant.group.barrier``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+      declare i8* @llvm.invariant.group.barrier(i8* <ptr>)
+
+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
 ------------------
 
 This class of intrinsics is designed to be generic and has no specific
 purpose.
 
 '``llvm.var.annotation``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
       declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32  <int>)
 
 Overview:
 """""""""
 
 The '``llvm.var.annotation``' intrinsic.
 
 Arguments:
 """"""""""
 
 The first argument is a pointer to a value, the second is a pointer to a
 global string, the third is a pointer to a global string which is the
 source file name, and the last argument is the line number.
 
 Semantics:
 """"""""""
 
 This intrinsic allows annotation of local variables with arbitrary
 strings. This can be useful for special purpose optimizations that want
 to look for these annotations. These have no other defined use; they are
 ignored by code generation and optimization.
 
 '``llvm.ptr.annotation.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a
 pointer to an integer of any width. *NOTE* you must specify an address space for
 the pointer. The identifier for the default address space is the integer
 '``0``'.
 
 ::