[LangRef] Update shufflevector's semantics to return poison if the mask is undef

[ManuelJBrito]

Summary

This patch changes the shufflevector's semantics to yield poison if the mask is undefined. This allows the extraction of shufflevectors while also opening the door for more optimization opportunities due to the fact that poison is more undefined than undef.

This is a continuation of the work done by @aqjune in D93818.

As described at https://github.com/llvm/llvm-project/issues/43530, here is a quick overview:

Undef in the shufflevector mask yielding undef even when the shuffled value is poison makes the following transformation invalid:

define <4 x float> @insert_not_undef_shuffle_translate_commute(float %x, <4 x float> %y, <4 x float> %q) {
  %xv = insertelement <4 x float> %q, float %x, i32 2
  %r = shufflevector <4 x float> %y, <4 x float> %xv, <4 x i32> { 0, 6, 2, undef }
  ret <4 x float> %r
}
=>
define <4 x float> @insert_not_undef_shuffle_translate_commute(float %x, <4 x float> %y, <4 x float> %q) {
  %r = insertelement <4 x float> %y, float %x, i32 1
  ret <4 x float> %r
}

float %x = poison
<4 x float> %y = < poison, poison, poison, poison >
<4 x float> %q = < poison, poison, poison, poison >

Source:
<4 x float> %xv = < poison, poison, poison, poison >
<4 x float> %r = < poison, poison, poison, undef >

Target:
<4 x float> %r = < poison, poison, poison, poison >

Source value: < poison, poison, poison, undef >
Target value: < poison, poison, poison, poison >

The motivation for the current semantics was to be able to introduce shufflevectors when building a vector with a sequence of insertelements starting from an undef vector:

%t = insertelement <4 x float> undef, float %arg, i32 1
%t4 = insertelement <4 x float> %t, float %arg, i32 1
%t5 = insertelement <4 x float> %t4, float %arg, i32 2
%t6 = insertelement <4 x float> %t5, float %arg, i32 3
ret <4 x float> %t6
=>
%t = insertelement <4 x float> undef, float %arg, i32 0
%t2 = shufflevector <4 x float> %t, <4 x float> undef, <4 x i32> <i32 undef, i32 0, i32 0, i32 0>
ret <4 x float> %t2

With the soft deprecation of undef these cases should become more rare. So these new semantics in combination with disabling these transformations when an undef placeholder is used should prevent miscompilations without meaningful regressions.

Theses cases are identified at https://web.ist.utl.pt/nuno.lopes/alive2/index.php?hash=a9bc405e427c007f with 'LLVM PR44185'.

[nlopes]

Looks great, thanks!

Please wait for at least another reviewer.

[aqjune]

llvm/docs/LangRef.rst

10102

Hi, it seems the LLVM assembly printer hasn't been updated yet: https://godbolt.org/z/ndEdos9Mx
Should we make this change after the assembly printer is updated in the future?

[ManuelJBrito]

llvm/docs/LangRef.rst

10102

Yes, I was just finishing updating the tests. Here is the patch D149210.
Thanks

[nikic]

I'm fine with the semantics change, but I think there are too many words here.

llvm/docs/LangRef.rst

10036

I don't think this sentence really adds anything. It just introduces a new ill-defined term "don't-care vector".

10036

(The recommendation to use poison instead of undef is a general one, that applies not only to insertelement.)

10091–10101

I feel like we could use a lot less words here and be less confusing at the same time.

[ManuelJBrito]

llvm/docs/LangRef.rst

10091–10101

I agree your wording is easier to follow, but shouldn't we still mention that selection of an undef value produces undef just to make it clear?

[ManuelJBrito]

Address comments:

• simplify wordings
• remove undef to poison recommendation

[nikic]

LGTM

llvm/docs/LangRef.rst

 The first operand of an '``insertelement``' instruction is a value of
 :ref:`vector <t_vector>` type. The second operand is a scalar value whose
 type must equal the element type of the first operand. The third operand
 is an index indicating the position at which to insert the value. The
 index may be a variable of any integer type, and will be treated as an
 unsigned integer.
 
 Semantics:
 """"""""""
 
 The result is a vector of the same type as ``val``. Its element values
 are those of ``val`` except at position ``idx``, where it gets the value
 ``elt``. If ``idx`` exceeds the length of ``val`` for a fixed-length vector,
 the result is a :ref:`poison value <poisonvalues>`. For a scalable vector,
 if the value of ``idx`` exceeds the runtime length of the vector, the result
 is a :ref:`poison value <poisonvalues>`.
 

 the input and length that is the same as the shuffle mask.
 
 Arguments:
 """"""""""
 
 The first two operands of a '``shufflevector``' instruction are vectors
 with the same type. The third argument is a shuffle mask vector constant
 whose element type is ``i32``. The mask vector elements must be constant
-integers or ``undef`` values. The result of the instruction is a vector
+integers or ``poison`` values. The result of the instruction is a vector
 whose length is the same as the shuffle mask and whose element type is the
 same as the element type of the first two operands.
 
 Semantics:
 """"""""""
 
 The elements of the two input vectors are numbered from left to right
 across both of the vectors. For each element of the result vector, the
 shuffle mask selects an element from one of the input vectors to copy
 to the result. Non-negative elements in the mask represent an index
 into the concatenated pair of input vectors.
 
-If the shuffle mask is undefined, the result vector is undefined. If
-the shuffle mask selects an undefined element from one of the input
-vectors, the resulting element is undefined. An undefined element
-in the mask vector specifies that the resulting element is undefined.
-An undefined element in the mask vector prevents a poisoned vector
-element from propagating.
+A ``poison`` element in the mask vector specifies that the resulting element
+is ``poison``.
+For backwards-compatibility reasons, LLVM temporarily also accepts ``undef``
+mask elements, which will be interpreted the same way as ``poison`` elements.
+If the shuffle mask selects an ``undef`` element from one of the input
+vectors, the resulting element is ``undef``.
 
 For scalable vectors, the only valid mask values at present are
-``zeroinitializer`` and ``undef``, since we cannot write all indices as
+``zeroinitializer``, ``undef`` and ``poison``, since we cannot write all indices as
 literals for a vector with a length unknown at compile time.
 
 Example:
 """"""""
 
 .. code-block:: text
 
       <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
                               <4 x i32> <i32 0, i32 4, i32 1, i32 5>  ; yields <4 x i32>
-      <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
+      <result> = shufflevector <4 x i32> %v1, <4 x i32> poison,
                               <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32> - Identity shuffle.
-      <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
+      <result> = shufflevector <8 x i32> %v1, <8 x i32> poison,
                               <4 x i32> <i32 0, i32 1, i32 2, i32 3>  ; yields <4 x i32>
       <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
                               <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 >  ; yields <8 x i32>
 
 Aggregate Operations
 --------------------
 
 LLVM supports several instructions for working with