[llvm] ead0d77 - [LangRef] make per-element poison behavior explicit

[Sanjay Patel via llvm-commits]

Author: Sanjay Patel
Date: 2019-12-04T15:32:19-05:00
New Revision: ead0d77409b888ad5b8df90ee3b8ab7639b241c7

URL: https://github.com/llvm/llvm-project/commit/ead0d77409b888ad5b8df90ee3b8ab7639b241c7
DIFF: https://github.com/llvm/llvm-project/commit/ead0d77409b888ad5b8df90ee3b8ab7639b241c7.diff

LOG: [LangRef] make per-element poison behavior explicit

As discussed in D70246 and PR43958:
https://bugs.llvm.org/show_bug.cgi?id=43958

The LangRef seems ambiguous about the behavior of poison with respect
to vectors.

We could go further with text and/or examples - suggestions welcome.

Also, see discussion on llvm-dev;
http://lists.llvm.org/pipermail/llvm-dev/2019-November/137243.html

Differential Revision: https://reviews.llvm.org/D70641

Added: 
    

Modified: 
    llvm/docs/LangRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 52f8e392ce86..aa37e00b5056 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3334,6 +3334,9 @@ Poison value behavior is defined in terms of value *dependence*:
    be 
diff erent if the terminator had transferred control to a 
diff erent
    successor.
 -  Dependence is transitive.
+-  Vector elements may be independently poisoned. Therefore, transforms
+   on instructions such as shufflevector must be careful to propagate
+   poison across values or elements only as allowed by the original code.
 
 An instruction that *depends* on a poison value, produces a poison value
 itself. A poison value may be relaxed into an
@@ -8448,10 +8451,13 @@ Semantics:
 The elements of the two input vectors are numbered from left to right
 across both of the vectors. The shuffle mask operand specifies, for each
 element of the result vector, which element of the two input vectors the
-result element gets. If the shuffle mask is undef, the result vector is
-undef. If any element of the mask operand is undef, that element of the
-result is undef. If the shuffle mask selects an undef element from one
-of the input vectors, the resulting element is undef.
+result element gets.
+
+If the shuffle mask is undef, the result vector is undef. If any element
+of the mask operand is undef, that element of the result is undef. If the
+shuffle mask selects an undef element from one of the input vectors, the
+resulting element is undef. An undef mask element prevents a poisoned
+vector element from propagating.
 
 For scalable vectors, the only valid mask values at present are
 ``zeroinitializer`` and ``undef``, since we cannot write all indices as