diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -9380,6 +9380,10 @@
 is an index indicating the position at which to insert the value. The
 index may be a variable of any integer type.
 
+``poison`` vector is used for ``val`` if the input is a don't-care vector.
+using ``undef`` for ``val`` is not recommended because it prohibits
+optimizations to '``shufflevector``' with ``poison`` masks.
+
 Semantics:
 """"""""""
 
@@ -9396,6 +9400,7 @@
 .. code-block:: text
 
       <result> = insertelement <4 x i32> %vec, i32 1, i32 0    ; yields <4 x i32>
+      <result> = insertelement <4 x i32> poison, i32 1, i32 0  ; creates <4 x i32> from a don't-care vector with the first element set to 1 and returns it
 
 .. _i_shufflevector:
 
@@ -9423,7 +9428,7 @@
 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.
 
@@ -9436,16 +9441,22 @@
 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.
+If the shuffle mask is ``poison``, the result vector is ``poison``. If
+the shuffle mask selects a ``poison`` element from one of the input vectors,
+the resulting element is ``poison``. Similarly, if an ``undef`` element
+is selected, the result is ``undef`` as well. A ``poison`` element
+in the mask vector specifies that the resulting element is ``poison``.
+
+If the shuffle mask is ``undef``, the result vector is ``poison``. An ``undef``
+element in the mask vector specifies that the resulting element is ``poison``.
+Therefore, the result of ``shufflevector`` does not change even if the
+``poison`` mask is used instead of ``undef``, and vice versa.
+LLVM's assembly printer will print ``poison`` if ``undef`` was given to the
+shuffle mask because LLVM does not distinguish between them internally.
 
 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.
+``zeroinitializer``, ``undef`` and ``poison``, since we cannot write all
+indices as literals for a vector with a length unknown at compile time.
 
 Example:
 """"""""
@@ -9454,9 +9465,9 @@
 
       <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>