Clarify wording in the LangRef around !invariant.load

Clarify the wording around !invariant.load to properly reflect the semantics of such loads with respect to control dependence and location lifetime.  To the best of my knowledge, the revised wording respects the actual implementation and understanding of issues involved highlighted in the recent 'Optimization hints for "constant" loads' thread on LLVMDev.

In particular, I'm aiming for the following results:
- To clarify that an invariant.load can fault and must respect control dependence.  In particular, it is not sound to unconditionally pull an invariant load out of a loop if that loop would potentially never execute.
- To clarify that the invariant nature of a given pointer does not preclude the modification of that location through a pointer which is unrelated to the load operand.  In particular, initializing a location and then passing a pointer through an opaque intrinsic which produces a new unrelated pointer, should behave as expected provided that the intrinsic is memory dependent on the initializing store.
- To clarify that storing a value to an invariant location is defined.  It can not, for example, be considered unreachable.  The value stored can be assumed to be equal to the value of any previous (or following!) invariant load, but the store itself is defined.

I recommend that anyone interested in using !invariant.load, or optimizing for them, read over the discussion in the review thread.  A number of motivating examples are discussed.

Differential Revision: http://reviews.llvm.org/D6346

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@222700 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/docs/LangRef.rst b/docs/LangRef.rst
index 56221c5154a4270df603811d214d32374a2cc88d..b48769e1ee492d91f68f86b94605395e0644b0c6 100644 (file)
--- a/docs/LangRef.rst
+++ b/docs/LangRef.rst
@@ -5211,10 +5211,11 @@ as the ``MOVNT`` instruction on x86.
 The optional ``!invariant.load`` metadata must reference a single
 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 this load
-address points to memory which does not change value during program
-execution. The optimizer may then move this load around, for example, by
-hoisting it out of loops using loop invariant code motion.
+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 ``!nonnull`` metadata must reference a single
 metadata name ``<index>`` corresponding to a metadata node with no