[LangRef] make per-element poison behavior explicit

[spatel]

Summary

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.

Side note: the LangRef displayed at http://llvm.org/docs/LangRef.html is out-of-date (doesn't show 'freeze' as of right now).

[nlopes]

The first bit looks ok to me, thanks!

The semantics for shufflevector doesn't. TL;DR: instructions can't detect undef and have some special behavior dedicated to undef.
(I said before this semantics for shufflevector could be ok, but I was wrong, sorry)

Longer version:
undef can be replaced with any number, including in the shufflevector mask. An undef mask may be replaced with an out-of-bounds index, or point to any element in either of the input elements. If one of those input elements is poison, then the result of shufflevector with undef mask may be poison.
Example:
%v = shufflevector <2 x float> %x, <2 x float> undef, <2 x i32> <i32 undef, i32 0>
->
%v = shufflevector <2 x float> %x, <2 x float> undef, <2 x i32> <i32 1, i32 0>
->
%v = <%x[1], %x[0]>

If %x[1] is poison, we get: %v = <poison, %x[0]>

Alternative optimization for the same instruction:
%v = shufflevector <2 x float> %x, <2 x float> undef, <2 x i32> <i32 undef, i32 0>
->
%v = shufflevector <2 x float> %x, <2 x float> undef, <2 x i32> <i32 2, i32 0>
->
%v = <undef, %x[0]>

The point is that if mask is undef, we can't promise to give undef.
AFAICT, the only way to fix this is to say that if the mask is out-of-bounds, we yield poison. That's correct because there's nothing worse than poison.

[spatel]

In D70641#1758212, @nlopes wrote:

The first bit looks ok to me, thanks!

The semantics for shufflevector doesn't. TL;DR: instructions can't detect undef and have some special behavior dedicated to undef.
(I said before this semantics for shufflevector could be ok, but I was wrong, sorry)

Longer version:
undef can be replaced with any number, including in the shufflevector mask. An undef mask may be replaced with an out-of-bounds index, or point to any element in either of the input elements. If one of those input elements is poison, then the result of shufflevector with undef mask may be poison.
Example:
%v = shufflevector <2 x float> %x, <2 x float> undef, <2 x i32> <i32 undef, i32 0>
->
%v = shufflevector <2 x float> %x, <2 x float> undef, <2 x i32> <i32 1, i32 0>
->
%v = <%x[1], %x[0]>

If %x[1] is poison, we get: %v = <poison, %x[0]>

Alternative optimization for the same instruction:
%v = shufflevector <2 x float> %x, <2 x float> undef, <2 x i32> <i32 undef, i32 0>
->
%v = shufflevector <2 x float> %x, <2 x float> undef, <2 x i32> <i32 2, i32 0>
->
%v = <undef, %x[0]>

The point is that if mask is undef, we can't promise to give undef.
AFAICT, the only way to fix this is to say that if the mask is out-of-bounds, we yield poison. That's correct because there's nothing worse than poison.

Can you raise this on llvm-dev (if it wasn't already)? I'll see if I can isolate the transforms that are currently in conflict and the potential optimization fallout.

[nlopes]

LGTM
Reference to the discussion: http://lists.llvm.org/pipermail/llvm-dev/2019-November/137243.html

llvm/docs/LangRef.rst

-  An instruction *control-depends* on a :ref:`terminator
    multiple successors and the instruction is always executed when
    control transfers to one of the successors, and may not be executed
    when control is transferred to another.
 -  Additionally, an instruction also *control-depends* on a terminator
    instruction if the set of instructions it otherwise depends on would
    be different if the terminator had transferred control to a different
    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
 :ref:`undef value <undefvalues>`, which takes an arbitrary bit-pattern.
 Propagation of poison can be stopped with the
 :ref:`freeze instruction <i_freeze>`.
 
 This means that immediate undefined behavior occurs if a poison value is

 constant integer or undef values.
 
 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
 literals for a vector with a length unknown at compile time.
 
 Example:
 """"""""