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

[via llvm-commits]

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

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.

>From a6e83f0b4e0064cd73d509986b5c5236c51f342f Mon Sep 17 00:00:00 2001
From: valadaptive <valadaptive at protonmail.com>
Date: Tue, 9 Dec 2025 09:50:13 -0500
Subject: [PATCH] [LangRef] Clarify semantics of undef in shufflevector masks

---
 llvm/docs/LangRef.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

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