[docs] Make it clear shifts yield poison when shift amount >= bitwidth

[nlopes]

Summary

This should be NFC: it's just to make it clear in the docs that shift returns a poison value if shift amount >= bitwidth (and not an undef value).
A few instcombine optimizations rely on this already.

[sanjoy]

A few instcombine optimizations rely on this already.

Can you please give one or two examples?

[nlopes]

This one for example (stole from Dave; I don't have my list here handy):
rewrite (1 << Y) * X into X << Y:

%Op0 = shl 1, %Y
%r = mul %Op0, %Op1

=>

%r = shl %Op1, %Y

With shl yielding undef this optimization is incorrect:

ERROR: Mismatch in values for i4 %r

Example:
i4 %Y = 0x8 (8, -8)
i4 %Op0 = 0x0 (0)
i4 %Op1 = 0x0 (0)
source: 0x0 (0)
target: 0x1 (1)

[efriedma]

Looking over LangRef, I think these are the operations which can return undef given operands that aren't undef/poison, and are likely reasonable to change over to return poison:

1. sitofp and friends (if the result is out of range)
2. llvm.ctlz.* and friends (is_zero_undef)
3. shufflevector (undef elements in shuffle mask)
4. shl and friends (shift amount out of range)
5. alloca (allocating zero bytes)
6. insertelement/extractelement (element index out of range)
7. certain operations involving the result of an inrange GEP (see http://llvm.org/docs/LangRef.html#getelementptr-instruction)

If we're committing to killing undef, I think switching all of these to do something other than return undef is fine as an intermediate step... but please send a proposal to llvmdev outlining what's changing (or not really changing, as the case may be), and how it interacts with the general undef/poison/freeze plan.

(The other places I can find that say we return undef are loads and fast-math floating-point operations. Loads are obviously special, and the description of nnan/ninf should probably say it returns an unspecified value rather than undef.)

[sanjoy]

In D33654#767979, @nlopes wrote:

This one for example (stole from Dave; I don't have my list here handy):

Thanks, can you please put this in the commit message? Other than that this LGTM, but I also agree with what Eli said.

rewrite (1 << Y) * X into X << Y:

%Op0 = shl 1, %Y
%r = mul %Op0, %Op1

=>

%r = shl %Op1, %Y

With shl yielding undef this optimization is incorrect:

ERROR: Mismatch in values for i4 %r

Example:
i4 %Y = 0x8 (8, -8)
i4 %Op0 = 0x0 (0)
i4 %Op1 = 0x0 (0)
source: 0x0 (0)
target: 0x1 (1)

llvm/trunk/docs/LangRef.rst

 '``op2``' is treated as an unsigned value.
 
 Semantics:
 """"""""""
 
 The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`,
 where ``n`` is the width of the result. If ``op2`` is (statically or
 dynamically) equal to or larger than the number of bits in
-``op1``, the result is undefined. If the arguments are vectors, each
-vector element of ``op1`` is shifted by the corresponding shift amount
-in ``op2``.
-
-If the ``nuw`` keyword is present, then the shift produces a :ref:`poison
-value <poisonvalues>` if it shifts out any non-zero bits. If the
-``nsw`` keyword is present, then the shift produces a :ref:`poison
-value <poisonvalues>` if it shifts out any bits that disagree with the
-resultant sign bit.
+``op1``, this instruction returns a :ref:`poison value <poisonvalues>`.
+If the arguments are vectors, each vector element of ``op1`` is shifted
+by the corresponding shift amount in ``op2``.
+
+If the ``nuw`` keyword is present, then the shift produces a poison
+value if it shifts out any non-zero bits.
+If the ``nsw`` keyword is present, then the shift produces a poison
+value it shifts out any bits that disagree with the resultant sign bit.
 
 Example:
 """"""""
 
 .. code-block:: text
 
       <result> = shl i32 4, %var   ; yields i32: 4 << %var
       <result> = shl i32 4, 2      ; yields i32: 16

 '``op2``' is treated as an unsigned value.
 
 Semantics:
 """"""""""
 
 This instruction always performs a logical shift right operation. The
 most significant bits of the result will be filled with zero bits after
 the shift. If ``op2`` is (statically or dynamically) equal to or larger
-than the number of bits in ``op1``, the result is undefined. If the
-arguments are vectors, each vector element of ``op1`` is shifted by the
-corresponding shift amount in ``op2``.
+than the number of bits in ``op1``, this instruction returns a :ref:`poison
+value <poisonvalues>`. If the arguments are vectors, each vector element
+of ``op1`` is shifted by the corresponding shift amount in ``op2``.
 
 If the ``exact`` keyword is present, the result value of the ``lshr`` is
-a :ref:`poison value <poisonvalues>` if any of the bits shifted out are
-non-zero.
+a poison value if any of the bits shifted out are non-zero.
 
 Example:
 """"""""
 
 .. code-block:: text
 
       <result> = lshr i32 4, 1   ; yields i32:result = 2
       <result> = lshr i32 4, 2   ; yields i32:result = 1

 '``op2``' is treated as an unsigned value.
 
 Semantics:
 """"""""""
 
 This instruction always performs an arithmetic shift right operation,
 The most significant bits of the result will be filled with the sign bit
 of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger
-than the number of bits in ``op1``, the result is undefined. If the
-arguments are vectors, each vector element of ``op1`` is shifted by the
-corresponding shift amount in ``op2``.
+than the number of bits in ``op1``, this instruction returns a :ref:`poison
+value <poisonvalues>`. If the arguments are vectors, each vector element
+of ``op1`` is shifted by the corresponding shift amount in ``op2``.
 
 If the ``exact`` keyword is present, the result value of the ``ashr`` is
-a :ref:`poison value <poisonvalues>` if any of the bits shifted out are
-non-zero.
+a poison value if any of the bits shifted out are non-zero.
 
 Example:
 """"""""
 
 .. code-block:: text
 
       <result> = ashr i32 4, 1   ; yields i32:result = 2
       <result> = ashr i32 4, 2   ; yields i32:result = 1