invariant.group and invariant.group.barrier docs

[nlewycky]

docs/LangRef.rst

5751

Typo "referenece"

5755

Typo "loados"

5756

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

5863

Typo "referenece"

5867

Typo "loados"

5868

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

10170–10171

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.

10183–10184

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

5753

existance -> existence

5755

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

5756

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.

5815–5816

invariant.group.barrier -> invariant.group

5863–5868

Same comments as above.

5865

existance -> existence

5867

that have -> that has
loados -> loads

10178

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?

10183–10184

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."

10186–10190

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

[reames]

docs/LangRef.rst

5754

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.

5755

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..."

5762

Stray change, please submit separately.

5863

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

3765

"atached" --> "attached"

3768

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

3768

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?

3876–3877

This should either be removed or committed independently.

10157

Either revert this newline or commit it independently if correct.

10178

"it's" --> "its"

[Prazek]

docs/LangRef.rst

3768

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

3768

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

3782–3783

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.

3792

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

3765

instruction -> instructions

3768

Remove the comma here.

docs/LangRef.rst

 ^^^^^^^^^^^^^^^^^^
 
 The ``llvm.bitsets`` global metadata is used to implement
 :doc:`bitsets <BitSets>`.
 
 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
 look it up.
 
 The ``llvm.module.flags`` metadata contains a list of metadata triplets.
 Each triplet has the following form:
 
 -  The first element is a *behavior* flag, which specifies the behavior
    when two (or more) modules are merged together, and it encounters two
    (or more) metadata with the same ID. The supported behaviors are
    described below.
 -  The second element is a metadata string that is a unique ID for the
    metadata. Each module may only have one flag entry for each unique ID (not
    including entries with the **Require** behavior).
 -  The third element is the value of the flag.
 
 When two (or more) modules are merged together, the resulting
 ``llvm.module.flags`` metadata is the union of the modules' flags. That is, for
 each unique metadata ID string, there will be exactly one entry in the merged
 modules ``llvm.module.flags`` metadata table, and the value for that entry will
 be determined by the merge behavior flag, as described below. The only exception
 is that entries with the *Require* behavior are always preserved.
 
 The following behaviors are supported:
 
 .. list-table::
    :header-rows: 1
    :widths: 10 90
 
    * - Value
      - Behavior
 
    * - 1
-  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 referenece a 
+single metadata name ``<index>`` corresponding to a metadata node with
+no entries. The existance of the ``!invariant.group`` metadata on the 
+instruction tells the optimizer that every load and store to the same pointer
+value, that have the same ``<index>`` loados or stores the same value 
+(unless optimizer see @llvm.invariant.barrier() called between loads).
+
 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
+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.barrier !<index>]        ; yields void
+      store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> [, !invariant.group.barrier !<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 referenece a 
+single metadata name ``<index>`` corresponding to a metadata node with
+no entries. The existance of the ``!invariant.group`` metadata on the 
+instruction tells the optimizer that every load and store to the same pointer
+value, that have the same ``<index>`` loados or stores the same value 
+(unless optimizer see @llvm.invariant.barrier() called between loads).
+
 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

 This intrinsic indicates that the memory is mutable again.
 
 General Intrinsics
 ------------------
 
 This class of intrinsics is designed to be generic and has no specific
 purpose.
 
+'``llvm.invariant.group.barrier``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+      declare i8* @llvm.invariant.group.barrier(i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.invariant.group.barrier``' intrinsic specifies that given a pointer, 
+produces another pointer that aliases the first but which is considered different 
+for the purposes of load/store !invariant.group metadata.
+
+Arguments:
+""""""""""
+
+The ``llvm.invariant.group.barrier`` takes only one argument, which is
+the pointer to memory that might changed.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that value of next load/store with !invariant.group 
+may have been changed.
+
+General Intrinsics
+------------------
+
+This class of intrinsics is designed to be generic and has no specific
+purpose.
+
 '``llvm.var.annotation``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::