[docs] cttz and ctlz return poison, not undef, when argument is 0

[lebedev.ri]

docs/LangRef.rst

12251–12252

Should defined also be reworded, since it is no longer 'un'defined, but poison?

[regehr]

docs/LangRef.rst

12251–12252

my view is the "undefined" is a broad term that encompasses undef and poison, so this probably doesn't require rewording

however, is_zero_undef is specifically referring to undef, and should be changed to is_zero_poison (or, perhaps, is_zero_undefined)

[nlopes]

As a justification why it doesn't matter whether it's undef or poison, clang emits__builtin_ffs as:
ffs(x) -> x ? cttz(x) + 1 : 0

https://clang.llvm.org/doxygen/CGBuiltin_8cpp_source.html#l01814

So I support this change to poison, since it makes things easier than undef.

[nikic]

Based on the current documentation of poison values, selecting over poison is still poison by the first rule. I'm assuming that this is an inaccuracy in the documentation and selects are treated the same ways as phis? Otherwise the cited clang code would be affected.

[nlopes]

In D56155#1342651, @nikic wrote:

Based on the current documentation of poison values, selecting over poison is still poison by the first rule. I'm assuming that this is an inaccuracy in the documentation and selects are treated the same ways as phis? Otherwise the cited clang code would be affected.

That's a good point. I agree the current documentation of poison is outdated; it misses a rule for select. "select a, b, c" is only poison if a=1 and b is poison or a=0 and c is poison.

[spatel]

Reverse ping.

Note that the poison text for selects was updated after:
rGfaba1d034a
rGd8061456b
( https://bugs.llvm.org/show_bug.cgi?id=20895 )

docs/LangRef.rst

 """"""""""
 
 The first argument is the value to be counted. This argument may be of
 any integer type, or a vector with integer element type. The return
 type must match the first argument type.
 
 The second argument must be a constant and is a flag to indicate whether
 the intrinsic should ensure that a zero as the first argument produces a
 defined result. Historically some architectures did not provide a
 defined result for zero values as efficiently, and many algorithms are
 now predicated on avoiding zero-value inputs.
 
 Semantics:
 """"""""""
 
 The '``llvm.ctlz``' intrinsic counts the leading (most significant)
 zeros in a variable, or within each element of the vector. If
 ``src == 0`` then the result is the size in bits of the type of ``src``
-if ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
-``llvm.ctlz(i32 2) = 30``.
+if ``is_zero_undef == 0`` and :ref:`poison value <poisonvalues>` otherwise.
+For example, ``llvm.ctlz(i32 2) = 30``.
 
 '``llvm.cttz.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 This is an overloaded intrinsic. You can use ``llvm.cttz`` on any

 now predicated on avoiding zero-value inputs.
 
 Semantics:
 """"""""""
 
 The '``llvm.cttz``' intrinsic counts the trailing (least significant)
 zeros in a variable, or within each element of a vector. If ``src == 0``
 then the result is the size in bits of the type of ``src`` if
-``is_zero_undef == 0`` and ``undef`` otherwise. For example,
-``llvm.cttz(2) = 1``.
+``is_zero_undef == 0`` and :ref:`poison value <poisonvalues>` otherwise.
+For example, ``llvm.cttz(2) = 1``.
 
 .. _int_overflow:
 
 '``llvm.fshl.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""