[llvm] [LangRef] Clarify semantics of undef in shufflevector masks (PR #171453)

[via llvm-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-llvm-ir

Author: None (valadaptive)

<details>
<summary>Changes</summary>

The current phrasing of `shufflevector` in the language reference states:

> 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.

This is a bit ambiguous. Does it mean that an undef mask element produces a poison result element, or an undef result element?

Per https://reviews.llvm.org/D148637, the answer is the former. I've updated the docs to make this explicit.

As part of the same paragraph, the language reference also currently states:

> If the shuffle mask selects an undef element from one of the input vectors, the resulting element is undef.

When I first skimmed this, I thought it meant that an undef *mask element* resulted in an undef result element. However, it's actually talking about undef *input elements*. That's easy to miss, since the rest of the paragraph discusses mask elements. I've moved that sentence to its own paragraph to make things less confusing.

---
Full diff: https://github.com/llvm/llvm-project/pull/171453.diff


1 Files Affected:

- (modified) llvm/docs/LangRef.rst (+5-4) 


``````````diff
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index b8ed1dba6303e..8673c832d9d60 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -11297,10 +11297,11 @@ 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.
 
-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.
+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. These will be interpreted the same way as ``poison``
+mask elements, also producing a ``poison`` element in the result.
+
 If the shuffle mask selects an ``undef`` element from one of the input
 vectors, the resulting element is ``undef``.
 

``````````

</details>


https://github.com/llvm/llvm-project/pull/171453