[LangRef] Add poison constant

[aqjune]

Summary

This patch adds a description about the newly added poison constant to LangRef.

[nikic]

LGTM

llvm/docs/LangRef.rst

3660

Would personally drop this sentence, seems pretty vague.

3735

%poison2 is already used below.

[aqjune]

update

[aqjune]

llvm/docs/LangRef.rst

3660

(it was saved as a draft, submitting now) A high-level definition of poison was necessary IMO - so I put a topic sentence here. Since technical descriptions are below, I think it is okay to be conceptual here.

llvm/docs/LangRef.rst

 least one undefined bit, the same branch condition is evaluated in the
 input IR as well.
 
 .. _poisonvalues:
 
 Poison Values
 -------------
 
+A poison value is a result of an erroneous operation.
 In order to facilitate speculative execution, many instructions do not
 invoke immediate undefined behavior when provided with illegal operands,
 and return a poison value instead.
-
-There is currently no way of representing a poison value in the IR; they
-only exist when produced by operations such as :ref:`add <i_add>` with
-the ``nsw`` flag.
+The string '``poison``' can be used anywhere a constant is expected, and
+operations such as :ref:`add <i_add>` with the ``nsw`` flag can produce
+a poison value.
 
 Poison value behavior is defined in terms of value *dependence*:
 
 -  Values other than :ref:`phi <i_phi>` nodes and :ref:`select <i_select>`
    instructions depend on their operands.
 -  :ref:`Phi <i_phi>` nodes depend on the operand corresponding to
    their dynamic predecessor basic block.
 -  Select instructions depend on their condition operand and their
-  The operand of a :ref:`ret <i_ret>` instruction if the function or invoking
    call site has a `noundef` attribute in the return value position.
 
 Here are some examples:
 
 .. code-block:: llvm
 
     entry:
       %poison = sub nuw i32 0, 1           ; Results in a poison value.
+      %poison2 = sub i32 poison, 1         ; Also results in a poison value.
       %still_poison = and i32 %poison, 0   ; 0, but also poison.
       %poison_yet_again = getelementptr i32, i32* @h, i32 %still_poison
       store i32 0, i32* %poison_yet_again  ; Undefined behavior due to
                                            ; store to poison.
 
       store i32 %poison, i32* @g           ; Poison value stored to memory.
-      %poison2 = load i32, i32* @g         ; Poison value loaded back from memory.
+      %poison3 = load i32, i32* @g         ; Poison value loaded back from memory.
 
       %narrowaddr = bitcast i32* @g to i16*
       %wideaddr = bitcast i32* @g to i64*
       %poison3 = load i16, i16* %narrowaddr ; Returns a poison value.
       %poison4 = load i64, i64* %wideaddr   ; Returns a poison value.
 
       %cmp = icmp slt i32 %poison, 0       ; Returns a poison value.
       br i1 %cmp, label %end, label %end   ; undefined behavior