[llvm] r222700 - Clarify wording in the LangRef around !invariant.load

[Philip Reames]

Author: reames
Date: Mon Nov 24 16:32:43 2014
New Revision: 222700

URL: http://llvm.org/viewvc/llvm-project?rev=222700&view=rev
Log:
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


Modified:
    llvm/trunk/docs/LangRef.rst

Modified: llvm/trunk/docs/LangRef.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/LangRef.rst?rev=222700&r1=222699&r2=222700&view=diff
==============================================================================
--- llvm/trunk/docs/LangRef.rst (original)
+++ llvm/trunk/docs/LangRef.rst Mon Nov 24 16:32:43 2014
@@ -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